Skip to main content

Query Settings

The query section controls how the server runs queries. Every query runs as a job; these settings bound how many run at once, how long a request waits for one, how many rows a response carries and how long a finished job stays.

KeyEnv varDefaultDescription
query.max_concurrentLYNXDB_QUERY_MAX_CONCURRENT32Queries running at once. A query beyond it is refused with 429 TOO_MANY_REQUESTS and Retry-After: 1. Minimum 1. Needs a restart.
query.sync_timeoutLYNXDB_QUERY_SYNC_TIMEOUT30sHow long POST /api/v1/query without wait waits for the result. A query still running then is answered with its job handle (202, {"data":{"type":"job","job_id":"qry_...","status":"running",...}}) and keeps running. Minimum 1s. Reloadable.
query.job_ttlLYNXDB_QUERY_JOB_TTL5mHow long a finished job and its rows stay available under /api/v1/query/jobs/{id}. Finished jobs are swept once a minute. Minimum 1s. Needs a restart.
query.default_result_limitLYNXDB_QUERY_DEFAULT_RESULT_LIMIT1000Rows per response when the request sets no limit. Minimum 1. Reloadable.
query.max_result_limitLYNXDB_QUERY_MAX_RESULT_LIMIT50000Largest limit a request can ask for; a larger one is lowered to it. At least default_result_limit. Reloadable.
query.max_query_lengthnone1048576Longest accepted query text in bytes; a longer one gets 400 QUERY_TOO_LARGE. 0 disables the check. Reloadable.

A job keeps running when its request returns, until it finishes, DELETE /api/v1/query/jobs/{id} cancels it, or the server shuts down. The result limits shape the response only: a query computes all its rows, and the response pages through them with limit and offset and reports has_more. To export many rows at once, use POST /api/v1/query/stream, which writes NDJSON rows without a limit.

lynxdb query --file and piped input run the query in the CLI process, not on the server, so these settings do not apply to them.

Complete Example​

query:
max_concurrent: 32
sync_timeout: "30s"
job_ttl: "15m"
default_result_limit: 1000
max_result_limit: 50000
max_query_length: 1048576

Tuning Guidelines​

WorkloadChange
Many concurrent users or dashboardsRaise max_concurrent; queries beyond it are refused, not queued.
API clients that need fast answersLower sync_timeout and poll the returned job, or send "wait": 0 to get a job at once.
Clients that come back for results laterRaise job_ttl.
Bulk export of raw eventsUse POST /api/v1/query/stream instead of raising max_result_limit.

For writing faster queries, see PPL performance.