apunkt/ktx
1
0
Fork 0
mirror of https://github.com/Kaelio/ktx.git synced 2026-07-16 11:31:02 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: standardize ktx naming (#187)

Browse source 
* docs: align KTX terminology

* docs: standardize ktx naming
This commit is contained in:
Andrey Avtomonov 2026-05-20 17:33:38 +02:00 • committed by GitHub
parent 2f70861a18
commit 17647a436a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
43 changed files with 438 additions and 419 deletions
Download patch file Download diff file Expand all files Collapse all files

22
docs-site/content/docs/integrations/context-sources.mdx
View file

@ -3,7 +3,7 @@ title: Context Sources
description: Ingest semantic context from dbt, MetricFlow, LookML, Metabase, Looker, and Notion.
---
Context sources feed your existing analytics tooling into KTX. During ingestion, KTX extracts metadata from each source and uses an LLM agent to reconcile it with your existing semantic layer and knowledge base - merging intelligently rather than overwriting.
Context sources feed your existing analytics tooling into **ktx**. During ingestion, **ktx** extracts metadata from each source and uses a reconciliation agent to reconcile it with your existing semantic layer and knowledge base - preserving accepted edits rather than overwriting.
All context sources are configured in `ktx.yaml` under `connections` with their respective `driver` value.
@ -27,7 +27,7 @@ LookML uses top-level `repoUrl`, and MetricFlow uses nested
| Field | Required | Description |
|-------|----------|-------------|
| `driver` | Yes | Source adapter: `dbt`, `metricflow`, `lookml`, `metabase`, `looker`, or `notion` |
| `driver` | Yes | Source connector: `dbt`, `metricflow`, `lookml`, `metabase`, `looker`, or `notion` |
| `source_dir` | For local file sources | Absolute or project-relative source directory |
| `repo_url` | For Git-hosted dbt sources | Git repository URL |
| `repoUrl` | For Git-hosted LookML sources | Git repository URL |
@ -88,7 +88,7 @@ connections:
### What gets ingested
- YAML semantic sources generated from dbt schema files
- One work unit per model file (for projects with >25 YAML files) or all at once for smaller projects
- One work unit per semantic source (for projects with >25 YAML files) or all at once for smaller projects
- Column descriptions, tests, and relationships are preserved
---
@ -198,7 +198,7 @@ This validates that LookML model `connection:` declarations match expectations,
## Metabase
Ingests dashboards, questions, and their underlying SQL queries from a Metabase instance. Maps Metabase databases to your KTX warehouse connections.
Ingests dashboards, questions, and their underlying SQL queries from a Metabase instance. Maps Metabase databases to your **ktx** warehouse connections.
### What it provides
@ -217,7 +217,7 @@ connections:
api_key_ref: env:METABASE_API_KEY
mappings:
databaseMappings:
"3": postgres-main # Metabase DB ID → KTX connection
"3": postgres-main # Metabase DB ID → ktx connection
syncEnabled:
"3": true
syncMode: ONLY # Only ingest mapped databases
@ -239,7 +239,7 @@ Generate an API key in Metabase: **Admin > Settings > Authentication > API Keys*
### Warehouse mapping
Metabase databases must be mapped to KTX connections so ingested context links to the correct warehouse:
Metabase databases must be mapped to **ktx** connections so ingested context links to the correct warehouse:
```yaml
mappings:
@ -256,7 +256,7 @@ Find Metabase database IDs in **Admin > Databases** - the ID is in the URL when
## Looker
Ingests explores, looks, and dashboards from a Looker instance via the Looker API. Maps Looker connections to your KTX warehouse connections.
Ingests explores, looks, and dashboards from a Looker instance via the Looker API. Maps Looker connections to your **ktx** warehouse connections.
### What it provides
@ -276,7 +276,7 @@ connections:
client_secret_ref: env:LOOKER_CLIENT_SECRET
mappings:
connectionMappings:
postgres_connection: postgres-main # Looker conn → KTX conn
postgres_connection: postgres-main # Looker conn → ktx conn
```
### Authentication
@ -296,7 +296,7 @@ Generate API credentials in Looker: **Admin > Users > Edit > API Keys**.
### Warehouse mapping
Map Looker connection names to KTX connections so explores link to the correct warehouse:
Map Looker connection names to **ktx** connections so explores link to the correct warehouse:
```yaml
mappings:
@ -316,7 +316,7 @@ Ingests pages and databases from a Notion workspace as wiki pages. Useful for ca
- Wiki pages synthesized from Notion content
- Page hierarchy and relationships
- Database schemas (when Notion databases describe data sources)
- Database schemas (when Notion databases describe primary sources)
- Semantic clustering for organized ingestion
### Connection config
@ -378,7 +378,7 @@ Create an integration at [notion.so/my-integrations](https://www.notion.so/my-in
| Error or symptom | Likely cause | Recovery |
|------------------|--------------|----------|
| Adapter cannot read source files | `source_dir`, `repo_url`, `repoUrl`, `metricflow.repoUrl`, `branch`, or `path` is wrong | Verify the path locally or clone the repo manually with the same credentials |
| Connector cannot read source files | `source_dir`, `repo_url`, `repoUrl`, `metricflow.repoUrl`, `branch`, or `path` is wrong | Verify the path locally or clone the repo manually with the same credentials |
| Private repo/API authentication fails | Token env var or secret file is missing | Export the env var or update `auth_token_ref` to a readable file |
| Ingest creates duplicate context | Existing source names or wiki pages do not match imported terminology | Review the diff, rename duplicates, and add wiki pages with canonical names |
| Notion ingest skips pages | Integration lacks access or root ids are missing | Share pages with the Notion integration and set `root_page_ids` or use `all_accessible` carefully |