@kweaver-ai/kweaver-sdk 0.6.1 → 0.6.2

package/README.md

@@ -126,9 +126,18 @@ const result = await client.dataflows.execute({
   steps: [{ id: "s1", title: "load", operator: "csv_import", parameters: {} }],
 });
 
-// Vega observability
+// Vega — observability and query
 const catalogs = await client.vega.listCatalogs();
 const health   = await client.vega.health();
+// Structured query — POST /api/vega-backend/v1/query/execute (JSON string body)
+const structured = await client.vega.executeQuery(
+  JSON.stringify({ tables: [{ resource_id: "res-1" }], output_fields: ["*"], limit: 20 }),
+);
+// Direct SQL or OpenSearch DSL — POST /api/vega-backend/v1/resources/query
+// Use {{resource_id}} placeholders so vega-backend routes to the correct catalog connector.
+const rows = await client.vega.sqlQuery(
+  JSON.stringify({ query: "SELECT * FROM {{res-1}} LIMIT 5", resource_type: "mysql" }),
+);
 
 // Context Loader (semantic search over a BKN via MCP)
 const cl      = client.contextLoader(mcpUrl, "bkn-id");
@@ -164,7 +173,7 @@ kweaver bkn action-execution get
 kweaver bkn action-log list/get/cancel
 kweaver agent list/get/create/update/delete/chat/sessions/history/publish/unpublish
 kweaver skill list/market/get/register/status/delete/content/read-file/download/install
-kweaver vega health/stats/inspect/catalog/resource/connector-type
+kweaver vega health/stats/inspect/sql/catalog/resource/connector-type
 kweaver context-loader config set/use/list/show
 kweaver context-loader kn-search/query-object-instance/...
 kweaver call <path> [-X METHOD] [-d BODY] [-H header]
@@ -184,6 +193,20 @@ kweaver dataflow logs <dagId> <instanceId> --detail
 
 `kweaver dataflow runs --since` filters one local natural day. If the value cannot be parsed by `new Date(...)`, the CLI falls back to the most recent 20 runs. `kweaver dataflow logs` defaults to summary output; add `--detail` to print indented `input` and `output` payloads.
 
+### Vega `sql` CLI examples
+
+Direct SQL against catalog-backed resources (`POST /api/vega-backend/v1/resources/query`). In SQL, use **`{{<resource_id>}}`** or **`{{.<resource_id>}}`** (Vega resource id from `vega resource list` / `get`) so the backend resolves the physical table and connector. `--resource-type` accepts the connector type of the target data source (run `kweaver vega connector-type list` to see available types). In simple mode, **quote the entire `--query` value** so the shell does not treat `{` / `}` specially.
+
+```bash
+# Simple mode (recommended): avoid JSON-escaping the query string
+kweaver vega sql --resource-type mysql --query "SELECT * FROM {{res-1}} LIMIT 5"
+
+# Advanced mode: full JSON body (optional fields like query_timeout, stream_size, OpenSearch DSL object)
+kweaver vega sql -d '{"resource_type":"mysql","query":"SELECT * FROM {{res-1}} LIMIT 5"}'
+```
+
+If both `-d` and `--query` / `--resource-type` are present, **only `-d` is used**.
+
 **No-auth platforms:** If OAuth is not enabled, use `kweaver auth <url> --no-auth` (or run a normal `auth login`; a **404** on `POST /oauth2/clients` switches to no-auth automatically). Credentials are still saved under `~/.kweaver/` and work with `auth use` / `auth list`. Optional: `KWEAVER_NO_AUTH=1` with `KWEAVER_BASE_URL` when no token env is set. SDK: `new KWeaverClient({ baseUrl, auth: false })` or `kweaver.configure({ baseUrl, auth: false })`.
 
 ## Environment Variables

package/README.zh.md

@@ -119,6 +119,19 @@ const queryRows = await client.dataviews.query(viewId, {
   needTotal: true,
 });
 
