Skip to content

Latest commit

 

History

History
278 lines (200 loc) · 20.3 KB

analytics.mdx

File metadata and controls

278 lines (200 loc) · 20.3 KB
title Analytics schema — API Protocol reference
navTitle Analytics
description Defines the HTTP interface for the Semantic Layer. Provides endpoints for executing analytical queries and discovering metadata.

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

Analytics API Protocol

Defines the HTTP interface for the Semantic Layer. Provides endpoints for executing analytical queries and discovering metadata.

**Source:** `packages/spec/src/api/analytics.zod.ts`

TypeScript Usage

import { AnalyticsEndpoint, AnalyticsMetadataResponseSchema, AnalyticsQueryRequestSchema, AnalyticsResultResponseSchema, AnalyticsSqlResponseSchema, DatasetCompareToSchema, DatasetSelectionSchema, DatasetTotalsSchema, GetAnalyticsMetaRequestSchema } from '@objectstack/spec/api';
import type { AnalyticsEndpoint, AnalyticsMetadataResponse, AnalyticsQueryRequest, AnalyticsResultResponse, AnalyticsSqlResponse, DatasetCompareTo, DatasetSelection, DatasetTotals, GetAnalyticsMetaRequest } from '@objectstack/spec/api';

// Validate data
const result = AnalyticsEndpoint.parse(data);

AnalyticsEndpoint

Allowed Values

  • /api/v1/analytics/query
  • /api/v1/analytics/meta
  • /api/v1/analytics/sql

AnalyticsMetadataResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { name: string; title?: string; description?: string; measures: object[]; … }[] ✅ Available cubes, each as the CubeMeta discovery projection — the cube name, its title and description, and the measures/dimensions a client may name in a query. A bare array: there is no cubes wrapper object, and no cube sql is published.

Nested Shape: AnalyticsMetadataResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: AnalyticsMetadataResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: AnalyticsMetadataResponse.data[number]

Property Type Required Description
name string ✅ Cube name
title string optional Human-readable cube title
description string optional Cube description, projected from the cube definition's description
measures { name: string; type: string; title?: string; description?: string; … }[] ✅ Measures this cube accepts in /analytics/query
dimensions { name: string; type: string; title?: string; description?: string }[] ✅ Dimensions this cube accepts in /analytics/query

AnalyticsQueryRequest

Properties

Property Type Required Description
cube string ✅ Target cube name
measures string[] ✅ List of metrics to calculate
dimensions string[] optional List of dimensions to group by
where any optional Filtering criteria (canonical Query DSL FilterCondition). An authored FilterArray is lowered by parseFilterAST on the client before the wire; this field admits only the lowered FilterCondition (see FilterArray in data/filter.zod.ts).
timeDimensions { dimension: string; granularity?: Enum<'day' | 'week' | 'month' | 'quarter' | 'year'>; dateRange?: Enum<'today' | 'yesterday' | 'this_week' | 'last_week' | 'this_month' | 'last_month' | …> | [string, string] }[] optional Time-bucketed dimensions. Each entry names a dimension, an optional bucket granularity, and an optional dateRange — a preset name from the closed date-range vocabulary (e.g. 'last_7_days') or an explicit [start, end] window; an unrecognised string answers 400 ANALYTICS_DATE_RANGE_UNRECOGNIZED instead of silently widening.
order Record<string, Enum<'asc' | 'desc'>> optional
limit integer optional Maximum number of rows to return, applied after order — a non-negative integer (0 returns no rows)
offset integer optional Number of rows to skip before the first row returned, applied after order — a non-negative integer; an offset with no limit returns every row after it
timezone string optional

Nested Shape: AnalyticsQueryRequest.timeDimensions[number]

Property Type Required Description
dimension string ✅
granularity Enum<'day' | 'week' | 'month' | 'quarter' | 'year'> optional
dateRange Enum<'today' | 'yesterday' | 'this_week' | 'last_week' | 'this_month' | 'last_month' | …> | [string, string] optional Time window for this dimension: a date-range PRESET name from the closed vocabulary in data/date-range-presets.ts (today, yesterday, this_week, last_week, this_month, last_month, this_quarter, last_quarter, this_year, last_year, last_7_days, last_30_days, last_90_days — e.g. 'last_7_days'), or an explicit [start, end] array of ISO dates / {date-macro} tokens (e.g. ["2023-01-01", "2023-01-31"]). Any other string is refused at the schema with 400 ANALYTICS_DATE_RANGE_UNRECOGNIZED.

AnalyticsResultResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { rows: Record<string, any>[]; fields: object[]; sql?: string; totals?: object[]; … } ✅

Nested Shape: AnalyticsResultResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: AnalyticsResultResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: AnalyticsResultResponse.data

