@querypanel/node-sdk 1.3.6 → 1.3.8

package/dist/index.d.cts

@@ -702,7 +702,7 @@ interface SortSpec {
 }
 interface VizSpecBase {
     version: '1.0';
-    kind: 'chart' | 'table' | 'metric';
+    kind: 'chart' | 'table' | 'metric' | 'map';
     title?: string;
     description?: string;
     data: {
@@ -758,13 +758,32 @@ interface MetricSpec extends VizSpecBase {
     kind: 'metric';
     encoding: MetricEncoding;
 }
-type VizSpec = ChartSpec | TableSpec | MetricSpec;
+type MapLocationMode = 'place' | 'latlng';
+interface MapLocation {
+    mode: MapLocationMode;
+    postalCodeField?: string | null;
+    cityField?: string | null;
+    latField?: string | null;
+    lngField?: string | null;
+}
+interface MapEncoding {
+    location: MapLocation;
+    country: string;
+    colorField?: string | null;
+    labelField?: string | null;
+    tooltips?: string[] | null;
+}
+interface MapSpec extends VizSpecBase {
+    kind: 'map';
+    encoding: MapEncoding;
+}
+type VizSpec = ChartSpec | TableSpec | MetricSpec | MapSpec;
 /**
  * Encoding hints for vizspec modifications.
  * These hints guide the LLM to generate specific visualization configurations.
  */
 interface EncodingHints {
-    /** Preferred vizspec kind (chart, table, metric) */
+    /** Preferred vizspec kind. A map is chosen by the question ("show them on a map"), not by a hint. */
     kind?: 'chart' | 'table' | 'metric';
     /** Preferred chart type (bar, line, area, scatter, pie) */
     chartType?: ChartType;
@@ -848,6 +867,12 @@ interface AskOptions {
     previousSql?: string;
     /** Maximum number of retry attempts on execution failure. */
     maxRetry?: number;
+    /**
+     * Also retry (within `maxRetry`) when the query returns no rows, or one row of only zeros/NULLs
+     * (what `COUNT(*) ... WHERE status = 'approved'` returns when the data stores 'APPROVE').
+     * Only that fact is sent to QueryPanel, never rows or values. Default false.
+     */
+    retryOnEmptyResult?: boolean;
     /** Maximum number of retries for chart generation. */
     chartMaxRetries?: number;
     /** Choose chart generation method. */
@@ -1030,8 +1055,8 @@ interface SqlModifications {
  * These changes only affect how the chart is rendered.
  */
 interface VizModifications {
-    /** Change the VizSpec kind (chart, table, metric). Applies to vizspec only. */
-    kind?: VizSpecKind;
+    /** Change the VizSpec kind (chart, table, metric; a map cannot be switched to or from). Applies to vizspec only. */
+    kind?: Exclude<VizSpecKind, "map">;
     /** Change the chart type (line, bar, area, scatter, pie) */
     chartType?: ChartType;
     /** Configure the X axis field and settings */
@@ -1537,7 +1562,7 @@ declare class QueryPanelSdkAPI {
      * @param input - VizSpec generation input with question, SQL, and result data
      * @param options - Optional settings for tenant and retries
      * @param signal - Optional AbortSignal for cancellation
-     * @returns VizSpec specification for chart, table, or metric visualization
+     * @returns VizSpec specification for chart, table, metric, or map visualization
      *
      * @example
      * ```typescript
@@ -2168,4 +2193,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 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 };
+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 MapEncoding, type MapLocation, type MapLocationMode, type MapSpec, 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

@@ -702,7 +702,7 @@ interface SortSpec {
 }
 interface VizSpecBase {
     version: '1.0';
-    kind: 'chart' | 'table' | 'metric';
+    kind: 'chart' | 'table' | 'metric' | 'map';
     title?: string;
     description?: string;
     data: {
@@ -758,13 +758,32 @@ interface MetricSpec extends VizSpecBase {
     kind: 'metric';
     encoding: MetricEncoding;
 }
-type VizSpec = ChartSpec | TableSpec | MetricSpec;
+type MapLocationMode = 'place' | 'latlng';
+interface MapLocation {
+    mode: MapLocationMode;
+    postalCodeField?: string | null;
+    cityField?: string | null;
+    latField?: string | null;
+    lngField?: string | null;
+}
+interface MapEncoding {
+    location: MapLocation;
+    country: string;
+    colorField?: string | null;
+    labelField?: string | null;
+    tooltips?: string[] | null;
+}
+interface MapSpec extends VizSpecBase {
+    kind: 'map';
+    encoding: MapEncoding;
+}
+type VizSpec = ChartSpec | TableSpec | MetricSpec | MapSpec;
 /**
  * Encoding hints for vizspec modifications.
  * These hints guide the LLM to generate specific visualization configurations.
  */
 interface EncodingHints {
-    /** Preferred vizspec kind (chart, table, metric) */
+    /** Preferred vizspec kind. A map is chosen by the question ("show them on a map"), not by a hint. */
     kind?: 'chart' | 'table' | 'metric';
     /** Preferred chart type (bar, line, area, scatter, pie) */
     chartType?: ChartType;
@@ -848,6 +867,12 @@ interface AskOptions {
     previousSql?: string;
     /** Maximum number of retry attempts on execution failure. */
     maxRetry?: number;
+    /**
+     * Also retry (within `maxRetry`) when the query returns no rows, or one row of only zeros/NULLs
+     * (what `COUNT(*) ... WHERE status = 'approved'` returns when the data stores 'APPROVE').
+     * Only that fact is sent to QueryPanel, never rows or values. Default false.
+     */
+    retryOnEmptyResult?: boolean;
     /** Maximum number of retries for chart generation. */
     chartMaxRetries?: number;
     /** Choose chart generation method. */
@@ -1030,8 +1055,8 @@ interface SqlModifications {
  * These changes only affect how the chart is rendered.
  */
 interface VizModifications {
-    /** Change the VizSpec kind (chart, table, metric). Applies to vizspec only. */
-    kind?: VizSpecKind;
+    /** Change the VizSpec kind (chart, table, metric; a map cannot be switched to or from). Applies to vizspec only. */
+    kind?: Exclude<VizSpecKind, "map">;
     /** Change the chart type (line, bar, area, scatter, pie) */
     chartType?: ChartType;
     /** Configure the X axis field and settings */
@@ -1537,7 +1562,7 @@ declare class QueryPanelSdkAPI {
      * @param input - VizSpec generation input with question, SQL, and result data
      * @param options - Optional settings for tenant and retries
      * @param signal - Optional AbortSignal for cancellation
-     * @returns VizSpec specification for chart, table, or metric visualization
+     * @returns VizSpec specification for chart, table, metric, or map visualization
      *
      * @example
      * ```typescript
@@ -2168,4 +2193,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 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 };
+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 MapEncoding, type MapLocation, type MapLocationMode, type MapSpec, 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.js

@@ -2444,6 +2444,15 @@ function resolveQueryPipeline(pipeline) {
   }
   return "v2";
 }
+var EMPTY_RESULT_ERROR = "The query ran but returned no rows (or only zero/NULL values). A filter value probably does not match how the data stores it (case, spelling, codes such as 'APPROVE' vs 'approved'), or a filter is narrower than the question. Check each filter value against the column's documented values and fix it; keep every filter the question asks for.";
+function isEmptyLikeResult(rows) {
+  if (rows.length === 0) return true;
+  if (rows.length > 1) return false;
+  const row = rows[0];
+  if (!row || typeof row !== "object") return false;
+  const values = Object.values(row);
+  return values.length > 0 && values.every((v) => v === null || v === 0 || v === "0" || v === 0n);
+}
 async function ask(client, queryEngine, question, options, signal) {
   const tenantId = resolveTenantId5(client, options.tenantId);
   const sessionId = crypto3.randomUUID();
@@ -2526,6 +2535,17 @@ async function ask(client, queryEngine, question, options, signal) {
         tenantId
       );
       const rows = execution.rows ?? [];
+      if (options.retryOnEmptyResult && attempt < maxRetry && isEmptyLikeResult(rows)) {
+        attempt++;
+        lastError = EMPTY_RESULT_ERROR;
+        previousSql = sql;
+        console.warn("Query returned no data, retrying query generation", {
+          attempt,
+          maxAttempts: maxRetry + 1,
+          sql
+        });
+        continue;
+      }
       const chartType = options.chartType ?? "vega-lite";
       let chart = {
         specType: chartType,
@@ -3612,7 +3632,7 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
    * @param input - VizSpec generation input with question, SQL, and result data
    * @param options - Optional settings for tenant and retries
    * @param signal - Optional AbortSignal for cancellation
-   * @returns VizSpec specification for chart, table, or metric visualization
+   * @returns VizSpec specification for chart, table, metric, or map visualization
    *
    * @example
    * ```typescript