Skip to main content
POST
Run a SQL query

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

database
string
required

Target database.

Body

application/json

POST /v1/sql_query/{database}.

query
string
required
rerank
object | null

Rows reranked for a question before they come back: {"question": "...", "k": 10}. The rows a query finds are each put to the deployment's grader with the question - the pass the agent APIs' ask ranks its results by - and the top k come back, best first, as JSON: {"rows": [...], "rerank": {...}} with the pass's coverage. The grader reads at most the deployment's triage pool (ask.triage.pool): a search fetches the pool rather than its k, and a match's or a statement's rows past the pool are neither graded nor returned, the coverage counting them (over_pool). k is the search's own when absent, or every row graded; a k over the pool is refused (400). Off when absent or null. Needs a deployment with the agent APIs and their triage pass; refused otherwise (501). Its shape is the agent APIs' (api::rerank::Rerank), carried here as it came.

validate
null | object

Ask for the result to be checked against the question it is meant to answer. Off when absent, and nothing about the query changes. When present, a GROUP BY over a search function with a literal k under 300 is refused before it runs, and the response is JSON whatever Accept says: {"rows": [...], "validation": {...}}, the verdict beside the rows. The engine work the check spends is metered with the query.

Response

Matching rows as an Arrow IPC stream (application/vnd.apache.arrow.stream), or JSON when the request sends Accept: application/json. With validate, always JSON: {"rows": [...], "validation": {...}}. The validation carries valid, check (no_rows, aggregate, anchors or unchecked), anchors (the terms read off the question), rows (how many were considered), and when the result does not answer the question, reason and absent (the terms the searched column holds nowhere, so no query will find them). For a GROUP BY over a search function it adds group_column, groups (each group's whole length in lines and its lines holding each search term) and note, so a total over the top k is not read as a size. valid: true means the rows answer something the question asked, not that the answer is right.