Search settings
Search admission (concurrency and queueing), per-priority ClickHouse resource budgets and query safety limits.
Use Settings → Search (/settings/search) to control search concurrency, queue waits, and query safety limits. Detection rules bypass these admission limits.
The page has three sections, saved with two buttons:
| Section | What it controls | API |
|---|---|---|
| Concurrency limits | Ad-hoc search slots and the wait queue | GET/PUT /api/settings/search |
| Resource budgets | Per-priority execution time and memory caps (fixed defaults; see below) | GET/PUT /api/settings/search |
| Query safety | Array, expansion, post-processing and cache caps, and cost-error blocking | GET/PUT /api/settings/search/query-limits |
Reading and changing these settings requires the settings:system permission.
How admission works
Every search is given a priority:
| Priority | Used for | Admission |
|---|---|---|
| Detection | Scheduled detection rules | Bypasses the queue, always runs |
| Near-realtime | Near-realtime rules | Bypasses the queue, always runs |
| Interactive | Analyst searches on the Search page | Counts against the limits below |
| Analytics | Long-running hunts | Counts against the limits below |
For Interactive and Analytics searches:
- If a slot is free under the global ad-hoc limit and you are under your per-user limit, the search starts.
- Otherwise it waits in a priority queue (by priority, then arrival time). While it waits, the Search page shows its queue position and a cancel button.
- A search fails with Search queue is full when the queue is at max queue depth, or when you already hold your per-user limit and your share of the queue is full.
- A search that waits longer than the queue timeout fails with Search queue timeout.
Concurrency limits
| Setting | Field | Default | Range |
|---|---|---|---|
| Global ad-hoc limit | global_adhoc_limit | 30 | 1–500 |
| Per-user limit | per_user_limit | 10 | 1–50, and not more than the global limit |
| Max queue depth | max_queue_depth | 100 | 10–1,000 |
| Queue timeout | queue_timeout_seconds | 300 s | 10–600 s |
One run of the Search page uses several queries at once (results, histogram and field statistics), so keep the per-user limit well above 1.
The search service rereads these settings every 60 seconds; no restart is needed. If it can't read them from Postgres at startup, it falls back to the environment variables SEARCH_GLOBAL_ADHOC_LIMIT, SEARCH_PER_USER_LIMIT, SEARCH_MAX_QUEUE_DEPTH and SEARCH_QUEUE_TIMEOUT_MS (milliseconds).
Resource budgets
Per-priority caps on execution time and memory for each query.
| Priority row | Max execution time (default, range) | Max memory (default, range) |
|---|---|---|
| Realtime (detections, near-realtime) | 30 s, 5–120 | 5 GB, 1–20 |
| Interactive | 300 s, 30–3,600 | 20 GB, 1–100 |
| Analytics | 3,600 s, 60–7,200 | 50 GB, 5–200 |
Query safety
| Setting | Field | Default | Range | What it does |
|---|---|---|---|---|
| Max array aggregation size | max_group_array_size | 100 | 100–1,000,000 | Maximum elements per group for values() and list(). Larger arrays are truncated without an error. |
| Max mvexpand rows | max_mvexpand_rows | 100,000 | 1,000–10,000,000 | Row cap for mvexpand when the query doesn't give limit=N. |
| Max post-processing groups | max_post_processing_groups | 1,000,000 | 10,000–10,000,000 | Maximum groups when stats, top or rare run after a Nano-side stage such as lookup or prevalence. Extra groups are dropped. |
| Max streaming cache rows | max_streaming_cache_rows | 50,000 | 1,000–1,000,000 | Rows kept for instant re-display of a streamed result. Larger results still stream but aren't cached. |
| Block queries with cost-analysis errors | block_on_cost_errors | Off | On / off | Rejects a query before it runs if cost analysis finds an Error-severity problem. |
The search service reloads query safety limits from PostgreSQL every 60 seconds.
An explicit limit on the command always wins over max_mvexpand_rows:
class_uid=4003 | mvexpand answers.rdata limit=500Cost-analysis errors
With Block queries with cost-analysis errors off, these appear as warnings in the search results and the query still runs. With it on, the query is refused with the reason and a suggested fix.
| Code | Trigger |
|---|---|
UNBOUNDED_DEDUP | dedup without an earlier head or aggregation |
UNBOUNDED_TRANSACTION | transaction without both maxspan and maxevents |
UNBOUNDED_EVENTSTATS | eventstats without an earlier limit or aggregation |
UNBOUNDED_STREAMSTATS | streamstats without an earlier limit or aggregation |
Info- and Warning-severity findings (for example UNBOUNDED_SORT or TINY_TIMECHART_SPAN) are always advisory.
API
# Read admission settings
curl -H "X-API-Key: $NANO_API_KEY" https://<host>/api/settings/search
# Change query safety limits
curl -X PUT -H "X-API-Key: $NANO_API_KEY" -H "Content-Type: application/json" \
-d '{"max_group_array_size": 10000, "max_mvexpand_rows": 250000,
"max_post_processing_groups": 1000000, "max_streaming_cache_rows": 50000,
"block_on_cost_errors": true}' \
https://<host>/api/settings/search/query-limitsTroubleshoot
Need help with these checks? Contact support with the request ID and time with timezone.
Search waits or fails in the queue
Check the global ad-hoc limit, per-user limit, queue depth, and timeout. A Search page run uses several queries, so a per-user limit of 1 can prevent a complete run.
Changing a resource budget has no effect
The search service does not read the resource-budget rows; it applies fixed per-priority caps. To give queries more memory, raise ClickHouse's memory and its user profile's max_memory_usage.