2026-05-10 23:51:24 +02:00
|
|
|
# ktx examples
|
2026-05-10 23:12:26 +02:00
|
|
|
|
|
|
|
|
## local-warehouse
|
|
|
|
|
|
2026-05-14 01:43:06 +02:00
|
|
|
`local-warehouse/` is a contributor fixture for local CLI smoke tests. It uses
|
|
|
|
|
the internal fake ingest adapter so tests can exercise memory-flow behavior
|
|
|
|
|
without a live database or external service.
|
2026-05-10 23:12:26 +02:00
|
|
|
|
2026-05-14 01:43:06 +02:00
|
|
|
For normal context building, use the public connection-centric commands:
|
2026-05-10 23:12:26 +02:00
|
|
|
|
|
|
|
|
```bash
|
2026-05-14 01:43:06 +02:00
|
|
|
ktx ingest <connectionId>
|
|
|
|
|
ktx ingest --all
|
2026-05-10 23:12:26 +02:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The copied project initializes its own Git repository on first use.
|
|
|
|
|
|
|
|
|
|
## orbit-relationship-verification
|
|
|
|
|
|
2026-06-11 13:49:45 +02:00
|
|
|
`orbit-relationship-verification/` is a checked-in **ktx** project used by
|
2026-05-10 23:12:26 +02:00
|
|
|
`pnpm run relationships:verify-orbit`. It points the `orbit` SQLite connection
|
|
|
|
|
at the Orbit-style no-declared-constraint relationship fixture and verifies that
|
|
|
|
|
relationship enrichment writes nine accepted joins without requiring a local
|
|
|
|
|
warehouse credential.
|
|
|
|
|
|
feat(connectors): add MongoDB connector (#305) (#310)
* refactor(connectors): split KtxDialect into core and KtxSqlDialect
Separate the dialect contract into a driver-agnostic core (display/ref
formatting and type mapping) and a SQL-only extension (query generators).
The catalog and entity-details paths resolve the core dialect for any
snapshot driver, so it must stay free of SQL generation; this is the
prerequisite refactor for adding non-SQL primary sources.
- KtxDialect keeps type, formatDisplayRef, parseDisplayRef,
columnDisplayTablePartCount, mapDataType, mapToDimensionType
- KtxSqlDialect extends it with quoteIdentifier, formatTableName, and the
query/sample/statistics generators; the 7 SQL dialects implement it
- add getSqlDialectForDriver for SQL drivers; the 7 connectors and the
relationship-benchmark harness consume it
- thread the relationship pipeline (profiling/validation/composite/
discovery) as KtxSqlDialect | null so a non-SQL source skips coverage SQL
and its candidates stay in review; local-enrichment builds the SQL
dialect only when the connector advertises readOnlySql
Pure extraction: no behavior change for the existing 7 drivers.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(connectors): add MongoDB connector for issue #305
Add a read-only MongoDB connector that treats a database as a primary
context source: collections map to tables and inferred top-level fields to
columns. MongoDB is the first non-SQL source (readOnlySql: false), so
ktx sql and metric compilation do not apply, but its collections flow
through ingest, descriptions, and relationship discovery.
- schema-inference: infer a flat column schema from the most recent
sample_size documents (by _id desc, or order_by for non-ObjectId keys).
Union BSON types per field, mark multi-type fields mixed (string), keep
sub-documents/arrays as a single opaque json column, derive nullability
from presence, treat _id as the primary key
- connector: KtxMongoDbScanConnector behind an injectable client seam;
strictly read-only (find/listCollections/estimatedDocumentCount only),
no executeReadOnly; resolves env:/file: via resolveKtxConfigReference
- core-only KtxMongoDbDialect and a live-database introspection adapter
- wire the mongodb driver: driver union, dialect registry, driver
registration (scopeConfigKey databases), mongodbConnectionSchema,
connection-drivers, normalizeDriver, the live-database route, and the
ktx setup picker. ktx sql is refused by the read-only SQL capability gate
- tests: schema inference, connector snapshot via a fake client, dialect,
driver-schema parsing, and the ktx sql rejection
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(integrations): document the MongoDB primary source
Add a MongoDB section to the primary-sources reference: connection config
(url, databases, enabled_tables, sample_size, order_by), mongodb+srv/TLS/
Atlas notes, the schema-inference explainer, a features matrix, and the
non-SQL caveat. Update the frontmatter and connection field reference.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(connectors): address review blockers on the MongoDB connector
- introspect: skip estimatedDocumentCount for views. The count command is
rejected on a MongoDB view (CommandNotSupportedOnView), so counting a view
aborted introspect for the whole connection; compute estimatedRows only for
real collections, as ClickHouse does.
- sl: refuse a semantic-layer query against a non-SQL connection instead of
defaulting it to the Postgres dialect. compileLocalSlQuery (the shared CLI +
MCP path) now rejects a driver with no SQL dialect via the new
isSqlQueryableDriver authority, keeping MongoDB context-only per issue #305.
- tests: cover input.tableScope and the empty-scope skip for the Mongo
connector (the scan layer does not post-filter), the view no-count path, and
the ktx sl query refusal for a mongodb connection.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* polish(mongodb): compute sampled nullCount and document sampling caveats
Address the non-blocking review notes:
- sampleColumn now counts null/absent values over the sampled window instead of
returning nullCount: null, since the documents are already in hand
- warn that a custom order_by must be indexed (an unindexed sort hits MongoDB's
in-memory sort limit on large collections) in the connection schema and docs
- note that sampled values for nested fields are stringified, not faithfully
serialized, so the json opacity is deliberate
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(examples): add a MongoDB connector example
A manual, container-backed example mirroring examples/postgres-historic:
- docker-compose.yml + init/seed.js seed a representative dataset (nested
documents, arrays, a Decimal128, a mixed-type field, a nullable field, an
ObjectId reference, and a view) on first container start
- scripts/smoke.sh + introspect-smoke.mjs assert the connector's inferred
schema with no LLM credentials — the same introspection entry point ktx
ingest's database-schema stage uses, including the view-no-count path
- README.md documents the smoke and a full keyless ktx ingest run
(claude-code LLM + managed sentence-transformers embeddings)
Works with Docker Compose or podman compose. Verified end to end.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* chore: ignore examples/** in knip to fix dead-code false positives
The MongoDB connector example files (examples/mongodb/init/seed.js and
examples/mongodb/scripts/introspect-smoke.mjs) are used at runtime but were
flagged as unused by knip. Add examples/** to the ignore array, matching the
existing .context/** entry.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0114qQV8fJ5a5ME3XbMVRzbL
* fix(mongodb): refuse non-SQL connections before SQL analysis
`ktx sql` and the MCP sql_execution tool resolved a SQL-analysis dialect
(falling back to Postgres for a non-SQL driver) and ran read-only
validation before the connector capability gate refused the connection.
For a MongoDB connection that spun up the parser/daemon and produced
Postgres parser diagnostics instead of a clean non-SQL refusal.
Route both entry points through a shared assertSqlQueryableConnection
guard before dialect selection, mirroring compileLocalSlQuery. The
federated duckdb path has no driver and is exempted at each call site.
Add CLI and MCP regression tests asserting validation/connector work
never starts for a MongoDB connection.
* fix(mongodb): pass CI gates (dialect boundary, secrets, setup test)
Three latent failures in the connector surfaced once CI ran on the branch:
- connector.ts imported the concrete KtxMongoDbDialect, which the connector
dialect-import boundary forbids. Route it through getDialectForDriver('mongodb')
and widen inferKtxMongoCollectionColumns to the base KtxDialect (it only uses
mapDataType/mapToDimensionType).
- detect-secrets flagged a test ObjectId hex and the mongodb+srv example URL;
annotate both with allowlist pragmas.
- the "shows every supported database" setup test omitted the new MongoDB option.
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Luca Martial <48870843+luca-martial@users.noreply.github.com>
Co-authored-by: Luca Martial <lucamrtl@gmail.com>
Co-authored-by: Andrey Avtomonov <andreybavt@gmail.com>
2026-06-29 15:17:56 +02:00
|
|
|
## mongodb
|
|
|
|
|
|
|
|
|
|
`mongodb/` is a manual container-backed example for the MongoDB connector. It
|
|
|
|
|
seeds a representative dataset (nested documents, arrays, a mixed-type field, a
|
|
|
|
|
nullable field, and a view), then exercises the connector as a fast no-LLM
|
|
|
|
|
introspection smoke (`scripts/smoke.sh`) and documents a full keyless
|
|
|
|
|
`ktx ingest` run. Works with Docker Compose or `podman compose`.
|
|
|
|
|
|
2026-05-10 23:12:26 +02:00
|
|
|
## postgres-historic
|
|
|
|
|
|
2026-05-14 01:43:06 +02:00
|
|
|
`postgres-historic/` is a manual Docker-backed smoke for Postgres
|
|
|
|
|
query-history ingest via `pg_stat_statements`. It verifies setup, staged
|
2026-06-11 13:49:45 +02:00
|
|
|
query-history artifacts, **ktx** daemon batch SQL analysis, bounded pattern
|
2026-05-14 01:43:06 +02:00
|
|
|
WorkUnit shards, and no-WorkUnit idempotency for unchanged bucketed table
|
|
|
|
|
inputs and pattern shards.
|
2026-05-10 23:12:26 +02:00
|
|
|
|
|
|
|
|
## package-artifacts
|
|
|
|
|
|
|
|
|
|
`package-artifacts/` documents the artifact smoke checks. Those checks create
|
|
|
|
|
temporary projects instead of storing sample projects in this directory.
|