Skip to content
footnote Docs
Install

The Cube connector

Read metrics and dimensions from Cube model files, in a Git repository or a folder on the server. A read needs no running Cube server, no database and no warehouse access, and it never stores SQL or a calculation.

What your model needs

  1. A folder of YAML model files. JavaScript, Python and Jinja templates are skipped, and a symbolic link is never followed.
  2. It compiles with Cube 1.8.27, the version the connector is pinned to.
  3. At least one public view or public cube. Only public members are listed.

Recommended in the model:

KeyWhereWhat it does
titleEach public memberIts name on screen
descriptionEach public memberWhat it means
meta.domainEach viewIts domain, exactly as a domain id. A member’s own meta.domain overrides it
meta.synonymsA memberA list of other names people use, such as [geo, market], each for one term

Connect a model in Git

An admin adds it in Settings, Integrations:

FieldWhat it is
RepositoryThe https address of the repository, without credentials
Branch, tag or commitWhat is read. A tag or a commit holds still, and a branch moves with each change
Model folderThe folder of model files in the repository. Empty for the top
Read-only tokenKept in the secret store. Empty for a public repository
User name for the tokenSent with the token, x-access-token when empty. Most hosts accept any
Model folder addressThe folder in the host’s web view, for links to each model file
Domain namesEach meta.domain value and the domain it means, when the two differ

Test connection reaches the repository, counts the model files, then reads the model once and keeps nothing.

Each read fetches one commit and removes it afterwards. See how Git is reached.

A domain name applies before a domain is checked. With the line paid_media → area_paid_media, a view whose meta.domain is paid_media has the domain area_paid_media. A name without a line stays as the model says it.

Read a model on the server

Whoever runs the service sets these, and Integrations shows them read only:

SettingWhat it does
CUBE_MODEL_DIRThe folder to read. Unset, the service reads two invented definitions
FOOTNOTE_DOMAIN_OVERRIDESA JSON file outside the model folder: view to domain, for views the model names no domain for
CUBE_RENAMES_FILEA JSON file of renamed members, old id to new id
CUBE_VIEWS_FILEA JSON file of the views to read, until an admin chooses them in the app. See the views it reads

To read a folder now, without changing it:

Terminal window
CUBE_MODEL_DIR=/path/to/cube/model npm run connectors:sync

The command reads .env.local, prints what it found and flagged, and exits with 1 on a failed read.

Domain overrides

{ "sales_analytics": "finance", "campaign_analytics": "paid_media" }

Keys are exact public view or cube names. A valid meta.domain in the model wins over this file. A value that is not a domain id is reported, and a domain is never created.

Renames

{ "cube:growth_analytics.revenue": "cube:expansion_analytics.revenue" }

A rename is used only when the old member is gone and the new one is there. Any other entry is reported. Items that rely on the old member are flagged, with the new id named.

Choose the views it reads

Every public view and public cube is read until you keep a list of the views to read. A model with many views can be narrowed to the few your team uses.

  • In the app. On Cube’s page in Integrations, press Choose views under What it reads, then pick Only the views you choose. Search the views the model has, each with its metrics and dimensions, and tick the ones to read. This works for a model folder on the server too.
  • On the server. Set CUBE_VIEWS_FILE to a JSON file that lists them. It is the list until an admin chooses the views in the app, and is not read after that:
["orders", "revenue"]
The listWhat is read
None, or Every viewEvery public view and cube, and a view the model adds later
Some viewsThose views only. A view the model adds later waits to be listed
Empty, []Nothing, and the read says so

Name a view as the model names it. A public cube is read only when it is listed by its own name. Cube still compiles the whole model, since a view needs the cubes it includes, but only the members of the listed views become definitions: a cube that two listed views include is read through each of them, so taking one of the views out keeps the other’s members.

The list applies everywhere the definitions do: the names waiting in the Inbox, Definitions, and figures in Ask, where a metric of a view that is not read gets no figure and says why. A listed view the model does not have is named in the read (group_not_found), and the other views are read.

Taking a view out of the list marks its definitions missing at the next read. Each item that relies on one is marked Due for a check for its owners, and nothing is unpublished or deleted.

Before you save, the app names the views left out and those items, and Save waits until you say you have seen them. Listing the view again clears the marks, and it keeps the domain it was mapped to.

A view the list leaves out is a choice, not a warning: the source’s page counts the views not selected. A view the model adds later is not read until it is chosen. The admins get one card in the Inbox, New views not chosen, which opens Choose.

The server’s file is read at each read. A file that is not a JSON list of names, each once, fails the read rather than reading every view.

A metric per currency

Model a currency, a sales channel or a region as a dimension, not as a measure for each one: Variants: a dimension, not a metric each says why. Keep one measure, and let the question filter by the dimension:

cubes:
- name: orders
measures:
- name: revenue
type: sum
sql: amount
dimensions:
- name: currency_code
type: string
sql: currency_code

When a reader picks the currency an amount is shown in, a switch dimension and a case measure (Cube 1.7 and later) keep that one measure too:

dimensions:
- name: currency
type: switch
values: [EUR, USD]
measures:
- name: amount
multi_stage: true
type: number
case:
switch: '{CUBE.currency}'
when:
- value: USD
sql: '{CUBE.amount_usd}'
else:
sql: '{CUBE.amount_eur}'

A model that a Jinja loop fills with a measure for each currency is skipped, as every Jinja file is. When most of a model’s measures look like variants of a few, Test connection says so before any name is published.

When you keep a measure for each currency, a measure can say which family it is a variant of, under meta.footnote. Each view that takes the measures has the family: Declare a family in your tool says how.

measures:
- name: revenue_eur
type: sum
sql: amount_eur
meta:
footnote:
family: revenue
by:
currency: EUR

Set the model folder’s address to link each view to its file. On the Cube source’s page, set Model folder address, for example:

https://github.com/acme/analytics/blob/main/model

The service never calls the Git host: it only builds the address. Moving a member to another file flags nothing. Without an address, a definition’s page has no Open in source.

Limits

LimitValue
One file2 MB
All the files20 MB
Files in the model folder1,000
Compile time120 seconds, set with CUBE_COMPILE_TIMEOUT_SECONDS
Compile memory1,024 MB, set with CUBE_COMPILE_MEMORY_MB

A model of 10,000 members takes about 45 seconds. An empty or unreadable model folder fails the read rather than removing definitions.

Warnings

CodeWhat it means
missing_domainA public view or cube names no domain
invalid_domainA domain is not a domain id
invalid_renameA rename does not apply
unsupported_fileA file is not YAML
unreadable_fileA link, a file over the limit or not text
folder_missingThe model folder is not there
too_many_recordsThe folder holds too many files
group_not_foundA listed view is not in the model
no_groups_chosenThe list of views is empty: nothing is read

Figures in Ask

Off by default. With it on, Ask shows one figure read from Cube, and keeps it nowhere. No MCP server is needed.

  1. On Cube’s page in Integrations, press Set up figures. Give the address of Cube’s REST API, such as https://cube.example.com/cubejs-api/v1/load, and a read-only token. The token is sent only to that address’s origin.
  2. Press Try a figure. It reads one measure for the last 7 days with the settings as saved, and says what came back.
  3. Name a Data contact.
  4. Switch on Show figures in Ask.

The figure comes from the integration that defines the metric, and the query is a fixed template, never words a person or a model wrote. There is no figure when more than one integration defines the metric, or when its view has no time dimension.

“Data as of” is Cube’s lastRefreshTime.

No person’s identity is passed to Cube. A refused token, a host that cannot be reached and a slow query each say so in Ask, within 4 seconds.

The token reads what Cube’s access policies let it read. A measure an access_policy hides from the token’s groups says so in Ask and in Try a figure: Cube answers it with an error, which reads as “not allowed”, not “unreachable”. Rows are filtered by Cube itself, as its row-level rules say.

Which date

A view with one time dimension reads its figures by it. A view with several reads them by the one the model names, in this order:

  1. meta.default_time_dimension on the measure.
  2. meta.default_time_dimension on its view.
  3. The server’s figure settings, below.

The name is the view’s own (invoice_day) or in full (sales.invoice_day). A name the view does not have is skipped. When nothing names one, Ask shows no figure, lists the view’s dates and asks which one figures use: the date is never guessed. The query in words says the date used, such as “by invoice day”.

views:
- name: sales
meta:
default_time_dimension: invoice_day

Measures that do not add up over days

A snapshot, such as a balance or stock on hand, is a value on a day: added up over a month it means nothing. Mark it with meta.non_additive_dimension on the measure, the date it is taken on, as dbt’s semantic models name it:

measures:
- name: units_on_hand
type: sum
sql: units
meta:
non_additive_dimension: stock_day

Its figure is then read on the last of the days only, and so is the one it is compared with. Ask says it is the value as of that day, and that it can’t be added up over a period. It is still added up across the values the question names, such as two markets on that day.

When Cube cannot say whether a measure adds up (its model could not be read) and the server’s figure settings do not say either, the figure is not read, rather than risk adding up a snapshot.

How the value is written

The value is written as the model says:

In the modelWritten as
format: currency and currency: EURMoney, €43,600
currency: EUR alone, or meta.currency: EURMoney too
format: percentA share, 0.175 as 17.5%
Nothing, or format: numberA number, 43,600

Named formats such as currency_0 and percent_1 count as currency and percent. A percent is the share Cube gives, as Cube’s own format writes it. Money with no currency anywhere is written as a number: the currency is never guessed.

Figure settings on the server

For a model you cannot change, whoever runs the service sets FOOTNOTE_FIGURE_OVERRIDES to a JSON file. It is by integration id, then by view or measure. A measure’s own setting wins over its view’s, and the model wins over both:

{
"cube": {
"sales": { "date": "invoice_day" },
"stock.units_on_hand": { "additive": false },
"sales.revenue": { "currency": "EUR" }
}
}
SettingWhat it does
dateThe date the days apply to, by its name
additivefalse for a measure that does not add up over days
formatcurrency, percent or number, when the model has no format
currencyThe currency of money, such as EUR, when the model names none

The file is read when the service starts. A file that is not JSON, or holds a setting not in this table, stops the start.