Skip to main content

Query Settings

The query section controls how the query engine allocates resources, enforces limits, and manages async jobs.

Concurrency​

Max Concurrent Queries​

The maximum number of queries that can execute simultaneously.

Config Keyquery.max_concurrent
Env VarLYNXDB_QUERY_MAX_CONCURRENT
Default10
Hot-ReloadableYes
query:
  max_concurrent: 10

When the limit is reached, new queries are queued. Increase this on machines with more CPU cores and memory. A good starting point is 2x the number of CPU cores.

# Change at runtime
lynxdb config set query.max_concurrent 20
lynxdb config reload

Timeouts​

Sync Timeout​

Maximum wait time for synchronous query execution. If the query does not complete within this time, the server returns a job ID for async polling.

Config Keyquery.sync_timeout
Env VarLYNXDB_QUERY_SYNC_TIMEOUT
Default30s
query:
  sync_timeout: "30s"

This is the server-side timeout for POST /api/v1/query. The CLI also supports a client-side --timeout flag.

Max Query Runtime​

Hard limit on how long any single query can run, regardless of execution mode.

Config Keyquery.max_query_runtime
Env VarLYNXDB_QUERY_MAX_QUERY_RUNTIME
Default5m
Hot-ReloadableYes
query:
  max_query_runtime: "10m"

Queries that exceed this limit are cancelled with an error. Increase for workloads that involve scanning large time ranges or complex aggregations.

Result Limits​

Default Result Limit​

The default number of result rows returned when the query does not include a HEAD or LIMIT command.

Config Keyquery.default_result_limit
Env VarLYNXDB_QUERY_DEFAULT_RESULT_LIMIT
Default1000
Hot-ReloadableYes
query:
  default_result_limit: 1000

Max Result Limit​

The hard cap on result rows, even if the query explicitly requests more.

Config Keyquery.max_result_limit
Env VarLYNXDB_QUERY_MAX_RESULT_LIMIT
Default50000
Hot-ReloadableYes
query:
  max_result_limit: 50000

For exporting large datasets, use the streaming endpoint (POST /api/v1/query/stream) which is not subject to this limit.

Memory Limits​

Server-Side Memory Pool​

The global memory pool shared across all concurrent queries.

CLI Flag--max-query-pool
Default(unlimited)
lynxdb server --max-query-pool 4gb

When the pool is exhausted, queries spill intermediate results to disk.

Spill Directory​

Directory for temporary spill files when query memory is exceeded.

CLI Flag--spill-dir
DefaultOS temp directory
lynxdb server --max-query-pool 2gb --spill-dir /data/lynxdb/tmp

Client-Side Memory Limit​

For pipe/file mode queries, limit the ephemeral engine's memory usage.

# Limit ephemeral engine to 512MB
lynxdb query --file huge.log '| stats count by host' --max-memory 512mb

Async Job Management​

Job TTL​

How long completed async job results are kept before garbage collection.

Config Keyquery.job_ttl
Env VarLYNXDB_QUERY_JOB_TTL
Default10m
query:
  job_ttl: "10m"

Job GC Interval​

How often the server cleans up expired async jobs.

Config Keyquery.job_gc_interval
Env VarLYNXDB_QUERY_JOB_GC_INTERVAL
Default1m
query:
  job_gc_interval: "1m"

Complete Example​

query:
  sync_timeout: "30s"
  max_query_runtime: "10m"
  max_concurrent: 20
  default_result_limit: 1000
  max_result_limit: 50000
  job_ttl: "10m"
  job_gc_interval: "1m"

Tuning Guidelines​

WorkloadRecommendation
High query concurrency (dashboards)Increase max_concurrent to 30-50, ensure enough CPU cores
Large time-range scansIncrease max_query_runtime to 30m, set --max-query-pool
API integrations with strict latencyDecrease sync_timeout to 10s, use async mode for slow queries
Exporting large datasetsUse /api/v1/query/stream, not the result limit settings
CI/CD pipelinesUse --timeout on the client side, --fail-on-empty for assertions

Next Steps​