Query
queryRead-only
Query an entity. Select fields by name and traverse relationships with dots (e.g. 'account_manager.full_name'); filters, grouping and ordering use the same names. Blessed metrics encode which of several defensible definitions (of revenue, say) the business uses. A metric answers what the business means; an aggregate answers exactly what was asked and nothing more. describe_entity gives this entity's fields and how to write filters against them. Set dry_run to compile and return the SQL without executing it. This tool does not accept SQL.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | maximum rows to return | |
| model | No | model name; omit for the default | |
| entity | Yes | entity to query, from list_entities | |
| fields | No | field names; traverse relationships with dots, e.g. account_manager.full_name | |
| grains | No | truncate a date field to a period: field plus grain (day, week, month, quarter, year). Each makes its own output column <field>_<grain>, which is the name group_by and order_by must use | |
| having | No | same shape as filters, but names aggregate aliases and metric names rather than fields, and needs at least one aggregate or metric. To filter rows BEFORE grouping use filters, which is cheaper | |
| dry_run | No | compile and return the SQL and what it would traverse, WITHOUT running it — to check an expensive query first, or to show how a number was derived | |
| filters | No | predicates, ANDed. A leaf is {field, op, value}; op is one of = != <> > >= < <= like, not like, ilike, not ilike, in, not in, between, not between, is_null, is_not_null. A node may instead carry and/or (lists) or not (one), which is how you group. describe_entity gives the value rules, a worked example in the entity's own columns, and relative dates | |
| metrics | No | blessed metric names defined on this entity | |
| group_by | No | field names to group by when using metrics or aggregates; each must also be in fields. For a period, name the grain's output column | |
| order_by | No | sort terms; field plus optional desc | |
| per_group | No | top n rows WITHIN each group rather than overall ('top 3 per owner'): n plus partition, naming selected fields or grain output columns. Requires an explicit order_by, which decides which rows survive | |
| aggregates | No | aggregations you compose when no blessed metric fits: fn is count, count_distinct, sum, avg, min, max or ratio. count takes NO field and counts rows. ratio: sum(field) / sum(over), or a rate field alone (describe_entity's rebuild). optional as names the output column |