+// Vega — 可观测性与查询
+const catalogs = await client.vega.listCatalogs();
+const health   = await client.vega.health();
+// 结构化查询 — POST /api/vega-backend/v1/query/execute（body 为 JSON 字符串）
+const structured = await client.vega.executeQuery(
+  JSON.stringify({ tables: [{ resource_id: "res-1" }], output_fields: ["*"], limit: 20 }),
+);
+// 直连 SQL 或 OpenSearch DSL — POST /api/vega-backend/v1/resources/query
+// 使用 {{resource_id}} 占位符以路由到正确的 catalog connector
+const rows = await client.vega.sqlQuery(
+  JSON.stringify({ query: "SELECT * FROM {{res-1}} LIMIT 5", resource_type: "mysql" }),
+);
+
 // Context Loader（通过 MCP 对 BKN 做语义搜索）
 const cl      = client.contextLoader(mcpUrl, "bkn-id");
 const results = await cl.search({ query: "高血压 治疗" });
@@ -149,6 +162,7 @@ kweaver bkn action-execution get
 kweaver bkn action-log list/get/cancel
 kweaver agent list/get/chat/sessions/history
 kweaver skill list/market/get/register/status/delete/content/read-file/download/install
+kweaver vega health|stats|inspect|sql|catalog|resource|connector-type
 kweaver context-loader config set/use/list/show
 kweaver context-loader kn-search/query-object-instance/...
 kweaver call <path> [-X METHOD] [-d BODY] [-H header]
@@ -168,6 +182,20 @@ kweaver dataflow logs <dagId> <instanceId> --detail
 
 `kweaver dataflow runs --since` 会按本地自然日过滤；如果参数无法被 `new Date(...)` 解析，CLI 会回退到最近 20 条运行记录。`kweaver dataflow logs` 默认输出摘要；加上 `--detail` 会打印带缩进的 `input` 和 `output` 载荷。
 
+### Vega `sql` CLI 示例
+
+对 Catalog 资源执行直连 SQL（`POST /api/vega-backend/v1/resources/query`）。SQL 中使用 **`{{<resource_id>}}`** 或 **`{{.<resource_id>}}`**（资源 id 来自 `vega resource list` / `get`），后端据此解析物理表与 connector。`--resource-type` 为目标数据源的连接器类型，可通过 `kweaver vega connector-type list` 查看。简单模式下请**用引号包住整个 `--query` 参数**，避免 shell 对花括号做特殊处理。
+
+```bash
+# 简单模式（推荐）：避免在 JSON 里转义整段 SQL
+kweaver vega sql --resource-type mysql --query "SELECT * FROM {{res-1}} LIMIT 5"
+
+# 高级模式：完整 JSON（可带 query_timeout、stream_size，或 OpenSearch DSL 对象等）
+kweaver vega sql -d '{"resource_type":"mysql","query":"SELECT * FROM {{res-1}} LIMIT 5"}'
+```
+
+若同时提供 `-d` 与 `--query` / `--resource-type`，**仅以 `-d` 为准**。
+
 **无 OAuth 的平台：** 使用 `kweaver auth <url> --no-auth`，或照常 `auth login`；若 `POST /oauth2/clients` 返回 **404**，CLI 会提示并自动保存为 no-auth。凭据仍在 `~/.kweaver/`，可用 `auth use` / `auth list` 切换。可选环境变量 `KWEAVER_NO_AUTH=1`（未设置 `KWEAVER_TOKEN` 时）配合 `KWEAVER_BASE_URL`。SDK：`new KWeaverClient({ baseUrl, auth: false })` 或 `kweaver.configure({ baseUrl, auth: false })`。
 
 ## 环境变量

package/dist/api/vega.d.ts

@@ -220,6 +220,14 @@ export interface ExecuteVegaQueryOptions {
     businessDomain?: string;
 }
 export declare function executeVegaQuery(options: ExecuteVegaQueryOptions): Promise<string>;
