@querypanel/node-sdk 1.0.24 → 1.0.26

package/README.md

@@ -1,323 +1,118 @@
 # QueryPanel Node SDK
 
-A lightweight Node.js client for QueryPanel's NL-to-SQL APIs. The SDK manages JWT auth, exposes helper methods for common endpoints, and provides database adapters with execution, validation, and schema introspection utilities for ClickHouse and Postgres.
+A TypeScript-first client for the QueryPanel Bun/Hono API. It signs JWTs with your service private key, syncs database schemas, enforces tenant isolation, and wraps every public route under `src/routes/` (query, ingest, charts, active charts, and knowledge base).
 
 ## Installation
 
 ```bash
-npm install @querypanel/node-sdk
+bun add @querypanel/sdk
+# or
+npm install @querypanel/sdk
 ```
 
-- Requires **Node 18+**.
-- `@clickhouse/client` is a peer dependency for ClickHouse integrations.
+> **Runtime:** Node.js 18+ (or Bun). The SDK relies on the native `fetch` API.
 
-## Quick start
+## Quickstart
 
 ```ts
-import { QueryPanelSdkAPI } from "@querypanel/node-sdk";
-import { createClient } from "@clickhouse/client";
+import { QueryPanelSdkAPI } from "@querypanel/sdk";
+import { Pool } from "pg";
 
 const qp = new QueryPanelSdkAPI(
   process.env.QUERYPANEL_URL!,
-  process.env.QUERYPANEL_SERVICE_TOKEN!,
-  process.env.PRIVATE_KEY!
-);
-
-// Attach a ClickHouse database (use the SDK-supplied adapter)
-const clickhouse = createClient({
-  url: process.env.CLICKHOUSE_URL!,
-  username: process.env.CLICKHOUSE_USER,
-  password: process.env.CLICKHOUSE_PASSWORD,
-  database: "analytics",
-});
-
-qp.attachClickhouse(
-  "analytics",
-  (params) => clickhouse.query(params),
+  process.env.PRIVATE_KEY!,
+  process.env.ORGANIZATION_ID!,
   {
-    database: "analytics",
-    tenantFieldName: "customer_id",     // Enable tenant isolation
-    tenantFieldType: "String",          // ClickHouse type
+    defaultTenantId: process.env.DEFAULT_TENANT_ID,
   },
 );
 
-// Ask a question - tenant isolation is automatic
-const response = await qp.ask("Top countries by revenue", { tenantId: "tenant_123" });
-console.log(response.sql);    // Includes WHERE customer_id = {customer_id:String}
-console.log(response.params); // { customer_id: "tenant_123", ... }
-console.table(response.rows);
-```
-
-## Authentication modes
-
-The constructor accepts a private key/organization pair for on-the-fly token generation:
-
-```ts
-
-// provide an RSA private key and organization ID (recommended)
-// and save the public key on the querypanel ui
-const qp = new QueryPanelSdkAPI(baseUrl, privateKeyPem, organizationId);
-```
-
-## V3 Bedrock Integration
-
-The SDK provides methods to generate schema exports compatible with AWS Bedrock knowledge bases:
-
-### introspectV3
-
-Generate a simplified schema export format suitable for Bedrock ingestion:
-
-```ts
-const schema = await qp.introspectV3("analytics", {
-  tenantId: "tenant-123",
-  tables: ["orders", "customers"], // Optional: filter specific tables
-});
-
-// Output matches schema_export.json format
-console.log(JSON.stringify(schema, null, 2));
-```
-
-### ingestSchemaV3
+const pool = new Pool({ connectionString: process.env.POSTGRES_URL });
 
