@querypanel/node-sdk 1.0.35 → 1.0.36
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 +62 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# QueryPanel Node SDK
|
|
2
2
|
|
|
3
|
-
A TypeScript-first client for the QueryPanel Bun/Hono API.
|
|
3
|
+
A TypeScript-first client for the QueryPanel Bun/Hono API. Its primary function is to **generate SQL from natural language**, but it also signs JWTs with your service private key, syncs database schemas, enforces tenant isolation, and wraps every public route under `src/routes/` (query, ingest, charts, active charts, and knowledge base).
|
|
4
4
|
|
|
5
5
|
## Installation
|
|
6
6
|
|
|
@@ -72,6 +72,67 @@ console.table(response.rows);
|
|
|
72
72
|
console.log(response.chart.vegaLiteSpec);
|
|
73
73
|
```
|
|
74
74
|
|
|
75
|
+
## Saving & Managing Charts
|
|
76
|
+
|
|
77
|
+
The SDK allows you to save generated charts to the QueryPanel system.
|
|
78
|
+
|
|
79
|
+
> **Privacy Note:** QueryPanel only stores the chart definition (SQL query, parameters, and Vega-Lite spec). We **never** store the actual result data rows. The data is fetched live from your database whenever the chart is rendered or refreshed.
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
// 1. Ask a question to generate a chart
|
|
83
|
+
const response = await qp.ask("Show revenue by country", {
|
|
84
|
+
tenantId: "tenant_123",
|
|
85
|
+
database: "analytics",
|
|
86
|
+
});
|
|
87
|
+
|
|
88
|
+
if (response.chart.vegaLiteSpec) {
|
|
89
|
+
// 2. Save the chart (only stores SQL + metadata, no data)
|
|
90
|
+
const savedChart = await qp.createChart({
|
|
91
|
+
title: "Revenue by Country",
|
|
92
|
+
sql: response.sql,
|
|
93
|
+
sql_params: response.params,
|
|
94
|
+
vega_lite_spec: response.chart.vegaLiteSpec,
|
|
95
|
+
query_id: response.queryId,
|
|
96
|
+
target_db: response.target_db,
|
|
97
|
+
}, {
|
|
98
|
+
tenantId: "tenant_123",
|
|
99
|
+
userId: "user_456" // Optional: associate with a user
|
|
100
|
+
});
|
|
101
|
+
|
|
102
|
+
console.log(`Chart saved with ID: ${savedChart.id}`);
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
// 3. List saved charts (History)
|
|
106
|
+
const charts = await qp.listCharts({ tenantId: "tenant_123" });
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Building a Dashboard (Active Charts)
|
|
110
|
+
|
|
111
|
+
While `createChart` and `listCharts` manage your **history** of saved queries, "Active Charts" are designed for building **dashboards**. You can "pin" a saved chart to a dashboard, control its order, and fetch it with live data in a single call.
|
|
112
|
+
|
|
113
|
+
```ts
|
|
114
|
+
// 1. Pin a saved chart to the dashboard
|
|
115
|
+
const activeChart = await qp.createActiveChart({
|
|
116
|
+
chart_id: "saved_chart_id_from_history",
|
|
117
|
+
order: 1, // Optional: for sorting in UI
|
|
118
|
+
meta: { width: "full", variant: "dark" } // Optional: UI layout hints
|
|
119
|
+
}, {
|
|
120
|
+
tenantId: "tenant_123"
|
|
121
|
+
});
|
|
122
|
+
|
|
123
|
+
// 2. Load the dashboard with live data
|
|
124
|
+
// Passing { withData: true } executes the SQL for each chart immediately
|
|
125
|
+
const dashboard = await qp.listActiveCharts({
|
|
126
|
+
tenantId: "tenant_123",
|
|
127
|
+
withData: true
|
|
128
|
+
});
|
|
129
|
+
|
|
130
|
+
dashboard.data.forEach(item => {
|
|
131
|
+
console.log(`Chart: ${item.chart?.title}`);
|
|
132
|
+
console.log(`Data points: ${item.chart?.vega_lite_spec.data.values.length}`);
|
|
133
|
+
});
|
|
134
|
+
```
|
|
135
|
+
|
|
75
136
|
## Building locally
|
|
76
137
|
|
|
77
138
|
```bash
|