@querypanel/node-sdk 1.0.44 → 1.0.45
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +48 -0
- package/dist/index.cjs +221 -23
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +218 -8
- package/dist/index.d.ts +218 -8
- package/dist/index.js +221 -23
- package/dist/index.js.map +1 -1
- package/package.json +71 -71
package/dist/index.d.cts
CHANGED
|
@@ -249,11 +249,11 @@ interface ChartUpdateInput {
|
|
|
249
249
|
spec_type?: 'vega-lite' | 'vizspec';
|
|
250
250
|
target_db?: string;
|
|
251
251
|
}
|
|
252
|
-
interface PaginationQuery {
|
|
252
|
+
interface PaginationQuery$1 {
|
|
253
253
|
page?: number;
|
|
254
254
|
limit?: number;
|
|
255
255
|
}
|
|
256
|
-
interface PaginationInfo {
|
|
256
|
+
interface PaginationInfo$1 {
|
|
257
257
|
page: number;
|
|
258
258
|
limit: number;
|
|
259
259
|
total: number;
|
|
@@ -261,15 +261,15 @@ interface PaginationInfo {
|
|
|
261
261
|
hasNext: boolean;
|
|
262
262
|
hasPrev: boolean;
|
|
263
263
|
}
|
|
264
|
-
interface PaginatedResponse<T> {
|
|
264
|
+
interface PaginatedResponse$1<T> {
|
|
265
265
|
data: T[];
|
|
266
|
-
pagination: PaginationInfo;
|
|
266
|
+
pagination: PaginationInfo$1;
|
|
267
267
|
}
|
|
268
268
|
interface ChartListOptions {
|
|
269
269
|
tenantId?: string;
|
|
270
270
|
userId?: string;
|
|
271
271
|
scopes?: string[];
|
|
272
|
-
pagination?: PaginationQuery;
|
|
272
|
+
pagination?: PaginationQuery$1;
|
|
273
273
|
sortBy?: "title" | "user_id" | "created_at" | "updated_at";
|
|
274
274
|
sortDir?: "asc" | "desc";
|
|
275
275
|
title?: string;
|
|
@@ -413,42 +413,90 @@ interface MetricSpec extends VizSpecBase {
|
|
|
413
413
|
}
|
|
414
414
|
type VizSpec = ChartSpec | TableSpec | MetricSpec;
|
|
415
415
|
|
|
416
|
+
/**
|
|
417
|
+
* Context document returned by the query pipeline.
|
|
418
|
+
*/
|
|
416
419
|
interface ContextDocument {
|
|
420
|
+
/** Optional source identifier for the document. */
|
|
417
421
|
source?: string;
|
|
422
|
+
/** Raw document content or excerpt. */
|
|
418
423
|
pageContent: string;
|
|
424
|
+
/** Additional metadata attached to the document. */
|
|
419
425
|
metadata?: Record<string, unknown>;
|
|
426
|
+
/** Optional relevance score from retrieval. */
|
|
420
427
|
score?: number;
|
|
421
428
|
}
|
|
429
|
+
/**
|
|
430
|
+
* Chart payload returned with query results.
|
|
431
|
+
*/
|
|
422
432
|
interface ChartEnvelope {
|
|
433
|
+
/** Vega-Lite spec when specType is "vega-lite". */
|
|
423
434
|
vegaLiteSpec?: Record<string, unknown> | null;
|
|
435
|
+
/** VizSpec payload when specType is "vizspec". */
|
|
424
436
|
vizSpec?: VizSpec | null;
|
|
437
|
+
/** Chart specification type. */
|
|
425
438
|
specType: "vega-lite" | "vizspec";
|
|
439
|
+
/** Optional chart generation notes or errors. */
|
|
426
440
|
notes: string | null;
|
|
427
441
|
}
|
|
442
|
+
/**
|
|
443
|
+
* Configuration options for query generation.
|
|
444
|
+
*/
|
|
428
445
|
interface AskOptions {
|
|
446
|
+
/** Tenant identifier for scoped access. */
|
|
429
447
|
tenantId?: string;
|
|
448
|
+
/** Optional user identifier for audit/telemetry. */
|
|
430
449
|
userId?: string;
|
|
450
|
+
/** Optional scopes to include in the auth token. */
|
|
431
451
|
scopes?: string[];
|
|
452
|
+
/** Override the default database name. */
|
|
432
453
|
database?: string;
|
|
454
|
+
/** Previous error message for retry context. */
|
|
433
455
|
lastError?: string;
|
|
456
|
+
/** Previous SQL statement for retry context. */
|
|
434
457
|
previousSql?: string;
|
|
458
|
+
/** Maximum number of retry attempts on execution failure. */
|
|
435
459
|
maxRetry?: number;
|
|
460
|
+
/** Maximum number of retries for chart generation. */
|
|
436
461
|
chartMaxRetries?: number;
|
|
462
|
+
/** Choose chart generation method. */
|
|
437
463
|
chartType?: "vega-lite" | "vizspec";
|
|
464
|
+
/**
|
|
465
|
+
* QueryPanel session ID for context-aware follow-ups.
|
|
466
|
+
* Use this to reuse a previously returned session for follow-up prompts.
|
|
467
|
+
*/
|
|
468
|
+
querypanelSessionId?: string;
|
|
438
469
|
}
|
|
470
|
+
/**
|
|
471
|
+
* Response returned after executing a query.
|
|
472
|
+
*/
|
|
439
473
|
interface AskResponse {
|
|
474
|
+
/** Generated SQL statement. */
|
|
440
475
|
sql: string;
|
|
476
|
+
/** Parameter values for the generated SQL. */
|
|
441
477
|
params: ParamRecord;
|
|
478
|
+
/** Raw parameter metadata from the backend. */
|
|
442
479
|
paramMetadata: Array<Record<string, unknown>>;
|
|
480
|
+
/** Optional reasoning for SQL generation. */
|
|
443
481
|
rationale?: string;
|
|
482
|
+
/** SQL dialect selected by the backend. */
|
|
444
483
|
dialect: string;
|
|
484
|
+
/** Optional query identifier for traceability. */
|
|
445
485
|
queryId?: string;
|
|
486
|
+
/** Result rows returned by the query execution. */
|
|
446
487
|
rows: Array<Record<string, unknown>>;
|
|
488
|
+
/** Column names for returned rows. */
|
|
447
489
|
fields: string[];
|
|
490
|
+
/** Generated chart payload. */
|
|
448
491
|
chart: ChartEnvelope;
|
|
492
|
+
/** Optional context documents used for query generation. */
|
|
449
493
|
context?: ContextDocument[];
|
|
494
|
+
/** Number of attempts used for execution. */
|
|
450
495
|
attempts?: number;
|
|
496
|
+
/** Target database name resolved by the backend or engine. */
|
|
451
497
|
target_db?: string;
|
|
498
|
+
/** QueryPanel session ID for follow-up queries. */
|
|
499
|
+
querypanelSessionId?: string;
|
|
452
500
|
}
|
|
453
501
|
declare function anonymizeResults(rows: Array<Record<string, unknown>>): Array<Record<string, string>>;
|
|
454
502
|
|
|
@@ -604,6 +652,93 @@ interface ChartModifyResponse extends AskResponse {
|
|
|
604
652
|
};
|
|
605
653
|
}
|
|
606
654
|
|
|
655
|
+
/**
|
|
656
|
+
* A single session turn containing the question and optional SQL output.
|
|
657
|
+
*/
|
|
658
|
+
interface SdkSessionTurn {
|
|
659
|
+
id: string;
|
|
660
|
+
session_id: string;
|
|
661
|
+
turn_index: number;
|
|
662
|
+
question: string;
|
|
663
|
+
sql: string | null;
|
|
664
|
+
rationale: string | null;
|
|
665
|
+
row_count: number | null;
|
|
666
|
+
fields: string[] | null;
|
|
667
|
+
error: string | null;
|
|
668
|
+
created_at: string;
|
|
669
|
+
}
|
|
670
|
+
/**
|
|
671
|
+
* Session metadata with optional turn history.
|
|
672
|
+
*/
|
|
673
|
+
interface SdkSession {
|
|
674
|
+
id: string;
|
|
675
|
+
session_id: string;
|
|
676
|
+
organization_id: string;
|
|
677
|
+
tenant_id: string | null;
|
|
678
|
+
user_id: string | null;
|
|
679
|
+
title: string | null;
|
|
680
|
+
created_at: string;
|
|
681
|
+
updated_at: string;
|
|
682
|
+
turns?: SdkSessionTurn[];
|
|
683
|
+
}
|
|
684
|
+
/**
|
|
685
|
+
* Fields allowed when updating a session.
|
|
686
|
+
*/
|
|
687
|
+
interface SessionUpdateInput {
|
|
688
|
+
title?: string;
|
|
689
|
+
}
|
|
690
|
+
/**
|
|
691
|
+
* Pagination settings for list endpoints.
|
|
692
|
+
*/
|
|
693
|
+
interface PaginationQuery {
|
|
694
|
+
page?: number;
|
|
695
|
+
limit?: number;
|
|
696
|
+
}
|
|
697
|
+
/**
|
|
698
|
+
* Pagination metadata returned by list endpoints.
|
|
699
|
+
*/
|
|
700
|
+
interface PaginationInfo {
|
|
701
|
+
page: number;
|
|
702
|
+
limit: number;
|
|
703
|
+
total: number;
|
|
704
|
+
totalPages: number;
|
|
705
|
+
hasNext: boolean;
|
|
706
|
+
hasPrev: boolean;
|
|
707
|
+
}
|
|
708
|
+
/**
|
|
709
|
+
* Generic paginated response wrapper.
|
|
710
|
+
*/
|
|
711
|
+
interface PaginatedResponse<T> {
|
|
712
|
+
data: T[];
|
|
713
|
+
pagination: PaginationInfo;
|
|
714
|
+
}
|
|
715
|
+
/**
|
|
716
|
+
* Options for listing sessions with filters and pagination.
|
|
717
|
+
*/
|
|
718
|
+
interface SessionListOptions {
|
|
719
|
+
tenantId?: string;
|
|
720
|
+
userId?: string;
|
|
721
|
+
scopes?: string[];
|
|
722
|
+
pagination?: PaginationQuery;
|
|
723
|
+
sortBy?: "title" | "user_id" | "created_at" | "updated_at";
|
|
724
|
+
sortDir?: "asc" | "desc";
|
|
725
|
+
title?: string;
|
|
726
|
+
userFilter?: string;
|
|
727
|
+
createdFrom?: string;
|
|
728
|
+
createdTo?: string;
|
|
729
|
+
updatedFrom?: string;
|
|
730
|
+
updatedTo?: string;
|
|
731
|
+
}
|
|
732
|
+
/**
|
|
733
|
+
* Options for retrieving a session.
|
|
734
|
+
*/
|
|
735
|
+
interface SessionGetOptions {
|
|
736
|
+
tenantId?: string;
|
|
737
|
+
userId?: string;
|
|
738
|
+
scopes?: string[];
|
|
739
|
+
includeTurns?: boolean;
|
|
740
|
+
}
|
|
741
|
+
|
|
607
742
|
interface VizSpecGenerateInput {
|
|
608
743
|
question: string;
|
|
609
744
|
sql: string;
|
|
@@ -700,6 +835,7 @@ declare class QueryPanelSdkAPI {
|
|
|
700
835
|
* console.log(result.sql); // Generated SQL
|
|
701
836
|
* console.log(result.rows); // Query results
|
|
702
837
|
* console.log(result.chart); // Vega-Lite chart spec
|
|
838
|
+
* console.log(result.querypanelSessionId); // Use for follow-ups
|
|
703
839
|
*
|
|
704
840
|
* // With automatic SQL repair on failure
|
|
705
841
|
* const result = await qp.ask("Show monthly trends", {
|
|
@@ -843,7 +979,81 @@ declare class QueryPanelSdkAPI {
|
|
|
843
979
|
* });
|
|
844
980
|
* ```
|
|
845
981
|
*/
|
|
846
|
-
listCharts(options?: ChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse<SdkChart>>;
|
|
982
|
+
listCharts(options?: ChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse$1<SdkChart>>;
|
|
983
|
+
/**
|
|
984
|
+
* Lists query sessions with pagination and filtering.
|
|
985
|
+
*
|
|
986
|
+
* @param options - Filtering, pagination, and sort options
|
|
987
|
+
* @param signal - Optional AbortSignal for cancellation
|
|
988
|
+
* @returns Paginated list of sessions
|
|
989
|
+
*
|
|
990
|
+
* @example
|
|
991
|
+
* ```typescript
|
|
992
|
+
* const sessions = await qp.listSessions({
|
|
993
|
+
* tenantId: "tenant_123",
|
|
994
|
+
* pagination: { page: 1, limit: 20 },
|
|
995
|
+
* sortBy: "updated_at",
|
|
996
|
+
* });
|
|
997
|
+
* ```
|
|
998
|
+
*/
|
|
999
|
+
listSessions(options?: SessionListOptions, signal?: AbortSignal): Promise<PaginatedResponse<SdkSession>>;
|
|
1000
|
+
/**
|
|
1001
|
+
* Retrieves a session by session_id with optional turn history.
|
|
1002
|
+
*
|
|
1003
|
+
* @param sessionId - QueryPanel session identifier used in ask()
|
|
1004
|
+
* @param options - Tenant, user, scopes, and includeTurns flag
|
|
1005
|
+
* @param signal - Optional AbortSignal for cancellation
|
|
1006
|
+
* @returns Session metadata with optional turns
|
|
1007
|
+
*
|
|
1008
|
+
* @example
|
|
1009
|
+
* ```typescript
|
|
1010
|
+
* const session = await qp.getSession("session_123", {
|
|
1011
|
+
* tenantId: "tenant_123",
|
|
1012
|
+
* includeTurns: true,
|
|
1013
|
+
* });
|
|
1014
|
+
* ```
|
|
1015
|
+
*/
|
|
1016
|
+
getSession(sessionId: string, options?: SessionGetOptions, signal?: AbortSignal): Promise<SdkSession>;
|
|
1017
|
+
/**
|
|
1018
|
+
* Updates session metadata (title).
|
|
1019
|
+
*
|
|
1020
|
+
* @param sessionId - QueryPanel session identifier to update
|
|
1021
|
+
* @param body - Fields to update
|
|
1022
|
+
* @param options - Tenant, user, and scope options
|
|
1023
|
+
* @param signal - Optional AbortSignal for cancellation
|
|
1024
|
+
* @returns Updated session
|
|
1025
|
+
*
|
|
1026
|
+
* @example
|
|
1027
|
+
* ```typescript
|
|
1028
|
+
* const updated = await qp.updateSession(
|
|
1029
|
+
* "session_123",
|
|
1030
|
+
* { title: "Q4 Revenue Analysis" },
|
|
1031
|
+
* { tenantId: "tenant_123" },
|
|
1032
|
+
* );
|
|
1033
|
+
* ```
|
|
1034
|
+
*/
|
|
1035
|
+
updateSession(sessionId: string, body: SessionUpdateInput, options?: {
|
|
1036
|
+
tenantId?: string;
|
|
1037
|
+
userId?: string;
|
|
1038
|
+
scopes?: string[];
|
|
1039
|
+
}, signal?: AbortSignal): Promise<SdkSession>;
|
|
1040
|
+
/**
|
|
1041
|
+
* Deletes a session and its turn history.
|
|
1042
|
+
*
|
|
1043
|
+
* @param sessionId - QueryPanel session identifier to delete
|
|
1044
|
+
* @param options - Tenant, user, and scope options
|
|
1045
|
+
* @param signal - Optional AbortSignal for cancellation
|
|
1046
|
+
*
|
|
1047
|
+
* @example
|
|
1048
|
+
* ```typescript
|
|
1049
|
+
* await qp.deleteSession("session_123", { tenantId: "tenant_123" });
|
|
1050
|
+
* ```
|
|
1051
|
+
*/
|
|
1052
|
+
deleteSession(sessionId: string, options?: {
|
|
1053
|
+
tenantId?: string;
|
|
1054
|
+
userId?: string;
|
|
1055
|
+
scopes?: string[];
|
|
1056
|
+
}, signal?: AbortSignal): Promise<void>;
|
|
847
1057
|
/**
|
|
848
1058
|
* Retrieves a single chart by ID with live data.
|
|
849
1059
|
*
|
|
@@ -955,7 +1165,7 @@ declare class QueryPanelSdkAPI {
|
|
|
955
1165
|
* });
|
|
956
1166
|
* ```
|
|
957
1167
|
*/
|
|
958
|
-
listActiveCharts(options?: ActiveChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse<SdkActiveChart>>;
|
|
1168
|
+
listActiveCharts(options?: ActiveChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse$1<SdkActiveChart>>;
|
|
959
1169
|
/**
|
|
960
1170
|
* Retrieves a single active chart by ID.
|
|
961
1171
|
*
|
|
@@ -1018,4 +1228,4 @@ declare class QueryPanelSdkAPI {
|
|
|
1018
1228
|
}, signal?: AbortSignal): Promise<void>;
|
|
1019
1229
|
}
|
|
1020
1230
|
|
|
1021
|
-
export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, 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 DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type FieldRef, type FieldRefInput, type FieldType, type IngestResponse, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse, type PaginationInfo, type PaginationQuery, type ParamRecord, type ParamValue, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, QueryPipelineError, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecResponse, anonymizeResults };
|
|
1231
|
+
export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, 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 DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type FieldRef, type FieldRefInput, type FieldType, type IngestResponse, 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, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, QueryPipelineError, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecResponse, anonymizeResults };
|
package/dist/index.d.ts
CHANGED
|
@@ -249,11 +249,11 @@ interface ChartUpdateInput {
|
|
|
249
249
|
spec_type?: 'vega-lite' | 'vizspec';
|
|
250
250
|
target_db?: string;
|
|
251
251
|
}
|
|
252
|
-
interface PaginationQuery {
|
|
252
|
+
interface PaginationQuery$1 {
|
|
253
253
|
page?: number;
|
|
254
254
|
limit?: number;
|
|
255
255
|
}
|
|
256
|
-
interface PaginationInfo {
|
|
256
|
+
interface PaginationInfo$1 {
|
|
257
257
|
page: number;
|
|
258
258
|
limit: number;
|
|
259
259
|
total: number;
|
|
@@ -261,15 +261,15 @@ interface PaginationInfo {
|
|
|
261
261
|
hasNext: boolean;
|
|
262
262
|
hasPrev: boolean;
|
|
263
263
|
}
|
|
264
|
-
interface PaginatedResponse<T> {
|
|
264
|
+
interface PaginatedResponse$1<T> {
|
|
265
265
|
data: T[];
|
|
266
|
-
pagination: PaginationInfo;
|
|
266
|
+
pagination: PaginationInfo$1;
|
|
267
267
|
}
|
|
268
268
|
interface ChartListOptions {
|
|
269
269
|
tenantId?: string;
|
|
270
270
|
userId?: string;
|
|
271
271
|
scopes?: string[];
|
|
272
|
-
pagination?: PaginationQuery;
|
|
272
|
+
pagination?: PaginationQuery$1;
|
|
273
273
|
sortBy?: "title" | "user_id" | "created_at" | "updated_at";
|
|
274
274
|
sortDir?: "asc" | "desc";
|
|
275
275
|
title?: string;
|
|
@@ -413,42 +413,90 @@ interface MetricSpec extends VizSpecBase {
|
|
|
413
413
|
}
|
|
414
414
|
type VizSpec = ChartSpec | TableSpec | MetricSpec;
|
|
415
415
|
|
|
416
|
+
/**
|
|
417
|
+
* Context document returned by the query pipeline.
|
|
418
|
+
*/
|
|
416
419
|
interface ContextDocument {
|
|
420
|
+
/** Optional source identifier for the document. */
|
|
417
421
|
source?: string;
|
|
422
|
+
/** Raw document content or excerpt. */
|
|
418
423
|
pageContent: string;
|
|
424
|
+
/** Additional metadata attached to the document. */
|
|
419
425
|
metadata?: Record<string, unknown>;
|
|
426
|
+
/** Optional relevance score from retrieval. */
|
|
420
427
|
score?: number;
|
|
421
428
|
}
|
|
429
|
+
/**
|
|
430
|
+
* Chart payload returned with query results.
|
|
431
|
+
*/
|
|
422
432
|
interface ChartEnvelope {
|
|
433
|
+
/** Vega-Lite spec when specType is "vega-lite". */
|
|
423
434
|
vegaLiteSpec?: Record<string, unknown> | null;
|
|
435
|
+
/** VizSpec payload when specType is "vizspec". */
|
|
424
436
|
vizSpec?: VizSpec | null;
|
|
437
|
+
/** Chart specification type. */
|
|
425
438
|
specType: "vega-lite" | "vizspec";
|
|
439
|
+
/** Optional chart generation notes or errors. */
|
|
426
440
|
notes: string | null;
|
|
427
441
|
}
|
|
442
|
+
/**
|
|
443
|
+
* Configuration options for query generation.
|
|
444
|
+
*/
|
|
428
445
|
interface AskOptions {
|
|
446
|
+
/** Tenant identifier for scoped access. */
|
|
429
447
|
tenantId?: string;
|
|
448
|
+
/** Optional user identifier for audit/telemetry. */
|
|
430
449
|
userId?: string;
|
|
450
|
+
/** Optional scopes to include in the auth token. */
|
|
431
451
|
scopes?: string[];
|
|
452
|
+
/** Override the default database name. */
|
|
432
453
|
database?: string;
|
|
454
|
+
/** Previous error message for retry context. */
|
|
433
455
|
lastError?: string;
|
|
456
|
+
/** Previous SQL statement for retry context. */
|
|
434
457
|
previousSql?: string;
|
|
458
|
+
/** Maximum number of retry attempts on execution failure. */
|
|
435
459
|
maxRetry?: number;
|
|
460
|
+
/** Maximum number of retries for chart generation. */
|
|
436
461
|
chartMaxRetries?: number;
|
|
462
|
+
/** Choose chart generation method. */
|
|
437
463
|
chartType?: "vega-lite" | "vizspec";
|
|
464
|
+
/**
|
|
465
|
+
* QueryPanel session ID for context-aware follow-ups.
|
|
466
|
+
* Use this to reuse a previously returned session for follow-up prompts.
|
|
467
|
+
*/
|
|
468
|
+
querypanelSessionId?: string;
|
|
438
469
|
}
|
|
470
|
+
/**
|
|
471
|
+
* Response returned after executing a query.
|
|
472
|
+
*/
|
|
439
473
|
interface AskResponse {
|
|
474
|
+
/** Generated SQL statement. */
|
|
440
475
|
sql: string;
|
|
476
|
+
/** Parameter values for the generated SQL. */
|
|
441
477
|
params: ParamRecord;
|
|
478
|
+
/** Raw parameter metadata from the backend. */
|
|
442
479
|
paramMetadata: Array<Record<string, unknown>>;
|
|
480
|
+
/** Optional reasoning for SQL generation. */
|
|
443
481
|
rationale?: string;
|
|
482
|
+
/** SQL dialect selected by the backend. */
|
|
444
483
|
dialect: string;
|
|
484
|
+
/** Optional query identifier for traceability. */
|
|
445
485
|
queryId?: string;
|
|
486
|
+
/** Result rows returned by the query execution. */
|
|
446
487
|
rows: Array<Record<string, unknown>>;
|
|
488
|
+
/** Column names for returned rows. */
|
|
447
489
|
fields: string[];
|
|
490
|
+
/** Generated chart payload. */
|
|
448
491
|
chart: ChartEnvelope;
|
|
492
|
+
/** Optional context documents used for query generation. */
|
|
449
493
|
context?: ContextDocument[];
|
|
494
|
+
/** Number of attempts used for execution. */
|
|
450
495
|
attempts?: number;
|
|
496
|
+
/** Target database name resolved by the backend or engine. */
|
|
451
497
|
target_db?: string;
|
|
498
|
+
/** QueryPanel session ID for follow-up queries. */
|
|
499
|
+
querypanelSessionId?: string;
|
|
452
500
|
}
|
|
453
501
|
declare function anonymizeResults(rows: Array<Record<string, unknown>>): Array<Record<string, string>>;
|
|
454
502
|
|
|
@@ -604,6 +652,93 @@ interface ChartModifyResponse extends AskResponse {
|
|
|
604
652
|
};
|
|
605
653
|
}
|
|
606
654
|
|
|
655
|
+
/**
|
|
656
|
+
* A single session turn containing the question and optional SQL output.
|
|
657
|
+
*/
|
|
658
|
+
interface SdkSessionTurn {
|
|
659
|
+
id: string;
|
|
660
|
+
session_id: string;
|
|
661
|
+
turn_index: number;
|
|
662
|
+
question: string;
|
|
663
|
+
sql: string | null;
|
|
664
|
+
rationale: string | null;
|
|
665
|
+
row_count: number | null;
|
|
666
|
+
fields: string[] | null;
|
|
667
|
+
error: string | null;
|
|
668
|
+
created_at: string;
|
|
669
|
+
}
|
|
670
|
+
/**
|
|
671
|
+
* Session metadata with optional turn history.
|
|
672
|
+
*/
|
|
673
|
+
interface SdkSession {
|
|
674
|
+
id: string;
|
|
675
|
+
session_id: string;
|
|
676
|
+
organization_id: string;
|
|
677
|
+
tenant_id: string | null;
|
|
678
|
+
user_id: string | null;
|
|
679
|
+
title: string | null;
|
|
680
|
+
created_at: string;
|
|
681
|
+
updated_at: string;
|
|
682
|
+
turns?: SdkSessionTurn[];
|
|
683
|
+
}
|
|
684
|
+
/**
|
|
685
|
+
* Fields allowed when updating a session.
|
|
686
|
+
*/
|
|
687
|
+
interface SessionUpdateInput {
|
|
688
|
+
title?: string;
|
|
689
|
+
}
|
|
690
|
+
/**
|
|
691
|
+
* Pagination settings for list endpoints.
|
|
692
|
+
*/
|
|
693
|
+
interface PaginationQuery {
|
|
694
|
+
page?: number;
|
|
695
|
+
limit?: number;
|
|
696
|
+
}
|
|
697
|
+
/**
|
|
698
|
+
* Pagination metadata returned by list endpoints.
|
|
699
|
+
*/
|
|
700
|
+
interface PaginationInfo {
|
|
701
|
+
page: number;
|
|
702
|
+
limit: number;
|
|
703
|
+
total: number;
|
|
704
|
+
totalPages: number;
|
|
705
|
+
hasNext: boolean;
|
|
706
|
+
hasPrev: boolean;
|
|
707
|
+
}
|
|
708
|
+
/**
|
|
709
|
+
* Generic paginated response wrapper.
|
|
710
|
+
*/
|
|
711
|
+
interface PaginatedResponse<T> {
|
|
712
|
+
data: T[];
|
|
713
|
+
pagination: PaginationInfo;
|
|
714
|
+
}
|
|
715
|
+
/**
|
|
716
|
+
* Options for listing sessions with filters and pagination.
|
|
717
|
+
*/
|
|
718
|
+
interface SessionListOptions {
|
|
719
|
+
tenantId?: string;
|
|
720
|
+
userId?: string;
|
|
721
|
+
scopes?: string[];
|
|
722
|
+
pagination?: PaginationQuery;
|
|
723
|
+
sortBy?: "title" | "user_id" | "created_at" | "updated_at";
|
|
724
|
+
sortDir?: "asc" | "desc";
|
|
725
|
+
title?: string;
|
|
726
|
+
userFilter?: string;
|
|
727
|
+
createdFrom?: string;
|
|
728
|
+
createdTo?: string;
|
|
729
|
+
updatedFrom?: string;
|
|
730
|
+
updatedTo?: string;
|
|
731
|
+
}
|
|
732
|
+
/**
|
|
733
|
+
* Options for retrieving a session.
|
|
734
|
+
*/
|
|
735
|
+
interface SessionGetOptions {
|
|
736
|
+
tenantId?: string;
|
|
737
|
+
userId?: string;
|
|
738
|
+
scopes?: string[];
|
|
739
|
+
includeTurns?: boolean;
|
|
740
|
+
}
|
|
741
|
+
|
|
607
742
|
interface VizSpecGenerateInput {
|
|
608
743
|
question: string;
|
|
609
744
|
sql: string;
|
|
@@ -700,6 +835,7 @@ declare class QueryPanelSdkAPI {
|
|
|
700
835
|
* console.log(result.sql); // Generated SQL
|
|
701
836
|
* console.log(result.rows); // Query results
|
|
702
837
|
* console.log(result.chart); // Vega-Lite chart spec
|
|
838
|
+
* console.log(result.querypanelSessionId); // Use for follow-ups
|
|
703
839
|
*
|
|
704
840
|
* // With automatic SQL repair on failure
|
|
705
841
|
* const result = await qp.ask("Show monthly trends", {
|
|
@@ -843,7 +979,81 @@ declare class QueryPanelSdkAPI {
|
|
|
843
979
|
* });
|
|
844
980
|
* ```
|
|
845
981
|
*/
|
|
846
|
-
listCharts(options?: ChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse<SdkChart>>;
|
|
982
|
+
listCharts(options?: ChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse$1<SdkChart>>;
|
|
983
|
+
/**
|
|
984
|
+
* Lists query sessions with pagination and filtering.
|
|
985
|
+
*
|
|
986
|
+
* @param options - Filtering, pagination, and sort options
|
|
987
|
+
* @param signal - Optional AbortSignal for cancellation
|
|
988
|
+
* @returns Paginated list of sessions
|
|
989
|
+
*
|
|
990
|
+
* @example
|
|
991
|
+
* ```typescript
|
|
992
|
+
* const sessions = await qp.listSessions({
|
|
993
|
+
* tenantId: "tenant_123",
|
|
994
|
+
* pagination: { page: 1, limit: 20 },
|
|
995
|
+
* sortBy: "updated_at",
|
|
996
|
+
* });
|
|
997
|
+
* ```
|
|
998
|
+
*/
|
|
999
|
+
listSessions(options?: SessionListOptions, signal?: AbortSignal): Promise<PaginatedResponse<SdkSession>>;
|
|
1000
|
+
/**
|
|
1001
|
+
* Retrieves a session by session_id with optional turn history.
|
|
1002
|
+
*
|
|
1003
|
+
* @param sessionId - QueryPanel session identifier used in ask()
|
|
1004
|
+
* @param options - Tenant, user, scopes, and includeTurns flag
|
|
1005
|
+
* @param signal - Optional AbortSignal for cancellation
|
|
1006
|
+
* @returns Session metadata with optional turns
|
|
1007
|
+
*
|
|
1008
|
+
* @example
|
|
1009
|
+
* ```typescript
|
|
1010
|
+
* const session = await qp.getSession("session_123", {
|
|
1011
|
+
* tenantId: "tenant_123",
|
|
1012
|
+
* includeTurns: true,
|
|
1013
|
+
* });
|
|
1014
|
+
* ```
|
|
1015
|
+
*/
|
|
1016
|
+
getSession(sessionId: string, options?: SessionGetOptions, signal?: AbortSignal): Promise<SdkSession>;
|
|
1017
|
+
/**
|
|
1018
|
+
* Updates session metadata (title).
|
|
1019
|
+
*
|
|
1020
|
+
* @param sessionId - QueryPanel session identifier to update
|
|
1021
|
+
* @param body - Fields to update
|
|
1022
|
+
* @param options - Tenant, user, and scope options
|
|
1023
|
+
* @param signal - Optional AbortSignal for cancellation
|
|
1024
|
+
* @returns Updated session
|
|
1025
|
+
*
|
|
1026
|
+
* @example
|
|
1027
|
+
* ```typescript
|
|
1028
|
+
* const updated = await qp.updateSession(
|
|
1029
|
+
* "session_123",
|
|
1030
|
+
* { title: "Q4 Revenue Analysis" },
|
|
1031
|
+
* { tenantId: "tenant_123" },
|
|
1032
|
+
* );
|
|
1033
|
+
* ```
|
|
1034
|
+
*/
|
|
1035
|
+
updateSession(sessionId: string, body: SessionUpdateInput, options?: {
|
|
1036
|
+
tenantId?: string;
|
|
1037
|
+
userId?: string;
|
|
1038
|
+
scopes?: string[];
|
|
1039
|
+
}, signal?: AbortSignal): Promise<SdkSession>;
|
|
1040
|
+
/**
|
|
1041
|
+
* Deletes a session and its turn history.
|
|
1042
|
+
*
|
|
1043
|
+
* @param sessionId - QueryPanel session identifier to delete
|
|
1044
|
+
* @param options - Tenant, user, and scope options
|
|
1045
|
+
* @param signal - Optional AbortSignal for cancellation
|
|
1046
|
+
*
|
|
1047
|
+
* @example
|
|
1048
|
+
* ```typescript
|
|
1049
|
+
* await qp.deleteSession("session_123", { tenantId: "tenant_123" });
|
|
1050
|
+
* ```
|
|
1051
|
+
*/
|
|
1052
|
+
deleteSession(sessionId: string, options?: {
|
|
1053
|
+
tenantId?: string;
|
|
1054
|
+
userId?: string;
|
|
1055
|
+
scopes?: string[];
|
|
1056
|
+
}, signal?: AbortSignal): Promise<void>;
|
|
847
1057
|
/**
|
|
848
1058
|
* Retrieves a single chart by ID with live data.
|
|
849
1059
|
*
|
|
@@ -955,7 +1165,7 @@ declare class QueryPanelSdkAPI {
|
|
|
955
1165
|
* });
|
|
956
1166
|
* ```
|
|
957
1167
|
*/
|
|
958
|
-
listActiveCharts(options?: ActiveChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse<SdkActiveChart>>;
|
|
1168
|
+
listActiveCharts(options?: ActiveChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse$1<SdkActiveChart>>;
|
|
959
1169
|
/**
|
|
960
1170
|
* Retrieves a single active chart by ID.
|
|
961
1171
|
*
|
|
@@ -1018,4 +1228,4 @@ declare class QueryPanelSdkAPI {
|
|
|
1018
1228
|
}, signal?: AbortSignal): Promise<void>;
|
|
1019
1229
|
}
|
|
1020
1230
|
|
|
1021
|
-
export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, 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 DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type FieldRef, type FieldRefInput, type FieldType, type IngestResponse, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse, type PaginationInfo, type PaginationQuery, type ParamRecord, type ParamValue, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, QueryPipelineError, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecResponse, anonymizeResults };
|
|
1231
|
+
export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, 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 DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type FieldRef, type FieldRefInput, type FieldType, type IngestResponse, 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, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, QueryPipelineError, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecResponse, anonymizeResults };
|