+export interface VegaSQLQueryOptions {
+    baseUrl: string;
+    accessToken: string;
+    body: string;
+    businessDomain?: string;
+}
+/** POST /api/vega-backend/v1/resources/query — direct SQL (or OpenSearch DSL) against catalog-backed resources. */
+export declare function vegaSQLQuery(options: VegaSQLQueryOptions): Promise<string>;
 export interface ListAllVegaResourcesOptions {
     baseUrl: string;
     accessToken: string;

package/dist/api/vega.js

@@ -458,6 +458,24 @@ export async function executeVegaQuery(options) {
         throw new HttpError(response.status, response.statusText, body);
     return body;
 }
+/** POST /api/vega-backend/v1/resources/query — direct SQL (or OpenSearch DSL) against catalog-backed resources. */
+export async function vegaSQLQuery(options) {
+    const { baseUrl, accessToken, body: requestBody, businessDomain = "bd_public" } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}${VEGA_BASE}/resources/query`;
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+        },
+        body: requestBody,
+    });
+    const body = await response.text();
+    if (!response.ok)
+        throw new HttpError(response.status, response.statusText, body);
+    return body;
+}
 export async function listAllVegaResources(options) {
     const { baseUrl, accessToken, limit, offset, businessDomain = "bd_public" } = options;
     const base = baseUrl.replace(/\/+$/, "");

package/dist/cli.js

@@ -102,6 +102,7 @@ Usage:
   kweaver vega health|stats|inspect
   kweaver vega catalog list|get|health|test-connection|discover|resources [options]
   kweaver vega resource list|get|query [options]
+  kweaver vega query execute|sql [options]
   kweaver vega connector-type list|get [options]
 
   kweaver context-loader config set|use|list|remove|show [options]
@@ -128,7 +129,7 @@ Commands:
                  object-type, relation-type, subgraph, action-type, action-execution, action-log)
   config         Per-platform configuration (business domain)
   skill          Skill registry and market (register, search, progressive read, download/install)
-  vega           Vega observability (catalog, resource, connector-type, health/stats/inspect)
+  vega           Vega observability (catalog, resource, query/sql, connector-type, health/stats/inspect)
   context-loader Context-loader MCP (config, tools, resources, prompts, kn-search, query-*, etc.)
   help           Show this message`);
 }

package/dist/commands/vega.js

@@ -1,6 +1,6 @@
 import { createInterface } from "node:readline";
 import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
-import { vegaHealth, listVegaCatalogs, getVegaCatalog, createVegaCatalog, updateVegaCatalog, deleteVegaCatalogs, vegaCatalogHealthStatus, testVegaCatalogConnection, discoverVegaCatalog, listVegaCatalogResources, listVegaResources, getVegaResource, queryVegaResourceData, createVegaResource, updateVegaResource, deleteVegaResources, listVegaConnectorTypes, getVegaConnectorType, registerVegaConnectorType, updateVegaConnectorType, deleteVegaConnectorType, setVegaConnectorTypeEnabled, createVegaDatasetDocs, updateVegaDatasetDocs, deleteVegaDatasetDocs, deleteVegaDatasetDocsQuery, buildVegaDataset, getVegaDatasetBuildStatus, executeVegaQuery, listAllVegaResources, } from "../api/vega.js";
+import { vegaHealth, listVegaCatalogs, getVegaCatalog, createVegaCatalog, updateVegaCatalog, deleteVegaCatalogs, vegaCatalogHealthStatus, testVegaCatalogConnection, discoverVegaCatalog, listVegaCatalogResources, listVegaResources, getVegaResource, queryVegaResourceData, createVegaResource, updateVegaResource, deleteVegaResources, listVegaConnectorTypes, getVegaConnectorType, registerVegaConnectorType, updateVegaConnectorType, deleteVegaConnectorType, setVegaConnectorTypeEnabled, createVegaDatasetDocs, updateVegaDatasetDocs, deleteVegaDatasetDocs, deleteVegaDatasetDocsQuery, buildVegaDataset, getVegaDatasetBuildStatus, executeVegaQuery, vegaSQLQuery, listAllVegaResources, } from "../api/vega.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
 // ---------------------------------------------------------------------------
@@ -35,7 +35,9 @@ Subcommands:
   dataset delete-docs-query <resource-id> -d <filter-json>
   dataset build <resource-id> [--mode full|incremental|realtime]
   dataset build-status <resource-id> <task-id>
