mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-10 08:05:14 +02:00
78 lines
3.1 KiB
Text
78 lines
3.1 KiB
Text
---
|
|
title: "ktx ingest"
|
|
description: "Build, inspect, and replay KTX context ingest runs."
|
|
---
|
|
|
|
`ktx ingest` builds or refreshes KTX context from configured connections.
|
|
Database connections build schema context. Context-source connections ingest
|
|
metadata from tools such as dbt, Looker, Metabase, MetricFlow, LookML, and
|
|
Notion.
|
|
|
|
## Command signature
|
|
|
|
```bash
|
|
ktx ingest [options] [connectionId]
|
|
```
|
|
|
|
Use a connection id to build one configured connection. Use `--all` to build
|
|
every configured connection. Database connections run before context-source
|
|
connections when you use `--all`.
|
|
|
|
## Build options
|
|
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--all` | Build every configured connection | `false` |
|
|
| `--fast` | Use deterministic database schema ingest | Stored connection default, or `fast` |
|
|
| `--deep` | Use AI-enriched database ingest | 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>` | Query-history lookback window for this run | Stored connection default |
|
|
| `--plain` | Print plain text output | `true` |
|
|
| `--json` | Print JSON output | `false` |
|
|
| `--no-input` | Disable interactive terminal input | `false` |
|
|
|
|
`--fast` and `--deep` are mutually exclusive. Depth flags apply only to
|
|
database connections. Query-history flags apply only to database connections
|
|
that support query history.
|
|
|
|
## Status and replay
|
|
|
|
| Subcommand | Description |
|
|
|------------|-------------|
|
|
| `status [runId]` | Print status for the latest or selected stored ingest run or report file |
|
|
| `replay <runId>` | Replay a stored ingest run or bundle report through memory-flow output |
|
|
|
|
Both subcommands accept `--report-file <path>`, `--plain`, `--json`, `--viz`,
|
|
and `--no-input`.
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
ktx ingest warehouse
|
|
ktx ingest warehouse --fast
|
|
ktx ingest warehouse --deep
|
|
ktx ingest warehouse --deep --query-history
|
|
ktx ingest warehouse --query-history-window-days 30
|
|
ktx ingest notion
|
|
ktx ingest --all
|
|
ktx ingest --all --deep
|
|
|
|
ktx ingest status
|
|
ktx ingest status run-abc123
|
|
ktx ingest status --json
|
|
|
|
ktx ingest replay run-abc123
|
|
ktx ingest replay run-abc123 --viz
|
|
ktx ingest replay run-abc123 --report-file /tmp/ingest-report.json
|
|
```
|
|
|
|
## Common errors
|
|
|
|
| Error | Cause | Recovery |
|
|
|-------|-------|----------|
|
|
| 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 |
|
|
| Latest run not found | No stored ingest report exists in this project | Run `ktx ingest <connectionId>` first |
|
|
| Visual replay fails in a non-interactive shell | Visual report replay needs a terminal | Use `ktx ingest status --json` for agent and CI workflows |
|