API Considerations

This page tracks API considerations for future semantic catalog work. It is not required reading for the current datasets API, but it explains which parts are intentional compatibility bridges and which parts are likely to become first-class APIs.

Measures and metrics naming

Dataset queries use measures.

await analytics.execute(Orders, {
  dimensions: ['country'],
  measures: ['revenue', 'orderCount'],
});

Named KPI handles use metrics.

const revenue = Orders.metric('revenue', {
  measure: 'revenue',
});

MCP previously accepted metrics in query_dataset for the values that are now correctly described as dataset measures. Because Hypequery is still in 0.x, the MCP API now breaks that old argument and accepts measures only.

Longer term:

• query_dataset should document and prefer measures.
• the old metrics dataset-query argument should stay removed rather than carried forward as an alias.
• named metrics should be queried through query_metric, not through dataset measure selection.

Attached metric refs

The current MCP registry convention can attach named metric refs to a dataset object.

const revenue = Orders.metric('revenue', {
  measure: 'revenue',
});

export const datasets = {
  orders: {
    ...Orders,
    metrics: { revenue },
  },
};

This shape is useful today because it preserves existing MCP configuration and lets getDatasetCatalog() include named metrics when they are present.

It is still an interim shape. A dataset instance does not own every metric handle created from it; metric handles are separate values returned by dataset.metric(...). Spreading metrics back onto the dataset object is a registry convention, not the final semantic catalog model.

Future catalog API

A future API should make the registry explicit.

const catalog = createSemanticCatalog({
  datasets: {
    orders: Orders,
  },
  metrics: {
    revenue,
    averageOrderValue,
  },
});

const orders = catalog.getDataset('orders');

Another possible shape is dataset-scoped metrics.

const catalog = createSemanticCatalog({
  datasets: {
    orders: Orders,
  },
  metrics: {
    orders: {
      revenue,
      averageOrderValue,
    },
  },
});

The important property is that datasets and named metric refs are registered intentionally instead of being discovered from ad hoc object spreading.

Compatibility boundary

The current getDatasetCatalog() API should stay small:

• it reads one dataset-like object
• it includes attached named metrics when present
• it does not introduce Serve, OpenAPI, React, or CLI coupling

Follow-up work can build on top of this with an explicit semantic catalog registry. That larger API should be designed once Serve metadata, OpenAPI generation, MCP tools, React metadata, and CLI code generation all consume the same source.