Analytics

Analytics/Semantic Layer Protocol

Defines the "Business Logic" for data analysis.

Inspired by Cube.dev, LookML, and dbt MetricFlow.

This layer decouples the "Physical Data" (Tables/Columns) from the

"Business Data" (Metrics/Dimensions).

Source: packages/spec/src/data/analytics.zod.ts

TypeScript Usage

import { AggregationMetricType, AnalyticsQuery, Cube, CubeJoin, Dimension, DimensionType, Metric, TimeUpdateInterval } from '@objectstack/spec/data';
import type { AggregationMetricType, AnalyticsQuery, Cube, CubeJoin, Dimension, DimensionType, Metric, TimeUpdateInterval } from '@objectstack/spec/data';

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

AggregationMetricType

Allowed Values

count
sum
avg
min
max
count_distinct
number
string
boolean

AnalyticsQuery

Properties

Property	Type	Required	Description
cube	`string`	optional	Target cube name (optional when provided externally, e.g. in API request wrapper)
measures	`string[]`	✅	List of metrics to calculate
dimensions	`string[]`	optional	List of dimensions to group by
filters	`Object[]`	optional
timeDimensions	`Object[]`	optional
order	`Record<string, Enum<'asc' \| 'desc'>>`	optional
limit	`number`	optional
offset	`number`	optional
timezone	`string`	✅

Cube

Properties

Property	Type	Required	Description
name	`string`	✅	Cube name (snake_case)
title	`string`	optional
description	`string`	optional
sql	`string`	✅	Base SQL statement or Table Name
measures	`Record<string, Object>`	✅	Quantitative metrics
dimensions	`Record<string, Object>`	✅	Qualitative attributes
joins	`Record<string, Object>`	optional
refreshKey	`Object`	optional
public	`boolean`	✅

CubeJoin

Properties

Property	Type	Required	Description
name	`string`	✅	Target cube name
relationship	`Enum<'one_to_one' \| 'one_to_many' \| 'many_to_one'>`	✅
sql	`string`	✅	Join condition (ON clause)

Dimension

Properties

Property	Type	Required	Description
name	`string`	✅	Unique dimension ID
label	`string`	✅	Human readable label
description	`string`	optional
type	`Enum<'string' \| 'number' \| 'boolean' \| 'time' \| 'geo'>`	✅
sql	`string`	✅	SQL expression or column reference
granularities	`Enum<'second' \| 'minute' \| 'hour' \| 'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>[]`	optional

DimensionType

Allowed Values

string
number
boolean
time
geo

Metric

Properties

Property	Type	Required	Description
name	`string`	✅	Unique metric ID
label	`string`	✅	Human readable label
description	`string`	optional
type	`Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct' \| 'number' \| 'string' \| 'boolean'>`	✅
sql	`string`	✅	SQL expression or field reference
filters	`Object[]`	optional
format	`string`	optional

TimeUpdateInterval

Allowed Values

second
minute
hour
day
week
month
quarter
year

On this page