@kaelio/ktx 0.13.1 → 0.15.0

package/dist/connectors/bigquery/connector.js

@@ -1,8 +1,10 @@
 import { BigQuery } from '@google-cloud/bigquery';
-import { normalizeBigQueryProjectId, normalizeBigQueryRegion } from '../../context/connections/bigquery-identifiers.js';
-import { getDialectForDriver } from '../../context/connections/dialects.js';
+import { normalizeBigQueryDatasetId, normalizeBigQueryProjectId, normalizeBigQueryRegion, } from '../../context/connections/bigquery-identifiers.js';
+import { getSqlDialectForDriver } from '../../context/connections/dialects.js';
+import { resolveQueryDeadlineMs, queryDeadlineExceededError } from '../../context/connections/query-deadline.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { tryConstraintQuery } from '../../context/scan/constraint-discovery.js';
+import { tryIntrospectObject } from '../../context/scan/object-introspection.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
 import { connectorTestFailure, createKtxConnectorCapabilities, } from '../../context/scan/types.js';
 import { resolveStringReference } from '../shared/string-reference.js';
@@ -11,8 +13,8 @@ class DefaultBigQueryClientFactory {
         const client = new BigQuery(input);
         return {
             getDatasets: (options) => client.getDatasets(options),
-            dataset: (datasetId) => {
-                const dataset = client.dataset(datasetId);
+            dataset: (datasetId, projectId) => {
+                const dataset = client.dataset(datasetId, { projectId });
                 return {
                     get: () => dataset.get(),
                     getTables: () => dataset.getTables(),
@@ -26,14 +28,39 @@ function stringConfigValue(connection, key, env) {
     const value = connection?.[key];
     return typeof value === 'string' && value.trim().length > 0 ? resolveStringReference(value.trim(), env) : undefined;
 }
-function datasetIds(connection, env) {
-    if (Array.isArray(connection.dataset_ids) && connection.dataset_ids.length > 0) {
-        return connection.dataset_ids
-            .filter((dataset) => dataset.trim().length > 0)
-            .map((dataset) => resolveStringReference(dataset, env));
-    }
-    const datasetId = stringConfigValue(connection, 'dataset_id', env);
-    return datasetId ? [datasetId] : [];
+/**
+ * Parse one `dataset_ids` / `dataset_id` entry into a canonical
+ * {@link BigQueryDatasetRef}. A `project.dataset` prefix selects the host
+ * project; a bare entry defaults to `defaultProject` (the billing project).
+ * More than one dot, or an empty segment, is a config error naming the
+ * connection — never a silent mis-introspection at scan time.
+ */
+function parseBigQueryDatasetEntry(entry, defaultProject, connectionId) {
+    const context = `connections.${connectionId}.dataset_ids entry "${entry}"`;
+    const parts = entry.split('.');
+    if (parts.length === 1) {
+        return { project: defaultProject, dataset: normalizeBigQueryDatasetId(parts[0], context) };
+    }
+    if (parts.length === 2) {
+        const [project, dataset] = parts;
+        if (!project || !dataset) {
+            throw new Error(`Invalid BigQuery dataset entry for ${context}: empty project or dataset segment`);
+        }
+        return {
+            project: normalizeBigQueryProjectId(project, context),
+            dataset: normalizeBigQueryDatasetId(dataset, context),
+        };
+    }
+    throw new Error(`Invalid BigQuery dataset entry for ${context}: expected "dataset" or "project.dataset", got more than one "."`);
+}
+function resolveDatasetRefs(connection, env, defaultProject, connectionId) {
+    const rawEntries = Array.isArray(connection.dataset_ids) && connection.dataset_ids.length > 0
+        ? connection.dataset_ids.map((dataset) => resolveStringReference(dataset, env))
+        : [stringConfigValue(connection, 'dataset_id', env)].filter((value) => Boolean(value));
+    return rawEntries
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0)
+        .map((entry) => parseBigQueryDatasetEntry(entry, defaultProject, connectionId));
 }
 function bigQueryMaxBytesBilledFromConnection(connection) {
     const value = connection?.max_bytes_billed;
@@ -46,12 +73,23 @@ function bigQueryMaxBytesBilledFromConnection(connection) {
     }
     return undefined;
 }
-function bigQueryJobTimeoutMsFromConnection(connection) {
-    const value = connection?.job_timeout_ms;
-    if (typeof value !== 'number') {
-        return undefined;
+// jobTimeoutMs cancels the job with a "Job timed out" message (or a timeout
+// reason in the errors array) once the deadline elapses.
+function isBigQueryTimeoutError(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
     }
-    return Number.isInteger(value) && value > 0 ? value : undefined;
+    const topMessage = error.message;
+    if (typeof topMessage === 'string' && /timed out|timeout/i.test(topMessage)) {
+        return true;
+    }
+    const errors = error.errors;
+    return (Array.isArray(errors) &&
+        errors.some((entry) => {
+            const reason = entry?.reason;
+            const message = entry?.message;
+            return reason === 'timeout' || (typeof message === 'string' && /timed out|timeout/i.test(message));
+        }));
 }
 function tableKind(metadataType) {
     const type = String(metadataType ?? '').toUpperCase();
@@ -125,7 +163,7 @@ export function bigQueryConnectionConfigFromConfig(input) {
     if (!projectId) {
         throw new Error(`Native BigQuery connector requires credentials_json.project_id for connections.${input.connectionId}`);
     }
-    const resolvedDatasetIds = datasetIds(input.connection, env);
+    const resolvedDatasetIds = resolveDatasetRefs(input.connection, env, projectId, input.connectionId);
     const location = stringConfigValue(input.connection, 'location', env);
     return { projectId, credentials, datasetIds: resolvedDatasetIds, ...(location ? { location } : {}) };
 }
@@ -146,8 +184,8 @@ export class KtxBigQueryScanConnector {
     clientFactory;
     now;
     maxBytesBilled;
-    queryTimeoutMs;
-    dialect = getDialectForDriver('bigquery');
+    deadlineMs;
+    dialect = getSqlDialectForDriver('bigquery');
     client = null;
     constructor(options) {
         this.connectionId = options.connectionId;
@@ -159,15 +197,15 @@ export class KtxBigQueryScanConnector {
         this.clientFactory = options.clientFactory ?? new DefaultBigQueryClientFactory();
         this.now = options.now ?? (() => new Date());
         this.maxBytesBilled = options.maxBytesBilled ?? bigQueryMaxBytesBilledFromConnection(options.connection);
-        this.queryTimeoutMs = options.queryTimeoutMs ?? bigQueryJobTimeoutMsFromConnection(options.connection);
+        this.deadlineMs = resolveQueryDeadlineMs(options.connection);
         this.id = `bigquery:${options.connectionId}`;
     }
     async testConnection() {
         try {
             const client = this.getClient();
             await client.getDatasets({ maxResults: 1 });
-            for (const datasetId of this.resolved.datasetIds) {
-                await client.dataset(datasetId).get();
+            for (const ref of this.resolved.datasetIds) {
+                await client.dataset(ref.dataset, ref.project).get();
             }
             return { success: true };
         }
@@ -178,22 +216,23 @@ export class KtxBigQueryScanConnector {
     async introspect(input, _ctx) {
         this.assertConnection(input.connectionId);
         const tables = [];
-        const datasetIds = this.requireDatasetIdsForScan();
+        const datasetRefs = this.requireDatasetIdsForScan();
         const snapshotWarnings = [];
-        for (const datasetId of datasetIds) {
+        for (const ref of datasetRefs) {
             const scopedNames = input.tableScope
-                ? scopedTableNames(input.tableScope, { catalog: this.resolved.projectId, db: datasetId })
+                ? scopedTableNames(input.tableScope, { catalog: ref.project, db: ref.dataset })
                 : null;
-            tables.push(...(await this.introspectDataset(datasetId, scopedNames, snapshotWarnings)));
+            tables.push(...(await this.introspectDataset(ref, scopedNames, snapshotWarnings)));
         }
+        const datasetLabels = datasetRefs.map((ref) => this.qualifiedDatasetLabel(ref));
         return {
             connectionId: this.connectionId,
             driver: 'bigquery',
             extractedAt: this.now().toISOString(),
-            scope: { catalogs: [this.resolved.projectId], datasets: datasetIds },
+            scope: { catalogs: [...new Set(datasetRefs.map((ref) => ref.project))], datasets: datasetLabels },
             metadata: {
                 project_id: this.resolved.projectId,
-                datasets: datasetIds,
+                datasets: datasetLabels,
                 table_count: tables.length,
                 total_columns: tables.reduce((sum, table) => sum + table.columns.length, 0),
             },
@@ -237,11 +276,11 @@ export class KtxBigQueryScanConnector {
         const valueRows = await this.queryRaw(this.dialect.generateDistinctValuesQuery(tableName, quotedColumn, options.limit));
         return { values: valueRows.filter((row) => row.val !== null).map((row) => String(row.val)), cardinality };
     }
-    async getTableRowCount(tableName, datasetId = this.resolved.datasetIds[0]) {
-        if (!datasetId) {
+    async getTableRowCount(tableName, ref = this.resolved.datasetIds[0]) {
+        if (!ref) {
             return 0;
         }
-        const tables = await this.introspectDataset(datasetId, null, []);
+        const tables = await this.introspectDataset(ref, null, []);
         return tables.find((table) => table.name === tableName)?.estimatedRows ?? 0;
     }
     qTableName(table) {
@@ -255,12 +294,27 @@ export class KtxBigQueryScanConnector {
         return datasets.map((dataset) => dataset.id).filter((id) => Boolean(id));
     }
     async listTables(datasetIds) {
-        const projectId = normalizeBigQueryProjectId(this.resolved.projectId, 'table discovery');
         const region = normalizeBigQueryRegion(this.resolved.location ?? 'US', 'table discovery');
+        if (!datasetIds || datasetIds.length === 0) {
+            return this.listTablesInProject(this.resolved.projectId, region);
+        }
+        const datasetsByProject = new Map();
+        for (const entry of datasetIds) {
+            const ref = parseBigQueryDatasetEntry(entry.trim(), this.resolved.projectId, this.connectionId);
+            datasetsByProject.set(ref.project, [...(datasetsByProject.get(ref.project) ?? []), ref.dataset]);
+        }
+        const entries = [];
+        for (const [project, datasets] of datasetsByProject) {
+            entries.push(...(await this.listTablesInProject(project, region, datasets)));
+        }
+        return entries;
+    }
+    async listTablesInProject(project, region, datasets) {
+        const projectId = normalizeBigQueryProjectId(project, 'table discovery');
         const params = {};
-        const filter = datasetIds && datasetIds.length > 0 ? 'AND table_schema IN UNNEST(@dataset_ids)' : '';
-        if (datasetIds && datasetIds.length > 0) {
-            params.dataset_ids = datasetIds;
+        const filter = datasets && datasets.length > 0 ? 'AND table_schema IN UNNEST(@dataset_ids)' : '';
+        if (datasets && datasets.length > 0) {
+            params.dataset_ids = datasets;
         }
         const rows = await this.queryRaw(`
     SELECT table_schema, table_name, table_type
@@ -272,7 +326,7 @@ export class KtxBigQueryScanConnector {
     ORDER BY table_schema, table_name
     `, params);
         return rows.map((row) => ({
-            catalog: this.resolved.projectId,
+            catalog: project,
             schema: row.table_schema,
             name: row.table_name,
             kind: row.table_type === 'VIEW' || row.table_type === 'MATERIALIZED VIEW'
@@ -298,27 +352,41 @@ export class KtxBigQueryScanConnector {
         }
         return this.resolved.datasetIds;
     }
+    // Bare in the billing project, qualified `project.dataset` otherwise, so the
+    // snapshot's scope/metadata stay unambiguous when two projects host the same
+    // dataset name. The dotless form is the unchanged single-project label.
+    qualifiedDatasetLabel(ref) {
+        return ref.project === this.resolved.projectId ? ref.dataset : `${ref.project}.${ref.dataset}`;
+    }
     async query(sql, params) {
-        const [job] = await this.getClient().createQueryJob({
-            query: sql,
-            ...(this.resolved.location ? { location: this.resolved.location } : {}),
-            ...(params && Object.keys(params).length > 0 ? { params } : {}),
-            ...(this.maxBytesBilled ? { maximumBytesBilled: String(this.maxBytesBilled) } : {}),
-            ...(this.queryTimeoutMs ? { jobTimeoutMs: this.queryTimeoutMs } : {}),
-        });
-        const [rows, , response] = await job.getQueryResults();
-        let headers = response?.schema?.fields?.map((field) => field.name || '') ?? [];
-        const headerTypes = response?.schema?.fields?.map((field) => String(field.type || 'STRING')) ?? [];
-        if (headers.length === 0 && rows.length > 0) {
-            headers = Object.keys(rows[0]);
+        try {
+            const [job] = await this.getClient().createQueryJob({
+                query: sql,
+                ...(this.resolved.location ? { location: this.resolved.location } : {}),
+                ...(params && Object.keys(params).length > 0 ? { params } : {}),
+                ...(this.maxBytesBilled ? { maximumBytesBilled: String(this.maxBytesBilled) } : {}),
+                jobTimeoutMs: this.deadlineMs,
+            });
+            const [rows, , response] = await job.getQueryResults();
+            let headers = response?.schema?.fields?.map((field) => field.name || '') ?? [];
+            const headerTypes = response?.schema?.fields?.map((field) => String(field.type || 'STRING')) ?? [];
+            if (headers.length === 0 && rows.length > 0) {
+                headers = Object.keys(rows[0]);
+            }
+            return {
+                headers,
+                headerTypes: headerTypes.length > 0 ? headerTypes : undefined,
+                rows: rows.map((row) => headers.map((header) => normalizeValue(row[header]))),
+                totalRows: rows.length,
+                rowCount: rows.length,
+            };
+        }
+        catch (error) {
+            if (isBigQueryTimeoutError(error)) {
+                throw queryDeadlineExceededError(this.deadlineMs, { cause: error });
+            }
+            throw error;
         }
-        return {
-            headers,
-            headerTypes: headerTypes.length > 0 ? headerTypes : undefined,
-            rows: rows.map((row) => headers.map((header) => normalizeValue(row[header]))),
-            totalRows: rows.length,
-            rowCount: rows.length,
-        };
     }
     async queryRaw(sql, params) {
         const result = await this.query(sql, params);
@@ -328,14 +396,14 @@ export class KtxBigQueryScanConnector {
         const rows = await this.queryRaw(sql);
         return firstNumber(rows[0]?.[header]);
     }
-    async introspectDataset(datasetId, scopedNames, snapshotWarnings) {
+    async introspectDataset(ref, scopedNames, snapshotWarnings) {
         if (scopedNames && scopedNames.length === 0)
             return [];
-        const dataset = this.getClient().dataset(datasetId);
+        const dataset = this.getClient().dataset(ref.dataset, ref.project);
         const [tableRefs] = await dataset.getTables();
         const scopeSet = scopedNames ? new Set(scopedNames) : null;
         const filteredTableRefs = scopeSet ? tableRefs.filter((tableRef) => scopeSet.has(tableRef.id ?? '')) : tableRefs;
-        const primaryKeysResult = await tryConstraintQuery({ schema: datasetId, kind: 'primary_key', isDeniedError }, () => this.primaryKeys(datasetId));
+        const primaryKeysResult = await tryConstraintQuery({ schema: ref.dataset, kind: 'primary_key', isDeniedError }, () => this.primaryKeys(ref));
         const primaryKeys = primaryKeysResult.ok ? primaryKeysResult.value : new Map();
         if (!primaryKeysResult.ok) {
             snapshotWarnings.push(primaryKeysResult.warning);
@@ -343,39 +411,47 @@ export class KtxBigQueryScanConnector {
         const tables = [];
         for (const tableRef of filteredTableRefs) {
             const tableName = tableRef.id || '';
-            const [table] = await tableRef.get();
-            const fields = table.metadata.schema?.fields ?? [];
-            tables.push({
-                catalog: this.resolved.projectId,
-                db: datasetId,
-                name: tableName,
-                kind: tableKind(table.metadata.type),
-                comment: table.metadata.description || null,
-                estimatedRows: firstNumber(table.metadata.numRows) ?? 0,
-                columns: fields.map((field) => this.toSchemaColumn(tableName, field, primaryKeys)),
-                foreignKeys: [],
+            const outcome = await tryIntrospectObject({ object: tableName, catalog: ref.project, db: ref.dataset }, async () => {
+                const [table] = await tableRef.get();
+                const fields = table.metadata.schema?.fields ?? [];
+                return {
+                    catalog: ref.project,
+                    db: ref.dataset,
+                    name: tableName,
+                    kind: tableKind(table.metadata.type),
+                    comment: table.metadata.description || null,
+                    estimatedRows: firstNumber(table.metadata.numRows) ?? 0,
+                    columns: fields.map((field) => this.toSchemaColumn(tableName, field, primaryKeys)),
+                    foreignKeys: [],
+                };
             });
+            if (outcome.ok) {
+                tables.push(outcome.table);
+            }
+            else {
+                snapshotWarnings.push(outcome.warning);
+            }
         }
         return tables;
     }
-    async primaryKeys(datasetId) {
+    async primaryKeys(ref) {
         const rows = await this.queryRaw('SELECT tc.table_name, kcu.column_name ' +
             'FROM `' +
-            this.resolved.projectId +
+            ref.project +
             '.' +
-            datasetId +
+            ref.dataset +
             '.INFORMATION_SCHEMA.TABLE_CONSTRAINTS` tc ' +
             'JOIN `' +
-            this.resolved.projectId +
+            ref.project +
             '.' +
-            datasetId +
+            ref.dataset +
             '.INFORMATION_SCHEMA.KEY_COLUMN_USAGE` kcu ' +
             'ON tc.constraint_name = kcu.constraint_name ' +
             'AND tc.table_schema = kcu.table_schema ' +
             'AND tc.table_name = kcu.table_name ' +
             "WHERE tc.constraint_type = 'PRIMARY KEY' " +
             "AND tc.table_schema = '" +
-            datasetId +
+            ref.dataset +
             "' " +
             "AND NOT REGEXP_CONTAINS(kcu.column_name, r'^(stacksync_record_id|sync_primary_key)_') " +
             'ORDER BY tc.table_name, kcu.ordinal_position');

package/dist/connectors/bigquery/dialect.d.ts

@@ -1,8 +1,8 @@
-import type { KtxDialect } from '../../context/connections/dialects.js';
+import type { KtxSqlDialect } from '../../context/connections/dialects.js';
 import type { KtxSchemaDimensionType, KtxTableRef } from '../../context/scan/types.js';
 type BigQueryTableNameRef = Pick<KtxTableRef, 'name'> & Partial<Pick<KtxTableRef, 'catalog' | 'db'>>;
 /** @internal */
-export declare class KtxBigQueryDialect implements KtxDialect {
+export declare class KtxBigQueryDialect implements KtxSqlDialect {
     readonly type: "bigquery";
     private readonly typeMappings;
     quoteIdentifier(identifier: string): string;

package/dist/connectors/clickhouse/connector.d.ts

@@ -90,6 +90,7 @@ export declare class KtxClickHouseScanConnector implements KtxScanConnector {
     private readonly clientFactory;
     private readonly endpointResolver?;
     private readonly now;
+    private readonly deadlineMs;
     private readonly dialect;
     private client;
     private resolvedEndpoint;

package/dist/connectors/clickhouse/connector.js

@@ -1,5 +1,6 @@
 import { createClient } from '@clickhouse/client';
-import { getDialectForDriver } from '../../context/connections/dialects.js';
+import { getSqlDialectForDriver } from '../../context/connections/dialects.js';
+import { resolveQueryDeadlineMs, queryDeadlineExceededError } from '../../context/connections/query-deadline.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { connectorTestFailure, createKtxConnectorCapabilities } from '../../context/scan/types.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
@@ -17,6 +18,20 @@ function stringConfigValue(connection, key, env) {
 function maybeNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
+// ClickHouse error code 159 = TIMEOUT_EXCEEDED, raised when max_execution_time
+// is hit. The client surfaces it via a numeric/string `code` or a "Code: 159"
+// message prefix depending on transport.
+function isClickHouseTimeoutError(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const code = error.code;
+    if (code === 159 || code === '159') {
+        return true;
+    }
+    const message = error.message;
+    return typeof message === 'string' && (/\bCode:\s*159\b/.test(message) || message.includes('TIMEOUT_EXCEEDED'));
+}
 function parseClickHouseUrl(url) {
     const parsed = new URL(url);
     return {
@@ -126,7 +141,8 @@ export class KtxClickHouseScanConnector {
     clientFactory;
     endpointResolver;
     now;
-    dialect = getDialectForDriver('clickhouse');
+    deadlineMs;
+    dialect = getSqlDialectForDriver('clickhouse');
     client = null;
     resolvedEndpoint = null;
     constructor(options) {
@@ -140,6 +156,7 @@ export class KtxClickHouseScanConnector {
         this.clientFactory = options.clientFactory ?? new DefaultClickHouseClientFactory();
         this.endpointResolver = options.endpointResolver;
         this.now = options.now ?? (() => new Date());
+        this.deadlineMs = resolveQueryDeadlineMs(this.connection);
         this.id = `clickhouse:${options.connectionId}`;
     }
     async testConnection() {
@@ -375,9 +392,13 @@ export class KtxClickHouseScanConnector {
                 username: config.username,
                 password: config.password ?? '',
                 database: config.database,
-                request_timeout: 30_000,
+                // The server aborts at max_execution_time (seconds); request_timeout must
+                // outlast it so the HTTP client receives the code-159 error instead of
+                // giving up first and leaving the query running.
+                request_timeout: this.deadlineMs + 5_000,
                 clickhouse_settings: {
                     output_format_json_quote_64bit_integers: 1,
+                    max_execution_time: Math.ceil(this.deadlineMs / 1000),
                 },
                 ...(isProxied && config.ssl
                     ? {
@@ -402,19 +423,27 @@ export class KtxClickHouseScanConnector {
     }
     async query(sql, params) {
         const client = await this.clientForQuery();
-        const resultSet = await client.query({
-            query: assertReadOnlySql(sql),
-            format: 'JSONCompact',
-            ...(params ? { query_params: params } : {}),
-        });
-        const response = (await resultSet.json());
-        const meta = response.meta ?? [];
-        return {
-            headers: meta.map((field) => field.name),
-            headerTypes: meta.map((field) => field.type),
-            rows: response.data ?? [],
-            totalRows: response.rows ?? response.data?.length ?? 0,
-        };
+        try {
+            const resultSet = await client.query({
+                query: assertReadOnlySql(sql),
+                format: 'JSONCompact',
+                ...(params ? { query_params: params } : {}),
+            });
+            const response = (await resultSet.json());
+            const meta = response.meta ?? [];
+            return {
+                headers: meta.map((field) => field.name),
+                headerTypes: meta.map((field) => field.type),
+                rows: response.data ?? [],
+                totalRows: response.rows ?? response.data?.length ?? 0,
+            };
+        }
+        catch (error) {
+            if (isClickHouseTimeoutError(error)) {
+                throw queryDeadlineExceededError(this.deadlineMs, { cause: error });
+            }
+            throw error;
+        }
     }
     assertConnection(connectionId) {
         if (connectionId !== this.connectionId) {

package/dist/connectors/clickhouse/dialect.d.ts

@@ -1,8 +1,8 @@
-import type { KtxDialect } from '../../context/connections/dialects.js';
+import type { KtxSqlDialect } from '../../context/connections/dialects.js';
 import type { KtxSchemaDimensionType, KtxTableRef } from '../../context/scan/types.js';
 type ClickHouseTableNameRef = Pick<KtxTableRef, 'name'> & Partial<Pick<KtxTableRef, 'catalog' | 'db'>>;
 /** @internal */
-export declare class KtxClickHouseDialect implements KtxDialect {
+export declare class KtxClickHouseDialect implements KtxSqlDialect {
     readonly type: "clickhouse";
     private readonly typeMappings;
     quoteIdentifier(identifier: string): string;

package/dist/connectors/mongodb/connector.d.ts

@@ -0,0 +1,69 @@
+import { type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxConnectorTestResult, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
+import { type KtxMongoDocument } from './schema-inference.js';
+export interface KtxMongoDbConnectionConfig {
+    driver?: string;
+    url?: string;
+    database?: string;
+    databases?: string[];
+    enabled_tables?: string[];
+    sample_size?: number;
+    order_by?: string;
+    [key: string]: unknown;
+}
+export interface KtxMongoListedCollection {
+    name: string;
+    type?: string;
+}
+interface KtxMongoFindOptions {
+    sort: Record<string, 1 | -1>;
+    limit: number;
+    projection?: Record<string, 1>;
+}
+/** Driver-agnostic seam over the `mongodb` client so the connector is unit-testable without a server. */
+export interface KtxMongoClient {
+    listCollections(databaseName: string): Promise<KtxMongoListedCollection[]>;
+    estimatedDocumentCount(databaseName: string, collectionName: string): Promise<number>;
+    find(databaseName: string, collectionName: string, options: KtxMongoFindOptions): Promise<KtxMongoDocument[]>;
+    ping(databaseName: string): Promise<void>;
+    close(): Promise<void>;
+}
+export interface KtxMongoClientFactory {
+    create(url: string): KtxMongoClient;
+}
+export interface KtxMongoDbScanConnectorOptions {
+    connectionId: string;
+    connection: KtxMongoDbConnectionConfig | undefined;
+    clientFactory?: KtxMongoClientFactory;
+    env?: NodeJS.ProcessEnv;
+    now?: () => Date;
+}
+export declare function isKtxMongoDbConnectionConfig(connection: KtxMongoDbConnectionConfig | undefined): connection is KtxMongoDbConnectionConfig;
+export declare class KtxMongoDbScanConnector implements KtxScanConnector {
+    readonly id: string;
+    readonly driver: "mongodb";
+    readonly capabilities: import("../../context/scan/types.js").KtxConnectorCapabilities;
+    private readonly connectionId;
+    private readonly connection;
+    private readonly url;
+    private readonly databases;
+    private readonly sampleSize;
+    private readonly orderBy;
+    private readonly enabledTables;
+    private readonly clientFactory;
+    private readonly now;
+    private readonly dialect;
+    private client;
+    constructor(options: KtxMongoDbScanConnectorOptions);
+    testConnection(): Promise<KtxConnectorTestResult>;
+    introspect(input: KtxScanInput, _ctx: KtxScanContext): Promise<KtxSchemaSnapshot>;
+    private introspectCollection;
+    sampleTable(input: KtxTableSampleInput, _ctx: KtxScanContext): Promise<KtxTableSampleResult>;
+    sampleColumn(input: KtxColumnSampleInput, _ctx: KtxScanContext): Promise<KtxColumnSampleResult>;
+    listSchemas(): Promise<string[]>;
+    listTables(schemas?: string[]): Promise<KtxTableListEntry[]>;
+    cleanup(): Promise<void>;
+    private resolveTableRef;
+    private clientForQuery;
+    private assertConnection;
+}
+export {};