ktx sl

Interact with your project's semantic layer. Semantic sources are YAML definitions that describe tables, columns, measures, joins, segments, and grain: the vocabulary agents use to generate correct SQL.

Command signature

ktx sl [options] [query...]            # list (bare) or search (with query)
ktx sl validate <sourceName> [options]
ktx sl query [options]

Bare ktx sl lists semantic sources.
ktx sl <query...> searches semantic sources (multi-word queries are joined with a space).
ktx sl validate and ktx sl query remain as explicit subcommands.

Subcommands

Subcommand	Description
(none, no query)	List semantic sources
(none, with query)	Search semantic sources
`validate <sourceName>`	Validate a semantic source against the database schema
`query`	Compile or execute a semantic query

Options

`sl` (list or search)

Flag	Description	Default
`--connection-id <id>`	Filter by ktx connection id	-
`--limit <number>`	Maximum search results (search mode only)	-
`--output <mode>`	Output mode: `pretty` (default in TTY), `plain` (TSV), or `json`	`pretty`
`--json`	Shortcut for `--output=json` (overrides `--output`)	`false`

`sl validate`

Flag	Description	Default
`--connection-id <id>`	ktx connection id (required)	-

`sl query`

Flag	Description	Default
`--connection-id <id>`	ktx connection id	-
`--query-file <path>`	JSON semantic query file	-
`--measure <measure>`	Measure to query; repeatable (at least one required)	-
`--dimension <dimension>`	Dimension to include; repeatable	-
`--filter <filter>`	Filter expression; repeatable	-
`--segment <segment>`	Segment to include; repeatable	-
`--order-by <field[:direction]>`	Order field, optionally suffixed with `:asc` or `:desc`; repeatable	-
`--limit <n>`	Query limit	-
`--include-empty`	Include empty rows	`false`
`--format <format>`	Output format: `json` or `sql`	`json`
`--execute`	Execute the compiled query against the database	`false`
`--yes`	Install the managed Python runtime without prompting when required	`false`
`--no-input`	Disable interactive managed runtime installation	-
`--max-rows <n>`	Maximum rows to return when executing	-

sl query requires at least one --measure unless --query-file is set. --query-file should point to a JSON semantic query object.

Examples

# List all semantic sources
ktx sl

# List sources for a specific connection
ktx sl --connection-id my-warehouse

# List sources as JSON
ktx sl --json

# Search sources as JSON
ktx sl "revenue" --json

# Validate a source against the live schema
ktx sl validate orders --connection-id my-warehouse

# Compile a query and view the generated SQL
ktx sl query \
  --connection-id my-warehouse \
  --measure orders.total_revenue \
  --dimension orders.created_date \
  --format sql

# Execute a query with filters
ktx sl query \
  --connection-id my-warehouse \
  --measure orders.total_revenue \
  --dimension orders.status \
  --filter "orders.created_date >= '2024-01-01'" \
  --execute \
  --max-rows 100

# Query with ordering and limit
ktx sl query \
  --connection-id my-warehouse \
  --measure orders.total_revenue \
  --dimension customers.country \
  --order-by total_revenue:desc \
  --limit 10 \
  --execute

# Execute and cap the result set
ktx sl query \
  --connection-id my-warehouse \
  --measure orders.count \
  --dimension orders.created_date \
  --execute \
  --max-rows 1000

# Compile or execute without prompting for runtime installation
ktx sl query \
  --connection-id my-warehouse \
  --measure orders.count \
  --execute \
  --yes

# Execute a query from a JSON file
ktx sl query \
  --connection-id my-warehouse \
  --query-file query.json \
  --execute \
  --max-rows 100

Output

Bare ktx sl (list) and ktx sl <query> (search) return human-readable output by default. Use --json when an agent needs structured output. Use --format sql on query to inspect generated SQL before execution, or leave --format json for the compiled query and optional rows. Pretty search output shows #1, #2, and later rank badges for the displayed results. Plain and JSON output keep the raw score value, which is a ranking score rather than a percentage.

{
  "sql": "SELECT orders.status, SUM(orders.total_amount) AS total_revenue FROM public.orders GROUP BY orders.status",
  "rows": [
    {
      "orders.status": "completed",
      "total_revenue": 125000
    }
  ]
}

Common errors

Error	Cause	Recovery
Source not found	Source name or connection id is wrong	Run `ktx sl --json` and retry with an exact source name and connection id
Validation fails	YAML references missing columns, invalid joins, or invalid SQL expressions	Fix the source YAML and rerun `ktx sl validate`
Query compile fails	Measure, dimension, filter, or segment name is invalid	Search sources with `ktx sl <query>`, inspect the source YAML in your project files, then retry using declared fields
Execution returns too many rows	`--max-rows` is missing or too high	Add `--max-rows` with a bounded value before executing
Runtime install is blocked	Query execution needs the managed Python runtime and prompts are disabled	Run `ktx admin runtime install --feature core --yes`, or rerun `ktx sl query --yes`

On this page