apache/superset · error

When using 'Group By' you are limited to use a single metric

Error message

When using 'Group By' you are limited to use a single metric

What it means

The Time-table chart's buildQuery enforces a legacy constraint from TimeTableViz.query_obj: when a Group By dimension is set, the query may only aggregate a single metric. With groupby present and more than one metric selected the client-side query builder aborts before any request is sent.

Source

Thrown at superset-frontend/src/visualizations/TimeTable/config/buildQuery.ts:36

 */
import { t } from '@apache-superset/core/translation';
import {
  buildQueryContext,
  ensureIsArray,
  QueryFormData,
} from '@superset-ui/core';

/**
 * Mirrors the legacy TimeTableViz.query_obj: a timeseries query ordered
 * by the first metric (ascending unless order_desc), limited to a single
 * metric when grouped.
 */
export default function buildQuery(formData: QueryFormData) {
  const { order_desc, groupby } = formData;
  return buildQueryContext(formData, baseQueryObject => {
    const metrics = ensureIsArray(baseQueryObject.metrics);
    if (ensureIsArray(groupby).length > 0 && metrics.length > 1) {
      throw new Error(
        t("When using 'Group By' you are limited to use a single metric"),
      );
    }
    const firstMetric = metrics[0];
    return [
      {
        ...baseQueryObject,
        is_timeseries: true,
        orderby: firstMetric ? [[firstMetric, !order_desc]] : undefined,
      },
    ];
  });
}

View on GitHub (pinned to f4587218dd)

Solutions

1. Remove the Group By entry, or reduce Metrics to exactly one metric.
2. If multiple metrics per group are needed, switch to a Pivot Table or Table chart.
3. Fix imported chart JSON: set metrics to a single entry before loading the dashboard.
4. Add a control-level warning in a custom plugin fork so users see the constraint before save.

Example fix

// before (form_data)
"metrics": ["sum__sales", "avg__price"],
"groupby": ["region"]

// after
"metrics": ["sum__sales"],
"groupby": ["region"]

import { ensureIsArray } from '@superset-ui/core';

function isValidTimeTableForm(formData: QueryFormData): boolean {
  const grouped = ensureIsArray(formData.groupby).length > 0;
  const metricCount = ensureIsArray(formData.metrics).length;
  return !grouped || metricCount <= 1;
}

try {
  await buildQuery(formData);
} catch (e) {
  if (e instanceof Error && e.message.includes('single metric')) {
    setControlValue('metrics', [currentFirstMetric]); // auto-repair
    return;
  }
  throw e;
}

When it happens

Trigger: In Explore, adding a dimension to Group By while Metrics contains 2+ entries on a Time-table chart; loading/importing a saved Time-table chart whose form_data has both multiple metrics and a non-empty groupby.

Common situations: Copying form_data from a Pivot/Table chart into Time-table; dashboards imported from older versions where validation was looser; editing an existing Time-table and adding a second metric without removing Group By.

Related errors

• Group by param is required
• Longitude and latitude columns are required
• Chart ${id} is missing form_data
• Please call with an object. Example: `stringify myObj`
• Unknown deck.gl layer type: ${vizType}

AI-assisted analysis of apache/superset@f4587218dd (2026-08-14). Data as JSON: /api/errors/a6cd3ab80dd7c8a2. Report an issue: GitHub.