--- title: "Resolve query template" method: POST path: "/api/v1/compiler/resolve" tags: ["compiler"] --- # Resolve query template `POST /api/v1/compiler/resolve` Resolve a query template with user-selected parameters. Takes a query reference and variable selections, returns the fully resolved query object ready for compilation. RLS: Filtered to current client (ClientRLSDB). ## Query parameters - `source` string, nullable ## Headers - `X-Kater-CLI-ID` string, nullable ## Request body - ResolveRequest — Request model for resolving a query template with user selections. - `auto_fix` boolean — Automatically fix broken refs caused by renames. Defaults to True. - `combination` string — Comma-separated slot selections and variable assignments. Reserved keys: measure, dimension, filter, calculation. All other keys are variable assignments. Example: 'measure=Compliance Rate,dimension=Department,breakdown=region' - `connection_id` string, uuid, required — Connection to resolve against - `pinned_variant` string, nullable — Optional pinned variant name (e.g. '_base'). Selects a specific pinned configuration. - `query_id` string, uuid, required — UUID of the query template ## Response `200` Successful Response - ResolveResponse — Response model for a resolved query. - `dependency_graph` DependencyGraphResponse — Dependency graph between schema objects. - `edges` object, required — Edge relationships with UUID string keys - `nodes` object, required — UUID string to node mapping - `manifest` Manifest — Compilation manifest with all named objects. - `generated_at` string, required - `objects` object, required - `schema_version` string - `ref_fixes` RefFixItem[], nullable — Files auto-fixed due to renamed refs. None when no renames detected. - `file_path` string, required — Path to the modified file - `new_content` string, required — Full updated file content after fixes - `replacements` RefReplacementItem[], required — Individual ref replacements made in this file - `file_path` string, required — Path to the file containing the replaced ref - `line_number` integer, required — Line number where the replacement occurred - `new_ref` string, required — Updated reference string - `old_ref` string, required — Original reference string - `request_id` string, nullable — Write-back request ID. Non-null when ref-fix files were dispatched to CLI via WebSocket. - `resolved_query` ResolvedQuerySchemaOutput, 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 - ChartHint1Output — 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) - ChartHint2Output — A chart recommendation rule - `default` DefaultOutput, 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` ResolvedChartOutput — 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` ResolvedVariableOutput[], 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` ResolvedSelectFromEntryOutput[], 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 ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — Validation Error - `500` — Internal Server Error ## Changes - **2026-03-05** `6a140b82e07c` — 1 breaking, 1 warning, 1 info - added the new required request property `query_id` - removed the request property `query_ref` - added the new optional request property `pinned_variant` - **2026-02-26** `bef1f3e205dd` — 8 breaking, 29 warning, 25 info - response property `errors` list-of-types was widened by adding types `array` to media type `application/json` of response `400` - response property `errors` list-of-types was widened by adding types `array` to media type `application/json` of response `401` - response property `errors` list-of-types was widened by adding types `array` to media type `application/json` of response `403` - response property `errors` list-of-types was widened by adding types `array` to media type `application/json` of response `404` - …58 more - **2026-02-15** `4037d7d3404b` — 1 breaking, 11 warning, 12 info - the `resolved_query/widget_category` response's property type/format changed from ``/`` to `string`/`` for status `200` - removed the request property `include_calculations` - removed the request property `include_dimensions` - removed the request property `include_filters` - …20 more - **2026-02-10** `4255a68f5e27` — 1 info - endpoint added [Change history](https://skmtc.dev/kater-ai/apis/kater-api/changes/api/v1/compiler/resolve/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)