Run a query
POST/v1/queries
Run a new query in a given context - one of the `sql` or `structured` parameters must be present. A reference to the created query job is returned. If the same query is submitted multiple times, the same job reference may be returned if caching is enabled.
Request Body
application/json
context * object — The context to run the query in. This context determines which data sources the query has access to. The service account must have an analyst role in this context.
type * "canvas" | "project" — The type of context
context_key * string — The unique identifier for the context.
source * object — The data source to run the query against. The source must be available in the chosen context.
type * "connection" | "catalog" — The data source to query.
source_key * null | string — The connection to run the query on. Use `null` to mean DuckDB.
sql string — A SQL query definition, which can only be used to query a database connection source
structured object — A structured query definition, which can only be used to query a catalog source. Read more about the expression syntax [here](https://learn.count.co/data-exploration-and-problem-solving/visual-and-low-code-cells/calculations-in-visuals-and-low-code-cells), which is a reduced subset of Postgres-like SQL.
dataset * string — The name of the dataset to query. This should always be the name of a dataset, not a view.
selects * object[] — A list of expressions to select
view * string — The name of the view that the field comes from.
expression * string — The name of a field, or an expression for a calculated field. Names of fields should always be qualified with view names, in case there are multiple fields with the same name in different views.
filters object — Optional filters to apply to the result.
combine * "and" | "or" — How multiple filters should be combined
filters * object[] — The list of filters
value * number | string | boolean | null — The filter value
operator * "=" | "!=" | ">" | "<" | ">=" | "<=" — The filter operation
field * string — The name of a field
view * string — The name of the view that the field comes from
cache_strategy "force" | "cached-only" | "default" — Define the caching behaviour for this query.
Responses
Successful response
success * boolean
request_id * string
result * object
job_key * string — The unique identifier for the query job
compiled_sql string — The SQL query that was constructed (if available).