---
title: Analytics
description: Analytics protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

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).

<Callout type="info">
**Source:** `packages/spec/src/data/analytics.zod.ts`
</Callout>

## TypeScript Usage

```typescript
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 |
| **where** | `[__schema0](./__schema0)` | optional | Filtering criteria (canonical Query DSL FilterCondition) |
| **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`


---

