mirror of
https://github.com/Kaelio/ktx.git
synced 2026-07-01 08:59:39 +02:00
* 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>
This commit is contained in:
Pintouch
GitHub
parent
4f084186f1
commit
2afab61417
59 changed files with 1971 additions and 129 deletions
|
|
@ -23,6 +23,14 @@ at the Orbit-style no-declared-constraint relationship fixture and verifies that
|
|||
relationship enrichment writes nine accepted joins without requiring a local
|
||||
warehouse credential.
|
||||
|
||||
## 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`.
|
||||
|
||||
## postgres-historic
|
||||
|
||||
`postgres-historic/` is a manual Docker-backed smoke for Postgres
|
||||
|
|
|
|||
127
examples/mongodb/README.md
Normal file
127
examples/mongodb/README.md
Normal file
|
|
@ -0,0 +1,127 @@
|
|||
# MongoDB Connector Example
|
||||
|
||||
A manual, self-contained example for the **ktx** MongoDB connector. It starts a
|
||||
local MongoDB, seeds a representative dataset, and exercises the connector both
|
||||
as a fast no-LLM introspection smoke and as a full `ktx ingest` run.
|
||||
|
||||
MongoDB is a **context-only** primary source: collections become tables and
|
||||
inferred top-level fields become columns, but `ktx sql` and semantic-layer
|
||||
metric compilation do not apply. See
|
||||
[`docs-site/content/docs/integrations/primary-sources.mdx`](../../docs-site/content/docs/integrations/primary-sources.mdx).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker with Compose v2, or Podman with `podman compose`
|
||||
- Node and pnpm matching the **ktx** workspace
|
||||
- The built CLI: `pnpm --filter @kaelio/ktx run build`
|
||||
- For the full ingest only: `uv` on `PATH` and a usable local Claude Code
|
||||
session (the keyless `claude-code` LLM backend)
|
||||
|
||||
## What the seed contains
|
||||
|
||||
[`init/seed.js`](init/seed.js) creates the `app` database with:
|
||||
|
||||
- `users` — `_id` (ObjectId), scalar fields, a nested `address`, an array
|
||||
`tags`, a `Decimal128` `balance`, a `ref` field that holds more than one type
|
||||
(inferred `mixed`), and an `age` field absent from one document (nullable)
|
||||
- `orders` — an ObjectId `user_id` reference for relationship discovery
|
||||
- `active_users` — a **view** (to confirm introspection never runs a count
|
||||
command on a view)
|
||||
|
||||
MongoDB applies the script once on first container start. Apply it by hand with:
|
||||
|
||||
```bash
|
||||
mongosh "mongodb://localhost:27117" < examples/mongodb/init/seed.js
|
||||
```
|
||||
|
||||
## Smoke (no LLM credentials)
|
||||
|
||||
From the **ktx** repository root:
|
||||
|
||||
```bash
|
||||
examples/mongodb/scripts/smoke.sh
|
||||
```
|
||||
|
||||
It starts MongoDB on `127.0.0.1:27117`, seeds it, and asserts the connector's
|
||||
inferred schema (collections → tables, nested → `json`, `mixed`, nullability,
|
||||
`_id` primary key, and a view introspected with `estimatedRows: null`). This
|
||||
drives the same entry point `ktx ingest`'s "database schema" stage uses, without
|
||||
needing an LLM or embeddings.
|
||||
|
||||
Podman:
|
||||
|
||||
```bash
|
||||
KTX_MONGODB_COMPOSE="podman compose" examples/mongodb/scripts/smoke.sh
|
||||
```
|
||||
|
||||
Set `KTX_MONGODB_KEEP=1` to leave the container running after the script exits.
|
||||
|
||||
## Full `ktx ingest`
|
||||
|
||||
The public database-ingest path requires a configured model and embeddings.
|
||||
This runs entirely locally with the keyless `claude-code` LLM backend and the
|
||||
**ktx**-managed `sentence-transformers` embedding daemon — no API keys.
|
||||
|
||||
Start MongoDB and create a project:
|
||||
|
||||
```bash
|
||||
docker compose -f examples/mongodb/docker-compose.yml up -d --wait # or: podman compose
|
||||
node packages/cli/dist/bin.js admin init /tmp/ktx-mongodb-example
|
||||
```
|
||||
|
||||
Add the connection and a keyless enrichment stack to
|
||||
`/tmp/ktx-mongodb-example/ktx.yaml`:
|
||||
|
||||
```yaml
|
||||
connections:
|
||||
mongo-prod:
|
||||
driver: mongodb
|
||||
url: mongodb://localhost:27117/app
|
||||
databases:
|
||||
- app
|
||||
llm:
|
||||
provider:
|
||||
backend: claude-code
|
||||
models:
|
||||
default: sonnet
|
||||
scan:
|
||||
enrichment:
|
||||
mode: llm
|
||||
embeddings:
|
||||
backend: sentence-transformers
|
||||
model: all-MiniLM-L6-v2
|
||||
dimensions: 384
|
||||
sentenceTransformers:
|
||||
base_url: ""
|
||||
```
|
||||
|
||||
Test the connection and ingest:
|
||||
|
||||
```bash
|
||||
node packages/cli/dist/bin.js connection test mongo-prod --project-dir /tmp/ktx-mongodb-example
|
||||
node packages/cli/dist/bin.js ingest mongo-prod --project-dir /tmp/ktx-mongodb-example --yes --plain
|
||||
```
|
||||
|
||||
The first ingest starts the **ktx** embedding daemon and downloads the
|
||||
`all-MiniLM-L6-v2` model. Expected final state: `Database schema: done`.
|
||||
|
||||
Inspect the result:
|
||||
|
||||
- `raw-sources/mongo-prod/live-database/<run>/tables/*.json` — one per
|
||||
collection, including the `active_users` view with `estimatedRows: null`
|
||||
- `raw-sources/mongo-prod/live-database/<run>/enrichment/relationships.json` —
|
||||
inferred relationships sit in `review` (a non-SQL source has no read-only SQL
|
||||
coverage validation), with `accepted: []`
|
||||
- `semantic-layer/mongo-prod/_schema/app.yaml` — the schema with per-column AI
|
||||
descriptions
|
||||
|
||||
`ktx sql -c mongo-prod "SELECT 1"` is refused by the read-only SQL capability
|
||||
gate, and `ktx sl query -c mongo-prod ...` is refused because MongoDB is not a
|
||||
SQL source.
|
||||
|
||||
## Cleanup
|
||||
|
||||
```bash
|
||||
docker compose -f examples/mongodb/docker-compose.yml down -v # or: podman compose
|
||||
rm -rf /tmp/ktx-mongodb-example
|
||||
```
|
||||
14
examples/mongodb/docker-compose.yml
Normal file
14
examples/mongodb/docker-compose.yml
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
services:
|
||||
mongodb:
|
||||
image: mongo:7
|
||||
ports:
|
||||
# Non-default host port so the example does not clash with a local MongoDB.
|
||||
- "27117:27017"
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "mongosh --quiet --eval \"db.runCommand({ ping: 1 }).ok\" | grep -q 1"]
|
||||
interval: 2s
|
||||
timeout: 5s
|
||||
retries: 30
|
||||
volumes:
|
||||
# MongoDB runs *.js here once, on first start, against an empty data dir.
|
||||
- ./init:/docker-entrypoint-initdb.d:ro
|
||||
64
examples/mongodb/init/seed.js
Normal file
64
examples/mongodb/init/seed.js
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
// Seed a representative MongoDB dataset for the ktx connector example.
|
||||
//
|
||||
// MongoDB runs this once on first container start (it is mounted into
|
||||
// /docker-entrypoint-initdb.d). It can also be applied by hand:
|
||||
// mongosh "mongodb://localhost:27117" < examples/mongodb/init/seed.js
|
||||
//
|
||||
// The shapes here exercise the connector's schema inference end to end:
|
||||
// scalar BSON types, a nested sub-document, an array, Decimal128, dates, a
|
||||
// field with more than one type (-> "mixed"), an absent field (-> nullable),
|
||||
// an ObjectId reference for relationship discovery, and a view (to confirm
|
||||
// introspection never runs a count command on a view).
|
||||
const app = db.getSiblingDB('app');
|
||||
|
||||
app.users.drop();
|
||||
app.orders.drop();
|
||||
|
||||
app.users.insertMany([
|
||||
{
|
||||
email: 'ada@example.com',
|
||||
age: 31,
|
||||
active: true,
|
||||
created: new Date('2026-01-04T10:00:00Z'),
|
||||
balance: NumberDecimal('120.50'),
|
||||
address: { city: 'NY', zip: '10001' },
|
||||
tags: ['admin', 'early-access'],
|
||||
ref: 'abc',
|
||||
},
|
||||
{
|
||||
email: 'grace@example.com',
|
||||
active: false,
|
||||
created: new Date('2026-02-11T08:30:00Z'),
|
||||
balance: NumberDecimal('0.00'),
|
||||
address: { city: 'SF', zip: '94016' },
|
||||
tags: [],
|
||||
ref: 42, // a second type for this field -> inferred "mixed"
|
||||
// age intentionally absent -> inferred nullable
|
||||
},
|
||||
{
|
||||
email: 'linus@example.com',
|
||||
age: 27,
|
||||
active: true,
|
||||
created: new Date('2026-03-01T12:00:00Z'),
|
||||
balance: NumberDecimal('9.99'),
|
||||
address: { city: 'Austin', zip: '73301' },
|
||||
tags: ['beta'],
|
||||
ref: null,
|
||||
},
|
||||
]);
|
||||
|
||||
const userIds = app.users.find({}, { _id: 1 }).toArray().map((u) => u._id);
|
||||
|
||||
app.orders.insertMany([
|
||||
{ user_id: userIds[0], total: 120.5, status: 'paid', placed: new Date('2026-03-02T09:00:00Z') },
|
||||
{ user_id: userIds[0], total: 9.99, status: 'pending', placed: new Date('2026-03-05T14:00:00Z') },
|
||||
{ user_id: userIds[1], total: 50.25, status: 'paid', placed: new Date('2026-03-06T16:00:00Z') },
|
||||
]);
|
||||
|
||||
// A view, to confirm introspection does not issue a count command on it
|
||||
// (MongoDB rejects count on a view with CommandNotSupportedOnView).
|
||||
app.createView('active_users', 'users', [{ $match: { active: true } }]);
|
||||
|
||||
print('users: ' + app.users.countDocuments());
|
||||
print('orders: ' + app.orders.countDocuments());
|
||||
print('collections: ' + app.getCollectionNames().join(', '));
|
||||
53
examples/mongodb/scripts/introspect-smoke.mjs
Normal file
53
examples/mongodb/scripts/introspect-smoke.mjs
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
// Deterministic, no-LLM smoke for the MongoDB connector. Drives the same
|
||||
// introspection entry point ktx ingest's "database schema" stage uses, against
|
||||
// the seeded example database, and asserts the inferred schema.
|
||||
//
|
||||
// Usage: node introspect-smoke.mjs [mongoUrl]
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { dirname, resolve } from 'node:path';
|
||||
|
||||
const here = dirname(fileURLToPath(import.meta.url));
|
||||
const ktxRoot = resolve(here, '../../..');
|
||||
const connectorUrl = `file://${resolve(
|
||||
ktxRoot,
|
||||
'packages/cli/dist/connectors/mongodb/live-database-introspection.js',
|
||||
)}`;
|
||||
|
||||
const mongoUrl = process.argv[2] ?? 'mongodb://localhost:27117/app';
|
||||
|
||||
const { createMongoDbLiveDatabaseIntrospection } = await import(connectorUrl);
|
||||
|
||||
function assert(condition, message) {
|
||||
if (!condition) {
|
||||
throw new Error(`assertion failed: ${message}`);
|
||||
}
|
||||
}
|
||||
|
||||
const port = createMongoDbLiveDatabaseIntrospection({
|
||||
connections: { 'mongo-example': { driver: 'mongodb', url: mongoUrl, databases: ['app'] } },
|
||||
});
|
||||
|
||||
const snapshot = await port.extractSchema('mongo-example');
|
||||
const tables = new Map(snapshot.tables.map((table) => [table.name, table]));
|
||||
|
||||
assert(snapshot.driver === 'mongodb', 'snapshot driver is mongodb');
|
||||
assert(['orders', 'users'].every((name) => tables.has(name)), 'users and orders collections introspected');
|
||||
|
||||
const users = tables.get('users');
|
||||
const columns = new Map(users.columns.map((column) => [column.name, column]));
|
||||
assert(columns.get('_id')?.primaryKey === true && columns.get('_id')?.nullable === false, '_id is the non-null primary key');
|
||||
assert(columns.get('age')?.nullable === true, 'age is nullable (absent in one document)');
|
||||
assert(columns.get('email')?.nullable === false, 'email is non-nullable (present in every document)');
|
||||
assert(columns.get('address')?.normalizedType === 'json', 'nested address maps to opaque json');
|
||||
assert(columns.get('tags')?.normalizedType === 'json', 'array tags maps to opaque json');
|
||||
assert(columns.get('ref')?.nativeType === 'mixed', 'ref with two types is inferred as mixed');
|
||||
|
||||
const view = tables.get('active_users');
|
||||
assert(view?.kind === 'view', 'active_users is a view');
|
||||
assert(view?.estimatedRows === null, 'a view is introspected without a count (estimatedRows null)');
|
||||
|
||||
console.log(`OK: introspected ${snapshot.tables.length} collections from ${mongoUrl}`);
|
||||
for (const table of snapshot.tables) {
|
||||
console.log(` - ${table.db}.${table.name} (${table.kind}, ${table.columns.length} columns)`);
|
||||
}
|
||||
process.exit(0);
|
||||
37
examples/mongodb/scripts/smoke.sh
Executable file
37
examples/mongodb/scripts/smoke.sh
Executable file
|
|
@ -0,0 +1,37 @@
|
|||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# Manual smoke for the MongoDB connector: start MongoDB, seed it, and assert the
|
||||
# connector's schema introspection (the deterministic, no-LLM half of ktx ingest's
|
||||
# "database schema" stage). The full enrichment ingest is documented in README.md.
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
EXAMPLE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
|
||||
KTX_ROOT="$(cd "$EXAMPLE_DIR/../.." && pwd)"
|
||||
COMPOSE_FILE="$EXAMPLE_DIR/docker-compose.yml"
|
||||
CONNECTOR="$KTX_ROOT/packages/cli/dist/connectors/mongodb/live-database-introspection.js"
|
||||
MONGO_URL="${KTX_MONGODB_URL:-mongodb://localhost:27117/app}"
|
||||
|
||||
# Compose engine: docker by default, override for podman:
|
||||
# KTX_MONGODB_COMPOSE="podman compose" examples/mongodb/scripts/smoke.sh
|
||||
COMPOSE="${KTX_MONGODB_COMPOSE:-docker compose}"
|
||||
|
||||
cleanup() {
|
||||
if [[ "${KTX_MONGODB_KEEP:-0}" != "1" ]]; then
|
||||
$COMPOSE -f "$COMPOSE_FILE" down -v >/dev/null 2>&1 || true
|
||||
fi
|
||||
}
|
||||
trap cleanup EXIT
|
||||
|
||||
if [[ ! -f "$CONNECTOR" ]]; then
|
||||
echo "Build the CLI first: pnpm --filter @kaelio/ktx run build" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Starting MongoDB and seeding (${COMPOSE})…"
|
||||
$COMPOSE -f "$COMPOSE_FILE" up -d --wait
|
||||
|
||||
echo "Asserting connector introspection against ${MONGO_URL}…"
|
||||
node "$SCRIPT_DIR/introspect-smoke.mjs" "$MONGO_URL"
|
||||
|
||||
echo "Smoke passed."
|
||||
Loading…
Add table
Add a link
Reference in a new issue