-Introspect and ingest directly to Bedrock knowledge base:
-
-```ts
-const result = await qp.ingestSchemaV3("analytics", {
-  tenantId: "tenant-123",
-  tables: ["orders", "customers"], // Optional
-});
-
-console.log(`Ingested ${result.total_documents} documents`);
-console.log(`Failed: ${result.failed.length}`);
-```
-
-The V3 format includes:
-- Table overviews with column summaries and statistics
-- Individual column metadata documents
-- Foreign key relationships
-- Primary key indicators
-
-This data powers the Bedrock-backed `/v3/generate-sql` endpoint using Claude Haiku 4.5.
-
-## Working with databases
-
-Adapters mediate between the SDK and your data sources. Two helpers are bundled:
-
-### ClickHouse
-
-```ts
-import {
-  ClickHouseAdapter,
-  type ClickHouseClientFn,
-} from "@querypanel/node-sdk";
-import { createClient } from "@clickhouse/client";
-
-const clickhouseClient = createClient({ url: "https://ch.example.com", database: "analytics" });
-const clickhouseFn: ClickHouseClientFn = (params) => clickhouseClient.query(params);
-const clickhouseAdapter = new ClickHouseAdapter(clickhouseFn, { database: "analytics" });
-
-// Optional introspection before attaching
-const schema = await clickhouseAdapter.introspect();
-console.log(schema.tables.map((t) => t.name));
-
-qp.attachDatabase("analytics", clickhouseAdapter);
-```
-
-### Postgres
-
-```ts
-import { Pool } from "pg";
-import {
-  PostgresAdapter,
-  type PostgresClientFn,
-} from "@querypanel/node-sdk";
-
-const pool = new Pool({ connectionString: process.env.DATABASE_URL });
-const pgFn: PostgresClientFn = async (sql) => {
+const createPostgresClient = () => async (sql: string, params?: unknown[]) => {
   const client = await pool.connect();
   try {
-    const result = await client.query(sql);
+    const result = await client.query(sql, params);
     return {
       rows: result.rows,
-      fields: result.fields.map((f) => ({ name: f.name })),
+      fields: result.fields.map((field) => ({ name: field.name })),
     };
   } finally {
     client.release();
   }
 };
 
-const pgAdapter = new PostgresAdapter(pgFn, {
-  database: "app",
-  defaultSchema: "public",
+qp.attachPostgres("analytics", createPostgresClient(), {
+  description: "Primary analytics warehouse",
+  tenantFieldName: "tenant_id",
 });
 
-await pgAdapter.introspect({ tables: ["public.users"] });
-qp.attachDatabase("app", pgAdapter);
-```
-
-Adapters expose three core methods:
-
-- `execute(sql)` – runs the query and returns `{ fields, rows }`.
-- `validate(sql)` – runs an `EXPLAIN` to verify syntax before execution.
-- `introspect(options?)` – returns structured schema metadata (`SchemaIntrospection`).
-
-## SDK helpers
-
-Once at least one adapter is attached you can call:
-
-- `ask(question, options)` – generate SQL, validate it, execute through the adapter, and retrieve a matching Vega-Lite chart spec.
-- `train(payload, { tenantId, userId, scopes })` – submit curated glossary entries, metric docs, and gold SQL examples.
-- `stats({ tenantId, userId, scopes })` – fetch ingestion statistics.
-- Chart helpers: `listCharts`, `getChart`, `createChart`, `updateChart`, `deleteChart`, `listActiveCharts`, `getActiveChart`, `createActiveChart`, `updateActiveChart`, `deleteActiveChart`.
-
-Every SDK call automatically attaches the correct authentication headers and forwards optional `tenantId`, `userId`, and `scopes` when provided.
-
-### Using V3 SQL generation
+qp.attachClickhouse(
+  "clicks",
+  (params) => clickhouse.query(params),
+  {
+    database: "analytics",
+    tenantFieldName: "customer_id",
+    tenantFieldType: "String",
+  },
+);
 
-By default, `ask()` uses the `/v2/generate-sql` endpoint (OpenAI + pgvector). To use the Bedrock-powered `/v3/generate-sql` endpoint (Claude Haiku 4.5), set `useV3: true`:
+await qp.syncSchema("analytics", { tenantId: "tenant_123" });
 
