apunkt/ktx
1
0
Fork 0
mirror of https://github.com/Kaelio/ktx.git synced 2026-06-16 08:25:14 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: align KTX terminology

Browse source
This commit is contained in:
Andrey Avtomonov 2026-05-20 17:11:46 +02:00
parent ad9c9eda0d
commit 27afd6a3b0
25 changed files with 117 additions and 116 deletions
Download patch file Download diff file Expand all files Collapse all files

15
docs-site/content/docs/cli-reference/ktx-connection.mdx
View file

@ -1,11 +1,12 @@
---
title: "ktx connection"
description: "List and test configured data sources."
description: "List and test configured database and context-source connections."
---
Inspect configured connections in your KTX project. Connections define how KTX
reaches databases, warehouses, BI tools, source projects, and knowledge
systems. Use `ktx setup` to add, remove, or reconfigure them.
reaches primary sources (databases and warehouses) and context sources (BI
tools, modeling projects, and knowledge systems). Use `ktx setup` to add,
remove, or reconfigure them.
## Command signature
@ -77,8 +78,8 @@ my-warehouse postgres
`ktx connection test <connectionId>` performs a lightweight connection probe.
Native database connections report `Status: ok` when the connector probe
passes. Source connectors report connector-specific details such as Metabase
database count, Looker user, Notion bot, or Git repo URL.
passes. Context-source connectors report connector-specific details such as
Metabase database count, Looker user, Notion bot, or Git repo URL.
```text
Connection test passed: my-warehouse
@ -102,7 +103,7 @@ configured connection and exit non-zero if any probe fails.
| Error | Cause | Recovery |
|-------|-------|----------|
| No connections configured | The project has no entries under `connections` | Run `ktx setup` and add a database or source connection |
| No connections configured | The project has no entries under `connections` | Run `ktx setup` and add a database or context-source connection |
| Connection test fails | Credentials, network access, database, warehouse, or schema is invalid | Verify the same URL with the database's native client, then rerun `ktx setup` and reconfigure the connection |
| Mapping validation fails during setup | BI database mappings do not point at valid warehouse connections | Rerun `ktx setup` and update the source mapping selections |
| Mapping validation fails during setup | BI database mappings do not point at valid warehouse connections | Rerun `ktx setup` and update the context-source mapping selections |
| Notion page picker cannot run | The terminal is non-interactive or Notion discovery failed | Rerun interactive `ktx setup`, or use non-interactive setup flags with explicit root page ids |

30
docs-site/content/docs/cli-reference/ktx-ingest.mdx
View file

@ -29,8 +29,8 @@ connection is selected.
| Flag | Description | Default |
|------|-------------|---------|
| `--all` | Ingest all configured connections (same as bare invocation) | `false` |
| `--fast` | Use deterministic database schema ingest | Stored connection default, or `fast` |
| `--deep` | Use AI-enriched database ingest | Stored connection default, or `fast` |
| `--fast` | Use deterministic fast database ingest | Stored connection default, or `fast` |
| `--deep` | Use deep database ingest with AI-generated descriptions, embeddings, and relationship evidence | Stored connection default, or `fast` |
| `--query-history` | Include database query-history usage patterns | Stored connection default |
| `--no-query-history` | Skip database query-history usage patterns for this run | Stored connection default |
| `--query-history-window-days <days>` | BigQuery/Snowflake query-history lookback window for this run | Stored connection default |
@ -48,14 +48,14 @@ connection is selected.
database connections. Query-history flags apply only to database connections
that support query history. The window flag applies to BigQuery and Snowflake;
Postgres reads the current `pg_stat_statements` aggregate data instead of a
time-windowed history table. Query-history ingest runs after schema ingest and
time-windowed history table. Query-history ingest runs after fast ingest and
requires deep ingest readiness.
When more than one connection is selected, database ingest runs first, then
source ingest and memory updates run for source connections.
context-source ingest and memory updates run for context-source connections.
Some ingest paths use the managed KTX Python runtime. Query-history ingest uses
it for SQL analysis, and Looker source ingest uses it for Looker identifier
it for SQL analysis, and Looker context-source ingest uses it for Looker identifier
parsing. In an interactive terminal, `ktx ingest` prompts before installing the
required runtime features. Use `--yes` to install them without prompting, or
use `--no-input` to fail fast with install guidance.
@ -69,13 +69,13 @@ use `--no-input` to fail fast with install guidance.
# Build every configured connection (bare = --all)
ktx ingest
# Build one database or source connection
# Build one database or context-source connection
ktx ingest warehouse
# Force deterministic database schema ingest
# Force deterministic fast database ingest
ktx ingest warehouse --fast
# Force AI-enriched database ingest
# Force deep database ingest with AI enrichment
ktx ingest warehouse --deep
# Include query-history usage patterns
@ -83,7 +83,7 @@ ktx ingest warehouse --deep --query-history
# Set the lookback window for BigQuery or Snowflake query history
ktx ingest warehouse --query-history-window-days 30
# Build a source connection
# Build a context-source connection
ktx ingest notion
# Capture inline text into memory
@ -114,11 +114,11 @@ notion skipped skipped done done
Use `--json` when a script or agent needs the selected plan and per-target
results.
## Inspect source ingest traces
## Inspect context-source ingest traces
Source ingest writes persistent JSONL traces for postmortem debugging. Plain
ingest output prints the trace path near the report, run, and job identifiers
when a trace is available:
Context-source ingest writes persistent JSONL traces for postmortem debugging.
Plain ingest output prints the trace path near the report, run, and job
identifiers when a trace is available:
```text
Report: report-abc123
@ -155,7 +155,7 @@ KTX_INGEST_TRACE_LEVEL=trace ktx ingest metabase
|-------|-------|----------|
| Connection not configured | The connection id is not present in `ktx.yaml` | Add the connection with `ktx setup` or update `ktx.yaml` |
| Deep readiness is missing | `--deep` or query history needs model, embedding, and scan-enrichment configuration | Run `ktx setup` or rerun with `--fast` |
| Query history is unsupported | The selected database driver does not support query history | Run schema ingest without query-history flags |
| Query history is unsupported | The selected database driver does not support query history | Run fast ingest without query-history flags |
| Python runtime is missing | The selected ingest target needs runtime-backed SQL analysis or source parsing | Accept the interactive prompt, rerun with `--yes`, or run the suggested `ktx admin runtime install` command |
| Source options were ignored | Depth and query-history flags were supplied for a non-database source | Omit database-only flags when ingesting source connections |
| Context-source options were ignored | Depth and query-history flags were supplied for a context-source connection | Omit database-only flags when ingesting context-source connections |
| Text ingest stops early | `--fail-fast` was used and one item failed | Fix the failed item or rerun without `--fail-fast` to collect all failures |