-  query execute -d <json>
+  query execute -d <json>               Structured query (tables, joins, filters)
+  sql --resource-type <t> --query <sql>  Direct SQL / DSL; use {{<resource_id>}} in SQL (quoted)
+  sql -d <json>                         Same API with full JSON body (advanced)
   connector-type list                 List connector types
   connector-type get <type>           Get connector type details
   connector-type register -d <json>   Register a new connector type
@@ -103,6 +105,8 @@ export async function runVegaCommand(args) {
             return runVegaDatasetCommand(rest);
         if (subcommand === "query")
             return runVegaQueryCommand(rest);
+        if (subcommand === "sql")
+            return runVegaSql(rest);
         if (subcommand === "connector-type")
             return runVegaConnectorTypeCommand(rest);
         return Promise.resolve(-1);
@@ -1321,6 +1325,101 @@ Options:
     return 0;
 }
 // ---------------------------------------------------------------------------
+// sql (POST /resources/query)
+// ---------------------------------------------------------------------------
+async function runVegaSql(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(`kweaver vega sql --resource-type <type> --query "<sql-or-dsl>"
+kweaver vega sql -d <json>
+
+POST /api/vega-backend/v1/resources/query — execute SQL (MySQL/MariaDB/PostgreSQL) or OpenSearch DSL.
+
+Simple mode (no JSON escaping for query + type):
+  --resource-type <t>   Required with --query unless using -d
+  --query <string>      One shell argument: the full SQL (or DSL string). Always quote it.
+
+Advanced mode (full request body, optional fields):
+  -d, --data <json>     Raw JSON body. When present, this mode is used and any --query / --resource-type are ignored.
+
+Resource placeholders (how to reference Vega tables in SQL):
+  {{<resource_id>}}     Required token form: double braces around the Vega resource id (from vega resource list / get).
+  {{.<resource_id>}}    Alternate form with a dot after {{ ; same replacement and routing.
+
+  The backend swaps each placeholder for that resource's physical SourceIdentifier and picks the catalog connector.
+  Without at least one placeholder, queries often fail (e.g. connector config is incomplete) unless a default connector exists.
+
+  Shell (simple mode) — wrap the whole SQL so braces are not interpreted by the shell:
+    kweaver vega sql --resource-type mysql --query "SELECT * FROM {{abc123xyz}} LIMIT 5"
+
+  Shell (-d mode) — placeholders live inside the JSON string value; use single quotes around the JSON so inner double quotes work:
+    kweaver vega sql -d '{"resource_type":"mysql","query":"SELECT * FROM {{abc123xyz}} LIMIT 5"}'
+
+Body fields (JSON / simple mode mapping):
+  query          (required) SQL string or OpenSearch DSL object
+  resource_type  (required) e.g. mysql, mariadb, postgresql, opensearch (see vega connector-type list)
+  stream_size    optional batch size for streaming (100–10000, default 10000)
+  query_timeout  optional seconds (1–3600, default 60)
+  query_id       optional cursor session id
+
+Do not use --type; use --resource-type.
+
+Common flags:
+  -bd, --biz-domain <s>   Business domain (default: bd_public)
+  --pretty               Pretty-print JSON (default)`);
+        return 0;
+    }
+    let data;
+    let query;
+    let resourceType;
+    const { remaining, businessDomain, pretty } = parseCommonFlags(args);
+    for (let i = 0; i < remaining.length; i += 1) {
+        const arg = remaining[i];
+        if (arg === "--type") {
+            console.error("Use --resource-type instead of --type (e.g. --resource-type mysql).");
+            return 1;
+        }
+        if ((arg === "-d" || arg === "--data") && remaining[i + 1]) {
+            data = remaining[++i];
+            continue;
+        }
+        if (arg === "--query" && remaining[i + 1]) {
+            query = remaining[++i];
+            continue;
+        }
+        if (arg === "--resource-type" && remaining[i + 1]) {
+            resourceType = remaining[++i];
+            continue;
+        }
+    }
+    let requestBody;
+    if (data !== undefined) {
+        try {
+            JSON.parse(data);
+        }
+        catch {
+            console.error(`Invalid JSON: ${data}`);
+            return 1;
+        }
+        requestBody = data;
+    }
+    else {
+        if (!query || !resourceType) {
+            console.error("Usage: kweaver vega sql --resource-type <type> --query \"<sql-or-dsl>\"\n       kweaver vega sql -d <json>");
+            return 1;
+        }
+        requestBody = JSON.stringify({ query, resource_type: resourceType });
+    }
+    const token = await ensureValidToken();
+    const body = await vegaSQLQuery({
+        baseUrl: token.baseUrl,
+        accessToken: token.accessToken,
+        body: requestBody,
+        businessDomain,
+    });
+    console.log(formatCallOutput(body, pretty));
+    return 0;
+}
+// ---------------------------------------------------------------------------
 // Connector-type router
 // ---------------------------------------------------------------------------
 async function runVegaConnectorTypeCommand(args) {

package/dist/resources/vega.d.ts

@@ -47,6 +47,8 @@ export declare class VegaResource {
     buildDataset(id: string, mode?: string): Promise<unknown>;
     getDatasetBuildStatus(id: string, taskId: string): Promise<unknown>;
     executeQuery(body: string): Promise<unknown>;
+    /** POST /resources/query — direct SQL or OpenSearch DSL (see kweaver vega sql --help). */
+    sqlQuery(body: string): Promise<unknown>;
     listAllResources(opts?: {
         limit?: number;
         offset?: number;

package/dist/resources/vega.js

@@ -1,4 +1,4 @@
-import { vegaHealth, listVegaCatalogs, getVegaCatalog, createVegaCatalog, updateVegaCatalog, deleteVegaCatalogs, vegaCatalogHealthStatus, testVegaCatalogConnection, discoverVegaCatalog, listVegaCatalogResources, listVegaResources, getVegaResource, queryVegaResourceData, createVegaResource, updateVegaResource, deleteVegaResources, createVegaDatasetDocs, updateVegaDatasetDocs, deleteVegaDatasetDocs, deleteVegaDatasetDocsQuery, buildVegaDataset, getVegaDatasetBuildStatus, executeVegaQuery, listAllVegaResources, listVegaConnectorTypes, getVegaConnectorType, registerVegaConnectorType, updateVegaConnectorType, deleteVegaConnectorType, setVegaConnectorTypeEnabled, } from "../api/vega.js";
+import { vegaHealth, listVegaCatalogs, getVegaCatalog, createVegaCatalog, updateVegaCatalog, deleteVegaCatalogs, vegaCatalogHealthStatus, testVegaCatalogConnection, discoverVegaCatalog, listVegaCatalogResources, listVegaResources, getVegaResource, queryVegaResourceData, createVegaResource, updateVegaResource, deleteVegaResources, createVegaDatasetDocs, updateVegaDatasetDocs, deleteVegaDatasetDocs, deleteVegaDatasetDocsQuery, buildVegaDataset, getVegaDatasetBuildStatus, executeVegaQuery, vegaSQLQuery, listAllVegaResources, listVegaConnectorTypes, getVegaConnectorType, registerVegaConnectorType, updateVegaConnectorType, deleteVegaConnectorType, setVegaConnectorTypeEnabled, } from "../api/vega.js";
 function unwrapArray(raw) {
     const parsed = JSON.parse(raw);
     if (Array.isArray(parsed))
@@ -114,6 +114,11 @@ export class VegaResource {
         const raw = await executeVegaQuery({ ...this.ctx.base(), body });
         return JSON.parse(raw);
     }
+    /** POST /resources/query — direct SQL or OpenSearch DSL (see kweaver vega sql --help). */
+    async sqlQuery(body) {
+        const raw = await vegaSQLQuery({ ...this.ctx.base(), body });
+        return JSON.parse(raw);
+    }
     // ── Resource List All ──────────────────────────────────────────────────────
     async listAllResources(opts = {}) {
         const raw = await listAllVegaResources({ ...this.ctx.base(), ...opts });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kweaver-ai/kweaver-sdk",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "KWeaver TypeScript SDK — CLI tool and programmatic API for knowledge networks and Decision Agents.",
   "type": "module",
   "main": "./dist/index.js",