-```ts
 const response = await qp.ask("Top countries by revenue", {
   tenantId: "tenant_123",
-  useV3: true, // Use Bedrock + Claude instead of OpenAI
-});
-```
-
-**Important**: The `useV3` flag controls both:
-1. **SQL generation endpoint**: Uses `/v3/generate-sql` instead of `/v2/generate-sql`
-2. **Schema introspection**: On first use, auto-syncs schema via `/v3/ingest` (Bedrock knowledge base) instead of `/v2/vectorize-schema` (pgvector)
-
-Both endpoints support the same request/response format, making migration seamless.
-
-### Manual sync control
-
-By default, the SDK automatically syncs your database schema on the first `ask()` call. You can disable this and sync manually:
-
-```ts
-// Manual sync workflow
-await qp.ingestSchemaV3("analytics", {
-  tenantId: "tenant_123",
-  tables: ["orders", "customers"], // Optional: sync specific tables
-});
-
-// Now ask questions with auto-sync disabled
-const response = await qp.ask("Top revenue by country", {
-  tenantId: "tenant_123",
-  useV3: true,
-  disableAutoSync: true, // ⚠️ Requires manual sync first
-});
-```
-
-**Why disable auto-sync?**
-- 🎯 Control when schema updates happen
-- ⚡ Faster `ask()` calls (no sync overhead)
-- 💰 Reduce API calls to Bedrock
-- 🔧 Better for production deployments (sync on app startup, not on every request)
-
-**Recommended pattern for production:**
-
-```ts
-// On app startup (once)
-await qp.ingestSchemaV3("analytics", { tenantId: "..." });
-
-// In request handlers (many times)
-app.post("/query", async (req, res) => {
-  const result = await qp.ask(req.body.question, {
-    tenantId: req.user.tenantId,
-    useV3: true,
-    disableAutoSync: true, // Already synced at startup
-  });
-  res.json(result);
-});
-```
-
-## Multi-database support
-
-The SDK keeps a registry of adapters. The first attached database becomes the default, but you can switch per request:
-
-```ts
-qp.attachPostgres("users", pgFn, { database: "users" });
-qp.attachClickhouse("analytics", clickhouseFn);
-
-await qp.ask("Top spenders", {
-  tenantId: "tenant_123",
-  database: "analytics", // override default database for this request
+  database: "analytics",
 });
-```
-
-The `available_databases` array is forwarded to the `/v2/generate-sql` endpoint so the service can pick the right dialect when it suggests queries.
-
-## Schema introspection
-
-Both adapters can produce consistent metadata that matches `node-sdk/src/schema/types.ts`:
 
-```ts
-const snapshot = await pgAdapter.introspect({ tables: ["public.orders"] });
-for (const table of snapshot.tables) {
-  console.log(table.name, table.columns.length);
-}
+console.log(response.sql);
+console.log(response.params);
+console.table(response.rows);
+console.log(response.chart.vegaLiteSpec);
 ```
 
-Use introspection to feed the training endpoint or to drive documentation for the AI planner.
-
-## Local introspection script
-
-Test V3 introspection locally without calling the API:
+## Building locally
 
 ```bash
-# Quick start
-npm run introspect:local
-
-# With custom database
-CLICKHOUSE_URL=http://localhost:8123 \
-CLICKHOUSE_DATABASE=analytics \
-TENANT_ID=my-tenant \
-npm run introspect:local
-
-# Filter specific tables
-TABLES="orders,customers" npm run introspect:local
+cd node-sdk
+bun install
+bun run build
 ```
 
-This generates `schema_export.json` that you can:
-1. Review locally before ingestion
-2. Upload manually via `/v3/ingest`
-3. Use for testing and CI/CD
+This runs `tsup` which emits dual ESM/CJS bundles plus type declarations to `dist/`.
 
-See `node-sdk/scripts/README.md` for full documentation.
+## Authentication model
 
-## Testing and building
+Every request is signed with `RS256` using the private key you pass to the constructor. The payload always includes `organizationId` and `tenantId`; `userId` and `scopes` are added when provided per call. If you still need service tokens or custom middleware, pass additional headers via the constructor.
 
-```bash
-# run unit tests
-npm --prefix node-sdk test
+## Error handling
 
-# build CommonJS and ESM artifacts
-npm --prefix node-sdk run build
-```
-
-## Tenant Isolation
+- HTTP errors propagate as thrown `Error` instances that include `status` (and `details` when available).
+- Schema ingestion failures are logged to `console.warn` during auto-sync, but you can call `syncSchema(..., { force: true })` to surface them directly.
+- `ask()` raises immediately for guardrail/moderation errors because `/query` responds with 4xx/5xx.
 
-The SDK provides automatic tenant isolation enforcement to prevent data leaks in multi-tenant environments. When configured, the SDK will automatically:
+### Automatic SQL repair and retry
 
-- ✅ Inject tenant parameters into all queries
-- ✅ Validate that generated SQL includes tenant filters
-- ✅ Auto-fix SQL missing tenant isolation by adding WHERE clauses
-- ✅ Support ClickHouse typed parameters (`{customer_id:String}`)
+When SQL execution fails (e.g., invalid column name, syntax error), the SDK can automatically retry with a repaired query:
 
