@querypanel/node-sdk 1.3.3 → 1.3.6

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   QueryErrorCode: () => QueryErrorCode,
   QueryPanelSdkAPI: () => QueryPanelSdkAPI,
   QueryPipelineError: () => QueryPipelineError,
+  SchemaTooLargeError: () => SchemaTooLargeError,
   anonymizeResults: () => anonymizeResults,
   mapGeneratedParams: () => mapGeneratedParams,
   normalizeSqlParamsInput: () => normalizeSqlParamsInput,
@@ -45,6 +46,16 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/adapters/types.ts
+var DEFAULT_CATALOG_LIMIT = 500;
+var MAX_CATALOG_LIMIT = 5e3;
+function resolveCatalogLimit(limit) {
+  if (limit === void 0 || !Number.isFinite(limit)) {
+    return DEFAULT_CATALOG_LIMIT;
+  }
+  return Math.min(Math.max(Math.floor(limit), 1), MAX_CATALOG_LIMIT);
+}
+
 // src/adapters/bigquery.ts
 var BigQueryAdapter = class {
   constructor(clientFn, options) {
@@ -153,6 +164,53 @@ var BigQueryAdapter = class {
       introspectedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
   }
+  /** The adapter is bound to one dataset, so this returns a single row. */
+  async listSchemas() {
+    const result = await this.clientFn({
+      query: `SELECT COUNT(*) AS table_count
+  FROM ${this.informationSchema("TABLES")}`,
+      dryRun: false
+    });
+    return [
+      {
+        schema: this.defaultDataset,
+        tableCount: Number(result.rows[0]?.table_count ?? 0)
+      }
+    ];
+  }
+  /**
+   * List tables in the bound dataset. Reads the full catalog (not restricted
+   * by `allowedTables`). Default limit 500, max 5000.
+   */
+  async listTables(options = {}) {
+    if (options.schema && options.schema !== this.defaultDataset) {
+      return [];
+    }
+    const search = options.search?.trim();
+    const params = {};
+    let searchClause = "";
+    if (search) {
+      params.search = `%${search.toLowerCase().replace(/[\\%_]/g, (ch) => `\\${ch}`)}%`;
+      searchClause = "\n  WHERE LOWER(table_name) LIKE @search";
+    }
+    const limit = resolveCatalogLimit(options.limit);
+    const result = await this.clientFn({
+      query: `SELECT table_schema, table_name, table_type
+  FROM ${this.informationSchema("TABLES")}${searchClause}
+  ORDER BY table_name
+  LIMIT ${limit}`,
+      ...search ? { params } : {},
+      dryRun: false
+    });
+    return result.rows.map((row) => ({
+      schema: row.table_schema,
+      name: row.table_name,
+      type: asTableType(row.table_type)
+    }));
+  }
+  informationSchema(view) {
+    return `\`${this.datasetProjectId}.${this.defaultDataset}.INFORMATION_SCHEMA.${view}\``;
+  }
   validateQueryTables(sql) {
     if (!this.allowedTables || this.allowedTables.length === 0) {
       return;
@@ -183,8 +241,10 @@ function normalizeTableFilter(tables, defaultDataset) {
   for (const raw of tables) {
     if (!raw?.trim()) continue;
     const trimmed = raw.trim();
+    if (trimmed === "*" || trimmed === `${defaultDataset}.*`) return [];
     const parts = trimmed.split(".");
     const table = parts.pop() ?? "";
+    if (table === "*") continue;
     const dataset = parts.pop() ?? defaultDataset;
     const key = tableKey(dataset, table);
     if (seen.has(key)) continue;
@@ -295,7 +355,10 @@ var ClickHouseAdapter = class {
     this.defaultFormat = options.defaultFormat ?? "JSONEachRow";
     this.kind = options.kind ?? "clickhouse";
     if (options.allowedTables) {
-      this.allowedTables = normalizeTableFilter2(options.allowedTables);
+      this.allowedTables = normalizeTableFilter2(
+        options.allowedTables,
+        this.databaseName
+      );
     }
   }
   clientFn;
@@ -334,7 +397,7 @@ var ClickHouseAdapter = class {
    * No indexes, constraints, or statistics
    */
   async introspect(options) {
-    const tablesToIntrospect = options?.tables ? normalizeTableFilter2(options.tables) : this.allowedTables;
+    const tablesToIntrospect = options?.tables ? normalizeTableFilter2(options.tables, this.databaseName) : this.allowedTables;
     const allowTables = tablesToIntrospect ?? [];
     const hasFilter = allowTables.length > 0;
     const queryParams = {
@@ -392,6 +455,53 @@ var ClickHouseAdapter = class {
       introspectedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
   }
+  /** The adapter is bound to one database, so this returns a single row. */
+  async listSchemas() {
+    const rows = await this.query(
+      `SELECT count() AS table_count
+       FROM system.tables
+       WHERE database = {db:String}`,
+      { params: { db: this.databaseName } }
+    );
+    return [
+      {
+        schema: this.databaseName,
+        tableCount: toNumber(rows[0]?.table_count) ?? 0
+      }
+    ];
+  }
+  /**
+   * List tables in the bound database. Reads the full catalog (not restricted
+   * by `allowedTables`). Default limit 500, max 5000.
+   */
+  async listTables(options = {}) {
+    if (options.schema && options.schema !== this.databaseName) {
+      return [];
+    }
+    const params = {
+      db: this.databaseName,
+      limit: resolveCatalogLimit(options.limit)
+    };
+    const search = options.search?.trim();
+    let searchClause = "";
+    if (search) {
+      params.search = search;
+      searchClause = " AND positionCaseInsensitive(name, {search:String}) > 0";
+    }
+    const rows = await this.query(
+      `SELECT name, engine
+       FROM system.tables
+       WHERE database = {db:String}${searchClause}
+       ORDER BY name
+       LIMIT {limit:UInt32}`,
+      { params }
+    );
+    return rows.map((row) => ({
+      schema: this.databaseName,
+      name: row.name,
+      type: asCatalogTableType(row.engine)
+    }));
+  }
   validateQueryTables(sql) {
     if (!this.allowedTables || this.allowedTables.length === 0) {
       return;
@@ -457,7 +567,7 @@ function normalizePayload(payload) {
   }
   return [];
 }
-function normalizeTableFilter2(tables) {
+function normalizeTableFilter2(tables, databaseName) {
   if (!tables?.length) return [];
   const seen = /* @__PURE__ */ new Set();
   const normalized = [];
@@ -465,8 +575,10 @@ function normalizeTableFilter2(tables) {
     if (!table) continue;
     const trimmed = table.trim();
     if (!trimmed) continue;
+    if (trimmed === "*" || trimmed === `${databaseName}.*`) return [];
     const parts = trimmed.split(".");
     const tableName = parts[parts.length - 1];
+    if (tableName === "*") continue;
     if (!tableName || seen.has(tableName)) continue;
     seen.add(tableName);
     normalized.push(tableName);
@@ -499,6 +611,12 @@ function asTableType2(engine) {
   }
   return "table";
 }
+function asCatalogTableType(engine) {
+  const normalized = typeof engine === "string" ? engine.toLowerCase() : "";
+  if (normalized === "materializedview") return "materialized_view";
+  if (normalized.includes("view")) return "view";
+  return "table";
+}
 function sanitize(value) {
   if (value === null || value === void 0) return void 0;
   const trimmed = String(value).trim();
@@ -512,6 +630,7 @@ function toNumber(value) {
 }
 
 // src/adapters/postgres.ts
+var WILDCARD = "*";
 function maxPostgresPlaceholderIndex(sql) {
   let max = 0;
   for (const match of sql.matchAll(/\$(\d+)\b/g)) {
@@ -548,7 +667,8 @@ var PostgresAdapter = class {
     this.clientFn = clientFn;
     this.databaseName = options.database ?? "postgres";
     this.defaultSchema = options.defaultSchema ?? "public";
-    this.kind = options.kind ?? "postgres";
+    this.dialect = options.dialect ?? "postgres";
+    this.kind = options.kind ?? this.dialect;
     if (options.allowedTables) {
       this.allowedTables = normalizeTableFilter3(
         options.allowedTables,
@@ -560,6 +680,7 @@ var PostgresAdapter = class {
   databaseName;
   defaultSchema;
   kind;
+  dialect;
   allowedTables;
   async execute(sql, params) {
     if (this.allowedTables) {
@@ -581,6 +702,9 @@ var PostgresAdapter = class {
     const allowedSet = new Set(
       this.allowedTables.map((t) => tableKey2(t.schema, t.table))
     );
+    const allowedSchemas = new Set(
+      this.allowedTables.filter((t) => t.table === WILDCARD).map((t) => t.schema)
+    );
     const neutralizedSql = sql.replace(/EXTRACT\s*\([^)]*FROM\s+[^)]+\)/gi, "EXTRACT(/*neutralized*/)").replace(/SUBSTRING\s*\([^)]*FROM\s+[^)]+\)/gi, "SUBSTRING(/*neutralized*/)").replace(/TRIM\s*\([^)]*FROM\s+[^)]+\)/gi, "TRIM(/*neutralized*/)").replace(/POSITION\s*\([^)]*FROM\s+[^)]+\)/gi, "POSITION(/*neutralized*/)");
     const tablePattern = /(?:FROM|JOIN)\s+(?:ONLY\s+)?(?:([a-zA-Z_][a-zA-Z0-9_]*)\.)?(["']?[a-zA-Z_][a-zA-Z0-9_]*["']?)/gi;
     const matches = neutralizedSql.matchAll(tablePattern);
@@ -589,7 +713,7 @@ var PostgresAdapter = class {
       const table = match[2]?.replace(/['"]/g, "");
       if (table) {
         const key = tableKey2(schema, table);
-        if (!allowedSet.has(key)) {
+        if (!allowedSet.has(key) && !allowedSchemas.has(schema)) {
           throw new Error(
             `Query references table "${schema}.${table}" which is not in the allowed tables list`
           );
@@ -639,7 +763,34 @@ var PostgresAdapter = class {
     await this.clientFn(`EXPLAIN ${sql}`, paramArray);
   }
   getDialect() {
-    return "postgres";
+    return this.dialect;
+  }
+  /**
+   * List schemas with their table/view counts. Reads the full catalog (not
+   * restricted by `allowedTables`) so it can back an allowed-tables picker.
+   */
+  async listSchemas() {
+    const result = await this.clientFn(
+      this.dialect === "redshift" ? buildRedshiftListSchemasQuery() : buildListSchemasQuery()
+    );
+    return result.rows.map((row) => ({
+      schema: String(row.schema),
+      tableCount: Number(row.table_count ?? 0)
+    }));
+  }
+  /**
+   * List tables/views, optionally filtered by schema and a case-insensitive
+   * substring of the table name. Reads the full catalog (not restricted by
+   * `allowedTables`). Default limit 500, max 5000.
+   */
+  async listTables(options = {}) {
+    const { sql, params } = buildListTablesQuery(this.dialect, options);
+    const result = await this.clientFn(sql, params);
+    return result.rows.map((row) => ({
+      schema: String(row.schema),
+      name: String(row.name),
+      type: asTableType3(String(row.table_type ?? ""))
+    }));
   }
   /**
    * Simplified introspection: only collect table/column metadata for IngestRequest
@@ -648,12 +799,13 @@ var PostgresAdapter = class {
   async introspect(options) {
     const tablesToIntrospect = options?.tables ? normalizeTableFilter3(options.tables, this.defaultSchema) : this.allowedTables;
     const normalizedTables = tablesToIntrospect ?? [];
+    const isRedshift = this.dialect === "redshift";
     const tablesResult = await this.clientFn(
-      buildTablesQuery2(normalizedTables)
+      isRedshift ? buildRedshiftTablesQuery(normalizedTables) : buildTablesQuery2(normalizedTables)
     );
     const tableRows = tablesResult.rows;
     const columnsResult = await this.clientFn(
-      buildColumnsQuery2(normalizedTables)
+      isRedshift ? buildRedshiftColumnsQuery(normalizedTables) : buildColumnsQuery2(normalizedTables)
     );
     const columnRows = columnsResult.rows;
     const tablesByKey = /* @__PURE__ */ new Map();
@@ -713,7 +865,7 @@ function normalizeTableFilter3(tables, defaultSchema) {
     const parts = trimmed.split(".");
     const table = parts.pop() ?? "";
     const schema = parts.pop() ?? defaultSchema;
-    if (!isSafeIdentifier(schema) || !isSafeIdentifier(table)) {
+    if (!isSafeIdentifier(schema) || table !== WILDCARD && !isSafeIdentifier(table)) {
       continue;
     }
     const key = tableKey2(schema, table);
@@ -767,10 +919,11 @@ function buildColumnsQuery2(tables) {
         AND kcu.column_name = cols.column_name
     ) AS is_primary_key
   FROM information_schema.columns cols
+  LEFT JOIN pg_catalog.pg_namespace n ON n.nspname = cols.table_schema
   LEFT JOIN pg_catalog.pg_class c
     ON c.relname = cols.table_name
+   AND c.relnamespace = n.oid
    AND c.relkind IN ('r', 'v', 'm')
-  LEFT JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
   LEFT JOIN pg_catalog.pg_attribute attr
     ON attr.attrelid = c.oid
    AND attr.attname = cols.column_name
@@ -780,13 +933,117 @@ function buildColumnsQuery2(tables) {
     ${filter}
   ORDER BY cols.table_schema, cols.table_name, cols.ordinal_position;`;
 }
+var REDSHIFT_EXCLUDED_SCHEMAS = "('pg_catalog', 'information_schema', 'pg_internal', 'pg_automv')";
+function buildRedshiftTablesQuery(tables) {
+  const filter = buildFilterClause(tables, "table_schema", "table_name");
+  return `SELECT
+    table_name,
+    table_schema AS schema_name,
+    table_type,
+    remarks AS comment
+  FROM svv_tables
+  WHERE table_catalog = current_database()
+    AND table_schema NOT IN ${REDSHIFT_EXCLUDED_SCHEMAS}
+    AND table_schema NOT LIKE 'pg_temp%'
+    ${filter}
+  ORDER BY table_schema, table_name;`;
+}
+function buildRedshiftColumnsQuery(tables) {
+  const filter = buildFilterClause(tables, "table_schema", "table_name");
+  return `SELECT
+    table_name,
+    table_schema,
+    column_name,
+    data_type,
+    NULL AS udt_name,
+    remarks AS description,
+    FALSE AS is_primary_key
+  FROM svv_columns
+  WHERE table_catalog = current_database()
+    AND table_schema NOT IN ${REDSHIFT_EXCLUDED_SCHEMAS}
+    AND table_schema NOT LIKE 'pg_temp%'
+    ${filter}
+  ORDER BY table_schema, table_name, ordinal_position;`;
+}
 function buildFilterClause(tables, schemaExpr, tableExpr) {
   if (!tables.length) return "";
-  const clauses = tables.map(({ schema, table }) => {
-    return `(${schemaExpr} = '${schema}' AND ${tableExpr} = '${table}')`;
-  });
+  const wildcardSchemas = new Set(
+    tables.filter((t) => t.table === WILDCARD).map((t) => t.schema)
+  );
+  const clauses = [];
+  for (const schema of wildcardSchemas) {
+    clauses.push(`(${schemaExpr} = '${schema}')`);
+  }
+  for (const { schema, table } of tables) {
+    if (table === WILDCARD || wildcardSchemas.has(schema)) continue;
+    clauses.push(`(${schemaExpr} = '${schema}' AND ${tableExpr} = '${table}')`);
+  }
   return `AND (${clauses.join(" OR ")})`;
 }
+function buildListSchemasQuery() {
+  return `SELECT n.nspname AS schema, COUNT(*) AS table_count
+  FROM pg_class c
+  JOIN pg_namespace n ON n.oid = c.relnamespace
+  WHERE c.relkind IN ('r', 'v', 'm')
+    AND n.nspname NOT IN ('pg_catalog', 'information_schema', 'pg_toast')
+    AND n.nspname NOT LIKE 'pg_temp%'
+    AND n.nspname NOT LIKE 'pg_toast_temp%'
+  GROUP BY n.nspname
+  ORDER BY n.nspname;`;
+}
+function buildRedshiftListSchemasQuery() {
+  return `SELECT table_schema AS schema, COUNT(*) AS table_count
+  FROM svv_tables
+  WHERE table_catalog = current_database()
+    AND table_schema NOT IN ${REDSHIFT_EXCLUDED_SCHEMAS}
+    AND table_schema NOT LIKE 'pg_temp%'
+  GROUP BY table_schema
+  ORDER BY table_schema;`;
+}
+function toLikeSubstringPattern(search) {
+  return `%${search.replace(/[\\%_]/g, (ch) => `\\${ch}`)}%`;
+}
+function buildListTablesQuery(dialect, options) {
+  const isRedshift = dialect === "redshift";
+  const schemaExpr = isRedshift ? "table_schema" : "n.nspname";
+  const tableExpr = isRedshift ? "table_name" : "c.relname";
+  const params = [];
+  const filters = [];
+  if (options.schema) {
+    params.push(options.schema);
+    filters.push(`AND ${schemaExpr} = $${params.length}`);
+  }
+  const search = options.search?.trim();
+  if (search) {
+    params.push(toLikeSubstringPattern(search));
+    filters.push(`AND ${tableExpr} ILIKE $${params.length}`);
+  }
+  const limit = resolveCatalogLimit(options.limit);
+  const filterSql = filters.join("\n    ");
+  const sql = isRedshift ? `SELECT table_schema AS schema, table_name AS name, table_type
+  FROM svv_tables
+  WHERE table_catalog = current_database()
+    AND table_schema NOT IN ${REDSHIFT_EXCLUDED_SCHEMAS}
+    AND table_schema NOT LIKE 'pg_temp%'
+    ${filterSql}
+  ORDER BY table_schema, table_name
+  LIMIT ${limit};` : `SELECT n.nspname AS schema, c.relname AS name,
+    CASE c.relkind
+      WHEN 'v' THEN 'view'
+      WHEN 'm' THEN 'materialized_view'
+      ELSE 'table'
+    END AS table_type
+  FROM pg_class c
+  JOIN pg_namespace n ON n.oid = c.relnamespace
+  WHERE c.relkind IN ('r', 'v', 'm')
+    AND n.nspname NOT IN ('pg_catalog', 'information_schema', 'pg_toast')
+    AND n.nspname NOT LIKE 'pg_temp%'
+    AND n.nspname NOT LIKE 'pg_toast_temp%'
+    ${filterSql}
+  ORDER BY n.nspname, c.relname
+  LIMIT ${limit};`;
+  return { sql, params };
+}
 function tableKey2(schema, table) {
   return `${schema}.${table}`;
 }
@@ -921,6 +1178,20 @@ var QueryPipelineError = class extends Error {
     return isAiProviderErrorCode(this.code);
   }
 };
+var SchemaTooLargeError = class extends Error {
+  constructor(tableCount, columnCount, maxColumns) {
+    super(
+      `Schema too large to sync: ${columnCount} columns across ${tableCount} tables exceeds the limit of ${maxColumns} columns. Restrict the tables to sync (e.g. allowedTables with "schema.*" or specific tables).`
+    );
+    this.tableCount = tableCount;
+    this.columnCount = columnCount;
+    this.maxColumns = maxColumns;
+    this.name = "SchemaTooLargeError";
+  }
+  tableCount;
+  columnCount;
+  maxColumns;
+};
 
 // src/core/client.ts
 var ApiClient = class {
@@ -1060,7 +1331,7 @@ var ApiClient = class {
       json = void 0;
     }
     if (!response.ok) {
-      const message = json?.error || response.statusText || "Request failed";
+      const message = errorMessageFromBody(json, response);
       if (isQueryErrorCode(json?.code)) {
         throw new QueryPipelineError(
           message,
@@ -1182,6 +1453,17 @@ var ApiClient = class {
     return `${data}.${encodedSignature}`;
   }
 };
+function errorMessageFromBody(json, response) {
+  const error = json?.error;
+  if (typeof error === "string" && error) return error;
+  if (error && typeof error === "object") {
+    const nested = error.message ?? error.code;
+    if (typeof nested === "string" && nested) {
+      return `${nested} (HTTP ${response.status})`;
+    }
+  }
+  return response.statusText || `Request failed (HTTP ${response.status})`;
+}
 
 // src/core/callback-client.ts
 var CallbackApiClient = class {
@@ -1968,6 +2250,191 @@ async function syncSchema(client, queryEngine, databaseName, options, signal) {
   );
   return response;
 }
+var DEFAULT_MAX_BATCH_DOCS = 1e3;
+var DEFAULT_MAX_BATCH_BYTES = 2e6;
+var utf8 = new TextEncoder();
+function jsonBytes(value) {
+  return utf8.encode(JSON.stringify(value)).length;
+}
+var BATCH_ENVELOPE_BYTES = jsonBytes({ tables: [] });
+function splitIngestTablesIntoBatches(tables, maxBatchDocs = DEFAULT_MAX_BATCH_DOCS, maxBatchBytes = DEFAULT_MAX_BATCH_BYTES) {
+  const batches = [];
+  let current = [];
+  let currentDocs = 0;
+  let currentBytes = BATCH_ENVELOPE_BYTES;
+  for (const table of tables) {
+    const docs = 1 + table.columns.length;
+    const bytes = jsonBytes(table);
+    if (current.length > 0 && (currentDocs + docs > maxBatchDocs || currentBytes + 1 + bytes > maxBatchBytes)) {
+      batches.push(current);
+      current = [];
+      currentDocs = 0;
+      currentBytes = BATCH_ENVELOPE_BYTES;
+    }
+    currentBytes += bytes + (current.length > 0 ? 1 : 0);
+    current.push(table);
+    currentDocs += docs;
+  }
+  if (current.length > 0 || batches.length === 0) {
+    batches.push(current);
+  }
+  return batches;
+}
+function sessionPath(sessionId, suffix) {
+  return `/ingest/sessions/${encodeURIComponent(sessionId)}${suffix}`;
+}
+async function stageSchemaIngest(client, queryEngine, databaseName, options, signal) {
+  const tenantId = resolveTenantId4(client, options.tenantId);
+  const adapter = queryEngine.getDatabase(databaseName);
+  const metadata = queryEngine.getDatabaseMetadata(databaseName);
+  const emit = options.onProgress ?? (() => {
+  });
+  emit({ phase: "introspecting" });
+  const introspection = await adapter.introspect(
+    options.tables ? { tables: options.tables } : void 0
+  );
+  const { tables, ...sessionFields } = buildSchemaRequest(
+    databaseName,
+    adapter,
+    introspection,
+    metadata
+  );
+  const tableCount = tables.length;
+  const columnCount = tables.reduce((sum, t) => sum + t.columns.length, 0);
+  emit({ phase: "introspected", tableCount, columnCount });
+  if (options.maxColumns !== void 0 && columnCount > options.maxColumns) {
+    throw new SchemaTooLargeError(tableCount, columnCount, options.maxColumns);
+  }
+  const batches = splitIngestTablesIntoBatches(
+    tables,
+    options.maxBatchDocs ?? DEFAULT_MAX_BATCH_DOCS,
+    options.maxBatchBytes ?? DEFAULT_MAX_BATCH_BYTES
+  );
+  const totalBatches = batches.length;
+  const created = await client.post(
+    "/ingest/sessions",
+    {
+      ...sessionFields,
+      ...options.forceReindex ? { force_reindex: true } : {},
+      total_batches: totalBatches
+    },
+    tenantId,
+    options.userId,
+    options.scopes,
+    signal,
+    import_node_crypto2.default.randomUUID()
+  );
+  const sessionId = created.session_id;
+  for (let index = 0; index < totalBatches; index += 1) {
+    await client.put(
+      sessionPath(sessionId, `/batches/${index}`),
+      { tables: batches[index] },
+      tenantId,
+      options.userId,
+      options.scopes,
+      signal,
+      sessionId
+    );
+    emit({ phase: "uploading", done: index + 1, total: totalBatches });
+  }
+  emit({ phase: "committing" });
+  const committed = await client.post(
+    sessionPath(sessionId, "/commit"),
+    {},
+    tenantId,
+    options.userId,
+    options.scopes,
+    signal,
+    sessionId
+  );
+  if (committed.status === "skipped") {
+    const { status: _status, ...skippedResult } = committed;
+    return {
+      sessionId,
+      status: "skipped",
+      totalBatches,
+      tableCount,
+      columnCount,
+      skippedResult,
+      driftDetected: skippedResult.drift_detected
+    };
+  }
+  return {
+    sessionId,
+    status: "embedding",
+    totalBatches: committed.total_batches ?? totalBatches,
+    tableCount,
+    columnCount,
+    driftDetected: committed.drift_detected
+  };
+}
+async function embedSchemaIngestBatch(client, sessionId, index, options, signal) {
+  const tenantId = resolveTenantId4(client, options.tenantId);
+  return await client.post(
+    sessionPath(sessionId, `/batches/${index}/embed`),
+    {},
+    tenantId,
+    options.userId,
+    options.scopes,
+    signal,
+    sessionId
+  );
+}
+async function finalizeSchemaIngest(client, sessionId, options, signal) {
+  const tenantId = resolveTenantId4(client, options.tenantId);
+  return await client.post(
+    sessionPath(sessionId, "/finalize"),
+    {},
+    tenantId,
+    options.userId,
+    options.scopes,
+    signal,
+    sessionId
+  );
+}
+async function syncSchemaInBatches(client, queryEngine, databaseName, options, signal) {
+  const staged = await stageSchemaIngest(
+    client,
+    queryEngine,
+    databaseName,
+    options,
+    signal
+  );
+  if (staged.status === "skipped") {
+    return staged.skippedResult;
+  }
+  const emit = options.onProgress ?? (() => {
+  });
+  const requestOptions = {
+    tenantId: options.tenantId,
+    userId: options.userId,
+    scopes: options.scopes
+  };
+  let chunks = 0;
+  for (let index = 0; index < staged.totalBatches; index += 1) {
+    const embedded = await embedSchemaIngestBatch(
+      client,
+      staged.sessionId,
+      index,
+      requestOptions,
+      signal
+    );
+    chunks += embedded.chunks ?? 0;
+    emit({
+      phase: "embedding",
+      done: index + 1,
+      total: staged.totalBatches,
+      chunks
+    });
+  }
+  emit({ phase: "finalizing" });
+  return await finalizeSchemaIngest(
+    client,
+    staged.sessionId,
+    requestOptions,
+    signal
+  );
+}
 function resolveTenantId4(client, tenantId) {
   const resolved = tenantId ?? client.getDefaultTenantId();
   if (!resolved) {
@@ -2913,7 +3380,7 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
     const adapter = new PostgresAdapter(clientFn, options);
     const metadata = {
       name,
-      dialect: "postgres",
+      dialect: adapter.getDialect(),
       description: options?.description,
       tags: options?.tags,
       tenantFieldName: options?.tenantFieldName,
@@ -2925,6 +3392,14 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
     };
     this.queryEngine.attachDatabase(name, adapter, metadata);
   }
+  /**
+   * Attach an Amazon Redshift database. Redshift speaks the Postgres wire
+   * protocol, so `clientFn` can wrap a `pg` client; introspection uses
+   * Redshift's svv_* catalog views and SQL is generated for Redshift.
+   */
+  attachRedshift(name, clientFn, options) {
+    this.attachPostgres(name, clientFn, { ...options, dialect: "redshift" });
+  }
   attachBigQuery(name, clientFn, options) {
     const adapter = new BigQueryAdapter(clientFn, options);
     const metadata = {
@@ -2953,6 +3428,33 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
     const adapter = this.queryEngine.getDatabase(databaseName);
     return await adapter.introspect(tables ? { tables } : void 0);
   }
+  /**
+   * Lists schemas (ClickHouse: the database, BigQuery: the dataset) with table
+   * counts. Cheap catalog read for building an allowed-tables picker; not
+   * restricted by `allowedTables`.
+   */
+  async listSchemas(databaseName) {
+    const adapter = this.queryEngine.getDatabase(databaseName);
+    if (!adapter.listSchemas) {
+      throw new Error(
+        `Database "${databaseName}" (${adapter.getDialect()}) does not support listSchemas`
+      );
+    }
+    return await adapter.listSchemas();
+  }
+  /**
+   * Lists tables/views (no columns) filtered by schema and a case-insensitive
+   * name substring. Default limit 500, max 5000. Not restricted by `allowedTables`.
+   */
+  async listTables(databaseName, options) {
+    const adapter = this.queryEngine.getDatabase(databaseName);
+    if (!adapter.listTables) {
+      throw new Error(
+        `Database "${databaseName}" (${adapter.getDialect()}) does not support listTables`
+      );
+    }
+    return await adapter.listTables(options);
+  }
   /**
    * Syncs the database schema to QueryPanel for natural language query generation.
    *
@@ -2986,6 +3488,62 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
       signal
     );
   }
+  /**
+   * Introspects the schema, uploads it in batches to a new ingest session and
+   * commits it. Returns `status: "skipped"` (with `skippedResult`) when the schema
+   * is unchanged, otherwise `status: "embedding"`: call embedSchemaIngestBatch for
+   * every index in [0, totalBatches) and then finalizeSchemaIngest.
+   * Throws SchemaTooLargeError before uploading if `maxColumns` is exceeded.
+   */
+  async stageSchemaIngest(databaseName, options, signal) {
+    return await stageSchemaIngest(
+      this.client,
+      this.queryEngine,
+      databaseName,
+      options,
+      signal
+    );
+  }
+  /** Embeds one batch of a staged ingest session. */
+  async embedSchemaIngestBatch(sessionId, index, options, signal) {
+    return await embedSchemaIngestBatch(
+      this.client,
+      sessionId,
+      index,
+      options,
+      signal
+    );
+  }
+  /** Finalizes a staged ingest session after all batches are embedded. */
+  async finalizeSchemaIngest(sessionId, options, signal) {
+    return await finalizeSchemaIngest(
+      this.client,
+      sessionId,
+      options,
+      signal
+    );
+  }
+  /**
+   * Batched alternative to syncSchema for large databases: stage, embed every
+   * batch, and finalize in-process, reporting progress via `onProgress`.
+   *
+   * @example
+   * ```typescript
+   * await qp.syncSchemaInBatches("warehouse", {
+   *   tenantId: "tenant_123",
+   *   onProgress: (e) => console.log(e.phase, e),
+   * });
+   * ```
+   */
+  async syncSchemaInBatches(databaseName, options, signal) {
+    return await syncSchemaInBatches(
+      this.client,
+      this.queryEngine,
+      databaseName,
+      options,
+      signal
+    );
+  }
   // Natural language query
   /**
    * Generates SQL from a natural language question and executes it.
@@ -3884,6 +4442,7 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
   QueryErrorCode,
   QueryPanelSdkAPI,
   QueryPipelineError,
+  SchemaTooLargeError,
   anonymizeResults,
   mapGeneratedParams,
   normalizeSqlParamsInput,