mirror of
https://github.com/Kaelio/ktx.git
synced 2026-07-07 11:02:11 +02:00
docs: standardize ktx naming (#187)
* docs: align KTX terminology * docs: standardize ktx naming
This commit is contained in:
Andrey Avtomonov
GitHub
parent
2f70861a18
commit
17647a436a
43 changed files with 438 additions and 419 deletions
|
|
@ -1,10 +1,10 @@
|
|||
---
|
||||
title: "ktx ingest"
|
||||
description: "Build or refresh KTX context, or capture text into KTX memory."
|
||||
description: "Build or refresh ktx context, or capture text into ktx memory."
|
||||
---
|
||||
|
||||
`ktx ingest` builds or refreshes KTX context from configured connections, and
|
||||
can also capture free-form text into KTX memory. Database connections build
|
||||
`ktx ingest` builds or refreshes **ktx** context from configured connections, and
|
||||
can also capture free-form text into **ktx** memory. Database connections build
|
||||
schema context. Context-source connections ingest metadata from tools such as
|
||||
dbt, Looker, Metabase, MetricFlow, LookML, and Notion. Pass `--text` or
|
||||
`--file` to capture inline text or text files into memory instead.
|
||||
|
|
@ -18,7 +18,7 @@ ktx ingest [options] [connectionId]
|
|||
- Bare `ktx ingest` (no positional, no `--all`) ingests every configured
|
||||
connection.
|
||||
- `ktx ingest <connectionId>` ingests one configured connection.
|
||||
- `ktx ingest --text "..."` (or `--file <path>`) captures notes into KTX
|
||||
- `ktx ingest --text "..."` (or `--file <path>`) captures notes into **ktx**
|
||||
memory instead of ingesting a connection.
|
||||
|
||||
Database connections run before context-source connections when more than one
|
||||
|
|
@ -29,14 +29,14 @@ 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 |
|
||||
| `--text <content>` | Capture inline text into KTX memory; repeatable | `[]` |
|
||||
| `--file <path>` | Capture a text file into KTX memory; use `-` for stdin; repeatable | `[]` |
|
||||
| `--connection-id <connectionId>` | KTX connection id to tag captured text/file notes | - |
|
||||
| `--text <content>` | Capture inline text into **ktx** memory; repeatable | `[]` |
|
||||
| `--file <path>` | Capture a text file into **ktx** memory; use `-` for stdin; repeatable | `[]` |
|
||||
| `--connection-id <connectionId>` | **ktx** connection id to tag captured text/file notes | - |
|
||||
| `--user-id <id>` | Memory user id for text/file capture attribution | `local-cli` |
|
||||
| `--fail-fast` | Stop after the first failed text/file item | `false` |
|
||||
| `--plain` | Print plain text output | `true` |
|
||||
|
|
@ -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
|
||||
Some ingest paths use the managed **ktx** Python runtime. Query-history ingest uses
|
||||
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
|
||||
|
|
@ -141,7 +141,7 @@ jq -c '. | {at, level, phase, event, durationMs, data, error}' \
|
|||
.ktx/ingest-traces/<jobId>/trace.jsonl
|
||||
```
|
||||
|
||||
KTX writes `debug` trace events by default. Set `KTX_INGEST_TRACE_LEVEL` to
|
||||
**ktx** writes `debug` trace events by default. Set `KTX_INGEST_TRACE_LEVEL` to
|
||||
`error`, `info`, `debug`, or `trace` before running ingest to change the trace
|
||||
verbosity:
|
||||
|
||||
|
|
@ -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 |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue