Back to Details

cap-apps-data-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Rule: Domo App Platform Data Access (Toolkit-First)

规则：Domo应用平台数据访问（工具优先）

This rule is toolkit/query-first. Use 
@domoinc/query
for dataset reads in apps.
Legacy endpoint-first guidance has been archived to 
archive/legacy-rules/domo-data-api.md
.
本规则遵循工具/查询优先原则。在应用中读取数据集时请使用
@domoinc/query
。
旧版的端点优先指南已归档至
archive/legacy-rules/domo-data-api.md
。

Canonical Query Approach

标准查询方法

1) Use 
@domoinc/query
for dataset queries

1) 使用
@domoinc/query
进行数据集查询

bash
yarn add @domoinc/query
typescript
import Query from '@domoinc/query';

const salesByRegion = await new Query()
  .select(['region', 'Sales_Amount'])
  .groupBy('region', { Sales_Amount: 'sum' })
  .orderBy('Sales_Amount', 'descending')
  .fetch('sales');
bash
yarn add @domoinc/query
typescript
import Query from '@domoinc/query';

const salesByRegion = await new Query()
  .select(['region', 'Sales_Amount'])
  .groupBy('region', { Sales_Amount: 'sum' })
  .orderBy('Sales_Amount', 'descending')
  .fetch('sales');

2) Keep SQL as exception-only

2) 仅在特殊情况下使用SQL

If you use SQL (
SqlClient
), remember it does not automatically respect page filters in dashboards.
typescript
import { SqlClient } from '@domoinc/toolkit';

const sqlClient = new SqlClient();
const result = await sqlClient.get(
  'sales',
  'SELECT region, SUM(Sales_Amount) AS total FROM sales GROUP BY region'
);
const rows = result.body.rows;
如果使用SQL（
SqlClient
），请注意它不会自动遵循仪表板中的页面筛选器。
typescript
import { SqlClient } from '@domoinc/toolkit';

const sqlClient = new SqlClient();
const result = await sqlClient.get(
  'sales',
  'SELECT region, SUM(Sales_Amount) AS total FROM sales GROUP BY region'
);
const rows = result.body.rows;

Required Manifest Wiring

必要的清单配置

Every dataset still must be declared in 
manifest.json
under 
datasetsMapping
.
json
{
  "datasetsMapping": [
    { "alias": "sales", "dataSetId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "fields": [] }
  ]
}
Critical gotcha:
  • fields
    must exist (can be 
    []
    ) to avoid manifest parsing errors.
每个数据集仍必须在
manifest.json
的
datasetsMapping
中声明。
json
{
  "datasetsMapping": [
    { "alias": "sales", "dataSetId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "fields": [] }
  ]
}
重要注意事项：
  • fields
    必须存在（可以是
    []
    ），以避免清单解析错误。

Local Development

本地开发

  • Use 
    @domoinc/ryuu-proxy
    for local API routing.
  • Authenticate with 
    domo login
    .
  • 使用
    @domoinc/ryuu-proxy
    进行本地API路由。
  • 使用
    domo login
    进行身份验证。

Canonical Rules References

标准规则参考

  • Query patterns and caveats: 
    .cursor/rules/03-query.mdc
  • Performance constraints: 
    .cursor/rules/10-performance-optimization.mdc
  • Query gotchas: 
    .cursor/rules/09-gotchas.mdc
  • 查询模式与注意事项：
    .cursor/rules/03-query.mdc
  • 性能约束：
    .cursor/rules/10-performance-optimization.mdc
  • 查询常见问题：
    .cursor/rules/09-gotchas.mdc

Checklist

检查清单

  • datasetsMapping
    aliases configured and valid
  • Queries implemented with 
    Query
    (not raw 
    /data/v1
    by default)
  • Aggregations use actual dataset field names
  • .aggregate()
    not used
  • 已配置并验证
    datasetsMapping
    别名
  • 使用
    Query
    实现查询（默认不使用原生
    /data/v1
    ）
  • 聚合操作使用实际的数据集字段名
  • 未使用
    .aggregate()
    方法