--- title: "Execute query with transparent caching" method: POST path: "/api/v1/compiler/execute" tags: ["compiler"] --- # Execute query with transparent caching `POST /api/v1/compiler/execute` Execute a query with transparent caching. Compiles the resolved query to SQL, checks the cache for existing results, executes against the warehouse on cache miss, and stores the result for future requests. Cache failures are invisible to the caller. RLS: Filtered to current client (ClientRLSDB). ## Query parameters - `source` string, nullable ## Headers - `X-Kater-CLI-ID` string, nullable ## Request body - ExecuteRequest — Request model for executing a query with transparent caching. - `connection_id` string, uuid, required — Connection to execute against - `resolved_query` ResolvedQuerySchemaInput, required — Schema for a resolved Kater query — after user selects optional fields and variables are bound, but before ref()/expr() compilation to SQL - `ai_context` string, nullable — Usage guidance for AI processing - `calculations` union[], nullable — Merged required + selected optional calculations - union - RefWithLabel — A reference with optional label override - `label` string, nullable — Optional label override for this reference - `ref` string, required — Reference using ref(), var(), or expr() syntax - InlineField — An inline field definition for dimensions/measures/calculations - `kater_id` string, uuid, required — Unique identifier for this inline field - `label` string, nullable — Human-readable label - `name` string, required — Name of the inline field - `sql` string, required — SQL expression for the field - string - `chart_hints` union[], nullable — Chart recommendations preserved for evaluation - union - ChartHint1Input — A chart recommendation rule - `config` ChartConfig, required — Chart configuration with variable references - `color_by` string, nullable — Field or variable reference for color grouping - `comparison` 'previous_period' | 'target' — Comparison mode for single_value widgets (e.g., previous_period, target) - `size` string, nullable — Field or variable reference for size - `stack_by` string, nullable — Field or variable reference for stacking - `target_value` string, nullable — Target value for comparison: target mode - `x_axis` string, nullable — Field or variable reference for x-axis - `y_axis` string, nullable — Field or variable reference for y-axis - `recommend` 'line' | 'bar' | 'stacked_bar' | 'area' | 'pie' | 'donut' | 'scatter' | 'table' | 'heatmap' | 'single_value', required — Type of chart visualization - `when` object, required — Conditions based on variable values - can be single value (string) or multiple values (array) - ChartHint2Input — A chart recommendation rule - `default` DefaultInput, required - `config` ChartConfig, required — Chart configuration with variable references - … - `recommend` 'line' | 'bar' | 'stacked_bar' | 'area' | 'pie' | 'donut' | 'scatter' | 'table' | 'heatmap' | 'single_value', required — Type of chart visualization - `custom_properties` CustomProperties — Custom properties - `description` string, nullable — Description of the query - `dimensions` union[], nullable — Merged required + selected optional dimensions - union - RefWithLabel — A reference with optional label override - `label` string, nullable — Optional label override for this reference - `ref` string, required — Reference using ref(), var(), or expr() syntax - InlineField — An inline field definition for dimensions/measures/calculations - `kater_id` string, uuid, required — Unique identifier for this inline field - `label` string, nullable — Human-readable label - `name` string, required — Name of the inline field - `sql` string, required — SQL expression for the field - string - `disallowed_widget_types` WidgetType[], nullable — Widget types within the declared widget_category that must NOT render this query - `filters` union[], nullable — Merged required + selected optional filters - union - InlineFormulaFilter — An inline filter using a SQL/expression formula - `name` string, required — Name of the inline filter - `sql` string, required — SQL expression for the filter condition - string - InlineExistsFilter1 — An inline filter using EXISTS or NOT EXISTS with a subquery - `description` string, nullable — Description of the filter - `exists` SubqueryCondition, required — A subquery condition for EXISTS/NOT EXISTS filters - `from` string, required — Reference to the source view/table for the subquery - `where` string[], required — WHERE conditions for the subquery - `label` string, nullable — Human-readable label - `name` string, required — Name of the inline filter - `not_exists` SubqueryCondition — A subquery condition for EXISTS/NOT EXISTS filters - `from` string, required — Reference to the source view/table for the subquery - `where` string[], required — WHERE conditions for the subquery - InlineExistsFilter2 — An inline filter using EXISTS or NOT EXISTS with a subquery - `description` string, nullable — Description of the filter - `exists` SubqueryCondition — A subquery condition for EXISTS/NOT EXISTS filters - `from` string, required — Reference to the source view/table for the subquery - `where` string[], required — WHERE conditions for the subquery - `label` string, nullable — Human-readable label - `name` string, required — Name of the inline filter - `not_exists` SubqueryCondition, required — A subquery condition for EXISTS/NOT EXISTS filters - `from` string, required — Reference to the source view/table for the subquery - `where` string[], required — WHERE conditions for the subquery - `inheritance_chain` string[], nullable — Ordered list of query refs that were merged during inheritance resolution - `kater_id` string, uuid, required — Unique identifier for this resolved query instance - `label` string, nullable — Human-readable label with var() values substituted - `limit` integer, nullable — Maximum number of rows to return - `measures` union[], nullable — Merged required + selected optional measures - union - RefWithLabel — A reference with optional label override - `label` string, nullable — Optional label override for this reference - `ref` string, required — Reference using ref(), var(), or expr() syntax - InlineField — An inline field definition for dimensions/measures/calculations - `kater_id` string, uuid, required — Unique identifier for this inline field - `label` string, nullable — Human-readable label - `name` string, required — Name of the inline field - `sql` string, required — SQL expression for the field - string - `name` string, required — Name from the leaf query in the inheritance chain - `order_by` OrderBy — Sort order specification for query results. Use desc for descending (highest/newest first) and asc for ascending (lowest/oldest first). - `asc` string[], nullable — Fields to sort in ascending order (lowest/oldest first) - `desc` string[], nullable — Fields to sort in descending order (highest/newest first) - `resolved_chart` ResolvedChartInput — The matched chart recommendation after evaluating chart hints - `config` ChartConfig, required — Chart configuration with variable references - `color_by` string, nullable — Field or variable reference for color grouping - `comparison` 'previous_period' | 'target' — Comparison mode for single_value widgets (e.g., previous_period, target) - `size` string, nullable — Field or variable reference for size - `stack_by` string, nullable — Field or variable reference for stacking - `target_value` string, nullable — Target value for comparison: target mode - `x_axis` string, nullable — Field or variable reference for x-axis - `y_axis` string, nullable — Field or variable reference for y-axis - `recommend` 'line' | 'bar' | 'stacked_bar' | 'area' | 'pie' | 'donut' | 'scatter' | 'table' | 'heatmap' | 'single_value', required — Type of chart visualization - `resolved_variables` ResolvedVariableInput[], nullable — Full variable definitions with bound values - `allowed_values` union — Allowed values configuration - VariableAllowedValues1 — Allowed values for a variable - either static list or from column - `static` LabeledValue[], required — Static list of allowed values with optional labels - `label` string, nullable — Human-readable label for the value - `value` union, required — The actual value - … - VariableAllowedValues2 — Allowed values for a variable - either static list or from column - `cache_ttl` integer — Cache time-to-live in seconds - `from_column` string, required — Reference to column for dynamic values - `limit` integer — Maximum number of values to retrieve - `order_by` 'asc' | 'desc' — Sort order for values - `bound_value` union, required — The concrete value bound for this resolution - string - number - boolean - union[] - union - string - number - boolean - `constraints` VariableConstraints — Constraints for variable types - `max` number, nullable — Maximum allowed value - `max_length` integer, nullable — Maximum length for STRING variables - `min` number, nullable — Minimum allowed value - `step` number, nullable — Step increment for numeric input - `default` union, required — Default value for this variable - string - number - boolean - union[] - union - string - number - boolean - `description` string, nullable — Description of the variable's purpose - `is_default` boolean, nullable — True if bound_value equals the default value - `is_runtime` boolean, nullable — True if this is a runtime variable (not resolved at compile time). Runtime variables have var() placeholders left in compiled SQL for literal substitution at execution time. - `kater_id` string, uuid, required — Unique identifier for this variable - `label` string, nullable — Human-readable label for the variable - `name` string, required — Variable name identifier - `type` 'STRING' | 'INT' | 'FLOAT' | 'DATE' | 'TIMESTAMP' | 'BOOL' | 'STRING[]' | 'INT[]' | 'FLOAT[]' | 'DATE[]' | 'DIMENSION' | 'MEASURE' | 'CALCULATION' | 'FILTER', required — Data type for query variables - `select_from` ResolvedSelectFromEntryInput[], nullable — Resolved select_from entries with CTE metadata - `cte_alias` string, required — CTE alias used in the WITH clause (e.g., __sf_compliance_rate__base) - `output_columns` CteOutputColumn[], required — Columns produced by the CTE, available as q:query_name.field_name in the parent - `column_alias` string, required — The SQL column alias in the CTE output - `field_name` string, required — The field name used in q:query_name.field_name references - `source_type` 'dimension' | 'dimension_date' | 'measure' | 'calculation', required — Original type of the field in the source query - `ref` string, required — Reference to the source query - `variables` object, nullable — Variable overrides passed to the referenced query - `source_query` string, required — Reference to the original query template this was resolved from - `topic` string, required — Reference to the topic this query uses (always known after inheritance resolution) - `widget_category` 'axis' | 'funnel' | 'heatmap' | 'image' | 'kpi_card' | 'pie' | 'table' | 'text', required — Category of widget that determines data shape constraints for queries - `tenant_key` string, required — Tenant key for multi-tenant execution. Use 'kater_global_tenant' for no-tenancy clients. ## Response `200` Successful Response - ExecuteResponse — Response model for query execution. - `cache_hit` boolean — Whether the result was served from cache - `column_map` ColumnMapEntryResponse[] — Maps UUID column aliases to human-readable names - `aggregation` string, nullable — Aggregation type for measures: sum, count, min, max, avg, unknown. None for non-measures. - `field_type` string, required — Field type: dimension, measure, or calculation - `kater_id` string, required — UUID string used as SQL column alias - `label` string, nullable — Display label - `name` string, required — Human-readable column name - `data` object[] — Query result rows as list of column-value dicts - `dialect` string, required — SQL dialect used - `errors` CompilerErrorItem[] — Compilation errors (if any) - `code` string, required — Machine-readable error code - `column` integer, nullable — Column number in the source file - `file` string, nullable — Source file path where the error occurred - `line` integer, nullable — Line number in the source file - `message` string, required — Human-readable error description - `ref` string, nullable — Reference to the source element (e.g. view or query name) - `remediation` string, nullable — Suggested fix for this error - `execution_time_ms` number — Total execution time in milliseconds - `metadata` CompilationMetadataResponse — Compilation metadata from the compiler. - `dialect` string, required — SQL dialect used (e.g. 'snowflake') - `dimensions_used` string[] — Dimension names used in compilation - `filters_used` string[] — Filter names used in compilation - `measures_used` string[] — Measure names used in compilation - `query_ref` string, required — Reference to the compiled query - `views_used` string[] — View names used in compilation - `row_count` integer — Number of rows returned - `sql` string, nullable — Generated SQL statement - `success` boolean, required — Whether execution succeeded ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — Validation Error - `500` — Internal Server Error ## Changes - **2026-03-05** `6a140b82e07c` — 2 breaking - the request property `tenant_key` became required - request property `tenant_key` list-of-types was narrowed by removing types `null` from media type `application/json` - **2026-02-26** `bef1f3e205dd` — 26 breaking, 1 warning, 32 info - added the new required request property `resolved_query/resolved_variables/anyOf[subschema #1]/items/kater_id` - removed `#/components/schemas/InlineFieldFilter` from the `resolved_query/filters/anyOf[subschema #1]/items/` request property `anyOf` list - removed the enum value `area_chart` of the request property `resolved_query/disallowed_widget_types/anyOf[subschema #1]/items/` - removed the enum value `bar_chart` of the request property `resolved_query/disallowed_widget_types/anyOf[subschema #1]/items/` - …55 more - **2026-02-15** `4037d7d3404b` — 1 info - endpoint added [Change history](https://skmtc.dev/kater-ai/apis/kater-api/changes/api/v1/compiler/execute/post.md) --- [API](https://skmtc.dev/kater-ai/apis/kater-api.md) · [All operations](https://skmtc.dev/kater-ai/apis/kater-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kater-ai/kater-api/revisions/6a140b82e07c/schema)