Property Type Required Description
rows Record<string, any>[] ✅ Result rows
fields { name: string; type: string; label?: string; format?: string; … }[] ✅ Column metadata
sql string optional Executed SQL (if debug enabled)
totals { dimensions: string[]; rows: Record<string, any>[] }[] optional Marginal aggregates - one entry per requested totals grouping, in request order, each computed with the measure's true aggregate over the underlying data (never re-derived from bucketed values). The grand-total grouping yields a single dimensionless row.
object string optional The base object of the dataset the answer was computed from: the dataset's object, by machine name. Every dataset answer (POST /analytics/dataset/query) must carry it, whatever dimensions are selected and whether or not rows came back, so a consumer can refresh on that object's record changes and drill into its records. Absent on a cube query answer, which has no dataset behind it.
dimensionFields Record<string, string> optional Drill-through sidecar: each equality-drillable dimension the answer is grouped by, dimension name to that dataset dimension's own field (a base-object field or a relationship.field path). Set only on a dataset answer (POST /analytics/dataset/query) that has rows and groups by at least one dimension with a field that is not type: 'date'; a date dimension is never listed (see drillRanges). Absent on a cube query answer.
drillRawRows Record<string, any>[] optional Drill-through sidecar, aligned to rows by index: each dimensionFields dimension name to the stored value that row was grouped by (a select option's value, a lookup's record id), captured before label resolution rewrites the row to its display label. An exact-match drill filter is built from these, not from the labels in rows. Set exactly when dimensionFields is.
drillRawTotals Record<string, any>[][] optional Drill-through sidecar for totals: entry [i][j] aligns to totals[i].rows[j] and holds the stored value of the dimensionFields dimensions that grouping groups by, so the grand-total grouping yields an empty map per row. Set only when dimensionFields is and the answer carries at least one totals grouping.
drillRanges Record<string, { field: string; gte: string; lt: string }>[] optional Drill-through sidecar for time buckets, aligned to rows by index: date dimension name to the half-open range [gte, lt) that row's bucket covers. Bounds are YYYY-MM-DD calendar days, or ISO-8601 instants at midnight in the reference timezone when the source field is datetime; a row whose bucket value is null gets no entry for that dimension. Set only on a dataset answer that has rows and groups by at least one type: 'date' dimension with a field and a granularity; independent of dimensionFields. Absent on a cube query answer.

AnalyticsSqlResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { sql: string; params: any[] } ✅

Nested Shape: AnalyticsSqlResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: AnalyticsSqlResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

DatasetCompareTo

Properties

Property Type Required Description
kind Enum<'previousPeriod' | 'previousYear'> ✅ Comparison window: previousPeriod (equal-length, immediately before) or previousYear (the same window one calendar year back)
dimension string optional Time dimension to shift; omit when the selection has exactly one dated time dimension

DatasetSelection

Properties

Property Type Required Description
dimensions string[] optional List of dimensions to group by
measures string[] ✅ List of metrics to calculate
runtimeFilter any optional Presentation-scope filter (canonical Query DSL FilterCondition), ANDed with the dataset's intrinsic filter at render
timeDimensions { dimension: string; granularity?: Enum<'day' | 'week' | 'month' | 'quarter' | 'year'>; dateRange?: Enum<'today' | 'yesterday' | 'this_week' | 'last_week' | 'this_month' | 'last_month' | …> | [string, string] }[] optional Time-bucketed dimensions. Each entry names a dimension, an optional bucket granularity, and an optional dateRange — a preset name from the closed date-range vocabulary (e.g. 'last_7_days') or an explicit [start, end] window; an unrecognised string answers 400 ANALYTICS_DATE_RANGE_UNRECOGNIZED instead of silently widening.
dateGranularity Enum<'day' | 'week' | 'month' | 'quarter' | 'year'> optional Presentation-scope date bucketing applied to every selected date dimension; an explicit timeDimensions entry wins over it, and the dataset dimension's own default is used when neither is set
order Record<string, Enum<'asc' | 'desc'>> optional
limit integer optional Maximum number of rows to return, applied after order — a non-negative integer (0 returns no rows)
offset integer optional Number of rows to skip before the first row returned, applied after order — a non-negative integer; an offset with no limit returns every row after it
compareTo { kind: Enum<'previousPeriod' | 'previousYear'>; dimension?: string } optional Period-over-period comparison window ({ kind, dimension? }); attaches <measure>__compare columns
totals { groupings: string[][] } optional Server-side marginal aggregates; each grouping is a dimension subset to additionally aggregate by, [] being the grand total
timezone string optional

Nested Shape: DatasetSelection.timeDimensions[number]

Property Type Required Description
dimension string ✅
granularity Enum<'day' | 'week' | 'month' | 'quarter' | 'year'> optional
dateRange Enum<'today' | 'yesterday' | 'this_week' | 'last_week' | 'this_month' | 'last_month' | …> | [string, string] optional Time window for this dimension: a date-range PRESET name from the closed vocabulary in data/date-range-presets.ts (today, yesterday, this_week, last_week, this_month, last_month, this_quarter, last_quarter, this_year, last_year, last_7_days, last_30_days, last_90_days — e.g. 'last_7_days'), or an explicit [start, end] array of ISO dates / {date-macro} tokens (e.g. ["2023-01-01", "2023-01-31"]). Any other string is refused at the schema with 400 ANALYTICS_DATE_RANGE_UNRECOGNIZED.

Nested Shape: DatasetSelection.compareTo

Property Type Required Description
kind Enum<'previousPeriod' | 'previousYear'> ✅ Comparison window: previousPeriod (equal-length, immediately before) or previousYear (the same window one calendar year back)
dimension string optional Time dimension to shift; omit when the selection has exactly one dated time dimension

Nested Shape: DatasetSelection.totals

Property Type Required Description
groupings string[][] ✅ Dimension subsets to additionally aggregate by, in request order; the empty subset is the grand total

DatasetTotals

Properties

Property Type Required Description
groupings string[][] ✅ Dimension subsets to additionally aggregate by, in request order; the empty subset is the grand total

GetAnalyticsMetaRequest

Properties

Property Type Required Description
cube string optional Optional cube name to filter