@querypanel/node-sdk 1.0.57 → 1.0.59

package/dist/index.d.cts

@@ -37,7 +37,7 @@ interface IntrospectOptions {
     tables?: string[];
 }
 
-type DatabaseDialect = "clickhouse" | "postgres" | "mysql";
+type DatabaseDialect = "bigquery" | "clickhouse" | "postgres" | "mysql";
 interface DatabaseExecutionResult {
     fields: string[];
     rows: Array<Record<string, unknown>>;
@@ -74,6 +74,70 @@ interface DatabaseAdapter {
     close?(): Promise<void>;
 }
 
+/**
+ * Request passed to BigQueryClientFn.
+ * dryRun: when true, the client should run the query as a dry run (validation only, no execution).
+ */
+interface BigQueryQueryRequest {
+    query: string;
+    params?: Record<string, string | number | boolean | string[] | number[]>;
+    /** When true, validate the query without executing (e.g. BigQuery dry run). */
+    dryRun?: boolean;
+}
+interface BigQueryQueryResult {
+    rows: Array<Record<string, unknown>>;
+    fields: string[];
+}
+/**
+ * Client function for the BigQuery adapter.
+ * Implement using @google-cloud/bigquery: createQueryJob with dryRun for validation, getQueryResults for execute.
+ */
+type BigQueryClientFn = (request: BigQueryQueryRequest) => Promise<BigQueryQueryResult>;
+interface BigQueryAdapterOptions {
+    /** GCP project ID. Used for INFORMATION_SCHEMA queries. */
+    projectId: string;
+    /** Optional project that owns the dataset. Defaults to projectId. */
+    datasetProjectId?: string;
+    /** Default dataset (schema) name. Used for introspection and unqualified table names. */
+    dataset: string;
+    /** Optional location for the dataset (e.g. "US", "EU"). */
+    location?: string;
+    /** Logical database name used in introspection metadata. */
+    database?: string;
+    /** Optional database kind label. Defaults to "bigquery". */
+    kind?: SchemaIntrospection["db"]["kind"];
+    /**
+     * Optional allow-list of table names (dataset.table or bare table name).
+     * When specified, introspection and queries are restricted to these tables only.
+     */
+    allowedTables?: string[];
+}
+/**
+ * BigQuery adapter following the same pattern as PostgresAdapter and ClickHouseAdapter.
+ * - execute: runs the query via the client function.
+ * - validate: uses dry run (no EXPLAIN in BigQuery) to validate SQL without executing.
+ * - introspect: uses INFORMATION_SCHEMA.TABLES and INFORMATION_SCHEMA.COLUMNS.
+ */
+declare class BigQueryAdapter implements DatabaseAdapter {
+    private readonly clientFn;
+    private readonly projectId;
+    private readonly datasetProjectId;
+    private readonly defaultDataset;
+    private readonly databaseName;
+    private readonly kind;
+    private readonly allowedTables?;
+    constructor(clientFn: BigQueryClientFn, options: BigQueryAdapterOptions);
+    execute(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<DatabaseExecutionResult>;
+    validate(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<void>;
+    getDialect(): "bigquery";
+    /**
+     * Introspect using BigQuery INFORMATION_SCHEMA (TABLES and COLUMNS).
+     * Restricts to the default dataset (or allowedTables) and returns tables/columns only.
+     */
+    introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
+    private validateQueryTables;
+}
+
 interface ClickHouseAdapterOptions {
     /** Optional logical database name used in introspection metadata. */
     database?: string;
@@ -640,6 +704,22 @@ interface AskOptions {
      * - "v2": Improved pipeline with intent planning, hybrid retrieval, schema linking, and SQL reflection
      */
     pipeline?: "v1" | "v2";
+    /**
+     * Optional OpenAI model id for v2 SQL generation. Omit to use server default.
+     */
+    model?: string;
+    /**
+     * Optional additional system prompt text for the v2 pipeline.
+     *
+     * This is appended to the backend's SQL generator/reflection system prompts
+     * (it does not change tenant isolation mechanics; it only guides the LLM).
+     *
+     * Use this for tenant-specific policies (e.g. retention windows) that must
+     * be enforced on every query.
+     *
+     * Only sent when `pipeline: "v2"`.
+     */
+    systemPrompt?: string;
 }
 /**
  * Intent analysis result from the v2 pipeline.
@@ -1029,14 +1109,17 @@ interface QueryPanelSdkAPIOptions {
 declare class QueryPanelSdkAPI {
     private readonly client;
     private readonly queryEngine;
-    constructor(baseUrl: string, privateKey: string, organizationId: string, options?: QueryPanelSdkAPIOptions);
+    /**
+     * @param workspaceId - Workspace UUID (same value as your org in the dashboard). Passed to the API as JWT claim `organizationId`.
+     */
+    constructor(baseUrl: string, privateKey: string, workspaceId: string, options?: QueryPanelSdkAPIOptions);
     /**
      * Create an SDK instance that uses a request callback instead of HTTP.
      * Use this when calling the SDK from within your own API so that "API" calls
      * are handled in-process (e.g. by invoking querypanel-sdk services directly)
      * and do not cause recursion.
      *
-     * @param organizationId - Organization identifier
+     * @param workspaceId - Workspace identifier (sent as `organizationId` in JWTs and API auth)
      * @param requestHandler - Callback invoked for each logical API request (method, path, body, tenantId, etc.)
      * @param options - Optional defaultTenantId
      * @returns QueryPanelSdkAPI instance; attach databases and call ask(), syncSchema(), etc. as usual
@@ -1044,7 +1127,7 @@ declare class QueryPanelSdkAPI {
      * @example
      * ```ts
      * const qp = QueryPanelSdkAPI.withCallbacks(
-     *   process.env.ORGANIZATION_ID!,
+     *   process.env.QUERYPANEL_WORKSPACE_ID!,
      *   async (opts) => {
      *     // Call your in-process services (e.g. querypanel-sdk logic) instead of HTTP
      *     if (opts.path === '/query' || opts.path === '/v2/query') {
@@ -1061,7 +1144,7 @@ declare class QueryPanelSdkAPI {
      * const result = await qp.ask('Top 10 orders', { tenantId: 't1', database: 'db' });
      * ```
      */
-    static withCallbacks(organizationId: string, requestHandler: RequestHandler, options?: {
+    static withCallbacks(workspaceId: string, requestHandler: RequestHandler, options?: {
         defaultTenantId?: string;
     }): QueryPanelSdkAPI;
     attachClickhouse(name: string, clientFn: ClickHouseClientFn, options?: ClickHouseAdapterOptions & {
@@ -1078,6 +1161,13 @@ declare class QueryPanelSdkAPI {
         tenantFieldType?: string;
         enforceTenantIsolation?: boolean;
     }): void;
+    attachBigQuery(name: string, clientFn: BigQueryClientFn, options: BigQueryAdapterOptions & {
+        description?: string;
+        tags?: string[];
+        tenantFieldName?: string;
+        tenantFieldType?: string;
+        enforceTenantIsolation?: boolean;
+    }): void;
     attachDatabase(name: string, adapter: DatabaseAdapter): void;
     introspect(databaseName: string, tables?: string[]): Promise<SchemaIntrospection>;
     /**
@@ -1787,4 +1877,4 @@ declare class QueryPanelSdkAPI {
     }, signal?: AbortSignal): Promise<SdkDashboard[]>;
 }
 
-export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, CallbackApiClient, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, 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 };
+export { 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 ChartCreateInput, type ChartEncoding, type ChartEnvelope, 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 };

package/dist/index.d.ts

@@ -37,7 +37,7 @@ interface IntrospectOptions {
     tables?: string[];
 }
 
-type DatabaseDialect = "clickhouse" | "postgres" | "mysql";
+type DatabaseDialect = "bigquery" | "clickhouse" | "postgres" | "mysql";
 interface DatabaseExecutionResult {
     fields: string[];
     rows: Array<Record<string, unknown>>;
@@ -74,6 +74,70 @@ interface DatabaseAdapter {
     close?(): Promise<void>;
 }
 
+/**
+ * Request passed to BigQueryClientFn.
+ * dryRun: when true, the client should run the query as a dry run (validation only, no execution).
+ */
+interface BigQueryQueryRequest {
+    query: string;
+    params?: Record<string, string | number | boolean | string[] | number[]>;
+    /** When true, validate the query without executing (e.g. BigQuery dry run). */
+    dryRun?: boolean;
+}
+interface BigQueryQueryResult {
+    rows: Array<Record<string, unknown>>;
+    fields: string[];
+}
+/**
+ * Client function for the BigQuery adapter.
+ * Implement using @google-cloud/bigquery: createQueryJob with dryRun for validation, getQueryResults for execute.
+ */
+type BigQueryClientFn = (request: BigQueryQueryRequest) => Promise<BigQueryQueryResult>;
+interface BigQueryAdapterOptions {
+    /** GCP project ID. Used for INFORMATION_SCHEMA queries. */
+    projectId: string;
+    /** Optional project that owns the dataset. Defaults to projectId. */
+    datasetProjectId?: string;
+    /** Default dataset (schema) name. Used for introspection and unqualified table names. */
+    dataset: string;
+    /** Optional location for the dataset (e.g. "US", "EU"). */
+    location?: string;
+    /** Logical database name used in introspection metadata. */
+    database?: string;
+    /** Optional database kind label. Defaults to "bigquery". */
+    kind?: SchemaIntrospection["db"]["kind"];
+    /**
+     * Optional allow-list of table names (dataset.table or bare table name).
+     * When specified, introspection and queries are restricted to these tables only.
+     */
+    allowedTables?: string[];
+}
+/**
+ * BigQuery adapter following the same pattern as PostgresAdapter and ClickHouseAdapter.
+ * - execute: runs the query via the client function.
+ * - validate: uses dry run (no EXPLAIN in BigQuery) to validate SQL without executing.
+ * - introspect: uses INFORMATION_SCHEMA.TABLES and INFORMATION_SCHEMA.COLUMNS.
+ */
+declare class BigQueryAdapter implements DatabaseAdapter {
+    private readonly clientFn;
+    private readonly projectId;
+    private readonly datasetProjectId;
+    private readonly defaultDataset;
+    private readonly databaseName;
+    private readonly kind;
+    private readonly allowedTables?;
+    constructor(clientFn: BigQueryClientFn, options: BigQueryAdapterOptions);
+    execute(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<DatabaseExecutionResult>;
+    validate(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<void>;
+    getDialect(): "bigquery";
+    /**
+     * Introspect using BigQuery INFORMATION_SCHEMA (TABLES and COLUMNS).
+     * Restricts to the default dataset (or allowedTables) and returns tables/columns only.
+     */
+    introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
+    private validateQueryTables;
+}
+
 interface ClickHouseAdapterOptions {
     /** Optional logical database name used in introspection metadata. */
     database?: string;
@@ -640,6 +704,22 @@ interface AskOptions {
      * - "v2": Improved pipeline with intent planning, hybrid retrieval, schema linking, and SQL reflection
      */
     pipeline?: "v1" | "v2";
+    /**
+     * Optional OpenAI model id for v2 SQL generation. Omit to use server default.
+     */
+    model?: string;
+    /**
+     * Optional additional system prompt text for the v2 pipeline.
+     *
+     * This is appended to the backend's SQL generator/reflection system prompts
+     * (it does not change tenant isolation mechanics; it only guides the LLM).
+     *
+     * Use this for tenant-specific policies (e.g. retention windows) that must
+     * be enforced on every query.
+     *
+     * Only sent when `pipeline: "v2"`.
+     */
+    systemPrompt?: string;
 }
 /**
  * Intent analysis result from the v2 pipeline.
@@ -1029,14 +1109,17 @@ interface QueryPanelSdkAPIOptions {
 declare class QueryPanelSdkAPI {
     private readonly client;
     private readonly queryEngine;
-    constructor(baseUrl: string, privateKey: string, organizationId: string, options?: QueryPanelSdkAPIOptions);
+    /**
+     * @param workspaceId - Workspace UUID (same value as your org in the dashboard). Passed to the API as JWT claim `organizationId`.
+     */
+    constructor(baseUrl: string, privateKey: string, workspaceId: string, options?: QueryPanelSdkAPIOptions);
     /**
      * Create an SDK instance that uses a request callback instead of HTTP.
      * Use this when calling the SDK from within your own API so that "API" calls
      * are handled in-process (e.g. by invoking querypanel-sdk services directly)
      * and do not cause recursion.
      *
-     * @param organizationId - Organization identifier
+     * @param workspaceId - Workspace identifier (sent as `organizationId` in JWTs and API auth)
      * @param requestHandler - Callback invoked for each logical API request (method, path, body, tenantId, etc.)
      * @param options - Optional defaultTenantId
      * @returns QueryPanelSdkAPI instance; attach databases and call ask(), syncSchema(), etc. as usual
@@ -1044,7 +1127,7 @@ declare class QueryPanelSdkAPI {
      * @example
      * ```ts
      * const qp = QueryPanelSdkAPI.withCallbacks(
-     *   process.env.ORGANIZATION_ID!,
+     *   process.env.QUERYPANEL_WORKSPACE_ID!,
      *   async (opts) => {
      *     // Call your in-process services (e.g. querypanel-sdk logic) instead of HTTP
      *     if (opts.path === '/query' || opts.path === '/v2/query') {
@@ -1061,7 +1144,7 @@ declare class QueryPanelSdkAPI {
      * const result = await qp.ask('Top 10 orders', { tenantId: 't1', database: 'db' });
      * ```
      */
-    static withCallbacks(organizationId: string, requestHandler: RequestHandler, options?: {
+    static withCallbacks(workspaceId: string, requestHandler: RequestHandler, options?: {
         defaultTenantId?: string;
     }): QueryPanelSdkAPI;
     attachClickhouse(name: string, clientFn: ClickHouseClientFn, options?: ClickHouseAdapterOptions & {
@@ -1078,6 +1161,13 @@ declare class QueryPanelSdkAPI {
         tenantFieldType?: string;
         enforceTenantIsolation?: boolean;
     }): void;
+    attachBigQuery(name: string, clientFn: BigQueryClientFn, options: BigQueryAdapterOptions & {
+        description?: string;
+        tags?: string[];
+        tenantFieldName?: string;
+        tenantFieldType?: string;
+        enforceTenantIsolation?: boolean;
+    }): void;
     attachDatabase(name: string, adapter: DatabaseAdapter): void;
     introspect(databaseName: string, tables?: string[]): Promise<SchemaIntrospection>;
     /**
@@ -1787,4 +1877,4 @@ declare class QueryPanelSdkAPI {
     }, signal?: AbortSignal): Promise<SdkDashboard[]>;
 }
 
-export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, CallbackApiClient, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, 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 };
+export { 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 ChartCreateInput, type ChartEncoding, type ChartEnvelope, 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 };