--- title: "Compile resolved query to SQL" method: POST path: "/api/v1/compiler/compile" tags: ["compiler"] --- # Compile resolved query to SQL `POST /api/v1/compiler/compile` Compile a resolved query to SQL. Takes a previously resolved query and generates the final SQL statement for the target dialect. RLS: Filtered to current client (ClientRLSDB). ## Query parameters - `source` string, nullable ## Headers - `X-Kater-CLI-ID` string, nullable ## Request body - CompileRequest — Request model for compiling a resolved query to SQL. - `connection_id` string, uuid, required — Connection to compile 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 compilation. Use 'kater_global_tenant' for no-tenancy clients or to bypass tenant isolation. For database tenancy, maps to the tenant's database. For row tenancy, used as the row-level filter value. ## Response `200` Successful Response - CompileResponse — Response model for SQL compilation. - `column_map` ColumnMapEntryResponse[] — Maps UUID column aliases to human-readable names and types - `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 - `dialect` string, required — SQL dialect used (e.g. 'snowflake') - `errors` CompilerErrorItem[] — Compilation errors - `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 - `manifest` Manifest — Compilation manifest with all named objects. - `generated_at` string, required - `objects` object, required - `schema_version` string - `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 - `request_id` string, nullable — Write-back request ID. Non-null when files were dispatched to CLI via WebSocket. - `sql` string, nullable — Generated SQL statement - `success` boolean, required — Whether compilation 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, 33 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/` - …56 more - **2026-02-15** `4037d7d3404b` — 6 breaking, 1 warning, 15 info - removed `#/components/schemas/ChartHint1` from the `resolved_query/chart_hints/anyOf[subschema #1]/items/` request property `anyOf` list - removed `#/components/schemas/ResolvedChart` from the `resolved_query/resolved_chart` request property `anyOf` list - removed `#/components/schemas/WidgetCategory, subschema #2` from the `resolved_query/widget_category` request property `anyOf` list - request property `resolved_query/widget_category` was restricted to a list of enum values - …18 more - **2026-02-10** `4255a68f5e27` — 1 info - endpoint added [Change history](https://skmtc.dev/kater-ai/apis/kater-api/changes/api/v1/compiler/compile/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)