---
title: "Execute an RQL query"
method: POST
path: "/v1/query"
tags: ["query"]
---

# Execute an RQL query

`POST /v1/query`

Execute SQL-like queries against documents using ReasonDB Query Language (RQL).

Supports:
- `WHERE` clauses for filtering by tags, author, metadata
- `SEARCH` clause for BM25 full-text search (fast keyword matching)
- `REASON` clause for LLM semantic search (intelligent answer extraction)
- `GROUP BY` and aggregate functions (COUNT, SUM, AVG)
- `EXPLAIN` to view query execution plans

## Request body

- QueryRequest
  - `query` string, required — RQL query string
  - `timeout_ms` integer — Optional timeout in milliseconds

## Response `200`

Query executed successfully

- QueryResponse
  - `documents` QueryDocumentMatch[] — Matched documents
    - `id` string — Document ID
    - `title` string — Document title
    - `table_id` string — Table ID
    - `tags` string[]
    - `metadata` object
    - `score` number — Relevance score (BM25 for SEARCH, confidence for REASON)
    - `highlights` string[] — Highlighted snippets
    - `answer` string — LLM-extracted answer (for REASON queries)
    - `confidence` number — Confidence score from LLM (for REASON queries)
  - `total_count` integer — Total count before pagination
  - `execution_time_ms` integer — Execution time in milliseconds
  - `aggregates` AggregateResult[] — Aggregate results (for COUNT/SUM/AVG queries)
    - `name` string — Alias or function name
    - `value` unknown
    - `group_key` array[] — Group key (for GROUP BY queries)
      - unknown[]
        - unknown
  - `explain` QueryPlan
    - `steps` PlanStep[] — Steps in the execution plan
      - `step_type` string — Step type (e.g., TableScan, IndexScan, Filter, Aggregate)
      - `description` string — Description of what this step does
      - `estimated_cost` integer — Estimated cost (0-100)
    - `estimated_rows` integer — Estimated row count
    - `indexes_used` string[] — Indexes that would be used

## Other responses

- `400` — Invalid query syntax
- `500` — Internal server error

---

[API](https://skmtc.net/brainfish-ai/apis/reasondb-api.md) · [All operations](https://skmtc.net/brainfish-ai/apis/reasondb-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/brainfish-ai/reasondb-api/revisions/f8665c1a5239/schema)