Analytics Analytics protocol schemas
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
import { AnalyticsEndpoint, AnalyticsMetadataResponseSchema, AnalyticsQueryRequestSchema, AnalyticsResultResponseSchema, AnalyticsSqlResponseSchema, GetAnalyticsMetaRequestSchema } from '@objectstack/spec/api' ; import type { AnalyticsEndpoint, AnalyticsMetadataResponse, AnalyticsQueryRequest, AnalyticsSqlResponse, GetAnalyticsMetaRequest } from '@objectstack/spec/api' ; // Validate data const result = AnalyticsEndpoint. parse (data);
/api/v1/analytics/query/api/v1/analytics/meta/api/v1/analytics/sql
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { name: string; title?: string; measures: object[]; dimensions: object[] }[]✅ Available cubes, each as the CubeMeta discovery projection — the cube name, its title, 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.
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 anyoptional Filtering criteria (canonical Query DSL FilterCondition) timeDimensions { dimension: string; granularity?: Enum<'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'>; dateRange?: string | string[] }[]optional order Record<string, Enum<'asc' | 'desc'>>optional limit numberoptional offset numberoptional timezone stringoptional query neveroptional [REMOVED] query was removed from AnalyticsQueryRequest in @objectstack/spec 17.0.0 (#3878). The { cube, query: {...} } envelope was the dialect of the retired degraded analytics shim (#3891) — the real engine never understood it. Move the query.* fields to the body top level: { cube, measures, dimensions?, where?, timeDimensions?, order?, limit?, offset?, timezone? }. format neveroptional [REMOVED] format was removed from AnalyticsQueryRequest in @objectstack/spec 17.0.0 (#3878). It was never implemented — every response is the JSON envelope. Delete the key; for CSV/XLSX use the export surface instead.
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { rows: Record<string, any>[]; fields: object[]; sql?: string }✅
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { sql: string; params: any[] }✅
Property Type Required Description cube stringoptional Optional cube name to filter
ObjectStack