Building Context

Build and refresh ktx context from databases, context sources, query history, and text.

Build context after ktx setup creates ktx.yaml and at least one database or context-source connection. ktx writes local semantic sources and wiki pages for agents to use before writing SQL.

The build loop

Most projects use this loop:

Check readiness with ktx status.
Build one connection with ktx ingest <connectionId>, or build everything with ktx ingest --all.
Search or inspect the generated files under semantic-layer/ and wiki/.
Edit source YAML or Markdown when business logic needs refinement.
Validate and query representative sources before handing the context to an agent.

ktx ingest --all runs databases first, then context-source connections, so external metadata can attach to known warehouse tables.

Database ingest

Database ingest records table, column, type, constraint, and row-count context.

# Build one configured database connection
ktx ingest warehouse

# Build all configured connections
ktx ingest --all

Depth controls how much context ktx builds:

Flag	Best for	What it does
`--fast`	First setup, quick refreshes, CI smoke checks	Deterministic fast ingest with tables, columns, types, constraints, and row counts
`--deep`	Agent-ready context for real analysis	Fast ingest plus deep enrichment with descriptions, embeddings, relationship evidence, and optional query history

Examples:

ktx ingest warehouse --fast
ktx ingest warehouse --deep
ktx ingest --all --deep

Deep ingest needs LLM and embedding readiness. Otherwise run ktx setup or use --fast.

With claude-code, ktx agent loops can invoke only the ktx MCP tools for the current run.

Query history

PostgreSQL, BigQuery, and Snowflake can add query-history context: common joins, filters, service-account patterns, redaction rules, and high-usage templates.

Enable it during setup, store it under connections.<id>.context.queryHistory, or request it for one run:

ktx ingest warehouse --deep --query-history
# Set the lookback window for BigQuery or Snowflake query history
ktx ingest warehouse --query-history-window-days 30

Use --no-query-history when you want to skip a stored query-history setting for one run.

Relationship evidence

ktx scores relationship candidates during supported deep database ingest. The public CLI does not expose separate relationship review subcommands.

Context-source ingest

Context-source connections pull metadata from dbt, BI tools, Notion, and other configured systems. Pass one connection id or --all.

# Build one context-source connection
ktx ingest dbt_main

# Build every configured database and context-source connection
ktx ingest --all

Supported source types:

Driver	Typical source	Output
`dbt`	dbt project or Git repo	Semantic sources with model, column, test, tag, and description metadata
`metricflow`	MetricFlow project or Git repo	Metrics, dimensions, entities, and semantic joins
`lookml`	LookML files or Git repo	Views, explores, dimensions, measures, and joins
`looker`	Looker API	Explores, looks, dashboards, and model metadata
`metabase`	Metabase API	Questions, dashboards, table metadata, and mappings
`notion`	Notion API	Wiki pages and business knowledge

Context-source ingest writes semantic source YAML and wiki Markdown, reconciling with local edits.

Text ingest

Use ktx ingest --text / ktx ingest --file for notes, Markdown, runbooks, Slack exports, or other searchable memory.

# Capture a Markdown file
ktx ingest --file docs/revenue-notes.md --connection-id warehouse

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

# Capture direct text
ktx ingest --text "ARR excludes one-time implementation fees."

Useful flags:

Flag	Description
`--text <content>`	Capture inline text into memory; repeatable
`--file <path>`	Capture a text file (or `-` for stdin) into memory; repeatable
`--connection-id <connectionId>`	Attach the captured memory to a ktx connection
`--user-id <id>`	Attribute capture to a user scope, default `local-cli`
`--json`	Print structured output
`--fail-fast`	Stop after the first failed text/file item

Use text ingest for small, high-signal documents. Prefer configured context-source ingest for Notion, dbt, Metabase, and similar systems.

Output and artifacts

Every ingest run prints a summary. Use --json for scripts and agents.

ktx ingest --all --json

Typical generated files:

Path	Created by	Purpose
`semantic-layer/<connection-id>/*.yaml`	Database and context-source ingest	Queryable semantic source definitions
`wiki/global/*.md`	Context-source, text, and memory ingest	Shared business definitions and notes
`wiki/user/<user-id>/*.md`	Text and memory ingest	User-scoped context
`.ktx/setup/context-build.json`	Setup context build	Resume and readiness state for setup

Ingest transcripts include tool calls, LLM responses, and write decisions.

Example: first full refresh

After interactive setup:

ktx status
ktx ingest --all --deep
ktx status

Then inspect what changed:

git status --short
ktx sl --json
ktx wiki "revenue" --json --limit 10

Common errors

Symptom	Likely cause	Recovery
Connection not configured	The connection id is missing from `ktx.yaml`	Add it with `ktx setup`
Deep readiness is missing	LLM or embeddings are not setup-ready	Run `ktx setup`, or rerun with `--fast`
Query history is unsupported	The selected database driver does not expose query history	Run fast ingest without query-history flags
No connections configured	The project has no entries under `connections`	Run `ktx setup` and add a database or context-source connection
Context-source flags have no effect	Depth and query-history flags were supplied for a context-source connector	Use those flags only for database connections
Text ingest stops early	`--fail-fast` stopped on the first failed item	Fix the item or rerun without `--fail-fast`

On this page