mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
c202202e6b
* feat(cli): clean up wiki and sl commands * test(scripts): update package artifact CLI smoke assertion
147 lines
4.7 KiB
Text
147 lines
4.7 KiB
Text
---
|
|
title: "ktx sl"
|
|
description: "List, search, validate, or query semantic-layer sources."
|
|
---
|
|
|
|
Interact with your project's semantic layer. Semantic sources are YAML definitions that describe your tables, columns, measures, joins, and grain — the vocabulary agents use to generate correct SQL.
|
|
|
|
## Command signature
|
|
|
|
```bash
|
|
ktx sl <subcommand> [options]
|
|
```
|
|
|
|
## Subcommands
|
|
|
|
| Subcommand | Description |
|
|
|-----------|-------------|
|
|
| `list` | List semantic-layer sources |
|
|
| `search <query>` | Search semantic-layer sources |
|
|
| `validate <sourceName>` | Validate a semantic-layer source against the database schema |
|
|
| `query` | Compile or execute a semantic-layer query |
|
|
|
|
## Options
|
|
|
|
### `sl list`
|
|
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--connection-id <id>` | Filter by KTX connection id | — |
|
|
| `--output <mode>` | Output mode: `pretty` (default in TTY), `plain` (TSV), or `json` | `pretty` |
|
|
| `--json` | Shortcut for `--output=json` (overrides `--output`) | `false` |
|
|
|
|
### `sl search`
|
|
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--connection-id <id>` | Filter by KTX connection id | — |
|
|
| `--limit <number>` | Maximum search results | — |
|
|
| `--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-layer 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` |
|
|
| `--max-rows <n>` | Maximum rows to return when executing | — |
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
# List all semantic sources
|
|
ktx sl list
|
|
|
|
# List sources for a specific connection
|
|
ktx sl list --connection-id my-warehouse
|
|
|
|
# List sources as JSON
|
|
ktx sl list --json
|
|
|
|
# Search sources as JSON
|
|
ktx sl search "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
|
|
|
|
# Execute a query from a JSON file
|
|
ktx sl query \
|
|
--connection-id my-warehouse \
|
|
--query-file query.json \
|
|
--execute \
|
|
--max-rows 100
|
|
```
|
|
|
|
## Output
|
|
|
|
Semantic-layer commands return human-readable output by default. Use `--json` or `--format json` when an agent needs structured output; use `--format sql` to inspect generated SQL before execution.
|
|
|
|
```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 list --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 search`, 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 |
|