mcpField
S
sql-query

sql-query

github.com/stahura数据与数据库24196 次安装26 周前更新
代码仓库

关于 sql-query

面向在 Domo 数据集上执行 SQL 的开发者，SqlClient 是 @domoinc/toolkit 提供的 SQL API 封装。它可将页面筛选器转换为 SQL 条件；由于 SQL 接口不自动应用页面筛选器，需要按需手动加入。

主要功能

  1. 01通过数据集别名执行 SQL
  2. 02将页面筛选器解析为 SQL 条件
  3. 03返回列与行组成的列式结果
  4. 04配合 AIClient 文本转 SQL

适用场景

  1. 01查询 manifest.json 中映射的数据集
  2. 02在 SQL 查询中手动应用页面筛选器
  3. 03执行 AIClient 生成的 SQL

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/stahura/domo-ai-vibe-rules --skill sql-query

安装后在 Claude Code 中输入/sql-query确认已加载。

详细介绍

@domoinc/toolkit - SqlClient

何时使用此技能

在针对 Domo 数据集执行 SQL 查询、使用来自 AIClient.text_to_sql 的 AI 生成 SQL，或者任何时候你需要针对数据集别名运行原始 SQL 时使用。使用来自 @domoinc/toolkit 的 SqlClient，而不是 domo.post('/sql/v1/')。

概述

SqlClient 是 Domo 的 SQL API 的工具包封装。使用它针对 manifest.json 中映射的数据集执行 SQL 查询。

导入与实例化

import { SqlClient } from '@domoinc/toolkit';

const sqlClient = new SqlClient();

方法

get(alias, query)

针对数据集执行 SQL 查询。

const result = await sqlClient.get('datasetAlias', 'SELECT * FROM datasetAlias');

参数：

  • alias（string）：来自 manifest.json 映射的数据集别名
  • query（string）：SQL 查询字符串

返回：Promise<Response<SqlResponse>>

parsePageFilters(datasets, produceClauses?)

将 Domo 页面筛选器转换为 SQL 谓词。

// Get predicates as objects
const predicates = sqlClient.parsePageFilters(['datasetAlias']);

// Get predicates as WHERE/HAVING clause strings
const clauses = sqlClient.parsePageFilters(['datasetAlias'], true);

响应格式

关键：SQL API 返回列式格式，而不是行对象数组。

// Response shape:
{
  columns: ['vendor', 'Total Spend'],
  rows: [
    ['Sysco Utah', 1880794.74],
    ['Intermountain Meats', 809389.15]
  ],
  metadata: [...],
  numRows: 8,
  numColumns: 2,
  datasource: 'dataset-uuid',
  fromcache: true
}

你必须将 columns + rows 拼接为对象以便 UI 渲染：

const result = await sqlClient.get('myAlias', sql);
const res = result?.body || result?.data || result;
const colNames: string[] = res?.columns || [];
const rawRows: unknown[][] = res?.rows || [];

const rows = rawRows.map((row) => {
  const obj: Record<string, unknown> = {};
  colNames.forEach((col, i) => {
    obj[col] = row[i];
  });
  return obj;
});
// rows => [{ vendor: 'Sysco Utah', 'Total Spend': 1880794.74 }, ...]

常见模式：AI text-to-SQL + SqlClient

使用 AIClient 生成 SQL，然后使用 SqlClient 执行它：

import { AIClient, SqlClient } from '@domoinc/toolkit';

// 1) Generate SQL from natural language
const aiResponse = await AIClient.text_to_sql(question, [
  {
    dataSourceName: 'myAlias',
    description: 'Description of the dataset',
    columns: [
      { name: 'vendor', type: 'string' },
      { name: 'amount', type: 'number' }
    ]
  }
]);
const responseBody = aiResponse.data || aiResponse.body || aiResponse;
const sql = responseBody.output || responseBody.choices?.[0]?.output;

// 2) Execute SQL
const sqlClient = new SqlClient();
const result = await sqlClient.get('myAlias', sql);

// 3) Parse columnar response into row objects
const res = result?.body || result?.data || result;
const colNames: string[] = res?.columns || [];
const rawRows: unknown[][] = res?.rows || [];
const rows = rawRows.map((row) => {
  const obj: Record<string, unknown> = {};
  colNames.forEach((col, i) => {
    obj[col] = row[i];
  });
  return obj;
});

重要说明

  • 使用 SqlClient，而不是 domo.post('/sql/v1/')。
  • SQL 端点会忽略页面筛选器；需要时使用 parsePageFilters() 手动注入筛选器。
  • SQL FROM 中的数据集别名必须与 manifest 别名匹配（例如：SELECT * FROM vendorPayments）。
  • 响应始终为列式（columns + rows），绝不是扁平的对象数组。
  • 响应可能位于 .body、.data 中，或直接位于结果上；请以防御性方式解析。

评论

支持 Markdown