Skip to main content

Cubes

Manage Cube.dev semantic model definitions. Cubes define the metrics, dimensions, and joins that power your analytics queries.

Verbs: list, get, create, update, delete, query, meta

Usage​

revos cubes list [--page-size <n>] [--order-by <field>] [--columns <cols>] [--json]
revos cubes get <cube-id> [--json]
revos cubes create --body JSON|@file|- [--json]
revos cubes update <cube-id> --body JSON|@file|- [--json]
revos cubes delete <cube-id> [--json]
revos cubes meta [--json]
revos cubes query --query JSON|@file|- [--json]

The recommended way to manage cubes is through YAML files in your project's cubes/ directory, using revos apply, revos pull, and revos diff. See Project scaffolding for details.

apiVersion: revos/v1
kind: Cube
metadata:
  name: revenue-metrics # local slug (kebab-case)
spec:
  name: revenue_metrics # the cube identifier — snake_case (${CUBE}, joins, queries)
  sql_table: "`my_project.my_dataset.gold_revenue`"
  dimensions:
    id:
      sql: "${CUBE}.id"
      type: string
      primary_key: true
  measures:
    count:
      type: count

spec.name is the cube identifier — snake_case (revenue_metrics), referenced by ${CUBE}, cross-cube joins, and queries (Orders.count). It must be a valid SQL/JS identifier (the compiler rejects hyphens). metadata.name is the local slug — kebab-case (revenue-metrics) by convention, like every other resource. It's the filename and IaC address, never sent to the API, so renaming it (and the file) is a local-only move while editing spec.name renames the cube upstream. Every Cube.dev field — sql_table, dimensions, measures, joins, meta — sits directly under spec.

revos apply          # push local cube files to the API
revos pull           # import remote cubes into local YAML
revos diff           # preview drift without making changes

Migration from legacy auto-generated cubes​

If your org previously relied on auto-generated cube definitions, you can migrate in one step. Ask Claude Code (or any AI assistant with revos api access) to do it for you:

"Fetch GET /cubes/preview via revos api, convert each cube into an IaC YAML file under cubes/, then run revos apply."

The AI will call the endpoint, transform the JSON response into the correct apiVersion: revos/v1 / kind: Cube YAML format, write the files, and push them.

Once revos apply succeeds, the org switches to reading cubes directly from the database — auto-generation is bypassed.

Querying the semantic model​

revos cubes meta lists every cube and view in the semantic model together with its measures, dimensions, and segments. Use it to discover the member names that you can reference in a query.

revos cubes query runs a Cube.js query and prints the resulting rows. --query accepts inline JSON, @path/to/file.json, or - to read from stdin. The payload may be a bare query object or wrapped as { "query": { ... } }. Rows render as a table by default; pass --json for the full response payload.

revos cubes meta
revos cubes meta --json | jq '.cubes[0]'

# inline
revos cubes query --query '{"measures":["Orders.count"]}'

# file
revos cubes query --query @./query.json --json

# stdin
echo '{"measures":["Orders.count"],"dimensions":["Orders.status"]}' | revos cubes query

Examples​

revos cubes list --json
revos cubes list --columns id,name
revos cubes get cube_123
revos cubes create --body @./my-cube.json
revos cubes update cube_123 --body '{"definition":{"sql_table":"gold.revenue"}}'
revos cubes delete cube_123