ktx/docs-site/content/docs/cli-reference/ktx-sl.mdx

---
title: "ktx sl"
description: "List, search, validate, or query semantic sources."
---

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

```bash
ktx sl [options] [query...]            # list (bare) or search (with query)
ktx sl read <sourceName>
ktx sl validate <sourceName>
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 read <sourceName>` prints the YAML for one source. Add
  `--connection-id` only when the source name exists in multiple connections.
- `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 |
| `read <sourceName>` | Print the YAML for one semantic source |
| `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 read`

| Flag | Description | Default |
|------|-------------|---------|
| `--connection-id <id>` | Optional **ktx** connection id for disambiguation | - |

### `sl validate`

| Flag | Description | Default |
|------|-------------|---------|
| `--connection-id <id>` | Optional **ktx** connection id for disambiguation | - |

### `sl query`

| Flag | Description | Default |
|------|-------------|---------|
| `--connection-id <id>` | Required **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 `--connection-id` and at least one `--measure` unless
`--query-file` is set. `--query-file` must point to a JSON semantic query
object.

## Examples

```bash
# 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

# Print the YAML for a source name that is unique across connections
ktx sl read orders

# Print the YAML for a source name that exists in multiple connections
ktx sl --connection-id my-warehouse read orders

# Validate a source name that is unique across connections
ktx sl validate orders

# Validate a source name that exists in multiple connections
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.

`ktx sl read <sourceName>` prints the source YAML directly to stdout when the
source name is unique across connections. If the name exists in multiple
connections, rerun the command with `--connection-id <id>`. The command does
not wrap output in pretty, plain, or JSON formatting, so it can be piped to
other tools.

```json
{
  "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 <query>` or `ktx sl --connection-id <id>` to find the exact source name, then retry `ktx sl read <sourceName>` or `ktx sl validate <sourceName>` |
| Source name is ambiguous | The same source name exists in multiple connections | Rerun with `--connection-id <id>` from the error message |
| 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` |