@querypanel/node-sdk 1.3.3 → 1.3.6

package/dist/index.d.cts

@@ -37,7 +37,27 @@ interface IntrospectOptions {
     tables?: string[];
 }
 
-type DatabaseDialect = "bigquery" | "clickhouse" | "postgres" | "mysql";
+type DatabaseDialect = "bigquery" | "clickhouse" | "postgres" | "redshift" | "mysql";
+/** A schema (or ClickHouse database / BigQuery dataset) in the catalog. */
+interface CatalogSchema {
+    schema: string;
+    tableCount: number;
+}
+type CatalogTableType = "table" | "view" | "materialized_view";
+/** A table or view in the catalog (no columns; cheap to list). */
+interface CatalogTable {
+    schema: string;
+    name: string;
+    type: CatalogTableType;
+}
+interface ListTablesOptions {
+    /** Only list tables in this schema. */
+    schema?: string;
+    /** Case-insensitive substring match on the table name. */
+    search?: string;
+    /** Max rows to return. Default 500, capped at 5000. */
+    limit?: number;
+}
 interface DatabaseExecutionResult {
     fields: string[];
     rows: Array<Record<string, unknown>>;
@@ -68,6 +88,14 @@ interface DatabaseAdapter {
      * Get the database dialect/type
      */
     getDialect(): DatabaseDialect;
+    /**
+     * Optional: List schemas with table counts (cheap catalog read for pickers).
+     */
+    listSchemas?(): Promise<CatalogSchema[]>;
+    /**
+     * Optional: List tables/views without columns (cheap catalog read for pickers).
+     */
+    listTables?(options?: ListTablesOptions): Promise<CatalogTable[]>;
     /**
      * Optional: Close/cleanup database connection
      */
@@ -108,6 +136,7 @@ interface BigQueryAdapterOptions {
     kind?: SchemaIntrospection["db"]["kind"];
     /**
      * Optional allow-list of table names (dataset.table or bare table name).
+     * `*` or `<dataset>.*` allows every table in the dataset (same as no filter).
      * When specified, introspection and queries are restricted to these tables only.
      */
     allowedTables?: string[];
@@ -135,6 +164,14 @@ declare class BigQueryAdapter implements DatabaseAdapter {
      * Restricts to the default dataset (or allowedTables) and returns tables/columns only.
      */
     introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
+    /** The adapter is bound to one dataset, so this returns a single row. */
+    listSchemas(): Promise<CatalogSchema[]>;
+    /**
+     * List tables in the bound dataset. Reads the full catalog (not restricted
+     * by `allowedTables`). Default limit 500, max 5000.
+     */
+    listTables(options?: ListTablesOptions): Promise<CatalogTable[]>;
+    private informationSchema;
     private validateQueryTables;
 }
 
@@ -152,6 +189,7 @@ interface ClickHouseAdapterOptions {
      * Optional allow-list of table names.
      * When specified, introspection and queries are restricted to these tables only.
      * ClickHouse tables are not schema-qualified, so just provide table names.
+     * `*` or `<database>.*` allows every table (same as no filter).
      */
     allowedTables?: string[];
 }
@@ -179,6 +217,13 @@ declare class ClickHouseAdapter implements DatabaseAdapter {
      * No indexes, constraints, or statistics
      */
     introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
+    /** The adapter is bound to one database, so this returns a single row. */
+    listSchemas(): Promise<CatalogSchema[]>;
+    /**
+     * List tables in the bound database. Reads the full catalog (not restricted
+     * by `allowedTables`). Default limit 500, max 5000.
+     */
+    listTables(options?: ListTablesOptions): Promise<CatalogTable[]>;
     private validateQueryTables;
     close(): Promise<void>;
     private query;
@@ -192,16 +237,24 @@ interface PostgresQueryResult {
     }>;
 }
 type PostgresClientFn = (sql: string, params?: unknown[]) => Promise<PostgresQueryResult>;
+type PostgresWireDialect = "postgres" | "redshift";
 interface PostgresAdapterOptions {
     /** Logical database name used in introspection metadata. */
     database?: string;
     /** Schema to assume when a table is provided without qualification. */
     defaultSchema?: string;
-    /** Optional database kind label. Defaults to "postgres". */
+    /** Optional database kind label. Defaults to the dialect. */
     kind?: SchemaIntrospection["db"]["kind"];
+    /**
+     * Wire-compatible engine behind the client. "redshift" uses Redshift's
+     * svv_* catalog views for introspection. Defaults to "postgres".
+     */
+    dialect?: PostgresWireDialect;
     /**
      * Optional allow-list of table names (schema-qualified or bare).
-     * When specified, introspection and queries are restricted to these tables only.
+     * Use `schema.*` to allow every table in a schema (a bare `*` means the
+     * default schema). When specified, introspection and queries are restricted
+     * to these tables only.
      */
     allowedTables?: string[];
 }
@@ -215,6 +268,7 @@ declare class PostgresAdapter implements DatabaseAdapter {
     private readonly databaseName;
     private readonly defaultSchema;
     private readonly kind;
+    private readonly dialect;
     private readonly allowedTables?;
     constructor(clientFn: PostgresClientFn, options?: PostgresAdapterOptions);
     execute(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<DatabaseExecutionResult>;
@@ -225,7 +279,18 @@ declare class PostgresAdapter implements DatabaseAdapter {
      */
     private convertNamedToPositionalParams;
     validate(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<void>;
-    getDialect(): "postgres";
+    getDialect(): PostgresWireDialect;
+    /**
+     * List schemas with their table/view counts. Reads the full catalog (not
+     * restricted by `allowedTables`) so it can back an allowed-tables picker.
+     */
+    listSchemas(): Promise<CatalogSchema[]>;
+    /**
+     * 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.
+     */
+    listTables(options?: ListTablesOptions): Promise<CatalogTable[]>;
     /**
      * Simplified introspection: only collect table/column metadata for IngestRequest
      * No indexes, constraints, or statistics
@@ -334,6 +399,17 @@ declare class QueryPipelineError extends Error {
      */
     isAiProviderError(): boolean;
 }
+/**
+ * Thrown by stageSchemaIngest / syncSchemaInBatches when the introspected schema
+ * has more columns than `maxColumns`. Raised before anything is uploaded; narrow
+ * the sync with `allowedTables` / `tables` (e.g. `schema.*`) and retry.
+ */
+declare class SchemaTooLargeError extends Error {
+    readonly tableCount: number;
+    readonly columnCount: number;
+    readonly maxColumns: number;
+    constructor(tableCount: number, columnCount: number, maxColumns: number);
+}
 
 type ParamValue = string | number | boolean | string[] | number[];
 type ParamRecord = Record<string, ParamValue>;
@@ -541,6 +617,57 @@ interface SchemaSyncOptions {
     tables?: string[];
     forceReindex?: boolean;
 }
+/** Progress events emitted by stageSchemaIngest / syncSchemaInBatches. */
+type SchemaSyncProgressEvent = {
+    phase: "introspecting";
+} | {
+    phase: "introspected";
+    tableCount: number;
+    columnCount: number;
+} | {
+    phase: "uploading";
+    done: number;
+    total: number;
+} | {
+    phase: "committing";
+} | {
+    phase: "embedding";
+    done: number;
+    total: number;
+    chunks: number;
+} | {
+    phase: "finalizing";
+};
+interface SchemaIngestRequestOptions {
+    tenantId?: string;
+    userId?: string;
+    scopes?: string[];
+}
+interface StageSchemaIngestOptions extends SchemaSyncOptions {
+    /** Max docs per batch (1 per table + 1 per column). Default 1000. */
+    maxBatchDocs?: number;
+    /** Max serialized JSON bytes per batch. Default 2_000_000. */
+    maxBatchBytes?: number;
+    /** Throw SchemaTooLargeError (before uploading) above this many columns. */
+    maxColumns?: number;
+    onProgress?: (event: SchemaSyncProgressEvent) => void;
+}
+type SyncSchemaInBatchesOptions = StageSchemaIngestOptions;
+interface StageSchemaIngestResult {
+    sessionId: string;
+    status: "skipped" | "embedding";
+    totalBatches: number;
+    tableCount: number;
+    columnCount: number;
+    /** Present when status is "skipped" (schema unchanged). */
+    skippedResult?: IngestResponse;
+    driftDetected?: boolean;
+}
+interface SchemaIngestBatchEmbedResponse {
+    index: number;
+    chunks: number;
+    chunks_with_annotations: number;
+}
 
 /**
  * VizSpec types for flexible visualization specifications
@@ -1255,6 +1382,18 @@ declare class QueryPanelSdkAPI {
         tenantFieldType?: string;
         enforceTenantIsolation?: boolean;
     }): void;
+    /**
+     * 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: string, clientFn: PostgresClientFn, options?: Omit<PostgresAdapterOptions, "dialect"> & {
+        description?: string;
+        tags?: string[];
+        tenantFieldName?: string;
+        tenantFieldType?: string;
+        enforceTenantIsolation?: boolean;
+    }): void;
     attachBigQuery(name: string, clientFn: BigQueryClientFn, options: BigQueryAdapterOptions & {
         description?: string;
         tags?: string[];
@@ -1264,6 +1403,17 @@ declare class QueryPanelSdkAPI {
     }): void;
     attachDatabase(name: string, adapter: DatabaseAdapter): void;
     introspect(databaseName: string, tables?: string[]): Promise<SchemaIntrospection>;
+    /**
+     * Lists schemas (ClickHouse: the database, BigQuery: the dataset) with table
+     * counts. Cheap catalog read for building an allowed-tables picker; not
+     * restricted by `allowedTables`.
+     */
+    listSchemas(databaseName: string): Promise<CatalogSchema[]>;
+    /**
+     * Lists tables/views (no columns) filtered by schema and a case-insensitive
+     * name substring. Default limit 500, max 5000. Not restricted by `allowedTables`.
+     */
+    listTables(databaseName: string, options?: ListTablesOptions): Promise<CatalogTable[]>;
     /**
      * Syncs the database schema to QueryPanel for natural language query generation.
      *
@@ -1289,6 +1439,31 @@ declare class QueryPanelSdkAPI {
      * ```
      */
     syncSchema(databaseName: string, options: SchemaSyncOptions, signal?: AbortSignal): Promise<IngestResponse>;
+    /**
+     * 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.
+     */
+    stageSchemaIngest(databaseName: string, options: StageSchemaIngestOptions, signal?: AbortSignal): Promise<StageSchemaIngestResult>;
+    /** Embeds one batch of a staged ingest session. */
+    embedSchemaIngestBatch(sessionId: string, index: number, options: SchemaIngestRequestOptions, signal?: AbortSignal): Promise<SchemaIngestBatchEmbedResponse>;
+    /** Finalizes a staged ingest session after all batches are embedded. */
+    finalizeSchemaIngest(sessionId: string, options: SchemaIngestRequestOptions, signal?: AbortSignal): Promise<IngestResponse>;
+    /**
+     * 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),
+     * });
+     * ```
+     */
+    syncSchemaInBatches(databaseName: string, options: SyncSchemaInBatchesOptions, signal?: AbortSignal): Promise<IngestResponse>;
     /**
      * Generates SQL from a natural language question and executes it.
      *
@@ -1993,4 +2168,4 @@ declare class QueryPanelSdkAPI {
     }, signal?: AbortSignal): Promise<SdkDashboard[]>;
 }
 
-export { ALL_VIZ_CHART_TYPES, type ActiveChartBulkGetResponse, type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, BigQueryAdapter, type BigQueryAdapterOptions, type BigQueryClientFn, type BigQueryQueryRequest, type BigQueryQueryResult, CallbackApiClient, type ChartBulkGetResponse, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListAllOptions, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DashboardCreateInput, type DashboardForkInput, type DashboardForkUpdateInput, type DashboardListOptions, type DashboardUpdateInput, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type EncodingHints, type FieldRef, type FieldRefInput, type FieldType, type IQueryPanelApi, type IngestResponse, type IntentResult, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse$1 as PaginatedResponse, type PaginationInfo$1 as PaginationInfo, type PaginationQuery$1 as PaginationQuery, type ParamRecord, type ParamValue, type PipelineTrace, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, type QueryPanelSdkAPIOptions, QueryPipelineError, type RequestHandler, type RequestHandlerOptions, type RequestHandlerResult, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SdkDashboard, type SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type ValueFormat, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecGeneratorInput, type VizSpecKind, type VizSpecResponse, type VizSpecResult, anonymizeResults, mapGeneratedParams, normalizeSqlParamsInput, resolveQueryPipeline };
+export { ALL_VIZ_CHART_TYPES, type ActiveChartBulkGetResponse, type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, BigQueryAdapter, type BigQueryAdapterOptions, type BigQueryClientFn, type BigQueryQueryRequest, type BigQueryQueryResult, CallbackApiClient, type CatalogSchema, type CatalogTable, type CatalogTableType, type ChartBulkGetResponse, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListAllOptions, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DashboardCreateInput, type DashboardForkInput, type DashboardForkUpdateInput, type DashboardListOptions, type DashboardUpdateInput, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type EncodingHints, type FieldRef, type FieldRefInput, type FieldType, type IQueryPanelApi, type IngestResponse, type IntentResult, type ListTablesOptions, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse$1 as PaginatedResponse, type PaginationInfo$1 as PaginationInfo, type PaginationQuery$1 as PaginationQuery, type ParamRecord, type ParamValue, type PipelineTrace, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, type PostgresWireDialect, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, type QueryPanelSdkAPIOptions, QueryPipelineError, type RequestHandler, type RequestHandlerOptions, type RequestHandlerResult, type SchemaIngestBatchEmbedResponse, type SchemaIngestRequestOptions, type SchemaIntrospection, type SchemaSyncOptions, type SchemaSyncProgressEvent, SchemaTooLargeError, type SdkActiveChart, type SdkChart, type SdkDashboard, type SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type StageSchemaIngestOptions, type StageSchemaIngestResult, type SyncSchemaInBatchesOptions, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type ValueFormat, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecGeneratorInput, type VizSpecKind, type VizSpecResponse, type VizSpecResult, anonymizeResults, mapGeneratedParams, normalizeSqlParamsInput, resolveQueryPipeline };

package/dist/index.d.ts

@@ -37,7 +37,27 @@ interface IntrospectOptions {
     tables?: string[];
 }
 
-type DatabaseDialect = "bigquery" | "clickhouse" | "postgres" | "mysql";
+type DatabaseDialect = "bigquery" | "clickhouse" | "postgres" | "redshift" | "mysql";
+/** A schema (or ClickHouse database / BigQuery dataset) in the catalog. */
+interface CatalogSchema {
+    schema: string;
+    tableCount: number;
+}
+type CatalogTableType = "table" | "view" | "materialized_view";
+/** A table or view in the catalog (no columns; cheap to list). */
+interface CatalogTable {
+    schema: string;
+    name: string;
+    type: CatalogTableType;
+}
+interface ListTablesOptions {
+    /** Only list tables in this schema. */
+    schema?: string;
+    /** Case-insensitive substring match on the table name. */
+    search?: string;
+    /** Max rows to return. Default 500, capped at 5000. */
+    limit?: number;
+}
 interface DatabaseExecutionResult {
     fields: string[];
     rows: Array<Record<string, unknown>>;
@@ -68,6 +88,14 @@ interface DatabaseAdapter {
      * Get the database dialect/type
      */
     getDialect(): DatabaseDialect;
+    /**
+     * Optional: List schemas with table counts (cheap catalog read for pickers).
+     */
+    listSchemas?(): Promise<CatalogSchema[]>;
+    /**
+     * Optional: List tables/views without columns (cheap catalog read for pickers).
+     */
+    listTables?(options?: ListTablesOptions): Promise<CatalogTable[]>;
     /**
      * Optional: Close/cleanup database connection
      */
@@ -108,6 +136,7 @@ interface BigQueryAdapterOptions {
     kind?: SchemaIntrospection["db"]["kind"];
     /**
      * Optional allow-list of table names (dataset.table or bare table name).
+     * `*` or `<dataset>.*` allows every table in the dataset (same as no filter).
      * When specified, introspection and queries are restricted to these tables only.
      */
     allowedTables?: string[];
@@ -135,6 +164,14 @@ declare class BigQueryAdapter implements DatabaseAdapter {
      * Restricts to the default dataset (or allowedTables) and returns tables/columns only.
      */
     introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
+    /** The adapter is bound to one dataset, so this returns a single row. */
+    listSchemas(): Promise<CatalogSchema[]>;
+    /**
+     * List tables in the bound dataset. Reads the full catalog (not restricted
+     * by `allowedTables`). Default limit 500, max 5000.
+     */
+    listTables(options?: ListTablesOptions): Promise<CatalogTable[]>;
+    private informationSchema;
     private validateQueryTables;
 }
 
@@ -152,6 +189,7 @@ interface ClickHouseAdapterOptions {
      * Optional allow-list of table names.
      * When specified, introspection and queries are restricted to these tables only.
      * ClickHouse tables are not schema-qualified, so just provide table names.
+     * `*` or `<database>.*` allows every table (same as no filter).
      */
     allowedTables?: string[];
 }
@@ -179,6 +217,13 @@ declare class ClickHouseAdapter implements DatabaseAdapter {
      * No indexes, constraints, or statistics
      */
     introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
+    /** The adapter is bound to one database, so this returns a single row. */
+    listSchemas(): Promise<CatalogSchema[]>;
+    /**
+     * List tables in the bound database. Reads the full catalog (not restricted
+     * by `allowedTables`). Default limit 500, max 5000.
+     */
+    listTables(options?: ListTablesOptions): Promise<CatalogTable[]>;
     private validateQueryTables;
     close(): Promise<void>;
     private query;
@@ -192,16 +237,24 @@ interface PostgresQueryResult {
     }>;
 }
 type PostgresClientFn = (sql: string, params?: unknown[]) => Promise<PostgresQueryResult>;
+type PostgresWireDialect = "postgres" | "redshift";
 interface PostgresAdapterOptions {
     /** Logical database name used in introspection metadata. */
     database?: string;
     /** Schema to assume when a table is provided without qualification. */
     defaultSchema?: string;
-    /** Optional database kind label. Defaults to "postgres". */
+    /** Optional database kind label. Defaults to the dialect. */
     kind?: SchemaIntrospection["db"]["kind"];
+    /**
+     * Wire-compatible engine behind the client. "redshift" uses Redshift's
+     * svv_* catalog views for introspection. Defaults to "postgres".
+     */
+    dialect?: PostgresWireDialect;
     /**
      * Optional allow-list of table names (schema-qualified or bare).
-     * When specified, introspection and queries are restricted to these tables only.
+     * Use `schema.*` to allow every table in a schema (a bare `*` means the
+     * default schema). When specified, introspection and queries are restricted
+     * to these tables only.
      */
     allowedTables?: string[];
 }
@@ -215,6 +268,7 @@ declare class PostgresAdapter implements DatabaseAdapter {
     private readonly databaseName;
     private readonly defaultSchema;
     private readonly kind;
+    private readonly dialect;
     private readonly allowedTables?;
     constructor(clientFn: PostgresClientFn, options?: PostgresAdapterOptions);
     execute(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<DatabaseExecutionResult>;
@@ -225,7 +279,18 @@ declare class PostgresAdapter implements DatabaseAdapter {
      */
     private convertNamedToPositionalParams;
     validate(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<void>;
-    getDialect(): "postgres";
+    getDialect(): PostgresWireDialect;
+    /**
+     * List schemas with their table/view counts. Reads the full catalog (not
+     * restricted by `allowedTables`) so it can back an allowed-tables picker.
+     */
+    listSchemas(): Promise<CatalogSchema[]>;
+    /**
+     * 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.
+     */
+    listTables(options?: ListTablesOptions): Promise<CatalogTable[]>;
     /**
      * Simplified introspection: only collect table/column metadata for IngestRequest
      * No indexes, constraints, or statistics
@@ -334,6 +399,17 @@ declare class QueryPipelineError extends Error {
      */
     isAiProviderError(): boolean;
 }
+/**
+ * Thrown by stageSchemaIngest / syncSchemaInBatches when the introspected schema
+ * has more columns than `maxColumns`. Raised before anything is uploaded; narrow
+ * the sync with `allowedTables` / `tables` (e.g. `schema.*`) and retry.
+ */
+declare class SchemaTooLargeError extends Error {
+    readonly tableCount: number;
+    readonly columnCount: number;
+    readonly maxColumns: number;
+    constructor(tableCount: number, columnCount: number, maxColumns: number);
+}
 
 type ParamValue = string | number | boolean | string[] | number[];
 type ParamRecord = Record<string, ParamValue>;
@@ -541,6 +617,57 @@ interface SchemaSyncOptions {
     tables?: string[];
     forceReindex?: boolean;
 }
+/** Progress events emitted by stageSchemaIngest / syncSchemaInBatches. */
+type SchemaSyncProgressEvent = {
+    phase: "introspecting";
+} | {
+    phase: "introspected";
+    tableCount: number;
+    columnCount: number;
+} | {
+    phase: "uploading";
+    done: number;
+    total: number;
+} | {
+    phase: "committing";
+} | {
+    phase: "embedding";
+    done: number;
+    total: number;
+    chunks: number;
+} | {
+    phase: "finalizing";
+};
+interface SchemaIngestRequestOptions {
+    tenantId?: string;
+    userId?: string;
+    scopes?: string[];
+}
+interface StageSchemaIngestOptions extends SchemaSyncOptions {
+    /** Max docs per batch (1 per table + 1 per column). Default 1000. */
+    maxBatchDocs?: number;
+    /** Max serialized JSON bytes per batch. Default 2_000_000. */
+    maxBatchBytes?: number;
+    /** Throw SchemaTooLargeError (before uploading) above this many columns. */
+    maxColumns?: number;
+    onProgress?: (event: SchemaSyncProgressEvent) => void;
+}
+type SyncSchemaInBatchesOptions = StageSchemaIngestOptions;
+interface StageSchemaIngestResult {
+    sessionId: string;
+    status: "skipped" | "embedding";
+    totalBatches: number;
+    tableCount: number;
+    columnCount: number;
+    /** Present when status is "skipped" (schema unchanged). */
+    skippedResult?: IngestResponse;
+    driftDetected?: boolean;
+}
+interface SchemaIngestBatchEmbedResponse {
+    index: number;
+    chunks: number;
+    chunks_with_annotations: number;
+}
 
 /**
  * VizSpec types for flexible visualization specifications
@@ -1255,6 +1382,18 @@ declare class QueryPanelSdkAPI {
         tenantFieldType?: string;
         enforceTenantIsolation?: boolean;
     }): void;
+    /**
+     * 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: string, clientFn: PostgresClientFn, options?: Omit<PostgresAdapterOptions, "dialect"> & {
+        description?: string;
+        tags?: string[];
+        tenantFieldName?: string;
+        tenantFieldType?: string;
+        enforceTenantIsolation?: boolean;
+    }): void;
     attachBigQuery(name: string, clientFn: BigQueryClientFn, options: BigQueryAdapterOptions & {
         description?: string;
         tags?: string[];
@@ -1264,6 +1403,17 @@ declare class QueryPanelSdkAPI {
     }): void;
     attachDatabase(name: string, adapter: DatabaseAdapter): void;
     introspect(databaseName: string, tables?: string[]): Promise<SchemaIntrospection>;
+    /**
+     * Lists schemas (ClickHouse: the database, BigQuery: the dataset) with table
+     * counts. Cheap catalog read for building an allowed-tables picker; not
+     * restricted by `allowedTables`.
+     */
+    listSchemas(databaseName: string): Promise<CatalogSchema[]>;
+    /**
+     * Lists tables/views (no columns) filtered by schema and a case-insensitive
+     * name substring. Default limit 500, max 5000. Not restricted by `allowedTables`.
+     */
+    listTables(databaseName: string, options?: ListTablesOptions): Promise<CatalogTable[]>;
     /**
      * Syncs the database schema to QueryPanel for natural language query generation.
      *
@@ -1289,6 +1439,31 @@ declare class QueryPanelSdkAPI {
      * ```
      */
     syncSchema(databaseName: string, options: SchemaSyncOptions, signal?: AbortSignal): Promise<IngestResponse>;
+    /**
+     * 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.
+     */
+    stageSchemaIngest(databaseName: string, options: StageSchemaIngestOptions, signal?: AbortSignal): Promise<StageSchemaIngestResult>;
+    /** Embeds one batch of a staged ingest session. */
+    embedSchemaIngestBatch(sessionId: string, index: number, options: SchemaIngestRequestOptions, signal?: AbortSignal): Promise<SchemaIngestBatchEmbedResponse>;
+    /** Finalizes a staged ingest session after all batches are embedded. */
+    finalizeSchemaIngest(sessionId: string, options: SchemaIngestRequestOptions, signal?: AbortSignal): Promise<IngestResponse>;
+    /**
+     * 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),
+     * });
+     * ```
+     */
+    syncSchemaInBatches(databaseName: string, options: SyncSchemaInBatchesOptions, signal?: AbortSignal): Promise<IngestResponse>;
     /**
      * Generates SQL from a natural language question and executes it.
      *
@@ -1993,4 +2168,4 @@ declare class QueryPanelSdkAPI {
     }, signal?: AbortSignal): Promise<SdkDashboard[]>;
 }
 
-export { ALL_VIZ_CHART_TYPES, type ActiveChartBulkGetResponse, type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, BigQueryAdapter, type BigQueryAdapterOptions, type BigQueryClientFn, type BigQueryQueryRequest, type BigQueryQueryResult, CallbackApiClient, type ChartBulkGetResponse, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListAllOptions, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DashboardCreateInput, type DashboardForkInput, type DashboardForkUpdateInput, type DashboardListOptions, type DashboardUpdateInput, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type EncodingHints, type FieldRef, type FieldRefInput, type FieldType, type IQueryPanelApi, type IngestResponse, type IntentResult, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse$1 as PaginatedResponse, type PaginationInfo$1 as PaginationInfo, type PaginationQuery$1 as PaginationQuery, type ParamRecord, type ParamValue, type PipelineTrace, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, type QueryPanelSdkAPIOptions, QueryPipelineError, type RequestHandler, type RequestHandlerOptions, type RequestHandlerResult, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SdkDashboard, type SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type ValueFormat, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecGeneratorInput, type VizSpecKind, type VizSpecResponse, type VizSpecResult, anonymizeResults, mapGeneratedParams, normalizeSqlParamsInput, resolveQueryPipeline };
+export { ALL_VIZ_CHART_TYPES, type ActiveChartBulkGetResponse, type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, BigQueryAdapter, type BigQueryAdapterOptions, type BigQueryClientFn, type BigQueryQueryRequest, type BigQueryQueryResult, CallbackApiClient, type CatalogSchema, type CatalogTable, type CatalogTableType, type ChartBulkGetResponse, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListAllOptions, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DashboardCreateInput, type DashboardForkInput, type DashboardForkUpdateInput, type DashboardListOptions, type DashboardUpdateInput, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type EncodingHints, type FieldRef, type FieldRefInput, type FieldType, type IQueryPanelApi, type IngestResponse, type IntentResult, type ListTablesOptions, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse$1 as PaginatedResponse, type PaginationInfo$1 as PaginationInfo, type PaginationQuery$1 as PaginationQuery, type ParamRecord, type ParamValue, type PipelineTrace, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, type PostgresWireDialect, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, type QueryPanelSdkAPIOptions, QueryPipelineError, type RequestHandler, type RequestHandlerOptions, type RequestHandlerResult, type SchemaIngestBatchEmbedResponse, type SchemaIngestRequestOptions, type SchemaIntrospection, type SchemaSyncOptions, type SchemaSyncProgressEvent, SchemaTooLargeError, type SdkActiveChart, type SdkChart, type SdkDashboard, type SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type StageSchemaIngestOptions, type StageSchemaIngestResult, type SyncSchemaInBatchesOptions, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type ValueFormat, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecGeneratorInput, type VizSpecKind, type VizSpecResponse, type VizSpecResult, anonymizeResults, mapGeneratedParams, normalizeSqlParamsInput, resolveQueryPipeline };