sql-query

@domoinc/toolkit - SqlClient

このスキルを使う場面

Domo データセットに対して SQL クエリを実行するとき、AIClient.text_to_sql が生成した SQL を使用するとき、またはデータセットエイリアスに対して生の SQL を実行する必要があるときに適用します。domo.post('/sql/v1/') ではなく、@domoinc/toolkit の SqlClient を使用してください。

概要

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
}

UI で表示するには、columns と rows を組み合わせてオブジェクトにする必要があります。

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 によるテキストから 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;
});

重要な注意事項

• domo.post('/sql/v1/') ではなく、SqlClient を使用してください。
• SQL エンドポイントはページフィルターを無視します。必要に応じて、parsePageFilters() を使ってフィルターを手動で追加してください。
• SQL の FROM に指定するデータセットエイリアスは、manifest のエイリアスと一致している必要があります（例：SELECT * FROM vendorPayments）。
• レスポンスは常に列指向形式（columns + rows）であり、フラットなオブジェクト配列ではありません。
• レスポンスは .body、.data、または結果に直接含まれる場合があります。安全に解析してください。