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
- A folder of YAML model files. JavaScript, Python and Jinja templates are skipped, and a symbolic link is never followed.
- It compiles with Cube 1.8.27, the version the connector is pinned to.
- At least one public view or public cube. Only public members are listed.
Recommended in the model:
| Key | Where | What it does |
|---|---|---|
title | Each public member | Its name on screen |
description | Each public member | What it means |
meta.domain | Each view | Its domain, exactly as a domain id. A member’s own meta.domain overrides it |
meta.synonyms | A member | A 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:
| Field | What it is |
|---|---|
| Repository | The https address of the repository, without credentials |
| Branch, tag or commit | What is read. A tag or a commit holds still, and a branch moves with each change |
| Model folder | The folder of model files in the repository. Empty for the top |
| Read-only token | Kept in the secret store. Empty for a public repository |
| User name for the token | Sent with the token, x-access-token when empty. Most hosts accept any |
| Model folder address | The folder in the host’s web view, for links to each model file |
| Domain names | Each 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:
| Setting | What it does |
|---|---|
CUBE_MODEL_DIR | The folder to read. Unset, the service reads two invented definitions |
FOOTNOTE_DOMAIN_OVERRIDES | A JSON file outside the model folder: view to domain, for views the model names no domain for |
CUBE_RENAMES_FILE | A JSON file of renamed members, old id to new id |
CUBE_VIEWS_FILE | A 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:
CUBE_MODEL_DIR=/path/to/cube/model npm run connectors:syncThe 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_FILEto 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 list | What is read |
|---|---|
| None, or Every view | Every public view and cube, and a view the model adds later |
| Some views | Those 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_codeWhen 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: EURLinks to model files
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/modelThe 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
| Limit | Value |
|---|---|
| One file | 2 MB |
| All the files | 20 MB |
| Files in the model folder | 1,000 |
| Compile time | 120 seconds, set with CUBE_COMPILE_TIMEOUT_SECONDS |
| Compile memory | 1,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
| Code | What it means |
|---|---|
missing_domain | A public view or cube names no domain |
invalid_domain | A domain is not a domain id |
invalid_rename | A rename does not apply |
unsupported_file | A file is not YAML |
unreadable_file | A link, a file over the limit or not text |
folder_missing | The model folder is not there |
too_many_records | The folder holds too many files |
group_not_found | A listed view is not in the model |
no_groups_chosen | The 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.
- 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. - Press Try a figure. It reads one measure for the last 7 days with the settings as saved, and says what came back.
- Name a Data contact.
- 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:
meta.default_time_dimensionon the measure.meta.default_time_dimensionon its view.- 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_dayMeasures 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_dayIts 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 model | Written as |
|---|---|
format: currency and currency: EUR | Money, €43,600 |
currency: EUR alone, or meta.currency: EUR | Money too |
format: percent | A share, 0.175 as 17.5% |
Nothing, or format: number | A 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" } }}| Setting | What it does |
|---|---|
date | The date the days apply to, by its name |
additive | false for a measure that does not add up over days |
format | currency, percent or number, when the model has no format |
currency | The 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.