docs: align KTX terminology

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

View file

@ -20,15 +20,15 @@ ingest decisions become files that can be reviewed, merged, and audited.
Most context already exists in dbt manifests, LookML, MetricFlow, Metabase,
Notion, warehouse metadata, and analyst notes. KTX reads those inputs through
adapters, then reconciles them into local files.
connectors, then reconciles them into local files.
```text
source tools -> adapters -> reconciliation agent -> YAML + Markdown diffs
context sources -> connectors -> reconciliation agent -> YAML + Markdown diffs
```
| Step | What happens | Output |
|------|--------------|--------|
| **Extract** | Adapters read models, metrics, questions, schemas, and docs | Structured metadata |
| **Extract** | Connectors read models, metrics, questions, schemas, and docs | Structured metadata |
| **Reconcile** | The agent compares incoming facts with existing context | Create, update, skip, or flag |
| **Write** | KTX saves changed semantic sources and wiki pages | Reviewable project files |
@ -88,7 +88,7 @@ context layer converge toward the team's current source of truth.
## Deterministic replay
Every ingestion session records the adapter inputs, tool calls, LLM responses,
Every ingestion session records the connector inputs, tool calls, LLM responses,
write decisions, and reasoning behind each change.
| Use case | What replay gives you |

View file

@ -1,24 +1,24 @@
---
title: Semantic Querying
description: How KTX compiles a short Semantic Query into safe, dialect-correct SQL using a reviewed join graph.
title: Semantic querying
description: How KTX compiles a short semantic query into safe, dialect-correct SQL using a reviewed join graph.
---
import { SemanticLayerFlow } from "@/components/semantic-layer-flow";
KTX's semantic layer is a compiler that turns intent into SQL. The agent
declares _what_ it wants - measures, dimensions, filters - in a small
Semantic Query. KTX figures out the _how_: which tables to join, what
semantic query. KTX figures out the _how_: which tables to join, what
grain to aggregate at, how to keep fan-out from inflating measures, and
what dialect the warehouse speaks.
This page covers four mechanics:
- The Semantic Query contract agents send to the compiler.
- The planner steps that turn a Semantic Query into SQL.
- The semantic query contract agents send to the compiler.
- The planner steps that turn a semantic query into SQL.
- The join graph that backs those steps, and how it's built.
- The fan-out failure mode the compiler is designed to prevent.
## Imperative SQL vs declarative Semantic Querying
## Imperative SQL vs declarative semantic querying
Writing analytics SQL is imperative work. Every question forces the
agent to hold two things in mind at once: _what_ it wants - a measure, a
@ -32,7 +32,7 @@ KTX's semantic layer separates those concerns:
- **You and KTX maintain the how.** Sources, joins, grain, measures, and
segments live in reviewable YAML - the analytical contract the team
agrees on, version-controlled.
- **The agent declares the what.** It sends a Semantic Query and trusts
- **The agent declares the what.** It sends a semantic query and trusts
the compiler to produce safe SQL.
The agent stops reasoning about plumbing. It states intent. KTX turns
@ -40,9 +40,9 @@ that into SQL the warehouse can run.
<SemanticLayerFlow />
## The Semantic Query contract
## The semantic query contract
A Semantic Query is the JSON payload the agent sends. Every field is optional
A semantic query is the JSON payload the agent sends. Every field is optional
except `measures`, and column references are fully qualified
(`source.column`) so the compiler never has to guess where a name came
from.
@ -76,7 +76,7 @@ authors a join, a CTE, or a dialect-specific cast.
## What the planner does
The planner is a deterministic pipeline. Each Semantic Query runs through the
The planner is a deterministic pipeline. Each semantic query runs through the
same ordered steps before any SQL is emitted.
1. **Resolve refs.** Qualify bare column names, look up pre-defined
@ -333,7 +333,7 @@ different from what the agent first proposed.
| Agent task | Relevant section | Next page |
|------------|------------------|-----------|
| Explain the Semantic Query shape | The Semantic Query contract | [ktx sl](/docs/cli-reference/ktx-sl) |
| Explain the semantic query shape | The semantic query contract | [ktx sl](/docs/cli-reference/ktx-sl) |
| Describe what the planner does between query and SQL | What the planner does | [ktx sl](/docs/cli-reference/ktx-sl) |
| Explain why KTX asks for grain and relationship types | The join graph | [Writing context](/docs/guides/writing-context) |
| Diagnose duplicated measures after a join | Fan-out and aggregate locality | [ktx sl](/docs/cli-reference/ktx-sl) |

View file

@ -156,7 +156,7 @@ joins:
```
For how the compiler walks the join graph, handles fan-out, and transpiles
dialects, read [Semantic Querying](/docs/concepts/semantic-layer-internals).
dialects, read [Semantic querying](/docs/concepts/semantic-layer-internals).
## Wiki pages
@ -274,7 +274,7 @@ layers.
| Agent task | Relevant section | Next page |
|------------|------------------|-----------|
| Explain why a database agent wrote a plausible but wrong query | Database access isn't enough | [Writing Context](/docs/guides/writing-context) |
| Explain why a data agent wrote a plausible but wrong query | Database access isn't enough | [Writing Context](/docs/guides/writing-context) |
| Decide whether a fact belongs in YAML or Markdown | Semantic sources / Wiki pages | [Writing Context](/docs/guides/writing-context) |
| Compare KTX to another semantic layer | How KTX compares | [Primary Sources](/docs/integrations/primary-sources) |
| Explain reviewability and source of truth | A KTX project on disk | [Context as Code](/docs/concepts/context-as-code) |