ktx ingest

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.

Command signature

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 memory instead of ingesting a connection.

Database connections run before context-source connections when more than one connection is selected.

Options

--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. 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 fast ingest and requires deep ingest readiness.

When more than one connection is selected, database ingest runs first, then 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 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.

--text and --file cannot be combined with a positional connectionId or --all; pass --connection-id <id> instead to tag captured notes.

Examples

# Build every configured connection (bare = --all)
ktx ingest

# Build one database or context-source connection
ktx ingest warehouse

# Force deterministic fast database ingest
ktx ingest warehouse --fast

# Force deep database ingest with AI enrichment
ktx ingest warehouse --deep

# Include query-history usage patterns
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 context-source connection
ktx ingest notion

# Capture inline text into memory
ktx ingest --text "Refunds are excluded from net revenue."

# Capture multiple text snippets in one call
ktx ingest --text "Revenue is gross receipts." --text "Orders are completed purchases."

# Capture a local Markdown file into memory and tag it to a connection
ktx ingest --file docs/revenue-notes.md --connection-id warehouse

# Capture one stdin item
printf "Refunds are excluded from net revenue." | ktx ingest --file -

Output

Plain output summarizes each target and the operations that ran.

Ingest finished

Source         Database schema  Query history  Source ingest  Memory update
warehouse      done             done           skipped        skipped
notion         skipped          skipped        done           done

Use --json when a script or agent needs the selected plan and per-target results.

Inspect context-source ingest traces

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:

Report: report-abc123
Run: run-abc123
Job: job-abc123
Trace: .ktx/ingest-traces/job-abc123/trace.jsonl

The trace file lives under the project directory at .ktx/ingest-traces/<jobId>/trace.jsonl. Each line is a JSON event with the job id, run id, sync id, connection id, source key, phase, event name, timing, state snapshot, decision context, and error details. Failed runs also write a stored ingest report with status: "failed", failure.phase, failure.message, and the same trace path.

Use jq or line-oriented tools to inspect a trace:

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 error, info, debug, or trace before running ingest to change the trace verbosity:

KTX_INGEST_TRACE_LEVEL=trace ktx ingest metabase

Common errors