-```typescript
-sdk.attachClickhouse('analytics', clickhouseFn, {
-  tenantFieldName: 'customer_id',      // Required field in your schema
-  tenantFieldType: 'String',           // ClickHouse type (String, UUID, Int64, etc.)
-  enforceTenantIsolation: true,        // Default: true (auto-fix missing filters)
+```ts
+const response = await qp.ask("Show revenue by country", {
+  tenantId: "tenant_123",
+  maxRetry: 3,  // Automatically retry up to 3 times on execution error
 });
+
+console.log(`Query succeeded after ${response.attempts} attempt(s)`);
+console.table(response.rows);
 ```
 
-See [TENANT_ISOLATION.md](./TENANT_ISOLATION.md) for complete documentation.
+The SDK will:
+1. Execute the generated SQL
+2. If execution fails, send the error back to the server with the failed SQL
+3. Get a repaired SQL query from the server
+4. Execute the repaired query
+5. Repeat up to `maxRetry` times
 
-## Additional resources
+Without `maxRetry`, execution errors throw immediately (default behavior).
 
-- `TENANT_ISOLATION.md` – Complete guide to automatic tenant isolation enforcement
-- `SDK-API.md` – REST endpoint reference used by the SDK
-- `MULTI_DATABASE.md` – Notes on attaching multiple adapters
+## Need more?
 
-If you hit an integration bug or need support for an additional database engine, open an issue or reach out to the QueryPanel team.
+Open an issue or extend `node-sdk/src/index.ts`—every route lives in one file. Pull requests are welcome for additional adapters, richer param coercion, or convenience helpers around charts/annotations.

package/dist/cjs/__tests__/ingest.test.d.ts

@@ -0,0 +1,5 @@
+declare global {
+    var fetch: typeof globalThis.fetch;
+}
+export {};
+//# sourceMappingURL=ingest.test.d.ts.map

package/dist/cjs/__tests__/ingest.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/ingest.test.ts"],"names":[],"mappings":"AAKA,OAAO,CAAC,MAAM,CAAC;IAEX,IAAI,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACtC"}

package/dist/cjs/__tests__/ingest.test.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const index_js_1 = require("../index.js");
+const noop = () => { };
+class StubConnector {
+    constructor(introspection) {
+        this.introspection = introspection;
+        this.connect = vitest_1.vi.fn(async () => { });
+        this.close = vitest_1.vi.fn(async () => { });
+        this.executeQuery = vitest_1.vi.fn(async () => []);
+        this.introspect = vitest_1.vi.fn(async (_options) => this.introspection);
+    }
+}
+(0, vitest_1.describe)('Ingestion API', () => {
+    const originalFetch = globalThis.fetch;
+    const fakeResponse = {
+        ok: true,
+        status: 200,
+        text: async () => JSON.stringify({ message: 'ok', ingestedTables: 1 }),
+    };
+    let fetchMock;
+    (0, vitest_1.beforeEach)(() => {
+        fetchMock = vitest_1.vi.fn().mockResolvedValue(fakeResponse);
+        globalThis.fetch = fetchMock;
+    });
+    (0, vitest_1.afterEach)(() => {
+        fetchMock.mockReset();
+        if (originalFetch) {
+            globalThis.fetch = originalFetch;
+        }
+        else {
+            delete globalThis.fetch;
+        }
+    });
+    (0, vitest_1.it)('posts schema introspection payloads with merged metadata', async () => {
+        const sdk = new index_js_1.QueryPanelSdkAPI('https://example.com', 'token');
+        const introspection = {
+            db: { kind: 'clickhouse', name: 'analytics' },
+            tables: [],
+            introspectedAt: new Date().toISOString(),
+            metadata: { existing: true },
+        };
+        const response = await sdk.ingestSchema(introspection, {
+            tenantId: 'tenant-1',
+            metadata: { triggeredBy: 'test' },
+        });
+        (0, vitest_1.expect)(response).toMatchObject({ message: 'ok', ingestedTables: 1 });
+        (0, vitest_1.expect)(fetchMock).toHaveBeenCalledTimes(1);
+        const [url, init] = fetchMock.mock.calls[0];
+        (0, vitest_1.expect)(url).toBe('https://example.com/ingest/schema');
+        (0, vitest_1.expect)(init.method).toBe('POST');
+        (0, vitest_1.expect)(init.headers).toMatchObject({
+            Authorization: 'Bearer token',
+            'Content-Type': 'application/json',
+        });
+        const body = JSON.parse(init.body);
+        (0, vitest_1.expect)(body.metadata).toEqual({ existing: true, triggeredBy: 'test' });
+    });
+    (0, vitest_1.it)('introspects via connector and closes connections by default', async () => {
+        const sdk = new index_js_1.QueryPanelSdkAPI('https://example.com', 'token');
+        const introspection = {
+            db: { kind: 'clickhouse', name: 'analytics' },
+            tables: [],
+            introspectedAt: new Date().toISOString(),
+        };
+        const connector = new StubConnector(introspection);
+        const response = await sdk.introspectAndIngest(connector, {
+            tenantId: 'tenant-1',
+            metadata: { flow: 'batch' },
+            tables: ['events'],
+        });
+        (0, vitest_1.expect)(response.message).toBe('ok');
+        (0, vitest_1.expect)(connector.connect).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(connector.introspect).toHaveBeenCalledWith({ tables: ['events'] });
+        (0, vitest_1.expect)(connector.close).toHaveBeenCalledTimes(1);
+        const [, init] = fetchMock.mock.calls[0];
+        const body = JSON.parse(init.body);
+        (0, vitest_1.expect)(body.metadata).toEqual({ flow: 'batch' });
+    });
+    (0, vitest_1.it)('respects keepConnectionOpen option', async () => {
+        const sdk = new index_js_1.QueryPanelSdkAPI('https://example.com', 'token');
+        const connector = new StubConnector({
+            db: { kind: 'clickhouse', name: 'analytics' },
+            tables: [],
+            introspectedAt: new Date().toISOString(),
+        });
+        await sdk.introspectAndIngest(connector, {
+            tenantId: 'tenant-1',
+            keepConnectionOpen: true,
+        });
+        (0, vitest_1.expect)(connector.close).not.toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=ingest.test.js.map

package/dist/cjs/__tests__/ingest.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.test.js","sourceRoot":"","sources":["../../../src/__tests__/ingest.test.ts"],"names":[],"mappings":"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"}

package/dist/cjs/connectors/__tests__/clickhouse.introspect.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=clickhouse.introspect.test.d.ts.map

package/dist/cjs/connectors/__tests__/clickhouse.introspect.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clickhouse.introspect.test.d.ts","sourceRoot":"","sources":["../../../../src/connectors/__tests__/clickhouse.introspect.test.ts"],"names":[],"mappings":""}

package/dist/cjs/connectors/__tests__/clickhouse.introspect.test.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const clickhouse_js_1 = require("../clickhouse.js");
+class StubResultSet {
+    constructor(payload) {
+        this.payload = payload;
+    }
+    async json() {
+        return this.payload;
+    }
+}
+class StubClickHouseClient {
+    constructor(responses) {
+        this.queries = [];
+        this.responses = responses;
+    }
+    async query(params) {
+        this.queries.push({ query: params.query, params: params.query_params });
+        const responseKey = params.query.includes('system.tables') ? 'tables' : 'columns';
+        const payload = this.responses.get(responseKey);
+        if (!payload) {
+            throw new Error(`No stub response registered for ${responseKey}`);
+        }
+        return new StubResultSet(payload);
+    }
+    async ping() {
+        return { success: true };
+    }
+    async close() { }
+}
+(0, vitest_1.describe)('ClickHouseConnector', () => {
+    (0, vitest_1.it)('introspects tables with large column counts', async () => {
+        const tableRows = [
+            {
+                name: 'events',
+                engine: 'MergeTree',
+                comment: 'User event stream',
+                total_rows: '424242',
+                total_bytes: '1024',
+                is_view: 0,
+                primary_key: 'tuple(event_id, occurred_at)',
+                sorting_key: 'tuple(occurred_at)',
+            },
+        ];
+        const columnRows = Array.from({ length: 120 }, (_, index) => ({
+            table: 'events',
+            name: `column_${index}`,
+            type: index % 2 === 0 ? 'Nullable(String)' : 'UInt32',
+            position: index + 1,
+            default_kind: index % 10 === 0 ? 'DEFAULT' : null,
+            default_expression: index % 10 === 0 ? `'value_${index}'` : null,
+            comment: index % 15 === 0 ? `Column ${index}` : null,
+            codec_expression: index % 20 === 0 ? 'ZSTD(3)' : null,
+            ttl_expression: null,
+            is_in_primary_key: index === 0 ? 1 : 0,
+            data_compressed_bytes: '128',
+            data_uncompressed_bytes: '256',
+        }));
+        const responses = new Map([
+            ['tables', tableRows],
+            ['columns', columnRows],
+        ]);
+        const stubClient = new StubClickHouseClient(responses);
+        const connector = new clickhouse_js_1.ClickHouseConnector({
+            database: 'analytics',
+        }, { client: stubClient });
+        const introspection = await connector.introspect();
+        (0, vitest_1.expect)(introspection.db).toEqual({ kind: 'clickhouse', name: 'analytics' });
+        (0, vitest_1.expect)(introspection.tables).toHaveLength(1);
+        const [table] = introspection.tables;
+        (0, vitest_1.expect)(table.name).toBe('events');
+        (0, vitest_1.expect)(table.columns).toHaveLength(120);
+        (0, vitest_1.expect)(table.columns[0]).toMatchObject({
+            name: 'column_0',
+            nullable: true,
+            type: 'String',
+            rawType: 'Nullable(String)',
+            defaultKind: 'DEFAULT',
+            defaultExpression: `'value_0'`,
+            statistics: { compressedBytes: 128, uncompressedBytes: 256 },
+        });
+        (0, vitest_1.expect)(table.columns.at(-1)).toMatchObject({
+            nullable: false,
+            type: 'UInt32',
+        });
+        (0, vitest_1.expect)(table.statistics).toEqual({ totalRows: 424242, totalBytes: 1024 });
+        (0, vitest_1.expect)(table.indexes).toEqual([
+            {
+                name: 'primary_key',
+                columns: ['event_id', 'occurred_at'],
+                unique: true,
+                type: 'PRIMARY KEY',
+                definition: 'tuple(event_id, occurred_at)',
+            },
+        ]);
+        (0, vitest_1.expect)(table.constraints[0]).toMatchObject({
+            type: 'PRIMARY KEY',
+            columns: ['event_id', 'occurred_at'],
+        });
+        (0, vitest_1.expect)(new Date(introspection.introspectedAt).toISOString()).toBe(introspection.introspectedAt);
+        (0, vitest_1.expect)(stubClient.queries).toHaveLength(2);
+        (0, vitest_1.expect)(stubClient.queries[0].params).toEqual({ db: 'analytics' });
+    });
+    (0, vitest_1.it)('applies table filters when provided', async () => {
+        const responses = new Map([
+            ['tables', [{ name: 'events', engine: 'MergeTree', is_view: 0 }]],
+            ['columns', [{ table: 'events', name: 'column_1', type: 'UInt64', position: 1 }]],
+        ]);
+        const stubClient = new StubClickHouseClient(responses);
+        const connector = new clickhouse_js_1.ClickHouseConnector({ database: 'analytics' }, { client: stubClient });
+        await connector.introspect({ tables: ['analytics.events', 'events'] });
+        (0, vitest_1.expect)(stubClient.queries).toHaveLength(2);
+        for (const query of stubClient.queries) {
+            (0, vitest_1.expect)(query.params).toEqual({ db: 'analytics', tables: ['events'] });
+        }
+    });
+});
+//# sourceMappingURL=clickhouse.introspect.test.js.map

package/dist/cjs/connectors/__tests__/clickhouse.introspect.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clickhouse.introspect.test.js","sourceRoot":"","sources":["../../../../src/connectors/__tests__/clickhouse.introspect.test.ts"],"names":[],"mappings":"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"}

package/dist/cjs/connectors/base.d.ts

@@ -1,13 +1,12 @@
-import type { DataFormat } from '@clickhouse/client';
 import type { IntrospectOptions, SchemaIntrospection } from '../schema/types.js';
 export interface QueryOptions {
     params?: Record<string, unknown>;
-    format?: DataFormat;
+    format?: string;
     settings?: Record<string, unknown>;
 }
 export interface DatabaseConnector {
     connect(): Promise<void>;
-    query<T = Record<string, unknown>>(sql: string, options?: QueryOptions): Promise<T[]>;
+    executeQuery<T = Record<string, unknown>>(query: string, options?: QueryOptions): Promise<T[]>;
     introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
     close(): Promise<void>;
 }