---
title: "Execute SPL2 query"
method: POST
path: "/query"
tags: ["Query"]
---

# Execute SPL2 query

`POST /query`

Core search endpoint. Executes any SPL2 pipeline including search, aggregation, and management commands.

**Execution modes** (controlled by `wait` parameter):

| `wait` value | Behavior | Response |
|---|---|---|
| `null` (default) | **Sync.** Block up to `query.sync_timeout` (30s). | `200` with results, or `202` + job if it exceeds the timeout |
| `0` | **Async.** Return immediately. | `202` with job handle |
| `N` (seconds) | **Hybrid.** Wait up to N seconds. | `200` if done in time, `202` + job otherwise |

Hybrid mode (`wait: 5`) is ideal for Web UI — fast queries return instantly, slow ones degrade to async with progress tracking.

**Response `data.type` determines rendering:**
- `events` → log viewer (raw events)
- `aggregate` → table (stats results)
- `timechart` → chart (time-series)
- `view_created` → MV creation confirmation (when query contains `| materialize`)
- `job` → async job handle (when `wait` is set and query didn't complete in time)

**MV acceleration:** when the query planner detects a Materialized View that covers the query,
`meta.accelerated_by` is present in the response.

**SPL2 management commands** also flow through this endpoint:
- `| materialize "name"` — create MV
- `| from mv_name` — read from MV
- `| views` — list MVs
- `| dropview "name"` — delete MV

## Request body

- QueryRequest
  - `q` string — SPL2 query string
  - `query` string — Alias for `q`
  - `earliest` string — Legacy alias for `from`
  - `latest` string — Legacy alias for `to`
  - `from` string — Start time: relative (`-1h`, `-7d`) or ISO 8601. Default: `-15m`
  - `to` string — End time: relative (`now`, `-5m`) or ISO 8601. Default: `now`
  - `limit` integer — Max events to return
  - `offset` integer — Offset for pagination (tabular results only)
  - `format` 'json' — Optional response format selector. Only `json` is accepted on `/query`.
  - `wait` number, nullable — Controls sync/async behavior: - `null` (default) — **Sync.** Block until query completes. Returns `200` with results. - `0` — **Async.** Return `202` immediately with a job handle. Client polls or subscribes to SSE for progress. - `N` (seconds) — **Hybrid.** Wait up to N seconds. If query completes in time → `200` with results. If not → `202` with job handle and current progress. Best for UI: short queries feel instant, long queries degrade gracefully.
  - `profile` 'basic' | 'full' | 'trace' — Include richer execution statistics in the response `meta.stats`.
  - `variables` object — Template variables substituted into the query before planning.

## Response `200`

Query completed synchronously. Returned when:
- `wait` is `null` (default sync mode) and query completes in-request
- `wait` is `N > 0` (hybrid mode) and query completes within N seconds

- union
  - QueryEventsResponse
    - `data` object, required
      - `type` 'events', required
      - `events` LogEvent[], required
      - `total` integer, required
      - `has_more` boolean
      - `partial` boolean — Present and `true` when served from a backfilling MV
    - `meta` object
      - `took_ms` number
      - `scanned` integer
      - `query_id` string
      - `accelerated_by` AcceleratedBy
        - `view` string — Name of the MV used
        - `original_scan` integer — Events that would have been scanned without MV
        - `speedup` string
        - `status` 'active' | 'backfilling'
        - `coverage_percent` number — Only present when MV is backfilling
  - QueryAggregateResponse
    - `data` object, required
      - `type` 'aggregate', required
      - `columns` string[], required
      - `rows` array[], required
        - unknown[]
          - unknown
      - `total_rows` integer
      - `partial` boolean
    - `meta` object
      - `took_ms` number
      - `scanned` integer
      - `query_id` string
      - `accelerated_by` AcceleratedBy
        - `view` string — Name of the MV used
        - `original_scan` integer — Events that would have been scanned without MV
        - `speedup` string
        - `status` 'active' | 'backfilling'
        - `coverage_percent` number — Only present when MV is backfilling
  - QueryTimechartResponse
    - `data` object, required
      - `type` 'timechart', required
      - `interval` string, required
      - `columns` string[], required
      - `rows` array[], required
        - unknown[]
          - unknown
    - `meta` Meta
      - `took_ms` number
      - `scanned` integer
      - `query_id` string
  - QueryViewCreatedResponse
    - `data` object, required
      - `type` 'view_created', required
      - `view` ViewSummary, required
        - `name` string, required
        - `kind` 'projection' | 'aggregation', required
        - `query` string, required
        - `retention` string
        - `status` 'active' | 'backfilling' | 'rebuilding' | 'paused' | 'error', required
        - `version` integer
        - `rows` integer
        - `segments` integer
        - `storage_bytes` integer
        - `lag_ms` integer, nullable
        - `backfill` BackfillProgress
          - `total` integer
          - `processed` integer
          - `percent` number
          - `eta_seconds` integer
        - `previous_version` object
          - `version` integer
          - `status` string
        - `created_at` string, date-time
        - `last_event` string, date-time, nullable
    - `meta` Meta
      - `took_ms` number
      - `scanned` integer
      - `query_id` string

## Other responses

- `202` — Query accepted for async execution. Returned when: - `wait: 0` (async mode) — always returns 202 immediately - `wait: N` (hybrid mode) — query didn't complete within N seconds Response contains a job handle with current progress. Use `GET /query/jobs/{id}` to poll or `GET /query/jobs/{id}/stream` for real-time SSE updates.
- `400` — Invalid SPL2 query
- `429` — Too many requests

---

[API](https://skmtc.net/lynxbase/apis/lynxdb-api.md) · [All operations](https://skmtc.net/lynxbase/apis/lynxdb-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lynxbase/lynxdb-api/versions/4363a070c444/schema)