Metric Query

Gateway prefix: ${API_BASE}/data/metric/...

Parameters (MetricQueryParams)

• dimensions string array, optional, dimension columns such as channel, country
• filter object, optional, Predicate (same structure as where in Query)
• time object, optional, time configuration (same as QueryRequest.time)
• limit number, optional
• offset number, optional

Dimensions and aggregation

• Metric definitions usually contain default aggregations (such as SUM(amount) or COUNT(*)).
• When dimensions is provided, the result is grouped and aggregated by those dimensions.
• Dimension fields must exist in the underlying entity/view or be derivable; otherwise a field error is returned.

Supported filter operators

• eq, ne, gt, gte, lt, lte, in, not_in, like, ilike, between, is_null, is_not_null

Single metric query

• POST /metric/{metricName}/query

Example (with dimensions and filters):

curl -X POST \
  "${API_BASE}/data/metric/revenue/query" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: tenant-abc123" \
  -d '{
    "dimensions": ["channel"],
    "filter": { "type":"logical", "op":"and", "conditions":[
      { "type":"comparison", "field":"country", "op":"eq", "value":"US" },
      { "type":"comparison", "field":"status", "op":"eq", "value":"PAID" }
    ]},
    "time": { "time_field":"order_date", "time_range": { "preset":"last_30_days" }, "grain":"day" },
    "limit": 50
  }'

Example response:

{"success": true, "data": {"columns": ["channel", "revenue"], "rows": [["web", 5000], ["store", 3000]]}}

Batch metric query

• POST /metric/query/batch

Request body:

• metrics: string[] required, list of metric names
• params: MetricQueryParams optional, shared parameters

Example:

curl -X POST \
  "${API_BASE}/data/metric/query/batch" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: tenant-abc123" \
  -d '{
    "metrics": ["revenue", "orders_count"],
    "params": {"dimensions":["channel"], "limit": 10}
  }'

Example response:

{
  "success": true,
  "data": {
    "revenue": {"columns": ["channel","revenue"], "rows": [["web",5000]]},
    "orders_count": {"columns": ["channel","orders_count"], "rows": [["web",120]]}
  }
}

Common error examples

• Unknown metric:

{"success": false, "message":"Metric not found: gmv", "errorCode":"METRIC_NOT_FOUND"}

• Invalid dimension:

{"success": false, "message":"Dimension 'region' not available for metric 'revenue'", "errorCode":"METRIC_QUERY_FAILED"}

• Invalid filter:

{"success": false, "message":"Operator 'BETWEEN' requires array or {from,to}", "errorCode":"METRIC_QUERY_FAILED"}