Catalog

The dataset catalog is a normalized metadata view of a dataset definition. Use it when another runtime needs to inspect the semantic model without reaching into dataset internals.

Catalog metadata includes:

• source table or view
• tenant and time keys
• dimensions and their labels, descriptions, columns, SQL expressions, and filter/group flags
• measures and their aggregation metadata
• attached named metrics
• filters, allowed operators, and filter value types
• relationship metadata, including whether each relationship is queryable and the qualified field names it contributes
• dataset limits, maximum result limit, supported time grains, and orderable fields

Dataset catalog

import { getDatasetCatalog } from '@hypequery/datasets';
import { Orders } from './datasets/orders.js';

const catalog = getDatasetCatalog(Orders);

console.log(catalog.dimensions.status);
console.log(catalog.measures.revenue);

The returned object is plain JSON-compatible metadata.

{
  "name": "orders",
  "source": "orders",
  "tenantKey": "tenant_id",
  "timeKey": "created_at",
  "dimensions": {
    "status": {
      "type": "string",
      "column": "status",
      "label": "Status",
      "filterable": true,
      "groupable": true
    }
  },
  "measures": {
    "revenue": {
      "aggregation": "sum",
      "field": "amount",
      "label": "Revenue",
      "filterCount": 0
    }
  },
  "metrics": {},
  "filters": {
    "status": {
      "field": "status",
      "operators": ["eq", "in"],
      "valueType": "string"
    }
  },
  "relationships": {},
  "limits": {
    "maxMeasures": 3,
    "maxResultSize": 1000
  },
  "requiresTenant": true,
  "supportedGrains": ["day", "week", "month", "quarter", "year"],
  "orderableFields": ["status", "revenue", "period"],
  "maxLimit": 1000
}

Relationship entries carry queryable and fields — the qualified <relationship>.<dimension> names a one-hop query may reference. To-one relationships (belongsTo, hasOne) are queryable; hasMany entries report queryable: false with an empty field list. See Relationships for the query semantics.

When a filter definition does not specify operators, the catalog exposes the default semantic operators from SEMANTIC_FILTER_OPERATORS:

import { SEMANTIC_FILTER_OPERATORS } from '@hypequery/datasets';

console.log(SEMANTIC_FILTER_OPERATORS);
// ["eq", "neq", "gt", "gte", "lt", "lte", "in", "notIn", "between", "like"]

Catalog maps

Use getDatasetCatalogs when you already have a dataset registry.

import { getDatasetCatalogs } from '@hypequery/datasets';
import { Customers, Orders } from './datasets/index.js';

const catalogs = getDatasetCatalogs({
  orders: Orders,
  customers: Customers,
});

Measures vs metrics

Measures are raw aggregations available in dataset queries. Metrics are named KPI handles created with dataset.metric(...).

By default, a dataset instance has measures but does not store every metric ref created from it. If a registry attaches named metric refs, the catalog includes them separately.

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

const catalog = getDatasetCatalog({
  ...Orders,
  metrics: { revenue },
});

console.log(catalog.measures.revenue);
console.log(catalog.metrics.revenue);

This is the same registry shape used by the MCP server. It lets get_dataset_schema show both the exploratory dataset measures and the named metrics that agents should use for stable KPIs.

Current consumers

The catalog is public in @hypequery/datasets. MCP introspection, MCP dataset listing, Serve endpoint descriptions, Serve OpenAPI input schemas, and generated dataset tools use it today to keep metadata aligned with real dataset definitions.

React metadata, CLI-generated labels, and broader cross-package drift tests are planned follow-up work.

For agent and function-calling schemas built from the same catalog, see Tool Generation.