nocobase/nocobase · error

sql is required

Error message

sql is required

What it means

ChartResource.run() in the data-visualization client-v2 executes a chart data query against the 'charts:queryData' API. When the chart's query mode is 'sql', the chart data must include a non-empty `sql` property; if it does not, the resource throws 'sql is required' before making any request, because a SQL-mode chart cannot produce results without a SQL statement.

Source

Thrown at packages/plugins/@nocobase/plugin-data-visualization/src/client-v2/flow/resources/ChartResource.ts:154

      contextParams: query.contextParams,
    };
    return data;
  }

  // 查询数据
  async run() {
    const data = this.request.data || {};
    // 尝试从已有字段推断模式；但若无法推断则直接跳过，避免切换时抛错
    const mode: 'sql' | 'builder' | undefined = data.mode ?? (data.sql ? 'sql' : undefined);

    if (!mode) {
      // 未配置模式时，认为尚未完成查询参数设置：不抛错、不请求 API，返回现有数据
      return { data: this.getData(), meta: this.getMeta?.() };
    }

    if (mode === 'sql') {
      if (!data.sql) {
        throw new Error('sql is required');
      }
    } else {
      // builder 模式
      if (!data.collection || !data.measures?.length) {
        throw new Error('collection and measures are required');
      }
    }

    // 请求数据 api.post('charts:queryData')
    return await this.runAction<TData, any>('queryData', this.getRefreshRequestOptions());
  }

  // debounce 刷新数据
  async refresh() {
    debugLog('---ChartResource refresh');
    if (this.refreshTimer) {
      clearTimeout(this.refreshTimer);
    }

View on GitHub (pinned to fa42722fef)

Solutions

1. Set a non-empty `data.sql` value in the chart configuration before calling run()
2. Check chart settings UI: open the chart's query settings and paste/complete the SQL statement, then save
3. If creating charts programmatically, include `sql` in the data payload (e.g. { mode: 'sql', sql: 'SELECT ...' })
4. Use mode 'builder' instead if you intend to configure collection/measures rather than raw SQL

Example fix

// before
await chartResource.run({ data: { mode: 'sql' } });
// after
await chartResource.run({ data: { mode: 'sql', sql: 'SELECT count(*) FROM users' } });

const chart = { mode: 'sql', sql: sqlInput };
if (chart.mode === 'sql' && !chart.sql) {
  throw new Error('Refusing to run: sql mode chart has no sql statement');
}
await chartResource.run({ data: chart });

function hasSqlChart(data: unknown): data is { mode: 'sql'; sql: string } {
  return !!data && typeof data === 'object' && (data as any).mode === 'sql' && typeof (data as any).sql === 'string' && (data as any).sql.trim().length > 0;
}

try {
  await chartResource.run({ data: chartData });
} catch (err) {
  if (err.message === 'sql is required') {
    openChartConfigPanel(); // prompt user to complete SQL settings
  } else {
    throw err;
  }
}

When it happens

Trigger: Calling run() on a chart whose `data.mode === 'sql'` while `data.sql` is undefined, null, or empty — e.g. the chart config was saved before the user typed a SQL statement, or config fields were renamed/stripped by a form or schema transform.

Common situations: Programmatically creating chart blocks via API or workflow with only mode='sql' set; a partial save of the chart settings form; copying chart options but forgetting the sql field; switching mode to 'sql' client-side without populating sql before calling run()/refresh().

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• collection and measures are required
• chart query.mode='sql' does not support: ${unsupportedKeys.j
• SQL cannot be empty
• Invalid aggregation function: ${aggregation}
• SQL is empty

AI-assisted analysis of nocobase/nocobase@fa42722fef (2026-09-01). Data as JSON: /api/errors/457d7673079b73a4. Report an issue: GitHub.