20
docs-site/content/docs/cli-reference/ktx-setup.mdx
View file

@ -82,11 +82,11 @@ embedding credential source.
Setup prepares the managed Python runtime when your selected configuration
needs it. In the full setup flow, the runtime step runs after database and
source setup and before the initial context build.
context-source setup and before the initial context build.
KTX prepares the `core` runtime feature when query-history ingest, Looker
source ingest, database introspection fallback, or daemon-backed context build
paths need it. KTX prepares the `local-embeddings` runtime feature when you
context-source ingest, database introspection fallback, or daemon-backed
context build paths need it. KTX prepares the `local-embeddings` runtime feature when you
choose managed local `sentence-transformers` embeddings. Existing external
daemon URLs, such as `KTX_DAEMON_URL` or `KTX_SQL_ANALYSIS_URL`, satisfy the
matching dependency and skip managed runtime installation for that dependency.
@ -134,25 +134,25 @@ Enabling query history makes deep ingest readiness matter for later
| Flag | Description |
|------|-------------|
| `--source <type>` | Source connector type: `dbt`, `metricflow`, `metabase`, `looker`, `lookml`, or `notion` |
| `--source-connection-id <id>` | Connection id for source setup |
| `--source <type>` | Context-source connector type: `dbt`, `metricflow`, `metabase`, `looker`, `lookml`, or `notion` |
| `--source-connection-id <id>` | Connection id for context-source setup |
| `--source-path <path>` | Local source path for dbt, MetricFlow, or LookML |
| `--source-git-url <url>` | Git URL for dbt, MetricFlow, or LookML |
| `--source-branch <branch>` | Git branch for source setup |
| `--source-subpath <path>` | Repo subpath for source setup |
| `--source-branch <branch>` | Git branch for context-source setup |
| `--source-subpath <path>` | Repo subpath for context-source setup |
| `--source-auth-token-ref <ref>` | `env:` or `file:` credential reference for source repo auth |
| `--source-url <url>` | Source service URL for Metabase or Looker |
| `--source-api-key-ref <ref>` | `env:` or `file:` API key reference for Metabase or Notion |
| `--source-client-id <id>` | Looker client id |
| `--source-client-secret-ref <ref>` | `env:` or `file:` Looker client secret reference |
| `--source-warehouse-connection-id <id>` | Warehouse connection id used for source mapping |
| `--source-warehouse-connection-id <id>` | Warehouse connection id used for context-source mapping |
| `--source-project-name <name>` | dbt project name override |
| `--source-profiles-path <path>` | dbt profiles path |
| `--source-target <target>` | dbt target or source-specific mapping target |
| `--source-target <target>` | dbt target or context-source-specific mapping target |
| `--metabase-database-id <id>` | Metabase database id to map |
| `--notion-crawl-mode <mode>` | Notion crawl mode: `all_accessible` or `selected_roots` |
| `--notion-root-page-id <id>` | Notion root page id; repeatable |
| `--skip-sources` | Mark optional source setup complete with no sources |
| `--skip-sources` | Mark optional context-source setup complete with no sources |
Choose only one source location: `--source-path` or `--source-git-url`.

18
docs-site/content/docs/cli-reference/ktx-sl.mdx
View file

@ -1,6 +1,6 @@
---
title: "ktx sl"
description: "List, search, validate, or query semantic-layer sources."
description: "List, search, validate, or query semantic sources."
---
Interact with your project's semantic layer. Semantic sources are YAML
@ -15,8 +15,8 @@ ktx sl validate <sourceName> [options]
ktx sl query [options]
```
- Bare `ktx sl` lists semantic-layer sources.
- `ktx sl <query...>` searches semantic-layer sources (multi-word queries are
- 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.
@ -24,10 +24,10 @@ ktx sl query [options]
| Subcommand | Description |
|-----------|-------------|
| (none, no query) | List semantic-layer sources |
| (none, with query) | Search semantic-layer sources |
| `validate <sourceName>` | Validate a semantic-layer source against the database schema |
| `query` | Compile or execute a Semantic Query |
| (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
@ -51,7 +51,7 @@ ktx sl query [options]
| Flag | Description | Default |
|------|-------------|---------|
| `--connection-id <id>` | KTX connection id | - |
| `--query-file <path>` | JSON Semantic Query file | - |
| `--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 | - |
@ -66,7 +66,7 @@ ktx sl query [options]
| `--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.
`--query-file` should point to a JSON semantic query object.
## Examples

4
docs-site/content/docs/cli-reference/ktx.mdx
View file

@ -4,7 +4,7 @@ description: "Root command map, global options, and project resolution for the K
---
The `ktx` CLI sets up local projects, builds agent-ready context, checks
connections, queries semantic-layer sources, searches wiki pages, runs the MCP
connections, queries semantic sources, searches wiki pages, runs the MCP
server, and manages the bundled Python runtime.
## Command signature
@ -93,7 +93,7 @@ ktx ingest warehouse
# Build every configured connection
ktx ingest
# Search semantic-layer sources and wiki pages
# Search semantic sources and wiki pages
ktx sl "revenue"
ktx wiki "revenue recognition"