# AI Tokens
Source: https://docs.cube.dev/admin/account-billing/ai-tokens

Understand how AI token usage works in Cube, including per-seat grants, token packages, and usage tracking.

AI features in Cube use a token-based system to measure and manage consumption.

## Overview

Cube's [AI-powered features][ref-ai-overview] consume tokens based on the
resources required to complete each request. Token allocation differs by
customer type:

* **On-demand customers** receive [per-seat token grants](#per-seat-token-grants)
  equal to half of their seat price, with optional
  [on-demand consumption](#on-demand-consumption) beyond that
* **Contract customers** can purchase [pooled token packages](#token-packages)

## Token consumption

Token usage depends on several factors:

* **Task complexity** — More complex questions, multi-step analysis, or larger
  datasets consume more tokens than simple lookups. Each message in a session
  carries prior context, so longer sessions compound usage.
* **Data model context** — Cube sends context from your data model to the LLM
  to improve answer accuracy. Larger models with more fields and descriptions
  use more tokens per request.
* **AI model** — More capable models consume more tokens per request than
  lighter models.

Not all AI features consume tokens. The list of features that consume tokens
is subject to change as the product evolves.

## Per-seat token grants

On-demand customers on paid plans receive **per-seat token grants** equal to
**half of the seat price**. Each user is awarded an individual monthly token
allocation based on their role.

Per-seat grants:

* Are assigned to the individual user
* Reset each billing cycle
* Cannot be transferred, shared, or rolled over

### On-demand consumption

When a user on an on-demand plan exceeds their monthly per-seat grant, usage
automatically continues as **on-demand consumption**. On-demand usage is billed
through the credit card on file.

Administrators can set a **monthly on-demand spending limit** to control
additional costs. This limit caps the total on-demand spend across the account
for each billing cycle.

## Token packages

Contract customers can purchase **pooled add-on token packages**. Token
packages are added to a shared pool accessible by all users in the account.

* Each package is valid for the duration of the contract or until fully
  consumed, whichever comes first
* Multiple active packages can be combined
* Packages do not auto-renew

Contact your account executive for details on purchasing token packages.

## Free tier

Each user on a free plan receives an individual monthly token allowance. This
allowance resets at the start of each calendar month.

## Tracking usage

Administrators can monitor token consumption through the **AI Tokens Usage**
tab in the billing settings page. The dashboard shows:

* Total token usage over time
* Remaining allocation from per-seat grants and token packages
* Breakdown by usage dimension

## When limits are reached

When a user exhausts all available token sources (per-seat grant and token
packages), AI requests will return an error indicating the token limit has been
exceeded.

* **Administrators** are directed to the billing page to purchase additional
  token packages
* **Non-admin users** are prompted to contact their account administrator to
  increase token quotas

## FAQ

### Do tokens roll over?

* **Per-seat grants** reset each billing cycle and do not roll over
* **Token packages** remain active for the duration of the contract

### Can I bring my own AI model?

Yes. When using a [Bring Your Own Model (BYOM)][ref-byom] configuration, AI
requests bypass the token quota system entirely — no tokens are consumed or
tracked for those requests. You are billed directly by your model provider.

### Why does a single prompt sometimes use more tokens than expected?

Cube's AI features use an agentic architecture. A single prompt may trigger
multiple internal steps — such as searching the data model, building a query,
and summarizing results — each of which consumes tokens independently.

### Why does the same question use different amounts of tokens?

Token usage can vary between identical prompts due to differences in
conversation context (earlier messages in the session) or the AI choosing a
different reasoning path.

[ref-ai-overview]: /admin/ai

[ref-byom]: /admin/ai/bring-your-own-model


# API keys
Source: https://docs.cube.dev/admin/account-billing/api-keys

Admins can manage API keys through Admin → API Keys.

Create and revoke API keys for your Cube organization.

<video />

<video />

## Deployment scope

By default, an API key is **not scoped** to any deployment—it can be used with
every deployment in your organization (the **All deployments** option). When
creating or editing a key, you can instead scope it to one or more **specific
deployments**.

The scope determines which requests a key can authorize:

* **Deployment-scoped endpoints**—such as generating an embed session for a
  deployment—require the key to be scoped either to that deployment or to all
  deployments. A request targeting a deployment outside the key's scope is
  rejected.
* **Endpoints that aren't tied to a specific deployment** continue to work with
  any key, regardless of its scope.

Each key's scope—**All** or the specific deployments it's limited to—is shown in
the API keys table.

<Note>
  Scoping is optional and backward compatible. Existing keys remain unscoped (**All
  deployments**) until you change them.
</Note>


# Billing FAQ
Source: https://docs.cube.dev/admin/account-billing/billing-faq

Frequently asked questions about Cube billing, pricing, payments, and invoices.

## Billing basics

### How does the billing structure work?

#### On-demand customers

On-demand customers are billed monthly. The credit card on file is automatically
charged through Stripe upon invoice generation.

* Invoices bill active seats in advance for the upcoming period
* Any seat count changes made during a previously billed period are charged in
  arrears on a prorated basis on the next invoice, as well as billed in advance
  on all subsequent invoices until the customer makes further adjustments

#### Contract customers

**Contract customers** are billed annually and upfront according to the terms
in their contract.

* Committed seats are billed annually
* Overages for uncommitted seats and usage are billed in arrears separately on a
  basis specified in the contract
* Standard payment terms are **Net 30**, unless otherwise specified in the agreement

### What payment methods does Cube accept?

#### On-demand customers

On-demand subscriptions must be paid by credit card via Stripe. Your card is
automatically charged on a recurring subscription basis at the start of each
billing cycle.

<Info>
  Cube does **not** support ACH or wire transfer payments for on-demand payment plans.
</Info>

#### Contract customers

Contract customers can pay via:

* **Invoice billing** (e.g., Net 30 terms) — Payment terms are defined in your
  contract and reflected on your invoice.
* **ACH / wire transfer** — Bank details (Stripe-managed virtual accounts) are
  listed directly on the invoice. Please reach out to
  [support@cube.dev](mailto:support@cube.dev) if you require validation.
* **Credit card** (via Stripe) — Contract customers may also pay by credit card.

### How can I update my payment information?

To update your payment information, log in to your Cube account and navigate to
the billing settings page.

If you need assistance confirming or updating your account email, please reach
out to [support@cube.dev](mailto:support@cube.dev).

### What happens if my credit card payment fails?

If your credit card payment fails:

1. **We automatically retry the charge** — Stripe will automatically retry the
   payment using the card on file. Sometimes failures are temporary (e.g.,
   insufficient funds, bank block, expired card).
2. **You may receive an email notification** — If the payment continues to fail,
   you'll receive an email prompting you to update your payment method.
3. **Update your card** — You can update your card through the billing settings
   page. Once updated, the system will automatically retry the charge.
4. **Continued failed payments** — If payment isn't resolved after multiple
   attempts, your account may be restricted or suspended until the outstanding
   balance is paid.


# Support in Cube Cloud
Source: https://docs.cube.dev/admin/account-billing/support

Summarizes support channels, coverage hours, and ticket allowances across Cube Cloud product tiers.

Cube Cloud [product tiers][ref-cloud-pricing] include different levels of support
in terms of speed and scope that you should review as you think about what is
right for your business.

## Support by product tiers

### Free

* [Free product tier][ref-free-tier] offers support via **online resources** such as
  [documentation][ref-docs-intro], [webinars][cube-webinars], and [community
  Slack][cube-slack].

### Starter

* [Starter product tier][ref-starter-tier] includes support via **online resources** such as
  [documentation][ref-docs-intro], [webinars][cube-webinars], and [community
  Slack][cube-slack].
* You can also connect with our support team during [support hours](#support-hours)
  with **2 support tickets per month** through the in-product chat feature.

### Premium

* [Premium product tier][ref-premium-tier] includes support via **online resources** such as
  [documentation][ref-docs-intro], [webinars][cube-webinars], and [community
  Slack][cube-slack].
* It also includes **either 4 support tickets per month** (on-demand customers)
  or **unlimited support tickets** (contract customers) for our support engineers during
  [support hours](#support-hours) through our in-product chat.

| Priority | Response time during support hours |
| -------- | ---------------------------------- |
| P0       | 60 minutes                         |
| P1       | 4 hours                            |
| P2       | 8 business hours                   |
| P3       | 2 business days                    |

### Enterprise

* [Enterprise product tier][ref-enterprise-tier] includes support via **online resources** such as
  [documentation][ref-docs-intro], [webinars][cube-webinars], and [community
  Slack][cube-slack].
* It also includes **unlimited support tickets** for our support engineers during
  [support hours](#support-hours) through our in-product chat with faster
  response times as compared to the [Premium product tier](#premium).

| Priority | Response Time during Support Hours |
| -------- | ---------------------------------- |
| P0       | 30 minutes                         |
| P1       | 2 hours                            |
| P2       | 8 business hours                   |
| P3       | 2 business days                    |

* Enterprise product tier also includes a **dedicated customer success manager** (CSM)
  who will provide quarterly reviews, sharing new features and training as well
  as usage and optimization advice.

## Support hours

Official support hours are weekdays (Monday through Friday) from 8am ET to 8pm
ET. The above response times are only during support hours.

## Support priority definitions

We prioritize support requests based on their severity, as follows:

* **P0**: The platform is severely impacted or completely shut down. We will
  assign specialists to work continuously to fix the issue, provide ongoing
  updates, and start working on a temporary workaround or fix.

* **P1**: The platform is functioning with limited capabilities or facing
  critical issues preventing a production deployment. We will assign specialists
  to fix the issue, provide ongoing updates, and start working on a temporary
  workaround or fix.

* **P2**: There are issues with workaround solutions or non-critical functions.
  We will use resources during local business hours until the issue is resolved
  or a workaround is in place.

* **P3**: There is a need for clarification in the documentation, or a
  suggestion for product enhancement. We will triage the request, provide
  clarification when possible, and may include a resolution in a future update.

[ref-docs-intro]: /docs/introduction

[cube-webinars]: https://cube.dev/events

[cube-slack]: https://slack.cube.dev

[ref-cloud-pricing]: /admin/account-billing/pricing

[ref-free-tier]: /admin/account-billing/pricing#free

[ref-starter-tier]: /admin/account-billing/pricing#starter

[ref-premium-tier]: /admin/account-billing/pricing#premium

[ref-enterprise-tier]: /admin/account-billing/pricing#enterprise


# Bring Your Own Model
Source: https://docs.cube.dev/admin/ai/bring-your-own-model

Configure custom LLM providers for AI agents in Cube, including supported providers, setup, and billing implications.

<Note>
  Available on the [Enterprise plan](https://cube.dev/pricing).
</Note>

Bring Your Own Model (BYOM) lets you connect your own LLM provider to power
AI agents in Cube, instead of using the built-in models. This gives you full
control over which models your agents use, where your data is processed, and
how you manage AI costs.

## Supported providers

| Provider             | Chat models | Embedding models |
| -------------------- | ----------- | ---------------- |
| **Anthropic**        | Yes         | No               |
| **OpenAI**           | Yes         | Yes              |
| **AWS Bedrock**      | Yes         | Yes              |
| **GCP Vertex AI**    | Yes         | No               |
| **Databricks**       | Yes         | No               |
| **Snowflake Cortex** | Yes         | No               |

## Configuration

### Step 1: Add a model

Before assigning a BYOM model to an agent, you need to register it in the
admin panel:

1. Navigate to **Admin > Models**
2. Click **Add Model**
3. Provide a **name** for the model
4. Select the **model type** (LLM or Embedding)
5. Choose a **provider** and **model**
6. Enter the required credentials for the provider

### Step 2: Assign the model to an agent

Once a model is registered, reference it in the agents YAML configuration by
name or ID:

```yaml theme={"dark"}
agents:
  - name: sales-analyst
    llm:
      byom:
        name: "my-anthropic-model"
    embedding_llm:
      byom:
        name: "my-bedrock-embeddings"
```

Each agent can use a different model. If no BYOM model is specified, the agent
uses the built-in default.

<Warning>
  Switching embedding models for an agent means existing memories stored with
  the previous embedding model will not be compatible. Memories are tied to the
  embedding model that created them.
</Warning>

## Network configuration

When using BYOM, Cube connects to your model provider from its control plane.
If your provider requires IP allowlisting, ensure the Cube outbound IP
addresses are added to your allowlist.

For agents running in dedicated regions, additional per-region IP addresses
may also need to be allowlisted.

## Billing

When using a BYOM model, **Cube AI tokens are not consumed**. You are billed
directly by your model provider based on their pricing.

This means:

* No Cube token quota is deducted for BYOM chat requests
* No token usage is tracked in the AI Tokens Usage dashboard for BYOM requests
* Per-seat token grants and token packages do not apply

See [AI Tokens][ref-ai-tokens] for details on how token billing works with
built-in models.

## Provider-specific notes

### Anthropic

Supports extended thinking mode for compatible models. Configure this in the
model settings when creating the model.

### AWS Bedrock

* Credentials are optional — if left empty, the default AWS credential chain
  is used (e.g., workload identity)
* Supports assume-role configuration for cross-account access
* Supports inference profiles

### GCP Vertex AI

Requires a service account JSON key for authentication.

### Databricks

Requires a workspace URL and access token.

### Snowflake Cortex

Supports two authentication methods:

* JWT authentication
* Key-pair authentication (requires an encrypted PKCS#8 PEM private key)

## Troubleshooting

### Rate limit errors

If you see rate limit errors, the limits are enforced by your model provider,
not by Cube. Check your provider's rate limits and usage quotas.

### Authentication errors

Verify that the API key or credentials configured for the model are valid and
have the necessary permissions.

### Model not found

Ensure the model ID configured in Cube matches a valid model offered by your
provider. Model availability may vary by region.

[ref-ai-tokens]: /admin/account-billing/ai-tokens


# Certified queries
Source: https://docs.cube.dev/admin/ai/certified-queries

Provide a library of trusted SQL queries that the agent uses as reference examples when answering user requests.

Certified queries are pre-approved SQL queries that the agent treats as a **library of trusted examples**. They guide the agent toward correct business logic and well-formed query patterns without restricting it to a fixed set of queries.

Certified queries are configured as code in your [data model repository](/admin/ai#agent-configuration), alongside your cubes and views.

<Note>
  The agent is not limited to running only certified queries. When answering a user request, the agent may:

  * Use a certified query directly if it matches the request
  * Use a certified query as a **starting point** and adapt it (e.g., add filters, dimensions, or measures) to fit the user's question
  * Generate a new query independently if no certified query is relevant

  Certified queries help the agent toward trusted patterns and correct business logic, but the agent retains full flexibility to construct the query that best answers each question.
</Note>

## Defining certified queries

Certified queries are defined as Markdown files under `agents/certified_queries/`. Each query lives in its own file: the YAML frontmatter holds metadata, and the Markdown body is the SQL query.

```markdown theme={"dark"}
<!-- agents/certified_queries/quarterly-revenue.md -->
---
description: "Get revenue by fiscal quarter"
user_request: "What is the revenue by quarter?"
---
SELECT
  DATE_TRUNC('quarter', order_date) AS quarter,
  SUM(amount) AS revenue
FROM orders
WHERE status != 'cancelled'
GROUP BY 1
ORDER BY 1
```

Files placed under a `certified_queries/`, `certified-queries/`, or `queries/` directory are treated as certified queries automatically — no `kind` property is required. The `name` is inferred from the file name (e.g., `quarterly-revenue.md` → `quarterly-revenue`).

### Frontmatter properties

| Property       | Type   | Required | Description                                                |
| -------------- | ------ | :------: | ---------------------------------------------------------- |
| `name`         | string |    No    | Unique identifier. Inferred from the file name if omitted. |
| `description`  | string |    No    | Human-readable description.                                |
| `user_request` | string |    Yes   | The user request pattern this query answers.               |
| `sql_query`    | string |    No    | The SQL query. Falls back to the Markdown body if omitted. |

### Inlining certified queries in YAML

You can also inline certified queries directly in `agents/config.yml` under a `certified_queries` key:

```yaml theme={"dark"}
# agents/config.yml
certified_queries:
  - name: total-revenue
    description: "Calculate total revenue"
    user_request: "What is the total revenue?"
    sql_query: "SELECT SUM(amount) AS total_revenue FROM orders WHERE status = 'completed'"

  - name: monthly-sales
    description: "Monthly sales breakdown"
    user_request: "Show me sales by month"
    sql_query: |
      SELECT
        DATE_TRUNC('month', order_date) AS month,
        SUM(amount) AS total_sales
      FROM orders
      GROUP BY 1
      ORDER BY 1
```

Inline certified queries accept the same properties as Markdown ones — `name`, `description`, `user_request` (required), and `sql_query` (required).

<Note>
  Certified queries inlined at the root of `agents/config.yml` are attached to the implicit `auto` space and applied to the default agent in a [single-agent setup](/admin/ai). In a [multi-agent setup](/admin/ai/multi-agent), attach certified queries to a specific space by inlining them under that space's `certified_queries` key (or by placing Markdown files under `agents/certified_queries/<space-name>/`).
</Note>

## Writing effective certified queries

* **Phrase `user_request` like a real user question.** This is what the agent matches against incoming requests.
* **Keep queries focused.** A certified query should answer one well-defined question; the agent will adapt it for variations.
* **Use canonical business logic.** Certified queries are the reference for "the right way" to compute something — encode the definitions you want the agent to follow.
* **Cover common patterns first.** Start with the questions users ask most often, and grow the library based on usage.


# Evals
Source: https://docs.cube.dev/admin/ai/evals

Benchmark your agent's answers against a known-correct ground truth and track accuracy across data-model and agent changes.

Evals let you benchmark your agent's answers against a known-correct ground
truth, on any branch. You author a set of questions, each with the SQL or
[certified query](/admin/ai/certified-queries) that represents the right
answer, run your agent against them, and get a per-question pass/fail plus an
accuracy score for the run — so you can see, objectively, whether a data-model
or agent change made the agent better or worse.

You'll find evals in the model IDE under the **Evals** tab, with two
sub-tabs: **Evals** (runs) and **Questions** (the benchmark set).

<Frame>
  <img alt="Eval run results showing the question list with pass/fail icons and a selected question's detail with the agent's SQL next to the ground truth SQL" />
</Frame>

## Concepts

| Term           | What it is                                                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Question**   | A natural-language question plus its **ground truth** (the correct answer, as SQL or a certified-query reference). Authored as code in your data model. |
| **Eval (run)** | One execution of the agent against the whole question set, on a specific branch and agent.                                                              |
| **Result**     | The agent's answer to a single question in a run, graded against that question's ground truth.                                                          |
| **Accuracy**   | `passed / total` for a run, shown as `NN% (passed/total)`.                                                                                              |

## Authoring benchmark questions

Questions live in your [data model repository](/admin/ai#agent-configuration),
versioned and branched like the rest of it. You can keep them in a single
top-level `agents/eval_questions.yml` file — the simplest place to start — or
split them across any number of `agents/eval_questions/*.yml` files as your set
grows. The parser picks up both and merges every file's `eval_questions` list
into one set, so you can move from one file to many at any time without changing
anything else.

Each file has a top-level `eval_questions` list. A question needs a unique
`name`, a `question`, and exactly one ground truth: a `certifiedQuery`
reference **or** inline `sql`.

```yaml theme={"dark"}
# agents/eval_questions.yml
eval_questions:
  - name: revenue_by_quarter
    question: What was our revenue by quarter over the last two years?
    certifiedQuery: revenue_by_quarter        # reference an existing certified query by name

  - name: arr_last_4_years
    question: What was our ARR over the last 4 years?
    sql: |                                    # ...or inline SQL ground truth
      SELECT date_trunc('year', created_at) AS year, SUM(arr) AS arr
      FROM subscriptions GROUP BY 1 ORDER BY 1
```

* `certifiedQuery` references a [certified query](/admin/ai/certified-queries)
  by name. Define it under `agents/certified_queries/` (or via **Certify this
  query** in chat). A reference that doesn't resolve to an existing certified
  query is flagged as a validation error.
* `sql` is inline ground-truth SQL, run through the same Cube SQL API the agent
  uses (so `MEASURE(...)` and friends work).
* Omitting both — or setting both — is a validation error.
* An optional top-level `space` key scopes a file's questions to a named space
  (defaults to `auto`). Question names are unique per space.

<Note>
  The **Questions** tab is a read-only view of these files. To add or edit
  questions, edit the YAML in the IDE — there's no in-product question editor
  yet.
</Note>

## Running an eval

On the **Evals** tab, click **Run eval** and choose:

* **Branch** — which branch's data model and agent configuration to run
  against. Defaults to the active branch.
* **Agent** — `auto` (the implicit auto-agent) or a configured agent name.

The run starts immediately and you can close the dialog — it executes in the
background. The run list shows live progress and then the outcome:

| Column               | Meaning                                                                                                                                                    |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Eval run**         | When the run was created.                                                                                                                                  |
| **Environment**      | Where it ran — **dev** (your personal dev-mode branch, shown as "*Name* Dev Mode"), **staging**, or **prod** (the deploy branch, e.g. `master` or `main`). |
| **Agent**            | The agent used.                                                                                                                                            |
| **Execution status** | Running, Completed, or Failed.                                                                                                                             |
| **Accuracy**         | `NN% (passed/total)`.                                                                                                                                      |
| **Created by**       | Who triggered the run.                                                                                                                                     |
| **Last updated**     | When it finished.                                                                                                                                          |

## Reading the results

Open a run to see per-question results: the question list on the left, with a
pass/fail icon for each, and the selected question's detail on the right.

* **Assessment** — `pass`, `fail`, `review`, or `error`.
* **Score reason** — when a question doesn't pass, a tag categorizing why:
  **Row count mismatch**, **Missing columns**, **Value mismatch**,
  **Unexpected rows**, **Query error**, **Ground truth query failed**,
  **Ground truth not found**, or **Agent error**.
* **Failure analysis** — a plain-English explanation, e.g. *"The agent
  returned 3 rows, but the ground truth has 5 rows."*
* **Model output · SQL** vs. **Ground truth SQL answer** — the agent's query
  side-by-side with the ground truth, so you can spot the difference.
* **Response** — the agent's full text answer, rendered as Markdown.

## How grading works

Grading is execution-based, not text-based — the same approach used by
industry text-to-SQL benchmarks such as BIRD and Spider 2.0. The agent's SQL
and the ground-truth SQL are both executed, and their result sets are
compared. So an answer that's worded or written differently but produces the
same data still passes.

The comparison is:

* **Sort-invariant** — row order never matters.
* **Numeric-tolerant** — values are compared to 4 significant figures, so
  float/representation noise (`6646` vs. `6646.0`) doesn't fail.
* **Column-name-agnostic and lenient on extra columns** — each ground-truth
  column must be reproduced by some agent column, matched by its values, so
  `revenue` vs. `total` aliases don't matter. Extra columns the agent adds are
  ignored.
* **No standalone row-count gate** — row count falls out of the comparison: a
  "top 5" question is enforced because the golden result has exactly 5 rows.

Verdicts:

| Verdict    | When                                                                                                                    |
| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| **pass**   | The agent's result set matches the ground truth.                                                                        |
| **fail**   | It ran but the result set doesn't match (see the score reason).                                                         |
| **review** | Nothing to compare automatically — the question has no ground truth, or the agent didn't run a query. Compare manually. |
| **error**  | The agent run failed, the ground-truth query failed, or a referenced certified query wasn't found.                      |

## Limitations

* Questions are authored as code only; the **Questions** tab is read-only.
* Very large question sets can be slow to run.
* Grading is execution-based on the result set; it does not semantically judge
  prose answers.


# Overview
Source: https://docs.cube.dev/admin/ai/index

Configure the agent that ships with every Cube deployment — accessible views, LLM, runtime, and memory.

Every Cube deployment ships with an agent that powers AI features such as [Analytics Chat](/docs/explore-analyze/analytics-chat). You can customize the agent's behavior with rules, certified queries, accessible views, model selection, and memory configuration.

<Warning>
  Configuring the agent in the UI is **deprecated** in favor of code-first configuration. Cube version 1.6.5 or above is required.

  Deployments created after **April 30, 2026** have code-first agent configuration enabled by default. Existing deployments need to opt in by setting `CUBE_CLOUD_AGENTS_CONFIG_ENABLED=true`. The directory path defaults to `agents` and can be overridden with `CUBE_CLOUD_AGENTS_CONFIG_PATH`.
</Warning>

## Agent configuration

Agent configuration lives in your **Cube data model repository**, alongside your cubes and views. Configuration is defined as YAML and Markdown files under an `agents/` directory in your project:

```text theme={"dark"}
your-cube-project/
├── model/
│   └── cubes/
│       └── orders.yml
├── agents/
│   ├── config.yml                 # Agent configuration
│   ├── rules/                     # Rules as Markdown
│   │   └── fiscal-year.md
│   └── certified_queries/         # Certified queries as Markdown
│       └── quarterly-revenue.md
└── cube.py
```

Storing configuration as code in your repository enables version control, code review, and consistent behavior across environments.

## Configure the agent

Place agent properties at the root of `agents/config.yml`:

```yaml theme={"dark"}
# agents/config.yml
llm: claude_4_sonnet
runtime: plain
accessible_views:
  - orders_view
  - customers_view
memory_mode: user
```

### Properties

| Property           | Type             | Default                  | Description                                                                                                                                                                                                                                                                    |
| ------------------ | ---------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `llm`              | string or object | `auto`                   | LLM provider — `auto`, a [predefined model](#llm) name, or a [BYOM](/admin/ai/bring-your-own-model) reference.                                                                                                                                                                 |
| `embedding_llm`    | string or object | `text-embedding-3-large` | Embedding model — a predefined name or a BYOM reference.                                                                                                                                                                                                                       |
| `runtime`          | string           | `plain`                  | [Runtime mode](#runtime) — `plain` or `reasoning`.                                                                                                                                                                                                                             |
| `accessible_views` | array            | *all views*              | List of view names exposed to the agent as context guidance for which views to query. This is not a security control — if omitted or empty, all views are exposed. Use [access policies](/reference/data-modeling/data-access-policies) to enforce actual access restrictions. |
| `memory_mode`      | string           | `space`                  | [Memory isolation mode](#memory) — `space`, `user`, or `disabled`.                                                                                                                                                                                                             |

Rules and certified queries have their own dedicated pages:

* [Rules](/admin/ai/rules) — instructions that guide the agent's behavior
* [Certified queries](/admin/ai/certified-queries) — a library of trusted SQL examples for the agent
* [Skills](/admin/ai/skills) — reusable, named agent workflows users can run on demand from chat

## LLM

The default value is `auto` — Cube picks a recommended model on your behalf and may change it as better models become available. Use `auto` unless you have a reason to pin a specific model.

To pin a specific model, set the `llm` property to one of the predefined models:

**Anthropic Claude:**

* `claude_3_5_sonnetv2`
* `claude_3_7_sonnet`
* `claude_3_7_sonnet_thinking`
* `claude_4_sonnet`
* `claude_4_5_sonnet`
* `claude_4_5_haiku`
* `claude_4_5_opus`
* `claude_4_6_sonnet`
* `claude_4_6_opus`
* `claude_4_7_opus`
* `claude_4_8_opus`
* `claude_5_sonnet`
* `claude_5_opus`

**OpenAI GPT:**

* `gpt_4o`
* `gpt_4_1`
* `gpt_4_1_mini`
* `gpt_5`
* `gpt_5_mini`
* `gpt_5_3`
* `gpt_5_4`
* `o3`
* `o4_mini`

To use your own model, see [Bring your own model](/admin/ai/bring-your-own-model).

### Embedding models

Predefined embedding models for the `embedding_llm` property:

* `text-embedding-3-large`
* `text-embedding-3-small`

BYOM is also supported for embedding models.

## Runtime

The `runtime` property controls how the agent processes requests:

| Mode        | Description                                                            |
| ----------- | ---------------------------------------------------------------------- |
| `plain`     | Default. Optimized for speed and cost. Recommended for most use cases. |
| `reasoning` | Enables extended thinking for complex analysis.                        |

<Warning>
  `reasoning` is **experimental**. It may be unstable and is not yet feature-complete. Stick with `plain` unless you have a specific need for extended reasoning.
</Warning>

## Memory

The `memory_mode` property controls how the agent persists context across conversations:

| Mode       | Description                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------- |
| `space`    | Default. Memories are shared across all users — useful when the agent serves a single team. |
| `user`     | Memories are isolated per user — useful when each user has private context.                 |
| `disabled` | The agent does not persist memory between conversations.                                    |

See [Memories](/admin/ai/memory-isolation) for details on how memories are stored and used.

## Customize the agent

<CardGroup>
  <Card title="Rules" icon="list-check" href="/admin/ai/rules">
    Define instructions that guide how the agent responds and analyzes data.
  </Card>

  <Card title="Certified queries" icon="certificate" href="/admin/ai/certified-queries">
    Provide a library of trusted SQL queries for the agent to reference.
  </Card>

  <Card title="Skills" icon="wand-magic-sparkles" href="/admin/ai/skills">
    Package reusable, named agent workflows that users can run on demand from chat.
  </Card>

  <Card title="Bring your own model" icon="brain" href="/admin/ai/bring-your-own-model">
    Configure the agent to use your own LLM provider or model.
  </Card>

  <Card title="Memories" icon="database" href="/admin/ai/memory-isolation">
    Control how the agent persists context across conversations and users.
  </Card>
</CardGroup>


# MCP Connectors
Source: https://docs.cube.dev/admin/ai/mcp-connectors

Connect external MCP servers so the agent can use their tools — search Notion, file Linear issues, query Sentry, and more — from chat.

<Note>
  MCP Connectors are available on [Premium and Enterprise plans](https://cube.dev/pricing).
</Note>

MCP Connectors let the [agent](/admin/ai) use tools from external services. An
administrator connects an external [MCP](https://modelcontextprotocol.io) server — such as
Notion, Linear, Sentry, or Attio — and its tools become available to the agent in
[Analytics Chat](/docs/explore-analyze/analytics-chat). The agent can then search a Notion
workspace, file a Linear issue, look up a Sentry error, or call any tool a connected server
exposes, alongside the data it queries from your semantic model.

<Note>
  **MCP Connectors are the inverse of the [MCP server](/docs/integrations/mcp-server).** A
  connector lets the **Cube agent reach out** to an external MCP server and call its tools.
  The MCP server lets **external MCP clients reach in** to Cube and query your data. One is
  outbound, the other inbound — you can use either or both.
</Note>

## Concepts

* A **connector** is a connection to one external MCP server. Each connector is configured
  and authenticated once, at the organization level, by an administrator.
* Each connector exposes one or more **tools** — the individual actions the agent can call
  (for example, "search pages" or "create issue"). A single connector typically exposes
  many tools.
* Connectors are managed in the admin panel under **MCP Connectors** and apply across the
  organization, so every agent can use the tools you enable.

## Adding a connector

Open the admin panel and go to **MCP Connectors**. You can add a connector from the
built-in directory or connect a custom MCP server.

### From the directory

The connector directory includes vetted, first-party integrations with streamlined setup.

<Steps>
  <Step title="Browse the directory">
    Select **Browse directory** and choose a service (for example, Notion, Linear, Sentry,
    or Attio).
  </Step>

  <Step title="Authenticate">
    Complete the connector's authentication flow (see [Authentication](#authentication)
    below). For OAuth-based connectors you'll be redirected to the provider to authorize
    access.
  </Step>

  <Step title="Enable tools">
    Review the tools the connector exposes and choose which ones are available to the
    agent. See [Choosing which tools are available](#choosing-which-tools-are-available).
  </Step>
</Steps>

### Custom connector

Any service that exposes a remote MCP endpoint can be connected as a custom connector.

<Steps>
  <Step title="Add a custom connector">
    Select **Add custom connector** and provide a name and the server's HTTPS endpoint URL
    (for example, `https://mcp.example.com/mcp`).
  </Step>

  <Step title="Authenticate">
    Choose the authentication method the server requires — OAuth or a user-provided
    credential such as an API key or token.
  </Step>

  <Step title="Enable tools">
    Once connected, the server's tools are discovered automatically. Choose which ones the
    agent may call.
  </Step>
</Steps>

## Authentication

Connectors authenticate to the external service in one of two ways, depending on what the
service supports:

| Method                       | How it works                                                                                                                                                                   |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **OAuth**                    | You authorize Cube with the provider through a standard OAuth flow. The connector stores the resulting tokens and refreshes them as needed. Used by most directory connectors. |
| **User-provided credential** | You supply a credential — such as an API key or access token — that the connector uses to authenticate. Used when a service does not offer OAuth.                              |

A connector's status indicator in the connectors list shows whether it is connected and
authenticated.

## Choosing which tools are available

Each connected server reports the full set of tools it exposes (shown as a count, for
example `16 / 16`). You control which of those tools the agent is allowed to call.
Enabling only the tools you need keeps the agent focused and limits what it can do through
each connector.

## How the agent uses connector tools

Once a connector is configured and its tools are enabled, the agent can call them in
[Analytics Chat](/docs/explore-analyze/analytics-chat) as part of answering a request — the
same way it queries your semantic model. The agent decides when a tool is relevant based on
the user's request and the tool's description. If a tool requires the user to authenticate
to the external service, the agent prompts for authorization in chat before the tool runs.

## Permissions

Managing MCP Connectors requires administrator access in Cube Cloud — the same access
needed to manage other organization-level settings in the admin panel. Connectors apply
across the organization; using the tools they expose is available to anyone with chat
access, subject to the tools you enable.

## Related

<CardGroup>
  <Card title="MCP server" icon="plug" href="/docs/integrations/mcp-server">
    Let external MCP clients connect to Cube and query your data over HTTPS.
  </Card>

  <Card title="Overview" icon="robot" href="/admin/ai">
    Configure the agent that powers Cube's AI features.
  </Card>

  <Card title="Skills" icon="wand-magic-sparkles" href="/admin/ai/skills">
    Package reusable, named agent workflows users can run on demand from chat.
  </Card>

  <Card title="Analytics Chat" icon="comments" href="/docs/explore-analyze/analytics-chat">
    Ask questions of your data in natural language.
  </Card>
</CardGroup>


# Memories
Source: https://docs.cube.dev/admin/ai/memory-isolation

How the agent stores, retrieves, and isolates memories across tenants, spaces, and users.

Memory in Cube allows Agents to learn from and recall past interactions, user preferences, and contextual information. When users interact with Agents, relevant information is stored as memories that can be retrieved in future conversations, enabling more personalized and context-aware responses. Memories help Agents understand user preferences, remember previous decisions, and provide continuity across sessions.

Memories are scoped and enforced at the Tenant/Space boundary. Cube applies both application-layer and (optionally) infrastructure-layer isolation so one customer's end users cannot see another customer's memories.

## How It Works

### Space-Scoped Memories

Cube memories are stored at the Space level. Agents only learn from and retrieve memories within the current Space, ensuring no cross-Space exposure by design.

Because a Space can be [scoped globally or to a single deployment](/admin/ai/multi-agent#space-scope), that boundary also decides whether memories are shared across deployments: agents in different deployments that use the same global Space share its memories, while a Space scoped to one deployment keeps them to that deployment.

### Tenant-Aware Security Context

Every request carries a tenant-bound security context (JWT). Cube maps that context to an app/tenant ID and uses it across caching, orchestration, and query flows. This is the backbone of multi-tenancy isolation.

### RBAC and Policy Guardrails

Role-based access policies gate what entities and content are visible within a tenant. These same guardrails apply to what agents can read and write as memories.

### Data Model and API Isolation

Even when using the SQL API or custom views, hidden members and non-public entities remain inaccessible. Multitenancy configuration ensures queries and artifacts resolve only within the current tenant's scope.

### Optional Infrastructure Isolation

Many customers run in multi-tenant regions, but single-tenant infrastructure and BYOC (Bring Your Own Cloud) variants are available. These provide stronger blast-radius isolation at the cluster, storage, and key-management levels.

## Practical Implications

* **Tenant Separation**: An end user in Customer A can only create and retrieve memories in Customer A's Spaces
* **Cross-Tenant Protection**: Memories are not retrievable by Customer B's users or agents, because requests from B carry a different security context and resolve to different Space and tenant IDs
* **Intra-Tenant Controls**: Even within a customer, RBAC and policies can further restrict which users or agents can contribute to or benefit from memories

## Technical Implementation

Cube ensures memory isolation through multiple layers of security controls:

1. **Tenant Isolation**: Every request is scoped to a specific tenant via JWT and middleware
2. **User Isolation**: Additional user-level filtering for user-mode memories
3. **Automatic Filtering**: Database queries are automatically filtered by tenant using decorators
4. **Vector Store Security**: All vector searches include tenant and user filters
5. **Container Isolation**: Each tenant gets its own dependency injection container
6. **JWT Security**: All security context comes from cryptographically signed JWT tokens
7. **Memory Mode Controls**: Configurable memory isolation levels (user/space/disabled)


# Multi-agent
Source: https://docs.cube.dev/admin/ai/multi-agent

Configure multiple agents within a single deployment, each with its own model, accessible views, rules, and certified queries.

Every Cube deployment ships with a single agent by default — see the [Overview](/admin/ai) for the standard configuration. For more advanced setups, you can configure **multiple agents** within the same deployment, each with its own model, accessible views, rules, and certified queries.

Multi-agent is useful when:

* Different teams need agents tuned to their own domain (e.g., a Sales Assistant and a Marketing Analyst).
* You want specialized agents with distinct instructions or tool access in the same deployment.
* You need to isolate context (rules, certified queries, memories) between user groups.

<Info>
  `agents/config.yml` is the source of truth for spaces and agents: declaring them there and [reconciling](#reconciliation) is the only supported way to create either. Agents can't be created in the UI, and their settings are read-only there. Cube links every record it creates to the entry it came from, and matches them by that entry's `name`.
</Info>

## Architecture

A multi-agent setup introduces one new concept on top of the single-agent model: **spaces**.

* A **space** belongs to the account and is used by one or more **deployments** — see [Space scope](#space-scope).
* A **space** is an isolated context. It owns its **rules**, **certified queries**, and **memories** — they are not shared across spaces.
* Each **agent** belongs to exactly one space and inherits everything that space owns. Multiple agents can live in the same space and share the same rules, certified queries, and memories.

This means you choose a space's boundary based on what context should be shared. Two agents serving the same team usually live in one space; agents serving different domains (Sales vs. Marketing) live in different spaces so their context stays separate.

```mermaid theme={"dark"}
flowchart LR
    classDef deployment fill:#4f46e5,stroke:#3730a3,color:#fff
    classDef space fill:#e0e7ff,stroke:#6366f1,color:#1e1b4b
    classDef agent fill:#10b981,stroke:#047857,color:#fff
    classDef resource fill:#fef3c7,stroke:#d97706,color:#78350f

    D[Deployment]:::deployment

    SA[Space<br/>sales-analytics]:::space
    SM[Space<br/>marketing-analytics]:::space

    SAR[Rules]:::resource
    SAC[Certified queries]:::resource
    SAM[Memories]:::resource
    A1[Agent<br/>sales-assistant]:::agent
    A2[Agent<br/>sales-reporter]:::agent

    SMR[Rules]:::resource
    SMC[Certified queries]:::resource
    SMM[Memories]:::resource
    A3[Agent<br/>marketing-analyst]:::agent

    D -->|uses| SA
    D -->|uses| SM

    SA --- SAR
    SA --- SAC
    SA --- SAM
    SA --> A1
    SA --> A2

    SM --- SMR
    SM --- SMC
    SM --- SMM
    SM --> A3
```

In the [single-agent setup](/admin/ai), there is an implicit `auto` space that holds all rules, certified queries, and memories — you don't need to think about it. In a multi-agent setup, you define spaces explicitly and attach rules and certified queries to specific spaces.

## What changes from the single-agent setup

The [`agents/` file structure](/admin/ai#agent-configuration) is the same. What's different is how `agents/config.yml` is shaped:

1. **Agents are defined as an array.** Each agent gets a unique `name` and an optional `description`, in addition to the standard agent [properties](/admin/ai#properties) (`llm`, `runtime`, `accessible_views`, `memory_mode`, etc.).
2. **Spaces are introduced.** A `spaces` array defines the contexts agents operate in. Each space gets a unique `name`.
3. **Rules and certified queries attach to spaces.** Use the `space` property in the frontmatter of each rule or certified query Markdown file to attach it to a specific space.

<Warning>
  You cannot mix flat root-level properties (the single-agent style) with `spaces` or `agents` arrays in the same file. Use one style per file.
</Warning>

## Agents

Replace the flat root-level agent properties with an `agents` array:

```yaml theme={"dark"}
# agents/config.yml
agents:
  - name: sales-assistant                   # Required
    description: "AI assistant for sales analytics"
    space: sales-analytics                  # Required: reference to a space
    llm: claude_4_6_sonnet
    accessible_views:
      - orders_view
      - customers_view
    memory_mode: user

  - name: marketing-analyst                 # Required
    description: "AI assistant for marketing analytics"
    space: marketing-analytics              # Required
    llm: gpt_5
```

The properties available on each agent are the same as in the [single-agent setup](/admin/ai#properties), plus:

| Property      | Type   | Required | Description                                         |
| ------------- | ------ | :------: | --------------------------------------------------- |
| `name`        | string |    Yes   | Unique identifier for the agent.                    |
| `description` | string |    No    | Human-readable description.                         |
| `space`       | string |    Yes   | Name of the [space](#spaces) this agent belongs to. |

## Spaces

A space is the context an agent operates in. Spaces own the rules, certified queries, and memories that the agents inside them share. Define spaces alongside agents:

```yaml theme={"dark"}
# agents/config.yml
spaces:
  - name: sales-analytics                   # Required
    description: "Space for sales team analytics and reporting"

  - name: marketing-analytics               # Required
    description: "Space for marketing team analytics"
```

| Property      | Type   | Required | Description                      |
| ------------- | ------ | :------: | -------------------------------- |
| `name`        | string |    Yes   | Unique identifier for the space. |
| `description` | string |    No    | Human-readable description.      |

Each agent must reference exactly one space via its `space` property. Multiple agents can share the same space and inherit its rules, certified queries, and memories.

## Reconciliation

A space or agent declared in `agents/config.yml` needs a matching record in Cube before users can chat with it. Cube creates those records from your config — that step is **reconciliation**:

<Steps>
  <Step title="Declare the space and the agent in YAML">
    Add the `spaces:` and `agents:` entries to `agents/config.yml`. In dev mode the pending list reflects your branch, so you can reconcile before merging.
  </Step>

  <Step title="Open the pending configurations">
    Cube compares the config with the records already available to that deployment, matching each entry by `name`. Entries with no record yet are listed under **Pending Configurations** on the **Agents** page and on **Agents** → **Spaces**, once you pick the deployment. The Semantic Model IDE also shows a **Reconcile agent configs** button with the pending count that links there.
  </Step>

  <Step title="Create them">
    Choose the [space scope](#space-scope) and press **Create All**. Spaces are created first, then each agent is linked to the space its `space` property names.
  </Step>
</Steps>

Reconciliation only creates missing spaces and agents, so you need it only when an entry has no record available to the deployment yet: after adding a `name` to the config, and on each deployment you reconcile for the first time — an agent belongs to one deployment, as does a space created per deployment, while a global space counts as created everywhere. Agent behavior — `llm`, `description`, `accessible_views`, `memory_mode`, rules, certified queries — is read from the `agents/` directory of the deployment's data model and takes effect without reconciling. The implicit `auto` space and agent of the [single-agent setup](/admin/ai) are never listed as pending.

An agent's `space` is the exception: the link is made when the agent is created, so changing it in YAML doesn't move an existing agent. The agent's page flags the mismatch between the space its config names and the space it is linked to. If the newly named space has no record yet, it appears under **Pending Configurations**, and **Create All** creates it and moves the agent onto it in the same action. If that space is already available to the deployment, nothing about the agent is pending and **Create All** won't move it — delete the agent so its config reads as pending again, then **Create All** recreates it in the space the config names. The recreated agent is a new agent, so chats from before the delete don't carry over to it.

<Warning>
  Changing an entry's `name` reads as a new entry: reconciling creates a new space or agent, and the record created from the old name stays behind with everything tied to it — an agent's chats, a space's memories — flagged **(misconfigured)** because its config no longer exists. Delete it from the **Agents** or **Spaces** page once you no longer need it.
</Warning>

## Space scope

Spaces live at the account level, so one space can be used by agents in more than one deployment. When a space is created, you choose its scope:

* **Global** — one space that agents in every deployment can use.
* **Per deployment** — the space is available to a single deployment only.

You pick the scope when you [reconcile](#reconciliation): the **Create All** panel's **Create Spaces** control offers **Global** and **Per deployment**. You can change the scope of an existing space later on its page, under **Agents** → **Spaces**.

Spaces created per deployment are named after the deployment, for example `Product (production)` and `Product (staging)`. Only the displayed name changes — the space stays linked to the `spaces:` entry it was created from, so the YAML entry keeps matching.

Choose per-deployment scope when the same `spaces:` entry is declared in several deployments — typically development, staging, and production fed from branches of one data model — and you don't want them sharing what the space stores.

<Warning>
  Creating the spaces again does not split a space that was created as global: it already counts as created for every deployment, so **Create All** creates nothing new. To split one, re-scope it to a deployment on its space page, then run **Create All** for the other deployments.
</Warning>

Spaces created before this option existed have no scope stored. Cube infers the deployment they belong to from the agents linked to them, and the Spaces list shows them as **Not scoped**. Set the scope explicitly on the space page to make it definite.

### Scope affects storage, not configuration

Scope never changes where configuration comes from. Agents always belong to a single deployment, and the `spaces:` and `agents:` entries, rules, and certified queries that shape an agent are read from the `agents/` directory of the data model of that deployment, on that deployment's branch. A global space does not merge the configuration of the deployments that use it.

What a global space shares is storage: the space itself and the data held against it — memories in particular. Two deployments using the same global space read and write the same memories, while each of them still applies its own `agents/` configuration.

## Attaching rules and certified queries to a space

In the single-agent setup, [rules](/admin/ai/rules) and [certified queries](/admin/ai/certified-queries) belong to the implicit `auto` space. In a multi-agent setup, you must attach each rule and certified query to a specific space using the `space` property in the Markdown frontmatter:

```markdown theme={"dark"}
<!-- agents/rules/fiscal-year.md -->
---
space: sales-analytics
type: always
---
Always use fiscal year starting April 1st when analyzing dates.
```

```markdown theme={"dark"}
<!-- agents/certified_queries/quarterly-revenue.md -->
---
space: sales-analytics
description: "Apply when the user asks about quarterly revenue"
user_request: "What is the revenue by quarter?"
---
SELECT
  DATE_TRUNC('quarter', order_date) AS quarter,
  SUM(amount) AS revenue
FROM orders
WHERE status != 'cancelled'
GROUP BY 1
ORDER BY 1
```

You can also organize rules and certified queries into space-named subdirectories. Files placed under `agents/rules/<space-name>/` or `agents/certified_queries/<space-name>/` are attached to that space automatically — no `space` frontmatter required.

## Complete example

```yaml theme={"dark"}
# agents/config.yml
spaces:
  - name: sales-analytics
    description: "Space for sales team analytics and reporting"

  - name: marketing-analytics
    description: "Space for marketing team analytics"

agents:
  - name: sales-assistant
    description: "AI assistant for sales analytics and reporting"
    space: sales-analytics
    llm: claude_4_6_sonnet
    accessible_views:
      - orders_view
      - customers_view
      - products_view
    memory_mode: user

  - name: marketing-analyst
    description: "AI assistant for marketing analytics"
    space: marketing-analytics
    llm: gpt_5
    memory_mode: user
```


# Rules
Source: https://docs.cube.dev/admin/ai/rules

Define instructions in your data model repository that guide the agent's behavior.

Rules are instructions that guide the agent's behavior — encoding business definitions, calculation methods, domain terminology, and analytical approaches the agent should follow when answering questions.

Rules are configured as code in your [data model repository](/admin/ai#agent-configuration), alongside your cubes and views. This enables version control, code review, and consistent behavior across environments.

## Rule types

| Type              | When applied                                                                                 | Best for                                                              |
| ----------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `always`          | Injected into every agent interaction.                                                       | Fundamental business definitions, default calculations, domain terms. |
| `agent_requested` | Conditionally applied when the agent determines the rule is relevant to the current request. | Scenario-specific guidance, specialized analysis methods.             |

For `agent_requested` rules, the `description` field is what the agent matches against the user's request to decide whether the rule is relevant — write it as a short summary of when this rule applies. `always` rules don't need a `description` since they're injected into every interaction regardless.

## Defining rules

Rules are defined as Markdown files under `agents/rules/`. Each rule lives in its own file: the YAML frontmatter holds metadata, and the Markdown body is the rule prompt.

```markdown theme={"dark"}
<!-- agents/rules/fiscal-year.md -->
---
type: always
---
Always use fiscal year starting April 1st when analyzing dates.
Q1 is April–June, Q2 is July–September, Q3 is October–December, Q4 is January–March.
```

For `agent_requested` rules, add a `description` so the agent can decide when the rule applies:

```markdown theme={"dark"}
<!-- agents/rules/cart-abandonment.md -->
---
description: "Apply when the user asks about cart abandonment"
type: agent_requested
---
For cart abandonment analysis, segment by device type and traffic source.
```

Files placed under a `rules/` directory are treated as rules automatically — no `kind` property is required. The `name` is inferred from the file name (e.g., `fiscal-year.md` → `fiscal-year`).

### Frontmatter properties

| Property      | Type   | Required | Description                                                                                                                       |
| ------------- | ------ | :------: | --------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string |    No    | Unique identifier. Inferred from the file name if omitted.                                                                        |
| `description` | string |    No    | Required for `agent_requested` rules — used by the agent to decide when the rule applies. Optional and unused for `always` rules. |
| `type`        | string |    Yes   | Either `always` or `agent_requested`.                                                                                             |
| `prompt`      | string |    No    | Rule prompt. Falls back to the Markdown body if omitted.                                                                          |

### Inlining rules in YAML

You can also inline rules directly in `agents/config.yml` under a `rules` key:

```yaml theme={"dark"}
# agents/config.yml
rules:
  - name: fiscal-year
    prompt: "Always use fiscal year starting April 1st when analyzing dates."
    type: always

  - name: efficiency-analysis
    description: "Apply when the user asks about sales efficiency"
    prompt: "When analyzing sales efficiency, calculate as deal size divided by sales cycle length."
    type: agent_requested
```

Inline rules accept the same properties as Markdown rules — `name`, `description`, `prompt` (required), and `type` (required).

<Note>
  Rules inlined at the root of `agents/config.yml` are attached to the implicit `auto` space and applied to the default agent in a [single-agent setup](/admin/ai). In a [multi-agent setup](/admin/ai/multi-agent), attach rules to a specific space by inlining them under that space's `rules` key (or by placing Markdown files under `agents/rules/<space-name>/`).
</Note>

## Writing effective rules

Good rules are specific, actionable, and encode context the agent wouldn't otherwise know about your business.

**Do:**

* "Customer churn rate is customers lost ÷ total customers at the start of the period."
* "When analyzing quarterly performance, always compare against the same quarter of the previous year."
* "Our fiscal year starts in October."

**Don't:**

* "Be helpful." (too vague)
* "Always be accurate." (redundant)
* "Consider all factors." (too broad)

### Domain examples

**E-commerce:**

```markdown theme={"dark"}
<!-- agents/rules/customer-lifetime-value.md -->
---
type: always
---
Customer lifetime value equals average order value × purchase frequency × customer lifespan.
```

```markdown theme={"dark"}
<!-- agents/rules/cart-abandonment.md -->
---
description: "Apply when the user asks about cart abandonment"
type: agent_requested
---
For cart abandonment analysis, segment by device type and traffic source.
```

**SaaS:**

```markdown theme={"dark"}
<!-- agents/rules/mrr-growth.md -->
---
type: always
---
MRR growth rate excludes one-time charges and setup fees.
```

```markdown theme={"dark"}
<!-- agents/rules/churn-segmentation.md -->
---
description: "Apply when the user asks about churn analysis"
type: agent_requested
---
When analyzing churn, distinguish between voluntary and involuntary churn.
```

## Resolving conflicts

When multiple rules could apply, follow these guidelines:

1. **Review existing rules** before adding new ones to avoid contradictions.
2. **Use specific triggers** in `agent_requested` rules so the agent knows when each rule applies.
3. **Prefer specificity over breadth** — narrowly scoped rules override broader defaults more cleanly.
4. **Test rule combinations** with sample queries before relying on them.

If two `always` rules directly contradict each other, the agent will surface the conflict in its response. Resolve such conflicts by editing the rules in your repository and redeploying.


# Skills
Source: https://docs.cube.dev/admin/ai/skills

Package reusable, named agent workflows in your data model repository that users can run on demand from chat.

Skills are reusable, named instruction packages for the agent — saved workflows a user
can run on demand wherever they work with the agent, including
[Analytics Chat](/docs/explore-analyze/analytics-chat), Workbooks, dashboards, and the
IDE. Instead of re-typing the same multi-step request ("produce a weekly revenue report,
broken down by region, with week-over-week trends…"), a user picks a skill and the agent
follows the workflow you've defined.

Skills are configured as code in your [data model repository](/admin/ai#agent-configuration),
alongside your cubes and views, so they're versioned, reviewed, and deployed like the rest
of your Cube project.

<Note>
  A skill guides what the agent does using the same data access the agent already has. The
  first version of skills is instructions-only — `title`, `description`, and instructions.
  There is no per-skill data scoping or external actions yet.
</Note>

## Defining skills

Skills are defined as Markdown files under `agents/skills/`. Each skill lives in its own
file: the YAML frontmatter holds metadata, and the Markdown body is the instructions the
agent follows.

```markdown theme={"dark"}
<!-- agents/skills/weekly-revenue-report.md -->
---
title: "Weekly revenue report"
description: "Use when the user asks for a weekly revenue summary, a weekly revenue report, or week-over-week revenue trends."
---
Produce a weekly revenue report:

1. Report total revenue for the requested week, alongside the prior week and the
   week-over-week percentage change.
2. Break revenue down by region, sorted from highest to lowest.
3. Highlight any region whose revenue changed by more than 10% week over week.
4. If the user names a region or a time range, scope the report accordingly.
```

Files placed under a `skills/` directory are treated as skills automatically — no `kind`
property is required. The `name` is inferred from the file name (e.g.,
`weekly-revenue-report.md` → `weekly-revenue-report`). Nested folders are allowed for
organization but do not namespace the skill — skill names must be unique across the
entire `skills/` directory.

### Frontmatter properties

| Property      | Type   | Required | Description                                                                 |
| ------------- | ------ | :------: | --------------------------------------------------------------------------- |
| `title`       | string |    Yes   | User-facing label shown on the skill button and in the `/` menu.            |
| `description` | string |    Yes   | What the agent matches free-text requests against to auto-select the skill. |
| `name`        | string |    No    | Unique identifier. Inferred from the file name if omitted.                  |

The Markdown body is the skill's instructions.

### Inlining skills in YAML

You can also inline skills directly in `agents/config.yml` under a `skills` key:

```yaml theme={"dark"}
# agents/config.yml
skills:
  - name: weekly-revenue-report
    title: "Weekly revenue report"
    description: "Use when the user asks for a weekly revenue summary or week-over-week trends."
    instructions: |
      Produce a weekly revenue report:
      1. Total revenue for the requested week, with the week-over-week change.
      2. A breakdown by region, sorted by revenue descending.
      3. Highlight any region that moved more than 10% week over week.
```

Inline skills use the same `name`, `title` (required), and `description` (required) as
Markdown skills. Since there is no Markdown body in YAML, provide the instructions inline
via the `instructions` key.

<Note>
  Skills inlined at the root of `agents/config.yml` are attached to the implicit `auto`
  space and applied to the default agent in a [single-agent setup](/admin/ai). In a
  [multi-agent setup](/admin/ai/multi-agent), attach skills to a specific space by inlining
  them under that space's `skills` key (or by placing Markdown files under
  `agents/skills/<space-name>/`).
</Note>

## How skills are surfaced

Skills use **progressive disclosure**. The agent is given a compact catalog of every
available skill — just the `name`, `title`, and `description` — so it knows what each
skill is for without carrying the full instructions. When a skill is run, the agent loads
its complete instructions on demand.

* The chat UI only ever receives a skill's `name`, `title`, and `description`. The full
  instruction body stays server-side and is never sent to the browser.
* Skills are surfaced through a viewer-accessible deployment endpoint, so they work for
  any configured agent as well as the default `auto` agent.
* Because the agent matches against `description`, a well-written description makes
  automatic matching more reliable.

For how skills appear and run in chat — buttons, the `/` menu, and automatic matching —
see [Agent skills](/docs/explore-analyze/skills).

## Deploying and testing

Skills ship through the normal Cube development flow: author the skill on a development
branch, commit, and merge to your production branch. Because skills live on the branch, a
skill on a development branch is testable before it reaches production — open chat against
the dev branch and run the skill to confirm it behaves as intended.

## Permissions

Authoring skills requires data-model edit access — the same access needed to define
[rules](/admin/ai/rules) and [certified queries](/admin/ai/certified-queries). In Cube
Cloud's built-in roles, that means the **Admin** or **Developer**
[roles](/admin/users-and-permissions/roles-and-permissions), or a custom role with
semantic-model edit access.

Running skills is available to anyone with chat access, including **Explorer** and
**Viewer** roles. In-product tips that promote authoring skills, rules, and certified
queries are role-aware and shown only to developers.

## Writing effective skills

* **Phrase `description` as a "use when…" statement.** This is what the agent matches
  against incoming requests, so describe the situations the skill applies to.
* **Write instructions as an explicit workflow.** Number the steps and state the output
  you expect, the same way you'd brief an analyst.
* **Account for added context.** Users can add specifics after selecting a skill (e.g.,
  `/weekly-revenue-report for EMEA, last 6 weeks`), so instruct the agent to honor a
  named region or time range when provided.
* **Keep each skill focused.** One skill should cover one well-defined workflow; create
  separate skills for distinct tasks.


# Querying concurrency
Source: https://docs.cube.dev/admin/connect-to-data/concurrency

All queries to data APIs are processed asynchronously via a query queue. It allows to optimize the load and increase querying performance.

## Query queue

The query queue allows to deduplicate queries to API instances and insulate upstream
data sources from query spikes. It also allows to execute queries to data sources
concurrently for increased performance.

By default, Cube uses a *single* query queue for queries from all API instances and
the refresh worker to all configured data sources.

<Note>
  You can read more about the query queue in the [this blog post](https://cube.dev/blog/how-you-win-by-using-cube-store-part-1#query-queue-in-cube).
</Note>

### Multiple query queues

You can use the [`context_to_orchestrator_id`][ref-context-to-orchestrator-id]
configuration option to route queries to multiple queues based on the security
context.

<Warning>
  If you're configuring multiple connections to data sources via the [`driver_factory`
  configuration option][ref-driver-factory], you **must** also configure
  `context_to_orchestrator_id` to ensure that queries are routed to correct queues.
</Warning>

## Data sources

Cube supports various kinds of [data sources][ref-data-sources], ranging from cloud
data warehouses to embedded databases. Each data source scales differently,
therefore Cube provides sound defaults for each kind of data source out-of-the-box.

### Data source concurrency

By default, Cube uses the following concurrency settings for data sources:

| Data source                     | Default concurrency                                                          |
| ------------------------------- | ---------------------------------------------------------------------------- |
| [Amazon Athena][ref-athena]     | 10                                                                           |
| [Amazon Redshift][ref-redshift] | 5                                                                            |
| [Apache Pinot][ref-pinot]       | 10                                                                           |
| [ClickHouse][ref-clickhouse]    | 10                                                                           |
| [Databricks][ref-databricks]    | 10                                                                           |
| [Firebolt][ref-firebolt]        | 10                                                                           |
| [Google BigQuery][ref-bigquery] | 10                                                                           |
| [Snowflake][ref-snowflake]      | 8                                                                            |
| All other data sources          | 5 or [less, if specified in the driver][link-github-data-source-concurrency] |

You can use the [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency) environment variable to adjust the maximum
number of concurrent queries to a data source. It's recommended to use the default
configuration unless you're sure that your data source can handle more concurrent
queries.

### Connection pooling

For data sources that support connection pooling, the maximum number of concurrent
connections to the database can also be set by using the [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool)
environment variable. If changing this from the default, you must ensure that the
new value is greater than the number of concurrent connections used by Cube's query
queues and the refresh worker.

## Refresh worker

By default, the refresh worker uses the same concurrency settings as API instances.
However, you can override this behvaior in the refresh worker
[configuration][ref-preagg-refresh].

[ref-data-apis]: /reference

[ref-data-sources]: /admin/connect-to-data/data-sources

[ref-context-to-orchestrator-id]: /reference/configuration/config#context_to_orchestrator_id

[ref-driver-factory]: /reference/configuration/config#driver_factory

[ref-preagg-refresh]: /docs/pre-aggregations/refreshing-pre-aggregations#configuration

[ref-athena]: /admin/connect-to-data/data-sources/aws-athena

[ref-clickhouse]: /admin/connect-to-data/data-sources/clickhouse

[ref-databricks]: /admin/connect-to-data/data-sources/databricks-jdbc

[ref-firebolt]: /admin/connect-to-data/data-sources/firebolt

[ref-pinot]: /admin/connect-to-data/data-sources/pinot

[ref-redshift]: /admin/connect-to-data/data-sources/aws-redshift

[ref-snowflake]: /admin/connect-to-data/data-sources/snowflake

[ref-bigquery]: /admin/connect-to-data/data-sources/google-bigquery

[link-github-data-source-concurrency]: https://github.com/search?q=repo%3Acube-js%2Fcube+getDefaultConcurrency+path%3Apackages%2Fcubejs-&type=code


# Amazon Athena
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/aws-athena

Give Cube IAM access to Athena, an S3 query-results path, region and catalog settings, plus optional assumed-role credentials.

## Prerequisites

* [A set of IAM credentials][aws-docs-athena-access] which allow access to [AWS
  Athena][aws-athena]
* [The AWS region][aws-docs-regions]
* [The S3 bucket][aws-s3] on AWS to [store query results][aws-docs-athena-query]

<Info>
  **Read-only access to your source data is sufficient.** Cube reads it with
  `athena:*QueryExecution`/`GetQueryResults`/`GetWorkGroup`, `glue:Get*` metadata,
  and `s3:GetObject`/`ListBucket`. Athena also **always** writes query results to
  [`CUBEJS_AWS_S3_OUTPUT_LOCATION`](#environment-variables) — even for `SELECT`s —
  so that location needs `s3:PutObject` (plus the multipart actions), but this is
  Athena's own staging bucket, not your source data. Writes to source data are
  only needed for [pre-aggregations](#pre-aggregation-build-strategies) built
  inside Athena. For a ready-to-use IAM policy, see the
  [AWS OIDC guide][ref-oidc-aws-athena].
</Info>

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

#### Static Credentials

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=athena
CUBEJS_AWS_KEY=AKIA************
CUBEJS_AWS_SECRET=****************************************
CUBEJS_AWS_REGION=us-east-1
CUBEJS_AWS_S3_OUTPUT_LOCATION=s3://my-athena-output-bucket
CUBEJS_AWS_ATHENA_WORKGROUP=primary
CUBEJS_DB_NAME=my_non_default_athena_database
CUBEJS_AWS_ATHENA_CATALOG=AwsDataCatalog
```

#### IAM Role Assumption

For enhanced security, you can configure Cube to assume an IAM role to access Athena:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=athena
CUBEJS_AWS_ATHENA_ASSUME_ROLE_ARN=arn:aws:iam::123456789012:role/AthenaAccessRole
CUBEJS_AWS_REGION=us-east-1
CUBEJS_AWS_S3_OUTPUT_LOCATION=s3://my-athena-output-bucket
CUBEJS_AWS_ATHENA_WORKGROUP=primary
# Optional: if the role requires an external ID
CUBEJS_AWS_ATHENA_ASSUME_ROLE_EXTERNAL_ID=unique-external-id
```

When using role assumption:

* If running in AWS (EC2, ECS, EKS with IRSA), the driver will use the instance's IAM role or service account to assume the target role
* You can also provide [`CUBEJS_AWS_KEY`](/reference/configuration/environment-variables#cubejs_aws_key) and [`CUBEJS_AWS_SECRET`](/reference/configuration/environment-variables#cubejs_aws_secret) as master credentials for the role assumption

### Cube Cloud

<Info>
  In some cases you'll need to allow connections from your Cube Cloud deployment
  IP address to your database. You can copy the IP address from either the
  Database Setup step in deployment creation, or from **Settings →
  Configuration** in your deployment.
</Info>

In Cube Cloud, select **AWS Athena** when creating a new deployment and fill in
the required fields:

<Frame>
  <img alt="Cube Cloud AWS Athena Configuration Screen" />
</Frame>

#### OIDC workload identity

Instead of static credentials, Cube Cloud deployments can authenticate to
Athena with [OIDC workload identity][ref-oidc-aws-athena]: an IAM role in
your account trusts Cube's OIDC issuer, and the driver assumes it through
the AWS SDK's default credential chain — no access keys to provision or
rotate.

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=athena
AWS_ROLE_ARN=arn:aws:iam::123456789012:role/cube-deployment-acme
CUBEJS_AWS_REGION=us-east-1
CUBEJS_AWS_S3_OUTPUT_LOCATION=s3://my-athena-output-bucket
```

See the [AWS OIDC guide][ref-oidc-aws-athena] for the IAM role, trust
policy, and permissions setup.

Cube Cloud also supports connecting to data sources within private VPCs
if [single-tenant infrastructure][ref-dedicated-infra] is used. Check out the
[VPC connectivity guide][ref-cloud-conf-vpc] for details.

[ref-dedicated-infra]: /admin/deployment/infrastructure#dedicated-infrastructure

[ref-cloud-conf-vpc]: /admin/deployment/dedicated

## Environment Variables

| Environment Variable                                                                                                                    | Description                                                                                                            | Possible Values                                  |    Required   |
| --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | :-----------: |
| [`CUBEJS_AWS_KEY`](/reference/configuration/environment-variables#cubejs_aws_key)                                                       | The AWS Access Key ID to use for database connections                                                                  | A valid AWS Access Key ID                        | ❌<sup>1</sup> |
| [`CUBEJS_AWS_SECRET`](/reference/configuration/environment-variables#cubejs_aws_secret)                                                 | The AWS Secret Access Key to use for database connections                                                              | A valid AWS Secret Access Key                    | ❌<sup>1</sup> |
| [`CUBEJS_AWS_REGION`](/reference/configuration/environment-variables#cubejs_aws_region)                                                 | The AWS region of the Cube deployment                                                                                  | [A valid AWS region][aws-docs-regions]           |       ✅       |
| `CUBEJS_AWS_S3_OUTPUT_LOCATION`                                                                                                         | The S3 path to store query results made by the Cube deployment                                                         | A valid S3 path                                  |       ❌       |
| [`CUBEJS_AWS_ATHENA_WORKGROUP`](/reference/configuration/environment-variables#cubejs_aws_athena_workgroup)                             | The name of the workgroup in which the query is being started                                                          | [A valid Athena Workgroup][aws-athena-workgroup] |       ❌       |
| [`CUBEJS_AWS_ATHENA_CATALOG`](/reference/configuration/environment-variables#cubejs_aws_athena_catalog)                                 | The name of the catalog to use by default                                                                              | [A valid Athena Catalog name][awsdatacatalog]    |       ❌       |
| [`CUBEJS_AWS_ATHENA_ASSUME_ROLE_ARN`](/reference/configuration/environment-variables#cubejs_aws_athena_assume_role_arn)                 | The ARN of the IAM role to assume for Athena access                                                                    | A valid IAM role ARN                             |       ❌       |
| [`CUBEJS_AWS_ATHENA_ASSUME_ROLE_EXTERNAL_ID`](/reference/configuration/environment-variables#cubejs_aws_athena_assume_role_external_id) | The external ID to use when assuming the IAM role (if required by the role's trust policy)                             | A string                                         |       ❌       |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)                                                       | The name of the database to use by default                                                                             | A valid Athena Database name                     |       ❌       |
| [`CUBEJS_DB_SCHEMA`](/reference/configuration/environment-variables#cubejs_db_schema)                                                   | The name of the schema to use as `information_schema` filter. Reduces count of tables loaded during schema generation. | A valid schema name                              |       ❌       |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)                                               | The number of [concurrent queries][ref-data-source-concurrency] to the data source                                     | A valid number                                   |       ❌       |

<sup>1</sup> Either provide [`CUBEJS_AWS_KEY`](/reference/configuration/environment-variables#cubejs_aws_key) and [`CUBEJS_AWS_SECRET`](/reference/configuration/environment-variables#cubejs_aws_secret) for static credentials, or use [`CUBEJS_AWS_ATHENA_ASSUME_ROLE_ARN`](/reference/configuration/environment-variables#cubejs_aws_athena_assume_role_arn) for role-based authentication. When using role assumption without static credentials, the driver will use the AWS SDK's default credential chain (IAM instance profile, EKS IRSA, or [OIDC workload identity][ref-oidc-aws-athena] in Cube Cloud).

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
be used in pre-aggregations when using AWS Athena as a source database. To learn
more about AWS Athena's support for approximate aggregate functions, [click
here][aws-athena-docs-approx-agg-fns].

## Pre-Aggregation Build Strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Batching      |              ❌             |      ✅      |
| Export Bucket |              ❌             |      ❌      |

By default, AWS Athena uses a [batching][self-preaggs-batching] strategy to
build pre-aggregations.

### Batching

No extra configuration is required to configure batching for AWS Athena.

<Info>
  Batching builds pre-aggregations inside Athena via `CREATE TABLE AS SELECT`, the
  only case needing more than read-only access: `glue:CreateTable` on the
  pre-aggregations schema plus `s3:PutObject` on its S3 location.
</Info>

### Export Bucket

<Warning>
  AWS Athena **only** supports using AWS S3 for export buckets.
</Warning>

#### AWS S3

For [improved pre-aggregation performance with large
datasets][ref-caching-large-preaggs], enable export bucket functionality by
configuring Cube with the following environment variables:

<Info>
  Ensure the AWS credentials are correctly configured in IAM to allow reads and
  writes to the export bucket in S3.

  The export bucket strategy uses Athena's `UNLOAD` to write directly to the
  bucket — no temporary tables, no Glue Data Catalog writes. The only extra
  permission beyond read-only querying is `s3:PutObject` on the export bucket.
</Info>

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET_TYPE=s3
CUBEJS_DB_EXPORT_BUCKET=my.bucket.on.s3
CUBEJS_DB_EXPORT_BUCKET_AWS_KEY=<AWS_KEY>
CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET=<AWS_SECRET>
CUBEJS_DB_EXPORT_BUCKET_AWS_REGION=<AWS_REGION>
```

## SSL

Cube does not require any additional configuration to enable SSL as AWS Athena
connections are made over HTTPS.

[aws-athena]: https://aws.amazon.com/athena

[aws-athena-workgroup]: https://docs.aws.amazon.com/athena/latest/ug/workgroups-benefits.html

[awsdatacatalog]: https://docs.aws.amazon.com/athena/latest/ug/understanding-tables-databases-and-the-data-catalog.html

[aws-s3]: https://aws.amazon.com/s3/

[aws-docs-athena-access]: https://docs.aws.amazon.com/athena/latest/ug/security-iam-athena.html

[aws-docs-athena-query]: https://docs.aws.amazon.com/athena/latest/ug/querying.html

[aws-docs-regions]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions

[aws-athena-docs-approx-agg-fns]: https://prestodb.io/docs/current/functions/aggregate.html#approximate-aggregate-functions

[ref-caching-large-preaggs]: /docs/pre-aggregations/using-pre-aggregations#export-bucket

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[ref-oidc-aws-athena]: /admin/deployment/oidc/aws#athena

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[self-preaggs-batching]: #batching


# AWS Redshift
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/aws-redshift

Authenticate Cube to Amazon Redshift with database passwords or IAM roles and ensure network reachability from your deployment.

## Prerequisites

* The [hostname][aws-redshift-docs-connection-string] for the [AWS
  Redshift][aws-redshift] cluster
* The [username/password][aws-redshift-docs-users] for the [AWS
  Redshift][aws-redshift] cluster **or** IAM credentials with
  `redshift:GetClusterCredentialsWithIAM` and `redshift:DescribeClusters`
  permissions
* The name of the database to use within the [AWS Redshift][aws-redshift]
  cluster

<Info>
  If the cluster is configured within a [VPC][aws-vpc], then Cube **must** have a
  network route to the cluster.
</Info>

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

#### Password Authentication

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=redshift
CUBEJS_DB_HOST=my-redshift-cluster.cfbs3dkw1io8.eu-west-1.redshift.amazonaws.com
CUBEJS_DB_NAME=my_redshift_database
CUBEJS_DB_USER=<REDSHIFT_USER>
CUBEJS_DB_PASS=<REDSHIFT_PASSWORD>
```

#### IAM Authentication

For enhanced security, you can configure Cube to use IAM authentication
instead of username and password. When running in AWS (EC2, ECS, EKS with
IRSA), the driver can use the instance's IAM role to obtain temporary
database credentials automatically.

Omit [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user) and [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass) to enable IAM authentication:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=redshift
CUBEJS_DB_HOST=my-redshift-cluster.xxx.eu-west-1.redshift.amazonaws.com
CUBEJS_DB_NAME=my_redshift_database
CUBEJS_DB_SSL=true
CUBEJS_DB_REDSHIFT_AWS_REGION=eu-west-1
CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER=my-redshift-cluster
```

The driver uses the AWS SDK's default credential chain (IAM instance profile,
EKS IRSA, etc.) to obtain temporary database credentials via the
`redshift:GetClusterCredentialsWithIAM` API.

#### IAM Role Assumption

For cross-account access or enhanced security, you can configure Cube to assume
an IAM role:

```dotenv theme={"dark"}
CUBEJS_DB_REDSHIFT_AWS_REGION=eu-west-1
CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER=my-redshift-cluster
CUBEJS_DB_REDSHIFT_ASSUME_ROLE_ARN=arn:aws:iam::123456789012:role/RedshiftAccessRole
CUBEJS_DB_REDSHIFT_ASSUME_ROLE_EXTERNAL_ID=unique-external-id
```

### Cube Cloud

<Info>
  In some cases you'll need to allow connections from your Cube Cloud deployment
  IP address to your database. You can copy the IP address from either the
  Database Setup step in deployment creation, or from **Settings →
  Configuration** in your deployment.
</Info>

The following fields are required when creating an AWS Redshift connection:

<Frame>
  <img alt="Cube Cloud AWS Redshift Configuration Screen" />
</Frame>

#### OIDC workload identity

Instead of a database password, Cube Cloud deployments can authenticate to
Redshift with [OIDC workload identity][ref-oidc-aws-redshift]: an IAM role
in your account trusts Cube's OIDC issuer, and the driver uses it to obtain
temporary database credentials via [IAM authentication](#iam-authentication).
Set `AWS_ROLE_ARN` alongside the IAM authentication variables and omit
`CUBEJS_DB_USER` / `CUBEJS_DB_PASS`:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=redshift
AWS_ROLE_ARN=arn:aws:iam::123456789012:role/cube-deployment-acme
CUBEJS_DB_HOST=my-redshift-cluster.xxx.eu-west-1.redshift.amazonaws.com
CUBEJS_DB_NAME=my_redshift_database
CUBEJS_DB_SSL=true
CUBEJS_DB_REDSHIFT_AWS_REGION=eu-west-1
CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER=my-redshift-cluster
```

See the [AWS OIDC guide][ref-oidc-aws-redshift] for the IAM role, trust
policy, and permissions setup.

Cube Cloud also supports connecting to data sources within private VPCs
if [single-tenant infrastructure][ref-dedicated-infra] is used. Check out the
[VPC connectivity guide][ref-cloud-conf-vpc] for details.

[ref-dedicated-infra]: /admin/deployment/infrastructure#dedicated-infrastructure

[ref-cloud-conf-vpc]: /admin/deployment/dedicated

## Environment Variables

| Environment Variable                                                                                                                      | Description                                                                        | Possible Values                        |    Required   |
| ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------- | :-----------: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host)                                                         | The host URL for a database                                                        | A valid database host URL              |       ✅       |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port)                                                         | The port for the database connection                                               | A valid port number                    |       ❌       |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)                                                         | The name of the database to connect to                                             | A valid database name                  |       ✅       |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)                                                         | The username used to connect to the database                                       | A valid database username              | ✅<sup>1</sup> |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)                                                         | The password used to connect to the database                                       | A valid database password              | ✅<sup>1</sup> |
| [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl)                                                           | If `true`, enables SSL encryption for database connections from Cube               | `true`, `false`                        |       ❌       |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool)                                                 | The maximum number of concurrent database connections to pool. Default is `16`     | A valid number                         |       ❌       |
| [`CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER`](/reference/configuration/environment-variables#cubejs_db_redshift_cluster_identifier)           | The Redshift cluster identifier. Required for IAM authentication                   | A valid cluster identifier             |       ❌       |
| [`CUBEJS_DB_REDSHIFT_AWS_REGION`](/reference/configuration/environment-variables#cubejs_db_redshift_aws_region)                           | The AWS region of the Redshift cluster. Required for IAM authentication            | [A valid AWS region][aws-docs-regions] |       ❌       |
| [`CUBEJS_DB_REDSHIFT_ASSUME_ROLE_ARN`](/reference/configuration/environment-variables#cubejs_db_redshift_assume_role_arn)                 | The ARN of the IAM role to assume for cross-account access                         | A valid IAM role ARN                   |       ❌       |
| [`CUBEJS_DB_REDSHIFT_ASSUME_ROLE_EXTERNAL_ID`](/reference/configuration/environment-variables#cubejs_db_redshift_assume_role_external_id) | The external ID for the assumed role's trust policy                                | A string                               |       ❌       |
| [`CUBEJS_DB_EXPORT_BUCKET_REDSHIFT_ARN`](/reference/configuration/environment-variables#cubejs_db_export_bucket_redshift_arn)             |                                                                                    |                                        |       ❌       |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)                                                 | The number of [concurrent queries][ref-data-source-concurrency] to the data source | A valid number                         |       ❌       |

<sup>1</sup> Required when using password-based authentication. When using IAM authentication, omit these and set [`CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER`](/reference/configuration/environment-variables#cubejs_db_redshift_cluster_identifier) and [`CUBEJS_DB_REDSHIFT_AWS_REGION`](/reference/configuration/environment-variables#cubejs_db_redshift_aws_region) instead. The driver uses the AWS SDK's default credential chain (IAM instance profile, EKS IRSA, or [OIDC workload identity][ref-oidc-aws-redshift] in Cube Cloud) to obtain temporary database credentials.

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
not be used in pre-aggregations when using AWS Redshift as a source database.

## Pre-Aggregation Build Strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Batching      |              ❌             |      ✅      |
| Export Bucket |              ❌             |      ❌      |

By default, AWS Redshift uses [batching][self-preaggs-batching] to build
pre-aggregations.

### Batching

Cube requires the Redshift user to have ownership of a schema in Redshift to
support pre-aggregations. By default, the schema name is `prod_pre_aggregations`.
It can be set using the [`pre_aggregations_schema` configration
option][ref-conf-preaggs-schema].

No extra configuration is required to configure batching for AWS Redshift.

### Export bucket

<Warning>
  AWS Redshift **only** supports using AWS S3 for export buckets.
</Warning>

#### AWS S3

For [improved pre-aggregation performance with large
datasets][ref-caching-large-preaggs], enable export bucket functionality by
configuring Cube with the following environment variables:

<Info>
  Ensure the AWS credentials are correctly configured in IAM to allow reads and
  writes to the export bucket in S3.
</Info>

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET_TYPE=s3
CUBEJS_DB_EXPORT_BUCKET=my.bucket.on.s3
CUBEJS_DB_EXPORT_BUCKET_AWS_KEY=<AWS_KEY>
CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET=<AWS_SECRET>
CUBEJS_DB_EXPORT_BUCKET_AWS_REGION=<AWS_REGION>
```

## SSL

To enable SSL-encrypted connections between Cube and AWS Redshift, set the
[`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) environment variable to `true`. For more information on how to
configure custom certificates, please check out [Enable SSL Connections to the
Database][ref-recipe-enable-ssl].

[aws-redshift-docs-connection-string]: https://docs.aws.amazon.com/redshift/latest/mgmt/configuring-connections.html#connecting-drivers

[aws-redshift-docs-users]: https://docs.aws.amazon.com/redshift/latest/dg/r_Users.html

[aws-redshift]: https://aws.amazon.com/redshift/

[aws-vpc]: https://aws.amazon.com/vpc/

[aws-docs-regions]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions

[ref-caching-large-preaggs]: /docs/pre-aggregations/using-pre-aggregations#export-bucket

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[ref-oidc-aws-redshift]: /admin/deployment/oidc/aws#redshift

[ref-recipe-enable-ssl]: /recipes/configuration/using-ssl-connections-to-data-source

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[self-preaggs-batching]: #batching

[ref-conf-preaggs-schema]: /reference/configuration/config#pre_aggregations_schema


# ClickHouse
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/clickhouse

Connect Cube to ClickHouse for low-latency analytics, including host credentials and driver-specific connection options.

[ClickHouse](https://clickhouse.com) is a fast and resource efficient
[open-source database](https://github.com/ClickHouse/ClickHouse) for real-time
applications and analytics.

## Prerequisites

* The hostname for the [ClickHouse][clickhouse] database server
* The [username/password][clickhouse-docs-users] for the
  [ClickHouse][clickhouse] database server

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=clickhouse
CUBEJS_DB_HOST=my.clickhouse.host
CUBEJS_DB_NAME=my_clickhouse_database
CUBEJS_DB_USER=clickhouse_user
CUBEJS_DB_PASS=**********
```

## Environment Variables

| Environment Variable                                                                                                  | Description                                                                        | Possible Values           | Required |
| --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------- | :------: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host)                                     | The host URL for a database                                                        | A valid database host URL |     ✅    |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port)                                     | The port for the database connection                                               | A valid port number       |     ❌    |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)                                     | The name of the database to connect to                                             | A valid database name     |     ✅    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)                                     | The username used to connect to the database                                       | A valid database username |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)                                     | The password used to connect to the database                                       | A valid database password |     ✅    |
| [`CUBEJS_DB_CLICKHOUSE_READONLY`](/reference/configuration/environment-variables#cubejs_db_clickhouse_readonly)       | Whether the ClickHouse user has read-only access or not                            | `true`, `false`           |     ❌    |
| [`CUBEJS_DB_CLICKHOUSE_COMPRESSION`](/reference/configuration/environment-variables#cubejs_db_clickhouse_compression) | Whether the ClickHouse client has compression enabled or not                       | `true`, `false`           |     ❌    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool)                             | The maximum number of concurrent database connections to pool. Default is `20`     | A valid number            |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)                             | The number of [concurrent queries][ref-data-source-concurrency] to the data source | A valid number            |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-Aggregation Feature Support

When using [pre-aggregations][ref-preaggs] with ClickHouse, you have to define
[indexes][ref-preaggs-indexes] in pre-aggregations. Otherwise, you might get
the following error: `ClickHouse doesn't support pre-aggregations without indexes`.

### `count_distinct_approx`

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
not be used in pre-aggregations when using ClickHouse as a source database.

### `rollup_join`

You can use [`rollup_join` pre-aggregations][ref-preaggs-rollup-join] to join
data from ClickHouse and other data sources inside Cube Store.

Alternatively, you can leverage ClickHouse support for [integration table
engines](https://clickhouse.com/docs/en/engines/table-engines#integration-engines)
to join data from ClickHouse and other data sources inside ClickHouse.
To do so, define table engines in ClickHouse and connect your ClickHouse as the
only data source to Cube.

## Pre-Aggregation Build Strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Batching      |              ✅             |      ✅      |
| Export Bucket |              ✅             |      -      |

By default, ClickHouse uses [batching][self-preaggs-batching] to build
pre-aggregations.

### Batching

No extra configuration is required to configure batching for ClickHouse.

### Export Bucket

<Warning>
  Clickhouse driver **only** supports using AWS S3 for export buckets.
</Warning>

#### AWS S3

For [improved pre-aggregation performance with large
datasets][ref-caching-large-preaggs], enable export bucket functionality by
configuring Cube with the following environment variables:

<Info>
  Ensure the AWS credentials are correctly configured in IAM to allow reads and
  writes to the export bucket in S3.
</Info>

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET_TYPE=s3
CUBEJS_DB_EXPORT_BUCKET=my.bucket.on.s3
CUBEJS_DB_EXPORT_BUCKET_AWS_KEY=<AWS_KEY>
CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET=<AWS_SECRET>
CUBEJS_DB_EXPORT_BUCKET_AWS_REGION=<AWS_REGION>
```

## SSL

To enable SSL-encrypted connections between Cube and ClickHouse, set the
[`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) environment variable to `true`. For more information on how to
configure custom certificates, please check out [Enable SSL Connections to the
Database][ref-recipe-enable-ssl].

## Custom headers

The ClickHouse driver supports forwarding custom HTTP headers on every request to
the ClickHouse server. This is useful when requests pass through a proxy or gateway
that expects additional headers (e.g., for routing or tracing). See the [ClickHouse
JavaScript client configuration][clickhouse-docs-js-config] for more details.

Custom headers can't be configured via environment variables. Instead, use the
[`driver_factory`](/reference/configuration/config#driver_factory) configuration
option to pass a `headers` object to the driver:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('driver_factory')
  def driver_factory(ctx: dict) -> dict:
    return {
      'type': 'clickhouse',
      'headers': {
        'X-Custom-Header': 'value',
        'X-Routing-Group': 'analytics'
      }
    }
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    driverFactory: ({ dataSource }) => ({
      type: "clickhouse",
      headers: {
        "X-Custom-Header": "value",
        "X-Routing-Group": "analytics"
      }
    })
  };
  ```
</CodeGroup>

In multitenant deployments, you can use the [security
context](/embedding/authentication/security-context) to pass per-tenant headers, for example
to forward a user token from the API request down to ClickHouse:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('driver_factory')
  def driver_factory(ctx: dict) -> dict:
    security_context = ctx['securityContext']
    return {
      'type': 'clickhouse',
      'headers': {
        'X-Custom-User-Token': security_context['token']
      }
    }
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    driverFactory: ({ securityContext }) => ({
      type: "clickhouse",
      headers: {
        "X-Custom-User-Token": securityContext.token
      }
    })
  };
  ```
</CodeGroup>

## Query attribution

Cube sets the ClickHouse [`query_id`](https://clickhouse.com/docs/operations/system-tables/query_log)
of every statement it runs to `<cube-query-id>-<uuid>`, where `<cube-query-id>` is the
identifier shown for the query in Query History and `<uuid>` is generated per statement, so
one Cube query matches as many rows as it ran statements. Use it to trace a Cube query to the
statements it produced in ClickHouse:

```sql theme={"dark"}
SELECT query_id, query, event_time
FROM system.query_log
WHERE query_id LIKE '<cube-query-id>%'
```

## Additional Configuration

You can connect to a ClickHouse database when your user's permissions are
[restricted][clickhouse-readonly] to read-only, by setting
[`CUBEJS_DB_CLICKHOUSE_READONLY`](/reference/configuration/environment-variables#cubejs_db_clickhouse_readonly) to `true`.

You can connect to a ClickHouse database with compression enabled, by setting
[`CUBEJS_DB_CLICKHOUSE_COMPRESSION`](/reference/configuration/environment-variables#cubejs_db_clickhouse_compression) to `true`.

[clickhouse]: https://clickhouse.tech/

[clickhouse-docs-users]: https://clickhouse.tech/docs/en/operations/settings/settings-users/

[clickhouse-docs-js-config]: https://clickhouse.com/docs/integrations/javascript#configuration

[clickhouse-readonly]: https://clickhouse.com/docs/en/operations/settings/permissions-for-queries#readonly

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[ref-recipe-enable-ssl]: /recipes/configuration/using-ssl-connections-to-data-source

[ref-caching-large-preaggs]: /docs/pre-aggregations/using-pre-aggregations#export-bucket

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[self-preaggs-batching]: #batching

[ref-preaggs]: /docs/pre-aggregations/using-pre-aggregations

[ref-preaggs-indexes]: /reference/data-modeling/pre-aggregations#indexes

[ref-preaggs-rollup-join]: /reference/data-modeling/pre-aggregations#rollup_join


# Databricks
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/databricks-jdbc

Databricks is a unified data intelligence platform.

[Databricks](https://www.databricks.com) is a unified data intelligence platform.

## Prerequisites

* [A JDK installation][gh-cubejs-jdbc-install]
* The [JDBC URL][databricks-docs-jdbc-url] for the [Databricks][databricks]
  cluster

## Setup

### Environment Variables

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=databricks-jdbc
# CUBEJS_DB_NAME is optional
CUBEJS_DB_NAME=default
# You can find this inside the cluster's configuration
CUBEJS_DB_DATABRICKS_URL=jdbc:databricks://dbc-XXXXXXX-XXXX.cloud.databricks.com:443/default;transportMode=http;ssl=1;httpPath=sql/protocolv1/o/XXXXX/XXXXX;AuthMech=3;UID=token
# You can specify the personal access token separately from [`CUBEJS_DB_DATABRICKS_URL`](/reference/configuration/environment-variables#cubejs_db_databricks_url) by doing this:
CUBEJS_DB_DATABRICKS_TOKEN=XXXXX
# This accepts the Databricks usage policy and must be set to `true` to use the Databricks JDBC driver
CUBEJS_DB_DATABRICKS_ACCEPT_POLICY=true
```

### Docker

Create a `.env` file [as above](#environment-variables), then extend the
`cubejs/cube:jdk` Docker image tag to build a Cube image with the JDBC driver:

```dockerfile theme={"dark"}
FROM cubejs/cube:jdk

COPY . .
RUN npm install
```

You can then build and run the image using the following commands:

```bash theme={"dark"}
docker build -t cube-jdk .
docker run -it -p 4000:4000 --env-file=.env cube-jdk
```

## Environment Variables

| Environment Variable                                                                                                                  | Description                                                                                                   | Possible Values       | Required |
| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------- | :------: |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)                                                     | The name of the database to connect to                                                                        | A valid database name |     ✅    |
| [`CUBEJS_DB_DATABRICKS_URL`](/reference/configuration/environment-variables#cubejs_db_databricks_url)                                 | The URL for a JDBC connection                                                                                 | A valid JDBC URL      |     ✅    |
| [`CUBEJS_DB_DATABRICKS_ACCEPT_POLICY`](/reference/configuration/environment-variables#cubejs_db_databricks_accept_policy)             | Whether or not to accept the license terms for the Databricks JDBC driver                                     | `true`, `false`       |     ✅    |
| [`CUBEJS_DB_DATABRICKS_OAUTH_CLIENT_ID`](/reference/configuration/environment-variables#cubejs_db_databricks_oauth_client_id)         | The OAuth client ID for [service principal][ref-databricks-m2m-oauth] authentication                          | A valid client ID     |     ❌    |
| [`CUBEJS_DB_DATABRICKS_OAUTH_CLIENT_SECRET`](/reference/configuration/environment-variables#cubejs_db_databricks_oauth_client_secret) | The OAuth client secret for [service principal][ref-databricks-m2m-oauth] authentication                      | A valid client secret |     ❌    |
| [`CUBEJS_DB_DATABRICKS_TOKEN`](/reference/configuration/environment-variables#cubejs_db_databricks_token)                             | The [personal access token][databricks-docs-pat] used to authenticate the Databricks connection               | A valid token         |     ❌    |
| [`CUBEJS_DB_DATABRICKS_CATALOG`](/reference/configuration/environment-variables#cubejs_db_databricks_catalog)                         | The name of the [Databricks catalog][databricks-catalog] to connect to                                        | A valid catalog name  |     ❌    |
| [`CUBEJS_DB_EXPORT_BUCKET_MOUNT_DIR`](/reference/configuration/environment-variables#cubejs_db_export_bucket_mount_dir)               | The path for the [Databricks DBFS mount][databricks-docs-dbfs] (Not needed if using Unity Catalog connection) | A valid mount path    |     ❌    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool)                                             | The maximum number of concurrent database connections to pool. Default is `8`                                 | A valid number        |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)                                             | The number of [concurrent queries][ref-data-source-concurrency] to the data source                            | A valid number        |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
be used in pre-aggregations when using Databricks as a source database. To learn
more about Databricks's support for approximate aggregate functions, [click
here][databricks-docs-approx-agg-fns].

## Pre-Aggregation Build Strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Simple        |              ✅             |      ✅      |
| Export Bucket |              ✅             |      ❌      |

By default, Databricks JDBC uses a [simple][self-preaggs-simple] strategy to
build pre-aggregations.

### Simple

No extra configuration is required to configure simple pre-aggregation builds
for Databricks.

### Export Bucket

Databricks supports using both [AWS S3][aws-s3] and [Azure Blob
Storage][azure-bs] for export bucket functionality.

#### AWS S3

To use AWS S3 as an export bucket, first complete [the Databricks guide on
connecting to cloud object storage using Unity Catalog][databricks-docs-uc-s3].

<Info>
  Ensure the AWS credentials are correctly configured in IAM to allow reads and
  writes to the export bucket in S3.
</Info>

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET_TYPE=s3
CUBEJS_DB_EXPORT_BUCKET=s3://my.bucket.on.s3
CUBEJS_DB_EXPORT_BUCKET_AWS_KEY=<AWS_KEY>
CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET=<AWS_SECRET>
CUBEJS_DB_EXPORT_BUCKET_AWS_REGION=<AWS_REGION>
```

#### Google Cloud Storage

<Info>
  When using an export bucket, remember to assign the **Storage Object Admin**
  role to your Google Cloud credentials ([`CUBEJS_DB_EXPORT_GCS_CREDENTIALS`](/reference/configuration/environment-variables#cubejs_db_export_gcs_credentials)).
</Info>

To use Google Cloud Storage as an export bucket, first complete [the Databricks guide on
connecting to cloud object storage using Unity Catalog][databricks-docs-uc-gcs].

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET=gs://databricks-export-bucket
CUBEJS_DB_EXPORT_BUCKET_TYPE=gcs
CUBEJS_DB_EXPORT_GCS_CREDENTIALS=<BASE64_ENCODED_SERVICE_CREDENTIALS_JSON>
```

#### Azure Blob Storage

To use Azure Blob Storage as an export bucket, follow [the Databricks guide on
connecting to Azure Data Lake Storage Gen2 and Blob Storage][databricks-docs-azure].

[Retrieve the storage account access key][azure-bs-docs-get-key] from your Azure
account and use as follows:

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET_TYPE=azure
CUBEJS_DB_EXPORT_BUCKET=wasbs://my-container@my-storage-account.blob.core.windows.net
CUBEJS_DB_EXPORT_BUCKET_AZURE_KEY=<AZURE_STORAGE_ACCOUNT_ACCESS_KEY>
```

Access key provides full access to the configuration and data,
to use a fine-grained control over access to storage resources, follow [the Databricks guide on authorize with Azure Active Directory][authorize-with-azure-active-directory].

[Create the service principal][azure-authentication-with-service-principal] and replace the access key as follows:

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET_AZURE_TENANT_ID=<AZURE_TENANT_ID>
CUBEJS_DB_EXPORT_BUCKET_AZURE_CLIENT_ID=<AZURE_CLIENT_ID>
CUBEJS_DB_EXPORT_BUCKET_AZURE_CLIENT_SECRET=<AZURE_CLIENT_SECRET>
```

## SSL/TLS

Cube does not require any additional configuration to enable SSL/TLS for
Databricks JDBC connections.

## Additional Configuration

### Cube Cloud

To accurately show partition sizes in the Cube Cloud APM, [an export
bucket][self-preaggs-export-bucket] **must be** configured.

[aws-s3]: https://aws.amazon.com/s3/

[azure-bs]: https://azure.microsoft.com/en-gb/services/storage/blobs/

[azure-bs-docs-get-key]: https://docs.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&tabs=azure-portal#view-account-access-keys

[authorize-with-azure-active-directory]: https://learn.microsoft.com/en-us/rest/api/storageservices/authorize-with-azure-active-directory

[azure-authentication-with-service-principal]: https://learn.microsoft.com/en-us/azure/developer/java/sdk/identity-service-principal-auth

[databricks]: https://databricks.com/

[databricks-docs-dbfs]: https://docs.databricks.com/en/dbfs/mounts.html

[databricks-docs-azure]: https://docs.databricks.com/data/data-sources/azure/azure-storage.html

[databricks-docs-uc-s3]: https://docs.databricks.com/en/connect/unity-catalog/index.html

[databricks-docs-uc-gcs]: https://docs.databricks.com/gcp/en/connect/unity-catalog/cloud-storage.html

[databricks-docs-jdbc-url]: https://docs.databricks.com/integrations/bi/jdbc-odbc-bi.html#get-server-hostname-port-http-path-and-jdbc-url

[databricks-docs-pat]: https://docs.databricks.com/dev-tools/api/latest/authentication.html#token-management

[databricks-catalog]: https://docs.databricks.com/en/data-governance/unity-catalog/create-catalogs.html

[gh-cubejs-jdbc-install]: https://github.com/cube-js/cube/blob/master/packages/cubejs-jdbc-driver/README.md#java-installation

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[databricks-docs-approx-agg-fns]: https://docs.databricks.com/en/sql/language-manual/functions/approx_count_distinct.html

[self-preaggs-simple]: #simple

[self-preaggs-export-bucket]: #export-bucket

[ref-databricks-m2m-oauth]: https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m


# Druid
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/druid

The driver for Druid is community-supported and is not maintained by Cube or the database vendor.

<Warning>
  The driver for Druid is community-supported and is not maintained by Cube or the database vendor.
</Warning>

## Prerequisites

* The URL for the [Druid][druid] database
* The username/password for the [Druid][druid] database server

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=druid
CUBEJS_DB_URL=https://my.druid.host:8082
CUBEJS_DB_USER=druid
CUBEJS_DB_PASS=**********
```

## Environment Variables

| Environment Variable                                                                      | Description                                                                        | Possible Values                | Required |
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------ | :------: |
| [`CUBEJS_DB_URL`](/reference/configuration/environment-variables#cubejs_db_url)           | The URL for a database                                                             | A valid database URL for Druid |     ✅    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)         | The username used to connect to the database                                       | A valid database username      |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)         | The password used to connect to the database                                       | A valid database password      |     ✅    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool) | The maximum number of concurrent database connections to pool. Default is `8`      | A valid number                 |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency) | The number of [concurrent queries][ref-data-source-concurrency] to the data source | A valid number                 |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## SSL

Cube does not require any additional configuration to enable SSL as Druid
connections are made over HTTPS.

[druid]: https://druid.apache.org/


# DuckDB
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/duckdb

Set up Cube with DuckDB for cloud object storage, local database files, or MotherDuck-backed hybrid query execution.

[DuckDB][duckdb] is an in-process SQL OLAP database management system, and has
support for querying data in CSV, JSON and Parquet formats from an AWS
S3-compatible blob storage. This means you can [query data stored in AWS S3,
Google Cloud Storage, or Cloudflare R2][duckdb-docs-s3-import].
You can also use the [`CUBEJS_DB_DUCKDB_DATABASE_PATH`](/reference/configuration/environment-variables#cubejs_db_duckdb_database_path) environment variable to
connect to a local DuckDB database.

<Frame>
  <img />
</Frame>

Cube can also connect to [MotherDuck][motherduck], a cloud-based serverless
analytics platform built on DuckDB. When connected to MotherDuck, DuckDB uses
[hybrid execution][motherduck-docs-architecture] and routes queries to S3
through MotherDuck for better performance.

<Frame>
  <img />
</Frame>

## Prerequisites

* A set of IAM credentials which allow access to the S3-compatible data source.
  Credentials are only required for private S3 buckets.
* The region of the bucket
* The name of a bucket to query data from

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=duckdb
```

### Cube Cloud

In Cube Cloud, select **DuckDB** when creating a new deployment
and fill in the required fields:

<Frame>
  <img alt="Cube Cloud DuckDB Configuration Screen" />
</Frame>

<Info>
  If you are not using MotherDuck, leave the **MotherDuck Token**
  field blank.
</Info>

<Info>
  You can also explore how DuckDB works with Cube if you create a [demo
  deployment][ref-demo-deployment] in Cube Cloud.
</Info>

## Environment Variables

| Environment Variable                                                                                                            | Description                                                                                                           | Possible Values                                               | Required |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | :------: |
| [`CUBEJS_DB_DUCKDB_MEMORY_LIMIT`](/reference/configuration/environment-variables#cubejs_db_duckdb_memory_limit)                 | The maximum memory limit for DuckDB. Equivalent to `SET memory_limit=<MEMORY_LIMIT>`. Default is 75% of available RAM | A valid memory limit                                          |     ❌    |
| [`CUBEJS_DB_DUCKDB_SCHEMA`](/reference/configuration/environment-variables#cubejs_db_duckdb_schema)                             | The [default search schema][link-duckdb-configuration-ref]                                                            | A valid schema name                                           |     ❌    |
| [`CUBEJS_DB_DUCKDB_MOTHERDUCK_TOKEN`](/reference/configuration/environment-variables#cubejs_db_duckdb_motherduck_token)         | The service token to use for connections to MotherDuck                                                                | A valid [MotherDuck service token][motherduck-docs-svc-token] |     ❌    |
| [`CUBEJS_DB_DUCKDB_DATABASE_PATH`](/reference/configuration/environment-variables#cubejs_db_duckdb_database_path)               | The database filepath to use for connection to a local database.                                                      | A valid duckdb database file path                             |     ❌    |
| `CUBEJS_DB_DUCKDB_S3_ACCESS_KEY_ID`                                                                                             | The Access Key ID to use for database connections                                                                     | A valid Access Key ID                                         |     ❌    |
| `CUBEJS_DB_DUCKDB_S3_SECRET_ACCESS_KEY`                                                                                         | The Secret Access Key to use for database connections                                                                 | A valid Secret Access Key                                     |     ❌    |
| `CUBEJS_DB_DUCKDB_S3_ENDPOINT`                                                                                                  | The S3 endpoint                                                                                                       | A valid [S3 endpoint][duckdb-docs-s3-import]                  |     ❌    |
| `CUBEJS_DB_DUCKDB_S3_REGION`                                                                                                    | The [region of the bucket][duckdb-docs-s3-import]                                                                     | A valid AWS region                                            |     ❌    |
| `CUBEJS_DB_DUCKDB_S3_USE_SSL`                                                                                                   | Use SSL for connection                                                                                                | A boolean                                                     |     ❌    |
| `CUBEJS_DB_DUCKDB_S3_URL_STYLE`                                                                                                 | To choose the S3 URL style(vhost or path)                                                                             | `vhost` or `path`                                             |     ❌    |
| `CUBEJS_DB_DUCKDB_S3_SESSION_TOKEN`                                                                                             | The token for the S3 session                                                                                          | A valid Session Token                                         |     ❌    |
| [`CUBEJS_DB_DUCKDB_EXTENSIONS`](/reference/configuration/environment-variables#cubejs_db_duckdb_extensions)                     | A comma-separated list of DuckDB extensions to install and load                                                       | A comma-separated list of DuckDB extensions                   |     ❌    |
| [`CUBEJS_DB_DUCKDB_COMMUNITY_EXTENSIONS`](/reference/configuration/environment-variables#cubejs_db_duckdb_community_extensions) | A comma-separated list of DuckDB community extensions to install and load                                             | A comma-separated list of DuckDB community extensions         |     ❌    |
| `CUBEJS_DB_DUCKDB_S3_USE_CREDENTIAL_CHAIN`                                                                                      | A flag to use credentials chain for secrets for S3 connections                                                        | `true`, `false`. Defaults to `false`                          |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)                                       | The number of [concurrent queries][ref-data-source-concurrency] to the data source                                    | A valid number                                                |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
be used in pre-aggregations when using DuckDB as a source database. To learn
more about DuckDB's support for approximate aggregate functions, [click
here][duckdb-docs-approx-agg-fns].

## Pre-Aggregation Build Strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Batching      |              ❌             |      ✅      |
| Export Bucket |              -             |      -      |

By default, DuckDB uses a [batching][self-preaggs-batching] strategy to build
pre-aggregations.

### Batching

No extra configuration is required to configure batching for DuckDB.

### Export Bucket

DuckDB does not support export buckets.

## SSL

Cube does not require any additional configuration to enable SSL as DuckDB
connections are made over HTTPS.

[duckdb]: https://duckdb.org/

[duckdb-docs-approx-agg-fns]: https://duckdb.org/docs/sql/aggregates.html#approximate-aggregates

[duckdb-docs-s3-import]: https://duckdb.org/docs/guides/import/s3_import

[link-duckdb-configuration-ref]: https://duckdb.org/docs/sql/configuration.html#configuration-reference

[motherduck]: https://motherduck.com/

[motherduck-docs-architecture]: https://motherduck.com/docs/architecture-and-capabilities#hybrid-execution

[motherduck-docs-svc-token]: https://motherduck.com/docs/authenticating-to-motherduck/#authentication-using-a-service-token

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[self-preaggs-batching]: #batching

[ref-demo-deployment]: /admin/deployment#demo-deployments


# Firebolt
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/firebolt

The driver for Firebolt is supported by its vendor. Please report any issues to their Help Center.

<Warning>
  The driver for Firebolt is supported by its vendor. Please report any issues to
  their [Help Center][firebolt-help].
</Warning>

## Prerequisites

* The id/secret (client id/client secret) for your [Firebolt][firebolt] [service account][firebolt-service-accounts]

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_NAME=firebolt_database
CUBEJS_DB_USER=aaaa-bbb-3244-wwssd
CUBEJS_DB_PASS=**********
CUBEJS_FIREBOLT_ACCOUNT=cube
CUBEJS_FIREBOLT_ENGINE_NAME=engine_name
```

## Environment Variables

| Environment Variable                                                                                          | Description                                                                        | Possible Values                                                         | Required |
| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | :------: |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)                             | The name of the database to connect to                                             | A valid database name                                                   |     ✅    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)                             | A service account ID for accessing Firebolt programmatically                       | A valid service id                                                      |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)                             | A service account secret for accessing Firebolt programmatically                   | A valid service secret                                                  |     ✅    |
| [`CUBEJS_FIREBOLT_ACCOUNT`](/reference/configuration/environment-variables#cubejs_firebolt_account)           | Account name                                                                       | An account name                                                         |     ✅    |
| [`CUBEJS_FIREBOLT_ENGINE_NAME`](/reference/configuration/environment-variables#cubejs_firebolt_engine_name)   | Engine name to connect to                                                          | A valid engine name                                                     |     ✅    |
| [`CUBEJS_FIREBOLT_API_ENDPOINT`](/reference/configuration/environment-variables#cubejs_firebolt_api_endpoint) | Firebolt API endpoint. Used for authentication                                     | `api.dev.firebolt.io`, `api.staging.firebolt.io`, `api.app.firebolt.io` |     -    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool)                     | The maximum number of concurrent database connections to pool. Default is `20`     | A valid number                                                          |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)                     | The number of [concurrent queries][ref-data-source-concurrency] to the data source | A valid number                                                          |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

[firebolt]: https://www.firebolt.io/

[firebolt-help]: https://help.firebolt.io/

[firebolt-service-accounts]: https://docs.firebolt.io/godocs/Guides/managing-your-organization/service-accounts.html


# Google BigQuery
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/google-bigquery

Grant a Google Cloud service account the right BigQuery IAM roles, then point Cube at your project, region, and key material.

## Prerequisites

<Info>
  In order to connect Google BigQuery to Cube, you need to provide service account
  credentials. Cube requires the service account to have **BigQuery Data Viewer**
  and **BigQuery Job User** roles enabled. If you plan to use pre-aggregations,
  the account will need the **BigQuery Data Editor** role instead of **BigQuery Data Viewer**.
  You can learn more about acquiring
  Google BigQuery credentials [here][bq-docs-getting-started].
  In Cube Cloud, you can authenticate with [OIDC workload identity
  federation][ref-oidc-gcp-bigquery] instead of a key file — the same roles
  apply to the impersonated service account.
</Info>

* The [Google Cloud Project ID][google-cloud-docs-projects] for the
  [BigQuery][bq] project
* A set of [Google Cloud service credentials][google-support-create-svc-account]
  which [allow access][bq-docs-getting-started] to the [BigQuery][bq] project
* The [Google Cloud region][bq-docs-regional-locations] for the [BigQuery][bq]
  project

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=bigquery
CUBEJS_DB_BQ_PROJECT_ID=my-bigquery-project-12345
CUBEJS_DB_BQ_KEY_FILE=/path/to/my/keyfile.json
```

You could also encode the key file using Base64 and set the result to
[`CUBEJS_DB_BQ_CREDENTIALS`](/reference/configuration/environment-variables#cubejs_db_bq_credentials):

```dotenv theme={"dark"}
CUBEJS_DB_BQ_CREDENTIALS=$(cat /path/to/my/keyfile.json | base64)
```

### Cube Cloud

<Info>
  In some cases you'll need to allow connections from your Cube Cloud deployment
  IP address to your database. You can copy the IP address from either the
  Database Setup step in deployment creation, or from **Settings →
  Configuration** in your deployment.
</Info>

The following fields are required when creating a BigQuery connection:

<Frame>
  <img alt="Cube Cloud BigQuery Configuration Screen" />
</Frame>

#### OIDC workload identity federation

Instead of a service account key file, Cube Cloud deployments can
authenticate to BigQuery with [OIDC workload identity
federation][ref-oidc-gcp-bigquery]: a Workload Identity Federation provider
in your GCP project trusts Cube's OIDC issuer, and the driver authenticates
through the GCP default credential chain — no JSON key to provision or
rotate. Select **OIDC workload identity federation** in the connection
wizard, or set the equivalent environment variables:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=bigquery
CUBEJS_DB_BQ_PROJECT_ID=my-bigquery-project-12345
GCP_POOL_AUDIENCE=//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/cube-pool/providers/cube
GCP_SERVICE_ACCOUNT_EMAIL=cube-deployment@my-bigquery-project-12345.iam.gserviceaccount.com
```

`GCP_SERVICE_ACCOUNT_EMAIL` selects the service account Cube impersonates;
leave it unset to authenticate as the federated principal directly. See the
[GCP OIDC guide][ref-oidc-gcp-bigquery] for the Workload Identity Pool,
provider, and IAM setup.

Cube Cloud also supports connecting to data sources within private VPCs
if [single-tenant infrastructure][ref-dedicated-infra] is used. Check out the
[VPC connectivity guide][ref-cloud-conf-vpc] for details.

[ref-dedicated-infra]: /admin/deployment/infrastructure#dedicated-infrastructure

[ref-cloud-conf-vpc]: /admin/deployment/dedicated

## Environment Variables

| Environment Variable                                                                                          | Description                                                                                                                                                                                     | Possible Values                                                         |    Required   |
| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | :-----------: |
| [`CUBEJS_DB_BQ_PROJECT_ID`](/reference/configuration/environment-variables#cubejs_db_bq_project_id)           | The Google BigQuery project ID to connect to                                                                                                                                                    | A valid Google BigQuery Project ID                                      |       ✅       |
| [`CUBEJS_DB_BQ_KEY_FILE`](/reference/configuration/environment-variables#cubejs_db_bq_key_file)               | The path to a JSON key file for connecting to Google BigQuery                                                                                                                                   | A valid Google BigQuery JSON key file                                   | ✅<sup>1</sup> |
| [`CUBEJS_DB_BQ_CREDENTIALS`](/reference/configuration/environment-variables#cubejs_db_bq_credentials)         | A Base64 encoded JSON key file for connecting to Google BigQuery                                                                                                                                | A valid Google BigQuery JSON key file encoded as a Base64 string        |       ❌       |
| [`CUBEJS_DB_BQ_LOCATION`](/reference/configuration/environment-variables#cubejs_db_bq_location)               | The Google BigQuery dataset location to connect to. Required if used with pre-aggregations outside of US. If not set then BQ driver will fail with `Dataset was not found in location US` error | [A valid Google BigQuery regional location][bq-docs-regional-locations] |       ⚠️      |
| [`CUBEJS_DB_EXPORT_BUCKET`](/reference/configuration/environment-variables#cubejs_db_export_bucket)           | The name of a bucket in cloud storage                                                                                                                                                           | A valid bucket name from cloud storage                                  |       ❌       |
| [`CUBEJS_DB_EXPORT_BUCKET_TYPE`](/reference/configuration/environment-variables#cubejs_db_export_bucket_type) | The cloud provider where the bucket is hosted                                                                                                                                                   | `gcp`                                                                   |       ❌       |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool)                     | The maximum number of concurrent database connections to pool. Default is `40`                                                                                                                  | A valid number                                                          |       ❌       |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)                     | The number of [concurrent queries][ref-data-source-concurrency] to the data source                                                                                                              | A valid number                                                          |       ❌       |

<sup>1</sup> Not required when authenticating with [OIDC workload identity
federation][ref-oidc-gcp-bigquery] in Cube Cloud, or when providing the key
material via [`CUBEJS_DB_BQ_CREDENTIALS`](/reference/configuration/environment-variables#cubejs_db_bq_credentials).

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
be used in pre-aggregations when using Google BigQuery as a source database. To
learn more about Google BigQuery's support for approximate aggregate functions,
[click here][bq-docs-approx-agg-fns].

## Pre-Aggregation Build Strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Batching      |              ❌             |      ✅      |
| Export Bucket |              ❌             |      ❌      |

By default, Google BigQuery uses [batching][self-preaggs-batching] to build
pre-aggregations.

### Batching

No extra configuration is required to configure batching for Google BigQuery.

### Export bucket

<Warning>
  BigQuery only supports using Google Cloud Storage for export buckets.
</Warning>

#### Google Cloud Storage

For [improved pre-aggregation performance with large
datasets][ref-caching-large-preaggs], enable export bucket functionality by
configuring Cube with the following environment variables:

<Info>
  When using an export bucket, remember to assign the **BigQuery Data Editor** and
  **Storage Object Admin** role to your BigQuery service account.
</Info>

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET=export_data_58148478376
CUBEJS_DB_EXPORT_BUCKET_TYPE=gcp
```

## SSL

Cube does not require any additional configuration to enable SSL as Google
BigQuery connections are made over HTTPS.

[bq]: https://cloud.google.com/bigquery

[bq-docs-getting-started]: https://cloud.google.com/docs/authentication/getting-started

[bq-docs-regional-locations]: https://cloud.google.com/bigquery/docs/locations#regional-locations

[bq-docs-approx-agg-fns]: https://cloud.google.com/bigquery/docs/reference/standard-sql/approximate_aggregate_functions

[google-cloud-docs-projects]: https://cloud.google.com/resource-manager/docs/creating-managing-projects#before_you_begin

[google-support-create-svc-account]: https://support.google.com/a/answer/7378726?hl=en

[ref-caching-large-preaggs]: /docs/pre-aggregations/using-pre-aggregations#export-bucket

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[ref-oidc-gcp-bigquery]: /admin/deployment/oidc/gcp#bigquery

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[self-preaggs-batching]: #batching


# Hive / SparkSQL
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/hive

The driver for Hive / SparkSQL is deprecated and community-supported, and is not maintained by Cube or the database vendor.

<Warning>
  The driver for Hive / SparkSQL is deprecated and will be removed in a future
  release. It is community-supported and is not maintained by Cube or the database
  vendor.
</Warning>

## Prerequisites

* The hostname for the [Hive][hive] database server
* The username/password for the [Hive][hive] database server

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=hive
CUBEJS_DB_HOST=my.hive.host
CUBEJS_DB_NAME=my_hive_database
CUBEJS_DB_USER=hive_user
CUBEJS_DB_PASS=**********
```

## Environment Variables

| Environment Variable                                                                                    | Description                                                                        | Possible Values           | Required |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------- | :------: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host)                       | The host URL for a database                                                        | A valid database host URL |     ✅    |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port)                       | The port for the database connection                                               | A valid port number       |     ❌    |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)                       | The name of the database to connect to                                             | A valid database name     |     ✅    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)                       | The username used to connect to the database                                       | A valid database username |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)                       | The password used to connect to the database                                       | A valid database password |     ✅    |
| [`CUBEJS_DB_HIVE_TYPE`](/reference/configuration/environment-variables#cubejs_db_hive_type)             |                                                                                    |                           |     ❌    |
| [`CUBEJS_DB_HIVE_VER`](/reference/configuration/environment-variables#cubejs_db_hive_ver)               |                                                                                    |                           |     ❌    |
| [`CUBEJS_DB_HIVE_THRIFT_VER`](/reference/configuration/environment-variables#cubejs_db_hive_thrift_ver) |                                                                                    |                           |     ❌    |
| [`CUBEJS_DB_HIVE_CDH_VER`](/reference/configuration/environment-variables#cubejs_db_hive_cdh_ver)       |                                                                                    |                           |     ❌    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool)               | The maximum number of concurrent database connections to pool. Default is `8`      | A valid number            |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)               | The number of [concurrent queries][ref-data-source-concurrency] to the data source | A valid number            |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

[hive]: https://hive.apache.org/


# Data Sources
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/index

Choose and configure a data warehouse, query engine, or other data source to connect to Cube.

Cube connects directly to your data warehouse or database. Select your data
source below to get started with the setup process.

You can also connect [multiple data sources][ref-config-multi-data-src] at the same
time and adjust the [concurrency settings][ref-data-source-concurrency] for data
sources.

## Data warehouses

<CardGroup>
  <Card title="Amazon Redshift" icon="brand-aws" href="/admin/connect-to-data/data-sources/aws-redshift">
    Connect to Amazon Redshift.
  </Card>

  <Card title="Google BigQuery" icon="brand-google-big-query" href="/admin/connect-to-data/data-sources/google-bigquery">
    Connect to Google BigQuery.
  </Card>

  <Card title="Snowflake" icon="brand-snowflake" href="/admin/connect-to-data/data-sources/snowflake">
    Connect to Snowflake.
  </Card>

  <Card title="Databricks" icon="brand-databricks" href="/admin/connect-to-data/data-sources/databricks-jdbc">
    Connect to Databricks.
  </Card>

  <Card title="Microsoft Fabric" icon="brand-windows" href="/admin/connect-to-data/data-sources/ms-fabric">
    Connect to Microsoft Fabric.
  </Card>

  <Card title="ClickHouse" icon="database" href="/admin/connect-to-data/data-sources/clickhouse">
    Connect to ClickHouse.
  </Card>

  <Card title="SingleStore" icon="database" href="/admin/connect-to-data/data-sources/singlestore">
    Connect to SingleStore.
  </Card>

  <Card title="Apache Pinot" icon="database" href="/admin/connect-to-data/data-sources/pinot">
    Connect to Apache Pinot.
  </Card>

  <Card title="Firebolt" icon="flame" href="/admin/connect-to-data/data-sources/firebolt">
    Connect to Firebolt.
  </Card>

  <Card title="Vertica" icon="database" href="/admin/connect-to-data/data-sources/vertica">
    Connect to Vertica.
  </Card>
</CardGroup>

## Query engines

<CardGroup>
  <Card title="Amazon Athena" icon="brand-aws" href="/admin/connect-to-data/data-sources/aws-athena">
    Connect to Amazon Athena.
  </Card>

  <Card title="DuckDB / MotherDuck" icon="database" href="/admin/connect-to-data/data-sources/duckdb">
    Connect to DuckDB or MotherDuck.
  </Card>

  <Card title="Hive / SparkSQL" icon="database" href="/admin/connect-to-data/data-sources/hive">
    Connect to Hive or SparkSQL.
  </Card>

  <Card title="Presto" icon="database" href="/admin/connect-to-data/data-sources/presto">
    Connect to Presto.
  </Card>

  <Card title="Trino" icon="database" href="/admin/connect-to-data/data-sources/trino">
    Connect to Trino.
  </Card>
</CardGroup>

## Transactional databases

<CardGroup>
  <Card title="Postgres" icon="database" href="/admin/connect-to-data/data-sources/postgres">
    Connect to Postgres.
  </Card>

  <Card title="Microsoft SQL Server" icon="brand-windows" href="/admin/connect-to-data/data-sources/ms-sql">
    Connect to Microsoft SQL Server.
  </Card>

  <Card title="MySQL" icon="brand-mysql" href="/admin/connect-to-data/data-sources/mysql">
    Connect to MySQL.
  </Card>

  <Card title="Oracle" icon="oval-vertical" href="/admin/connect-to-data/data-sources/oracle">
    Connect to Oracle.
  </Card>

  <Card title="SQLite" icon="database" href="/admin/connect-to-data/data-sources/sqlite">
    Connect to SQLite.
  </Card>
</CardGroup>

## Time series & streaming

<CardGroup>
  <Card title="QuestDB" icon="clock-hour-4" href="/admin/connect-to-data/data-sources/questdb">
    Connect to QuestDB.
  </Card>

  <Card title="ksqlDB" icon="ripple" href="/admin/connect-to-data/data-sources/ksqldb">
    Connect to ksqlDB.
  </Card>

  <Card title="Materialize" icon="ripple" href="/admin/connect-to-data/data-sources/materialize">
    Connect to Materialize.
  </Card>

  <Card title="RisingWave" icon="ripple" href="/admin/connect-to-data/data-sources/risingwave">
    Connect to RisingWave.
  </Card>
</CardGroup>

## Other data sources

<CardGroup>
  <Card title="MongoDB" icon="leaf" href="/admin/connect-to-data/data-sources/mongodb">
    Connect to MongoDB.
  </Card>

  <Card title="Druid" icon="database" href="/admin/connect-to-data/data-sources/druid">
    Connect to Apache Druid.
  </Card>

  <Card title="Parquet" icon="file" href="/admin/connect-to-data/data-sources/duckdb">
    Query Parquet files via DuckDB.
  </Card>

  <Card title="CSV" icon="file-type-csv" href="/admin/connect-to-data/data-sources/duckdb">
    Query CSV files via DuckDB.
  </Card>

  <Card title="JSON" icon="braces" href="/admin/connect-to-data/data-sources/duckdb">
    Query JSON files via DuckDB.
  </Card>
</CardGroup>

### API endpoints

Cube is designed to work with data sources that allow querying them with SQL.

Cube is not designed to access data files directly or fetch data from REST,
or GraphQL, or any other API. To use Cube in that way, you either need to use
a supported data source (e.g., use [DuckDB][ref-duckdb] to query Parquet files
on Amazon S3) or create a [custom data source driver](#currently-unsupported-data-sources).

## Data source drivers

### Driver support

Most of the drivers for data sources are supported either directly by the Cube
team or by their vendors. The rest are community-supported and will be
highlighted as such in their respective pages.

You can find the [source code][link-github-packages] of the drivers that are part
of the Cube distribution in `cubejs-*-driver` folders on GitHub.

### Third-party drivers

The following drivers were contributed by the Cube community. They are not part
of the Cube distribution, however, they can still be used with Cube:

* [ArangoDB](https://www.npmjs.com/package/arangodb-cubejs-driver)
* [CosmosDB](https://www.npmjs.com/package/cosmosdb-cubejs-driver)
* [CrateDB](https://www.npmjs.com/package/cratedb-cubejs-driver)
* [Dremio](https://www.npmjs.com/package/mydremio-cubejs-driver)
* [Dremio ODBC](https://www.npmjs.com/package/dremio-odbc-cubejs-driver)
* [OpenDistro Elastic](https://www.npmjs.com/package/opendistro-cubejs-driver)
* [SAP Hana](https://www.npmjs.com/package/cubejs-hana-driver)
* [Trino](https://www.npmjs.com/package/trino-cubejs-driver)
* [Vertica](https://www.npmjs.com/package/@knowitall/vertica-driver)

You need to configure [`driver_factory`][ref-driver-factory] to use a third-party
driver.

### Currently unsupported data sources

If you'd like to connect to a data source which is not yet listed on this page,
please see the list of [requested drivers](https://github.com/cube-js/cube/issues/7076)
and [file an issue](https://github.com/cube-js/cube/issues) on GitHub.

You're more than welcome to contribute new drivers as well as new features and
patches to
[existing drivers](https://github.com/cube-js/cube/tree/master/packages). Please
check the
[contribution guidelines](https://github.com/cube-js/cube/blob/master/CONTRIBUTING.md#contributing-database-drivers)
and join the `#contributing-to-cube` channel in our
[Slack community](https://slack.cube.dev).

[ref-config-multi-data-src]: /admin/connect-to-data/multiple-data-sources

[ref-driver-factory]: /reference/configuration/config#driver_factory

[ref-duckdb]: /admin/connect-to-data/data-sources/duckdb

[link-github-packages]: https://github.com/cube-js/cube/tree/master/packages

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-sources


# ksqlDB
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/ksqldb

ksqlDB is a purpose-built database for stream processing applications, ingesting data from Apache Kafka.

[ksqlDB](https://ksqldb.io) is a purpose-built database for stream processing
applications, ingesting data from [Apache Kafka](https://kafka.apache.org).

<Note>
  Available on the [Enterprise plan](https://cube.dev/pricing).
  [Contact us](https://cube.dev/contact) for details.
</Note>

See how you can use ksqlDB and Cube Cloud to power real-time analytics in Power BI:

<iframe title="YouTube video" />

<Info>
  In this video, the SQL API is used to connect to Power BI.
  Currently, it's recommended to use the DAX API.
</Info>

## Prerequisites

* Hostname for the ksqlDB server
* Username and password (or an API key) to connect to ksqlDB server

### Confluent Cloud

If you are using [Confluent Cloud](https://www.confluent.io/confluent-cloud/),
you need to generate an API key and use the API key name as your username and
the API key secret as your password.

You can generate an API key by installing `confluent-cli` and running the
following commands in the command line:

```sh theme={"dark"}
brew install --cask confluent-cli
confluent login
confluent environment use <YOUR-ENVIRONMENT-ID>
confluent ksql cluster list
confluent api-key create --resource <YOUR-KSQL-CLUSTER-ID>
```

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=ksql
CUBEJS_DB_URL=https://xxxxxx-xxxxx.us-west4.gcp.confluent.cloud:443
CUBEJS_DB_USER=username
CUBEJS_DB_PASS=password
```

## Environment Variables

| Environment Variable                                                                                | Description                                                                                                  | Possible Values           | Required |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------- | :------: |
| [`CUBEJS_DB_URL`](/reference/configuration/environment-variables#cubejs_db_url)                     | The host URL for ksqlDB with port                                                                            | A valid database host URL |     ✅    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)                   | The username used to connect to the ksqlDB. API key for Confluent Cloud.                                     | A valid database username |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)                   | The password used to connect to the ksqlDB. API secret for Confluent Cloud.                                  | A valid database password |     ✅    |
| [`CUBEJS_DB_KAFKA_HOST`](/reference/configuration/environment-variables#cubejs_db_kafka_host)       | Kafka broker host(s) for [Kafka streams mode](#kafka-streams-mode). Multiple brokers can be comma-separated. | A valid Kafka broker URL  |     ❌    |
| [`CUBEJS_DB_KAFKA_USER`](/reference/configuration/environment-variables#cubejs_db_kafka_user)       | Username for Kafka broker authentication (SASL PLAIN)                                                        | A valid Kafka username    |     ❌    |
| [`CUBEJS_DB_KAFKA_PASS`](/reference/configuration/environment-variables#cubejs_db_kafka_pass)       | Password for Kafka broker authentication (SASL PLAIN)                                                        | A valid Kafka password    |     ❌    |
| [`CUBEJS_DB_KAFKA_USE_SSL`](/reference/configuration/environment-variables#cubejs_db_kafka_use_ssl) | If `true`, enables SASL\_SSL for the Kafka connection                                                        | `true`, `false`           |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)           | The number of [concurrent queries][ref-data-source-concurrency] to the data source                           | A valid number            |     ❌    |

## Pre-Aggregations Support

ksqlDB supports only
[streaming pre-aggregations][ref-streaming-pre-aggs].

## Kafka streams mode

By default, Cube connects to ksqlDB via its REST API. ksqlDB uses its REST
API both for metadata (discovering tables and streams) and for streaming
data into Cube Store during pre-aggregation builds.

In this default mode, Cube may create tables and streams in ksqlDB as part
of the pre-aggregation build process (e.g., `CREATE TABLE ... AS SELECT`
statements for non-read-only pre-aggregations).

When **Kafka streams mode** is enabled, Cube reads data directly from the
underlying Kafka topics instead of going through the ksqlDB REST API for
data streaming. ksqlDB is still used for metadata operations such as
discovering tables, streams, and their schemas, but Cube Store subscribes
to the backing Kafka topic directly.

In this mode, Cube does not create any tables or streams in ksqlDB. All
pre-aggregations use the read-only refresh path: Cube discovers the
existing ksqlDB objects and their backing Kafka topics, then streams data
directly from Kafka into Cube Store.

### When to use Kafka streams mode

Kafka streams mode is useful when:

* You want to prevent Cube from creating any objects in ksqlDB
* You need higher throughput for data ingestion by reading Kafka directly
* Your ksqlDB environment has restricted permissions that don't allow
  creating tables or streams
* You prefer Cube Store to consume from Kafka topics without an
  intermediary

### Enabling Kafka streams mode

Set the `CUBEJS_DB_KAFKA_HOST` environment variable to the address of your
Kafka broker(s). This activates Kafka streams mode automatically:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=ksql
CUBEJS_DB_URL=https://xxxxxx-xxxxx.us-west4.gcp.confluent.cloud:443
CUBEJS_DB_USER=ksql_username
CUBEJS_DB_PASS=ksql_password
CUBEJS_DB_KAFKA_HOST=pkc-xxxxx.us-west4.gcp.confluent.cloud:9092
CUBEJS_DB_KAFKA_USER=kafka_api_key
CUBEJS_DB_KAFKA_PASS=kafka_api_secret
CUBEJS_DB_KAFKA_USE_SSL=true
```

Multiple Kafka brokers can be specified as a comma-separated list:

```dotenv theme={"dark"}
CUBEJS_DB_KAFKA_HOST=broker1:9092,broker2:9092,broker3:9092
```

<Info>
  When using [Confluent Cloud](https://www.confluent.io/confluent-cloud/),
  the Kafka credentials are separate from the ksqlDB credentials. Generate
  an API key for the Kafka cluster (not the ksqlDB cluster) and use it as
  `CUBEJS_DB_KAFKA_USER` and `CUBEJS_DB_KAFKA_PASS`.
</Info>

### How it works

With Kafka streams mode enabled:

1. Cube uses the ksqlDB REST API to discover available tables and streams
   and to retrieve their schemas via `DESCRIBE`.
2. For each table or stream, Cube resolves the backing Kafka topic name
   from the ksqlDB metadata.
3. Instead of streaming data through ksqlDB, Cube Store connects directly
   to the Kafka broker(s) and consumes from the resolved topic.
4. Pre-aggregation builds use the read-only refresh strategy. Cube does
   not issue any `CREATE TABLE` or `CREATE STREAM` statements to ksqlDB.

### Data modeling

ksqlDB is typically used as an additional data source alongside a primary
data warehouse. To use Kafka streams mode, configure ksqlDB as a named
data source using [decorated environment variables][ref-decorated-env-vars]
and point your cubes to it with the
[`data_source`][ref-cube-data-source] property.

First, declare the data sources and configure the ksqlDB connection with
Kafka credentials:

```dotenv theme={"dark"}
CUBEJS_DATASOURCES=default,ksql
CUBEJS_DB_TYPE=postgres
CUBEJS_DB_HOST=my.postgres.host
CUBEJS_DB_NAME=my_database
CUBEJS_DB_USER=postgres_user
CUBEJS_DB_PASS=postgres_password
CUBEJS_DS_KSQL_DB_TYPE=ksql
CUBEJS_DS_KSQL_DB_URL=https://xxxxxx-xxxxx.us-west4.gcp.confluent.cloud:443
CUBEJS_DS_KSQL_DB_USER=ksql_api_key
CUBEJS_DS_KSQL_DB_PASS=ksql_api_secret
CUBEJS_DS_KSQL_DB_KAFKA_HOST=pkc-xxxxx.us-west4.gcp.confluent.cloud:9092
CUBEJS_DS_KSQL_DB_KAFKA_USER=kafka_api_key
CUBEJS_DS_KSQL_DB_KAFKA_PASS=kafka_api_secret
CUBEJS_DS_KSQL_DB_KAFKA_USE_SSL=true
```

Then, create cubes that reference your data. A common pattern is to
combine a **batch cube** (reading historical data from your warehouse)
with a **streaming cube** (reading real-time data from ksqlDB via Kafka)
using a [lambda pre-aggregation][ref-lambda-pre-aggs].

The batch cube queries the warehouse and builds daily partitions
incrementally. The streaming cube points at an existing ksqlDB stream
with `data_source: ksql` and uses a read-only streaming pre-aggregation
that consumes from the backing Kafka topic directly. The lambda
pre-aggregation in the batch cube merges both, serving historical data
from the warehouse rollup and real-time data from the streaming rollup:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: order_events
      data_source: default
      sql: >
        SELECT
          order_id,
          user_id,
          status,
          amount,
          created_at
        FROM ecommerce.order_events
        WHERE {FILTER_PARAMS.order_events.created_at.filter(
          (from, to) =>
          `created_at >= ${from} AND created_at < ${to}`
        )}

      measures:
        - name: count
          type: count

        - name: total_amount
          sql: amount
          type: sum

        - name: failed_count
          sql: "CASE WHEN status = 'failed' THEN 1 ELSE 0 END"
          type: sum

      dimensions:
        - name: order_id
          sql: order_id
          type: string
          primary_key: true

        - name: user_id
          sql: user_id
          type: string

        - name: status
          sql: status
          type: string

        - name: created_at
          sql: created_at
          type: time

      pre_aggregations:
        - name: lambda
          type: rollup_lambda
          rollups:
            - order_events.batch
            - order_events_stream.stream

        - name: batch
          type: rollup
          measures:
            - CUBE.count
            - CUBE.total_amount
            - CUBE.failed_count
          dimensions:
            - CUBE.order_id
            - CUBE.user_id
            - CUBE.status
          time_dimension: CUBE.created_at
          granularity: second
          partition_granularity: day
          build_range_start:
            sql: SELECT NOW() - INTERVAL '90 days'
          build_range_end:
            sql: SELECT NOW()
          refresh_key:
            every: 8 hour
            update_window: 1 day
            incremental: true
          indexes:
            - name: user_status
              columns:
                - CUBE.user_id
                - CUBE.status

    - name: order_events_stream
      data_source: ksql
      sql: "SELECT * FROM ORDER_EVENTS_STREAM"

      measures:
        - name: count
          type: count

        - name: total_amount
          sql: AMOUNT
          type: sum

        - name: failed_count
          sql: "CASE WHEN STATUS = 'failed' THEN 1 ELSE 0 END"
          type: sum

      dimensions:
        - name: order_id
          sql: ORDER_ID
          type: string
          primary_key: true

        - name: user_id
          sql: USER_ID
          type: string

        - name: status
          sql: STATUS
          type: string

        - name: created_at
          sql: CREATED_AT
          type: time

      pre_aggregations:
        - name: stream
          type: rollup
          read_only: true
          measures:
            - CUBE.count
            - CUBE.total_amount
            - CUBE.failed_count
          dimensions:
            - CUBE.order_id
            - CUBE.user_id
            - CUBE.status
          unique_key_columns:
            - order_id
            - user_id
            - status
            - created_at_second
          time_dimension: CUBE.created_at
          granularity: second
          partition_granularity: day
          # ksqlDB does not support NOW(); use CURRENT_TIMESTAMP with INTERVAL arithmetic instead.
          build_range_start:
            sql: "SELECT date_trunc('day', CURRENT_TIMESTAMP - INTERVAL '5 hour')"
          build_range_end:
            sql: "SELECT CURRENT_TIMESTAMP + INTERVAL '15 minute'"
          refresh_key:
            every: 1 minute
            update_window: 1 hour
            incremental: true
          indexes:
            - name: user_status
              columns:
                - CUBE.user_id
                - CUBE.status
                - orders__created_at_second
          stream_offset: latest
          output_column_types:
            - member: CUBE.order_id
              type: text
            - member: CUBE.user_id
              type: text
            - member: CUBE.status
              type: text
            - member: CUBE.created_at.second
              type: timestamp
            - member: CUBE.count
              type: int
            - member: CUBE.total_amount
              type: decimal
            - member: CUBE.failed_count
              type: int
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("order_events", {
    data_source: "default",

    sql: `
      SELECT
        order_id,
        user_id,
        status,
        amount,
        created_at
      FROM ecommerce.order_events
      WHERE ${FILTER_PARAMS.order_events.created_at.filter(
        (from, to) => `created_at >= ${from} AND created_at < ${to}`
      )}
    `,

    measures: {
      count: {
        type: `count`,
      },

      total_amount: {
        sql: `amount`,
        type: `sum`,
      },

      failed_count: {
        sql: `CASE WHEN status = 'failed' THEN 1 ELSE 0 END`,
        type: `sum`,
      },
    },

    dimensions: {
      order_id: {
        sql: `order_id`,
        type: `string`,
        primary_key: true,
      },

      user_id: {
        sql: `user_id`,
        type: `string`,
      },

      status: {
        sql: `status`,
        type: `string`,
      },

      created_at: {
        sql: `created_at`,
        type: `time`,
      },
    },

    pre_aggregations: {
      lambda: {
        type: `rollup_lambda`,
        rollups: [
          order_events.batch,
          order_events_stream.stream,
        ],
      },

      batch: {
        type: `rollup`,
        measures: [CUBE.count, CUBE.total_amount, CUBE.failed_count],
        dimensions: [CUBE.order_id, CUBE.user_id, CUBE.status],
        time_dimension: CUBE.created_at,
        granularity: `second`,
        partition_granularity: `day`,
        build_range_start: {
          sql: `SELECT NOW() - INTERVAL '90 days'`,
        },
        build_range_end: {
          sql: `SELECT NOW()`,
        },
        refresh_key: {
          every: `8 hour`,
          update_window: `1 day`,
          incremental: true,
        },
        indexes: {
          user_status: {
            columns: [CUBE.user_id, CUBE.status],
          },
        },
      },
    },
  });

  cube("order_events_stream", {
    data_source: "ksql",

    sql: `SELECT * FROM ORDER_EVENTS_STREAM`,

    measures: {
      count: {
        type: `count`,
      },

      total_amount: {
        sql: `AMOUNT`,
        type: `sum`,
      },

      failed_count: {
        sql: `CASE WHEN STATUS = 'failed' THEN 1 ELSE 0 END`,
        type: `sum`,
      },
    },

    dimensions: {
      order_id: {
        sql: `ORDER_ID`,
        type: `string`,
        primary_key: true,
      },

      user_id: {
        sql: `USER_ID`,
        type: `string`,
      },

      status: {
        sql: `STATUS`,
        type: `string`,
      },

      created_at: {
        sql: `CREATED_AT`,
        type: `time`,
      },
    },

    pre_aggregations: {
      stream: {
        type: `rollup`,
        read_only: true,
        measures: [CUBE.count, CUBE.total_amount, CUBE.failed_count],
        dimensions: [CUBE.order_id, CUBE.user_id, CUBE.status],
        unique_key_columns: [
          `order_id`,
          `user_id`,
          `status`,
          `created_at_second`,
        ],
        time_dimension: CUBE.created_at,
        granularity: `second`,
        partition_granularity: `day`,
        // ksqlDB does not support NOW(); use CURRENT_TIMESTAMP with INTERVAL arithmetic instead.
        build_range_start: {
          sql: `SELECT date_trunc('day', CURRENT_TIMESTAMP - INTERVAL '5 hour')`,
        },
        build_range_end: {
          sql: `SELECT CURRENT_TIMESTAMP + INTERVAL '15 minute'`,
        },
        refresh_key: {
          every: `1 minute`,
          update_window: `1 hour`,
          incremental: true,
        },
        indexes: {
          user_status: {
            columns: [CUBE.user_id, CUBE.status, `orders__created_at_second`],
          },
        },
        stream_offset: `latest`,
        output_column_types: [
          { member: CUBE.order_id, type: `text` },
          { member: CUBE.user_id, type: `text` },
          { member: CUBE.status, type: `text` },
          { member: CUBE.created_at.second, type: `timestamp` },
          { member: CUBE.count, type: `int` },
          { member: CUBE.total_amount, type: `decimal` },
          { member: CUBE.failed_count, type: `int` },
        ],
      },
    },
  });
  ```
</CodeGroup>

Key properties for the streaming pre-aggregation:

* `read_only: true` — Cube will not create any objects in ksqlDB. The
  data is consumed directly from the backing Kafka topic.
* `stream_offset` — controls where Cube Store starts consuming from in
  the Kafka topic. Set to `"latest"` to only consume new messages
  arriving after the pre-aggregation is created. Set to `"earliest"` to
  replay the topic from the beginning. Defaults to `"latest"` if not
  specified. On subsequent refreshes, Cube Store automatically resumes
  from the last processed offset regardless of this setting.
* `unique_key_columns` — columns that uniquely identify a record, used
  for deduplication (see [below](#unique-key-columns-and-deduplication)).
* `output_column_types` — declares the output column types for the Cube
  Store table, required for Kafka streams mode (see
  [below](#output-column-types)).

#### Primary key and ungrouped queries

For the streaming pre-aggregation to work in read-only mode, the
generated SQL must not contain a `GROUP BY` clause — Cube Store's stream
post-processing engine does not support aggregation.

Cube automatically omits the `GROUP BY` clause when the dimensions
included in the pre-aggregation contain a primary key. In that case, the
generated query becomes a simple `SELECT ... FROM ...` without grouping,
and measures are passed through as raw expressions rather than
aggregated. This is what makes the pre-aggregation eligible for the
read-only streaming path.

You must include **all** primary key columns of the cube in the
streaming pre-aggregation's `dimensions` list. If any primary key
dimension is missing, the query may not be recognized as ungrouped
and will fail to use the streaming path.

The `sql_table` or `sql` value should reference an existing ksqlDB stream
or table. Cube discovers its schema automatically. With Kafka streams
mode enabled, the streaming pre-aggregation reads the backing Kafka topic
directly — no objects are created in ksqlDB.

#### Topic name matching

In Kafka streams mode, Cube Store parses the `select_statement`
(generated from the cube's `sql` property) and matches the `FROM` table
name against the actual Kafka topic name. On managed platforms like
Confluent Cloud, the Kafka topic name often differs from the ksqlDB
stream or table name — for example, a ksqlDB stream called
`ORDER_EVENTS_STREAM` might be backed by a Kafka topic named
`pksqlc-abc123ORDER_EVENTS_STREAM`.

The cube's `sql` property must reference the **ksqlDB stream or table
name** (not the Kafka topic), because Cube uses ksqlDB `DESCRIBE` to
discover the schema and resolve the backing topic. However, Cube does
not currently rewrite the `FROM` clause in the generated
`select_statement` to use the resolved Kafka topic name. If the ksqlDB
object name differs from the Kafka topic name, Cube Store will fail
with:

> Topic table ORDER\_EVENTS\_STREAM is not found

<Warning>
  **The ksqlDB stream (or table) name and the backing Kafka topic name
  MUST be identical, including case.** Kafka streams mode will fail if
  they differ in any way.

  Take this into account when creating the stream — explicitly set the
  topic name to match the stream name (and vice versa). For example:

  ```sql theme={"dark"}
  CREATE STREAM ORDER_EVENTS_STREAM (...)
    WITH (KAFKA_TOPIC='ORDER_EVENTS_STREAM', VALUE_FORMAT='JSON', ...);
  ```

  The match is **case-sensitive**: `OrderEvents` and `ORDEREVENTS` are
  treated as different names and will cause the build to fail with
  `Topic table ... is not found`.

  This is a known limitation of Kafka streams mode. It does not occur
  when the ksqlDB object name and the Kafka topic name are the same,
  which is the default behavior when ksqlDB creates a stream or table
  with the default topic naming strategy.
</Warning>

### Unique key columns and deduplication

When `unique_key_columns` is set, Cube Store appends an internal
sequence column (`__seq`) to the table, populated from the Kafka
partition offset. The unique key columns together with `__seq` form the
sort key for all indexes on this table.

Entries in `unique_key_columns` are strings, not member references. Use
the dimension's own name (for example, `user_id`). To include the time
dimension as part of the unique key, use the form
`<time_dimension_name>_<granularity>` — for example, `created_at_second`
when `granularity` is `second`.

<Warning>
  The naming convention for the time dimension inside `unique_key_columns`
  is **not** the same as the column name used in
  [`indexes`](/reference/data-modeling/pre-aggregations#indexes). Indexes
  expect the fully-qualified alias from the generated `select_statement`
  (`<cube_name>__<time_dimension_name>_<granularity>`), while
  `unique_key_columns` expects only `<time_dimension_name>_<granularity>`.
</Warning>

If the pre-aggregation defines `indexes`, every dimension referenced by
any index must also be listed in `unique_key_columns`. Cube Store uses
`unique_key_columns` (plus `__seq`) as the sort key for all indexes, so
an index column that is not part of the unique key cannot be sorted on
during compaction and the pre-aggregation build will fail.

Deduplication is not applied at ingestion time — all incoming records are
appended as they arrive. Instead, Cube Store deduplicates during
**reads** and **compaction**: rows are sorted by the unique key columns
and then by `__seq`, and only the **last row per unique key** (the one
with the highest sequence number) is kept. This means that if the same
key appears multiple times in the stream, the most recent version is
always the one returned by queries.

For Kafka messages, unique key column values can come from either the
message **payload** (the JSON value) or the message **key**. If a column
listed in `unique_key_columns` is missing from the payload, Cube Store
falls back to the Kafka message key: for a single unique key column, the
raw key value is used; for composite keys, the key is expected to be a
JSON object with matching field names.

### Output column types

In Kafka streams mode, Cube Store creates its internal pre-aggregation
table based on column type information. By default, column types are
inferred from the source ksqlDB stream using `DESCRIBE`. However, the
pre-aggregation's `select_statement` (generated from the rollup
definition) renames and transforms columns — for example, a source
column `CREATED_AT` becomes `order_events_stream__created_at_second` in
the output.

When this renaming happens, the raw source column types no longer match
the output column names, causing errors like:

> Key column `order_events_stream__id` not found among column definitions

To fix this, define `output_column_types` on the streaming
pre-aggregation. This tells Cube the exact output column types to use
for the Cube Store table, and separately passes the source schema so
Cube Store can deserialize the raw Kafka messages correctly.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  pre_aggregations:
    - name: stream
      type: rollup
      read_only: true
      measures:
        - CUBE.count
        - CUBE.total_amount
        - CUBE.failed_count
      dimensions:
        - CUBE.order_id
        - CUBE.user_id
        - CUBE.status
      unique_key_columns:
        - order_id
      time_dimension: CUBE.created_at
      granularity: second
      partition_granularity: day
      # ksqlDB does not support NOW(); use CURRENT_TIMESTAMP with INTERVAL arithmetic instead.
      build_range_start:
        sql: "SELECT date_trunc('day', CURRENT_TIMESTAMP - INTERVAL '5 hour')"
      build_range_end:
        sql: "SELECT CURRENT_TIMESTAMP + INTERVAL '15 minute'"
      refresh_key:
        every: 1 minute
        update_window: 1 hour
        incremental: true
      stream_offset: latest
      output_column_types:
        - member: CUBE.order_id
          type: text
        - member: CUBE.user_id
          type: text
        - member: CUBE.status
          type: text
        - member: CUBE.created_at.second
          type: timestamp
        - member: CUBE.count
          type: int
        - member: CUBE.total_amount
          type: decimal
        - member: CUBE.failed_count
          type: int
  ```

  ```javascript title="JavaScript" theme={"dark"}
  pre_aggregations: {
    stream: {
      type: `rollup`,
      read_only: true,
      measures: [CUBE.count, CUBE.total_amount, CUBE.failed_count],
      dimensions: [CUBE.order_id, CUBE.user_id, CUBE.status],
      unique_key_columns: [`order_id`],
      time_dimension: CUBE.created_at,
      granularity: `second`,
      partition_granularity: `day`,
      // ksqlDB does not support NOW(); use CURRENT_TIMESTAMP with INTERVAL arithmetic instead.
      build_range_start: {
        sql: `SELECT date_trunc('day', CURRENT_TIMESTAMP - INTERVAL '5 hour')`,
      },
      build_range_end: {
        sql: `SELECT CURRENT_TIMESTAMP + INTERVAL '15 minute'`,
      },
      refresh_key: {
        every: `1 minute`,
        update_window: `1 hour`,
        incremental: true,
      },
      stream_offset: `latest`,
      output_column_types: [
        { member: CUBE.order_id, type: `text` },
        { member: CUBE.user_id, type: `text` },
        { member: CUBE.status, type: `text` },
        { member: CUBE.created_at.second, type: `timestamp` },
        { member: CUBE.count, type: `int` },
        { member: CUBE.total_amount, type: `decimal` },
        { member: CUBE.failed_count, type: `int` },
      ],
    },
  },
  ```
</CodeGroup>

Each entry in `output_column_types` has two properties:

* `member` — a reference to a dimension or measure included in the
  pre-aggregation. This must be a `CUBE` member reference (for example,
  `CUBE.user_id`), not a string. For the time dimension, reference it
  with the rollup granularity attached — for example,
  `CUBE.created_at.second` when `granularity` is `second`.
* `type` — the Cube Store column type. Common values: `text`, `int`,
  `bigint`, `decimal`, `float`, `boolean`, `timestamp`.

Include an entry for every dimension and measure in the pre-aggregation.
The time dimension must also be listed, with `type: timestamp` and the
granularity suffix on the member reference as shown above.

When `output_column_types` is defined, Cube uses the aliased column
names (matching the `select_statement`) for the Cube Store table
definition and passes the raw source schema separately via
`source_table`, so Cube Store knows how to deserialize incoming Kafka
messages. Without it, column names come from the raw ksqlDB `DESCRIBE`
output and will not match the aliased names in the `select_statement`
or `unique_key_columns`.

<Warning>
  `output_column_types` is required for Kafka streams mode when the
  pre-aggregation uses `unique_key_columns`. Without it, the unique key
  column names will not match the table column definitions, causing the
  pre-aggregation build to fail.
</Warning>

### Stream format

Cube Store expects Kafka messages to have a **JSON object** as their
value payload, with field names matching the column names defined in the
cube. For example, given the streaming cube above, each Kafka message
value should look like:

```json theme={"dark"}
{
  "ORDER_ID": "ord_12345",
  "USER_ID": "usr_789",
  "STATUS": "completed",
  "AMOUNT": 49.99,
  "CREATED_AT": "2025-01-15T10:30:00.000"
}
```

Field names are case-sensitive and must match the column names used in
the `sql` property of each dimension and measure definition. Missing
fields default to `null`.

The message key is optional. When present and the value starts with `{`,
it is parsed as a JSON object and used as a fallback source for unique
key column values (see [above](#unique-key-columns-and-deduplication)).

#### Timestamp handling

For dimensions with `type: time`, Cube Store accepts timestamp values in
two formats:

* **String** — parsed using ISO 8601 / RFC 3339 formats. Supported
  patterns include:
  * `2025-01-15T10:30:00.000Z`
  * `2025-01-15T10:30:00Z`
  * `2025-01-15 10:30:00.000 UTC`
  * `2025-01-15T10:30:00`
  * `2025-01-15 10:30:00`
  * `2025-01-15`
* **Number** — interpreted as **epoch milliseconds** (not seconds, not
  microseconds). For example, `1736939400000` represents
  `2025-01-15T10:30:00.000Z`.

If your Kafka topic produces timestamps as strings in a non-standard
format, you can use `PARSE_TIMESTAMP` in the cube's `sql` property to
convert them. In that case, define the source column as `type: string`
in a `source_table` and use the `select_statement` to transform it:

```javascript theme={"dark"}
sql: `SELECT PARSE_TIMESTAMP(TIMESTAMP_STR,
  'yyyy-MM-dd''T''HH:mm:ss.SSSX', 'UTC') AS created_at,
  ORDER_ID, USER_ID, STATUS, AMOUNT
  FROM ORDER_EVENTS_STREAM`,
```

Time dimension truncation (controlled by the `granularity` property of
the pre-aggregation) is handled automatically. Cube generates the
appropriate `PARSE_TIMESTAMP(FORMAT_TIMESTAMP(CONVERT_TZ(...)))`
expression chain to truncate timestamps to the configured granularity
(e.g., `day`, `hour`, `minute`). Cube Store evaluates these expressions
natively on each micro-batch during ingestion. Standard SQL functions
like `date_trunc` are also available in the `select_statement`.

##### Converting `bigint` timestamps

When a source column stores a timestamp as a `bigint` (a common pattern
in Kafka topics — for example, a `created_at` field with values like
`1778800167128`), the value must be converted to a timestamp before it
can be used as a time dimension.

The conversion depends on the unit of the `bigint` value:

* **Milliseconds** (most common, e.g. `Date.now()` in JavaScript, Java's
  `System.currentTimeMillis()`) — multiply by `1000` before casting,
  because `CAST(... AS TIMESTAMP(6))` interprets numeric input as
  **microseconds**. Without the multiplication, a millisecond value like
  `1778800167128` is read as microseconds and produces a timestamp in
  1970 instead of the intended date.
* **Microseconds** — cast directly to `TIMESTAMP(6)`.
* **Seconds** — multiply by `1000000` before casting.

Apply the conversion in the time dimension's `sql` property:

```javascript theme={"dark"}
dimensions: {
  created_at: {
    sql: `CAST(${CUBE}.created_at * 1000 AS TIMESTAMP(6))`,
    type: `time`
  }
}
```

The cast runs first; any granularity truncation generated by Cube
(`PARSE_TIMESTAMP(FORMAT_TIMESTAMP(CONVERT_TZ(...)))`) then operates on
the resulting `TIMESTAMP(6)` value.

<Tip>
  When debugging a `bigint` timestamp issue, temporarily remove
  `partition_granularity` from the pre-aggregation. This skips
  partitioned builds and makes it easier to verify the conversion is
  correct before re-enabling partitioning.
</Tip>

### Filtering on the stream

When the streaming cube defines a `sql` property with a `SELECT`
statement (rather than `sql_table`), Cube Store applies the projection
and any `WHERE` filters from that statement directly on each micro-batch
of incoming Kafka messages. This filtering happens inside Cube Store
using its query engine — it does not require ksqlDB to process the
filter. Only rows that pass the filter are ingested into the
pre-aggregation table.

This allows you to define a streaming cube that only ingests a subset of
the data from the underlying Kafka topic without creating any
server-side filter objects in ksqlDB.

#### Supported SQL syntax

The `SELECT` statement must follow a strict shape. Cube Store only
accepts plans that resolve to **Projection > Filter > TableScan** (where
the filter is optional). Any other query plan shape is rejected.

**Supported:**

* `SELECT` with column references (e.g., `SELECT col1, col2 FROM topic`)
* `SELECT *` wildcard
* Column aliases (`SELECT col1 AS my_alias`)
* `WHERE` clause with comparison operators (`=`, `!=`, `<`, `>`, `<=`,
  `>=`)
* Boolean logic in `WHERE` (`AND`, `OR`, `NOT`)
* `IS NULL` and `IS NOT NULL`
* `IN` lists (`col IN (1, 2, 3)`)
* `BETWEEN` expressions
* `CASE ... WHEN ... THEN ... ELSE ... END` expressions
* `CAST(expr AS type)` type conversions
* `EXTRACT(field FROM expr)` for date/time parts
* `SUBSTRING(expr FROM start FOR length)`
* Scalar functions (e.g., `COALESCE`, `CONCAT`, arithmetic)
* `CONVERT_TZ` for timezone conversion (internally rewritten for
  compatibility)
* `PARSE_TIMESTAMP` and `FORMAT_TIMESTAMP` for timestamp parsing and
  formatting using ksql-style format strings (e.g.,
  `yyyy-MM-dd'T'HH:mm:ss.SSS`)
* Nested expressions with parentheses
* `date_trunc` for timestamp truncation

**Not supported:**

* `JOIN` clauses — only a single `FROM` table is allowed
* Subqueries in `SELECT` or `WHERE`
* `GROUP BY`, `HAVING`, or aggregate functions (`SUM`, `COUNT`, `AVG`,
  etc.)
* `ORDER BY` (rows are consumed in stream order)
* `LIMIT` and `OFFSET`
* `UNION`, `INTERSECT`, `EXCEPT`
* Window functions (`OVER`, `PARTITION BY`)
* Multiple `FROM` or multiple `WHERE` clauses
* Common Table Expressions (`WITH ... AS`)

All column expressions in the `SELECT` list that are not simple column
references must have explicit aliases. Unique key columns may reference
the source column through a scalar function (e.g.,
`CAST(id AS VARCHAR) AS id`), but not through arbitrary expressions.

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

[ref-streaming-pre-aggs]: /docs/pre-aggregations/using-pre-aggregations#streaming-pre-aggregations

[ref-decorated-env-vars]: /admin/connect-to-data/multiple-data-sources#under-the-hood

[ref-cube-data-source]: /reference/data-modeling/cube#data_source

[ref-lambda-pre-aggs]: /docs/pre-aggregations/lambda-pre-aggregations


# Materialize
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/materialize

The driver for Materialize is supported by its vendor. Please report any issues to their Slack.

<Warning>
  The driver for Materialize is supported by its vendor. Please report any issues
  to their [Slack][materialize-slack].
</Warning>

## Prerequisites

* The hostname for the [Materialize][materialize] database server

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=materialize
CUBEJS_DB_HOST=my.materialize.host
CUBEJS_DB_PORT=6875
CUBEJS_DB_NAME=materialize
CUBEJS_DB_USER=materialize
CUBEJS_DB_PASS=materialize
CUBEJS_DB_MATERIALIZE_CLUSTER=quickstart
```

## Environment Variables

| Environment Variable                                                                                            | Description                                                                        | Possible Values           | Required |
| --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------- | :------: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host)                               | The host URL for a database                                                        | A valid database host URL |     ✅    |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port)                               | The port for the database connection                                               | A valid port number       |     ✅    |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)                               | The name of the database to connect to                                             | A valid database name     |     ✅    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)                               | The username used to connect to the database                                       | A valid database username |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)                               | The password used to connect to the database                                       | A valid database password |     ✅    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool)                       | The maximum number of concurrent database connections to pool. Default is `8`      | A valid number            |     ❌    |
| [`CUBEJS_DB_MATERIALIZE_CLUSTER`](/reference/configuration/environment-variables#cubejs_db_materialize_cluster) | The name of the Materialize cluster to connect to                                  | A valid cluster name      |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)                       | The number of [concurrent queries][ref-data-source-concurrency] to the data source | A valid number            |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## SSL

To enable SSL-encrypted connections between Cube and Materialize, set the
[`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) environment variable to `true`. For more information on how to
configure custom certificates, please check out [Enable SSL Connections to the
Database][ref-recipe-enable-ssl].

[materialize]: https://materialize.com/docs/

[materialize-slack]: https://materialize.com/s/chat

[ref-recipe-enable-ssl]: /recipes/configuration/using-ssl-connections-to-data-source


# MongoDB
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/mongodb

Query MongoDB from Cube through the BI Connector’s SQL interface, including community-driver and Atlas deprecation caveats.

[MongoDB](https://www.mongodb.com) is a popular document database. It can be
accessed using SQL via the [MongoDB Connector for BI][link-bi-connector], also
known as *BI Connector*.

<Warning>
  The driver for MongoDB is community-supported and is not maintained by Cube or the database vendor.
</Warning>

<Warning>
  BI Connector for MongoDB Atlas, cloud-based MongoDB service, is approaching
  [end-of-life](https://www.mongodb.com/docs/atlas/bi-connection/#std-label-bi-connection).
  It will be deprecated and no longer supported in June 2025.
</Warning>

## Prerequisites

<Info>
  To use Cube with MongoDB you need to install the [MongoDB Connector for
  BI][mongobi-download]. [Learn more about setup for MongoDB
  here][cube-blog-mongodb].
</Info>

* [MongoDB Connector for BI][mongobi-download]
* The hostname for the [MongoDB][mongodb] database server
* The username/password for the [MongoDB][mongodb] database server

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=mongobi
# The MongoBI connector host. If using on local machine, it should be either `localhost` or `127.0.0.1`:
CUBEJS_DB_HOST=my.mongobi.host
# The default port of the MongoBI connector service
CUBEJS_DB_PORT=3307
CUBEJS_DB_NAME=my_mongodb_database
CUBEJS_DB_USER=mongodb_server_user
CUBEJS_DB_PASS=mongodb_server_password
# MongoBI requires SSL connections, so set the following to `true`:
CUBEJS_DB_SSL=true
```

If you are connecting to a local MongoBI Connector, which is pointing to a local
MongoDB instance, If MongoBI Connector and MongoDB are both running locally,
then the above should work. To connect to a remote MongoDB instance, first
configure `mongosqld` appropriately. See [here for an example config
file][mongobi-with-remote-db].

## Environment Variables

| Environment Variable                                                                      | Description                                                                        | Possible Values           | Required |
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------- | :------: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host)         | The host URL for a database                                                        | A valid database host URL |     ✅    |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port)         | The port for the database connection                                               | A valid port number       |     ❌    |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)         | The name of the database to connect to                                             | A valid database name     |     ✅    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)         | The username used to connect to the database                                       | A valid database username |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)         | The password used to connect to the database                                       | A valid database password |     ✅    |
| [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl)           | If `true`, enables SSL encryption for database connections from Cube               | `true`, `false`           |     ✅    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool) | The maximum number of concurrent database connections to pool. Default is `8`      | A valid number            |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency) | The number of [concurrent queries][ref-data-source-concurrency] to the data source | A valid number            |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
not be used in pre-aggregations when using MongoDB as a source database.

## Pre-Aggregation Build Strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Batching      |              ✅             |      ✅      |
| Export Bucket |              -             |      -      |

By default, MongoDB uses [batching][self-preaggs-batching] to build
pre-aggregations.

### Batching

No extra configuration is required to configure batching for MongoDB.

### Export Bucket

MongoDB does not support export buckets.

## SSL

To enable SSL-encrypted connections between Cube and MongoDB, set the
[`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) environment variable to `true`. For more information on how to
configure custom certificates, please check out [Enable SSL Connections to the
Database][ref-recipe-enable-ssl].

[mongodb]: https://www.mongodb.com/

[mongobi-with-remote-db]: https://docs.mongodb.com/bi-connector/current/reference/mongosqld/#example-configuration-file

[cube-blog-mongodb]: https://cube.dev/blog/building-mongodb-dashboard-using-nodejs

[mongobi-download]: https://www.mongodb.com/download-center/bi-connector

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[ref-recipe-enable-ssl]: /recipes/configuration/using-ssl-connections-to-data-source

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[self-preaggs-batching]: #batching

[link-bi-connector]: https://www.mongodb.com/docs/bi-connector/current/


# Microsoft Fabric
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/ms-fabric

Microsoft Fabric is an all-in-one analytics solution for enterprises. It offers a comprehensive suite of services, including a data warehouse.

[Microsoft Fabric][link-fabric] is an all-in-one analytics solution for
enterprises. It offers a comprehensive suite of services, including a
data warehouse.

<Note>
  Available on the [Enterprise plan](https://cube.dev/pricing).
  [Contact us](https://cube.dev/contact) for details.
</Note>

## Setup

When creating a new deployment in Cube Cloud, at the **Set up a database
connection** step, choose **Microsoft Fabric**.

<Frame>
  <img />
</Frame>

Then, provide the **JDBC URL** connection string in the following
format. See below for tips on filling in `<SERVER_NAME>`, `<DATABASE_NAME>`,
`<AUTH_TYPE>`, `<USER_NAME>`, and `<PASSWORD>`.

```text theme={"dark"}
jdbc:sqlserver://;serverName=<SERVER_NAME>.datawarehouse.pbidedicated.windows.net;database=<DATABASE_NAME>;encrypt=true;Authentication=<AUTH_TYPE>;UserName=<USER_NAME>;Password=<PASSWORD>
```

Optionally, fill in **Database** if you'd like to override the database
name from the JDBC URL.

### Server and database name

To obtain your data warehouse server name and database name, navigate to your
data warehouse in Microsoft Fabric and click on the cog icon to open
**Settings**:

<Frame>
  <img />
</Frame>

On the **About** page, you can find the database name (`<DATABASE_NAME>`)
under **Name** and the server name (`<SERVER_NAME>`) under
**SQL connection string**:

<Frame>
  <img />
</Frame>

### Authentication

Microsoft Fabric supports two [authentication types][link-fabric-auth]:

* Use `ActiveDirectoryPassword` as `<AUTH_TYPE>` to connect using a
  Microsoft Entra principal name and password. Provide principal name as
  `<USER_NAME>` and password as `<PASSWORD>`.
* Use `ActiveDirectoryServicePrincipal` as `<AUTH_TYPE>` to connect
  using the client ID and secret of a service principal identity. Provide
  client ID as `<USER_NAME>` and secet as `<PASSWORD>`.

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
not be used in pre-aggregations when using Microsoft Fabric as a source
database.

## Pre-Aggregation Build Strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Simple        |              ✅             |      ✅      |
| Batching      |              -             |      -      |
| Export Bucket |              -             |      -      |

By default, Microsoft Fabric uses a [simple][self-preaggs-simple] strategy
to build pre-aggregations.

### Simple

No extra configuration is required to configure simple pre-aggregation builds
for Microsoft Fabric.

### Batching

Microsoft Fabric does not support batching.

### Export Bucket

Microsoft Fabric does not support export buckets.

[link-fabric]: https://www.microsoft.com/en-us/microsoft-fabric/

[link-fabric-auth]: https://learn.microsoft.com/en-us/sql/connect/jdbc/setting-the-connection-properties?view=sql-server-ver16#properties

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[self-preaggs-simple]: #simple


# Microsoft SQL Server
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/ms-sql

Connect Cube to SQL Server with database host credentials, optional domain-scoped login, and SSL or pool tuning as needed.

## Prerequisites

* The hostname for the [Microsoft SQL Server][mssql] database server
* The username/password for the [Microsoft SQL Server][mssql] database server
* The name of the database to use within the [Microsoft SQL Server][mssql]
  database server

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=mssql
CUBEJS_DB_HOST=my.mssql.host
CUBEJS_DB_NAME=my_mssql_database
CUBEJS_DB_USER=mssql_user
CUBEJS_DB_PASS=**********
```

## Environment Variables

| Environment Variable                                                                                                        | Description                                                                                                                 | Possible Values                                            | Required |
| --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | :------: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host)                                           | The host URL for a database                                                                                                 | A valid database host URL                                  |     ✅    |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port)                                           | The port for the database connection                                                                                        | A valid port number                                        |     ❌    |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)                                           | The name of the database to connect to                                                                                      | A valid database name                                      |     ✅    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)                                           | The username used to connect to the database                                                                                | A valid database username                                  |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)                                           | The password used to connect to the database                                                                                | A valid database password                                  |     ✅    |
| [`CUBEJS_DB_DOMAIN`](/reference/configuration/environment-variables#cubejs_db_domain)                                       | A domain name within the database to connect to                                                                             | A valid domain name within a Microsoft SQL Server database |     ❌    |
| [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl)                                             | If `true`, enables SSL encryption for database connections from Cube                                                        | `true`, `false`                                            |     ❌    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool)                                   | The maximum number of concurrent database connections to pool. Default is `8`                                               | A valid number                                             |     ❌    |
| [`CUBEJS_DB_MSSQL_USE_NAMED_TIMEZONES`](/reference/configuration/environment-variables#cubejs_db_mssql_use_named_timezones) | The flag to use time zone names (with DST-aware conversion) or numeric offsets for time zone conversion. Default is `false` | `true`, `false`                                            |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)                                   | The number of [concurrent queries][ref-data-source-concurrency] to the data source                                          | A valid number                                             |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
not be used in pre-aggregations when using Microsoft SQL Server as a source
database.

## Pre-Aggregation Build Strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Simple        |              ✅             |      ✅      |
| Batching      |              -             |      -      |
| Export Bucket |              -             |      -      |

By default, Microsoft SQL Server uses a [simple][self-preaggs-simple] strategy
to build pre-aggregations.

### Simple

No extra configuration is required to configure simple pre-aggregation builds
for Microsoft SQL Server.

### Batching

Microsoft SQL Server does not support batching.

### Export Bucket

Microsoft SQL Server does not support export buckets.

## SSL

To enable SSL-encrypted connections between Cube and Microsoft SQL Server, set
the [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) environment variable to `true`. For more information on how
to configure custom certificates, please check out [Enable SSL Connections to
the Database][ref-recipe-enable-ssl].

## Additional Configuration

### Windows Authentication

To connect to a Microsoft SQL Server database using Windows Authentication (also
sometimes known as `trustedConnection`), instantiate the driver with
`trustedConnection: true` in your `cube.js` configuration file:

```javascript theme={"dark"}
const MssqlDriver = require("@cubejs-backend/mssql-driver")
module.exports = {
  driverFactory: ({ dataSource }) =>
    new MssqlDriver({ database: dataSource, trustedConnection: true })
}
```

[mssql]: https://www.microsoft.com/en-gb/sql-server/sql-server-2019

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[ref-recipe-enable-ssl]: /recipes/configuration/using-ssl-connections-to-data-source

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[self-preaggs-simple]: #simple


# MySQL
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/mysql

Configure Cube’s MySQL client with TCP or Unix socket access, SSL, pooling limits, and optional timezone handling flags.

## Prerequisites

* The hostname for the [MySQL][mysql] database server
* The username/password for the [MySQL][mysql] database server
* The name of the database to use within the [MySQL][mysql] database server

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=mysql
CUBEJS_DB_HOST=my.mysql.host
CUBEJS_DB_NAME=my_mysql_database
CUBEJS_DB_USER=mysql_user
CUBEJS_DB_PASS=**********
```

## Environment Variables

| Environment Variable                                                                                                        | Description                                                                                     | Possible Values           | Required |
| --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------- | :------: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host)                                           | The host URL for a database                                                                     | A valid database host URL |     ✅    |
| [`CUBEJS_DB_SOCKET_PATH`](/reference/configuration/environment-variables#cubejs_db_socket_path)                             | See [connecting via a Unix socket](#connecting-via-a-unix-socket)                               | A valid path to a socket  |     ❌    |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port)                                           | The port for the database connection                                                            | A valid port number       |     ❌    |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)                                           | The name of the database to connect to                                                          | A valid database name     |     ✅    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)                                           | The username used to connect to the database                                                    | A valid database username |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)                                           | The password used to connect to the database                                                    | A valid database password |     ✅    |
| [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl)                                             | If `true`, enables SSL encryption for database connections from Cube                            | `true`, `false`           |     ❌    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool)                                   | The maximum number of concurrent database connections to pool. Default is `8`                   | A valid number            |     ❌    |
| [`CUBEJS_DB_MYSQL_USE_NAMED_TIMEZONES`](/reference/configuration/environment-variables#cubejs_db_mysql_use_named_timezones) | The flag to use time zone names or numeric offsets for time zone conversion. Default is `false` | `true`, `false`           |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)                                   | The number of [concurrent queries][ref-data-source-concurrency] to the data source              | A valid number            |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
not be used in pre-aggregations when using MySQL as a source database.

## Pre-Aggregation Build Strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Batching      |              ✅             |      ✅      |
| Export Bucket |              -             |      -      |

By default, MySQL uses [batching][self-preaggs-batching] to build
pre-aggregations.

### Batching

No extra configuration is required to configure batching for MySQL.

### Export Bucket

MySQL does not support export buckets.

## SSL

To enable SSL-encrypted connections between Cube and MySQL, set the
[`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) environment variable to `true`. For more information on how to
configure custom certificates, please check out [Enable SSL Connections to the
Database][ref-recipe-enable-ssl].

## Additional configuration

### Connecting via a Unix socket

To connect to a local MySQL database using a Unix socket, use the
[`CUBEJS_DB_SOCKET_PATH`](/reference/configuration/environment-variables#cubejs_db_socket_path) environment variable, for example:

```dotenv theme={"dark"}
CUBEJS_DB_SOCKET_PATH=/var/run/mysqld/mysqld.sock
```

When doing so, [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host) will be ignored.

### Connecting to MySQL 8

MySQL 8 uses a new default authentication plugin (`caching_sha2_password`)
whereas previous version used `mysql_native_password`. Please
[see this answer on StackOverflow](https://stackoverflow.com/a/50377944)
for a workaround.

<Info>
  For additional details, check the [relevant issue](https://github.com/cube-js/cube/issues/3525) on GitHub.
</Info>

[mysql]: https://www.mysql.com/

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[ref-recipe-enable-ssl]: /recipes/configuration/using-ssl-connections-to-data-source

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[self-preaggs-batching]: #batching


# Oracle
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/oracle

The driver for Oracle is community-supported and is not maintained by Cube or the database vendor.

<Warning>
  The driver for Oracle is community-supported and is not maintained by Cube or the database vendor.
</Warning>

## Prerequisites

* The hostname for the [Oracle][oracle] database server
* The username/password for the [Oracle][oracle] database server
* The name of the database to use within the [Oracle][oracle] database server

<Info>
  The driver uses [`node-oracledb`][node-oracledb] in Thin mode, which supports Oracle Database
  12.1 and later. Older servers (e.g. 11g) require [Thick mode][node-oracledb-thick], which the
  driver does not currently enable — [track this issue](https://github.com/cube-js/cube/issues/10756).
</Info>

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=oracle
CUBEJS_DB_HOST=my.oracle.host
CUBEJS_DB_NAME=my_oracle_database
CUBEJS_DB_USER=oracle_user
CUBEJS_DB_PASS=**********
```

## Environment Variables

| Environment Variable                                                                      | Description                                                                        | Possible Values           | Required |
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------- | :------: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host)         | The host URL for a database                                                        | A valid database host URL |     ✅    |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port)         | The port for the database connection                                               | A valid port number       |     ❌    |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)         | The name of the database to connect to                                             | A valid database name     |     ✅    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)         | The username used to connect to the database                                       | A valid database username |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)         | The password used to connect to the database                                       | A valid database password |     ✅    |
| [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl)           | If `true`, enables SSL encryption for database connections from Cube               | `true`, `false`           |     ❌    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool) | The maximum number of concurrent database connections to pool. Default is `8`      | A valid number            |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency) | The number of [concurrent queries][ref-data-source-concurrency] to the data source | A valid number            |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## SSL

To enable SSL-encrypted connections between Cube and Oracle, set the
[`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) environment variable to `true`. For more information on how to
configure custom certificates, please check out [Enable SSL Connections to the
Database][ref-recipe-enable-ssl].

[oracle]: https://www.oracle.com/uk/index.html

[node-oracledb]: https://node-oracledb.readthedocs.io/en/latest/user_guide/introduction.html#architecture

[node-oracledb-thick]: https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#enabling-node-oracledb-thick-mode

[ref-recipe-enable-ssl]: /recipes/configuration/using-ssl-connections-to-data-source


# Apache Pinot
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/pinot

Broker-level connection details and required Pinot SQL features for wiring Cube to an Apache Pinot cluster via environment variables.

[Apache Pinot][link-pinot] is a real-time distributed OLAP datastore purpose-built
for low-latency, high-throughput analytics, and perfect for user-facing analytical
workloads. [StarTree][link-startree] is a fully-managed platform for Pinot.

## Prerequisites

* The hostname for the [Pinot][pinot] broker
* The port for the [Pinot][pinot] broker

Note that the following features should be enabled in your Pinot cluster:

* [Multi-stage query engine][link-pinot-msqe].
* [Advanced null value support][link-pinot-nvs].

## Setup

<Note>
  Currently, Apache Pinot is not shown in the list of available data sources in the UI.
  However, you can still [configure](https://github.com/cube-js/cube/issues/8579#issuecomment-2453545048)
  it using environment variables.
</Note>

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=pinot
CUBEJS_DB_HOST=http[s]://pinot.broker.host
CUBEJS_DB_PORT=8099
CUBEJS_DB_USER=pinot_user
CUBEJS_DB_PASS=**********
```

## Environment Variables

| Environment Variable                                                                                            | Description                                                                        | Possible Values     | Required |
| --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------- | :------: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host)                               | The host URL for your Pinot broker                                                 | A valid host URL    |     ✅    |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port)                               | The port for the database connection                                               | A valid port number |     ✅    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)                               | The username used to connect to the broker                                         | A valid username    |     ❌    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)                               | The password used to connect to the broker                                         | A valid password    |     ❌    |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)                               | The database name for StarTree                                                     | A valid name        |     ❌    |
| [`CUBEJS_DB_PINOT_NULL_HANDLING`](/reference/configuration/environment-variables#cubejs_db_pinot_null_handling) | If `true`, enables null handling. Default is `false`                               | `true`, `false`     |     ❌    |
| [`CUBEJS_DB_PINOT_AUTH_TOKEN`](/reference/configuration/environment-variables#cubejs_db_pinot_auth_token)       | The authentication token for StarTree                                              | A valid token       |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)                       | The number of [concurrent queries][ref-data-source-concurrency] to the data source | A valid number      |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
be used in pre-aggregations when using Pinot as a source database. To learn more
about Pinot support for approximate aggregate functions, [click
here][pinot-docs-approx-agg-fns].

## Pre-aggregation build strategies

<Info>
  To learn more about pre-aggregation build strategies, \[head
  here]\[ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Simple        |              ✅             |      ✅      |
| Batching      |              -             |      -      |
| Export bucket |              -             |      -      |

By default, Pinot uses a simple strategy to build pre-aggregations.

### Simple

No extra configuration is required to configure simple pre-aggregation builds
for Pinot.

### Batching

Pinot does not support batching.

### Export bucket

Pinot does not support export buckets.

## SSL

Cube does not require any additional configuration to enable SSL as Pinot connections are made over HTTPS.

[link-pinot]: https://pinot.apache.org/

[pinot]: https://docs.pinot.apache.org/

[link-pinot-msqe]: https://docs.pinot.apache.org/reference/multi-stage-engine

[link-pinot-nvs]: https://docs.pinot.apache.org/developers/advanced/null-value-support#advanced-null-handling-support

[pinot-docs-approx-agg-fns]: https://docs.pinot.apache.org/users/user-guide-query/query-syntax/how-to-handle-unique-counting

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[link-startree]: https://startree.ai


# Postgres
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/postgres

Supply PostgreSQL host, database name, credentials, and optional SSL or pool settings to connect Cube as a client.

## Prerequisites

* The hostname for the [Postgres][postgres] database server
* The username/password for the [Postgres][postgres] database server
* The name of the database to use within the [Postgres][postgres] database
  server

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=postgres
CUBEJS_DB_HOST=my.postgres.host
CUBEJS_DB_NAME=my_postgres_database
CUBEJS_DB_USER=postgres_user
CUBEJS_DB_PASS=**********
```

## Environment Variables

| Environment Variable                                                                      | Description                                                                        | Possible Values           | Required |
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------- | :------: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host)         | The host URL for a database                                                        | A valid database host URL |     ✅    |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port)         | The port for the database connection                                               | A valid port number       |     ❌    |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)         | The name of the database to connect to                                             | A valid database name     |     ✅    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)         | The username used to connect to the database                                       | A valid database username |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)         | The password used to connect to the database                                       | A valid database password |     ✅    |
| [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl)           | If `true`, enables SSL encryption for database connections from Cube               | `true`, `false`           |     ❌    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool) | The maximum number of concurrent database connections to pool. Default is `8`      | A valid number            |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency) | The number of [concurrent queries][ref-data-source-concurrency] to the data source | A valid number            |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
only be used in pre-aggregations when using the [Postgres HLL
extension][gh-postgres-hll] with Postgres as a source database.

## Pre-Aggregation Build Strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Batching      |              ✅             |      ✅      |
| Export Bucket |              -             |      -      |

By default, Postgres uses [batching][self-preaggs-batching] to build
pre-aggregations.

### Batching

No extra configuration is required to configure batching for Postgres.

### Export Bucket

Postgres does not support export buckets.

## SSL

To enable SSL-encrypted connections between Cube and Postgres, set the
[`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) environment variable to `true`. For more information on how to
configure custom certificates, please check out [Enable SSL Connections to the
Database][ref-recipe-enable-ssl].

## Additional Configuration

### AWS RDS

Use `CUBEJS_DB_SSL=true` to enable SSL if you have SSL enabled for your RDS
cluster. Download the new certificate [here][aws-rds-pem], and provide the
contents of the downloaded file to [`CUBEJS_DB_SSL_CA`](/reference/configuration/environment-variables#cubejs_db_ssl_ca). All other SSL-related
environment variables can be left unset. See [the SSL section][self-ssl] for
more details. More info on AWS RDS SSL can be found [here][aws-docs-rds-ssl].

### Google Cloud SQL

You can connect to an SSL-enabled MySQL database by setting [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) to
`true`. You may also need to set [`CUBEJS_DB_SSL_SERVERNAME`](/reference/configuration/environment-variables#cubejs_db_ssl_servername), depending on how
you are [connecting to Cloud SQL][gcp-docs-sql-connect].

### Heroku

Unless you're using a Private or Shield Heroku Postgres database, Heroku
Postgres does not currently support verifiable certificates. [Here is the
description of the issue from Heroku][heroku-postgres-issue].

As a workaround, you can set `rejectUnauthorized` option to `false` in the Cube
Postgres driver:

```javascript theme={"dark"}
const PostgresDriver = require("@cubejs-backend/postgres-driver")
module.exports = {
  driverFactory: () =>
    new PostgresDriver({
      ssl: {
        rejectUnauthorized: false
      }
    })
}
```

[aws-docs-rds-ssl]: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html

[aws-rds-pem]: https://s3.amazonaws.com/rds-downloads/rds-ca-2019-root.pem

[gcp-docs-sql-connect]: https://cloud.google.com/sql/docs/postgres/connect-functions#connect

[gh-postgres-hll]: https://github.com/citusdata/postgresql-hll

[heroku-postgres-issue]: https://help.heroku.com/3DELT3RK/why-can-t-my-third-party-utility-connect-to-heroku-postgres-with-ssl

[postgres]: https://www.postgresql.org/

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[ref-recipe-enable-ssl]: /recipes/configuration/using-ssl-connections-to-data-source

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[self-preaggs-batching]: #batching

[self-ssl]: #ssl


# Presto
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/presto

Connect Cube to PrestoDB using hostname authentication together with catalog and schema selectors for your query engine layout.

## Prerequisites

* The hostname for the [Presto][presto] database server
* The username/password for the [Presto][presto] database server
* The name of the database to use within the [Presto][presto] database server

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=prestodb
CUBEJS_DB_HOST=my.presto.host
CUBEJS_DB_USER=presto_user
CUBEJS_DB_PASS=**********
CUBEJS_DB_PRESTO_CATALOG=my_presto_catalog
CUBEJS_DB_SCHEMA=my_presto_schema
```

## Environment Variables

| Environment Variable                                                                                                      | Description                                                                                                     | Possible Values                                                | Required |
| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | :------: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host)                                         | The host URL for a database                                                                                     | A valid database host URL                                      |     ✅    |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port)                                         | The port for the database connection                                                                            | A valid port number                                            |     ❌    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)                                         | The username used to connect to the database                                                                    | A valid database username                                      |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)                                         | The password used to connect to the database                                                                    | A valid database password                                      |     ✅    |
| [`CUBEJS_DB_PRESTO_CATALOG`](/reference/configuration/environment-variables#cubejs_db_presto_catalog)                     | The catalog within Presto to connect to                                                                         | A valid catalog name within a Presto database                  |     ✅    |
| [`CUBEJS_DB_PRESTO_AUTH_TOKEN`](/reference/configuration/environment-variables#cubejs_db_presto_auth_token)               | The authentication token to use when connecting to Presto/Trino. It will be sent in the `Authorization` header. | A valid authentication token                                   |     ❌    |
| [`CUBEJS_DB_SCHEMA`](/reference/configuration/environment-variables#cubejs_db_schema)                                     | The schema within the database to connect to                                                                    | A valid schema name within a Presto database                   |     ✅    |
| [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl)                                           | If `true`, enables SSL encryption for database connections from Cube                                            | `true`, `false`                                                |     ❌    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool)                                 | The maximum number of concurrent database connections to pool. Default is `8`                                   | A valid number                                                 |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)                                 | The number of [concurrent queries][ref-data-source-concurrency] to the data source                              | A valid number                                                 |     ❌    |
| [`CUBEJS_DB_EXPORT_BUCKET_TYPE`](/reference/configuration/environment-variables#cubejs_db_export_bucket_type)             | The export bucket type for pre-aggregations                                                                     | `s3`, `gcs`                                                    |     ❌    |
| [`CUBEJS_DB_EXPORT_BUCKET`](/reference/configuration/environment-variables#cubejs_db_export_bucket)                       | The export bucket to connect to                                                                                 | A valid bucket URL                                             |     ❌    |
| [`CUBEJS_DB_EXPORT_BUCKET_AWS_KEY`](/reference/configuration/environment-variables#cubejs_db_export_bucket_aws_key)       | The AWS Access Key ID to use for export bucket writes                                                           | A valid AWS Access Key ID                                      |     ❌    |
| [`CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET`](/reference/configuration/environment-variables#cubejs_db_export_bucket_aws_secret) | The AWS Secret Access Key to use for export bucket writes                                                       | A valid AWS Secret Access Key                                  |     ❌    |
| [`CUBEJS_DB_EXPORT_BUCKET_AWS_REGION`](/reference/configuration/environment-variables#cubejs_db_export_bucket_aws_region) | The AWS region to use for export bucket writes                                                                  | A valid AWS region                                             |     ❌    |
| [`CUBEJS_DB_EXPORT_GCS_CREDENTIALS`](/reference/configuration/environment-variables#cubejs_db_export_gcs_credentials)     | A Base64 encoded JSON key file for connecting to Google Cloud Storage                                           | A valid Google Cloud JSON key file, encoded as a Base64 string |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
be used in pre-aggregations when using Presto as a source database. To learn
more about Presto support for approximate aggregate functions, [click
here][presto-docs-approx-agg-fns].

## Pre-Aggregation Build Strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Simple        |              ✅             |      ✅      |
| Export Bucket |              ❌             |      ❌      |

By default, Presto uses a [simple][self-preaggs-simple] strategy to
build pre-aggregations.

### Simple

No extra configuration is required to configure simple pre-aggregation builds
for Presto.

### Export Bucket

Presto supports using both [AWS S3][aws-s3] and [Google Cloud Storage][google-cloud-storage] for export bucket functionality.

#### AWS S3

<Info>
  Ensure the AWS credentials are correctly configured in IAM to allow reads and
  writes to the export bucket in S3.
</Info>

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET_TYPE=s3
CUBEJS_DB_EXPORT_BUCKET=my.bucket.on.s3
CUBEJS_DB_EXPORT_BUCKET_AWS_KEY=<AWS_KEY>
CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET=<AWS_SECRET>
CUBEJS_DB_EXPORT_BUCKET_AWS_REGION=<AWS_REGION>
```

#### Google Cloud Storage

<Info>
  When using an export bucket, remember to assign the **Storage Object Admin**
  role to your Google Cloud credentials ([`CUBEJS_DB_EXPORT_GCS_CREDENTIALS`](/reference/configuration/environment-variables#cubejs_db_export_gcs_credentials)).
</Info>

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET=gs://presto-export-bucket
CUBEJS_DB_EXPORT_BUCKET_TYPE=gcs
CUBEJS_DB_EXPORT_GCS_CREDENTIALS=<BASE64_ENCODED_SERVICE_CREDENTIALS_JSON>
```

## SSL

To enable SSL-encrypted connections between Cube and Presto, set the
[`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) environment variable to `true`. For more information on how to
configure custom certificates, please check out [Enable SSL Connections to the
Database][ref-recipe-enable-ssl].

## Custom headers

The Presto driver supports forwarding custom HTTP headers on every request to
the Presto coordinator. This is useful for setting headers like
`X-Presto-Source`, `X-Presto-Client-Tags`, or any other custom header your
Presto coordinator expects.

Custom headers can't be configured via environment variables. Instead, use the
[`driver_factory`](/reference/configuration/config#driver_factory) configuration
option to pass a `headers` object to the driver:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('driver_factory')
  def driver_factory(ctx: dict) -> dict:
    return {
      'type': 'prestodb',
      'headers': {
        'X-Presto-Source': 'cube',
        'X-Presto-Client-Tags': 'user=alice@example.com'
      }
    }
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    driverFactory: ({ dataSource }) => ({
      type: "prestodb",
      headers: {
        "X-Presto-Source": "cube",
        "X-Presto-Client-Tags": "user=alice@example.com"
      }
    })
  };
  ```
</CodeGroup>

In multitenant deployments, you can use the [security
context](/embedding/authentication/security-context) to pass per-tenant headers,
for example to forward a user token from the API request down to Presto:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('driver_factory')
  def driver_factory(ctx: dict) -> dict:
    security_context = ctx['securityContext']
    return {
      'type': 'prestodb',
      'headers': {
        'X-Presto-Client-Tags': f"user={security_context['user_id']}",
        'X-Custom-User-Token': security_context['token']
      }
    }
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    driverFactory: ({ securityContext }) => ({
      type: "prestodb",
      headers: {
        "X-Presto-Client-Tags": `user=${securityContext.user_id}`,
        "X-Custom-User-Token": securityContext.token
      }
    })
  };
  ```
</CodeGroup>

[aws-s3]: https://aws.amazon.com/s3/

[google-cloud-storage]: https://cloud.google.com/storage

[presto]: https://prestodb.io/

[presto-docs-approx-agg-fns]: https://prestodb.io/docs/current/functions/aggregate.html

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[ref-recipe-enable-ssl]: /recipes/configuration/using-ssl-connections-to-data-source

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[self-preaggs-simple]: #simple


# QuestDB
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/questdb

QuestDB is a high-performance time-series database which helps you overcome ingestion bottlenecks.

[QuestDB][questdb] is a high-performance [time-series database][time-series-database-glossary] which helps you overcome ingestion bottlenecks.

<Warning>
  The driver for QuestDB is supported by its vendor. Please report any issues to
  their [Slack][questdb-slack].
</Warning>

## Prerequisites

* The hostname for the QuestDB database server
  * If QuestDB is not running, checkout the QuestDB [quick start][questdb-quick-start]
* [Docker][docker] (optional)

## Setup

### Docker

Create a dockerfile within the project directory:

```yaml title=docker-compose.yml theme={"dark"}
services:
  cube:
    environment:
      - CUBEJS_DEV_MODE=true
    image: "cubejs/cube:latest"
    ports:
      - "4000:4000"
    volumes:
      - ".:/cube/conf"
  questdb:
    container_name: questdb
    hostname: questdb
    image: "questdb/questdb:latest"
    ports:
      - "9000:9000"
      - "8812:8812"
```

Within your project directory, create an `.env` file:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=questdb
CUBEJS_DB_HOST=my.questdb.host
CUBEJS_DB_PORT=8812
CUBEJS_DB_NAME=qdb
CUBEJS_DB_USER=admin
CUBEJS_DB_PASS=quest
```

Finally, bring it all up with Docker:

```bash title=shell theme={"dark"}
docker-compose up -d
```

Access Cube at [http://localhost:4000](http://localhost:4000) & QuestDB at [http://localhost:9000](http://localhost:9000)

<Warning>
  Development mode is an authentication bypass. Cube is in development mode when
  `CUBEJS_DEV_MODE=true` — which, under the `cubejs` CLI and the official Docker images,
  also forces `NODE_ENV=development` and so switches off JWT verification on the
  REST (JSON) and GraphQL APIs — and whenever `NODE_ENV` is not
  `production`. Playground's endpoints are served with no authentication too: anyone who
  can reach the instance is handed a ready-to-use API token, can mint others carrying any
  security context, can read your data model files, and can overwrite your data model and
  your `.env`. With `CUBEJS_DEV_MODE=true` and no
  [`CUBEJS_SQL_PASSWORD`](/reference/configuration/environment-variables#cubejs_sql_password)
  set, the SQL API accepts any credentials as well, allowing arbitrary SQL against
  connected data sources. Use it only on a local development machine, never in
  production. See
  [`CUBEJS_DEV_MODE`](/reference/configuration/environment-variables#cubejs_dev_mode).
</Warning>

## Environment Variables

| Environment Variable                                                                      | Description                                                                        | Possible Values           | Required |
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------- | :------: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host)         | The host URL for a database                                                        | A valid database host URL |     ✅    |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port)         | The port for the database connection                                               | A valid port number       |     ✅    |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)         | The name of the database to connect to                                             | A valid database name     |     ✅    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)         | The username used to connect to the database                                       | A valid database username |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)         | The password used to connect to the database                                       | A valid database password |     ✅    |
| [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl)           | If `true`, enables SSL encryption for database connections from Cube               | `true`, `false`           |     ❌    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool) | The maximum number of concurrent database connections to pool. Default is `8`      | A valid number            |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency) | The number of [concurrent queries][ref-data-source-concurrency] to the data source | A valid number            |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

[questdb]: https://questdb.io/

[questdb-slack]: https://slack.questdb.io/

[time-series-database-glossary]: https://questdb.io/glossary/time-series/database/

[questdb-quick-start]: https://questdb.io/docs/quick-start/

[docker]: https://docs.docker.com/get-docker/


# RisingWave
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/risingwave

Point Cube at RisingWave using the Postgres-compatible driver and your cluster host, database, and credential settings.

[RisingWave](https://risingwave.com) is a distributed streaming database that enables
processing and management of real-time data with a Postgres-style SQL syntax. It is
available as an [open-source edition](https://github.com/risingwavelabs/risingwave)
and a managed cloud service.

## Prerequisites

* [Credentials](https://docs.risingwave.com/docs/current/risingwave-docker-compose/#connect-to-risingwave) for the RisingWave cluster

## Setup

RisingWave provides a Postgres-compatible interface. You can connect Cube to RisingWave
as if it's a regular [Postgres][ref-postgres] data source.

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=postgres
CUBEJS_DB_HOST=risingwave_host
CUBEJS_DB_PORT=risingwave_port
CUBEJS_DB_NAME=risingwave_database
CUBEJS_DB_USER=risingwave_user
CUBEJS_DB_PASS=risingwave_password
```

## Environment variables

| Environment Variable                                                                      | Description                                                                                                                                       | Possible Values           | Required |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | :------: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host)         | The host URL for a database                                                                                                                       | A valid database host URL |     ✅    |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port)         | The port for the database connection                                                                                                              | A valid port number       |     ❌    |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)         | The name of the database to connect to                                                                                                            | A valid database name     |     ✅    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)         | The username used to connect to the database                                                                                                      | A valid database username |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)         | The password used to connect to the database                                                                                                      | A valid database password |     ✅    |
| [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl)           | If `true`, enables [SSL encryption](https://docs.risingwave.com/docs/current/secure-connections-with-ssl-tls/) for database connections from Cube | `true`, `false`           |     ❌    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool) | The maximum number of concurrent database connections to pool. Default is `8`                                                                     | A valid number            |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency) | The number of [concurrent queries][ref-data-source-concurrency] to the data source                                                                | A valid number            |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-aggregation feature support

### `count_distinct_approx`

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
not be used in pre-aggregations when using RisingWave as a source database.

## Pre-aggregation build strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Simple        |              ✅             |      ✅      |
| Batching      |              -             |      -      |
| Export bucket |              -             |      -      |

By default, RisingWave uses a simple strategy to build pre-aggregations.

### Simple

No extra configuration is required to configure simple pre-aggregation builds
for RisingWave.

### Batching

RisingWave does not support batching.

### Export bucket

RisingWave does not support export buckets.

[ref-postgres]: /admin/connect-to-data/data-sources/postgres

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type


# SingleStore
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/singlestore

SingleStore is a distributed SQL database that offers high-throughput transactions (inserts and upserts) and low-latency analytics.

[SingleStore][link-singlestore] is a distributed SQL database that offers
high-throughput transactions (inserts and upserts) and low-latency analytics.

<Note>
  Available on the [Enterprise plan](https://cube.dev/pricing).
  [Contact us](https://cube.dev/contact) for details.
</Note>

## Setup

When creating a new deployment in Cube Cloud, at the **Set up a database
connection** step, choose **SingleStore**.

<Frame>
  <img />
</Frame>

Then, provide credetials: host name, database name, user name (`admin` by
default), and password.

### Host name

To obtain the host name, navigate to the necessary group and workspace
in the side bar, then click **Connect** and choose **CLI client**:

<Frame>
  <img />
</Frame>

On the **Connect to Workspace** page, you can find the host name
(`svc-<UUID>-dml.<REGION>.svc.singlestore.com`):

<Frame>
  <img />
</Frame>

### Database name

To obtain the database name, navigate to the necessary group and workspace
in the side bar. You'll see databases on the right:

<Frame>
  <img />
</Frame>

### Password

You have set the password when creating the workspace. If you'd like to reset
the password, navigate to the **Access** tab within your workspace.

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
not be used in pre-aggregations when using SingleStore as a source
database.

## Pre-Aggregation Build Strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Simple        |              ✅             |      ✅      |
| Batching      |              -             |      -      |
| Export Bucket |              -             |      -      |

By default, SingleStore uses a [simple][self-preaggs-simple] strategy
to build pre-aggregations.

### Simple

No extra configuration is required to configure simple pre-aggregation builds
for SingleStore.

### Batching

SingleStore does not support batching.

### Export Bucket

SingleStore does not support export buckets.

[link-singlestore]: https://www.singlestore.com

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[self-preaggs-simple]: #simple


# Snowflake
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/snowflake

Snowflake is a popular cloud-based data platform.

[Snowflake][snowflake] is a popular cloud-based data platform.

## Prerequisites

<Info>
  In order to connect Cube to Snowflake, you need to grant certain permissions to the Snowflake role
  used by Cube. **Read-only access is sufficient to query data.** Cube requires the role to have
  `USAGE` on the warehouse, databases, and schemas, and `SELECT` on tables. An example configuration:

  ```sql theme={"dark"}
  GRANT USAGE ON WAREHOUSE MY_WAREHOUSE TO ROLE XYZ;
  GRANT USAGE ON DATABASE ABC TO ROLE XYZ;
  GRANT USAGE ON ALL SCHEMAS IN DATABASE ABC TO ROLE XYZ;
  GRANT USAGE ON FUTURE SCHEMAS IN DATABASE ABC TO ROLE XYZ;
  GRANT SELECT ON ALL TABLES IN DATABASE ABC TO ROLE XYZ;
  GRANT SELECT ON FUTURE TABLES IN DATABASE ABC TO ROLE XYZ;
  ```

  Write access is only needed for [pre-aggregations](#pre-aggregation-build-strategies) built inside
  Snowflake with the default [batching](#batching) strategy (`CREATE TABLE` on the pre-aggregations
  schema). The [export bucket](#export-bucket) strategy writes to the bucket, not the source.
</Info>

* [Account/Server URL][snowflake-docs-account-id] for Snowflake.
* User name and password or an RSA private key for the Snowflake account.
  In Cube Cloud, you can authenticate with [OIDC workload
  identity][ref-oidc-overview] instead — the same role grants apply to the
  mapped service user.
* Optionally, the warehouse name, the user role, and the database name.

## Setup

<Warning>
  If you're having Network error and Snowflake can't be reached please make sure you tried
  [format 2 for an account id][snowflake-format-2].
</Warning>

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=snowflake
CUBEJS_DB_SNOWFLAKE_ACCOUNT=XXXXXXXXX.us-east-1
CUBEJS_DB_SNOWFLAKE_WAREHOUSE=MY_SNOWFLAKE_WAREHOUSE
CUBEJS_DB_NAME=my_snowflake_database
CUBEJS_DB_USER=snowflake_user
CUBEJS_DB_PASS=**********
```

### Cube Cloud

<Info>
  In some cases you'll need to allow connections from your Cube Cloud deployment
  IP address to your database. You can copy the IP address from either the
  Database Setup step in deployment creation, or from **Settings →
  Configuration** in your deployment.
</Info>

The following fields are required when creating a Snowflake connection:

<Frame>
  <img alt="Cube Cloud Snowflake Configuration Screen" />
</Frame>

#### OIDC workload identity

Instead of a password or key pair, Cube Cloud deployments can authenticate
to Snowflake with [OIDC workload identity][ref-oidc-overview]: a Snowflake
External OAuth integration trusts Cube's OIDC issuer, and the driver
presents a short-lived Cube-minted JWT — no long-lived secrets to
provision or rotate. Snowflake validates each connection's token against
your tenant's public JWKS, maps the token's `sub` claim to a Snowflake
user, and authorizes the session role through the token's `scp` claim.

Start with the [OIDC overview][ref-oidc-overview] for the concepts (issuer,
token configs, custom claims, target env var) and to enable OIDC for your
tenant, then:

<Steps>
  <Step title="Create the token config">
    In **Admin → OIDC**, click **Add Config** and create a config with:

    | Field                    | Value                                                                                                               |
    | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
    | **Audience Type**        | `Custom`                                                                                                            |
    | **Name**                 | `snowflake`                                                                                                         |
    | **Custom Audience**      | `https://<account-identifier>.snowflakecomputing.com`                                                               |
    | **Subject Claim Format** | Keep the default, or pick a richer template — the rendered `sub` must match the Snowflake user's `LOGIN_NAME` below |
    | **Custom Claims**        | Claim `scp` with value `session:role-any`                                                                           |
    | **Target Env Var**       | `CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH`                                                                              |

    <Frame>
      <img alt="Edit OIDC Token Config dialog in Cube Cloud for Snowflake: Custom audience type, the Snowflake account URL as the custom audience, a Target Env Var of CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH, and a custom claim scp set to session:role-any." />
    </Frame>

    The `scp` claim is the part that's easy to miss: Snowflake grants
    session roles **exclusively** through it — a token without `scp`
    authenticates but fails role authorization. `session:role-any` lets the
    driver request any role granted to the mapped user; to pin the role
    inside the token instead, use `session:role:<role-name>` and
    `EXTERNAL_OAUTH_ANY_ROLE_MODE = 'DISABLE'` below. The **Target Env Var**
    is how the driver finds the token: Cube sets that env var to the token
    file path in every execution context (deployed pods, dev mode, and test
    connection each keep the file in a different place), so the path is
    never written by hand.
  </Step>

  <Step title="Create the External OAuth security integration">
    In a Snowflake worksheet, as `ACCOUNTADMIN`:

    ```sql theme={"dark"}
    CREATE SECURITY INTEGRATION CUBE_CLOUD_EXTERNAL_OAUTH
      TYPE = EXTERNAL_OAUTH
      ENABLED = TRUE
      EXTERNAL_OAUTH_TYPE = CUSTOM
      EXTERNAL_OAUTH_ISSUER = 'https://<tenant-name>.cubecloud.dev'
      EXTERNAL_OAUTH_JWS_KEYS_URL = 'https://<tenant-name>.cubecloud.dev/.well-known/jwks.json'
      EXTERNAL_OAUTH_AUDIENCE_LIST = ('https://<account-identifier>.snowflakecomputing.com')
      EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = 'sub'
      EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'LOGIN_NAME'
      EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE';
    ```

    The issuer and audience must match the token config exactly. Snowflake
    fetches the JWKS from your tenant's public endpoint, so no key material
    changes hands.
  </Step>

  <Step title="Create the service user and role">
    The integration maps the token's `sub` claim to a Snowflake user via
    `LOGIN_NAME`. With the default subject claim format the rendered `sub`
    is `cube:deployment:<deployment-id>` — the deployment ID is the number
    in your deployment's console URL. If you chose a different template,
    use the token-config dialog's live preview to see the exact rendered
    value.

    ```sql theme={"dark"}
    CREATE ROLE CUBE_ROLE;

    CREATE USER CUBE_SVC
      TYPE = SERVICE
      LOGIN_NAME = 'cube:deployment:<deployment-id>'
      DEFAULT_ROLE = CUBE_ROLE
      DEFAULT_WAREHOUSE = <warehouse>;

    GRANT ROLE CUBE_ROLE TO USER CUBE_SVC;
    GRANT USAGE ON WAREHOUSE <warehouse> TO ROLE CUBE_ROLE;

    -- Grant the role read access to the data Cube serves, e.g.:
    GRANT USAGE ON DATABASE <database> TO ROLE CUBE_ROLE;
    GRANT USAGE ON ALL SCHEMAS IN DATABASE <database> TO ROLE CUBE_ROLE;
    GRANT SELECT ON ALL TABLES IN DATABASE <database> TO ROLE CUBE_ROLE;
    ```

    `TYPE = SERVICE` blocks password logins for this user entirely — it
    can only authenticate through the federation.
  </Step>

  <Step title="Configure the deployment">
    Set the `OAUTH` authenticator and omit `CUBEJS_DB_USER` /
    `CUBEJS_DB_PASS`:

    ```dotenv theme={"dark"}
    CUBEJS_DB_TYPE=snowflake
    CUBEJS_DB_SNOWFLAKE_ACCOUNT=<account-identifier>
    CUBEJS_DB_SNOWFLAKE_WAREHOUSE=<warehouse>
    CUBEJS_DB_NAME=<database>
    CUBEJS_DB_SNOWFLAKE_ROLE=CUBE_ROLE
    CUBEJS_DB_SNOWFLAKE_AUTHENTICATOR=OAUTH
    ```

    `CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH` is **not** set here — Cube
    populates it automatically thanks to the **Target Env Var** from the
    token config. The driver re-reads the file on every new connection, so
    the broker's automatic refresh is picked up without restarts.
  </Step>
</Steps>

To verify, run any query against the Snowflake data source. On the
Snowflake side, a successful federation shows up in the login history with
`OAUTH_ACCESS_TOKEN` as the authentication factor:

```sql theme={"dark"}
SELECT event_timestamp, user_name, first_authentication_factor, is_success
FROM TABLE(SNOWFLAKE.INFORMATION_SCHEMA.LOGIN_HISTORY_BY_USER(USER_NAME => 'CUBE_SVC'))
ORDER BY event_timestamp DESC;
```

Common failure modes:

| Error                                                                    | Cause                                                                                                                                      |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `Invalid OAuth access token`                                             | Issuer or audience mismatch between the token config and the security integration, or the JWKS URL is unreachable.                         |
| `The role … is not listed in the Access Token or was filtered`           | The `scp` custom claim is missing from the token config, or the role isn't granted to the mapped user.                                     |
| `User … not found` / mapping errors                                      | The rendered `sub` doesn't match the Snowflake user's `LOGIN_NAME` — compare against the dialog's live preview.                            |
| `File … provided by CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH does not exist` | The **Target Env Var** isn't set on the token config (or a stale hand-written path is configured), or the deployment is still starting up. |

Cube Cloud also supports connecting to data sources within private VPCs
if [single-tenant infrastructure][ref-dedicated-infra] is used. Check out the
[VPC connectivity guide][ref-cloud-conf-vpc] for details.

### Query tagging

Set a [query tag][snowflake-docs-query-tag] on the connection so that queries
Cube sends to Snowflake are labeled in `QUERY_HISTORY`. There's no environment
variable for this; set `queryTag` from a custom [`driverFactory`][ref-driver-factory]
instead of returning a plain options object:

```javascript theme={"dark"}
const SnowflakeDriver = require('@cubejs-backend/snowflake-driver');

module.exports = {
  driverFactory: () =>
    new SnowflakeDriver({
      queryTag: 'cube',
    }),
};
```

The tag is set once per connection, not per query — all queries issued over
that connection carry the same tag.

[ref-dedicated-infra]: /admin/deployment/infrastructure#dedicated-infrastructure

[ref-cloud-conf-vpc]: /admin/deployment/dedicated

## Environment Variables

| Environment Variable                                                                                                                                      | Description                                                                                                                                         | Possible Values                                                        |    Required   |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | :-----------: |
| [`CUBEJS_DB_SNOWFLAKE_ACCOUNT`](/reference/configuration/environment-variables#cubejs_db_snowflake_account)                                               | The Snowflake account identifier to use when connecting to the database                                                                             | [A valid Snowflake account ID][snowflake-docs-account-id]              |       ✅       |
| [`CUBEJS_DB_SNOWFLAKE_REGION`](/reference/configuration/environment-variables#cubejs_db_snowflake_region)                                                 | The Snowflake region to use when connecting to the database                                                                                         | [A valid Snowflake region][snowflake-docs-regions]                     |       ❌       |
| [`CUBEJS_DB_SNOWFLAKE_WAREHOUSE`](/reference/configuration/environment-variables#cubejs_db_snowflake_warehouse)                                           | The Snowflake warehouse to use when connecting to the database                                                                                      | [A valid Snowflake warehouse][snowflake-docs-warehouse] in the account |       ✅       |
| [`CUBEJS_DB_SNOWFLAKE_ROLE`](/reference/configuration/environment-variables#cubejs_db_snowflake_role)                                                     | The Snowflake role to use when connecting to the database                                                                                           | [A valid Snowflake role][snowflake-docs-roles] in the account          |       ❌       |
| [`CUBEJS_DB_SNOWFLAKE_CLIENT_SESSION_KEEP_ALIVE`](/reference/configuration/environment-variables#cubejs_db_snowflake_client_session_keep_alive)           | If `true`, [keep the Snowflake connection alive indefinitely][snowflake-docs-connection-options]                                                    | `true`, `false`                                                        |       ❌       |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)                                                                         | The name of the database to connect to                                                                                                              | A valid database name                                                  |       ✅       |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)                                                                         | The username used to connect to the database                                                                                                        | A valid database username                                              | ✅<sup>1</sup> |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)                                                                         | The password used to connect to the database                                                                                                        | A valid database password                                              | ✅<sup>1</sup> |
| [`CUBEJS_DB_SNOWFLAKE_AUTHENTICATOR`](/reference/configuration/environment-variables#cubejs_db_snowflake_authenticator)                                   | The type of authenticator to use with Snowflake. Use `SNOWFLAKE` with username/password, or `SNOWFLAKE_JWT` with key pairs. Defaults to `SNOWFLAKE` | `SNOWFLAKE`, `SNOWFLAKE_JWT`, `OAUTH`                                  |       ❌       |
| [`CUBEJS_DB_SNOWFLAKE_PRIVATE_KEY`](/reference/configuration/environment-variables#cubejs_db_snowflake_private_key)                                       | The content of the private RSA key                                                                                                                  | Content of the private RSA key (encrypted or not)                      |       ❌       |
| [`CUBEJS_DB_SNOWFLAKE_PRIVATE_KEY_PATH`](/reference/configuration/environment-variables#cubejs_db_snowflake_private_key_path)                             | The path to the private RSA key                                                                                                                     | A valid path to the private RSA key                                    |       ❌       |
| [`CUBEJS_DB_SNOWFLAKE_PRIVATE_KEY_PASS`](/reference/configuration/environment-variables#cubejs_db_snowflake_private_key_pass)                             | The password for the private RSA key. Only required for encrypted keys                                                                              | A valid password for the encrypted private RSA key                     |       ❌       |
| [`CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN`](/reference/configuration/environment-variables#cubejs_db_snowflake_oauth_token)                                       | The OAuth token                                                                                                                                     | A valid OAuth token (string)                                           |       ❌       |
| [`CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH`](/reference/configuration/environment-variables#cubejs_db_snowflake_oauth_token_path)                             | The path to the valid oauth toket file                                                                                                              | A valid path for the oauth token file                                  |       ❌       |
| [`CUBEJS_DB_SNOWFLAKE_HOST`](/reference/configuration/environment-variables#cubejs_db_snowflake_host)                                                     | Host address to which the driver should connect                                                                                                     | A valid hostname                                                       |       ❌       |
| [`CUBEJS_DB_SNOWFLAKE_QUOTED_IDENTIFIERS_IGNORE_CASE`](/reference/configuration/environment-variables#cubejs_db_snowflake_quoted_identifiers_ignore_case) | Whether or not [quoted identifiers should be case insensitive][link-snowflake-quoted-identifiers]. Default is `false`                               | `true`, `false`                                                        |       ❌       |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool)                                                                 | The maximum number of concurrent database connections to pool. Default is `20`                                                                      | A valid number                                                         |       ❌       |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)                                                                 | The number of [concurrent queries][ref-data-source-concurrency] to the data source                                                                  | A valid number                                                         |       ❌       |

<sup>1</sup> Required when using password-based authentication. Not required with `SNOWFLAKE_JWT` (key pair) or with `OAUTH` — including [OIDC workload identity](#oidc-workload-identity) in Cube Cloud, where the driver reads a Cube-minted token from [`CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH`](/reference/configuration/environment-variables#cubejs_db_snowflake_oauth_token_path).

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
be used in pre-aggregations when using Snowflake as a source database. To learn
more about Snowflake's support for approximate aggregate functions, [click
here][snowflake-docs-approx-agg-fns].

## Pre-Aggregation Build Strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Batching      |              ❌             |      ✅      |
| Export Bucket |              ❌             |      ❌      |

By default, Snowflake uses [batching][self-preaggs-batching] to build
pre-aggregations.

### Batching

No extra configuration is required to configure batching for Snowflake.

### Export Bucket

Snowflake supports using both [AWS S3][aws-s3] and [Google Cloud
Storage][google-cloud-storage] for export bucket functionality.

<Info>
  The export bucket strategy unloads with `COPY INTO` directly from the query — no
  temporary tables. The role only needs the read-only grants above plus `USAGE` on
  the storage integration.
</Info>

#### AWS S3

<Info>
  Ensure proper IAM privileges are configured for S3 bucket reads and writes, using either
  storage integration or user credentials for Snowflake and either IAM roles/IRSA or user
  credentials for Cube Store, with mixed configurations supported.
</Info>

Using IAM user credentials for both:

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET_TYPE=s3
CUBEJS_DB_EXPORT_BUCKET=my.bucket.on.s3
CUBEJS_DB_EXPORT_BUCKET_AWS_KEY=<AWS_KEY>
CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET=<AWS_SECRET>
CUBEJS_DB_EXPORT_BUCKET_AWS_REGION=<AWS_REGION>
```

Using a [Storage Integration][snowflake-docs-aws-integration] to write to export buckets and
user credentials to read from Cube Store:

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET_TYPE=s3
CUBEJS_DB_EXPORT_BUCKET=my.bucket.on.s3
CUBEJS_DB_EXPORT_INTEGRATION=aws_int
CUBEJS_DB_EXPORT_BUCKET_AWS_KEY=<AWS_KEY>
CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET=<AWS_SECRET>
CUBEJS_DB_EXPORT_BUCKET_AWS_REGION=<AWS_REGION>
```

Using a Storage Integration to write to export bucket and IAM role/IRSA to read from Cube Store:\*\*

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET_TYPE=s3
CUBEJS_DB_EXPORT_BUCKET=my.bucket.on.s3
CUBEJS_DB_EXPORT_INTEGRATION=aws_int
CUBEJS_DB_EXPORT_BUCKET_AWS_REGION=<AWS_REGION>
```

#### Google Cloud Storage

<Info>
  When using an export bucket, remember to assign the **Storage Object Admin**
  role to your Google Cloud credentials ([`CUBEJS_DB_EXPORT_GCS_CREDENTIALS`](/reference/configuration/environment-variables#cubejs_db_export_gcs_credentials)).
</Info>

Before configuring Cube, an [integration must be created and configured in
Snowflake][snowflake-docs-gcs-integration]. Take note of the integration name
(`gcs_int` from the example link) as you'll need it to configure Cube.

Once the Snowflake integration is set up, configure Cube using the following:

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET=snowflake-export-bucket
CUBEJS_DB_EXPORT_BUCKET_TYPE=gcs
CUBEJS_DB_EXPORT_GCS_CREDENTIALS=<BASE64_ENCODED_SERVICE_CREDENTIALS_JSON>
CUBEJS_DB_EXPORT_INTEGRATION=gcs_int
```

#### Azure

To use Azure Blob Storage as an export bucket, follow [the guide on
using a Snowflake storage integration (Option 1)][snowflake-docs-azure].
Take note of the integration name (`azure_int` from the example link)
as you'll need it to configure Cube.

[Retrieve the storage account access key][azure-bs-docs-get-key] from your Azure
account.

Once the Snowflake integration is set up, configure Cube using the following:

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET_TYPE=azure
CUBEJS_DB_EXPORT_BUCKET=wasbs://my-container@my-storage-account.blob.core.windows.net
CUBEJS_DB_EXPORT_BUCKET_AZURE_KEY=<AZURE_STORAGE_ACCOUNT_ACCESS_KEY>
CUBEJS_DB_EXPORT_INTEGRATION=azure_int
```

## SSL

Cube does not require any additional configuration to enable SSL as Snowflake
connections are made over HTTPS.

[aws-s3]: https://aws.amazon.com/s3/

[google-cloud-storage]: https://cloud.google.com/storage

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[ref-oidc-overview]: /admin/deployment/oidc

[ref-driver-factory]: /reference/configuration/config#driver_factory

[self-preaggs-batching]: #batching

[snowflake]: https://www.snowflake.com/

[snowflake-docs-account-id]: https://docs.snowflake.com/en/user-guide/admin-account-identifier.html

[snowflake-docs-connection-options]: https://docs.snowflake.com/en/developer-guide/node-js/nodejs-driver-options#additional-connection-options

[snowflake-docs-query-tag]: https://docs.snowflake.com/en/developer-guide/node-js/nodejs-driver-options#additional-connection-options

[snowflake-docs-aws-integration]: https://docs.snowflake.com/en/user-guide/data-load-s3-config-storage-integration

[snowflake-docs-gcs-integration]: https://docs.snowflake.com/en/user-guide/data-load-gcs-config.html

[snowflake-docs-regions]: https://docs.snowflake.com/en/user-guide/intro-regions.html

[snowflake-docs-roles]: https://docs.snowflake.com/en/user-guide/security-access-control-overview.html#roles

[snowflake-docs-approx-agg-fns]: https://docs.snowflake.com/en/sql-reference/functions/approx_count_distinct.html

[snowflake-docs-warehouse]: https://docs.snowflake.com/en/user-guide/warehouses.html

[snowflake-format-2]: https://docs.snowflake.com/en/user-guide/admin-account-identifier#format-2-account-locator-in-a-region

[snowflake-docs-azure]: https://docs.snowflake.com/en/user-guide/data-load-azure-config#option-1-configuring-a-snowflake-storage-integration

[azure-bs-docs-get-key]: https://docs.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&tabs=azure-portal#view-account-access-keys

[link-snowflake-quoted-identifiers]: https://docs.snowflake.com/en/sql-reference/identifiers-syntax#double-quoted-identifiers


# SQLite
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/sqlite

The driver for SQLite is community-supported and is not maintained by Cube or the database vendor.

<Warning>
  The driver for SQLite is community-supported and is not maintained by Cube or the database vendor.
</Warning>

## Prerequisites

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=sqlite
CUBEJS_DB_NAME=my_sqlite_database
```

## Environment Variables

| Environment Variable                                                                      | Description                                                                        | Possible Values       | Required |
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------- | :------: |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name)         | The name of the database to connect to                                             | A valid database name |     ✅    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool) | The maximum number of concurrent database connections to pool. Default is `8`      | A valid number        |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency) | The number of [concurrent queries][ref-data-source-concurrency] to the data source | A valid number        |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## SSL

SQLite does not support SSL connections.


# Trino
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/trino

Map Cube to Trino with host credentials plus catalog, schema, SSL, and optional bearer-token variables on the shared Presto driver.

## Prerequisites

* The hostname for the [Trino][trino] database server
* The username/password for the [Trino][trino] database server
* The name of the database to use within the [Trino][trino] database server

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=trino
CUBEJS_DB_HOST=my.trino.host
CUBEJS_DB_USER=trino_user
CUBEJS_DB_PASS=**********
CUBEJS_DB_PRESTO_CATALOG=my_trino_catalog
CUBEJS_DB_SCHEMA=my_trino_schema
```

## Environment Variables

| Environment Variable                                                                                                      | Description                                                                                                     | Possible Values                                                | Required |
| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | :------: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host)                                         | The host URL for a database                                                                                     | A valid database host URL                                      |     ✅    |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port)                                         | The port for the database connection                                                                            | A valid port number                                            |     ❌    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)                                         | The username used to connect to the database                                                                    | A valid database username                                      |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)                                         | The password used to connect to the database                                                                    | A valid database password                                      |     ✅    |
| [`CUBEJS_DB_PRESTO_CATALOG`](/reference/configuration/environment-variables#cubejs_db_presto_catalog)                     | The catalog within Presto to connect to                                                                         | A valid catalog name within a Presto database                  |     ✅    |
| [`CUBEJS_DB_PRESTO_AUTH_TOKEN`](/reference/configuration/environment-variables#cubejs_db_presto_auth_token)               | The authentication token to use when connecting to Presto/Trino. It will be sent in the `Authorization` header. | A valid authentication token                                   |     ❌    |
| [`CUBEJS_DB_SCHEMA`](/reference/configuration/environment-variables#cubejs_db_schema)                                     | The schema within the database to connect to                                                                    | A valid schema name within a Presto database                   |     ✅    |
| [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl)                                           | If `true`, enables SSL encryption for database connections from Cube                                            | `true`, `false`                                                |     ❌    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool)                                 | The maximum number of concurrent database connections to pool. Default is `8`                                   | A valid number                                                 |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency)                                 | The number of [concurrent queries][ref-data-source-concurrency] to the data source                              | A valid number                                                 |     ❌    |
| [`CUBEJS_DB_EXPORT_BUCKET_TYPE`](/reference/configuration/environment-variables#cubejs_db_export_bucket_type)             | The export bucket type for pre-aggregations                                                                     | `s3`, `gcs`                                                    |     ❌    |
| [`CUBEJS_DB_EXPORT_BUCKET`](/reference/configuration/environment-variables#cubejs_db_export_bucket)                       | The export bucket to connect to                                                                                 | A valid bucket URL                                             |     ❌    |
| [`CUBEJS_DB_EXPORT_BUCKET_AWS_KEY`](/reference/configuration/environment-variables#cubejs_db_export_bucket_aws_key)       | The AWS Access Key ID to use for export bucket writes                                                           | A valid AWS Access Key ID                                      |     ❌    |
| [`CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET`](/reference/configuration/environment-variables#cubejs_db_export_bucket_aws_secret) | The AWS Secret Access Key to use for export bucket writes                                                       | A valid AWS Secret Access Key                                  |     ❌    |
| [`CUBEJS_DB_EXPORT_BUCKET_AWS_REGION`](/reference/configuration/environment-variables#cubejs_db_export_bucket_aws_region) | The AWS region to use for export bucket writes                                                                  | A valid AWS region                                             |     ❌    |
| [`CUBEJS_DB_EXPORT_GCS_CREDENTIALS`](/reference/configuration/environment-variables#cubejs_db_export_gcs_credentials)     | A Base64 encoded JSON key file for connecting to Google Cloud Storage                                           | A valid Google Cloud JSON key file, encoded as a Base64 string |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
be used in pre-aggregations when using Trino as a source database. To learn more
about Trino support for approximate aggregate functions, [click
here][trino-docs-approx-agg-fns].

## Pre-Aggregation Build Strategies

<Info>
  To learn more about pre-aggregation build strategies, [head
  here][ref-caching-using-preaggs-build-strats].
</Info>

| Feature       | Works with read-only mode? | Is default? |
| ------------- | :------------------------: | :---------: |
| Simple        |              ✅             |      ✅      |
| Export Bucket |              ❌             |      ❌      |

By default, Trino uses a [simple][self-preaggs-simple] strategy to
build pre-aggregations.

### Simple

No extra configuration is required to configure simple pre-aggregation builds
for Trino.

### Export Bucket

Trino supports using both [AWS S3][aws-s3] and [Google Cloud Storage][google-cloud-storage] for export bucket functionality.

#### AWS S3

<Info>
  Ensure the AWS credentials are correctly configured in IAM to allow reads and
  writes to the export bucket in S3.
</Info>

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET_TYPE=s3
CUBEJS_DB_EXPORT_BUCKET=my.bucket.on.s3
CUBEJS_DB_EXPORT_BUCKET_AWS_KEY=<AWS_KEY>
CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET=<AWS_SECRET>
CUBEJS_DB_EXPORT_BUCKET_AWS_REGION=<AWS_REGION>
```

#### Google Cloud Storage

<Info>
  When using an export bucket, remember to assign the **Storage Object Admin**
  role to your Google Cloud credentials ([`CUBEJS_DB_EXPORT_GCS_CREDENTIALS`](/reference/configuration/environment-variables#cubejs_db_export_gcs_credentials)).
</Info>

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET=gs://trino-export-bucket
CUBEJS_DB_EXPORT_BUCKET_TYPE=gcs
CUBEJS_DB_EXPORT_GCS_CREDENTIALS=<BASE64_ENCODED_SERVICE_CREDENTIALS_JSON>
```

## SSL

To enable SSL-encrypted connections between Cube and Trino, set the
[`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) environment variable to `true`. For more information on how to
configure custom certificates, please check out [Enable SSL Connections to the
Database][ref-recipe-enable-ssl].

## Custom headers

The Trino driver supports forwarding custom HTTP headers (e.g., `X-Trino-Source`,
`X-Trino-Routing-Group`, `X-Trino-Client-Tags`, or any other custom header) on
every request to the Trino coordinator. See the [Trino client
protocol][trino-docs-client-protocol] for the list of headers accepted by Trino.

Custom headers can't be configured via environment variables. Instead, use the
[`driver_factory`](/reference/configuration/config#driver_factory) configuration
option to pass a `headers` object to the driver:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('driver_factory')
  def driver_factory(ctx: dict) -> dict:
    return {
      'type': 'trino',
      'headers': {
        'X-Trino-Source': 'cube',
        'X-Trino-Routing-Group': 'etl',
        'X-Trino-Client-Tags': 'user=alice@example.com'
      }
    }
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    driverFactory: ({ dataSource }) => ({
      type: "trino",
      headers: {
        "X-Trino-Source": "cube",
        "X-Trino-Routing-Group": "etl",
        "X-Trino-Client-Tags": "user=alice@example.com"
      }
    })
  };
  ```
</CodeGroup>

In multitenant deployments, you can use the [security
context](/embedding/authentication/security-context) to pass per-tenant headers, for example
to forward a user token from the API request down to Trino:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('driver_factory')
  def driver_factory(ctx: dict) -> dict:
    security_context = ctx['securityContext']
    return {
      'type': 'trino',
      'headers': {
        'X-Trino-Client-Tags': f"user={security_context['user_id']}",
        'X-Custom-User-Token': security_context['token']
      }
    }
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    driverFactory: ({ securityContext }) => ({
      type: "trino",
      headers: {
        "X-Trino-Client-Tags": `user=${securityContext.user_id}`,
        "X-Custom-User-Token": securityContext.token
      }
    })
  };
  ```
</CodeGroup>

[trino-docs-client-protocol]: https://trino.io/docs/current/develop/client-protocol.html

[aws-s3]: https://aws.amazon.com/s3/

[google-cloud-storage]: https://cloud.google.com/storage

[ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies

[self-preaggs-simple]: #simple

[trino]: https://trino.io/

[trino-docs-approx-agg-fns]: https://trino.io/docs/current/functions/aggregate.html#approximate-aggregate-functions

[ref-recipe-enable-ssl]: /recipes/configuration/using-ssl-connections-to-data-source

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type


# Vertica
Source: https://docs.cube.dev/admin/connect-to-data/data-sources/vertica

OpenText Analytics Database (Vertica) is a columnar database designed for big data analytics.

[OpenText Analytics Database][opentext-adb] (Vertica) is a columnar database
designed for big data analytics.

## Prerequisites

* The hostname for the [Vertica][vertica] database server
* The username/password for the [Vertica][vertica] database server
* The name of the database to use within the [Vertica][vertica] database server

## Setup

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={"dark"}
CUBEJS_DB_TYPE=vertica
CUBEJS_DB_HOST=my.vertica.host
CUBEJS_DB_USER=vertica_user
CUBEJS_DB_PASS=**********
CUBEJS_DB_SCHEMA=my_vertica_schema
```

## Environment Variables

| Environment Variable                                                                      | Description                                                                        | Possible Values                              | Required |
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------- | :------: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host)         | The host URL for a database                                                        | A valid database host URL                    |     ✅    |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port)         | The port for the database connection                                               | A valid port number                          |     ❌    |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user)         | The username used to connect to the database                                       | A valid database username                    |     ✅    |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass)         | The password used to connect to the database                                       | A valid database password                    |     ✅    |
| [`CUBEJS_DB_SCHEMA`](/reference/configuration/environment-variables#cubejs_db_schema)     | The schema within the database to connect to                                       | A valid schema name within a Presto database |     ✅    |
| [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl)           | If `true`, enables SSL encryption for database connections from Cube               | `true`, `false`                              |     ❌    |
| [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool) | The maximum number of concurrent database connections to pool. Default is `8`      | A valid number                               |     ❌    |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency) | The number of [concurrent queries][ref-data-source-concurrency] to the data source | A valid number                               |     ❌    |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## SSL

To enable SSL-encrypted connections between Cube and Verica, set the
[`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) environment variable to `true`. For more information on how to
configure custom certificates, please check out [Enable SSL Connections to the
Database][ref-recipe-enable-ssl].

[opentext-adb]: https://www.opentext.com/products/analytics-database?o=vert

[vertica]: https://www.vertica.com/documentation/vertica/all/

[ref-recipe-enable-ssl]: /recipes/configuration/using-ssl-connections-to-data-source


# Connect to data
Source: https://docs.cube.dev/admin/connect-to-data/index

Connect your data warehouse or database to Cube and configure connection settings.

Connect your data warehouse, database, or query engine to Cube. Once connected,
you can configure multiple data sources, tune concurrency, and set up
multitenancy.

## Getting started

<CardGroup>
  <Card title="Data sources" icon="database" href="/admin/connect-to-data/data-sources">
    Choose and configure a data warehouse, query engine, or other data source.
  </Card>

  <Card title="Multiple data sources" icon="topology-ring-2" href="/admin/connect-to-data/multiple-data-sources">
    Connect to multiple databases so different cubes reference different sources.
  </Card>

  <Card title="Concurrency" icon="progress-bolt" href="/admin/connect-to-data/concurrency">
    Optimize query queue settings and control load on your data sources.
  </Card>
</CardGroup>

## Recipes

<CardGroup>
  <Card title="SSL connections" icon="lock" href="/recipes/configuration/using-ssl-connections-to-data-source">
    Enable TLS to upstream databases with custom CA bundles and client certificates.
  </Card>

  <Card title="Optimizing data source usage" icon="bolt" href="/recipes/configuration/data-store-cost-saving-guide">
    Reduce warehouse spend through pre-aggregation strategy and workload-aware settings.
  </Card>

  <Card title="Custom data source per tenant" icon="server" href="/recipes/configuration/multiple-sources-same-schema">
    Route each tenant to its own database while reusing a single data model.
  </Card>
</CardGroup>


# Connecting to multiple data sources
Source: https://docs.cube.dev/admin/connect-to-data/multiple-data-sources

Manage one or more data source connections per Cube Cloud deployment from a single place.

A Cube Cloud deployment always has a single **default** data source plus,
optionally, one or more **named** data sources. [Cubes](/reference/data-modeling/cube)
reference whichever source they need via the
[`data_source`](/reference/data-modeling/cube#data_source) property.

Manage data sources from your deployment's **Settings → Data Sources** page.

## Adding a data source

Click **+ Add data source**, pick the driver, give the source a short
name (see [Source name rules](#source-name-rules)), and fill in the
connection form — the same form the deployment wizard uses.

Cube Cloud tests the connection before saving; on success it persists the
env vars and restarts the development environment, on failure it surfaces
the driver's error and saves nothing.

## Editing and deleting

Use the **Edit** action on a row to update credentials, or the **Delete**
action to remove a named source. The **default** source can be edited but
not deleted — to remove it, clear the bare `CUBEJS_DB_*` variables from
[**Settings → Environment Variables**][ref-config-ref-env] by hand.

## Source name rules

* Letters, digits, and underscores; must start with a letter.
* `default` is reserved; use the **Use as default** button on the naming
  step instead.
* Flat names (`analytics`, `warehouse`) are safer than names with
  underscores, which can collide with the env-var parser when they end in
  `_db`, `_aws`, or `_jdbc`.

## Using a data source from a cube

Reference a source from the
[`data_source`](/reference/data-modeling/cube#data_source) property using
the name you gave it when you created it:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders_from_other_data_source
      # ...
      data_source: analytics
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders_from_other_data_source`, {
    // ...
    data_source: `analytics`
  })
  ```
</CodeGroup>

Cubes that don't set `data_source` use the default source — there's no
need to write `data_source: default` explicitly, though you can if you
prefer to be explicit.

A single query can also span sources: see [querying across data
sources](/recipes/data-modeling/cross-data-source-queries) for appending rows
from cubes in different databases into one result set.

For multitenancy scenarios where the data source is selected dynamically
per request, see [`driver_factory`](/reference/configuration/config#driver_factory)
and the [multitenancy guide][ref-config-multitenancy].

## Workbooks

Sources show up immediately in
[Workbooks](/docs/explore-analyze/workbooks) — open a
[Source SQL tab](/docs/explore-analyze/workbooks/source-sql-tabs) and they
appear in the data sources sidebar without needing a cube to reference
them first.

## Under the hood

The UI is a friendlier surface over the deployment's environment
variables — inspect or hand-edit them from
[**Settings → Environment Variables**][ref-config-ref-env] at any time.

The default source uses bare `CUBEJS_DB_*` variables; each named source
uses a `CUBEJS_DS_<NAME>_*` prefix. `CUBEJS_DATASOURCES` is auto-maintained
whenever at least one named source exists, with `default` first and named
entries lowercased:

```dotenv theme={"dark"}
CUBEJS_DATASOURCES=default,analytics
CUBEJS_DB_TYPE=postgres
CUBEJS_DB_HOST=localhost
CUBEJS_DS_ANALYTICS_DB_TYPE=postgres
CUBEJS_DS_ANALYTICS_DB_HOST=remotehost
```

For the full list of variables that support decoration, see the
[environment variables reference][ref-config-ref-env].

Each source can also build and store its pre-aggregations on a dedicated connection
using the `CUBEJS_DS_<NAME>_PRE_AGGREGATIONS_DB_*` variables. See [pre-aggregation data
source][ref-preagg-data-source] for details.

[ref-config-ref-env]: /reference/configuration/environment-variables

[ref-preagg-data-source]: /docs/pre-aggregations/refreshing-pre-aggregations#pre-aggregation-data-source

[ref-config-multitenancy]: /embedding/multitenancy#multitenancy-multitenancy-vs-multiple-data-sources


# Set up per-user OAuth
Source: https://docs.cube.dev/admin/connect-to-data/oauth-authentication

Configure Cube to authenticate each user with their own OAuth token, falling back to a service account for liveness checks.

<Note>
  This feature is in beta. Reach out to your account manager to have it
  enabled for your Cube Cloud deployment.
</Note>

## Use case

You want each user's queries to run under their own database identity
using OAuth tokens managed by Cube Cloud. When a user's token is
unavailable or expired, Cube falls back to a service account so that
connectivity checks and background operations still work.

This pattern applies to any data source that supports OAuth, including
[Databricks][ref-databricks-jdbc] and [Snowflake][ref-snowflake]. The
examples below use Databricks; switch the `userCredentials` key and
driver options for any other OAuth-capable data source.

Because every user connects with different credentials, you also need
per-user query orchestrator state. Without this, one user's cached
connection could leak to another.

## Prerequisites

* A [Cube Cloud][ref-cube-cloud] deployment connected to an
  OAuth-capable data source
* OAuth configured in your data source so that Cube Cloud can
  obtain per-user tokens (via the **User Credentials** feature)
* A service account credential (token or password) stored as an
  environment variable for fallback connectivity

<Warning>
  The service account credential is used only as a fallback for Cube's
  internal liveness checks and background operations. Grant it the minimum
  permissions necessary — ideally read-only access to the required schemas —
  to limit exposure if the credential is compromised.
</Warning>

## Set up the OAuth app

Before configuring Cube to use per-user OAuth, register your data
source as an OAuth app in Cube Cloud:

<Steps>
  <Step title="Open the OAuth apps settings">
    In Cube Cloud, go to **Admin → Integrations → OAuth apps** and click
    **Add**.

    <Frame>
      <img alt="Admin Integrations page showing the OAuth apps section with the Add button" />
    </Frame>
  </Step>

  <Step title="Fill out the OAuth app details">
    Provide the OAuth app metadata from your data source: **Name**,
    **Auth URL**, **Token URL**, **Client ID**, **Client Secret**, and any
    required **Scopes**. Copy the **Redirect URI** shown in this form and
    register it with your data source's OAuth provider, then click
    **Create**.

    <Frame>
      <img alt="New OAuth app form with fields for Name, Auth URL, Token URL, Client ID, Client Secret, Scopes, and Redirect URI" />
    </Frame>
  </Step>

  <Step title="Authorize the app">
    Open the sidebar and go to **Connected apps**. Find your OAuth app
    and click **Authorize** to generate an access token.

    You'll need to repeat this step whenever the token expires.

    <Frame>
      <img alt="Connected apps page showing the OAuth integration with an Authorize action" />
    </Frame>
  </Step>
</Steps>

## Configuration

The configuration uses two options from the
[configuration file reference][ref-config]:

* [`driver_factory`][ref-driver-factory] — dynamically selects the
  authentication credential per request
* [`context_to_orchestrator_id`][ref-context-to-orchestrator-id] — gives
  each user their own query orchestrator instance (database connections,
  execution queues, pre-aggregation table caches)

### Environment variables

Set the environment variables for your data source. The examples below
show Databricks and Snowflake; adapt them to your specific setup.

<Tabs>
  <Tab title="Databricks">
    ```dotenv theme={"dark"}
    CUBEJS_DB_TYPE=databricks-jdbc
    CUBEJS_DB_DATABRICKS_URL=jdbc:databricks://dbc-XXXXXXX-XXXX.cloud.databricks.com:443/default;transportMode=http;ssl=1;httpPath=sql/protocolv1/o/XXXXX/XXXXX;AuthMech=3;UID=token
    CUBEJS_DB_DATABRICKS_TOKEN=dapi_service_account_token
    CUBEJS_DB_DATABRICKS_ACCEPT_POLICY=true
    # Optional: specify a catalog
    CUBEJS_DB_DATABRICKS_CATALOG=my_catalog
    ```
  </Tab>

  <Tab title="Snowflake">
    ```dotenv theme={"dark"}
    CUBEJS_DB_TYPE=snowflake
    CUBEJS_DB_SNOWFLAKE_ACCOUNT=XXXXXXXXX.us-east-1
    CUBEJS_DB_SNOWFLAKE_WAREHOUSE=MY_SNOWFLAKE_WAREHOUSE
    CUBEJS_DB_NAME=my_snowflake_database
    CUBEJS_DB_USER=service_account_user
    CUBEJS_DB_PASS=service_account_password
    CUBEJS_DB_SNOWFLAKE_ROLE=MY_ROLE
    ```
  </Tab>
</Tabs>

### Configuration file

The examples below use Databricks. To target a different data source,
swap `userCredentials.databricks` for the matching key (for example,
`userCredentials.snowflake`) and update the `driver_factory` return
value with the correct `type` and driver-specific options. See the
[data sources reference][ref-data-sources] for available drivers.

<Tabs>
  <Tab title="Python">
    ```python cube.py theme={"dark"}
    from cube import config
    import os


    @config("driver_factory")
    def driver_factory(ctx: dict) -> dict:
        # Extract the Cube Cloud security context, which contains
        # per-user OAuth credentials when available.
        # For other data sources, swap "databricks" for "snowflake", etc.
        databricks_creds = (
            ctx
            .get("securityContext", {})
            .get("cubeCloud", {})
            .get("userCredentials", {})
            .get("databricks", {})
        )

        # Only use the OAuth token when the credential status is "active".
        # An expired or revoked token falls back to the service account.
        oauth_token = (
            databricks_creds.get("accessToken")
            if databricks_creds.get("status") == "active"
            else None
        )

        return {
            "type": "databricks-jdbc",
            "url": os.environ["CUBEJS_DB_DATABRICKS_URL"],
            # Prefer the user's OAuth token; fall back to the service account token
            "token": oauth_token or os.environ["CUBEJS_DB_DATABRICKS_TOKEN"],
            "acceptPolicy": True,
            "catalog": os.environ.get("CUBEJS_DB_DATABRICKS_CATALOG"),
        }


    @config("context_to_orchestrator_id")
    def context_to_orchestrator_id(ctx: dict) -> str:
        # Give each user a separate orchestrator instance (DB connections,
        # execution queues, pre-aggregation caches)
        username = (
            ctx
            .get("securityContext", {})
            .get("cubeCloud", {})
            .get("username", "default")
        )
        return f"CUBE_APP_{username}"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript cube.js theme={"dark"}
    module.exports = {
      driverFactory: ({ securityContext }) => {
        // Extract the Cube Cloud security context, which contains
        // per-user OAuth credentials when available.
        // For other data sources, swap `databricks` for `snowflake`, etc.
        const databricksCreds =
          securityContext?.cubeCloud?.userCredentials?.databricks ?? {};

        // Only use the OAuth token when the credential status is "active".
        // An expired or revoked token falls back to the service account.
        const oauthToken =
          databricksCreds.status === "active"
            ? databricksCreds.accessToken
            : null;

        return {
          type: "databricks-jdbc",
          url: process.env.CUBEJS_DB_DATABRICKS_URL,
          // Prefer the user's OAuth token; fall back to the service account token
          token: oauthToken || process.env.CUBEJS_DB_DATABRICKS_TOKEN,
          acceptPolicy: true,
          catalog: process.env.CUBEJS_DB_DATABRICKS_CATALOG,
        };
      },

      // Give each user a separate orchestrator instance (DB connections,
      // execution queues, pre-aggregation caches)
      contextToOrchestratorId: ({ securityContext }) => {
        const username = securityContext?.cubeCloud?.username ?? "default";
        return `CUBE_APP_${username}`;
      },
    };
    ```
  </Tab>
</Tabs>

## How it works

1. **User makes a request** — Cube Cloud attaches the user's OAuth
   credentials to `securityContext.cubeCloud.userCredentials.<data_source>`
   (for example, `.databricks` or `.snowflake`).

2. **`driver_factory` resolves the credential** — If the credential status
   is `active`, the user's OAuth token is used. Otherwise, Cube falls back
   to the service account credential stored in environment variables.

3. **Per-user orchestrator** —
   [`context_to_orchestrator_id`][ref-context-to-orchestrator-id] returns
   a unique key per username, so each user gets their own database
   connection pool, execution queues, and pre-aggregation table cache.
   Without this, Cube would share a single cached connection across all
   users, causing one user's credentials to be reused for another user's
   queries.

[ref-config]: /reference/configuration/config

[ref-driver-factory]: /reference/configuration/config#driver_factory

[ref-context-to-orchestrator-id]: /reference/configuration/config#context_to_orchestrator_id

[ref-databricks-jdbc]: /admin/connect-to-data/data-sources/databricks-jdbc

[ref-snowflake]: /admin/connect-to-data/data-sources/snowflake

[ref-data-sources]: /admin/connect-to-data/data-sources

[ref-cube-cloud]: /docs/introduction


# App theme
Source: https://docs.cube.dev/admin/customization/app-theme

Brand Cube with your own colors, logo, and fonts — applied to embedded surfaces and, optionally, across the entire Cube Cloud console.

The **app theme** controls the brand appearance of Cube — the accent color, background and text colors, logo, and fonts. You pick a handful of colors per color scheme and Cube generates a complete, accessible light and dark palette from them.

By default the app theme brands [embedded surfaces](/embedding/iframe/creator-mode) (Creator Mode, published dashboards, and embedded chat) so they match your product. You can also turn it on for the entire Cube Cloud console so everyone in your account sees your branding.

## Requirements

Configuring the app theme requires the **Admin** [role][ref-roles]. The theme is account-wide: there is a single app theme per account, and changes apply to every deployment in it.

[ref-roles]: /admin/users-and-permissions/roles-and-permissions

<Note>
  The app theme is distinct from **[dashboard themes](/admin/customization/dashboard-themes)**, which style individual dashboards (backgrounds, widget cards, borders). The app theme sets your account's overall brand; dashboard themes are a narrower override.
</Note>

## What you can customize

The app theme is configured for two color schemes — **Light** and **Dark** — plus shared **Typography**.

| Section              | What it controls                                                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Accent color**     | Your primary brand color. Cube derives the full palette (buttons, links, active states, highlights) from its hue and saturation.     |
| **Background color** | The main surface and page background.                                                                                                |
| **Foreground color** | The primary text color.                                                                                                              |
| **Contrast**         | A 0–100 control (45 is neutral) for how strongly the generated palette separates surfaces and text. Higher values increase contrast. |
| **Logo**             | The mark shown in the navigation header.                                                                                             |
| **Typography**       | The web fonts used for body and heading text (shared across both schemes).                                                           |

<Tip>
  You only choose the accent, background, and foreground colors — Cube generates every other token (borders, muted text, success/danger states, hover and active variants) for both light and dark mode, keeping contrast accessible automatically.
</Tip>

## Configure the theme

Go to **Admin → Customization → App Theme**. The page has a **Light theme** and a **Dark theme** editor on the left and a live preview on the right.

<Steps>
  <Step title="Set the colors">
    For each scheme, pick the **Accent**, **Background**, and **Foreground** colors and adjust the **Contrast** slider. The preview updates as you edit.
  </Step>

  <Step title="Add your logo">
    Paste an HTTPS URL to your logo image (see [Logo](#logo) below).
  </Step>

  <Step title="Configure fonts">
    Add one or more web fonts and choose which to use for body and heading text (see [Fonts](#fonts) below).
  </Step>

  <Step title="Preview">
    Use the **Light / Auto / Dark** toggle above the preview to check both schemes. **Auto** follows your current OS/app appearance.
  </Step>

  <Step title="Save">
    Click **Save**. To start over, use **Restore defaults** (and **Revert** to undo a restore before saving).
  </Step>
</Steps>

### Logo

The logo is referenced by URL and must be served over **HTTPS**. Use a small, square mark (around **24×24**) in **PNG**, **SVG**, or **JPG** format — it renders in the navigation header. If you set a logo only for the light scheme, it is reused in dark mode unless you set a dark-mode logo as well.

### Fonts

Fonts are shared across the light and dark schemes. You register one or more fonts, then choose which font and weight to use for body and heading text.

You can add a font in two ways:

* **A direct font file** — an HTTPS URL ending in a font file: `woff2`, `woff`, `ttf` (TrueType), or `otf` (OpenType).
* **A CSS stylesheet** — an HTTPS URL to a CSS file containing `@font-face` declarations (for example, a Google Fonts stylesheet link). A single stylesheet can register multiple font families at once.

<Steps>
  <Step title="Add a font">
    In the **Typography** section, paste the font or stylesheet URL and add it. Cube validates the URL and reads the font's metadata; a stylesheet may register several families in one step.
  </Step>

  <Step title="Assign body and heading fonts">
    Choose a font from your registry for **Body** and for **Heading** text, and set the **font weight** for each.
  </Step>
</Steps>

<Warning>
  Font URLs must be HTTPS and publicly reachable. Cube fetches the font to validate it; private, non-HTTPS, or oversized files are rejected.
</Warning>

## Where the theme is applied

### Embedded surfaces

When configured, the app theme automatically brands your [embedded](/embedding/iframe/customization) experiences — the [Creator Mode](/embedding/iframe/creator-mode) app, published dashboards, and embedded chat — including overlays such as dialogs and menus. No extra configuration is required beyond saving the theme.

### Across Cube Cloud

Turn on **Apply across Cube Cloud** (the switch at the top of the App Theme page) to apply the same theme to the **entire authenticated Cube Cloud console** — the sidebar, pages, and overlays — for every user in the account.

* It takes effect immediately for all users on their next load.
* It respects each user's light/dark preference, switching schemes accordingly.
* Unauthenticated pages (such as sign-in) keep Cube's default appearance.

Turn the switch off to return the console to Cube's default look while keeping your embedded surfaces branded.


# Chart palettes
Source: https://docs.cube.dev/admin/customization/chart-palettes

Create custom color palettes so charts across your account stay consistent and on-brand.

Chart palettes control the colors used in chart visualizations across [workbooks][ref-workbooks] and [dashboards][ref-dashboards]. Cube ships with a set of built-in palettes, and you can also define your own custom palettes — for example, to match your company brand — and reuse them on any chart in the account.

Custom palettes are managed centrally and are available across every deployment in the account.

[ref-workbooks]: /docs/explore-analyze/workbooks

[ref-dashboards]: /docs/explore-analyze/dashboards

## Requirements

Custom chart palettes are managed under the **Manage chart palettes** permission. The built-in **Admin** [role][ref-roles] has this permission by default; for other users, grant the **Manage chart palettes** global permission via a [custom role][ref-custom-roles].

[ref-roles]: /admin/users-and-permissions/roles-and-permissions

[ref-custom-roles]: /admin/users-and-permissions/custom-roles

## Browse palettes

Go to **Admin → Customization → Chart Palettes** to see every palette available in your account. The list combines:

* **Built-in palettes** shipped with Cube — these can be used in charts but cannot be edited or deleted.
* **Custom palettes** created in your account — these can be edited, renamed, and deleted.

Each row shows the palette name and a preview of its colors.

## Create a custom palette

1. Go to **Admin → Customization → Chart Palettes**.
2. Click **Add palette**.
3. Give the palette a **Name** and provide its colors as a comma-separated list of hex codes (for example, `#1F77B4, #FF7F0E, #2CA02C`).
4. Click **Save**.

The new palette appears in the list immediately and becomes selectable in the chart styling controls.

## Edit a custom palette

1. Go to **Admin → Customization → Chart Palettes**.
2. Click the row action on the palette you want to change and select **Edit**.
3. Update the name or colors and click **Save**.

Existing charts that use the palette pick up the new colors automatically.

## Delete a custom palette

1. Go to **Admin → Customization → Chart Palettes**.
2. Click the row action on the palette you want to remove and select **Delete**.

Charts that were using the deleted palette fall back to the built-in **Default** palette.

## Apply a palette to a chart

Palettes are applied per chart from the chart's styling controls:

1. Open a workbook and select a chart.
2. Open the **Style** panel for the chart.
3. Use the **Palette** dropdown to pick a built-in or custom palette.

The dropdown shows palettes that match the chart's color encoding:

* **Discrete** palettes appear when the color encoding is categorical (for example, color by `status` or `category`).
* **Continuous** palettes appear when the color encoding is quantitative or temporal (for example, color by `total_sale_price` or `created_at`).

If no palette is explicitly selected, charts use the built-in **Default** palette.


# Dashboard themes
Source: https://docs.cube.dev/admin/customization/dashboard-themes

Style dashboards with reusable themes that control backgrounds, widget cards, borders, titles, and text.

Dashboard themes control the look and feel of [dashboards][ref-dashboards] — including the dashboard background, widget cards, borders, titles, and text. Cube ships with a built-in theme, and you can also create your own custom themes and reuse them across dashboards in the account.

Themes are designed and saved from the dashboard builder, then managed centrally in the admin area.

[ref-dashboards]: /docs/explore-analyze/dashboards

## Requirements

Custom dashboard themes are managed under the **Manage dashboard themes** permission. The built-in **Admin** [role][ref-roles] has this permission by default; for other users, grant the **Manage dashboard themes** global permission via a [custom role][ref-custom-roles].

[ref-roles]: /admin/users-and-permissions/roles-and-permissions

[ref-custom-roles]: /admin/users-and-permissions/custom-roles

## What you can theme

A theme defines styles for the following parts of a dashboard:

| Section       | Properties                                            |
| ------------- | ----------------------------------------------------- |
| **Dashboard** | Background color, padding                             |
| **Widgets**   | Card background color, padding                        |
| **Borders**   | Color, width, style, corner radius                    |
| **Titles**    | Color, font size, font weight, font family            |
| **Text**      | Color, secondary color, font family, code font family |

The built-in **Cube** theme provides Cube's default look and is always available. It can be selected on dashboards but cannot be edited, renamed, or deleted.

## Browse themes

Go to **Admin → Customization → Dashboard Themes** to see every theme available in your account. The list combines the built-in **Cube** theme and any custom themes saved from dashboards.

For each custom theme you can:

* **Rename** the theme.
* **Delete** the theme.

Themes are created from the dashboard builder rather than from this page — see [Create a custom theme](#create-a-custom-theme) below.

## Create a custom theme

Custom themes are saved from the dashboard builder's **Styling** tab.

<Steps>
  <Step title="Open a dashboard">
    Open a dashboard in a workbook and switch to the dashboard builder.
  </Step>

  <Step title="Open dashboard options">
    Click the dashboard options button and switch to the **Styling** tab.
  </Step>

  <Step title="Edit styling">
    Adjust the dashboard background, widget card styles, borders, titles, and text until the dashboard looks the way you want.
  </Step>

  <Step title="Save as new theme">
    Click **Save as new**, give the theme a name, and confirm.
  </Step>
</Steps>

The new theme appears in the **Admin → Customization → Dashboard Themes** list and becomes selectable in the **Styling** tab on every other dashboard in the account.

## Apply a theme to a dashboard

1. Open the dashboard in the dashboard builder.
2. Open dashboard options and switch to the **Styling** tab.
3. Pick a theme from the theme picker.

You can also tweak any styling properties on top of the selected theme — those changes are stored as overrides on the dashboard and do not modify the underlying theme.

## Update a saved theme

After tweaking styling on a dashboard that uses a custom theme, you can push those changes back into the theme so every other dashboard using it picks them up.

1. From the dashboard's **Styling** tab, make your changes.
2. Click **Save** to write the current effective styles back into the theme.

<Warning>
  Saving a theme updates **every dashboard** that uses it. Already-published dashboard snapshots keep their previous styling until they are re-published.
</Warning>

## Delete a custom theme

1. Go to **Admin → Customization → Dashboard Themes**.
2. Click the row action on the theme you want to remove and select **Delete**.

Dashboards that were using the deleted theme revert to the built-in **Cube** theme.

## Theme scope

* **Themes** are defined once and shared across all deployments in the account.
* **Theme assignment** is per dashboard — different dashboards in the same workbook can use different themes.
* New dashboards use the built-in **Cube** theme until you assign a custom theme.


# Continuous deployment
Source: https://docs.cube.dev/admin/deployment/continuous-deployment

This guide covers features and tools you can use to deploy your Cube project to Cube Cloud.

Each Cube deployment is configured to use one of the following deploy modes:

* **Deploy with Git** — Cube Cloud builds and deploys your project from a Git
  repository. Use this mode when you want commits to the production branch
  (or merges performed from the Cube Cloud UI) to automatically trigger a
  production build.
* **Deploy with CLI** — you push your project to Cube Cloud from your local
  machine or CI/CD pipeline by running the `cubejs-cli deploy` command. The
  production branch is **never** built automatically; it only changes when
  somebody explicitly runs `cubejs-cli deploy`.

You can change the deploy mode at any time on the **Build & Deploy** tab of
the **Settings** screen.

Independently of the deploy mode, you can [connect a GitHub
repository](#deploy-with-github) to the deployment. Non-production branches
pushed to GitHub are then auto-synced into Cube Cloud and reflected in their
[staging environments][ref-environments-staging]. The production branch
follows the deploy mode: it auto-deploys in Git mode and stays manual in CLI
mode.

## Deploy with Git

Continuous deployment works by connecting a Git repository to a Cube Cloud
deployment and keeping the two in sync.

First, go to the **Build & Deploy** tab on the **Settings** screen and
select **Deploy with Git** under **Deploy with**. From the same screen you
can pick the production branch, connect a Git repository, and copy the
commands that set up Cube Cloud as a Git remote:

<Frame>
  <img alt="Build & Deploy settings tab with Deploy with Git selected" />
</Frame>

Click **Generate Git credentials** to obtain Git credentials. The instructions
to set up Cube Cloud as a Git remote are also available on the same screen:

```bash theme={"dark"}
git config credential.helper store
git remote add cubecloud <YOUR-CUBE-CLOUD-GIT-URL>
git push cubecloud master
```

## Deploy with GitHub

You can connect a GitHub repository to your deployment by clicking the
**Connect to GitHub** button on the **Build & Deploy** tab of the
**Settings** screen and selecting your repository. This works with both the
**Deploy with Git** and **Deploy with CLI** deploy modes.

<Warning>
  If your organization uses SAML SSO for GitHub authentication, make sure to start an active SAML
  session prior to connecting to your GitHub account from Cube.
</Warning>

What happens after connecting depends on the deploy mode:

* In **Deploy with Git** mode, Cube Cloud will automatically deploy from the
  specified production branch (`master` by default) on every push, and also
  sync non-production branches into their staging environments.
* In **Deploy with CLI** mode, only non-production branches are auto-synced
  into their staging environments. See [Connecting GitHub on a CLI
  deployment](#connecting-github-on-a-cli-deployment) for details.

## Deploy with CLI

When a deployment is configured to deploy with CLI, production builds are
**only** triggered when you (or your CI/CD pipeline) push the project to
Cube Cloud by running:

```bash theme={"dark"}
npx cubejs-cli deploy --token <TOKEN>
```

You can find your Deploy Token, along with copy-paste instructions and an
example CI/CD pipeline config (such as a GitHub Actions workflow), on the
**Build & Deploy** tab of the **Settings** screen. The same screen lets you
regenerate the token if it needs to be rotated.

<Frame>
  <img alt="Build & Deploy settings tab with Deploy with CLI selected, showing the Deploy Token and a sample GitHub Actions workflow" />
</Frame>

<Note>
  Cube Cloud still maintains an internal Git repository for the deployment so
  that features such as [development mode][ref-dev-mode] and branching can work.
  This internal repository is overwritten on every successful CLI deploy — only
  the contents of your most recent `cubejs-cli deploy` invocation are used to
  build and run production.
</Note>

### Connecting GitHub on a CLI deployment

You can still [connect a GitHub repository](#deploy-with-github) to a CLI
deployment. When you do:

* Pushes to **non-production branches** (typically feature branches) are
  picked up by the GitHub webhook and automatically synced into Cube Cloud,
  so the corresponding [staging environments][ref-environments-staging]
  reflect the latest commits without any manual step.
* Pushes to the **production branch** are intentionally **not**
  auto-deployed in CLI mode. The production branch only changes when
  somebody runs `cubejs-cli deploy` against the deployment.

This gives you GitHub-driven previews for feature work while keeping the
production deploy gated on an explicit CLI invocation (for example, from your
CI/CD pipeline after a release is approved).

### Development mode with CLI deployments

[Development mode][ref-dev-mode] is fully available on CLI deployments:
developers can enter dev mode, switch branches, save changes, commit them,
and even merge branches into the production branch from the Cube Cloud UI.

However, in CLI mode, **none of these actions trigger a production build or
redeploy**. Specifically:

* Saving or committing changes in dev mode only updates the per-developer
  [development environment][ref-environments-dev] and the corresponding
  branch in the internal repository. Production is not affected.
* Merging a branch into the production branch from the Cube Cloud UI updates
  the production branch in the internal repository but **does not** rebuild
  or redeploy the [production environment][ref-environments-prod].
* Any changes made through the UI are **overwritten on the next
  `cubejs-cli deploy`**, which uploads the contents of your local project to
  Cube Cloud and triggers a production build.

In other words, a CLI-mode deployment will not change production just because
somebody pressed **Enter Development Mode** and merged a work-in-progress
branch — production only changes when somebody (or some pipeline) explicitly
runs `cubejs-cli deploy` against the deployment.

If you want changes made in the Cube Cloud UI to flow to production
automatically, switch the deployment to [Deploy with Git](#deploy-with-git).

[ref-dev-mode]: /docs/data-modeling/dev-mode

[ref-environments-dev]: /admin/deployment/environments#development-environments

[ref-environments-prod]: /admin/deployment/environments#production-environment

[ref-environments-staging]: /admin/deployment/environments#staging-environments


# Custom domains
Source: https://docs.cube.dev/admin/deployment/custom-domains

Maps your own DNS hostname to Cube Cloud deployment APIs using the custom domain flow and required CNAME records.

By default, Cube Cloud deployments and their API endpoints use auto-generated
anonymized domain names, e.g., `emerald-llama.gcp-us-central1.cubecloudapp.dev`.
You can also assign a custom domain to your deployment.

<Note>
  Available on [Premium and above plans](https://cube.dev/pricing).
</Note>

To set up a custom domain, go to your deployment's settings page. Under
the **Custom Domain** section, type in your custom domain and
click **Add**:

<Frame>
  <img />
</Frame>

After doing this, copy the provided domain and add the following `CNAME` records
to your DNS provider:

| Name          | Value                                       |
| ------------- | ------------------------------------------- |
| `YOUR_DOMAIN` | The copied value from Cube Cloud's settings |

Using the example subdomain from the screenshot, a `CNAME` record for `acme.dev`
would look like:

| Name       | Value                                                 |
| ---------- | ----------------------------------------------------- |
| `insights` | `colossal-crowville.gcp-us-central1.cubecloudapp.dev` |

DNS changes can sometimes take up to 15 minutes to propagate, please wait at
least 15 minutes and/or try using another DNS provider to verify the `CNAME`
record correctly before raising a new support ticket.


# Bring Your Own Cloud on AWS
Source: https://docs.cube.dev/admin/deployment/dedicated/aws/byoc

Prerequisites, IAM access, and provisioning steps for deploying BYOC inside your own AWS account, managed by the Cube Operator.

With Bring Your Own Cloud (BYOC) on AWS, all the components interacting with private data are deployed on
the customer infrastructure on AWS and managed by the Cube Control Plane via the Cube Operator.
This document provides step-by-step instructions for deploying Cube BYOC on AWS.

<Note>
  Available on the [Enterprise plan](https://cube.dev/pricing).
  [Contact us](https://cube.dev/contact) for details. For private API access from your
  applications and BI tools, see [Private API Connectivity][private-api-connectivity].
</Note>

[private-api-connectivity]: /admin/deployment/dedicated/aws/private-api-connectivity

## Prerequisites

The bulk of provisioning work will be done remotely by Cube automation.
However, to get started, you'll need to provide Cube with the necessary access
along with some additional information that includes:

* **AWS Account ID:** The AWS account ID of the target deployment account
  [the AWS Console][aws-console].
* **AWS Region:** [The AWS region][aws-docs-regions] where the BYOC resources
  should be deployed.

In addition to that, you'll need to make sure you have sufficient access to create
the `CubeCloudBYOC` IAM role that would allow Cube to:

* Create and manage a VPC
* Create one or more EKS clusters
* Create and maintain necessary IAM roles and policies
* Configure VPC networking
* Run ec2 instances
* Manage ec2 autoscaling
* Manage S3 buckets
* Manage CloudWatch Logs
* Create and manage RDS PostgreSQL instances

<Warning>
  **Restrictive SCPs may block RDS provisioning.** Amazon RDS needs a service-linked
  role named `AWSServiceRoleForRDS` in the account. The policy below grants
  `iam:CreateServiceLinkedRole` for `rds.amazonaws.com`, so Cube creates it during
  provisioning — but if your organization's SCPs deny IAM writes, the grant is
  present in the policy without being effective in the account, and provisioning
  fails with a message that names a parameter rather than a permission:

  ```
  InvalidParameterValue: Unable to create the resource.
  Verify that you have permission to create service linked role.
  ```

  To rule this out, run the following once in the target account before granting
  Cube access. `InvalidInput: ... has been taken in this account` means the role
  already exists and no action is needed.

  ```bash theme={"dark"}
  aws iam create-service-linked-role --aws-service-name rds.amazonaws.com
  ```

  If the command itself is denied by an SCP, the same denial will block Cube during
  provisioning — ask your AWS organization administrator to permit
  `iam:CreateServiceLinkedRole` for `rds.amazonaws.com` in this account.
</Warning>

## Provisioning access

### Create a CubeCloudBYOC policy

Navigate to **IAM->Policies** and create a new policy called `CubeCloudBYOC`
with the following JSON content. Please substitute `AWS_ACCOUNT_ID` with your
actual account ID.

```JSON theme={"dark"}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "autoscaling:DescribeAutoScalingGroups",
                "autoscaling:DescribeAutoScalingInstances",
                "autoscaling:DescribeLaunchConfigurations",
                "autoscaling:DescribeTags",
                "ec2:DescribeAddresses",
                "ec2:DescribeAddressesAttribute",
                "ec2:DescribeAvailabilityZones",
                "ec2:DescribeInternetGateways",
                "ec2:DescribeLaunchTemplateVersions",
                "ec2:DescribeLaunchTemplates",
                "ec2:DescribeNatGateways",
                "ec2:DescribeNetworkInterfaces",
                "ec2:DescribePrefixLists",
                "ec2:DescribeRegions",
                "ec2:DescribeRouteTables",
                "ec2:DescribeSecurityGroupRules",
                "ec2:DescribeSecurityGroups",
                "ec2:DescribeSubnets",
                "ec2:DescribeVpcAttribute",
                "ec2:DescribeVpcClassicLink",
                "ec2:DescribeVpcClassicLinkDnsSupport",
                "ec2:DescribeVpcEndpointServiceConfigurations",
                "ec2:DescribeVpcEndpoints",
                "ec2:DescribeVpcPeeringConnections",
                "ec2:DescribeVpcs",
                "ec2:DescribeVolumes",
                "ec2:RunInstances",
                "eks:DescribeCluster",
                "eks:DescribeNodegroup",
                "eks:ListClusters",
                "iam:GetRole",
                "sts:DecodeAuthorizationMessage",
                "rds:DescribeDBInstances",
                "rds:DescribeDBSubnetGroups",
                "rds:DescribeDBParameterGroups",
                "rds:ListTagsForResource"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": ["s3:*"],
            "Resource": ["arn:aws:s3:::cube-store-*"]
        },
        {
            "Effect": "Allow",
            "Action": [
                "ec2:AllocateAddress",
                "ec2:CreateInternetGateway",
                "ec2:CreateLaunchTemplate",
                "ec2:CreateNatGateway",
                "ec2:CreateRoute",
                "ec2:CreateRouteTable",
                "ec2:CreateSecurityGroup",
                "ec2:CreateSubnet",
                "ec2:CreateTags",
                "ec2:CreateVpc",
                "ec2:CreateVpcEndpoint",
                "ec2:CreateVpcEndpointServiceConfiguration",
                "ec2:CreateVpcPeeringConnection",
                "ec2:CreateVolume",
                "eks:CreateCluster",
                "eks:CreateNodegroup",
                "iam:CreateOpenIDConnectProvider",
                "iam:PassRole",
                "iam:TagOpenIDConnectProvider",
                "logs:CreateLogDelivery",
                "kms:TagResource",
                "kms:CreateKey",
                "rds:CreateDBInstance",
                "rds:CreateDBSubnetGroup",
                "rds:AddTagsToResource"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:RequestTag/Created-By": "CubeCloud"
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:AddRoleToInstanceProfile",
                "iam:AttachRolePolicy",
                "iam:CreateInstanceProfile",
                "iam:CreateOpenIDConnectProvider",
                "iam:CreatePolicy",
                "iam:CreatePolicyVersion",
                "iam:CreateRole",
                "iam:CreateServiceLinkedRole",
                "iam:DeleteInstanceProfile",
                "iam:DeleteOpenIDConnectProvider",
                "iam:DeletePolicy",
                "iam:DeletePolicyVersion",
                "iam:DeleteRole",
                "iam:DeleteRolePolicy",
                "iam:DeleteServiceLinkedRole",
                "iam:DetachRolePolicy",
                "iam:GetInstanceProfile",
                "iam:GetOpenIDConnectProvider",
                "iam:GetPolicy",
                "iam:GetPolicyVersion",
                "iam:GetRole",
                "iam:GetRolePolicy",
                "iam:ListAttachedRolePolicies",
                "iam:ListInstanceProfilesForRole",
                "iam:ListOpenIDConnectProviderTags",
                "iam:ListPolicyVersions",
                "iam:ListRolePolicies",
                "iam:PassRole",
                "iam:PutRolePolicy",
                "iam:RemoveRoleFromInstanceProfile",
                "iam:TagInstanceProfile",
                "iam:TagOpenIDConnectProvider",
                "iam:TagPolicy",
                "iam:TagRole",
                "iam:UpdateOpenIDConnectProviderThumbprint"
            ],
            "Resource": [
                "arn:aws:iam::{AWS_ACCOUNT_ID}:instance-profile/CubeCloud*",
                "arn:aws:iam::{AWS_ACCOUNT_ID}:instance-profile/cubeapp-*",
                "arn:aws:iam::{AWS_ACCOUNT_ID}:instance-profile/cube-store-*",
                "arn:aws:iam::{AWS_ACCOUNT_ID}:oidc-provider/oidc.eks.*",
                "arn:aws:iam::{AWS_ACCOUNT_ID}:policy/CubeCloud*",
                "arn:aws:iam::{AWS_ACCOUNT_ID}:policy/cubeapp-*",
                "arn:aws:iam::{AWS_ACCOUNT_ID}:role/CubeCloud*",
                "arn:aws:iam::{AWS_ACCOUNT_ID}:role/cubeapp-*",
                "arn:aws:iam::{AWS_ACCOUNT_ID}:role/cube-store-*"
            ],
            "Condition": {
                "StringEquals": {
                    "iam:ResourceTag/Created-By": "CubeCloud"
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": "iam:CreateServiceLinkedRole",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "iam:AWSServiceName": [
                        "eks.amazonaws.com",
                        "eks-nodegroup.amazonaws.com",
                        "eks-fargate.amazonaws.com",
                        "rds.amazonaws.com"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "autoscaling:SetDesiredCapacity",
                "autoscaling:TerminateInstanceInAutoScalingGroup"
            ],
            "Resource": ["*"],
            "Condition": {
                "StringEquals": {
                    "autoscaling:ResourceTag/Created-By": "CubeCloud"
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": ["eks:*", "kms:*"],
            "Resource": ["*"],
            "Condition": {
                "StringEquals": {
                    "aws:ResourceTag/Created-By": "CubeCloud"
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": ["ec2:*"],
            "Resource": ["*"],
            "Condition": {
                "StringEquals": {
                    "ec2:ResourceTag/Created-By": "CubeCloud"
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "rds:ModifyDBInstance",
                "rds:DeleteDBInstance",
                "rds:DeleteDBSubnetGroup",
                "rds:RebootDBInstance",
                "rds:StartDBInstance",
                "rds:StopDBInstance",
                "rds:AddTagsToResource",
                "rds:RemoveTagsFromResource"
            ],
            "Resource": ["*"],
            "Condition": {
                "StringEquals": {
                    "aws:ResourceTag/Created-By": "CubeCloud"
                }
            }
        }
    ]
}
```

### Creating a role

Navigate to **IAM->Roles** and create a new Role called `CubeCloudBYOC`. Select
**AWS Account** as the Trusted entity. Type and enter
`arn:aws:iam::307491255751:root`, which is the Cube BYOC provisioner
account. On the **Add permissions** page, find and select the `CubeCloudBYOC`
policy you created earlier. On the final **Review and create** page, edit the
**Trust Policy** to make it look like this.

```JSON theme={"dark"}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::307491255751:root"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "cube-cloud-byoc"
                }
            }
        }
    ]
}
```

Make sure to include `"sts:ExternalId": "cube-cloud-byoc"` in the Condition section.

## Deployment

The actual deployment will be done by Cube automation. All that's left to
do is notify your Cube contact point that access has been granted, and pass
along your Region/AWS Account ID information.

[aws-console]: https://console.aws.amazon.com/

[aws-docs-regions]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions


# Dedicated Infrastructure on AWS
Source: https://docs.cube.dev/admin/deployment/dedicated/aws/index

Connect Cube's Dedicated Infrastructure on AWS to your VPCs and corporate networks, or deploy the entire data plane inside your own AWS account via BYOC.

On AWS, Cube offers single-tenant Dedicated Infrastructure operated by Cube,
and Bring Your Own Cloud (BYOC) operated inside your own AWS account. Both
options support private network connectivity so that data source traffic — and,
optionally, Cube API traffic — never traverses the public internet.

## Backend connectivity (Cube → your network)

Use these options to give Cube private access to your data sources, auth
providers, BI APIs targeted by Semantic Layer Sync, and anything else Cube
needs to query. See [Backend and frontend connectivity][backend-frontend] for
the full picture.

* [**AWS PrivateLink**][aws-private-link] — let Cube reach data sources (your
  own services, Snowflake, Databricks, etc.) over PrivateLink endpoint services
  you expose.
* [**VPC Peering**][aws-vpc-peering] — establish a VPC peering connection
  between the Cube VPC and your own VPC for access to internal data sources.

## Frontend connectivity (your clients → Cube)

Use this option to expose Cube's APIs to your applications, browsers, BI
tools, embedded analytics clients, and Semantic Layer Sync-generated configs
over a private network. Public endpoints can be disabled entirely on request.

* [**Private API Connectivity**][aws-private-api-connectivity] — expose Cube's
  HTTP and SQL APIs over AWS PrivateLink.

## Bring Your Own Cloud

If you'd like the entire Cube data plane to live inside your own AWS account,
see [Bring Your Own Cloud on AWS][aws-byoc].

[aws-private-link]: /admin/deployment/dedicated/aws/private-link

[aws-vpc-peering]: /admin/deployment/dedicated/aws/vpc-peering

[aws-private-api-connectivity]: /admin/deployment/dedicated/aws/private-api-connectivity

[aws-byoc]: /admin/deployment/dedicated/aws/byoc

[backend-frontend]: /admin/deployment/dedicated#backend-and-frontend-connectivity


# Private API Connectivity on AWS
Source: https://docs.cube.dev/admin/deployment/dedicated/aws/private-api-connectivity

Expose Cube's HTTP and SQL APIs to your AWS network and internal BI tools over AWS PrivateLink so traffic from your applications, browsers, and BI clients never traverses the public internet.

<Note>
  This page covers **frontend connectivity** — exposing Cube's HTTP and SQL APIs
  to your applications, browsers, BI tools, embedded analytics clients, and
  Semantic Layer Sync-generated configs over a private network. For **backend
  connectivity** (letting Cube reach into your network to query data sources,
  auth providers, BI APIs targeted by SLS, and other upstream services), see
  [AWS PrivateLink][aws-private-link] or [VPC Peering][aws-vpc-peering].
</Note>

With Dedicated Infrastructure and Bring Your Own Cloud on AWS, Cube supports
establishing **AWS PrivateLink** connections from your AWS accounts to the Cube
API endpoints. This lets your applications, internal BI tools, and end-user
browsers reach the Cube HTTP, SQL, and AI APIs entirely over private AWS
networking — never touching the public internet. When private connectivity is
in place, the public API endpoints can be disabled completely on request.

<Note>
  Available on the [Enterprise plan](https://cube.dev/pricing) with Dedicated
  Infrastructure or BYOC on AWS. [Contact us](https://cube.dev/contact) to enable
  private API connectivity for your tenant.
</Note>

## Architecture

Cube runs as two cooperating planes:

* The **control plane** powers the Cube UI and the product surface area
  (deployment management, schema editor, dashboards, Semantic Layer Sync,
  etc.) and is always served from Cube's public domain at
  `https://<customer>.cubecloud.dev`. The control plane itself does not need
  private connectivity — it is a SaaS UI like any other.
* The **data plane** runs your Cube deployments and serves all Cube HTTP and
  SQL **data API** traffic — REST/GraphQL queries from your applications,
  live data calls issued by the Cube UI while rendering charts, SQL
  connections from BI tools, and AI traffic to the [Chat API][chat-api] and
  other AI endpoints (including data-plane-hosted AI Engineer agents and
  external agentic clients [calling the Chat API as a tool][agent-to-agent]).
  The data plane is the part that talks to your databases and returns query
  results, and the part this document teaches you how to expose privately.

[AWS PrivateLink][aws-privatelink] lets a service running in one VPC be
consumed from another VPC over the AWS internal network, without VPC peering
or routing through the internet. The service owner publishes a
[VPC Endpoint Service][aws-endpoint-service] in front of an internal load
balancer; the consumer creates a corresponding
[interface VPC Endpoint][aws-interface-endpoint] in their VPC, which appears
as a set of private ENIs that route traffic to the service over the AWS
backbone.

Cube exposes two VPC Endpoint Services per [Cube Region][cube-region] — one
fronting the HTTP (REST/GraphQL) data API and one fronting the SQL data API.
Each endpoint service sits in front of an internal
[Network Load Balancer][aws-nlb] (NLB) in the Cube VPC.

On the HTTP side, the NLB forwards traffic to Cube's ingress controller, which
terminates TLS using a certificate that only covers
`*.<cube-region>.cubecloudapp.dev`. Because that certificate is bound to the
Cube-managed hostname, you have two options for presenting HTTPS to your own
clients (covered in detail [below](#tls-options-for-https)):

* **Re-terminate TLS on your side** with your own certificate for the hostname
  your clients will dial (`http.cube.internal`, `cube.example.com`, …),
  forwarding upstream to the HTTP VPC endpoint.
* **Reuse the Cube hostname privately** by setting up an internal DNS override
  for `<cube-region>.cubecloudapp.dev` that points at the VPC endpoint. Cube's
  certificate is then valid for all clients without any additional cert work
  on your side.

On the SQL side, TLS is terminated inside the SQL API service behind the NLB,
and SQL clients connect using `sslmode=require` (or equivalent) directly to
the VPC endpoint hostname.

On your side, you create a **VPC Endpoint** (interface endpoint) in your VPC
that connects to each Cube endpoint service, and bind a DNS name to it that
resolves to the endpoint's private IPs from inside your VPN-routable network.
Your applications and BI tools then connect to that private hostname exactly
as they would to a public Cube endpoint, except the traffic flows through
PrivateLink instead of the internet.

<Frame>
  <img alt="Private API Connectivity on AWS — control plane vs data plane topology, VPC endpoints fronted by a customer NLB / SSL-capable proxy, private DNS for the HTTP and SQL APIs, and browser traffic from the corporate VPN" />
</Frame>

## Cube Region

The endpoint services described here are scoped to a **Cube Region** — the
unit of infrastructure that hosts one or more of your deployments. Each region
has a stable identifier of the form `<provider>-<geo-region>-<infrastructure>`
(e.g. `aws-us-east-1-t-12345-prod` for a single-tenant Dedicated region, or
`aws-us-east-1-t-12345-byoc` for a BYOC region). The hostname you override on
your side — either privately remapping `<cube-region>.cubecloudapp.dev` or
fronting it with your own domain — applies to **every** deployment in that
region. See [Cube Regions][cube-region] for the full reference, including
how to find the exact region identifier for your tenant.

## How queries are routed

A single private endpoint per region serves all deployments inside that
region; there is no per-deployment subdomain or per-deployment endpoint to
provision separately.

<Info>
  On Cube's shared, public-facing infrastructure, traffic is routed to a
  deployment by **subdomain** — `<deployment-slug>.<cube-region>.cubecloudapp.dev`
  maps to a specific deployment. When private connectivity is enabled, Cube
  switches to **path-based routing** so that a single private hostname can serve
  every deployment in the region.
</Info>

For the HTTP API, the prefix has the shape:

```
https://<your-private-hostname>/deployment/<deployment-slug>/cubejs-api/v1/...
```

where `<deployment-slug>` is the leftmost label of the deployment's Cube-issued
hostname (e.g. `thirsty-raccoon` from
`thirsty-raccoon.aws-us-east-1-t-12345-prod.cubecloudapp.dev`). The same prefix
applies to all HTTP endpoints — `/cubejs-api/v1/load`, `/livez`, the GraphQL
endpoint, and so on:

```bash theme={"dark"}
curl https://http.cube.internal/deployment/thirsty-raccoon/cubejs-api/v1/load \
  -H "Authorization: $CUBE_JWT" \
  -d '{"query":{"measures":["orders.count"]}}'
```

The SQL API uses a TCP protocol that does not carry an HTTP path, so SQL
connections are routed at the protocol layer (via the database name and
credentials in the connection string) rather than by URL prefix. SQL clients
connect to the same private hostname on port 5432 and identify the deployment
through the SQL connection parameters.

## TLS options for HTTPS

Cube's ingress controller can terminate TLS only for the Cube-issued domain
`*.<cube-region>.cubecloudapp.dev`. Pick the option that fits your DNS and
certificate posture:

### Option A — Reuse the Cube hostname via private DNS

Create a private DNS zone for `<cube-region>.cubecloudapp.dev` —
typically a [Route 53 private hosted zone][aws-route53-phz] associated with
your VPC, or an equivalent override in your corporate resolver — and point the
following records at the VPC endpoints:

| Record name                            | Type | Target                         |
| -------------------------------------- | ---- | ------------------------------ |
| `<cube-region>.cubecloudapp.dev`       | A    | Alias to the HTTP VPC endpoint |
| `*.<cube-region>.cubecloudapp.dev`     | A    | Alias to the HTTP VPC endpoint |
| `sql.<cube-region>.cubecloudapp.dev`   | A    | Alias to the SQL VPC endpoint  |
| `*.sql.<cube-region>.cubecloudapp.dev` | A    | Alias to the SQL VPC endpoint  |

Clients then dial:

```
https://<cube-region>.cubecloudapp.dev/deployment/<deployment-slug>/cubejs-api/v1/...
```

TLS is terminated by Cube's ingress controller using Cube's own certificate
for `*.cubecloudapp.dev` — you don't need to manage a certificate yourself.
This is the simplest setup if you control DNS resolution on the networks your
clients live on. Configure the same hostname in Cube's admin interface so
that the UI and Semantic Layer Sync generate links and configs against it.

### Option B — Front the endpoint with your own domain and certificate

If you'd rather present clients a hostname inside your own domain (e.g.
`cube.example.com`), stand up a customer-side proxy — typically an internal
NLB with a TLS listener bound to a certificate you own, or any reverse proxy
such as nginx, HAProxy, Envoy, or an ALB — that terminates TLS with your
certificate and **re-encrypts** traffic to the Cube HTTP VPC endpoint. Because
Cube's ingress only has a cert for `*.cubecloudapp.dev`, the proxy must do
its own TLS termination; it cannot pass-through your custom-domain TLS to
Cube.

The rest of this section walks each step with both **AWS Console** and
**AWS CLI** instructions. The CLI commands use AWS CLI v2 — run them with
credentials for the account that holds the VPC endpoint, and set your region
with `--region` or the `AWS_REGION` environment variable. If you front the
endpoint with a different reverse proxy (nginx, Envoy, HAProxy, an ALB) instead
of an NLB, the same two principles apply: terminate your own certificate at the
proxy, and re-encrypt to the endpoint over TLS (HTTPS) on port 443 rather than
forwarding plaintext.

<Steps>
  <Step title="Create a target group that points at the HTTP VPC endpoint">
    Create a target group for the HTTP VPC endpoint with these settings:

    * **Target type**: **IP addresses**. A target group cannot reference a VPC
      endpoint service name directly, so you register the endpoint's private
      IPs instead — one ENI per Availability Zone, so register the address from
      every AZ. These IPs are stable for the lifetime of the endpoint.
    * **Protocol / port**: **TLS / 443**. This must be TLS, not TCP — see the
      callout below.
    * **VPC**: the same VPC that holds your HTTP VPC endpoint.
    * **Health check**: **TCP** on port 443 (a TLS health check works too).

    **Console** — under **EC2 → Target groups → Create target group**, choose
    the settings above, then register the endpoint ENI IPs on the **Register
    targets** screen. Find the ENI IPs on the endpoint's **VPC → Endpoints →
    (your endpoint) → Subnets** view, or via the CLI below.

    **AWS CLI**:

    ```bash theme={"dark"}
    # Look up the endpoint's ENI private IPs (one per AZ)
    ENIS=$(aws ec2 describe-vpc-endpoints --vpc-endpoint-ids <vpce-id> \
      --query 'VpcEndpoints[0].NetworkInterfaceIds' --output text)
    aws ec2 describe-network-interfaces --network-interface-ids $ENIS \
      --query 'NetworkInterfaces[].PrivateIpAddress' --output text
    # → one private IP per Availability Zone, e.g. 10.0.1.15   10.0.2.15

    TG_ARN=$(aws elbv2 create-target-group \
      --name cube-http-tg \
      --protocol TLS --port 443 \
      --vpc-id <vpc-id> \
      --target-type ip \
      --health-check-protocol TCP --health-check-port 443 \
      --query 'TargetGroups[0].TargetGroupArn' --output text)

    aws elbv2 register-targets --target-group-arn "$TG_ARN" \
      --targets Id=10.0.1.15,Port=443 Id=10.0.2.15,Port=443
    ```
  </Step>

  <Step title="Create the internal NLB with a TLS listener">
    Create an internal NLB with these settings:

    * **Scheme**: **internal**.
    * **VPC / subnets**: the same VPC, with subnets in the same Availability
      Zones as the endpoint's ENIs (see [Availability Zone
      alignment](#availability-zone-alignment)). Enable **cross-zone load
      balancing** if you want an NLB node in one AZ to reach endpoint ENIs in
      another.
    * **Listener**: protocol **TLS**, port **443**, forwarding to the target
      group from the previous step.
    * **Default certificate**: your own [ACM certificate][aws-acm] covering the
      hostname your clients will dial (e.g. `cube.example.com`).
    * **Security policy**: a current TLS 1.2+ policy such as
      `ELBSecurityPolicy-TLS13-1-2-2021-06`.

    Also allow inbound **TCP/443** from the NLB's subnets on the HTTP VPC
    endpoint's security group so the re-encrypted traffic can reach the
    endpoint ENIs.

    **Console** — under **EC2 → Load balancers → Create load balancer →
    Network Load Balancer**, apply the settings above and add the **TLS**
    listener; then add the endpoint security-group rule under **VPC → Security
    groups**.

    **AWS CLI**:

    ```bash theme={"dark"}
    NLB_ARN=$(aws elbv2 create-load-balancer \
      --name cube-http-nlb \
      --type network --scheme internal \
      --subnets <subnet-az-a> <subnet-az-b> \
      --query 'LoadBalancers[0].LoadBalancerArn' --output text)
    aws elbv2 wait load-balancer-available --load-balancer-arns "$NLB_ARN"

    # Optional: let an NLB node reach endpoint ENIs in another AZ
    aws elbv2 modify-load-balancer-attributes --load-balancer-arn "$NLB_ARN" \
      --attributes Key=load_balancing.cross_zone.enabled,Value=true

    # TLS listener on 443 with your ACM certificate, forwarding to the TG
    aws elbv2 create-listener --load-balancer-arn "$NLB_ARN" \
      --protocol TLS --port 443 \
      --certificates CertificateArn=<acm-cert-arn> \
      --ssl-policy ELBSecurityPolicy-TLS13-1-2-2021-06 \
      --default-actions Type=forward,TargetGroupArn="$TG_ARN"

    # Allow re-encrypted traffic from the NLB subnets into the endpoint
    aws ec2 authorize-security-group-ingress --group-id <endpoint-sg-id> \
      --protocol tcp --port 443 --cidr <nlb-subnet-cidr>
    ```
  </Step>

  <Step title="Bind your hostname to the NLB and set the domain override">
    The NLB receives an internal DNS name of the form
    `<name>-<hash>.elb.<region>.amazonaws.com`. Point your chosen hostname
    (e.g. `cube.example.com`) at it with an `ALIAS`/`CNAME` record in a
    [Route 53 private hosted zone][aws-route53-phz] or your corporate resolver,
    resolvable from every network that reaches Cube (corporate VPN included).

    **Console** — copy the NLB's DNS name from its detail page under **EC2 →
    Load balancers**, then create the `ALIAS`/`CNAME` record under **Route 53 →
    Hosted zones** (or in your corporate DNS).

    **AWS CLI** (Route 53 private hosted zone):

    ```bash theme={"dark"}
    NLB_DNS=$(aws elbv2 describe-load-balancers --load-balancer-arns "$NLB_ARN" \
      --query 'LoadBalancers[0].DNSName' --output text)

    aws route53 change-resource-record-sets --hosted-zone-id <phz-id> \
      --change-batch "{
        \"Changes\": [{
          \"Action\": \"UPSERT\",
          \"ResourceRecordSet\": {
            \"Name\": \"cube.example.com\",
            \"Type\": \"CNAME\",
            \"TTL\": 60,
            \"ResourceRecords\": [{ \"Value\": \"$NLB_DNS\" }]
          }
        }]
      }"
    ```

    Then set the same hostname as the domain override in Cube's admin panel so
    generated UI links and SLS configs use it — see
    [Configuring the private domain](#configuring-the-private-domain).
  </Step>
</Steps>

<Warning>
  The target group's protocol must be **TLS**, not **TCP**. Cube's HTTP endpoint
  expects a TLS handshake on port 443, so the NLB has to **re-encrypt** on the
  upstream leg: with a [TLS target group][aws-nlb-tls] it terminates your
  listener's TLS and opens a fresh TLS connection to the endpoint, whereas a TCP
  target group would forward the already-decrypted bytes to a port that expects
  TLS — so requests never complete. AWS does **not** validate the backend
  certificate on a TLS target group, so Cube's `*.cubecloudapp.dev` certificate
  is accepted even though it does not match your custom hostname; it is used
  purely to encrypt the upstream hop, keeping traffic encrypted end-to-end across
  PrivateLink.
</Warning>

## Reaching Cube from every client

The same private hostname is used by three distinct classes of client, and
each imposes a requirement on how the name resolves:

1. **Your application servers** inside the same VPC as the VPC endpoint
   resolve the private hostname via the VPC's DNS resolver and connect over
   PrivateLink directly.
2. **End-user browsers loading the Cube UI.** When a developer opens
   `https://<customer>.cubecloud.dev` and renders a dashboard, the page issues
   live queries against the Cube data API from the user's browser. Those
   calls originate on the user's laptop, not from a Cube backend, so the URL
   embedded in the UI must be a hostname the user's machine can resolve and
   reach. For this to use PrivateLink, the hostname has to resolve to the
   VPC endpoint over your corporate VPN's DNS and route over the VPN to your
   VPC. A purely internal name that only resolves inside the VPC will fail
   when the user is on the corporate network but not in the VPC; a public
   name that resolves outside the VPN will bypass PrivateLink entirely.
3. **Internal BI tools configured by Semantic Layer Sync (SLS).** If you
   publish Cube datasets to BI tools via SLS, Cube generates connection
   configs that embed the Cube API hostname. Those configs are used by BI
   desktop clients, BI gateways, or other clients running inside your
   network — so SLS must be configured with a hostname those clients can
   resolve and reach over your VPN.

In short, the **private hostname must be visible and routable from every
place the Cube API needs to be reached** — your VPCs, your corporate
VPN-connected laptops, and any BI gateway hosts. Cube cannot infer your
internal DNS; you tell us the hostname you want to use, and you point it at
the VPC endpoint on your side.

<Warning>
  If a user opens the Cube UI and sees a **"Network Error"** banner while
  loading charts, dashboards, or other data-driven views, it means the
  browser cannot reach the data plane over your private network. See
  [Troubleshooting "Network Error" in the Cube UI](#troubleshooting-network-error-in-the-cube-ui)
  below for steps to isolate the failure.
</Warning>

## Chrome local network access permission

<Warning>
  Chromium-based browsers block requests from a page served over the public
  internet to a host that resolves to a **private** address, unless the site has
  the **Local network access** permission. The Cube UI is served from the public
  `https://<customer>.cubecloud.dev` origin while your private API hostname
  resolves to an RFC 1918 address over the VPN — so every browser that loads the
  Cube UI needs this permission before charts, the Semantic Model IDE, the
  playground, and any other data-driven view will render.
</Warning>

This is a browser policy that Cube cannot grant on your behalf, and it applies
to both TLS options above: the browser decides from the **resolved IP address**,
not the hostname, so reusing `<cube-region>.cubecloudapp.dev` does not avoid it.
Non-browser clients — `curl`, `psql`, your application servers, BI gateways — are
unaffected, which is why `curl` from a laptop can succeed while the Cube UI on
the same laptop shows **"Network Error"**.

Chrome enforces this as [Local Network Access][chrome-lna] from Chrome 142
onwards; earlier versions enforced its predecessor,
[Private Network Access][chrome-pna]. A blocked call appears in DevTools as a
failed request with `ERR_BLOCKED_BY_PRIVATE_NETWORK_ACCESS_CHECKS`, or as a
CORS-style console error naming a private or local target address space.

**Individual users** can accept Chrome's *"wants to look for and connect to any
device on your local network"* prompt, or set **Local network access** to
**Allow** under the padlock icon → **Site settings** on the Cube UI origin.

**Managed fleets** should pre-grant the permission with a Chrome Enterprise
policy, since the prompt is easy to dismiss and reappears per profile. Set the
policy value to your Cube UI origin (e.g. `https://<customer>.cubecloud.dev`):

| Chrome version | Policy                                                              |
| -------------- | ------------------------------------------------------------------- |
| 142 and later  | [`LocalNetworkAccessAllowedForUrls`][chrome-policy-lna]             |
| Before 142     | [`InsecurePrivateNetworkRequestsAllowedForUrls`][chrome-policy-pna] |

If some users still fail after the policy is rolled out, have them check
`chrome://policy` and confirm the policy is listed with the expected value. A
missing entry means it has not synced to that device or profile — most often
because the user is signed in to Chrome with a personal, unmanaged Google
profile, which enterprise policies do not reach. That is the usual explanation
for the same page working for one colleague and failing for another on the same
VPN.

## Configuring the private domain

Configure the private hostname for each Cube Region from the Cube admin panel,
under **Regions → \<your region> → Path-based routing → Domain override**.

The domain override tells Cube **where the data plane lives from the
caller's point of view**. It does *not* re-route traffic on Cube's side and
it does *not* open a new tunnel — it is purely a string Cube embeds when
generating outbound references to the data API. Specifically, Cube uses the
override value when generating:

* Links inside the Cube UI (used by **browsers** when rendering dashboards
  and the schema editor — every Cube API call the UI issues goes to this
  hostname directly from the user's machine).
* Connection configs generated by Semantic Layer Sync (used by BI
  desktop clients and gateways inside your network).
* API connection details surfaced to your applications on the
  deployment's API page.

Because every one of those callers — the browser, the BI client, your
application — connects to the hostname **directly**, the override only
works if that hostname is resolvable and reachable from each of those
networks. Setting the override does not give Cube's control plane a new
way to talk to your data plane; it tells *your* clients to stop using the
public Cube domain and start using the private one *you* have published.

Use the hostname your clients will actually dial — the custom-domain front-end
in Option B (e.g. `http.cube.internal`), or the Cube-issued
`<cube-region>.cubecloudapp.dev` if you went with Option A. Leaving the field
empty falls back to the default public hostname, and clients will not use
PrivateLink even if the endpoint service is connected.

<Frame>
  <img alt="Cube admin panel — Regions → Path-based routing → Domain override field" />
</Frame>

HTTP and SQL APIs are typically published under two separate hostnames
(`http.cube.internal` and `sql.cube.internal` in the diagram above), since
the HTTP endpoint sits behind your TLS-terminating proxy on port 443 while
the SQL endpoint is accessed directly on port 5432.

## Provisioning checklist

1. **Request PrivateLink for your tenant.** Contact Cube and provide your
   tenant name and the AWS account ID(s) that will create the VPC endpoints.
2. **Receive endpoint service names.** Cube provisions one HTTP and one SQL
   VPC Endpoint Service per region and shares the service names
   (`com.amazonaws.vpce.<region>.vpce-svc-…`) along with the Cube Region
   identifier.
3. **Create VPC endpoints in your account.** In the AWS Console under
   **VPC → Endpoints**, create an [interface endpoint][aws-interface-endpoint]
   for each service. Place the endpoint in subnets that are reachable from
   both your application workloads and your corporate VPN, and attach a
   security group that allows inbound traffic on 443 (HTTP) or 5432 (SQL)
   from those clients.
4. **Accept the connection.** Cube accepts the endpoint connection request
   on the provider side once visibility is confirmed.
5. **Bind the private hostname.** Pick a TLS option above and create the
   corresponding DNS records — either a [Route 53 private hosted
   zone][aws-route53-phz] for `<cube-region>.cubecloudapp.dev` (Option A) or
   a single record for your custom hostname pointing at your proxy
   (Option B). Make sure the records resolve from every network that needs
   to reach Cube, corporate VPN included.
6. **Set the domain in Cube.** In the admin panel under
   **Regions → \<your region> → Path-based routing → Domain override**,
   enter the chosen hostname so that Cube generates UI links and SLS configs
   using that name.
7. **(Optional) Disable public endpoints.** Once private connectivity is
   verified end-to-end, ask Cube support to disable the public HTTP and SQL
   endpoints for your deployment.

## Availability Zone alignment

<Warning>
  Cube's dedicated infrastructure in each AWS region is deployed across a
  **limited, fixed set of Availability Zones**.
  [AWS PrivateLink requires][aws-privatelink-az] the consumer's VPC endpoint
  to have a subnet in **at least one of the same AZs** where the provider's
  endpoint service is exposed. If none of the subnets in your VPC live in a
  Cube-supported AZ for that region, the VPC endpoint will fail to attach.

  The remedy is to create an additional subnet in one of the Cube-supported
  AZs inside your VPC, attach the VPC endpoint to that subnet, and route
  traffic from your other AZs to it. AWS-internal AZ IDs (e.g. `use1-az2`)
  differ per-account, so coordinate with the Cube team to confirm the
  correct AZ IDs for your region before adding the subnet.
</Warning>

## Verifying connectivity

From a host inside the consumer VPC or attached to the corporate VPN:

```bash theme={"dark"}
# DNS resolves the HTTP and SQL names to their VPC endpoints' private IPs
dig +short http.cube.internal
dig +short sql.cube.internal

# HTTPS reachable over PrivateLink, routed to a specific deployment by path prefix
curl -v https://http.cube.internal/deployment/<deployment-slug>/livez

# SQL API reachable
psql "host=sql.cube.internal port=5432 user=… dbname=… sslmode=require" -c "select 1;"
```

If DNS resolves but connections hang, check the VPC endpoint state, security
group rules on the endpoint ENIs, and that your VPN's route tables include
the VPC's CIDR.

## Troubleshooting "Network Error" in the Cube UI

When the domain override is configured, the Cube UI stops calling the
public Cube data API and starts calling the private hostname you supplied
**directly from the user's browser**. If that hostname is not reachable
from the machine the UI is loaded on, the UI surfaces a red **"Network
Error"** banner on charts, the schema editor, the playground, and any
other view that issues data queries — even though direct API calls (e.g.
`curl` from inside the VPC, or your application servers) keep working.

The fix is usually somewhere along the network path between the browser
and the VPC endpoint. Use the browser's developer tools to pinpoint which
hop is failing:

<Steps>
  <Step title="Open the Network tab in DevTools">
    Reload the page that shows the **"Network Error"** banner with the
    Network tab open. Filter for `Fetch/XHR` requests and look for the
    failing call — it will be a request to the private hostname you
    configured as the domain override (for example
    `https://http.cube.internal/deployment/<slug>/cubejs-api/v1/load`),
    not to `*.cubecloud.dev`.

    If the failing request still points at the **public** `*.cubecloud.dev`
    hostname, the domain override has not been picked up yet — re-check
    the value in **Regions → \<your region> → Path-based routing → Domain
    override** and reload the UI with cache disabled.
  </Step>

  <Step title="Open the failing request URL in a new tab">
    Right-click the failing request and copy its full URL, then open it
    in a new browser tab. This strips the Cube UI out of the picture so
    you can see what the browser itself sees when talking to the private
    hostname.

    Common outcomes:

    * **The page does not load at all / "This site can't be reached" /
      `ERR_NAME_NOT_RESOLVED`** — DNS for the private hostname is not
      reachable from the user's machine. Confirm the user is on the
      corporate VPN, that the VPN pushes the private DNS zone (or that
      the corporate resolver answers for the override hostname), and
      that the record points at the VPC endpoint's private IPs.
    * **`ERR_CONNECTION_TIMED_OUT` / `ERR_CONNECTION_REFUSED`** — DNS
      resolves but TCP to the VPC endpoint is blocked. Check that the
      VPN route table covers the VPC CIDR and that the security group on
      the VPC endpoint ENIs allows 443 from the VPN's client CIDR.
    * **`NET::ERR_CERT_COMMON_NAME_INVALID` /
      `NET::ERR_CERT_AUTHORITY_INVALID` / browser interstitial about an
      untrusted certificate** — TLS termination is misconfigured. With
      Option A (reuse the Cube hostname), make sure the private DNS
      record really is for `<cube-region>.cubecloudapp.dev` so Cube's
      `*.cubecloudapp.dev` certificate matches. With Option B (custom
      domain), make sure your proxy is presenting a certificate whose
      CN/SAN matches the override hostname and is signed by a CA the
      user's machine trusts.
    * **`ERR_BLOCKED_BY_PRIVATE_NETWORK_ACCESS_CHECKS`, or the URL
      loads fine in its own tab but still fails from the Cube UI** —
      the browser is blocking the call because the private hostname
      resolves to a private address and the site lacks Chrome's
      **Local network access** permission. See
      [Chrome local network access permission](#chrome-local-network-access-permission).
    * **HTTP 4xx/5xx from Cube** — the network path is fine; the error
      is on the API itself. Inspect the response body in the new tab to
      see Cube's error message and proceed as you would for any other
      API error.
  </Step>

  <Step title="Confirm the same request works from inside the VPC">
    From a host inside the consumer VPC, run the same request with
    `curl -v` (see [Verifying connectivity](#verifying-connectivity)
    above). If it succeeds from the VPC but fails from the user's
    laptop, the data plane is healthy and the problem is strictly in the
    VPN → VPC endpoint path for that user.
  </Step>

  <Step title="Sanity-check the override value itself">
    If every request from every machine fails, re-open
    **Regions → \<your region> → Path-based routing → Domain override**
    and confirm:

    * The hostname has no scheme prefix (no `https://`) and no path.
    * The hostname matches the DNS record you actually published.
    * For Option B, the hostname matches the certificate on your TLS
      proxy.
    * Clearing the field falls back to the public hostname — useful as
      a quick smoke test to confirm the UI itself is healthy and the
      problem is the private path.
  </Step>
</Steps>

[cube-region]: /admin/deployment/infrastructure#understanding-cube-cloud-region

[aws-private-link]: /admin/deployment/dedicated/aws/private-link

[aws-vpc-peering]: /admin/deployment/dedicated/aws/vpc-peering

[chat-api]: /reference/embed-apis/chat-api

[agent-to-agent]: /recipes/ai/agent-to-agent

[aws-privatelink]: https://docs.aws.amazon.com/vpc/latest/privatelink/what-is-privatelink.html

[aws-endpoint-service]: https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html

[aws-interface-endpoint]: https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html

[aws-nlb]: https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html

[aws-nlb-tls]: https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-tls-listener.html

[aws-acm]: https://docs.aws.amazon.com/acm/latest/userguide/acm-overview.html

[aws-privatelink-az]: https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#endpoint-service-availability-zones

[aws-route53-phz]: https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html

[chrome-lna]: https://developer.chrome.com/blog/local-network-access

[chrome-pna]: https://developer.chrome.com/blog/private-network-access-update

[chrome-policy-lna]: https://chromeenterprise.google/policies/local-network-access-allowed-for-urls/

[chrome-policy-pna]: https://chromeenterprise.google/policies/insecure-private-network-requests-allowed-for-urls/


# Setting up AWS PrivateLink
Source: https://docs.cube.dev/admin/deployment/dedicated/aws/private-link

How to expose an AWS endpoint service and coordinate PrivateLink so Cube's Dedicated Infrastructure reaches your VPC privately.

<Note>
  This page covers **backend connectivity** — Cube reaching into your network to
  query data sources, auth providers, BI APIs targeted by Semantic Layer Sync,
  and other upstream services. See
  [Backend and frontend connectivity][backend-frontend] for the full picture.
  For **frontend connectivity** (exposing Cube's APIs to your applications,
  browsers, BI tools, and embedded analytics clients), see
  [Private API Connectivity on AWS][aws-private-api-connectivity].
</Note>

[AWS PrivateLink][aws-docs-private-link] provides private connectivity between
virtual private clouds (VPCs), supported services and resources, and your
on-premises networks, without exposing your traffic to the public internet.
To set up a PrivateLink connection between Cube's Dedicated Infrastructure
and your own VPC, you'll need to prepare an Endpoint Service, share service
details with the Cube team, and accept the incoming connection request.

<Note>
  **Dedicated Infrastructure vs. Bring Your Own Cloud.** The flow described on
  this page — sharing service details with the Cube team and letting Cube create
  the VPC endpoint and DNS overrides — applies to
  [Dedicated Infrastructure][cube-region] operated by Cube.

  In a [Bring Your Own Cloud (BYOC)][aws-byoc] deployment, the Cube VPC lives in
  **your own AWS account**, so you own the networking. The IAM role granted to
  the Cube Operator intentionally does not include `route53:*` permissions,
  which means Cube cannot create the VPC interface endpoint or the Route 53
  private hosted zone needed for the DNS override on your behalf.

  For BYOC, set up PrivateLink yourself inside the Cube VPC:

  1. Create the VPC interface endpoint in the Cube VPC against the provider's
     Endpoint Service Name.
  2. Create a Route 53 private hosted zone for the TLS hostname and associate
     it with the Cube VPC, with an `A` ALIAS record pointing at the interface
     endpoint.
  3. Confirm the security groups on both ends allow the required ports.

  If you'd prefer Cube to do this for you in BYOC, you can grant the Cube
  Operator role `route53:*` (and the matching `ec2:*VpcEndpoint*` permissions)
  on the BYOC role — but most customers keep this networking in their own
  hands.
</Note>

## Preparing the Endpoint Service

There are two common scenarios for preparing the Endpoint Service:

* Connecting to a service in your AWS infrastructure
* Connecting to a service provided by a third party such as Snowflake,
  Databricks, Altinity Cloud, etc.

In the case of your own infrastructure, please follow the
[official AWS documentation][aws-docs-endpoint-service] to configure the
Endpoint Service pointing at your data source.

If your data source is hosted in a third-party infrastructure, please follow
the vendor's documentation for creating and managing an Endpoint Service.

## Allowing the Cube principal

Cube needs to be added to the list of principals allowed to discover your
Endpoint Service. To do so, please go to **AWS Console** → **VPC** →
**Endpoint Services** → **Your service** → **Allow principals** and add
`arn:aws:iam::331376342520:root` to the list.

<Info>
  `331376342520` is the AWS account ID of Cube's PrivateLink consumer account.
  Adding its root principal authorizes Cube to discover your endpoint service
  and create a private endpoint against it; nothing else in Cube's AWS estate
  gains access to your network.
</Info>

## Gathering required information

To request establishing a PrivateLink connection, please share the following
information with the Cube team:

* **Service Name** (such as `com.amazonaws.vpce.us-west-2.vpce-svc-abcde`)
* **Reference Name** for the record (such as "Snowflake-prod" or
  "clickhouse-dev")
* **Ports**: a list of ports that will be accessed through this connection
* **DNS Name(s)**: see [DNS and TLS](#dns-and-tls) below
* **Cube Region:** PrivateLink requires Cube to be hosted on
  [Dedicated Infrastructure][cube-region]. Specify which Cube Region should
  host your Dedicated Infrastructure.

## DNS and TLS

How your data source is addressed inside Cube depends on whether it speaks
TLS:

* **If the service uses TLS** (HTTPS, JDBC `sslmode=require`, etc.), share
  the **DNS name(s)** the certificate is issued for — typically the same
  hostname your in-network clients already use to reach it. Cube creates
  internal DNS overrides inside the Dedicated Infrastructure so that the same
  hostname resolves to the PrivateLink endpoint. Keeping the original
  hostname is what preserves TLS validity: the certificate's CN/SAN keeps
  matching what Cube dials.
* **If the service does not use TLS** and you don't supply a DNS name, the
  Cube team will share back an internal endpoint hostname (e.g. an
  AWS-assigned interface-endpoint DNS name) that you can configure as the
  upstream when you wire the connection into Cube.

## Accepting the connection

The Cube team will notify you once the connection request is sent. You can
accept it by going to **AWS Console** → **VPC** → **Endpoint Services** →
**Your Service** → **Endpoint Connections** and clicking
**Accept Connection Request**.

## Using the connection

Once the connection is established, you can access your data source by
addressing it via the DNS name(s) you supplied (TLS case) or the internal
endpoint hostname returned to you by the Cube team (non-TLS case).

## Supported Regions

AWS PrivateLink is available in all AWS commercial regions where Dedicated
Infrastructure can be provisioned. AWS China (`cn-north-1`, `cn-northwest-1`)
and AWS GovCloud (`us-gov-east-1`, `us-gov-west-1`) are not supported.

[aws-docs-private-link]: https://aws.amazon.com/privatelink/

[aws-docs-endpoint-service]: https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html

[cube-region]: /admin/deployment/infrastructure#understanding-cube-cloud-region

[aws-private-api-connectivity]: /admin/deployment/dedicated/aws/private-api-connectivity

[aws-byoc]: /admin/deployment/dedicated/aws/byoc

[backend-frontend]: /admin/deployment/dedicated#backend-and-frontend-connectivity


# Setting up VPC Peering on AWS
Source: https://docs.cube.dev/admin/deployment/dedicated/aws/vpc-peering

End-to-end checklist for VPC peering Cube's Dedicated Infrastructure with your AWS VPC for private data access.

<Note>
  This page covers **backend connectivity** — Cube reaching into your network to
  query data sources, auth providers, BI APIs targeted by Semantic Layer Sync,
  and other upstream services. See
  [Backend and frontend connectivity][backend-frontend] for the full picture.
  For **frontend connectivity** (exposing Cube's APIs to your applications,
  browsers, BI tools, and embedded analytics clients), see
  [Private API Connectivity on AWS][aws-private-api-connectivity].
</Note>

To set up AWS VPC Peering between Cube's Dedicated Infrastructure and your
VPC, you collect the information below and hand it over to your Cube
representative. Next, you accept a VPC peering request initiated by Cube, then
configure security groups and route tables so that Cube can reach your data
source.

## Information required by Cube

To allow Cube to peer with a [VPC on AWS][aws-docs-vpc], please share the
following with the Cube team:

* **AWS Account ID:** The AWS account ID of the VPC owner. This can be found
  in the top-right corner of [the AWS Console][aws-console].
* **AWS Region:** [The AWS region][aws-docs-regions] that the VPC resides in.
* **AWS VPC ID:** The ID of the VPC that Cube will connect to, for example
  `vpc-0099aazz`.
* **AWS VPC CIDR:** The [CIDR block][wiki-cidr-block] of the VPC that Cube
  will connect to, for example `10.0.0.0/16`.
* **Cube Region:** VPC Peering requires Cube to be hosted on
  [Dedicated Infrastructure][cube-region]. Specify which Cube Region should
  host your Dedicated Infrastructure.

## Setup

### Accepting the peering request

After receiving the information above, Cube will send a
[VPC peering request][aws-docs-vpc-peering] that must be accepted. This can
be done either through the [AWS Web Console][aws-console] or through an
infrastructure-as-code tool.

To [accept the VPC peering request][aws-docs-vpc-peering-accept] through the
AWS Web Console, follow the instructions below:

1. Open the [Amazon VPC console](https://console.aws.amazon.com/vpc/).

   <Warning>
     Ensure you have the necessary permissions to accept a VPC peering
     request. If you are unsure, please contact your AWS administrator.
   </Warning>

2. Use the Region selector to choose the Region of the accepter VPC.

3. In the navigation pane, choose **Peering connections**.

4. Select the pending VPC peering connection (the status should be
   `pending-acceptance`), then choose **Actions**, followed by
   ​**Accept request**.

   <Warning>
     Ensure the peering request is from Cube by checking that the **AWS
     account ID**, **region**, and **VPC IDs** match those provided by your
     CSM.
   </Warning>

5. When prompted for confirmation, choose **Accept request**.

6. Choose **Modify my route tables now** to add a route to the VPC route
   table so that you can send and receive traffic across the peering
   connection.

<Info>
  For more information about peering connection lifecycle statuses, check out
  the [VPC peering connection lifecycle on AWS][aws-docs-vpc-peering-lifecycle].
</Info>

### Updating security groups

The initial VPC setup will not allow traffic from Cube; this is because
[the security group][aws-docs-vpc-security-group] for the database will need
to allow access from the Cube VPC CIDR block.

This can be achieved by adding a new security group rule:

| Protocol | Port Range | Source/Destination                          |
| -------- | ---------- | ------------------------------------------- |
| TCP      | 3306       | The Cube VPC CIDR block for the AWS region. |

<Info>
  The Cube VPC CIDR block is shared with you by the Cube team alongside the
  peering request, and is also visible in the AWS Console on the **Peering
  connections** → **\<your peering>** → **Details** page as the
  **Requester VPC CIDR**.
</Info>

### Updating route tables

The final step is to update route tables in your VPC to allow traffic from
Cube to reach your database. The Cube VPC CIDR block must be added to the
route tables of all subnets that connect to the database. To do this, follow
the instructions on [the AWS documentation][aws-docs-vpc-peering-routing].

## Troubleshooting

Database connection issues with misconfigured VPCs often manifest as
connection timeouts. If you are experiencing connection issues, please check
the following:

* Verify that
  [all security groups allow traffic](#updating-security-groups) from the
  Cube VPC CIDR block.
* Verify that
  [a route exists to the Cube VPC CIDR block](#updating-route-tables) from
  the subnets that connect to the database.

## Supported Regions

VPC Peering is available in all AWS commercial regions where Dedicated
Infrastructure can be provisioned. AWS China (`cn-north-1`, `cn-northwest-1`)
and AWS GovCloud (`us-gov-east-1`, `us-gov-west-1`) are not supported.

[aws-console]: https://console.aws.amazon.com/

[aws-docs-regions]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions

[aws-docs-vpc]: https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html

[aws-docs-vpc-peering]: https://docs.aws.amazon.com/vpc/latest/peering/what-is-vpc-peering.html

[aws-docs-vpc-peering-accept]: https://docs.aws.amazon.com/vpc/latest/peering/create-vpc-peering-connection.html#different-account-different-region

[aws-docs-vpc-peering-lifecycle]: https://docs.aws.amazon.com/vpc/latest/peering/vpc-peering-basics.html#vpc-peering-lifecycle

[aws-docs-vpc-peering-routing]: https://docs.aws.amazon.com/vpc/latest/peering/vpc-peering-routing.html

[aws-docs-vpc-security-group]: https://docs.aws.amazon.com/vpc/latest/userguide/security-group-rules.html

[wiki-cidr-block]: https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_blocks

[cube-region]: /admin/deployment/infrastructure#understanding-cube-cloud-region

[aws-private-api-connectivity]: /admin/deployment/dedicated/aws/private-api-connectivity

[backend-frontend]: /admin/deployment/dedicated#backend-and-frontend-connectivity


# Bring Your Own Cloud on Azure
Source: https://docs.cube.dev/admin/deployment/dedicated/azure/byoc

Azure BYOC architecture, provisioner app access, and AKS-based onboarding for deploying Cube inside your own Azure subscription.

With Bring Your Own Cloud (BYOC) on Azure, all the components interacting with private data are deployed on
the customer infrastructure on Azure and managed by the Cube Control Plane via the Cube Operator.
This document provides step-by-step instructions for deploying Cube BYOC on Azure.

## Overall Design

Cube will gain access to your Azure account via the Cube Provisioner Enterprise App.

It will leverage a dedicated subscription where it will create a new Resource
Group and bootstrap all the necessary infrastructure. At the center of the BYOC
infrastructure are two AKS clusters that provide compute resources for Cube
Store and all Cube deployments you configure in the Cube UI. These AKS
clusters will have a Cube Operator installed in them that is connected to
the Cube Control Plane. The Cube Operator receives instructions from the
Control Plane and dynamically creates or destroys all the necessary
Kubernetes resources required to support your Cube deployments.

<div>
  <img alt="High-level diagram of Cube resources deployed on Azure" />
</div>

## Prerequisites

The bulk of provisioning work will be done remotely by Cube automation.
However, to get started, you'll need to provide Cube with the necessary access
along with some additional information that includes:

* **Azure Tenant ID** - the Entra ID of your Azure account
* **Azure Subscription ID** - The target subscription where Cube will be granted admin permissions to provision the BYOC infrastructure
* **Region** - The target Azure region where Cube BYOC will be installed

## Provisioning access

### Add Cube tenant to your organization

First you should add the Cube tenant to your organization. To do this,
open the [Azure Portal][azure-console] and go to **Azure Active
Directory** → **External Identities** → **Cross-tenant
access settings** → **Organizational Settings**
→ **Add Organization**.

For Tenant ID, enter `197e5263-87f4-4ce1-96c4-351b0c0c714a`.

Make sure that **B2B Collaboration** → **Inbound Access**
→ **Applications** is set to **Allows access**.

### Register Cube service principal at your organization

To register the Cube service principal for your organization, follow these
steps:

1. Log in with an account that has permissions to register Enterprise
   applications.
2. Open a browser tab and go to the following URL, replacing `<TENANT_ID>` with
   your tenant ID:
   `https://login.microsoftonline.com/<TENANT_ID>/oauth2/authorize?client_id=0c5d0d4b-6cee-402e-9a08-e5b79f199481&response_type=code&redirect_uri=https%3A%2F%2Fwww.microsoft.com%2F`
3. The Cube service principal has specific credentials. Check that the
   following details match exactly what you see on the dialog box that pops up:

* Client ID: `d1c59948-4d4a-43dc-8d04-c0df8795ae19`
* Name: `cube-cloud-byoc-provisioner`

Once you have confirmed that all the information is correct,
select **Consent on behalf of your organization** and
click **Accept**.

### Grant admin permissions on your BYOC Azure Subscription to the cube-cloud-byoc-provisioner

On the [Azure Portal][azure-console], go to **Subscriptions**
→ *Your BYOC Subscription* → **IAM**→ **Role Assignment**
and assing `Contributor` and `Role Based Access Control Administrator` to the `cube-cloud-byoc-provisioner`
Service Principal.

<Frame>
  <img />
</Frame>

## Deployment

The actual deployment will be done by Cube automation. All that's left to
do is notify your Cube contact point that access has been granted, and pass
along your Azure Tenant/Subscription/Region information.

[azure-console]: https://portal.azure.com


# Dedicated Infrastructure on Azure
Source: https://docs.cube.dev/admin/deployment/dedicated/azure/index

Connect Cube's Dedicated Infrastructure on Azure to your VNets and corporate networks, or deploy the entire data plane inside your own Azure subscription via BYOC.

On Azure, Cube offers single-tenant Dedicated Infrastructure operated by Cube,
and Bring Your Own Cloud (BYOC) operated inside your own Azure subscription.
Both options support private network connectivity to your data sources.

## Backend connectivity (Cube → your network)

Use these options to give Cube private access to your data sources, auth
providers, BI APIs targeted by Semantic Layer Sync, and anything else Cube
needs to query. See [Backend and frontend connectivity][backend-frontend] for
the full picture.

* [**Azure Private Link**][azure-private-link] — connect to data sources
  exposed through Azure Private Link Services without routing traffic over
  the public internet.
* [**VNet Peering**][azure-vnet-peering] — establish a VNet peering connection
  between the Cube VNet and your own VNet.

## Frontend connectivity (your clients → Cube)

Expose Cube's APIs to your applications, browsers, BI tools, embedded
analytics clients, and Semantic Layer Sync-generated configs over a private
network. The pattern mirrors the AWS implementation documented in
[Private API Connectivity on AWS][aws-private-api-connectivity];
[contact us](https://cube.dev/contact) to enable the equivalent on Azure for
your tenant.

## Bring Your Own Cloud

If you'd like the entire Cube data plane to live inside your own Azure
subscription, see [Bring Your Own Cloud on Azure][azure-byoc].

[azure-private-link]: /admin/deployment/dedicated/azure/private-link

[azure-vnet-peering]: /admin/deployment/dedicated/azure/vpc-peering

[azure-byoc]: /admin/deployment/dedicated/azure/byoc

[aws-private-api-connectivity]: /admin/deployment/dedicated/aws/private-api-connectivity

[backend-frontend]: /admin/deployment/dedicated#backend-and-frontend-connectivity


# Setting up Azure Private Link
Source: https://docs.cube.dev/admin/deployment/dedicated/azure/private-link

How to publish an Azure Private Link Service and coordinate the connection so Cube's Dedicated Infrastructure reaches your VNet privately.

<Note>
  This page covers **backend connectivity** — Cube reaching into your network to
  query data sources, auth providers, BI APIs targeted by Semantic Layer Sync,
  and other upstream services. See
  [Backend and frontend connectivity][backend-frontend] for the full picture.
  For **frontend connectivity** (exposing Cube's APIs to your applications,
  browsers, BI tools, and embedded analytics clients), see
  [Private API Connectivity on AWS][aws-private-api-connectivity]; the
  equivalent pattern is available on Azure on request.
</Note>

[Azure Private Link][azure-docs-private-link] enables you to access Azure
PaaS services and Azure-hosted customer-owned/partner services over a private
endpoint in your virtual network. To set up a Private Link connection between
Cube's Dedicated Infrastructure and your own VNet, you'll need to prepare a
Private Link Service, share service details with the Cube team, and approve
the incoming connection request.

<Note>
  **Dedicated Infrastructure vs. Bring Your Own Cloud.** The flow described on
  this page — sharing service details with the Cube team and letting Cube create
  the private endpoint and DNS overrides — applies to
  [Dedicated Infrastructure][cube-region] operated by Cube.

  In a [Bring Your Own Cloud (BYOC)][azure-byoc] deployment, the Cube VNet lives
  in **your own Azure subscription**, so you own the networking. The role granted
  to the Cube Operator does not include permissions to manage Private DNS Zones,
  which means Cube cannot create the private endpoint or the DNS override on
  your behalf. In BYOC, create the private endpoint in the Cube VNet against the
  provider's Private Link Service Resource ID yourself, then create a Private DNS
  Zone for the TLS hostname and link it to the Cube VNet.
</Note>

## Preparing the Private Link Service

There are two common scenarios for preparing the Private Link Service:

* Connecting to a service in your Azure infrastructure
* Connecting to a service provided by a third party such as Snowflake,
  Databricks, Confluent Cloud, etc.

In the case of your own infrastructure, please follow the
[official Azure documentation][azure-docs-private-link-service] to configure
the Private Link Service behind a standard Azure Load Balancer.

If your data source is hosted in a third-party infrastructure, please follow
the vendor's documentation for creating and managing a Private Link Service.

## Configuring service visibility

Azure Private Link Service enables you to control the visibility of your
private endpoint. You'll need to configure access permissions to allow Cube
to connect to your service.

To allow Cube access, please go to **Azure Portal** → **Private Link
Services** → **Your service** → **Manage visibility** and add the following
subscription ID to the allowed list: `cd69336e-c628-4a88-a56e-86900a0df732`.

<Info>
  This is the Azure subscription ID of Cube's Private Link consumer
  subscription. Adding it authorizes Cube to discover your Private Link
  Service and create a private endpoint against it; nothing else in Cube's
  Azure estate gains access to your network.
</Info>

Alternatively, you can configure auto-approval for faster connection
establishment by adding the same subscription ID to the auto-approval list
under **Manage auto-approval**.

## Gathering required information

To request establishing a Private Link connection, please share the following
information with the Cube team:

* **Private Link Service Resource ID** (such as
  `/subscriptions/abc123/resourceGroups/myResourceGroup/providers/Microsoft.Network/privateLinkServices/myservice`)
* **Reference Name** for the record (such as "Snowflake-prod" or
  "databricks-dev")
* **Ports**: a list of ports that will be accessed through this connection
* **DNS Name(s)**: see [DNS and TLS](#dns-and-tls) below
* **Cube Region:** Private Link requires Cube to be hosted on
  [Dedicated Infrastructure][cube-region]. Specify which Cube Region should
  host your Dedicated Infrastructure.

## DNS and TLS

How your data source is addressed inside Cube depends on whether it speaks
TLS:

* **If the service uses TLS** (HTTPS, JDBC `Encrypt=true`, etc.), share the
  **DNS name(s)** the certificate is issued for — typically the same
  hostname your in-network clients already use to reach it. Cube creates
  internal DNS overrides inside the Dedicated Infrastructure so that the
  same hostname resolves to the Private Endpoint. Keeping the original
  hostname is what preserves TLS validity: the certificate's CN/SAN keeps
  matching what Cube dials.
* **If the service does not use TLS** and you don't supply a DNS name, the
  Cube team will share back an internal endpoint hostname (e.g. an
  Azure-assigned private-endpoint DNS name) that you can configure as the
  upstream when you wire the connection into Cube.

## Approving the connection

The connection approval process depends on your visibility configuration:

### Manual approval

If you haven't configured auto-approval, the Cube team will notify you once
the Private Endpoint connection request is sent. You can approve it by:

1. Going to **Azure Portal** → **Private Link Center** → **Private Link
   Services** → **Your Service** → **Private endpoint connections**.
2. Finding the pending connection from Cube.
3. Clicking **Approve** and optionally providing an approval message.

Alternatively, you can approve the connection from the resource itself if it
supports Private Link natively (e.g., Storage Accounts, SQL Databases).

### Auto-approval

If you've added Cube's subscription ID to the auto-approval list, the
connection will be automatically approved upon creation and no manual action
is required.

## Using the connection

Once the connection is established, you can access your data source by
addressing it via the DNS name(s) you supplied (TLS case) or the internal
endpoint hostname returned to you by the Cube team (non-TLS case).

## Supported Regions

Azure Private Link is available in all Azure commercial regions where
Dedicated Infrastructure can be provisioned. Azure operated by 21Vianet
(China) and Azure Government regions are not supported.

[azure-docs-private-link]: https://docs.microsoft.com/azure/private-link/

[azure-docs-private-link-service]: https://docs.microsoft.com/azure/private-link/create-private-link-service-portal

[cube-region]: /admin/deployment/infrastructure#understanding-cube-cloud-region

[azure-byoc]: /admin/deployment/dedicated/azure/byoc

[aws-private-api-connectivity]: /admin/deployment/dedicated/aws/private-api-connectivity

[backend-frontend]: /admin/deployment/dedicated#backend-and-frontend-connectivity


# Setting up VNet Peering on Azure
Source: https://docs.cube.dev/admin/deployment/dedicated/azure/vpc-peering

End-to-end checklist for VNet peering Cube's Dedicated Infrastructure with your Azure VNet for private data access.

<Note>
  This page covers **backend connectivity** — Cube reaching into your network to
  query data sources, auth providers, BI APIs targeted by Semantic Layer Sync,
  and other upstream services. See
  [Backend and frontend connectivity][backend-frontend] for the full picture.
  For **frontend connectivity** (exposing Cube's APIs to your applications,
  browsers, BI tools, and embedded analytics clients), see
  [Private API Connectivity on AWS][aws-private-api-connectivity]; the
  equivalent pattern is available on Azure on request.
</Note>

For cross-tenant peering in Azure, you assign the peering role to the service
principal of the peering party. Using the steps outlined below, you would
register the Cube tenant in your organization, grant peering access to the
Cube service principal, and hand over the information Cube needs to initiate
the peering.

## Granting peering access to Cube

### Add the Cube tenant to your organization

First, add the Cube tenant to your organization. Open the
[Azure Portal][azure-console] and go to **Azure Active Directory** →
**External Identities** → **Cross-tenant access settings** →
**Organizational Settings** → **Add Organization**.

For Tenant ID, enter `197e5263-87f4-4ce1-96c4-351b0c0c714a`.

Make sure that **B2B Collaboration** → **Inbound Access** →
**Applications** is set to **Allows access**.

### Register the Cube service principal at your organization

To register the Cube service principal for your organization, follow these
steps:

1. Log in with an account that has permissions to register Enterprise
   applications.
2. Open a browser tab and go to the following URL, replacing `<TENANT_ID>`
   with your tenant ID:
   `https://login.microsoftonline.com/<TENANT_ID>/oauth2/authorize?client_id=7f3afcf3-e061-4e1b-8261-f396646d7fc7&response_type=code&redirect_uri=https%3A%2F%2Fwww.microsoft.com%2F`
3. The Cube service principal has specific credentials. Check that the
   following details match exactly what you see on the dialog box that
   pops up:

   * Client ID: `7f3afcf3-e061-4e1b-8261-f396646d7fc7`
   * Name: `cube-dedicated-infra-peering-sp`

   Once you have confirmed that all the information is correct,
   select **Consent on behalf of your organization** and
   click **Accept**.

### Grant peering permissions on your virtual network

As the peering role you can use the built-in `Network Contributor` role or
create a custom role (e.g. `cube-peering-role`) with the following
permissions:

* `Microsoft.Network/virtualNetworks/virtualNetworkPeerings/write`
* `Microsoft.Network/virtualNetworks/peer/action`
* `Microsoft.ClassicNetwork/virtualNetworks/peer/action`
* `Microsoft.Network/virtualNetworks/virtualNetworkPeerings/read`
* `Microsoft.Network/virtualNetworks/virtualNetworkPeerings/delete`

On the [Azure Portal][azure-console], go to **Virtual networks** →
*Virtual Network Name* → **Access Control (IAM)** → **Add** →
**Add role assignment** and fill in the following details:

* Role: `Network Contributor` or `cube-peering-role`
* Members: `cube-dedicated-infra-peering-sp`

## Information required by Cube

When reaching out to Cube support, please provide the following information:

* **Virtual Network ID:** Find this at **Virtual Networks** →
  *Virtual Network Name* → **Overview** → **JSON view** →
  **Resource ID** on the [Azure Portal][azure-console].
* **Virtual Network Address Spaces:** Find this at **Virtual Networks**
  → *Virtual Network Name* → **Overview** → **JSON view** →
  **properties** → **addressSpace** on the [Azure Portal][azure-console].
* **Tenant ID:** Find this in **Azure Active Directory** →
  **Properties** → **Tenant ID** section of the
  [Azure Portal][azure-console].
* **Cube Region:** VNet Peering requires Cube to be hosted on
  [Dedicated Infrastructure][cube-region]. Specify which Cube Region should
  host your Dedicated Infrastructure.

## Firewall and routing

Once the peering is established, allow traffic from Cube's VNet CIDR block to
reach your data source:

1. **Network Security Groups (NSGs)** attached to the data-source subnet (or
   the resource itself) must include an inbound rule that permits TCP traffic
   from Cube's VNet CIDR on the database port. For example, for PostgreSQL:

   | Priority | Source                        | Source Port | Destination      | Service / Port | Action |
   | -------- | ----------------------------- | ----------- | ---------------- | -------------- | ------ |
   | 1000     | Cube VNet CIDR (e.g. 10.x/16) | `*`         | `VirtualNetwork` | TCP / 5432     | Allow  |

   Cube's VNet CIDR is shared with you alongside the peering request and is
   also visible in the Azure Portal on the **Virtual networks** →
   **\<your VNet>** → **Peerings** → **\<Cube peering>** → **Address
   space** field.

2. **Azure Firewall / third-party NVAs**: if traffic between your subnets
   transits a firewall, add a rule permitting TCP from the Cube VNet CIDR to
   the data source's IP and port.

3. **User-defined routes (UDRs)**: confirm that the route tables on your
   subnets do not blackhole Cube's CIDR via `0.0.0.0/0` next-hop appliances.
   Ensure traffic destined for Cube's VNet CIDR is routed to the **Virtual
   network peering** next-hop.

4. **Data source firewall**: if the resource has its own firewall (e.g. an
   Azure SQL Server firewall or a PaaS-level allow-list), add Cube's VNet
   CIDR there as well.

## Supported Regions

VNet Peering is available in all Azure commercial regions where Dedicated
Infrastructure can be provisioned. Azure operated by 21Vianet (China) and
Azure Government regions are not supported.

[azure-console]: https://portal.azure.com

[cube-region]: /admin/deployment/infrastructure#understanding-cube-cloud-region

[aws-private-api-connectivity]: /admin/deployment/dedicated/aws/private-api-connectivity

[backend-frontend]: /admin/deployment/dedicated#backend-and-frontend-connectivity


# Bring Your Own Cloud on GCP
Source: https://docs.cube.dev/admin/deployment/dedicated/gcp/byoc

Project setup, permissions, and provisioning flow for deploying Cube BYOC inside a dedicated GCP project.

With Bring Your Own Cloud (BYOC) on Google Cloud Platform (GCP), all the components interacting with private data are deployed on
the customer infrastructure on GCP and managed by the Cube Control Plane via the Cube Operator.
This document provides step-by-step instructions for deploying Cube BYOC on GCP.

## Prerequisites

The bulk of provisioning work will be done remotely by Cube automation.
However, to get started, you'll need:

### Required Information

* **GCP Project ID:** A dedicated GCP project ID that will exclusively host Cube-managed infrastructure.
  This should be a new, isolated project created specifically for Cube BYOC.
* **GCP Region:** [The GCP region][gcp-docs-regions] where the BYOC resources
  should be deployed.

### Required Permissions

You'll need to have the following permissions in your GCP organization/folder to complete the setup:

* **Project Creator** (`roles/resourcemanager.projectCreator`) - To create a new dedicated project
* **Project IAM Admin** (`roles/resourcemanager.projectIamAdmin`) - To grant permissions in the project
* **Billing Account User** (`roles/billing.user`) - To link billing to the new project

If you don't have these permissions, contact your GCP organization administrator.

## Provisioning access

### Step 1: Create a dedicated GCP project

We strongly recommend creating a dedicated GCP project that will exclusively host
Cube-managed infrastructure. This project isolation approach simplifies permission
management and provides clear resource boundaries.

1. Navigate to the [GCP Console][gcp-console]
2. Click **Create Project**
3. Enter a project name (e.g., "cube-cloud-byoc")
4. Note the **Project ID** (not the project name) - you'll need this for subsequent steps
5. Select your billing account
6. Click **Create**

<Info>
  Make sure billing is enabled for the project. You can verify this by navigating to
  **Billing** in the GCP Console and confirming the project is linked to an active billing account.
</Info>

### Step 2: Enable required APIs

Before granting permissions, enable the necessary GCP APIs in your dedicated project.
This ensures that subsequent API calls will work correctly.

**Required APIs:**

* **Compute Engine API** (`compute.googleapis.com`) - For VPC networks and compute resources
* **Kubernetes Engine API** (`container.googleapis.com`) - For GKE clusters
* **Cloud Storage API** (`storage.googleapis.com`) - For Cube Store buckets
* **IAM API** (`iam.googleapis.com`) - For service account management
* **Cloud Resource Manager API** (`cloudresourcemanager.googleapis.com`) - For project IAM operations
* **Service Networking API** (`servicenetworking.googleapis.com`) - For private service connectivity

<Info>
  **Note:** DNS and Artifact Registry APIs are not required in your project. Cube manages DNS in its own project,
  and container images are pulled from Cube's Artifact Registry using Cube-provided credentials.
</Info>

You can enable these APIs through the [API Library][gcp-api-library] in the GCP Console,
or use the `gcloud` command:

```bash theme={"dark"}
# Set your project ID
export PROJECT_ID="your-cube-byoc-project-id"

# Enable all required APIs
gcloud services enable \
  compute.googleapis.com \
  container.googleapis.com \
  storage.googleapis.com \
  iam.googleapis.com \
  cloudresourcemanager.googleapis.com \
  servicenetworking.googleapis.com \
  --project=$PROJECT_ID
```

### Step 3: Grant IAM permissions

In order to manage resources in the Cube-dedicated GCP project, the Cube service principal
needs to be granted administrative permissions to a set of services.

Navigate to **IAM & Admin > IAM** in your dedicated project and add the following IAM
binding for the Cube service account:

**Principal:** `cube-cloud-byoc-installer@cube-cloud-byoc.iam.gserviceaccount.com`

**Roles:**

* **Compute Admin** (`roles/compute.admin`) - Allows creation and management of VPC networks, subnets, routers, NAT gateways, firewall rules, IP addresses, and Private Service Connect endpoints
* **Kubernetes Engine Admin** (`roles/container.admin`) - Allows creation and management of GKE clusters and node pools
* **Storage Admin** (`roles/storage.admin`) - Allows creation and management of Cloud Storage buckets for Cube Store
* **Service Account Admin** (`roles/iam.serviceAccountAdmin`) - Allows creation and management of service accounts for cluster nodes and workload identity
* **Service Account Key Admin** (`roles/iam.serviceAccountKeyAdmin`) - Allows creation and management of service account keys for Cube Store authentication
* **Project IAM Admin** (`roles/resourcemanager.projectIamAdmin`) - Allows granting IAM permissions to created resources (e.g., bucket access for service accounts)

You can grant these permissions through the Google Cloud Console UI or using the
`gcloud` command-line tool:

```bash theme={"dark"}
# Set your project ID (replace with your actual project ID)
export PROJECT_ID="your-cube-byoc-project-id"

# Set the Cube service account (use this exact value)
export CUBE_SA="cube-cloud-byoc-installer@cube-cloud-byoc.iam.gserviceaccount.com"

# Grant all required roles
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CUBE_SA" \
  --role="roles/compute.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CUBE_SA" \
  --role="roles/container.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CUBE_SA" \
  --role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CUBE_SA" \
  --role="roles/iam.serviceAccountAdmin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CUBE_SA" \
  --role="roles/iam.serviceAccountKeyAdmin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CUBE_SA" \
  --role="roles/resourcemanager.projectIamAdmin"
```

### Step 4: Grant Service Account User permissions

Additionally, the Cube service account needs permission to use the default Compute Engine service account for GKE node pools.

<Info>
  Make sure you have the `PROJECT_ID` and `CUBE_SA` environment variables set from Step 3 before running these commands.
</Info>

Run the following command to grant the necessary permissions:

```bash theme={"dark"}
# Get the project number
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

# Grant the Cube service account permission to use the default compute service account
gcloud iam service-accounts add-iam-policy-binding \
  ${PROJECT_NUMBER}-compute@developer.gserviceaccount.com \
  --member="serviceAccount:$CUBE_SA" \
  --role="roles/iam.serviceAccountUser" \
  --project=$PROJECT_ID
```

This allows the Cube service account to create GKE clusters that use the project's default compute service account for worker nodes.

### Step 5: Verify setup

Before notifying Cube, verify that all permissions and APIs are correctly configured:

```bash theme={"dark"}
# Verify APIs are enabled
gcloud services list --enabled --project=$PROJECT_ID | grep -E '(compute|container|storage|iam|cloudresourcemanager|servicenetworking)'

# Verify IAM bindings for the Cube service account
gcloud projects get-iam-policy $PROJECT_ID \
  --flatten="bindings[].members" \
  --format="table(bindings.role)" \
  --filter="bindings.members:serviceAccount:cube-cloud-byoc-installer@cube-cloud-byoc.iam.gserviceaccount.com"

# Verify Service Account User permission
gcloud iam service-accounts get-iam-policy \
  ${PROJECT_NUMBER}-compute@developer.gserviceaccount.com \
  --project=$PROJECT_ID
```

If all commands return the expected results, you're ready to proceed with deployment.

## Deployment

The actual deployment will be done by Cube automation. All that's left to
do is notify your Cube contact point that access has been granted, and pass
along your GCP Project ID and Region information.

After deployment, Cube will manage the following resources in your dedicated project:

* A VPC network with subnets, Cloud Router, and Cloud NAT for outbound connectivity
* A GKE cluster with node pools for running Cube applications
* Cloud Storage buckets for Cube Store data
* Service accounts and IAM bindings for secure resource access
* Firewall rules and network policies for security

[gcp-console]: https://console.cloud.google.com/

[gcp-docs-regions]: https://cloud.google.com/compute/docs/regions-zones

[gcp-api-library]: https://console.cloud.google.com/apis/library


# Dedicated Infrastructure on GCP
Source: https://docs.cube.dev/admin/deployment/dedicated/gcp/index

Connect Cube's Dedicated Infrastructure on GCP to your VPC networks via Private Service Connect or VPC Peering, or deploy the entire data plane inside your own GCP project via BYOC.

On GCP, Cube offers single-tenant Dedicated Infrastructure operated by Cube,
and Bring Your Own Cloud (BYOC) operated inside your own GCP project. Both
options support private network connectivity to your data sources.

## Backend connectivity (Cube → your network)

Use these options to give Cube private access to your data sources, auth
providers, BI APIs targeted by Semantic Layer Sync, and anything else Cube
needs to query. See [Backend and frontend connectivity][backend-frontend] for
the full picture.

* [**Private Service Connect**][gcp-private-service-connect] — connect to
  data sources exposed through GCP Service Attachments without routing traffic
  over the public internet.
* [**VPC Peering**][gcp-vpc-peering] — establish a VPC peering connection
  between the Cube VPC and your own VPC.

## Frontend connectivity (your clients → Cube)

Expose Cube's APIs to your applications, browsers, BI tools, embedded
analytics clients, and Semantic Layer Sync-generated configs over a private
network. The pattern mirrors the AWS implementation documented in
[Private API Connectivity on AWS][aws-private-api-connectivity];
[contact us](https://cube.dev/contact) to enable the equivalent on GCP for
your tenant.

## Bring Your Own Cloud

If you'd like the entire Cube data plane to live inside your own GCP project,
see [Bring Your Own Cloud on GCP][gcp-byoc].

[gcp-private-service-connect]: /admin/deployment/dedicated/gcp/private-service-connect

[gcp-vpc-peering]: /admin/deployment/dedicated/gcp/vpc-peering

[gcp-byoc]: /admin/deployment/dedicated/gcp/byoc

[aws-private-api-connectivity]: /admin/deployment/dedicated/aws/private-api-connectivity

[backend-frontend]: /admin/deployment/dedicated#backend-and-frontend-connectivity


# Setting up Google Private Service Connect
Source: https://docs.cube.dev/admin/deployment/dedicated/gcp/private-service-connect

How to publish a Service Attachment and coordinate Private Service Connect so Cube's Dedicated Infrastructure reaches your VPC privately.

<Note>
  This page covers **backend connectivity** — Cube reaching into your network to
  query data sources, auth providers, BI APIs targeted by Semantic Layer Sync,
  and other upstream services. See
  [Backend and frontend connectivity][backend-frontend] for the full picture.
  For **frontend connectivity** (exposing Cube's APIs to your applications,
  browsers, BI tools, and embedded analytics clients), see
  [Private API Connectivity on AWS][aws-private-api-connectivity]; the
  equivalent pattern is available on GCP on request.
</Note>

[Private Service Connect][gcp-docs-psc] (PSC) provides private connectivity
between VPC networks in different projects or organizations, without VPC
peering or exposing your traffic to the public internet. To set up a PSC
connection between Cube's Dedicated Infrastructure and your own VPC, you'll
need to publish a Service Attachment, share its details with the Cube team,
and approve the incoming connection request.

<Note>
  **Dedicated Infrastructure vs. Bring Your Own Cloud.** The flow described on
  this page — sharing service details with the Cube team and letting Cube create
  the PSC endpoint and DNS overrides — applies to
  [Dedicated Infrastructure][cube-region] operated by Cube.

  In a [Bring Your Own Cloud (BYOC)][gcp-byoc] deployment, the Cube VPC lives in
  **your own GCP project**, so you own the networking. The service account
  granted to the Cube Operator does not include Cloud DNS admin permissions,
  which means Cube cannot create the PSC endpoint or the private DNS zone needed
  for the hostname override on your behalf. In BYOC, create the PSC endpoint in
  the Cube VPC against the provider's Service Attachment yourself, then create a
  Cloud DNS private zone for the TLS hostname and attach it to the Cube VPC.
</Note>

## Preparing the Service Attachment

There are two common scenarios for preparing the Service Attachment:

* Connecting to a service in your GCP infrastructure
* Connecting to a service provided by a third party such as Snowflake,
  Databricks, Confluent Cloud, etc.

In the case of your own infrastructure, follow the
[official GCP documentation][gcp-docs-publish-service] to publish a Service
Attachment that points at an
[internal passthrough or proxy Network Load Balancer][gcp-docs-internal-lb]
in front of your data source.

If your data source is hosted in a third-party infrastructure, follow the
vendor's documentation for creating and managing a Service Attachment.

## Allowing the Cube consumer project

PSC service attachments can restrict which consumer projects are allowed to
create a PSC endpoint against them. Cube's PSC consumer project is
`cube-cloud-dedicated`.

In the GCP Console, go to **Network services → Private Service Connect →
Published services → \<your service>** and add `cube-cloud-dedicated` to
**Accepted projects**. For faster connection establishment, you can also
add the same project to the **auto-accept** list so the connection is
approved automatically when Cube initiates it.

<Info>
  `cube-cloud-dedicated` is the GCP project Cube uses to host Dedicated
  Infrastructure PSC endpoints. Adding it to your accepted-projects list
  authorizes Cube to create a private endpoint against your Service
  Attachment; nothing else in Cube's GCP estate gains access to your network.
</Info>

## Gathering required information

To request establishing a PSC connection, please share the following
information with the Cube team:

* **Service Attachment URI** (such as
  `projects/<your-project>/regions/<region>/serviceAttachments/<name>`)
* **Reference Name** for the record (such as "Snowflake-prod" or
  "clickhouse-dev")
* **Ports**: a list of ports that will be accessed through this connection
* **DNS Name(s)**: see [DNS and TLS](#dns-and-tls) below
* **Cube Region:** PSC requires Cube to be hosted on
  [Dedicated Infrastructure][cube-region]. Specify which Cube Region should
  host your Dedicated Infrastructure.

## DNS and TLS

How your data source is addressed inside Cube depends on whether it speaks
TLS:

* **If the service uses TLS** (HTTPS, JDBC `sslmode=require`, etc.), share
  the **DNS name(s)** the certificate is issued for — typically the same
  hostname your in-network clients already use to reach it. Cube creates
  internal DNS overrides inside the Dedicated Infrastructure so that the
  same hostname resolves to the PSC endpoint. Keeping the original hostname
  is what preserves TLS validity: the certificate's CN/SAN keeps matching
  what Cube dials.
* **If the service does not use TLS** and you don't supply a DNS name, the
  Cube team will share back an internal endpoint hostname that you can
  configure as the upstream when you wire the connection into Cube.

## Accepting the connection

The approval flow depends on how your Service Attachment is configured:

* **Manual acceptance.** Cube will notify you once the connection request
  has been sent. Approve it in the GCP Console under **Network services →
  Private Service Connect → Published services → \<your service> →
  Connected endpoints**, then select the pending connection and click
  **Accept**.
* **Auto-accept.** If you added `cube-cloud-dedicated` to the auto-accept
  list, the connection is approved automatically upon creation and no
  further action is required.

## Using the connection

Once the connection is established, you can access your data source by
addressing it via the DNS name(s) you supplied (TLS case) or the internal
endpoint hostname returned to you by the Cube team (non-TLS case).

## Supported Regions

Private Service Connect is available in all GCP commercial regions where
Dedicated Infrastructure can be provisioned. GCP regions in mainland China
(serviced by partner providers) are not supported.

[gcp-docs-psc]: https://cloud.google.com/vpc/docs/private-service-connect

[gcp-docs-publish-service]: https://cloud.google.com/vpc/docs/configure-private-service-connect-producer

[gcp-docs-internal-lb]: https://cloud.google.com/load-balancing/docs/internal

[cube-region]: /admin/deployment/infrastructure#understanding-cube-cloud-region

[gcp-byoc]: /admin/deployment/dedicated/gcp/byoc

[aws-private-api-connectivity]: /admin/deployment/dedicated/aws/private-api-connectivity

[backend-frontend]: /admin/deployment/dedicated#backend-and-frontend-connectivity


# Setting up VPC Peering on GCP
Source: https://docs.cube.dev/admin/deployment/dedicated/gcp/vpc-peering

End-to-end checklist for VPC peering Cube's Dedicated Infrastructure with your GCP VPC network for private data access.

<Note>
  This page covers **backend connectivity** — Cube reaching into your network to
  query data sources, auth providers, BI APIs targeted by Semantic Layer Sync,
  and other upstream services. See
  [Backend and frontend connectivity][backend-frontend] for the full picture.
  For **frontend connectivity** (exposing Cube's APIs to your applications,
  browsers, BI tools, and embedded analytics clients), see
  [Private API Connectivity on AWS][aws-private-api-connectivity]; the
  equivalent pattern is available on GCP on request.
</Note>

VPC Peering requires Cube to be hosted on
[Dedicated Infrastructure][cube-region]. Let the Cube team know which Cube
Region should host your Dedicated Infrastructure.

Cube will provision the Dedicated VPC and provide the following information
you can use to create the peering request:

* **GCP Project ID:** `cube-cloud-dedicated` (the project Cube uses to host
  Dedicated VPCs).
* **VPC Network Name:** shared with you by the Cube team once the Dedicated
  VPC is provisioned.

## Setup

### Creating the peering connection

After receiving the information above, create a
[VPC peering request][gcp-docs-vpc-peering], either through the
[GCP Web Console][gcp-console] or an infrastructure-as-code tool. To send a
VPC peering request through the Google Cloud Console, follow
[the instructions here][gcp-docs-create-vpc-peering], with the following
amendments:

* In Step 6, use the project ID `cube-cloud-dedicated` and the network name
  provided by Cube.
* In Step 7, ensure **Import custom routes** and **Export custom routes** are
  selected so that the necessary routes are created.

### Firewall and routing

Once the peering is established, configure your VPC firewall rules to allow
inbound TCP traffic from Cube's VPC CIDR block to your data source on the
database port. Cube's VPC CIDR is shared with you alongside the peering
request and is also visible in the GCP Console on the **VPC network** →
**\<your VPC>** → **VPC network peering** → **\<Cube peering>** page as
the **Peer VPC network** subnet ranges.

If your data source is in a different project or subnet that transits a
firewall or Cloud NAT, add a matching allow rule for Cube's CIDR there as
well.

## Cloud SQL

Google Cloud SQL databases
[can only be peered to a VPC within the same GCP project][gcp-docs-vpc-peering-restrictions].
If you need Cube to reach a Cloud SQL instance, prefer
[Private Service Connect][gcp-private-service-connect] (Cloud SQL supports
PSC natively), or alternatively provision a small VM in your GCP project
running the [Cloud SQL Auth Proxy][gcp-cloudsql-auth-proxy].

## Supported Regions

VPC Peering is available in all GCP commercial regions where Dedicated
Infrastructure can be provisioned. GCP regions in mainland China (serviced
by partner providers) are not supported.

[gcp-cloudsql-auth-proxy]: https://cloud.google.com/sql/docs/mysql/connect-admin-proxy

[gcp-console]: https://console.cloud.google.com/

[gcp-docs-create-vpc-peering]: https://cloud.google.com/vpc/docs/using-vpc-peering#creating_a_peering_configuration

[gcp-docs-vpc-peering]: https://cloud.google.com/vpc/docs/vpc-peering

[gcp-docs-vpc-peering-restrictions]: https://cloud.google.com/vpc/docs/vpc-peering#restrictions

[cube-region]: /admin/deployment/infrastructure#understanding-cube-cloud-region

[gcp-private-service-connect]: /admin/deployment/dedicated/gcp/private-service-connect

[aws-private-api-connectivity]: /admin/deployment/dedicated/aws/private-api-connectivity

[backend-frontend]: /admin/deployment/dedicated#backend-and-frontend-connectivity


# Dedicated Infrastructure
Source: https://docs.cube.dev/admin/deployment/dedicated/index

Run Cube on dedicated single-tenant infrastructure (managed by Cube) or on your own AWS, Azure, or GCP account (BYOC), with private connectivity to your data sources and APIs.

Cube offers two flavors of single-tenant deployment: **Dedicated Infrastructure**
managed by Cube in our cloud accounts, and **Bring Your Own Cloud (BYOC)** managed
by Cube inside your own cloud account. Both options give you isolated compute,
the ability to route traffic over private networks, and integrations with
services in your VPC or VNet.

<Note>
  Available on the [Enterprise plan](https://cube.dev/pricing) with the
  [Dedicated Infrastructure][ref-dedicated-infra] add-on.
</Note>

## Single-tenant Cube cluster

With Dedicated Infrastructure, Cube provisions and operates a **single-tenant**
cluster for you in a Cube-managed account on AWS, GCP, or Azure. *Single-tenant*
means the cluster — VPC/VNet, compute, storage, and the Cube data plane that
runs your deployments — is dedicated entirely to your organization and not
shared with any other customer. The cluster lives in a Cube
[Region][cube-region], can be peered or PrivateLink/PSC-connected to your own
networks, and can optionally expose Cube's APIs to your network so that no Cube
traffic ever crosses the public internet.

## Bring Your Own Cloud (BYOC)

On the Enterprise plan, Cube is also available as **Bring Your Own Cloud**: all
components that interact with your private data are deployed inside your own
AWS, Azure, or GCP account and managed remotely by the Cube Control Plane via
the Cube Operator. This keeps all data plane resources within your boundary
while preserving the managed-service experience.
[Contact us](https://cube.dev/contact) for details.

## Backend and frontend connectivity

There are two distinct directions in which Cube exchanges traffic with your
network, and each has its own connectivity story:

* **Backend connectivity** — traffic that flows **from Cube into your network**.
  Cube uses these connections to query the things it needs to function:
  databases and warehouses, auth providers (e.g. an internal OIDC issuer),
  upstream BI APIs that Semantic Layer Sync targets, and any other service the
  Cube data plane has to reach. PrivateLink, Private Link, Private Service
  Connect, and Peering on the provider pages below all configure backend
  connectivity.
* **Frontend connectivity** — traffic that flows **from your network into
  Cube**. Anything that needs to query Cube falls in this bucket: the Cube UI
  running in employee browsers, application servers, BI tools, embedded
  analytics clients, and Semantic Layer Sync-generated configs. Frontend
  connectivity is currently documented for AWS in
  [Private API Connectivity on AWS][aws-private-api-connectivity], and
  equivalent patterns are available on Azure and GCP on request.

Most enterprise deployments end up using both: a backend
PrivateLink/PSC/peering into the customer's data network, plus a frontend
private API endpoint so the Cube UI and BI tools talk to Cube over the same
private fabric.

## Choose a provider

<CardGroup>
  <Card title="Amazon Web Services" icon="brand-aws" href="/admin/deployment/dedicated/aws">
    Dedicated Infrastructure, BYOC, and private connectivity on AWS.
  </Card>

  <Card title="Google Cloud Platform" icon="google" href="/admin/deployment/dedicated/gcp">
    Dedicated Infrastructure and BYOC on GCP.
  </Card>

  <Card title="Microsoft Azure" icon="microsoft" href="/admin/deployment/dedicated/azure">
    Dedicated Infrastructure, BYOC, and private connectivity on Azure.
  </Card>
</CardGroup>

[ref-dedicated-infra]: /admin/deployment/infrastructure#dedicated-infrastructure

[aws-private-api-connectivity]: /admin/deployment/dedicated/aws/private-api-connectivity

[cube-region]: /admin/deployment/infrastructure#understanding-cube-cloud-region


# Bring-Your-Own Pre-aggregation Storage
Source: https://docs.cube.dev/admin/deployment/dedicated/pre-aggregation-storage

Supply your own object storage bucket as the backend for Cube Store pre-aggregated data so that all data at rest stays within your infrastructure.

On the Enterprise plan, Dedicated Infrastructure customers can supply their
own object storage bucket to be used as the underlying storage for Cube Store
pre-aggregated data. This lets you keep all data at rest fully within your
own infrastructure while still leveraging the managed compute and operations
of Dedicated Infrastructure.

<Note>
  Available on the [Enterprise plan](https://cube.dev/pricing) with Dedicated
  Infrastructure. [Contact us](https://cube.dev/contact) to enable this option
  for your tenant.
</Note>

## AWS — S3

To activate this option on AWS:

1. Create an S3 bucket in the same region as your Cube Region.
2. Generate a new AWS Access Key with full access to that bucket.
3. Request activation from your Customer Success Manager and share the
   following:
   * **AWS Access Key ID**
   * **AWS Secret Access Key**
   * **S3 Bucket ARN**

## GCP — Cloud Storage

To activate this option on GCP:

1. Create a Cloud Storage bucket in the same region as your Cube Region.
2. Create a service account with full access to that bucket and generate a
   JSON service-account key.
3. Request activation from your Customer Success Manager and share the
   following:
   * **GCS Bucket Name**
   * **Service-account JSON key** (transferred securely)

## Azure — Blob Storage

To activate this option on Azure:

1. Create a Storage Account and Blob container in the same region as your
   Cube Region.
2. Create a SAS token (or service principal) with full read/write/delete
   access to the container.
3. Request activation from your Customer Success Manager and share the
   following:
   * **Storage Account name**
   * **Container name**
   * **Access credentials** (SAS token or service-principal details)

## Supported Regions

Bring-Your-Own Pre-aggregation Storage is available wherever Dedicated
Infrastructure is supported on the corresponding cloud — see the per-provider
[Supported Regions](#supported-regions) sections in the connectivity docs for
the exact list. Government and China regions are not supported.


# Deployment types
Source: https://docs.cube.dev/admin/deployment/deployment-types

Cube provides three deployment types: Shared, Dedicated, and Multi-cluster.

* [Shared](#shared) — designed for development use cases. Runs on compute
  shared with other deployments within the selected region.
* [Dedicated](#dedicated) — designed for production workloads and
  high-availability. Runs on compute dedicated to your deployment.
* [Multi-cluster](#multi-cluster) — designed for demanding production workloads,
  high-scalability, high-availability, and advanced multi-tenancy configurations.
  Runs on multiple Dedicated deployments.

## Shared

<Note>
  Available for free, no credit card required. Your free trial is limited to 2
  Shared deployments and only 1,000 queries per day. Upgrade to
  [any paid plan](https://cube.dev/pricing) to unlock all features.
</Note>

Shared deployments run on compute shared with other deployments within the
selected region, which keeps the cost low but means resources aren't reserved
for you exclusively.

<Note>
  If your account uses [single-tenant infrastructure][ref-dedicated-infra],
  Shared deployments are only shared with your other deployments on that
  infrastructure — never with other customers. Your environment remains fully
  isolated at the infrastructure level.
</Note>

Shared deployments are designed for development use cases only. This makes
it easy to get started with Cube quickly, and also allows you to build and
query pre-aggregations on-demand.

Shared deployments don't have dedicated [refresh workers][ref-refresh-worker]
and, consequently, they do not refresh pre-aggregations on schedule.

Shared deployments do not provide high-availability nor do they guarantee
fast response times. Shared deployments also [auto-suspend][ref-auto-sus]
after 30 minutes of inactivity, which can cause the first request after the
deployment wakes up to take additional time to process. They also have
[limits][ref-limits] on the maximum number of queries per day and the maximum
number of Cube Store Workers. We **strongly** advise not using a Shared
deployment in a production environment, it is for testing and learning about
Cube only and will not deliver a production-level experience for your users.

You can try a Shared deployment by
[signing up for Cube](https://cubecloud.dev/auth/signup) to try it free
(no credit card required).

## Dedicated

<Note>
  Available on [all paid plans](https://cube.dev/pricing).
</Note>

Dedicated deployments run on compute dedicated exclusively to your deployment,
giving you predictable performance and full control over capacity.

Dedicated deployments are designed to support high-availability production
workloads. It consists of several key components, including starting with 2 Cube
API instances, 1 Cube Refresh Worker and 2 Cube Store Routers - all of which run
on compute dedicated to your deployment. The deployment can automatically scale
to meet the needs of your workload by adding more components as necessary;
check the page on [scalability][ref-scalability] to learn more.

## Multi-cluster

Multi-cluster deployments are designed for demanding production workloads,
high-scalability, high-availability, and large [multi-tenancy][ref-multitenancy]
configurations, e.g., with more than 100 tenants.

<Note>
  Available on [Premium and above plans](https://cube.dev/pricing).
</Note>

It provides you with two options:

* Scale the number of [Dedicated](#dedicated) deployments serving your
  workload, allowing to route requests over up to 10 Dedicated deployments and
  up to 100 API instances.
* Optionally, scale the number of Cube Store routers, allowing for increased
  Cube Store querying performance.

Each Dedicated deployment is billed separately, and all Dedicated deployments
can use auto-scaling to match demand.

### Configuring Multi-cluster

To switch your deployment to Multi-cluster, navigate to
**Settings → General**, select it under **Type**, and confirm
with **✓**.

To set the number of Dedicated deployments within your Multi-cluster
deployment, navigate to **Settings → Configuration** and edit
**Number of clusters**.

### Routing traffic between Dedicated deployments

Cube routes requests between multiple Dedicated deployments within a
Multi-cluster deployment based on [`context_to_app_id`][ref-ctx-to-app-id].
In most cases, it should return an identifier that does not change over time
for each tenant.

The following implementation will make sure that all requests from a
particular tenant are always routed to the same Dedicated deployment. This
approach ensures that only one Dedicated deployment keeps compiled data model
cache for each tenant and serves its requests. It allows to reduce the
footprint of the compiled data model cache on individual Dedicated deployments.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config
   
  @config('context_to_app_id')
  def context_to_app_id(ctx: dict) -> str:
    return f"CUBE_APP_{ctx['securityContext']['tenant_id']}"
  ```

  ```js title="JavaScript" theme={"dark"}
  module.exports = {
    contextToAppId: ({ securityContext }) => {
      return `CUBE_APP_${securityContext.tenant_id}`
    }
  }
  ```
</CodeGroup>

<Warning>
  If your implementation of `context_to_app_id` returns identifiers that change
  over time for each tenant, requests from one tenant would likely hit multiple
  Dedicated deployments and you would not have the benefit of reduced memory
  footprint. Also you might see 502 or timeout errors in case of different
  deployment nodes would return different `context_to_app_id` results for the
  same request.
</Warning>

## Switching between deployment types

To switch a deployment's type, go to the deployment's **Settings** screen
and select from the available options.

[ref-ctx-to-app-id]: /reference/configuration/config#context_to_app_id

[ref-limits]: /admin/deployment/limits#resources

[ref-scalability]: /admin/deployment/scalability

[ref-multitenancy]: /embedding/multitenancy

[ref-auto-sus]: /admin/deployment/auto-suspension

[ref-refresh-worker]: /cube-core/architecture#refresh-worker

[ref-dedicated-infra]: /admin/deployment/infrastructure#dedicated-infrastructure


# Encryption keys
Source: https://docs.cube.dev/admin/deployment/encryption-keys

The Encryption Keys page in Cube Cloud allows to manage data-at-rest encryption in Cube Store.

<Note>
  Available on the [Enterprise plan](https://cube.dev/pricing).
  Also requires the M [Cube Store Worker tier](/admin/account-billing/pricing#cube-store-worker-tiers).
</Note>

Navigate to **Settings → Encryption Keys** in your Cube Cloud deployment
to [provide](#add-a-key), [rotate](#rotate-a-key), or [drop](#drop-a-key)
your own customer-managed keys (CMK) for Cube Store.

## Customer-managed keys for Cube Store

On the **Encryption Keys** page, you can see all previously provided keys:

<Frame>
  <img />
</Frame>

### Add a key

To add an encryption key, click **Create** to open a modal window.
Provide the key name and the key value: an 256-bit AES encryption key, encoded
in [standard Base64][link-base64] in its canonical representation.

<Frame>
  <img />
</Frame>

**Once the first encryption key is added, Cube Store will assume that data-at-rest
encryption is enabled.** After that, querying unencrypted pre-aggregation partitions
will yield the following error: `Invalid Parquet file in encrypted mode. File (or
at least the Parquet footer) is not encrypted`.

<Info>
  It may take a few minutes for any changes to encryption keys to take effect.
</Info>

After the refresh worker builds or rebuilds pre-aggregation partitions with
respect to their [refresh strategy][ref-pre-aggs-refresh-strategy] or after they
are [built manually][ref-pre-aggs-build-manually], their data will be encrypted.

**For encryption, the most recently added encryption key is used.** For decryption,
all previously provided keys can be used, if there are still any pre-aggregation
partitions encrypted with those keys.

### Rotate a key

To rotate an encryption key, you have to [add a new key](#add-a-key) and then
rebuild pre-aggregation partitions using this key, either by the means of the
refresh worker, or manually.

You can check which encryption key is used by any pre-aggregation partition by
querying `system.tables` in Cube Store via [SQL Runner][ref-sql-runner]:

<Frame>
  <img />
</Frame>

<Warning>
  Only newly built or rebuilt pre-aggregation partitions will be encrypted using the
  newly added encryption key. Previously built partitions will still be encrypted
  using previously provided keys. If you [drop a key](#drop-a-key) before these
  partitions are rebuilt, querying them will yield an error.
</Warning>

<Info>
  If you're using [incremental pre-aggregations][ref-pre-aggs-incremental], the
  refresh worker will likely only rebuild some of their partitions. You have to [rebuild
  them manually][ref-pre-aggs-build-manually] to ensure that the new encryption key
  is used.
</Info>

### Drop a key

To drop an encryption key, click **Delete** next to it.

[ref-cube-store-encryption]: /docs/pre-aggregations/running-in-production#data-at-rest-encryption

[link-base64]: https://datatracker.ietf.org/doc/html/rfc4648#section-4

[ref-pre-aggs-refresh-strategy]: /docs/pre-aggregations/using-pre-aggregations#refresh-strategy

[ref-pre-aggs-build-manually]: /admin/monitoring/pre-aggregations

[ref-pre-aggs-incremental]: /reference/data-modeling/pre-aggregations#incremental

[ref-sql-runner]: /docs/data-modeling/sql-runner


# Deployment environments
Source: https://docs.cube.dev/admin/deployment/environments

Outlines production, staging, and per-developer environments and how they differ inside one Cube deployment.

Every Cube Cloud deployment provides a number of environments:

* A single [production environment](#production-environment).
* Multiple [staging environments](#staging-environments).
* Per-user [development environments](#development-environments).

## Production environment

This is the main environment. It runs the data model from the *main branch*.

### Availability

The production environment is *always available* unless [suspended][ref-suspend].

### Resources and costs

Depending on the [deployment type][ref-deployment-types], the production environment
either runs on a Shared deployment or on a Dedicated deployment with [multiple API
instances][ref-api-instance-scalability], incurring [relevant
costs][ref-pricing-deployment-tiers].

### Cube version

Production environments run a [Cube version][ref-version] from the selected
[update channel][ref-version-channel].

## Staging environments

Staging environments are activated automatically for specific source code branches
when a branch is switched to in the Cube Cloud UI. Any [development mode][ref-dev-mode]
changes must be committed to a branch to be available in this environment.

### Availability

By default, they are only active and accessible while viewed by at least one user.
When no users are viewing the branch, the environment becomes inactive and inaccessible.

If you'd like to update this setting for a specific branch (e.g., for testing purposes),
go to **Settings → Staging Environments** and check the toggle next to it:

* **Toggle off** (default). A staging environment is only active when viewed by users.
  When no users are viewing the branch, queries to this environment will fail.
* **Toggle on**. A staging environment remains *always active* and accessible,
  regardless of user activity.

<Frame>
  <img />
</Frame>

The same toggle is available in the [CLI][ref-cli] and the [Control Plane
API][ref-control-plane-api-staging], so it can be scripted, e.g. from CI:

```bash theme={"dark"}
cube data-model enable-branch DEPLOYMENT_ID BRANCH_NAME
cube data-model disable-branch DEPLOYMENT_ID BRANCH_NAME
```

### Resources and costs

Staging environments run on Shared deployments, incurring [relevant
costs][ref-pricing-deployment-tiers]. However, they automatically suspend after 10 minutes
of inactivity, regardless of the [availability](#availability) setting, so you are only
charged for the time when staging environments are being used.

### Cube version

Staging environments always run the *most up-to-date* Cube version.

## Development environments

A development environment is activated automatically when a user enters the [development
mode][ref-dev-mode] on a specific branch of the source code. It updates automatically
when a user saves changes to the data model.

Only one development environment is allocated per user.

### Availability

A development environment is only active and accessible while viewed by a user in the
development mode. Otherwise, queries to this environment will fail.

### Resources and costs

Development environments run on Shared deployments, incurring [relevant
costs][ref-pricing-deployment-tiers]. However, they automatically suspend after 10 minutes
of inactivity, so you are only charged for the time when development environments are
being used.

### Cube version

Development environments always run the *most up-to-date* Cube version.

## API endpoints

Each environment provides its own set of API endpoints.

You can access them on the [**Overview** page][ref-overview] of your deployment
or by navigating to the **Integrations** page and [clicking **API
credentials**][ref-credentials].

<Frame>
  <img />
</Frame>

[ref-dev-mode]: /docs/data-modeling/dev-mode

[ref-deployment-types]: /admin/deployment/deployment-types

[ref-api-instance-scalability]: /admin/deployment/scalability#auto-scaling-of-api-instances

[ref-pricing-deployment-tiers]: /admin/account-billing/pricing

[ref-suspend]: /admin/deployment/auto-suspension

[ref-overview]: /admin/connect-to-data/visualization-tools

[ref-credentials]: /admin/connect-to-data/visualization-tools

[ref-version]: /admin/deployment#cube-version

[ref-version-channel]: /admin/deployment#update-channels

[ref-cli]: /reference/cli

[ref-control-plane-api-staging]: /reference/control-plane-api#buildapiv1deploymentsdeployment_idbranchesstaging-environment


# Overview
Source: https://docs.cube.dev/admin/deployment/index

Introduces Cube deployments and how to browse, create, and operate the environments that run your semantic layer.

Deployments are top-level entities in Cube Cloud. They include the source
code, configuration, allocated resources, API endpoints and essentially
do all the heavy lifting, running workloads and fulfilling requests.

## List of deployments

Each account in Cube Cloud can have multiple deployments. Once you've
logged in, you can access the list of deployments by clicking on
the **Cube Cloud** logo in the top left corner.

<Frame>
  <img />
</Frame>

With more than one deployment, an admin can pin one as the account-wide default from its
row's **⋯** menu (**Set as default** / **Remove as default**). This is what a user
lands on when they open Cube without a deployment in the URL and haven't set their own
[default deployment](/docs/preferences#default-deployment) or previously switched deployments.

## Creating a new deployment

Creating a new deployment is an essential prerequisite to running a Cube
project in Cube Cloud.

After you've created your [Cube Cloud account][cube-cloud-signup],
click **+ Create Deployment** in the top-right corner of your
list of deployments to jump into the wizard. Watch the following video for
guidance on the rest of the steps:

<iframe title="YouTube video" />

All deployments within a Cube Cloud account should have uniqie names.

## Demo deployments

After you've created your [Cube Cloud account][cube-cloud-signup] and
proceeded to create a new deployment, you would be prompted to set up a
connection to your [data source][ref-data-source].

If, for any reason, you're not ready or unable to connect your staging or
production data source at the moment, you can click **Create a demo
deployment** in the yellow box:

<Frame>
  <img />
</Frame>

Shortly, Cube Cloud will create and pre-configure a new deployment in your
account. You will see it as **Demo deployment** in the list of
deployments. This new deployment will be:

* Configured to use [DuckDB][ref-duckdb] as the data source.
* Provided with a sample [data model][ref-data-model] backed with CSV files
  in a public S3 bucket.
* Provided with an example of [dynamic data modeling][ref-dynamic-data-models]
  and programmatic [configuration options][ref-config-options].

Watch the following video to for a step-by-step walkthrough:

<iframe title="YouTube video" />

Exploring the demo deployment is a great way to understand how Cube works.
Use the [data model editor][ref-data-model] to review the data model and
make sure to run a few queries in [Playground][ref-playground].

## Deployment overview

The **Overview** page of each deployment provides a high-level
summary of its components and state:

* API endpoints with URLs and connection instructions.
* Allocated resources in line with the [deployment type][ref-deployment-types].
* Activity log of the most recent events.

<Frame>
  <img />
</Frame>

Additionally, the bar under the **Cube Cloud** logo displays
user-specific state of the deployment:

* Branch selector displays the source code branch that is currently
  selected and being viewed by the user.
* **Enter Development Mode** button indicates whether a user has
  entered the [development mode][ref-dev-mode].

## Deployment settings

You can manage various settings of a deployment, such as [environment
variables](#environment-variables), by navigating to the **Settings** page of the
deployment.

### Environment variables

You can configure environment variables by navigating to **Settings → Environment
variables** where you can add, edit, or remove environment variables for your
deployment.

For convenience, environment variables are split into two lists: ones that relate to
the [data source][ref-data-sources] configuration and all other variables.
Browsing environment variables is reflected in the [Audit Log][ref-audit-log].

<Frame>
  <img />
</Frame>

## Cube version

Each [environment][ref-environments] within a Cube Cloud deployment runs a specific
version of Cube that depends on the environment type and the selected [update
channel](#update-channels).

### Current version

You can check the current version of Cube that your deployment (environment) runs by
navigating to **Overview → Resources & Logs → Cube API**:

<Frame>
  <img />
</Frame>

### Update channels

Cube Cloud provides two update channels:

* **LTS channel** for infrequent [long-term support][ref-lts] releases with
  critical fixes.
* **Regular channel** for regular releases, which occur more frequently and
  contain both fixes and new features.

You can view or change the update channel by navigating to **Settings →
General → Cube version**:

<Frame>
  <img />
</Frame>

You can select a specific version in the drop-down. Only versions that have been used by
a deployment during the last 6 months are available in the list.

There's an option to **Upgrade automatically to new patch versions**, which is
available for both update channels. When it's turned on, an upgrade will occur if a new
[patch version][link-semver] is available in the selected channel. To trigger an upgrade,
deploy a new build to the [production environment][ref-environments-prod] or change its
settings, e.g., by updating environment variables of the Cube Cloud deployment.

Generally, it's recommended to use the *regular channel* to get the latest updates.
You can *pin the version* to a specific one by turning the **Upgrade automatically...**
toggle off.

If you choose to pin the version, make sure to upgrade periodically, especially when the
next [minor version][ref-distribution-versions] is released. If you use the *LTS channel*,
make sure to upgrade to the latest [LTS version][ref-lts] every few months.

## Resource consumption

Cube Cloud deployments only consume resources when they are needed to run workloads:

* For the [production environment][ref-environments-prod], resources are always consumed
  unless a deployment is [suspended][ref-auto-sus].
* For any other [environment][ref-environments], a Shared deployment is allocated
  while it's active. After a period of inactivity, the Shared deployment is deallocated.
* For pre-aggregations, Cube Store workers are allocated while there's some
  activity related to pre-aggregations, e.g., API endpoints are serving
  requests to pre-aggregations, pre-aggregations are being built, etc.
  After a period of inactivity, Cube Store workers are deallocated.

Please refer to [total cost examples][ref-total-cost] to learn more about
resource consumption in different scenarios.

[cube-cloud-signup]: https://cubecloud.dev/auth/signup

[ref-deployment-types]: /admin/deployment/deployment-types

[ref-dev-mode]: /docs/data-modeling/dev-mode

[ref-auto-sus]: /admin/deployment/auto-suspension

[ref-total-cost]: /admin/account-billing/pricing#total-cost-examples

[ref-data-source]: /admin/connect-to-data/data-sources

[ref-duckdb]: /admin/connect-to-data/data-sources/duckdb

[ref-data-model]: /docs/data-modeling/overview

[ref-dynamic-data-models]: /docs/data-modeling/dynamic

[ref-config-options]: /admin/connect-to-data#configuration-options

[ref-data-model]: /docs/data-modeling/data-model-ide

[ref-playground]: /docs/explore-analyze/playground

[ref-environments]: /admin/deployment/environments

[ref-environments-prod]: /admin/deployment/environments#production-environment

[ref-lts]: /admin/account-billing/distribution#long-term-support

[link-semver]: https://semver.org

[ref-data-sources]: /admin/connect-to-data/data-sources

[ref-audit-log]: /admin/monitoring/audit-log

[ref-distribution-versions]: /admin/account-billing/distribution#versions


# Infrastructure Options
Source: https://docs.cube.dev/admin/deployment/infrastructure

Cube Cloud provides four infrastructure options to host your Cube deployments:

* [Multi-tenant infrastructure](#shared-infrastructure) - your
  deployments share compute resources and network with other customers.
  Data in-motion and data at-rest are both on the Cube Cloud side.
* [Single-tenant infrastructure](#dedicated-infrastructure) - your
  deployments reside in a dedicated VPC inside a Cube Cloud account and do not
  share resources with anyone else. Data in-motion and data at-rest are both on
  the Cube Cloud side.
* [Single-tenant infrastructure with CSPS](#dedicated-infrastructure-with-csps) -
  same as single-tenant infrastructure, but data at-rest is stored in a customer-supplied
  object store.
* [Bring Your Own Cloud (BYOC)](#byoc) - Cube Cloud data plane is fully hosted
  in your cloud account.

## Multi-tenant infrastructure

This is the most common deployment option that is the easiest to get started with.
In this scenario, everything is deployed on the Cube Cloud infrastructure in
one of our **multi-tenant** VPCs. Cube Cloud Control Plane takes care of creating,
scaling, and monitoring your Cube Deployments, as well as managing Cube Store
and persisting pre-aggregated data. This option requires the least effort to
set up.

Please note that some Enterprise features, such as VPC peering or PrivateLink are
not available on the multi-tenant infrastructure. There's also a possibility of
resource contention ("noisy neighbor") problem.

<div>
  <img alt="High-level diagram of the fully managed Cube Cloud Infrastructure option (multi-tenant)" />
</div>

## Single-tenant infrastructure

It is similar to the previous option, but each customer gets a
[Dedicated][ref-dedicated-vpc] VPC within one of Cube Cloud's own cloud
accounts that hosts only that customer's deployments. This option is great for
most of the typical Enterprise use-cases as it provides a higher level of
performance, as well as additional security and isolation.

<Note>
  Available as an add-on on the [Enterprise plan](https://cube.dev/pricing).
</Note>

<div>
  <img alt="High-level diagram of the fully managed Cube Cloud Infrastructure option (single-tenant)" />
</div>

## Single-tenant infrastructure with CSPS

Cube Cloud offers a **customer-supplied pre-aggregation storage (CSPS)** that
allows moving all data at rest to the customer
infrastructure. In this scenario, all Cube components reside on the Cube Cloud
side. However, Cube Store uses a customer-provided object store for reading and
persisting pre-aggregated data. This provides additional peace of mind when
processing highly critical business or personal information.

<Note>
  Available on the [Enterprise plan](https://cube.dev/pricing) with the
  [Single-tenant infrastructure](#dedicated-infrastructure) add-on.
</Note>

<div>
  <img alt="High-level diagram explaining the CSPS option" />
</div>

## BYOC

With [Bring Your Own Cloud](/admin/deployment/dedicated) (BYOC) all the components interacting with private data are deployed on the customer infrastructure
on a platform of choice (AWS/Azure/GCP) and managed by the Cube Cloud Control Plane via the Cube Cloud Operator.

<Note>
  Available as an add-on on the [Enterprise plan](https://cube.dev/pricing).
</Note>

<div>
  <img alt="High-level architecture diagram of the Cube Cloud BYOC deployment option" />
</div>

## Understanding "Cube Cloud Region"

Throughout Cube documentation and when interacting with Cube staff, you may encounter the term **"Cube Cloud Region"** or simply **"Region"**. Understanding this term is crucial for properly configuring and managing your Cube deployments.

### What is a Cube Cloud Region?

A **Cube Cloud Region** refers to a specific cloud infrastructure instance used to host your Cube deployments. While it includes a geographical location component, it encompasses much more than just a physical data center location.

Each Cube Cloud Region is identified by a unique identifier that contains several components:

* **Cloud provider** (AWS, GCP, or Azure)
* **Geographical region** (e.g., us-east-1, eu-west-1)
* **Infrastructure type** (multi-tenant, single-tenant, or BYOC)
* **Tenant identifier** (for single-tenant infrastructure)
* **Environment** (e.g., prod, staging)

For example, a region identifier might look like:

* `aws-us-east-1-shared` for multi-tenant infrastructure in AWS US East
* `aws-us-east-1-t-12345-prod` for single-tenant infrastructure with tenant ID 12345
* `gcp-europe-west1-t-12345-byoc` for a BYOC deployment in GCP Europe

Each region also has a human-readable display name that's visible in the Cube Cloud UI. For single-tenant infrastructure regions, these display names typically include the customer name and/or environment name (e.g., "Acme Corp Production (N. Virginia)" or "Acme Corp Staging (Iowa)") to help distinguish between different infrastructure instances.

<Frame>
  <img />
</Frame>

### Not to be confused with...

The term "Cube Cloud Region" should **not** be confused with:

* **Cloud provider regions alone** (like AWS `us-east-1`) - A Cube Cloud Region includes but is not limited to the underlying cloud provider region
* **Geographical regions** - While geography is a component, the Cube Cloud Region encompasses infrastructure type and tenant isolation as well
* **Availability zones** - These are subdivisions within cloud provider regions and are handled transparently by Cube Cloud

### Why this matters

Understanding your Cube Cloud Region is important for:

1. **API endpoints**: Your deployment's API endpoints include the region identifier (e.g., `<deployment-id>.<region>.cubecloudapp.dev`)
2. **Network configuration**: When setting up VPC peering, PrivateLink, or custom domains, you'll need the exact region identifier
3. **Support requests**: Providing the correct region identifier helps Cube support team quickly locate and assist with your deployment
4. **Infrastructure planning**: Different region types offer different capabilities (e.g., PrivateLink is only available in single-tenant and BYOC regions)

### Finding your region identifier

You can find your Cube Cloud Region identifier in:

* The Cube Cloud UI deployment settings
* API endpoint URLs provided in the deployment overview
* Communication from Cube Cloud support when your infrastructure is provisioned

When in doubt, contact Cube Cloud support with your deployment ID, and they can provide the exact region identifier for your infrastructure.

[ref-dedicated-vpc]: /admin/deployment/dedicated


# Limits and quotas
Source: https://docs.cube.dev/admin/deployment/limits

Cube Cloud implements limits on resource usage on account and deployment levels to ensure the best experience for all Cube Cloud users.

<Info>
  Applies to [all plans](https://cube.dev/pricing).
</Info>

## Limit types

Each limit can be of one of the following types:

* *Hard limit* either has a threshold that can't be exceeded or prevents further
  use of a resource when a threshhold is hit until a cool-down period passes
  (e.g., until the next day starts) or the limit is increased (e.g., when a Cube
  Cloud account upgrades to another tier).
* *Soft limit* may allow further use of a resource after a threshold is hit.

## Resources

The following resources are subject to limits, depending on [deployment
types][ref-deployment-types] and [product tiers][ref-pricing]:

| Resource                                                                           | Free Tier |                     Starter                    |                     Premium                    |                       Enterprise                      |
| ---------------------------------------------------------------------------------- | :-------: | :--------------------------------------------: | :--------------------------------------------: | :---------------------------------------------------: |
| Number of deployments                                                              |     2     |                    Unlimited                   |                    Unlimited                   |                       Unlimited                       |
| Number of API instances per deployment                                             |     1     |                       10                       |                       10                       |             [Contact us][cube-contact-us]             |
| Number of Cube Store workers per deployment                                        |     2     |                       16                       |                       16                       |             [Contact us][cube-contact-us]             |
| Queries per day for each [Shared deployment][ref-dev-instance]                     |   1,000   |                     10,000                     |                    Unlimited                   |                       Unlimited                       |
| Queries per day for each [Dedicated deployment][ref-prod-cluster]                  |     —     |                     50,000                     |                    Unlimited                   |                       Unlimited                       |
| [Query History][ref-query-history] — retention period                              |   1 day   | Depends on the [tier][ref-query-history-tiers] | Depends on the [tier][ref-query-history-tiers] |     Depends on the [tier][ref-query-history-tiers]    |
| [Query History][ref-query-history] — queries processed per day for each deployment |   1,000   | Depends on the [tier][ref-query-history-tiers] | Depends on the [tier][ref-query-history-tiers] |     Depends on the [tier][ref-query-history-tiers]    |
| [Audit Log][ref-audit-log] — retention period                                      |     —     |                        —                       |                        —                       |                        30 days                        |
| [Audit Log][ref-audit-log] — events collected                                      |     —     |                        —                       |                        —                       |                         10,000                        |
| [Monitoring Integrations][ref-monitoring-integrations] — exported data             |     —     |                        —                       |                        —                       | Available as an [add-on][ref-monitoring-integrations] |

### Number of deployments

This is a hard limit. Consider upgrading to [another tier][ref-pricing].

### Number of API instances

This is a hard limit. Consider upgrading to [another tier][ref-pricing].

### Number of Cube Store workers

This is a hard limit. Consider upgrading to [another tier][ref-pricing].

An option to use 32 Cube Store workers is subject to availability in select
regions. Please [contact support][cube-contact-us] for more details.

### Queries per day

This is a hard limit. Usage is calculated per Cube Cloud account, i.e., in total
for all deployments within an account.

When a threshold is hit, further queries will not be processed. In that case,
consider upgrading a Shared deployment to a Dedicated deployment.
Alternatively, consider upgrading to [another tier][ref-pricing].

### Queries processed by Query History per day

This is a soft limit. Usage is calculated per Cube Cloud account, i.e., in total
for all deployments within an account.

When a threshold is hit, query processing will be stopped. Please [contact
support][cube-contact-us] for further assistance.

### Data retained by Query History

This is a soft limit. Usage is calculated per Cube Cloud account, i.e., in total
for all deployments within an account.

### Data collected and retained by Audit Log

This is a hard limit. Usage is calculated per Cube Cloud account, i.e., in total
for all deployments within an account. Please [contact
support][cube-contact-us] for further assistance.

### Data exported via Monitoring Integrations

This is a hard limit. Usage is calculated per Cube Cloud deployment. [Contact
support][cube-contact-us] for higher quotas.

## Quotas

The [REST (JSON)][ref-rest-api] and [GraphQL][ref-gql-api] APIs both have a standard
quota of 100 requests per second per deployment; this can also go higher
for short bursts of traffic. These limits can be raised on request,
[contact support][cube-contact-us] for more details.

When the quota is exceeded, the API will return a `429 Too Many Requests`
response.

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-gql-api]: /reference/core-data-apis/graphql-api

[ref-deployment-types]: /admin/deployment/deployment-types

[ref-pricing]: /admin/account-billing/pricing

[ref-query-history]: /admin/monitoring/query-history

[ref-monitoring-integrations]: /admin/monitoring/monitoring-integrations

[ref-dev-instance]: /admin/deployment/deployment-types#shared

[ref-prod-cluster]: /admin/deployment/deployment-types#dedicated

[cube-contact-us]: https://cube.dev/contact

[ref-query-history-tiers]: /admin/account-billing/pricing#query-history-tiers

[ref-audit-log]: /admin/monitoring/audit-log


# AWS
Source: https://docs.cube.dev/admin/deployment/oidc/aws

Configure AWS IAM trust for Cube's OIDC issuer and use it for Athena, Redshift, S3 export buckets, Cube Store CSPS, and Bedrock.

This guide walks through configuring AWS to trust Cube's OIDC issuer and
shows the trust policies for the most common targets — Athena, Redshift, an
S3 export bucket, Cube Store CSPS, and Bedrock for bring-your-own LLM.

If you haven't enabled OIDC for your tenant yet, start with the
[OIDC overview][ref-oidc-overview].

<Info>
  Available on the [Enterprise plan](https://cube.dev/pricing).
</Info>

## Prerequisites

* The Cube tenant has OIDC enabled and an `AWS` token config exists under
  **Admin → OIDC**.
* IAM access to your AWS account sufficient to register an IAM OIDC provider
  and create / update IAM roles.
* Your tenant slug — the leftmost label of your tenant's console URL.
  Throughout this guide it's referenced as `<tenant-name>` (and the full
  issuer URL as `https://<tenant-name>.cubecloud.dev`). Substitute your
  actual slug everywhere it appears.

<Warning>
  The trust policies, env vars, and CLI commands in this guide use angle-bracket
  placeholders — `<tenant-name>`, `<aws-account-id>`, `<deployment-id>`,
  etc. **Replace each placeholder with your real value** before
  copying. AWS will accept these strings literally and the federation call will
  fail with a confusing error.
</Warning>

## Step 1: Register Cube as an OIDC provider in AWS

This is a **one-time** setup per AWS account. Once registered, every IAM role
in this account can be configured to trust deployments in your Cube tenant.

```bash theme={"dark"}
aws iam create-open-id-connect-provider \
  --url https://<tenant-name>.cubecloud.dev \
  --client-id-list sts.amazonaws.com
```

<Note>
  AWS no longer requires a TLS thumbprint for HTTPS OIDC providers. The
  `--thumbprint-list` parameter is accepted for compatibility but ignored —
  AWS validates the issuer's certificate chain against its own trust store.
</Note>

The command returns the provider ARN, which looks like:

```
arn:aws:iam::<aws-account-id>:oidc-provider/<tenant-name>.cubecloud.dev
```

You'll reference this ARN as the `Federated` principal in every trust policy
below. From AWS's point of view, this provider *is* your Cube tenant.

## Step 2: Set the deployment identity

Add `AWS_ROLE_ARN` to your deployment's environment variables under
**Settings → Environment variables**. This is the IAM role Cube assumes by
default for every AWS SDK call inside the deployment — drivers, export
bucket I/O, custom code in `cube.py` / `cube.js`. You can either grant this
role direct access to your data, or use it as the entry point for further
`AssumeRole` hops.

```dotenv theme={"dark"}
AWS_ROLE_ARN=arn:aws:iam::<aws-account-id>:role/cube-deployment-<tenant-name>
```

<Info>
  `sts:AssumeRoleWithWebIdentity` does **not** accept `sts:ExternalId`. Trust
  policies for OIDC-federated roles can only condition on the standard OIDC
  claims (`aud`, `sub`, `iss`). If you copy a trust policy from a non-federated
  role assumption (cross-account access keys, for example) and it includes
  `sts:ExternalId`, remove it — STS will reject the federation call. Use the
  `sub` claim to pin the role to a specific deployment or component instead.
</Info>

## Step 3: Build the trust policy

Every IAM role you want Cube to assume needs a trust policy with this shape:

```json theme={"dark"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<aws-account-id>:oidc-provider/<tenant-name>.cubecloud.dev"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "<tenant-name>.cubecloud.dev:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "<tenant-name>.cubecloud.dev:sub": "cube:deployment:<deployment-id>:component:cube_api"
        }
      }
    }
  ]
}
```

The `aud` condition pins the audience to AWS STS — exactly what Cube's `aws`
token config emits. The `sub` condition is what scopes the trust to a
specific deployment (and optionally a specific Cube component). Patterns:

| Trust scope                                                             | `sub` pattern                                          |
| ----------------------------------------------------------------------- | ------------------------------------------------------ |
| One specific deployment, any component                                  | `cube:deployment:<deployment-id>:component:*`          |
| One deployment, only the Cube API and refresh worker                    | `cube:deployment:<deployment-id>:component:cube_api`   |
| One deployment, only Cube Store                                         | `cube:deployment:<deployment-id>:component:cube_store` |
| Every deployment in the tenant, only Cube Store (e.g. tenant-wide CSPS) | `cube:deployment:*:component:cube_store`               |
| Every deployment, every component                                       | `cube:deployment:*:component:*`                        |

Cube's default `sub` claim is `cube:deployment:<deployment_id>`. To match
the `:component:<component>` patterns in the table above (or to add
`:region:<region>`), open your AWS token config in **Admin → OIDC** and
paste one of these templates into the **Subject Claim Format** field:

* `cube:deployment:{deployment_id}:component:{component}` — for the patterns
  in the table above.
* `cube:deployment:{deployment_id}:component:{component}:region:{region}` —
  to additionally pin a [Cube Cloud region][ref-cube-cloud-region], useful
  when you have dedicated regions per environment.

See [the subject editor section][ref-sub-editor] for the full syntax.

<Warning>
  Update your AWS trust policy first, then change the **Subject Claim Format**
  on the token config — otherwise existing tokens won't match the trust policy
  and `AssumeRoleWithWebIdentity` will start failing.
</Warning>

## Athena

Configure an IAM role with permissions to query Athena and read query
results from your S3 results bucket.

<Steps>
  <Step title="Create the IAM role">
    Trust policy — substitute your AWS account ID, tenant slug, and
    deployment ID for the angle-bracket placeholders:

    ```json theme={"dark"}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "Federated": "arn:aws:iam::<aws-account-id>:oidc-provider/<tenant-name>.cubecloud.dev"
          },
          "Action": "sts:AssumeRoleWithWebIdentity",
          "Condition": {
            "StringEquals": {
              "<tenant-name>.cubecloud.dev:aud": "sts.amazonaws.com"
            },
            "StringLike": {
              "<tenant-name>.cubecloud.dev:sub": "cube:deployment:<deployment-id>:component:cube_api"
            }
          }
        }
      ]
    }
    ```
  </Step>

  <Step title="Attach the Athena permissions">
    Athena needs permission to start queries, read Glue metadata, and
    read / write the S3 results bucket. The example below scopes the S3
    permissions to a single bucket; tighten the resource list as needed.

    ```json theme={"dark"}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "athena:StartQueryExecution",
            "athena:GetQueryExecution",
            "athena:GetQueryResults",
            "athena:StopQueryExecution",
            "athena:ListQueryExecutions",
            "athena:GetWorkGroup",
            "athena:ListWorkGroups"
          ],
          "Resource": "*"
        },
        {
          "Effect": "Allow",
          "Action": [
            "glue:GetDatabase",
            "glue:GetDatabases",
            "glue:GetTable",
            "glue:GetTables",
            "glue:GetPartitions"
          ],
          "Resource": "*"
        },
        {
          "Effect": "Allow",
          "Action": [
            "s3:GetBucketLocation",
            "s3:GetObject",
            "s3:ListBucket",
            "s3:PutObject",
            "s3:DeleteObject",
            "s3:AbortMultipartUpload",
            "s3:ListMultipartUploadParts"
          ],
          "Resource": [
            "arn:aws:s3:::my-athena-results",
            "arn:aws:s3:::my-athena-results/*",
            "arn:aws:s3:::my-athena-data",
            "arn:aws:s3:::my-athena-data/*"
          ]
        }
      ]
    }
    ```
  </Step>

  <Step title="Configure the deployment">
    Set the deployment-level Athena env vars. With `AWS_ROLE_ARN` in place,
    the Athena driver automatically assumes the role via OIDC federation —
    no static credentials needed.

    ```dotenv theme={"dark"}
    CUBEJS_DB_TYPE=athena
    AWS_ROLE_ARN=arn:aws:iam::<aws-account-id>:role/cube-deployment-<tenant-name>
    CUBEJS_AWS_REGION=us-east-1
    CUBEJS_AWS_S3_OUTPUT_LOCATION=s3://my-athena-results/queries/
    ```

    If Athena lives in a different role / account from the deployment's
    default identity, set [`CUBEJS_AWS_ATHENA_ASSUME_ROLE_ARN`][ref-athena-assume-role]
    in addition to `AWS_ROLE_ARN`. The Athena driver uses the deployment
    identity to perform a second `AssumeRole` hop into the Athena role.
  </Step>
</Steps>

## Redshift

Configure an IAM role that can obtain temporary Redshift database
credentials. The Redshift driver uses the deployment's federated identity
to call `redshift:GetClusterCredentialsWithIAM` — no database password is
stored anywhere.

<Steps>
  <Step title="Create the IAM role">
    Use the same trust policy shape as [Athena](#athena) — federated
    principal, `aud` pinned to `sts.amazonaws.com`, and `sub` pinned to your
    deployment.
  </Step>

  <Step title="Attach the Redshift permissions">
    The role needs to fetch temporary credentials and describe the cluster:

    ```json theme={"dark"}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "redshift:GetClusterCredentialsWithIAM",
            "redshift:DescribeClusters"
          ],
          "Resource": "*"
        }
      ]
    }
    ```

    Tighten `Resource` to your cluster and database ARNs in production.
  </Step>

  <Step title="Configure the deployment">
    Set the Redshift driver env vars for [IAM
    authentication][ref-redshift-driver-iam] and omit `CUBEJS_DB_USER` /
    `CUBEJS_DB_PASS`. With `AWS_ROLE_ARN` in place, the driver assumes the
    role via OIDC federation and exchanges it for temporary database
    credentials:

    ```dotenv theme={"dark"}
    CUBEJS_DB_TYPE=redshift
    AWS_ROLE_ARN=arn:aws:iam::<aws-account-id>:role/cube-deployment-<tenant-name>
    CUBEJS_DB_HOST=my-cluster.xxx.us-east-1.redshift.amazonaws.com
    CUBEJS_DB_NAME=my_database
    CUBEJS_DB_SSL=true
    CUBEJS_DB_REDSHIFT_AWS_REGION=us-east-1
    CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER=my-cluster
    ```
  </Step>
</Steps>

## S3 export bucket

If your data source uses an [export bucket][ref-export-bucket] for
pre-aggregation unloads (Snowflake, Redshift, Athena, BigQuery, …), Cube
needs `s3:PutObject` / `s3:GetObject` / `s3:ListBucket` on the bucket. The
deployment's default identity is the simplest place to put this.

<Steps>
  <Step title="Grant export bucket access to the deployment role">
    Add an inline statement to the policy attached to your deployment's
    `AWS_ROLE_ARN`:

    ```json theme={"dark"}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "s3:GetObject",
            "s3:PutObject",
            "s3:DeleteObject",
            "s3:ListBucket",
            "s3:GetBucketLocation",
            "s3:AbortMultipartUpload",
            "s3:ListMultipartUploadParts"
          ],
          "Resource": [
            "arn:aws:s3:::my-export-bucket",
            "arn:aws:s3:::my-export-bucket/*"
          ]
        }
      ]
    }
    ```
  </Step>

  <Step title="Configure the export bucket env vars">
    Set the export bucket env vars on the deployment — leave the AWS access
    key vars empty so the SDK falls back to the OIDC-derived credentials:

    ```dotenv theme={"dark"}
    CUBEJS_DB_EXPORT_BUCKET_TYPE=s3
    CUBEJS_DB_EXPORT_BUCKET=my-export-bucket
    CUBEJS_DB_EXPORT_BUCKET_AWS_REGION=us-east-1
    ```

    See the [export bucket reference][ref-export-bucket] for the full set
    of variables.
  </Step>
</Steps>

<Warning>
  OIDC only covers Cube's **read** side of the export bucket. The data
  warehouse itself (Snowflake, Redshift, Athena, BigQuery, …) runs the
  `UNLOAD` that writes objects to the bucket, and the warehouse cannot
  federate with Cube's OIDC issuer. You still need to provide **separate
  credentials for the `UNLOAD`** so the warehouse can write to S3 — typically
  an AWS access key pair or a warehouse-side storage integration / IAM role
  — via the standard export bucket env vars (e.g.
  `CUBEJS_DB_EXPORT_BUCKET_AWS_KEY` and `CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET`,
  or the driver-specific storage-integration variables). OIDC then handles
  Cube's download of the unloaded objects from the bucket.
</Warning>

## Cube Store CSPS bucket

Cube Store CSPS lets you store pre-aggregations in your own S3 bucket.
Cube Store gets a separate OIDC token whose `sub` claim ends in
`component:cube_store`, so the trust policy can be locked down to that
component — even if the same role were ever shared with the rest of the
deployment, only Cube Store would be able to assume it.

Because every Cube Store worker emits a `sub` of the form
`cube:deployment:<deployment-id>:component:cube_store`, the trust policy's
`StringLike` condition controls how broadly the role is shared:

* `cube:deployment:*:component:cube_store` — **one role + one bucket for the
  whole tenant.** Every deployment in the tenant writes pre-aggregations to
  the same bucket, isolated only by Cube Store's own per-deployment path
  prefix. Easiest to operate and the most common setup.
* `cube:deployment:<deployment-id>:component:cube_store` — **per-deployment
  isolation.** Pin the role to one deployment so its pre-aggregations live
  in a dedicated bucket that no other deployment can read or write.

The example below shows the tenant-wide pattern; swap `*` for a specific
deployment ID if you want isolation.

<Steps>
  <Step title="Create the Cube Store IAM role">
    Trust policy — note the `StringLike` condition pinning the component
    and using `*` so every deployment in the tenant can assume the role:

    ```json theme={"dark"}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "Federated": "arn:aws:iam::<aws-account-id>:oidc-provider/<tenant-name>.cubecloud.dev"
          },
          "Action": "sts:AssumeRoleWithWebIdentity",
          "Condition": {
            "StringEquals": {
              "<tenant-name>.cubecloud.dev:aud": "sts.amazonaws.com"
            },
            "StringLike": {
              "<tenant-name>.cubecloud.dev:sub": "cube:deployment:*:component:cube_store"
            }
          }
        }
      ]
    }
    ```
  </Step>

  <Step title="Attach the bucket permissions">
    Allow the role to read, write, and list objects in your CSPS bucket.
    Cube Store needs all of the actions below — including the multipart
    upload primitives — to handle large pre-aggregation partitions:

    ```json theme={"dark"}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "s3:GetObject",
            "s3:PutObject",
            "s3:DeleteObject",
            "s3:ListBucket",
            "s3:GetBucketLocation",
            "s3:AbortMultipartUpload",
            "s3:ListMultipartUploadParts"
          ],
          "Resource": [
            "arn:aws:s3:::my-csps-bucket",
            "arn:aws:s3:::my-csps-bucket/*"
          ]
        }
      ]
    }
    ```
  </Step>

  <Step title="Enable CSPS on each deployment">
    For each deployment that should use this bucket, go to **Settings →
    Pre-Aggregation Storage** on the deployment and:

    * Toggle **Enable CSPS** on.
    * **Storage Provider**: Amazon S3.
    * **S3 Bucket**: `my-csps-bucket`.
    * **S3 Region**: e.g. `us-east-1`.
    * **IAM Role ARN**: `arn:aws:iam::<aws-account-id>:role/cube-cubestore-<tenant-name>`.

    Click **Test Connection** to verify Cube Store can assume the role and
    access the bucket, then **Apply**. Cube Store starts writing
    pre-aggregations to your bucket on the next refresh. With the
    tenant-wide trust policy above, every deployment in the tenant points
    at the same role — no need to provision a new IAM role per deployment.

    <Frame>
      <img alt="Settings → Pre-Aggregation Storage page on a Cube Cloud deployment, with the Enable CSPS toggle on and the Amazon S3 fields (S3 Bucket, S3 Region, IAM Role ARN) ready to fill in." />
    </Frame>
  </Step>
</Steps>

## Bedrock for bring-your-own LLM

Bring-your-own LLM lets the AI engineer service call Bedrock through your
own AWS account. The AI engineer's `sub` claim ends in
`component:ai_engineer`, so the trust policy uses a `StringLike` match on
`cube:deployment:*:component:ai_engineer` to grant access tenant-wide
(every deployment's AI engineer assumes the same role and writes against
the same Bedrock account).

<Steps>
  <Step title="Create the Bedrock IAM role">
    Trust policy — note the `StringLike` condition pinning the component:

    ```json theme={"dark"}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "Federated": "arn:aws:iam::<aws-account-id>:oidc-provider/<tenant-name>.cubecloud.dev"
          },
          "Action": "sts:AssumeRoleWithWebIdentity",
          "Condition": {
            "StringEquals": {
              "<tenant-name>.cubecloud.dev:aud": "sts.amazonaws.com"
            },
            "StringLike": {
              "<tenant-name>.cubecloud.dev:sub": "cube:deployment:*:component:ai_engineer"
            }
          }
        }
      ]
    }
    ```
  </Step>

  <Step title="Attach Bedrock invoke permissions">
    Grant access only to the foundation models and inference profiles you
    intend to use:

    ```json theme={"dark"}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "bedrock:InvokeModel",
            "bedrock:InvokeModelWithResponseStream",
            "bedrock:Converse",
            "bedrock:ConverseStream"
          ],
          "Resource": [
            "arn:aws:bedrock:*::foundation-model/anthropic.*",
            "arn:aws:bedrock:*:<aws-account-id>:inference-profile/*"
          ]
        }
      ]
    }
    ```

    Cross-region inference profiles need access to the foundation model in
    every region the profile routes through, hence the `*` region in the
    foundation-model ARN.
  </Step>

  <Step title="Configure the BYO LLM provider in the AI engineer">
    Under **Admin → AI → Models**, click **Add Model** and configure:

    * **Name** — a human-readable label for this BYOM entry.
    * **Model Type** — `LLM`.
    * **Provider** — `AWS Bedrock`.
    * **Model** — the Claude (or other) model you want the AI engineer to
      call.
    * **Region** — the Bedrock region (e.g. `us-east-1`).
    * **Inference Profile ID** — optional; leave blank to call the
      foundation model directly, or set to a cross-region inference
      profile ID.
    * **Assume Role ARN** — the role you created above.
    * **Use OIDC workload identity** — toggle on. With this on, the AI
      engineer authenticates via the deployment's OIDC token instead of
      static AWS credentials.

    <Frame>
      <img alt="Admin → AI → Models → Add New Model modal in Cube Cloud, showing the AWS Bedrock provider selected with the Assume Role ARN field and the Use OIDC workload identity toggle on." />
    </Frame>
  </Step>
</Steps>

## Monitoring integrations (CloudWatch, S3)

[Monitoring integrations][ref-monitoring-integrations] can ship deployment logs
to AWS without a static access key pair. The Vector agent that performs the
export reads the deployment's OIDC token and assumes an IAM role, exactly like
the targets above — so the `[sinks.*.auth]` block disappears from `vector.toml`
entirely.

The credentials are resolved by the AWS SDK's default chain **for the whole
Vector agent**, not per sink, so one role serves every AWS sink you configure —
[`aws_cloudwatch_logs`][ref-cloudwatch], [`aws_s3`][ref-s3], and the `aws_s3`
sink used by [Query History export][ref-query-history-export]. Grant that single
role whatever those sinks need.

Vector authenticates as the deployment's **`cube_api`** component, so the trust
policy is the standard one from [Step 3](#step-3-build-the-trust-policy) with
`sub` set to `cube:deployment:<deployment-id>:component:cube_api`.

<Warning>
  That `sub` uses the `:component:` form, which is **not** Cube's default — the
  default claim is `cube:deployment:<deployment-id>` with no `component` segment,
  and a trust policy written against the pattern above will never match it. Set
  **Subject Claim Format** on your `AWS` token config to
  `cube:deployment:{deployment_id}:component:{component}` first; see
  [Step 3](#step-3-build-the-trust-policy) for the full syntax and the ordering
  caveat when changing it on a config that is already in use.
</Warning>

<Steps>
  <Step title="Create the CloudWatch role">
    Create a role with that trust policy and attach a permissions policy that
    can write to your log group:

    ```json theme={"dark"}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "logs:CreateLogStream",
            "logs:PutLogEvents",
            "logs:DescribeLogStreams"
          ],
          "Resource": [
            "arn:aws:logs:<region>:<aws-account-id>:log-group:<log-group-name>",
            "arn:aws:logs:<region>:<aws-account-id>:log-group:<log-group-name>:*"
          ]
        },
        {
          "Effect": "Allow",
          "Action": ["logs:DescribeLogGroups"],
          "Resource": "*"
        }
      ]
    }
    ```

    Add `logs:CreateLogGroup` to the first statement if you set
    `create_missing_group = true` in the sink.

    If the same agent also writes to S3 (the [S3][ref-s3] or
    [Query History export][ref-query-history-export] sinks), add the bucket
    permissions those need to this same role: `s3:PutObject` on
    `arn:aws:s3:::<bucket>/*`, plus `s3:ListBucket` on `arn:aws:s3:::<bucket>`
    if you enable the sink's healthcheck. Both S3 examples in the docs ship with
    `[sinks.aws_s3.healthcheck] enabled = false`, so `s3:PutObject` alone is
    enough as written — but Vector's `aws_s3` healthcheck issues a `HeadBucket`,
    which AWS authorizes as `s3:ListBucket` on the bucket ARN (not `/*`).
  </Step>

  <Step title="Point the deployment at the role">
    Set these on the deployment under **Settings → Environment variables**:

    ```dotenv theme={"dark"}
    CUBE_CLOUD_MONITORING_AWS_ROLE_ARN=arn:aws:iam::<aws-account-id>:role/<role-name>
    ```

    Setting the role ARN is what enables keyless authentication. The region for
    the credential exchange is taken from the sink's own `region`; set
    `CUBE_CLOUD_MONITORING_AWS_REGION` only to override it.

    Then drop the `auth` block from your `vector.toml` — see
    [Integration with Amazon CloudWatch][ref-cloudwatch] for the sink
    configuration.
  </Step>
</Steps>

<Warning>
  **`logs:DescribeLogGroups` must be scoped to `"*"`.** Vector's healthcheck calls
  it, and it is an account-level list operation that AWS evaluates against an
  *empty* resource. Scoping it to your log group ARN — the natural
  least-privilege instinct — denies it, and the sink is marked unhealthy at
  startup with:

  ```
  not authorized to perform: logs:DescribeLogGroups on resource:
  arn:aws:logs:<region>:<aws-account-id>:log-group::log-stream:
  ```

  Keep it in a separate statement from the log-group-scoped write actions, as
  shown above.
</Warning>

<Info>
  This role is separate from the deployment's default `AWS_ROLE_ARN`. Because
  both are assumed by the same `cube_api` identity, a trust policy written for
  one will also admit the other — scope each role's **permissions** policy
  tightly rather than relying on the trust policy to separate them.
</Info>

## Verifying the setup

The fastest way to confirm the trust policy is wired up correctly is the
**Test connection** button on the relevant settings page (data source
wizard, CSPS settings, BYO LLM provider). Behind the scenes, this issues a
real Cube OIDC token, runs `AssumeRoleWithWebIdentity` against AWS STS, and
returns a precise error if the trust policy rejects it.

If the test fails:

| Symptom                                                   | Likely cause                                                                                                                                                                            |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Not authorized to perform sts:AssumeRoleWithWebIdentity` | The trust policy's `sub` condition doesn't match the deployment / component. Compare the `sub` in the error with what your `StringLike` allows.                                         |
| `Incorrect token audience`                                | `aud` condition is wrong, or you copied a trust policy from a different tenant. The condition key must be `<tenant-name>.cubecloud.dev:aud`.                                            |
| `OpenIDConnectProvider not found`                         | The OIDC provider hasn't been registered in this AWS account yet, or its URL doesn't match your tenant's domain. Re-run `aws iam create-open-id-connect-provider` with the correct URL. |
| `An error occurred ... InvalidIdentityToken`              | Trying to use `sts:ExternalId`. Remove it — federated assume-role doesn't accept it.                                                                                                    |

`AssumeRoleWithWebIdentity` events show up in CloudTrail with the deployment
subject in the `userIdentity.webIdFederationData.federatedProvider` and
`...attributes` fields — useful for auditing which deployments are
authenticating against which roles.

[ref-oidc-overview]: /admin/deployment/oidc

[ref-sub-editor]: /admin/deployment/oidc#subject-claim-format

[ref-cube-cloud-region]: /admin/deployment/infrastructure#what-is-a-cube-cloud-region

[ref-export-bucket]: /admin/connect-to-data#export-bucket

[ref-monitoring-integrations]: /admin/monitoring/monitoring-integrations

[ref-cloudwatch]: /admin/monitoring/monitoring-integrations/cloudwatch

[ref-s3]: /admin/monitoring/monitoring-integrations/s3

[ref-query-history-export]: /admin/monitoring/query-history-export

[ref-athena-assume-role]: /admin/connect-to-data/data-sources/aws-athena#environment-variables

[ref-redshift-driver-iam]: /admin/connect-to-data/data-sources/aws-redshift#iam-authentication


# Azure
Source: https://docs.cube.dev/admin/deployment/oidc/azure

Configure an Azure AD app registration with federated credentials that trust Cube's OIDC issuer, then use it for Azure SQL and Blob Storage.

This guide walks through configuring Azure to trust Cube's OIDC issuer using
**federated credentials** on an Azure AD app registration, and shows the
setup for the most common targets — Azure SQL and an Azure Blob Storage
export bucket.

If you haven't enabled OIDC for your tenant yet, start with the
[OIDC overview][ref-oidc-overview].

<Info>
  Available on the [Enterprise plan](https://cube.dev/pricing).
</Info>

## Prerequisites

* The Cube tenant has OIDC enabled and an `Azure` token config exists under
  **Admin → OIDC**.
* Permissions in your Azure AD tenant sufficient to create an app
  registration and add federated credentials, plus an Azure subscription
  where you can grant the app role assignments on resources.
* Your Cube tenant slug — the leftmost label of your tenant's console URL.
  Throughout this guide it's referenced as `<tenant-name>` (and the full
  issuer URL as `https://<tenant-name>.cubecloud.dev`). Substitute your
  actual slug everywhere it appears.

<Warning>
  Commands and federated-credential snippets in this guide use angle-bracket
  placeholders — `<tenant-name>`, `<deployment-id>`, etc.
  **Replace each placeholder with your real value** before running. Azure
  will accept these strings literally and the federation call will fail with
  a confusing error.
</Warning>

## How Azure federation works

Azure doesn't have a generic OIDC provider registration the way AWS does.
Instead, you configure each app registration (or user-assigned managed
identity) with a **federated credential** that pins the issuer URL,
expected `aud`, and exact `sub` value. When Cube presents a JWT that
matches all three, Azure AD swaps it for an access token scoped to the
app registration.

```mermaid theme={"dark"}
sequenceDiagram
    participant Cube as Cube Deployment
    participant AAD as Azure AD<br/>(login.microsoftonline.com)
    participant Resource as Azure Resource<br/>(SQL / Blob / OpenAI)

    Cube->>AAD: client_assertion = OIDC JWT<br/>grant_type = client_credentials<br/>audience = api://AzureADTokenExchange
    AAD->>AAD: Match federated credential by issuer + sub + aud<br/>Validate JWT against Cube's JWKS
    AAD->>Cube: Access token for the app registration
    Cube->>Resource: Authenticated request
```

<Warning>
  Azure caps you at **20 federated credentials per app registration**. For
  tenants with many deployments, see [Scaling past 20
  credentials](#scaling-past-20-federated-credentials) below.
</Warning>

## Step 1: Create or pick an app registration

You can use an existing app registration or create a new one — Cube doesn't
have any opinion as long as it has the federated credential and the role
assignments.

```bash theme={"dark"}
az ad app create --display-name "Cube Cloud Deployment"
```

Note the **Application (client) ID** — this is your `AZURE_CLIENT_ID`. The
**Directory (tenant) ID** is your `AZURE_TENANT_ID`. Both are visible in
the Azure portal under **Microsoft Entra ID → App registrations → Cube
Cloud Deployment → Overview**.

## Step 2: Add a federated credential

The federated credential is what binds the app registration to a specific
Cube subject. Each credential matches **exactly one** issuer + subject +
audience triple — Azure doesn't support wildcards or pattern matching here.

```bash theme={"dark"}
az ad app federated-credential create \
  --id <APP_OBJECT_ID> \
  --parameters '{
    "name": "cube-<tenant-name>-deployment-<deployment-id>",
    "issuer": "https://<tenant-name>.cubecloud.dev",
    "subject": "cube:deployment:<deployment-id>:component:cube_api",
    "audiences": ["api://AzureADTokenExchange"]
  }'
```

| Field       | Value                                                                                                 |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| `issuer`    | Your Cube tenant's URL: `https://<tenant-name>.cubecloud.dev`.                                        |
| `subject`   | The exact `sub` claim Cube emits — typically `cube:deployment:<deployment-id>:component:<component>`. |
| `audiences` | Always `["api://AzureADTokenExchange"]` — this is the standard Azure AD token-exchange audience.      |
| `name`      | A human-readable label. Pick something that lets you find this credential later.                      |

Each Cube component you want this app to authenticate as needs its own
federated credential. So if a deployment runs both Cube API and Cube Store
against the same Azure resource, you create two credentials — one with
`subject` ending in `:component:cube_api` and one ending in
`:component:cube_store`.

Cube's default `sub` claim is `cube:deployment:<deployment_id>`. To match
the `:component:<component>` examples in this guide (or to add
`:region:<region>`), open your Azure token config in **Admin → OIDC** and
paste one of these templates into the **Subject Claim Format** field:

* `cube:deployment:{deployment_id}:component:{component}` — for the
  `cube:deployment:<deployment-id>:component:<component>` examples below.
* `cube:deployment:{deployment_id}:component:{component}:region:{region}` —
  to additionally pin a [Cube Cloud region][ref-cube-cloud-region].

See [the subject editor section][ref-sub-editor] for the full syntax.

<Warning>
  Azure pins the federated credential's `subject` field literally — changing
  the format means recreating every federated credential that references it.
  Create the new federated credential first, then change the **Subject Claim
  Format** on the token config.
</Warning>

## Step 3: Set the deployment identity

Add two env vars to your deployment under **Settings → Environment
variables**:

```dotenv theme={"dark"}
AZURE_TENANT_ID=00000000-0000-0000-0000-000000000000
AZURE_CLIENT_ID=11111111-1111-1111-1111-111111111111
```

* **`AZURE_TENANT_ID`** — the Microsoft Entra ID (Azure AD) tenant where
  your app registration lives.
* **`AZURE_CLIENT_ID`** — the Application (client) ID of the app
  registration.

## Step 4: Assign roles on Azure resources

Grant the app registration the standard Azure RBAC roles it needs, the
same way you'd grant any service principal access to a resource. Examples
follow per target.

## Azure SQL

<Steps>
  <Step title="Create the federated credential">
    See [Step 2](#step-2-add-a-federated-credential) — pin subject to
    `cube:deployment:<deployment-id>:component:cube_api`.
  </Step>

  <Step title="Create a contained user in Azure SQL">
    Connect to your Azure SQL database as an Entra-authenticated admin and
    create a user backed by the app registration:

    ```sql theme={"dark"}
    CREATE USER [Cube Cloud Deployment] FROM EXTERNAL PROVIDER;
    ALTER ROLE db_datareader ADD MEMBER [Cube Cloud Deployment];
    GRANT EXECUTE ON SCHEMA::dbo TO [Cube Cloud Deployment];
    ```

    The user name must match the app registration's display name.
  </Step>

  <Step title="Configure the deployment">
    Set the MSSQL driver and identity env vars on the deployment:

    ```dotenv theme={"dark"}
    CUBEJS_DB_TYPE=mssql
    CUBEJS_DB_HOST=my-server.database.windows.net
    CUBEJS_DB_NAME=my-db
    CUBEJS_DB_PORT=1433
    AZURE_TENANT_ID=00000000-0000-0000-0000-000000000000
    AZURE_CLIENT_ID=11111111-1111-1111-1111-111111111111
    ```

    The MSSQL driver uses the `azure-active-directory-access-token` auth
    type with the federated token Cube provides. No username, password, or
    client secret needed.
  </Step>
</Steps>

## Azure Blob Storage export bucket

If your data source uses an [export bucket][ref-export-bucket] for
pre-aggregation unloads, grant the app registration **Storage Blob Data
Contributor** on the storage account.

<Steps>
  <Step title="Grant role assignment">
    Assign **Storage Blob Data Contributor** on the storage account scope:

    ```bash theme={"dark"}
    az role assignment create \
      --assignee <APP_CLIENT_ID> \
      --role "Storage Blob Data Contributor" \
      --scope "/subscriptions/<SUB_ID>/resourceGroups/<RG>/providers/Microsoft.Storage/storageAccounts/<ACCOUNT>"
    ```

    For tighter scoping, narrow to a specific container with
    `.../blobServices/default/containers/<container>` instead of the whole
    storage account.
  </Step>

  <Step title="Configure the export bucket env vars">
    Point the export bucket env vars at your container:

    ```dotenv theme={"dark"}
    CUBEJS_DB_EXPORT_BUCKET_TYPE=azure
    CUBEJS_DB_EXPORT_BUCKET=https://<account>.blob.core.windows.net/<container>
    AZURE_TENANT_ID=00000000-0000-0000-0000-000000000000
    AZURE_CLIENT_ID=11111111-1111-1111-1111-111111111111
    ```

    The Azure storage client picks up the same federated identity. See the
    [export bucket reference][ref-export-bucket] for the full set of
    variables.
  </Step>
</Steps>

<Warning>
  OIDC only covers Cube's **read** side of the export bucket. The data
  warehouse itself (Snowflake on Azure, Synapse, …) runs the `UNLOAD` that
  writes objects to Blob Storage, and the warehouse cannot federate with
  Cube's OIDC issuer. You still need to provide **separate credentials for
  the unload** so the warehouse can write to the container — typically a
  storage account key, SAS token, or a warehouse-side storage integration —
  via the standard export bucket env vars (e.g.
  `CUBEJS_DB_EXPORT_BUCKET_AZURE_KEY`, or the driver-specific
  storage-integration variables). OIDC then handles Cube's download of the
  unloaded objects from the bucket.
</Warning>

## Azure Blob Storage CSPS bucket

Cube Store CSPS lets you store pre-aggregations in your own Azure Blob
Storage container. Cube Store gets a separate OIDC token whose `sub` claim
ends in `component:cube_store`, so the federated credential can be locked
down to that component — even if the same app registration were shared with
the rest of the deployment, only Cube Store would match.

Every Cube Store worker emits a `sub` of the form
`cube:deployment:<deployment-id>:component:cube_store`. Unlike AWS IAM —
which matches `sub` with a `StringLike` wildcard, so one role can cover the
whole tenant — **Azure pins the federated credential's `subject` literally**
and has no tenant-wide `*`. So CSPS on Azure is **per deployment**: each
deployment that writes pre-aggregations to the container needs its own
federated credential carrying that deployment's exact `sub`. If you expect
many deployments, mind the 20-credential limit and see [Scaling past 20
federated credentials](#scaling-past-20-federated-credentials).

<Steps>
  <Step title="Create the Cube Store federated credential">
    Add a federated credential on the app registration, pinning the subject
    to the deployment's Cube Store component:

    ```bash theme={"dark"}
    az ad app federated-credential create \
      --id <APP_OBJECT_ID> \
      --parameters '{
        "name": "cube-<tenant-name>-deployment-<deployment-id>-cube-store",
        "issuer": "https://<tenant-name>.cubecloud.dev",
        "subject": "cube:deployment:<deployment-id>:component:cube_store",
        "audiences": ["api://AzureADTokenExchange"]
      }'
    ```

    Make sure the Azure token config's **Subject Claim Format** includes the
    `:component:` segment
    (`cube:deployment:{deployment_id}:component:{component}`) — see
    [Step 2](#step-2-add-a-federated-credential) — otherwise the Cube Store
    `sub` won't match this credential.
  </Step>

  <Step title="Grant the container permissions">
    Grant the app registration **Storage Blob Data Contributor** so Cube
    Store can read, write, and list pre-aggregation blobs. Scope it to the
    container for tightest isolation:

    ```bash theme={"dark"}
    az role assignment create \
      --assignee <APP_CLIENT_ID> \
      --role "Storage Blob Data Contributor" \
      --scope "/subscriptions/<SUB_ID>/resourceGroups/<RG>/providers/Microsoft.Storage/storageAccounts/<ACCOUNT>/blobServices/default/containers/<container>"
    ```

    Use the storage account scope (drop the
    `/blobServices/default/containers/<container>` suffix) if you'd rather
    one assignment cover multiple containers.
  </Step>

  <Step title="Enable CSPS on each deployment">
    For each deployment that should use this container, go to **Settings →
    Pre-Aggregation Storage** on the deployment and:

    * Toggle **Enable CSPS** on.
    * **Storage Provider**: Azure Blob Storage.
    * **Storage Account**: `<account>`.
    * **Container**: `<container>`.
    * **Client ID**: the app registration's Application (client) ID.
    * **Tenant ID**: the Microsoft Entra ID (Azure AD) directory ID.

    Click **Test Connection** to verify Cube Store can exchange its OIDC
    token with Azure AD and access the container, then **Apply**. Cube Store
    starts writing pre-aggregations to your container on the next refresh.
  </Step>
</Steps>

## Scaling past 20 federated credentials

A single app registration accepts at most **20 federated credentials**.
Three patterns cover most growth scenarios:

* **One app registration per deployment.** Each deployment gets its own
  app + role assignments. Clean isolation, but you have to provision a new
  app every time you add a deployment.
* **Multiple app registrations behind one set of role assignments.** Group
  deployments by access pattern (e.g. read-only vs read-write); each group
  gets its own app, and the role assignments target the same resources.
* **User-assigned managed identities.** Each managed identity has its own
  20-credential limit, and you can attach many of them to your tenant.
  Useful when you want the resource permissions managed in Azure
  alongside other infrastructure rather than as RBAC on app registrations.

If you expect more than \~10 deployments in a single tenant, plan for one
of these patterns up front — splitting later is a recreation, not a
migration.

## Verifying the setup

The fastest way to confirm the federated credential is wired up correctly
is the **Test connection** button on the relevant settings page (data
source wizard, BYO LLM provider). Behind the scenes, Cube issues a real
OIDC token, exchanges it with Azure AD, and returns a precise error if
anything is misconfigured.

If the test fails:

| Symptom                                                                 | Likely cause                                                                                                                                                                                         |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AADSTS70021: No matching federated identity record found`              | The federated credential's `issuer`, `subject`, and `audiences` triple doesn't match the JWT exactly. Compare with the `iss` / `sub` / `aud` of a token from the **Test connection** error response. |
| `AADSTS700213: No matching federated identity record found ... subject` | The subject claim differs by even a single character. Azure doesn't support wildcards — you need one credential per exact subject.                                                                   |
| `AADSTS50034: The user account does not exist`                          | You're using the wrong `AZURE_TENANT_ID`. Double-check the directory ID on the app registration's Overview blade.                                                                                    |
| `AADSTS500011: The resource principal ... was not found`                | The role assignment hasn't been created on the target resource, or it's still propagating. Wait a minute and retry; if it persists, re-check the `--assignee` and `--scope` values.                  |

Federation events show up in **Microsoft Entra ID → Sign-in logs** under
the **Service principal sign-ins** tab — filter by the app registration to
see which deployments are authenticating, when, and which resources they
hit.

[ref-oidc-overview]: /admin/deployment/oidc

[ref-sub-editor]: /admin/deployment/oidc#subject-claim-format

[ref-cube-cloud-region]: /admin/deployment/infrastructure#what-is-a-cube-cloud-region

[ref-export-bucket]: /admin/connect-to-data#export-bucket


# GCP
Source: https://docs.cube.dev/admin/deployment/oidc/gcp

Configure GCP Workload Identity Federation to trust Cube's OIDC issuer and use it for BigQuery and GCS export buckets.

This guide walks through configuring GCP to trust Cube's OIDC issuer using
Workload Identity Federation (WIF) and shows the setup for the most common
targets — BigQuery and a GCS export bucket.

If you haven't enabled OIDC for your tenant yet, start with the
[OIDC overview][ref-oidc-overview].

<Info>
  Available on the [Enterprise plan](https://cube.dev/pricing).
</Info>

## Prerequisites

* The Cube tenant has OIDC enabled and a `GCP` token config exists under
  **Admin → OIDC**.
* IAM access to your GCP project sufficient to create Workload Identity
  Pools, providers, and service accounts.
* Your tenant slug — the leftmost label of your tenant's console URL.
  Throughout this guide it's referenced as `<tenant-name>` (and the full
  issuer URL as `https://<tenant-name>.cubecloud.dev`). Substitute your
  actual slug everywhere it appears.

<Warning>
  Commands and config snippets in this guide use angle-bracket placeholders —
  `<tenant-name>`, `<project-number>`, `<deployment-id>`, etc. **Replace each
  placeholder with your real value** before running. GCP will accept these
  strings literally and the federation call will fail with a confusing error.
</Warning>

## How GCP federation works

Cube doesn't talk to GCP STS directly. Instead, it writes a small
**credential configuration JSON** to disk that points the GCP SDK at the
OIDC token file. The Google client library handles the two-step exchange
internally:

```mermaid theme={"dark"}
sequenceDiagram
    participant Cube as Cube Deployment
    participant STS as Google STS
    participant IAM as IAM Credentials API
    participant BQ as BigQuery / GCS

    Cube->>STS: Exchange OIDC JWT for federated access token<br/>(audience = WIF pool provider URI)
    STS->>Cube: Federated access token
    Cube->>IAM: generateAccessToken on target service account<br/>(impersonation)
    IAM->>Cube: Service account access token (1h)
    Cube->>BQ: Authenticated request
```

You can also skip the impersonation step and grant permissions directly to
the federated principal — see [Direct federation](#direct-federation) at the
end of this page.

## Step 1: Create a Workload Identity Pool and provider

Run these once per GCP project. The pool is a container; the provider is
what actually trusts your Cube issuer.

```bash theme={"dark"}
gcloud iam workload-identity-pools create cube-pool \
  --location=global \
  --display-name="Cube workload identity"

gcloud iam workload-identity-pools providers create-oidc cube \
  --location=global \
  --workload-identity-pool=cube-pool \
  --issuer-uri="https://<tenant-name>.cubecloud.dev" \
  --attribute-mapping="google.subject=assertion.sub,attribute.issuer=assertion.iss" \
  --attribute-condition="assertion.sub.startsWith('cube:deployment:')"
```

What each option does:

| Option                  | Purpose                                                                                                                             |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--issuer-uri`          | Cube tenant URL. GCP fetches `${issuer-uri}/.well-known/openid-configuration` and JWKS from here.                                   |
| `--attribute-mapping`   | Maps the JWT `sub` to GCP's `google.subject`. The mapped subject is what IAM bindings reference when granting impersonation rights. |
| `--attribute-condition` | An optional CEL expression that GCP evaluates on every token exchange. The condition above accepts only deployment-scoped tokens.   |

Note the provider's full resource URI — you'll need it shortly:

```
//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/cube-pool/providers/cube
```

`PROJECT_NUMBER` is the numeric project number, not the project ID. You can
fetch it with `gcloud projects describe PROJECT_ID --format='value(projectNumber)'`.

## Step 2: Set the deployment identity

Add two env vars to your deployment under **Settings → Environment variables**:

```dotenv theme={"dark"}
GCP_POOL_AUDIENCE=//iam.googleapis.com/projects/<project-number>/locations/global/workloadIdentityPools/cube-pool/providers/cube
GCP_SERVICE_ACCOUNT_EMAIL=cube-deployment@my-project.iam.gserviceaccount.com
```

* **`GCP_POOL_AUDIENCE`** — the full resource URI of the WIF provider you
  created in Step 1. This becomes the `aud` claim on the GCP token Cube
  mints.

<Note>
  The GCP token config under **Admin → OIDC** must carry this **exact same**
  provider resource path as its audience (unlike AWS/Azure, GCP has no global
  audience, so it is not auto-filled). If the token config's audience and
  `GCP_POOL_AUDIENCE` disagree, the STS exchange fails with
  `invalid_grant: The audience in ID Token ... does not match the expected
      audience`.
</Note>

* **`GCP_SERVICE_ACCOUNT_EMAIL`** — the service account that Cube
  impersonates after federation succeeds. Cube assumes this service account
  by default for every GCP SDK call inside the deployment.

If you want to skip impersonation entirely and have Cube call GCP services
as the federated principal directly, leave `GCP_SERVICE_ACCOUNT_EMAIL` unset.
See [Direct federation](#direct-federation) below.

## Step 3: Build the IAM bindings

There are two distinct IAM bindings to set:

1. **Workload Identity User** on the impersonated service account — lets
   the federated principal call `generateAccessToken` on it.
2. **Resource access** (BigQuery, GCS, etc.) on the impersonated service
   account itself — what the SA is actually allowed to do once Cube is
   running as it.

The Workload Identity User binding's `--member` controls which Cube
deployments / components can impersonate the SA. Patterns mirror the AWS
`sub` patterns:

| Trust scope                                       | `--member`                                                                                                                                                   |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| One specific deployment, any component            | `principalSet://iam.googleapis.com/projects/123/locations/global/workloadIdentityPools/cube-pool/subject/cube:deployment:<deployment-id>:component:cube_api` |
| Every component of every deployment in the tenant | `principalSet://iam.googleapis.com/projects/123/locations/global/workloadIdentityPools/cube-pool/*`                                                          |
| Only Cube Store, across every deployment          | Use a CEL `--attribute-condition` on the provider that constrains `sub` to end in `:component:cube_store`, then bind the whole pool.                         |

The `principal://` (singular) form pins to one exact subject; `principalSet://`
matches a set.

Cube's default `sub` claim is `cube:deployment:<deployment_id>`. To match
the `:component:<component>` patterns in the table above (or to add
`:region:<region>`), open your GCP token config in **Admin → OIDC** and
paste one of these templates into the **Subject Claim Format** field:

* `cube:deployment:{deployment_id}:component:{component}` — for the
  `principalSet://...subject/cube:deployment:<deployment-id>:component:<component>`
  patterns above.
* `cube:deployment:{deployment_id}:component:{component}:region:{region}` —
  to additionally pin a [Cube Cloud region][ref-cube-cloud-region].

See [the subject editor section][ref-sub-editor] for the full syntax.

<Warning>
  Update the GCP IAM binding (or the WIF provider's CEL `--attribute-condition`)
  first, then change the **Subject Claim Format** on the token config —
  otherwise existing tokens won't match the binding and impersonation will
  fail.
</Warning>

## BigQuery

<Steps>
  <Step title="Create a service account for BigQuery access">
    Provision a regular GCP service account that will hold the BigQuery
    permissions Cube assumes:

    ```bash theme={"dark"}
    gcloud iam service-accounts create cube-deployment \
      --display-name="Cube deployment"
    ```

    Note the email — `cube-deployment@PROJECT_ID.iam.gserviceaccount.com` —
    this is what you'll set as `GCP_SERVICE_ACCOUNT_EMAIL`.
  </Step>

  <Step title="Grant Cube permission to impersonate the service account">
    Bind the federated principal to the service account so the deployment's
    OIDC token can impersonate it:

    ```bash theme={"dark"}
    PROJECT_NUMBER="<project-number>"
    DEPLOYMENT_ID="<deployment-id>"

    gcloud iam service-accounts add-iam-policy-binding \
      cube-deployment@my-project.iam.gserviceaccount.com \
      --role=roles/iam.workloadIdentityUser \
      --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/cube-pool/subject/cube:deployment:${DEPLOYMENT_ID}:component:cube_api"
    ```
  </Step>

  <Step title="Grant the service account BigQuery permissions">
    Standard IAM, as if the service account were any normal workload:

    ```bash theme={"dark"}
    gcloud projects add-iam-policy-binding my-project \
      --member="serviceAccount:cube-deployment@my-project.iam.gserviceaccount.com" \
      --role=roles/bigquery.dataViewer

    gcloud projects add-iam-policy-binding my-project \
      --member="serviceAccount:cube-deployment@my-project.iam.gserviceaccount.com" \
      --role=roles/bigquery.jobUser
    ```

    Tighten these to specific datasets / tables in production. The minimum
    set of roles Cube needs to run BigQuery queries is
    `roles/bigquery.dataViewer` plus `roles/bigquery.jobUser` on the project
    the queries run in.
  </Step>

  <Step title="Configure the deployment">
    Set the BigQuery driver and identity env vars on the deployment:

    ```dotenv theme={"dark"}
    CUBEJS_DB_TYPE=bigquery
    CUBEJS_DB_BQ_PROJECT_ID=my-project
    GCP_POOL_AUDIENCE=//iam.googleapis.com/projects/<project-number>/locations/global/workloadIdentityPools/cube-pool/providers/cube
    GCP_SERVICE_ACCOUNT_EMAIL=cube-deployment@my-project.iam.gserviceaccount.com
    ```

    The BigQuery driver follows the GCP default credential chain, picks up
    the credential config Cube generates, and runs as
    `cube-deployment@my-project.iam.gserviceaccount.com`. No service account
    JSON key is ever used.
  </Step>
</Steps>

## GCS export bucket

If your data source uses an [export bucket][ref-export-bucket] for
pre-aggregation unloads (BigQuery, Snowflake on GCP, etc.), grant the
deployment's service account read / write access to the bucket.

<Steps>
  <Step title="Grant the service account bucket access">
    Add a bucket-scoped IAM binding for the deployment's service account:

    ```bash theme={"dark"}
    gcloud storage buckets add-iam-policy-binding gs://my-export-bucket \
      --member="serviceAccount:cube-deployment@my-project.iam.gserviceaccount.com" \
      --role=roles/storage.objectAdmin
    ```

    `objectAdmin` covers reads, writes, and deletes within the bucket. If
    you only need writes (e.g. you have a separate process cleaning up old
    exports), `roles/storage.objectCreator` is enough.
  </Step>

  <Step title="Configure the export bucket env vars">
    Point the export bucket env vars at your bucket:

    ```dotenv theme={"dark"}
    CUBEJS_DB_EXPORT_BUCKET_TYPE=gcs
    CUBEJS_DB_EXPORT_BUCKET=my-export-bucket
    ```

    The GCS client inside Cube picks up the same default identity. See the
    [export bucket reference][ref-export-bucket] for the full set of
    variables.
  </Step>
</Steps>

<Warning>
  OIDC only covers Cube's **read** side of the export bucket. The data
  warehouse itself (BigQuery, Snowflake on GCP, …) runs the `UNLOAD` /
  `EXPORT DATA` that writes objects to the bucket, and the warehouse cannot
  federate with Cube's OIDC issuer. You still need to provide **separate
  credentials for the unload** so the warehouse can write to GCS — typically
  an HMAC key pair or a warehouse-side service-account integration — via the
  standard export bucket env vars (e.g.
  `CUBEJS_DB_EXPORT_GCS_CREDENTIALS`, or the driver-specific
  storage-integration variables). OIDC then handles Cube's download of the
  unloaded objects from the bucket.
</Warning>

## Direct federation

If you'd rather skip the service account impersonation hop, grant
permissions directly to the federated principal and leave
`GCP_SERVICE_ACCOUNT_EMAIL` unset on the deployment. Cube generates a
credential config that performs only the OIDC-to-federated-token exchange,
and the resulting token is what your code authenticates with.

```bash theme={"dark"}
PROJECT_NUMBER="<project-number>"
DEPLOYMENT_ID="<deployment-id>"

gcloud projects add-iam-policy-binding my-project \
  --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/cube-pool/subject/cube:deployment:${DEPLOYMENT_ID}:component:cube_api" \
  --role=roles/bigquery.dataViewer
```

Direct federation is simpler — fewer moving parts, and the principal
identity in audit logs is the Cube subject itself rather than an
intermediate service account. The trade-off is that some GCP services
(notably anything that requires `iam.serviceAccountTokenCreator`) only
accept service-account principals, so you may need the impersonation path
for those.

## Cube Store CSPS bucket

Cube Store CSPS lets you store pre-aggregations in your own GCS bucket. Cube
Store gets a separate OIDC token whose `sub` claim ends in
`component:cube_store`, so the IAM bindings can be locked down to that
component — even if the same service account were ever shared with the rest
of the deployment, only Cube Store would be able to impersonate it.

Every Cube Store worker emits a `sub` of the form
`cube:deployment:<deployment-id>:component:cube_store`. As with the
[deployment identity bindings](#step-3-build-the-iam-bindings), how broadly
you share access is controlled by the `principalSet` member you bind:

* `…/workloadIdentityPools/cube-pool/*` — paired with a provider
  `--attribute-condition` that constrains `sub` to end in
  `:component:cube_store`, this gives you **one service account + one bucket
  for the whole tenant.** Every deployment writes pre-aggregations to the
  same bucket, isolated by Cube Store's own per-deployment path prefix.
  Easiest to operate.
* `…/cube-pool/subject/cube:deployment:<deployment-id>:component:cube_store`
  — **per-deployment isolation.** Pin access to a single deployment's Cube
  Store so its pre-aggregations live in a dedicated bucket no other
  deployment can touch.

Cube Store can authenticate either by impersonating a service account or by
federating to the bucket directly — pick one.

<Steps>
  <Step title="Grant access to the CSPS bucket">
    **Service account impersonation** (works with every GCS feature). Give a
    service account object access on the bucket, then let the Cube Store
    principal impersonate it:

    ```bash theme={"dark"}
    PROJECT_NUMBER="<project-number>"

    # 1. The SA Cube Store impersonates — grant it object access on the bucket.
    gcloud storage buckets add-iam-policy-binding gs://my-csps-bucket \
      --member="serviceAccount:cube-cubestore@my-project.iam.gserviceaccount.com" \
      --role=roles/storage.objectAdmin

    # 2. Let Cube Store's federated principal impersonate that SA. Swap the
    #    trailing `*` for a single `subject/...:component:cube_store` to pin
    #    one deployment.
    gcloud iam service-accounts add-iam-policy-binding \
      cube-cubestore@my-project.iam.gserviceaccount.com \
      --role=roles/iam.workloadIdentityUser \
      --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/cube-pool/*"
    ```

    **Direct federation** (no impersonation hop). Grant the Cube Store
    principal object access on the bucket directly, and leave the service
    account blank in the UI:

    ```bash theme={"dark"}
    PROJECT_NUMBER="<project-number>"
    DEPLOYMENT_ID="<deployment-id>"

    gcloud storage buckets add-iam-policy-binding gs://my-csps-bucket \
      --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/cube-pool/subject/cube:deployment:${DEPLOYMENT_ID}:component:cube_store" \
      --role=roles/storage.objectAdmin
    ```

    `roles/storage.objectAdmin` covers the reads, writes, lists, and deletes
    Cube Store performs as it builds and evicts pre-aggregation partitions.
  </Step>

  <Step title="Make Cube Store's sub match">
    Cube Store only emits the `:component:cube_store` subject if your GCP
    token config uses a subject claim format that includes the `:component:`
    segment. In **Admin → OIDC**, set the GCP token config's **Subject Claim
    Format** to `cube:deployment:{deployment_id}:component:{component}` (see
    [Step 3](#step-3-build-the-iam-bindings)). Update the IAM binding or the
    provider's CEL `--attribute-condition` before changing the format.
  </Step>

  <Step title="Enable CSPS on each deployment">
    For each deployment that should use this bucket, go to **Settings →
    Pre-Aggregation Storage** on the deployment and:

    * Toggle **Enable CSPS** on.
    * **Storage Provider**: Google Cloud Storage.
    * **GCS Bucket**: `my-csps-bucket`.
    * **Service Account Email** (optional): `cube-cubestore@my-project.iam.gserviceaccount.com` — or leave blank if you granted the Cube Store principal bucket access directly (direct federation).
    * **Workload Identity Provider**: the provider resource name (without the
      `//iam.googleapis.com/` prefix),
      `projects/<project-number>/locations/global/workloadIdentityPools/cube-pool/providers/cube`.

    Click **Test Connection** to verify Cube Store can federate — and
    impersonate the service account, if one is set — and read/write the
    bucket, then **Apply**. Cube Store starts writing pre-aggregations to
    your bucket on the next refresh.
  </Step>
</Steps>

## Verifying the setup

The fastest way to confirm WIF is wired up correctly is the **Test
connection** button on the relevant settings page (data source wizard,
CSPS settings). Behind the scenes, Cube issues a real OIDC token, performs
the GCP STS exchange, optionally impersonates the service account, and
returns a precise error if anything is misconfigured.

If the test fails:

| Symptom                                                     | Likely cause                                                                                                                                                 |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Permission iam.serviceAccounts.getAccessToken denied`      | The Workload Identity User binding on the service account is missing or its `--member` doesn't match the deployment's `sub`. Double-check the principal URI. |
| `INVALID_ARGUMENT: Invalid value for audience`              | `GCP_POOL_AUDIENCE` doesn't match the WIF provider's URI. Re-run `gcloud iam workload-identity-pools providers describe` and copy the value verbatim.        |
| `The token issuer ... does not match the configured issuer` | The provider was created with a different `--issuer-uri` than your tenant URL, or your tenant slug has changed. Re-create the provider with the correct URL. |
| `attribute condition ... evaluated to false`                | The CEL `--attribute-condition` on the provider rejected the token. Inspect the `sub` Cube emits and adjust the condition.                                   |

Federation events show up in **Cloud Audit Logs** under
`sts.googleapis.com` (the token exchange) and `iamcredentials.googleapis.com`
(the SA impersonation). The Cube subject is included in both, so you can
trace which deployment authenticated against which service account at any
point in time.

[ref-oidc-overview]: /admin/deployment/oidc

[ref-sub-editor]: /admin/deployment/oidc#subject-claim-format

[ref-cube-cloud-region]: /admin/deployment/infrastructure#what-is-a-cube-cloud-region

[ref-export-bucket]: /admin/connect-to-data#export-bucket


# OIDC workload identity
Source: https://docs.cube.dev/admin/deployment/oidc/index

Cube's keyless authentication mechanism. Federate your cloud accounts and external services to a Cube-issued OIDC token instead of provisioning long-lived secrets.

OIDC workload identity is Cube's keyless authentication mechanism. Cube acts
as an OpenID Connect (OIDC) identity provider for every deployment in your
account: it mints short-lived, signed JWTs that you federate with the systems
your deployment talks to. The system on the other side — AWS, GCP, Azure,
Snowflake, your own Bedrock-hosted LLM — verifies the token directly against
Cube's published JWKS and grants access, eliminating the need for long-lived
access keys, manual rotation, or shared secrets passed through Cube.

<Info>
  Available on the [Enterprise plan](https://cube.dev/pricing).
</Info>

You can use OIDC workload identity to authenticate to:

* **Data sources** — AWS Athena, Redshift, BigQuery, Snowflake, and any other
  driver that supports federated credentials.
* **Export buckets** — S3 and GCS buckets used for `EXPORT_BUCKET` pre-aggregation
  unloads. OIDC covers Cube's download of the unloaded objects; the warehouse's
  `UNLOAD` write still needs its own credentials configured on the client side
  — see the per-cloud guides for details.
* **Cube Store CSPS** — a per-deployment S3, GCS, or Azure Blob Storage
  bucket that holds your Cube Store pre-aggregations (Customer-Supplied
  Pre-aggregation Storage).
* **Bring-your-own LLM providers** — AWS Bedrock, Google Vertex AI, and Azure
  OpenAI behind your own cloud account.
* **Other cloud services** — any cloud service that supports OIDC federation
  that you'd like to access from the dynamic part of your data model
  (`cube.py` / `cube.js`, dynamic schema generators, `checkAuth`, custom
  pre-aggregation strategies, etc.) — works with the same token.

The same mechanism powers all of these — the only thing that changes between
integrations is the trust policy on the receiving side and which IAM role,
service account, or app registration Cube assumes.

## How it works

If you're new to OpenID Connect, the [OpenID Connect Core 1.0
specification][link-oidc-spec] is the canonical reference; the
[OAuth.com OIDC primer][link-oidc-primer] is a friendlier read. Cube's
implementation is a standard OIDC provider — anything that works with
GitHub Actions OIDC, Vercel OIDC, or AWS IAM OIDC providers works the
same way here.

Each Cube tenant hosts a per-tenant OIDC issuer at its own domain, e.g.
`https://<tenant-name>.cubecloud.dev`. The issuer publishes the standard OIDC discovery
endpoints, and Cube signs every token with a KMS-backed RS256 key.

```mermaid theme={"dark"}
sequenceDiagram
    participant Cube as Cube Deployment
    participant Issuer as Cube OIDC Issuer<br/>(your tenant URL)
    participant STS as Cloud STS<br/>(AWS / GCP / Azure)
    participant Resource as Customer Resource<br/>(Athena / S3 / BigQuery / ...)

    Cube->>Issuer: Request signed JWT for audience X
    Issuer->>Cube: JWT (sub, aud, iss, exp = +1h)
    Cube->>STS: Exchange JWT for temporary credentials
    STS->>Issuer: Fetch JWKS, verify signature, evaluate trust policy
    STS->>Cube: Temporary credentials (1h)
    Cube->>Resource: Access with temporary credentials
```

The deployment never sees an access key or service account JSON. The cloud
SDKs inside Cube — AWS SDK, GCP `google-auth-library`, Azure SDK — pick up
the token automatically from a path supplied by Cube and exchange it with
the cloud's own STS for short-lived credentials.

## Endpoints served by Cube

Each tenant's issuer URL is `https://<tenant-name>.cubecloud.dev`. Cube serves
the standard OIDC endpoints from that domain:

| Endpoint                            | Purpose                                                                                                           |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `/.well-known/openid-configuration` | OIDC discovery document. Cloud providers fetch this to learn the issuer, supported algorithms, and JWKS location. |
| `/.well-known/jwks.json`            | JSON Web Key Set. Contains the public keys cloud providers use to verify token signatures.                        |

Both endpoints are unauthenticated, because they're consumed by AWS STS,
Google STS, Azure AD, and any other relying party that validates
Cube-issued tokens.

## Token configs

A **token config** is a tenant-level entry that tells Cube which audience to
mint tokens for and how to format the `sub` claim each token carries. Each
token config produces one audience-scoped JWT that is delivered to all
deployments in the tenant.

| Field                    | What it controls                                                                                                                                                                                                                                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Audience type**        | One of `AWS`, `GCP`, `Azure`, or `Custom`. `AWS` and `Azure` pre-fill the audience value.                                                                                                                                                                                                                          |
| **Audience**             | The JWT `aud` claim value. Pre-set for `AWS` (`sts.amazonaws.com`) and `Azure` (`api://AzureADTokenExchange`). For `GCP` you supply the **Workload Identity Federation provider resource path** (`//iam.googleapis.com/projects/.../providers/...`) — there is no global GCP audience. User-supplied for `Custom`. |
| **Name**                 | A short, filesystem-safe slug that becomes part of the token file name (`cube_cloud_token_<name>`).                                                                                                                                                                                                                |
| **Subject Claim Format** | Template for the JWT `sub` claim. Defaults to `cube:deployment:{deployment_id}` if left empty.                                                                                                                                                                                                                     |
| **Custom Claims**        | Optional extra JWT claims emitted verbatim in every minted token — see [Custom claims](#custom-claims) below.                                                                                                                                                                                                      |
| **Target Env Var**       | Custom audience type only: env var Cube populates with the token file path in every execution context — see [Custom token configs](#custom-token-configs) below.                                                                                                                                                   |

You can have one config per well-known audience type (AWS, GCP, Azure) plus
any number of custom configs for tools like [Snowflake][ref-oidc-snowflake]
or Databricks. A deployment that integrates with several clouds
simultaneously gets a separate token file per audience — the Cube runtime
picks the right one based on which SDK is making the call.

### Subject claim format

The `sub` claim is what the receiving cloud provider's trust policy matches
on to decide which deployment or component is allowed to assume a role.
Cube's default template is `cube:deployment:{deployment_id}` — sufficient if
you only need to identify the deployment.

To scope further — by component (Cube API vs. Cube Store vs. the AI Engineer)
or by Cube Cloud region — override the template with one of the **Common
templates** the dialog offers:

* `cube:deployment:{deployment_id}` (default)
* `cube:deployment:{deployment_id}:component:{component}`
* `cube:deployment:{deployment_id}:component:{component}:region:{region}`

Three placeholders are supported anywhere in the template:

| Placeholder       | What it resolves to                                                                                                                                            |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{deployment_id}` | The deployment's numeric ID. Substitutes to the literal `global` for tenant-scoped tokens (e.g., AI Engineer running in the control plane).                    |
| `{component}`     | The component requesting the token: `cube_api`, `cube_store`, or `ai_engineer`. Substitutes to `global` when no component context is set.                      |
| `{region}`        | The deployment's [Cube Cloud region][ref-cube-cloud-region]. For tenant-scoped tokens minted in the control plane, substitutes to the literal `control-plane`. |

The component values Cube emits are `cube_api` (the Cube API, refresh
worker, dev-mode pods, Cold Start Workers, etc.), `cube_store` (Cube Store),
and `ai_engineer` (the AI Engineer service, used for BYO LLM auth).

Outside of placeholders, the template may contain only the characters
`[A-Za-z0-9:_-]`. Anything else is rejected at save time.

<Frame>
  <img alt="Add OIDC Token Config dialog in Cube Cloud, showing the Audience Type, Name, Subject Claim Format field with a Common templates picker, and a live preview of the rendered sub claim." />
</Frame>

<Warning>
  Changing the subject claim format on a token config that's already in use
  **will break customer trust policies that pin the old `sub` shape**. Update
  the trust policy in your cloud account first, then change the format here.
</Warning>

<Note>
  Subject claim format changes can take **up to one hour to fully propagate**.
  Already-minted tokens are cached at several layers — the credentials broker
  sidecar and the cloud SDKs' own STS-credential caches — and remain valid
  until their TTL expires (up to 1h). Plan trust-policy rollouts so the new
  `sub` shape is accepted before the old one stops being honored, and expect
  a window where both formats are in flight.
</Note>

### Custom claims

Some token consumers authorize through claims beyond `iss`/`sub`/`aud`. The
canonical example is [Snowflake External OAuth][ref-oidc-snowflake], which
grants session roles exclusively through the `scp` claim — a token without
it authenticates but fails role authorization. The **Custom Claims** field
on a token config adds such claims to every token minted for that audience.

Each claim is a name plus a value. Values are emitted as strings; to emit
an array claim, comma-separate the values (a trailing comma forces a
one-element array). For example, claim `scp` with value `session:role-any`
covers the Snowflake case.

Custom claims are deliberately constrained:

* The registered JWT claims (`iss`, `sub`, `aud`, `exp`, `iat`, `nbf`,
  `jti`) and anything under the `cube:` namespace cannot be overridden —
  those carry the token's identity semantics and stay authoritative.
* Values are strings or arrays of strings only, with bounded lengths.

Like subject-format changes, custom-claim changes take up to one hour to
fully propagate as cached tokens expire.

### Custom token configs

For `Custom` audiences, the driver or SDK on the other side reads the token
from a file. Where that file lives depends on **where the deployment is
running** — deployed pods, a dev-mode worker, and a test-connection probe
each keep it in a different place — so the path must never be hard-coded.

The **Target Env Var** field solves this: name the env var the consumer
reads (e.g. `CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH` for the Snowflake
driver), and Cube sets it to the correct token-file path in every context.
Leave `CUBEJS_DB_USER` / `CUBEJS_DB_PASS` (or the equivalent secret) unset
and don't write the path by hand. Well-known audiences (AWS/GCP/Azure)
don't need this — their SDKs read fixed, standard env vars that Cube
already populates.

The example below — a custom config for the Snowflake driver — combines
both fields: a `scp` custom claim (which Snowflake requires for role
authorization) and a Target Env Var of `CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH`.
The [Snowflake data source page][ref-oidc-snowflake] walks through the full setup.

<Frame>
  <img alt="Edit OIDC Token Config dialog in Cube Cloud for a custom Snowflake audience: Custom audience type, the Snowflake account URL as the custom audience, a Target Env Var of CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH, and a custom claim scp set to session:role-any." />
</Frame>

## Trust mechanism

The receiving system trusts Cube tokens by referencing two things:

1. **The issuer URL** — `https://<tenant-name>.cubecloud.dev`. The cloud
   provider fetches your tenant's JWKS from this URL and uses it to validate
   every token signature. As long as Cube holds the matching private key,
   tokens issued for your tenant verify; tokens issued by any other Cube
   tenant do not.
2. **The subject claim** — `sub`. The trust policy on the receiving side
   matches the `sub` exactly (or with wildcards) against the format you
   configured above to decide which deployments / components are allowed
   in.

## Token lifecycle

| Property         | Value                                                                                                                                                                       |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Algorithm**    | RS256                                                                                                                                                                       |
| **TTL**          | 1 hour                                                                                                                                                                      |
| **Refresh**      | Automatic — Cube re-mints each token before it expires and atomically replaces the token file. The cloud SDK on the other side picks up the new token without reconnecting. |
| **Signing keys** | Per-tenant, KMS-backed. Rotated regularly; the JWKS endpoint always serves the current and previous public keys so in-flight tokens remain valid across rotations.          |
| **Revocation**   | TTL-based. Emergency revocation is performed by rotating the signing key, which invalidates all tokens within the next TTL window.                                          |

## Enabling OIDC for your tenant

Workload identity is configured at the **tenant** level under
**Admin → OIDC**. From there, you turn the issuer on and create one token
config per integration target.

<Steps>
  <Step title="Enable the OIDC issuer">
    In **Admin → OIDC**, flip the **OIDC token issuance is active for all
    deployments** switch to on. This activates the discovery and JWKS
    endpoints on your tenant URL and unlocks the deployment-level OIDC
    settings everywhere else in the UI. Click **OpenID Configuration** or
    **JWKS Endpoint** to grab the URLs you'll hand to your cloud provider
    when configuring federation.

    <Frame>
      <img alt="Admin → OIDC page in Cube Cloud showing the enable toggle, issuer URL, discovery and JWKS endpoint links, and the configured token configs table." />
    </Frame>
  </Step>

  <Step title="Add token configs">
    Click **Add Config** and pick the audience type. For `AWS` and `Azure`,
    the audience auto-fills with the standard value. For `GCP`, enter the
    **Workload Identity Federation provider resource path** (the same
    `//iam.googleapis.com/projects/.../providers/...` value you use for
    `GCP_POOL_AUDIENCE`) — GCP has no global audience. For `Custom`, enter the
    audience your target system expects. Optionally set the **Subject Claim
    Format** — see [Token configs](#token-configs) for the available templates.
  </Step>

  <Step title="Configure trust on the cloud side">
    Follow the cloud-specific guides below to register Cube as an OIDC
    provider on the system you want Cube to access, create a role / service
    account / app registration, and write a trust policy that pins the
    issuer URL and the subject pattern.

    <CardGroup>
      <Card title="Amazon Web Services" href="/admin/deployment/oidc/aws">
        Athena, S3 export buckets, Bedrock, and any other AWS-IAM-protected service.
      </Card>

      <Card title="Google Cloud Platform" href="/admin/deployment/oidc/gcp">
        BigQuery, GCS export buckets, and any other GCP service via Workload Identity Federation.
      </Card>

      <Card title="Microsoft Azure" href="/admin/deployment/oidc/azure">
        Azure SQL, Blob Storage export buckets, and any other Azure service via federated credentials.
      </Card>
    </CardGroup>
  </Step>

  <Step title="Set deployment identity environment variables">
    For each deployment, set the cloud-specific "who to become" env vars
    under **Settings → Environment variables**. These point Cube at the
    role or service account it should assume on your side:

    | Cloud | Env vars                                         |
    | ----- | ------------------------------------------------ |
    | AWS   | `AWS_ROLE_ARN`                                   |
    | GCP   | `GCP_POOL_AUDIENCE`, `GCP_SERVICE_ACCOUNT_EMAIL` |
    | Azure | `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`             |

    These are the **default identity** for the deployment — see below.
  </Step>
</Steps>

## Default identity for a deployment

When you set `AWS_ROLE_ARN` (or the GCP / Azure equivalents) on a deployment,
that role becomes the default cloud identity for everything that runs inside
that deployment:

* **Drivers** that follow the AWS / GCP / Azure default credential chain
  (Athena, Redshift, BigQuery, RDS Postgres / MySQL with IAM auth, Azure SQL,
  and more) automatically authenticate as this role / service account.
* **Pre-aggregation export bucket I/O** uses the same identity to write to
  S3 / GCS / Blob Storage.
* **Code in your data model** — `dataSource` factories, `driverFactory`,
  `extendContext`, `checkAuth`, dynamic schema generators — runs with the same
  default identity. If you instantiate an AWS / GCP / Azure SDK client with no
  explicit credentials, it picks up the deployment's OIDC token automatically.

If you need a driver to talk to a different role or service account than the
deployment default — for example, the deployment's default role can read S3
but a specific Athena workgroup lives in a different account — set the
**driver-specific assume-role env var** in addition to the default. The
driver then uses the default identity to perform a second
`AssumeRole` / impersonation hop and connect as the downstream principal.

| Driver            | Driver-specific assume-role env var                                                              |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| AWS Athena        | `CUBEJS_AWS_ATHENA_ASSUME_ROLE_ARN`                                                              |
| AWS Redshift      | `CUBEJS_DB_AWS_ROLE_ARN`                                                                         |
| Other AWS drivers | Driver-specific — see the driver page in [Connect to data](/admin/connect-to-data/data-sources). |

The chain is always:

```
Cube OIDC token  →  default deployment identity  →  (optional) driver-specific assumed role
```

Most setups don't need the second hop — granting permissions directly to the
deployment's default role is simpler and easier to reason about.

## Cube Store CSPS

Cube Store can store its pre-aggregations in a **per-deployment** S3, GCS, or
Azure Blob Storage bucket that you own — Customer-Supplied Pre-aggregation
Storage (CSPS). When you enable CSPS for a deployment, Cube Store
authenticates to your bucket with the same OIDC machinery as the rest of the
deployment. The trust policy (AWS IAM role / Azure federated credential) pins
the `sub` claim to `cube:deployment:<deployment-id>:component:cube_store`,
giving Cube Store its own identity that's distinct from the Cube API.

CSPS is configured under **Settings → Pre-Aggregation Storage** on the
deployment. See
[AWS](/admin/deployment/oidc/aws#cube-store-csps-bucket),
[GCP](/admin/deployment/oidc/gcp#cube-store-csps-bucket), and
[Azure](/admin/deployment/oidc/azure#azure-blob-storage-csps-bucket) for the
trust policy shape on each cloud.

## Audit trail

Every token Cube issues is recorded in the tenant audit log with the
deployment ID, component, audience, and TTL. On the receiving side, the
cloud's own audit trail shows the federation event:

* **AWS CloudTrail** — `AssumeRoleWithWebIdentity` events with the deployment
  subject.
* **GCP Cloud Audit Logs** — Workload Identity Federation token-exchange and
  service-account-impersonation events.
* **Azure Activity Log** — Federated-credential sign-in events on the app
  registration.

Together these give you an end-to-end record of which deployment accessed
which resource and when, without ever issuing a long-lived credential.

[ref-oidc-aws]: /admin/deployment/oidc/aws

[ref-oidc-gcp]: /admin/deployment/oidc/gcp

[ref-oidc-azure]: /admin/deployment/oidc/azure

[ref-oidc-snowflake]: /admin/connect-to-data/data-sources/snowflake#oidc-workload-identity

[ref-env-vars]: /admin/deployment#environment-variables

[ref-data-sources]: /admin/connect-to-data/data-sources

[ref-sub-editor]: /admin/deployment/oidc#subject-claim-format

[ref-cube-cloud-region]: /admin/deployment/infrastructure#what-is-a-cube-cloud-region

[link-oidc-spec]: https://openid.net/specs/openid-connect-core-1_0.html

[link-oidc-primer]: https://www.oauth.com/oauth2-servers/openid-connect/


# Scalability
Source: https://docs.cube.dev/admin/deployment/scalability

Tune Cube Cloud throughput and pre-aggregation capacity by scaling API instances and Cube Store workers.

Cube Cloud also allows adding additional infrastructure to your deployment to
increase scalability and performance beyond what is available with each
Dedicated deployment.

## Auto-scaling of API instances

With a Dedicated deployment, 2 Cube API Instances are included. That said, it
is very common to use more, and [additional API instances][ref-limits] can be
added to your deployment to increase the throughput of your queries. A rough
estimate is that 1 Cube API Instance is needed for every 5-10
requests-per-second served. Cube API Instances can also auto-scale as needed.

To change how many Cube API instances are available in the Dedicated deployment,
go to the deployment’s **Settings** screen, and open
the **Configuration** tab. From this screen, you can set the minimum and
maximum number of Cube API instances for a deployment:

<Frame>
  <img alt="Cube Cloud Deployment Settings page showing auto-scaling configuration options" />
</Frame>

## Sizing Cube Store workers

Cube Store Workers are used to build and persist pre-aggregations. Each Worker
has a **maximum of 150GB** of storage; [additional Cube Store
workers][ref-limits] can be added to your deployment to both increase storage
space and improve pre-aggregation performance. A **minimum of 2** Cube Store
Workers is required for pre-aggregations; this can be adjusted. For a rough
estimate, it will take approximately 2 Cube Store Workers per 4 GB of
pre-aggregated data per day.

<Info>
  Idle workers will automatically hibernate after 10 minutes of inactivity, and
  will not consume CCUs until they are resumed. Workers are resumed automatically
  when Cube receives a query that should be accelerated by a pre-aggregation, or
  when a scheduled refresh is triggered.
</Info>

To change the number of Cube Store Workers in a deployment, go to the
deployment’s **Settings** screen, and open the **Configuration**
tab. From this screen, you can set the number of Cube Store Workers from the
dropdown:

<Frame>
  <img alt="Cube Cloud Deployment Settings page showing auto-scaling configuration options" />
</Frame>

[ref-limits]: /admin/deployment/limits#resources


# Deployment warm-up
Source: https://docs.cube.dev/admin/deployment/warm-up

Covers optional pre-launch warm-up for data model compilation and pre-aggregations on Dedicated deployments.

Deployment warm-up improves querying performance by executing time-consuming
tasks after a Cube Cloud deployment is spun up but before it's exposed to
requests from users.

<Note>
  Available on [Starter and above plans](https://cube.dev/pricing).
</Note>

<Info>
  Deployment warm-up is only available for [Dedicated][ref-prod-cluster]
  and [Multi-cluster][ref-prod-multi-cluster] deployments.
</Info>

There are two warm-up options:

* [Data model warm-up](#data-model-warm-up) — compiles the data model and
  populates data model compilation cache ahead of time.
* [Pre-aggregation warm-up](#pre-aggregation-warm-up) — builds and refreshes
  pre-aggregations ahead of time.

## Data model warm-up

By default, an API instance compiles the [data model][ref-data-model] and
stores results in the data model compilation cache when the first request hits
that API instance. For [multi-tenant][ref-multitenancy] configurations, a
request from a particular tenant would only trigger the data model compilation
for that tenant.

Depending on the complexity of the data model (i.e., the number of cubes,
views, and their members) and the use of [dynamic data models][ref-dynamic-data-model],
its compilation might take from a few milliseconds to a few seconds.

Data-model warm-up will compile the data model before a Cube Cloud deployment
is exposed to requests from users, making sure that they aren't affected by
the data model compilation time.

<Info>
  If a data model warm-up takes more than 15 minutes, the deployment will be
  considered unhealthy and rolled back.
</Info>

### Configuring data model warm-up

To configure data model warm-up, navigate to **Settings → Configuration**
and enable **Warm-up data model before deploying API**:

<Frame>
  <img />
</Frame>

## Pre-aggregation warm-up

By default, the refresh worker takes care of [pre-aggregation][ref-pre-aggs]
refresh and runs pre-aggregation builds. When first requests hit API instances,
it's possible that pre-aggregations would still be being built and users would
need to wait or the completion of that process.

Depending on the volume of data and the configuration of pre-aggregations,
their builds might take from seconds to minutes.

Pre-aggregation warm-up will refresh pre-aggregations before a Cube Cloud
deployment is exposed to requests from users, making sure they aren't affected
by the pre-aggregation build time.

<Info>
  If a pre-aggregation warm-up takes more than 24 hours, it will be cancelled.
  However, the deployment will still succeed.
</Info>

### Configuring pre-aggregation warm-up

To configure pre-aggregation warm-up, navigate to **Settings → Configuration**
and enable **Warm-up pre-aggregations before deploying API**:

<Frame>
  <img />
</Frame>

[ref-prod-cluster]: /admin/deployment/deployment-types#dedicated

[ref-prod-multi-cluster]: /admin/deployment/deployment-types#multi-cluster

[ref-data-model]: /docs/data-modeling/overview

[ref-dynamic-data-model]: /docs/data-modeling/dynamic

[ref-multitenancy]: /embedding/multitenancy

[ref-pre-aggs]: /docs/pre-aggregations#pre-aggregations


# Alerts
Source: https://docs.cube.dev/admin/monitoring/alerts

Set up email alerts for API outages, database timeouts, pre-aggregation failures, and build completions in Cube.

Alerts notify you by email when something happens in your account: an API goes
down, a database stops responding in time, a pre-aggregation build fails, or a
build finishes.

<Note>
  Available on [Premium and above plans](https://cube.dev/pricing).
</Note>

## Manage alerts

Click **Alerts** in the sidebar to see every alert configured on the account. Click
**New alert** to add one, or use the edit and delete icons on a row to change or remove
an existing alert.

On plans below [Enterprise](https://cube.dev/pricing), only account administrators can
manage alerts. On the Enterprise plan, access also follows the `AlertsCreate`,
`AlertsRead`, `AlertsUpdate`, and `AlertsDelete` actions. Administrators always have
access, and the built-in Developer and AIBI Developer roles carry all four. The same four
actions also govern [budgets](/admin/account-billing/budgets).

<Note>
  These four actions are not among the ones you can pick when you build a [custom
  role][ref-custom-roles]. To grant them, assign a built-in Developer or AIBI Developer
  role.
</Note>

## Event types

Each alert watches a single event type:

| Event type                         | What it detects                                                     | Resolved email |
| ---------------------------------- | ------------------------------------------------------------------- | -------------- |
| **API outages**                    | The API stops responding                                            | Yes            |
| **Database response timeouts**     | The database takes too long to answer                               | Yes            |
| **Pre-aggregation build failures** | A [pre-aggregation](/admin/monitoring/pre-aggregations) build fails | Yes            |
| **Build completed**                | A build reaches a terminal state                                    | No             |
| **All**                            | Every event type above                                              | Per event type |

The first three are conditions: Cube emails you when the condition starts, then emails
you again with a `Resolved —` subject prefix when it clears. While a condition persists,
Cube does not re-send the same alert for a while — 1 hour for API outages and database
response timeouts, 3 hours for pre-aggregation build failures.

<Warning>
  **Build completed** fires when a build finishes, whether it succeeded or failed. The
  subject line reads `Build finished with status: <status>`. It is a point-in-time event,
  so it has no resolved email.
</Warning>

## Deployments

An alert applies either to **All** deployments in the account, or to a **Specific** set
you pick. Choosing **Specific** requires at least one deployment.

## Recipients

Under **Send alerts to**, pick either **All users on this account** or **Specific users**.
Under **Also send to**, add any number of custom email addresses; these are additive, and
a custom address on its own is a valid set of recipients.

<Note>
  **All users on this account** only reaches users who have signed in at least once. Users
  who were invited but never signed in do not receive alerts.
</Note>

## Delivery

Alerts are delivered by email only — there is no Slack, webhook, or PagerDuty delivery.
[Scheduled refresh notifications](/docs/explore-analyze/notifications), which cover
dashboard refresh outcomes, are a separate feature with its own delivery channels.

To alert from your own observability stack instead, export telemetry with [monitoring
integrations](/admin/monitoring/monitoring-integrations).

[ref-custom-roles]: /admin/users-and-permissions/custom-roles


# Audit Log
Source: https://docs.cube.dev/admin/monitoring/audit-log

Learn how to turn on Audit Log in Cube Cloud, review security events across deployments, and download them for compliance reviews.

Audit Log collects, stores, and displays security-related events within a Cube Cloud
account, across all deployments. You can use it to maintain and review a historical
record of activity for compliance purposes.

<Note>
  Available on the [Enterprise plan](https://cube.dev/pricing).
</Note>

Read below about [collected events](#event-types). Also, see how you can [enable](#configuration)
Audit Log, [view events](#viewing-events), and [download](#downloading-events) them.

## Configuration

To enable Audit Log, navigate to the **Team & Security** page, open the
**Audit Log** tab, and turn the **Enable Audit Log** switch on.

## Viewing events

### Table view

Audit Log displays events in a table with the following information for each event:

* Event timestamp in your local time zone.
* User email, if applicable to a particular event.
* Event name (see [event types](#event-types) for the full list).
* Deployment name, if applicable to a particular event.

### Extended view

You can click on any event to view extended information:

* IP address from which an event was initiated.
* Event-specific attributes.

#### Sanitization

Audit Log uses heuristics to detect sensitive values (e.g., passwords and tokens)
and sanitize them, i.e., replace them with `[HIDDEN]` in event-specific
attributes. You can see that a password was sanitized on the screenshot above.

If you'd like your custom environment variable to be sanitized, include one of
the following substrings in its name: `PASS`, `SECRET`, `TOKEN`, `KEY`.

### Filters

You can also customize the table view with filters on the top and in the right sidebar:

* Text input for full-text search.
* Date range filter.
* Filters to narrow the view down to a specific user, event, or deployment.

## Downloading events

You can use the **↓ CSV** button to download a CSV file with all events in the
current view:

## Exporting events via API

You can also export audit log events as a CSV file programmatically using the
[`/api/v1/audit-logs/export`][ref-audit-log-api] endpoint of the
[Control Plane API][ref-control-plane-api]. This is useful for integrating
with external log aggregation or SIEM tools.

## Event types

Audit Log collects the following types of events:

| Category                                                         | Event type                                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Users                                                            | `Created user`<br />`Deleted user`<br />`Invited user`<br />`Updated user profile`<br />`Requested password reset`<br />`Changed password`                                                                                                                                                                                                                                                                      |
| SCIM provisioning                                                | `Created user via SCIM`<br />`Updated user via SCIM`<br />`Deleted user via SCIM`<br />`Created group via SCIM`<br />`Updated group via SCIM`<br />`Deleted group via SCIM`                                                                                                                                                                                                                                     |
| [Custom roles](/admin/users-and-permissions/custom-roles)        | `Created role`<br />`Deleted role`<br />`Updated role`<br />`Assigned role to user`<br />`Assigned roles to user`<br />`Removed role from user`                                                                                                                                                                                                                                                                 |
| Authentication                                                   | `Logged in`<br />`Logged out`<br />`Redirected to SAML provider for login`<br />`Logged in via SAML`                                                                                                                                                                                                                                                                                                            |
| Account and [single sign-on](/admin/sso)                         | `Updated account settings`<br />`Updated account authentication configuration`<br />`Updated account SAML configuration`<br />`Uploaded identity provider metadata file`                                                                                                                                                                                                                                        |
| [Deployments](/admin/deployment)                                 | `Created deployment`<br />`Deleted deployment`<br />`Updated deployment configuration`<br />`Enabled SQL API for deployment`<br />`Generated data model`                                                                                                                                                                                                                                                        |
| Branches and [dev mode](/docs/data-modeling/dev-mode)            | `Created Git branch`<br />`Deleted Git branch`<br />`Entered dev mode`<br />`Exited dev mode`<br />`Pulled changes to data model`<br />`Committed and merged changes to data model`<br />`Merged changes to data model`<br />`Reverted changes to data model in branch`                                                                                                                                         |
| [Continuous deployment](/admin/deployment/continuous-deployment) | `Requested connection of GitHub account`<br />`Connected deployment to GitHub repository`<br />`Generated SSH key for deployment`<br />`Connected deployment to Git upstream`<br />`Generated Git credentials for Cube Cloud repository`<br />`Generated webhook token for Git repository`<br />`Received a Git hook`<br />`Started uploading files`<br />`Finished uploading files`<br />`Triggered new build` |
| [Budgets](/admin/account-billing/budgets)                        | `Created budget`<br />`Deleted budget`<br />`Updated budget`                                                                                                                                                                                                                                                                                                                                                    |

[ref-control-plane-api]: /reference/control-plane-api

[ref-audit-log-api]: /reference/control-plane-api#%2Fapi%2Fv1%2Faudit-logs%2Fexport


# Chats History
Source: https://docs.cube.dev/admin/monitoring/chats-history

Admins can access users chat history through Admin → Chats History.

It's possible to search specific chats by the first message content or chat UUID.
You can also filter the list by user type, creation date, and source
(**Web**, **MCP**, **Slack**, **Scheduled**, or **API**).

<video />


# Integration with Amazon CloudWatch
Source: https://docs.cube.dev/admin/monitoring/monitoring-integrations/cloudwatch

Export Cube Cloud deployment logs to Amazon CloudWatch using Vector and an aws_cloudwatch_logs sink configuration.

[Amazon CloudWatch](https://aws.amazon.com/cloudwatch/) is an application
monitoring service that collects and visualizes logs, metrics, and event data.
This guide demonstrates how to set up Cube Cloud to export logs to Amazon
CloudWatch.

## Configuration

First, enable [monitoring integrations][ref-monitoring-integrations] in Cube
Cloud.

### Exporting logs

To export logs to Amazon CloudWatch, start by creating [a log group and a log
stream](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)
for Cube Cloud logs.

Then, configure the [`aws_cloudwatch_logs`](https://vector.dev/docs/reference/configuration/sinks/aws_cloudwatch_logs/)
sink in your [`vector.toml` configuration file][ref-monitoring-integrations-conf].

Example configuration:

```toml theme={"dark"}
[sinks.aws_cloudwatch_logs]
type = "aws_cloudwatch_logs"
inputs = [
  "cubejs-server",
  "refresh-scheduler",
  "warmup-job",
  "cubestore"
]
region = "us-east-1"
group_name = "your-group-name"
stream_name = "your-stream-name"
create_missing_group = true
create_missing_stream = true

[sinks.aws_cloudwatch_logs.auth]
access_key_id = "$CUBE_CLOUD_MONITORING_AWS_ACCESS_KEY_ID"
secret_access_key = "$CUBE_CLOUD_MONITORING_AWS_SECRET_ACCESS_KEY"

[sinks.aws_cloudwatch_logs.encoding]
codec = "json"
```

Commit the configuration for Vector, it should take effect in a minute. Then,
navigate to Amazon CloudWatch and watch the logs coming.

## Keyless authentication

Instead of the access key pair above, Vector can authenticate to CloudWatch with
the deployment's [OIDC][ref-oidc] identity — no static credentials stored in
Cube, and nothing to rotate.

The credentials apply to the **whole Vector agent**, not just this sink, so the
same role also covers the [S3][ref-s3] and [Query History export][ref-query-history-export]
sinks if you use them.

<Note>
  Requires [OIDC][ref-oidc] enabled for your tenant with an `AWS` token config.
</Note>

<Steps>
  <Step title="Create the IAM role">
    [Register Cube as an OIDC provider][ref-oidc-aws-provider] in your AWS
    account — a one-time step per account — then follow
    [Monitoring integrations][ref-oidc-aws-cloudwatch] to create a role that
    trusts your deployment and can write to the log group.

    Two things to carry over from that section: the `sub` claim needs the
    non-default `:component:` **Subject Claim Format**, and
    `logs:DescribeLogGroups` must be scoped to `"*"` or Vector's healthcheck
    fails at startup.
  </Step>

  <Step title="Set the deployment environment variables">
    Under **Settings → Environment variables**:

    ```dotenv theme={"dark"}
    CUBE_CLOUD_MONITORING_AWS_ROLE_ARN=arn:aws:iam::<aws-account-id>:role/<role-name>
    ```

    The role ARN is the only required variable — setting it is what turns
    keyless authentication on.

    The credential exchange also needs a region, which Cube takes from your
    sink's `region`. Set `CUBE_CLOUD_MONITORING_AWS_REGION` only to override
    that, for example when the STS region should differ from the sink's.
  </Step>

  <Step title="Drop the auth block from vector.toml">
    Omit `[sinks.*.auth]` entirely so Vector falls back to the AWS SDK's default
    credential chain, which picks up the OIDC token Cube mounts for it:

    ```toml theme={"dark"}
    [sinks.aws_cloudwatch_logs]
    type = "aws_cloudwatch_logs"
    # "warmup-job" is omitted deliberately — see the warning below.
    inputs = [
      "cubejs-server",
      "refresh-scheduler",
      "cubestore"
    ]
    region = "us-east-1"
    group_name = "your-group-name"
    stream_name = "your-stream-name"
    # Add create_missing_group = true only if you also grant
    # logs:CreateLogGroup to the role.
    create_missing_stream = true

    [sinks.aws_cloudwatch_logs.encoding]
    codec = "json"
    ```

    Leaving an `auth` block in place keeps the static keys in use — the two are
    mutually exclusive.
  </Step>
</Steps>

<Warning>
  Keyless authentication does not cover the **`warmup-job`** input. The
  [pre-aggregation warm-up][ref-preagg-warmup] runs as a Kubernetes Job that does
  not receive the OIDC token, so its logs will not reach CloudWatch on this path
  while the other inputs succeed. If you need warm-up logs in CloudWatch, keep
  using the access key pair.
</Warning>

[ref-monitoring-integrations]: /admin/monitoring/monitoring-integrations

[ref-monitoring-integrations-conf]: /admin/monitoring/monitoring-integrations#configuration

[ref-oidc]: /admin/deployment/oidc

[ref-oidc-aws-cloudwatch]: /admin/deployment/oidc/aws#monitoring-integrations-cloudwatch-s3

[ref-oidc-aws-provider]: /admin/deployment/oidc/aws#step-1-register-cube-as-an-oidc-provider-in-aws

[ref-s3]: /admin/monitoring/monitoring-integrations/s3

[ref-query-history-export]: /admin/monitoring/query-history-export

[ref-preagg-warmup]: /admin/deployment/warm-up


# Integration with Datadog
Source: https://docs.cube.dev/admin/monitoring/monitoring-integrations/datadog

Datadog is a popular fully managed observability service. This guide demonstrates how to set up Cube Cloud to export logs and metrics to Datadog.

[Datadog][datadog] is a popular fully managed observability service. This guide
demonstrates how to set up Cube Cloud to export logs and metrics to Datadog.

## Configuration

First, enable [monitoring integrations][ref-monitoring-integrations] in Cube
Cloud.

### Exporting logs

To export logs to Datadog, go to **Organization Settings → API Keys**
obtain an API key:

<Frame>
  <img />
</Frame>

Then, configure the [`datadog_logs`][vector-datadog-logs] sink in your
[`vector.toml` configuration file][ref-monitoring-integrations-conf].

Example configuration:

```toml theme={"dark"}
[sinks.datadog_logs]
type = "datadog_logs"
inputs = [
  "cubejs-server",
  "refresh-scheduler",
  "warmup-job",
  "cubestore"
]
default_api_key = "$CUBE_CLOUD_MONITORING_DATADOG_API_KEY"
site = "datadoghq.eu"
compression = "gzip"
healthcheck = false
```

Note that Datadog accounts belong to specific [sites][datadog-docs-sites]
throughout the world. Use the `site` option to configure the sink appropriately.
When miscofigured, Vector agent outputs the following error:
`Client request was forbidden`.

Commit the configuration for Vector, it should take effect in a minute. Then,
navigate to **Logs** in Datadog and watch the logs coming:

<Frame>
  <img />
</Frame>

### Exporting metrics

To export metrics to Datadog, use the same API key from
**Organization Settings → API Keys** as configured for logs.

Then, configure the [`datadog_metrics`][vector-datadog-metrics] sink in your
[`vector.toml` configuration file][ref-monitoring-integrations-conf].

Example configuration:

```toml theme={"dark"}
[sinks.datadog_metrics]
type = "datadog_metrics"
inputs = [
  "metrics"
]
default_api_key = "$CUBE_CLOUD_MONITORING_DATADOG_API_KEY"
site = "datadoghq.eu"
```

Again, upon commit the configuration for Vector should take effect in a minute. Then,
navigate to **Metrics → Summary** in Datadog and explore the available
metrics. Cube metrics are prefixed with `cube_`, such as `cube_cpu_usage_ratio`,
`cube_memory_usage_ratio`, and `cube_requests_total`.

[datadog]: https://www.datadoghq.com

[datadog-docs-sites]: https://docs.datadoghq.com/getting_started/site/

[vector-datadog-logs]: https://vector.dev/docs/reference/configuration/sinks/datadog_logs/

[vector-datadog-metrics]: https://vector.dev/docs/reference/configuration/sinks/datadog_metrics/

[ref-monitoring-integrations]: /admin/monitoring/monitoring-integrations

[ref-monitoring-integrations-conf]: /admin/monitoring/monitoring-integrations#configuration


# Integration with Google Cloud Storage
Source: https://docs.cube.dev/admin/monitoring/monitoring-integrations/gcs

Google Cloud Storage is a popular object storage system. This guide demonstrates how to set up Cube to export logs to Google Cloud Storage.

[Google Cloud Storage](https://cloud.google.com/storage) is a popular object
storage system. This guide demonstrates how to set up Cube to export logs to
Google Cloud Storage.

## Configuration

First, enable [monitoring integrations][ref-monitoring-integrations] in Cube.

### Exporting logs

To export logs to Google Cloud Storage, start by creating a bucket for Cube logs
and a service account that can write to it.

Then, put the service account key in an environment variable under **Settings →
Environment variables**, base64-encoded. The name must start with
`CUBE_CLOUD_MONITORING_` — only variables with that prefix are available to the
Vector agent:

```bash theme={"dark"}
CUBE_CLOUD_MONITORING_GCS_CREDENTIALS=eyJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsIC4uLn0=
```

Finally, configure the [`gcp_cloud_storage`](https://vector.dev/docs/reference/configuration/sinks/gcp_cloud_storage/)
sink in your [`vector.toml` configuration file][ref-monitoring-integrations-conf].

Example configuration:

```toml theme={"dark"}
[sinks.gcp-cloud-storage]
type = "gcp_cloud_storage"
inputs = [
  "cubejs-server",
  "refresh-scheduler",
  "warmup-job",
  "cubestore"
]
bucket = "your-gcs-bucket-name"
compression = "gzip"
credentials_base64 = "$CUBE_CLOUD_MONITORING_GCS_CREDENTIALS"

[sinks.gcp-cloud-storage.encoding]
codec = "json"

[sinks.gcp-cloud-storage.healthcheck]
enabled = false
```

Commit the configuration for Vector, it should take effect in a minute. Then,
navigate to your bucket and watch the logs coming.

### Authentication

Authenticate with the `credentials_base64` option, referencing the environment
variable that holds the base64-encoded service account key, as in the example above.
This is the only supported way to give the sink its credentials.

`credentials_base64` is specific to Cube — it does not appear in [Vector's own sink
reference][vector-docs-sinks-gcs]. Cube decodes the key and provides it to the Vector
agent as a file named after the sink.

<Warning>
  The sink name becomes the name of a Kubernetes object that carries the credentials
  file, so it must be lowercase alphanumeric characters and dashes only — **no
  underscores**. A sink named `query_history_gcs` will not get a credentials file; name
  it `query-history-gcs` instead.
</Warning>

### Healthcheck

The example above sets `healthcheck.enabled = false`. Vector's
`gcp_cloud_storage` healthcheck sends a `HEAD` request to the bucket root, which
requires the `storage.objects.list` permission — write access alone, such as
`roles/storage.objectCreator`, does not grant it. Without this, the sink fails to
start with a forbidden-healthcheck error even though it could write objects
successfully.

With the healthcheck disabled, the sink always starts and reports healthy, so check
the bucket itself to confirm that data is arriving.

### Exporting Query History

Add the `query-history` input to the sink to bring [Query History
export][ref-query-history-export] data to the same bucket.

<Warning>
  Query History export additionally requires the **Monitoring Integrations Tier** of
  your deployment to be set to **Medium (Up to 50 GB/mo)**. On a lower tier it fails
  silently — the sink reports healthy and the bucket stays empty, with no error
  logged anywhere.
</Warning>

[ref-monitoring-integrations]: /admin/monitoring/monitoring-integrations

[ref-monitoring-integrations-conf]: /admin/monitoring/monitoring-integrations#configuration

[ref-query-history-export]: /admin/monitoring/monitoring-integrations#query-history-export

[vector-docs-sinks-gcs]: https://vector.dev/docs/reference/configuration/sinks/gcp_cloud_storage/


# Integration with Grafana Cloud
Source: https://docs.cube.dev/admin/monitoring/monitoring-integrations/grafana-cloud

Grafana Cloud is a popular fully managed observability service. This guide demonstrates how to set up Cube Cloud to export logs to Grafana Cloud.

[Grafana Cloud][grafana] is a popular fully managed observability service. This
guide demonstrates how to set up Cube Cloud to export logs to Grafana Cloud.

## Configuration

First, enable [monitoring integrations][ref-monitoring-integrations] in Cube
Cloud.

### Exporting logs

To export logs to Grafana Cloud, go to your account and get credentials for
Loki, the logging service in Grafana Cloud:

<Frame>
  <img />
</Frame>

Then, configure the [`loki`][vector-loki] sink in your [`vector.toml`
configuration file][ref-monitoring-integrations-conf].

Example configuration:

```toml theme={"dark"}
[sinks.loki]
type = "loki"
inputs = [
  "cubejs-server",
  "refresh-scheduler",
  "warmup-job",
  "cubestore"
]
endpoint = "https://logs-prod-012.grafana.net"

[sinks.loki.auth]
strategy = "basic"
user = "$CUBE_CLOUD_MONITORING_GRAFANA_CLOUD_USER"
password = "$CUBE_CLOUD_MONITORING_GRAFANA_CLOUD_PASSWORD"

[sinks.loki.encoding]
codec = "json"

[sinks.loki.cubestore]
levels = [
  "trace",
  "info",
  "debug",
  "error"
]

[sinks.loki.labels]
app = "cube-cloud"
env = "production"
```

Commit the configuration for Vector, it should take effect in a minute. Then,
navigate to **Logs** in Grafana Cloud and watch the logs coming.

<Frame>
  <img />
</Frame>

### Exporting metrics

To export metrics to Grafana Cloud, go to your account and get credentials for
Prometheus, the metrics service in Grafana Cloud:

<Frame>
  <img />
</Frame>

Then, configure the [`prometheus_remote_write`][vector-prometheus-rw] sink in
your [`vector.toml` configuration file][ref-monitoring-integrations-conf].

Example configuration:

```toml theme={"dark"}
[sinks.prometheus]
type = "prometheus_remote_write"
inputs = [
  "metrics"
]
endpoint = "https://prometheus-prod-24-prod-eu-west-2.grafana.net/api/prom/push"

[sinks.prometheus.auth]
strategy = "basic"
user = "1033221"
password = "eyJrIjoiYTg1OTQ2OGY4Yzg3MTQxODc5OTA4NDUxMGM4NTA2ZDQ3ZjliYWZjOCIsIm4iOiJwcnciLCJpZCI6ODc1NzE5fQ=="
```

Commit the configuration for Vector, it should take effect in a minute. Then,
navigate to **Explore** in Grafana Cloud, select metrics from the drop
down:

<Frame>
  <img />
</Frame>

Then, you can create visualizations and add them to a dashboard:

<Frame>
  <img />
</Frame>

[grafana]: https://grafana.com

[vector-loki]: https://vector.dev/docs/reference/configuration/sinks/loki/

[vector-prometheus-rw]: https://vector.dev/docs/reference/configuration/sinks/prometheus_remote_write/

[ref-monitoring-integrations]: /admin/monitoring/monitoring-integrations

[ref-monitoring-integrations-conf]: /admin/monitoring/monitoring-integrations#configuration


# Overview
Source: https://docs.cube.dev/admin/monitoring/monitoring-integrations/index

Export Cube Cloud logs and metrics to external monitoring tools like Datadog, Grafana Cloud, and New Relic.

Cube Cloud allows exporting logs and metrics to external monitoring tools so you
can leverage your existing monitoring stack and retain logs and metrics for the
long term.

<Note>
  Available as an add-on on the [Enterprise plan](https://cube.dev/pricing).
</Note>

<Warning>
  Monitoring integrations suspend their work when a deployment goes to [auto-suspension][ref-autosuspend].
</Warning>

Monitoring integrations are only available for [production environments][ref-prod-env].

Under the hood, Cube Cloud uses [Vector][vector], an open-source tool for
collecting and delivering monitoring data. It supports a [wide range of
destinations][vector-docs-sinks], also known as *sinks*.

<Frame>
  <img />
</Frame>

<iframe title="YouTube video" />

## Guides

Monitoring integrations work with various popular monitoring tools. Check the
following guides and configuration examples to get tool-specific instructions:

<CardGroup>
  <Card title="Amazon CloudWatch" href="/admin/monitoring/monitoring-integrations/cloudwatch">
    Export logs and metrics to Amazon CloudWatch.
  </Card>

  <Card title="Amazon S3" href="/admin/monitoring/monitoring-integrations/s3">
    Archive logs to an Amazon S3 bucket.
  </Card>

  <Card title="Datadog" href="/admin/monitoring/monitoring-integrations/datadog">
    Export logs and metrics to Datadog.
  </Card>

  <Card title="Google Cloud Storage" href="/admin/monitoring/monitoring-integrations/gcs">
    Archive logs to a Google Cloud Storage bucket.
  </Card>

  <Card title="Grafana Cloud" href="/admin/monitoring/monitoring-integrations/grafana-cloud">
    Export logs and metrics to Grafana Cloud.
  </Card>

  <Card title="New Relic" href="/admin/monitoring/monitoring-integrations/new-relic">
    Export logs and metrics to New Relic.
  </Card>
</CardGroup>

## Configuration

To enable monitoring integrations, navigate to **Settings → Monitoring
Integrations** and click **Enable Vector** to add a Vector agent to
your deployment.

<Frame>
  <img />
</Frame>

Under **Metrics export**, you will see credentials for the
`prometheus_exporter` sink, in case you'd like to setup [metrics
export][self-sinks-for-metrics].

Additionally, create a [`vector.toml` configuration file][vector-docs-config]
next to your `cube.js` file. This file is used to keep sinks configuration. You
have to commit this file to the main branch of your deployment for Vector
configuration to take effect.

### Environment variables

You can use environment variables prefixed with `CUBE_CLOUD_MONITORING_` to
reference configuration parameters securely in the `vector.toml` file.

Example configuration for exporting logs to
[Datadog][vector-docs-sinks-datadog]:

```toml theme={"dark"}
[sinks.datadog]
type = "datadog_logs"
default_api_key = "$CUBE_CLOUD_MONITORING_DATADOG_API_KEY"
```

### Inputs for logs

Sinks accept the `inputs` option that allows to specify which components of a
Cube Cloud deployment should export their logs:

| Input name          | Description                                              |
| ------------------- | -------------------------------------------------------- |
| `cubejs-server`     | Logs of API instances                                    |
| `refresh-scheduler` | Logs of the refresh worker                               |
| `warmup-job`        | Logs of the [pre-aggregation warm-up][ref-preagg-warmup] |
| `cubestore`         | Logs of Cube Store                                       |
| `query-history`     | [Query History export](#query-history-export)            |

Example configuration for exporting logs to
[Datadog][vector-docs-sinks-datadog]:

```toml theme={"dark"}
[sinks.datadog]
type = "datadog_logs"
inputs = [
  "cubejs-server",
  "refresh-scheduler",
  "warmup-job",
  "cubestore"
]
default_api_key = "da8850ce554b4f03ac50537612e48fb1"
compression = "gzip"
```

When exporting Cube Store logs using the `cubestore` input, you can filter logs
by providing an array of their severity levels via the `levels` option. If not
specified, only `error` and `info` logs will be exported.

| Level   | Exported by default? |
| ------- | -------------------- |
| `error` | ✅ Yes                |
| `info`  | ✅ Yes                |
| `debug` | ❌ No                 |
| `trace` | ❌ No                 |

<Info>
  If you'd like to adjust severity levels of logs from API instances and the
  refresh scheduler, use the [`CUBEJS_LOG_LEVEL`](/reference/configuration/environment-variables#cubejs_log_level) environment variable.
</Info>

### Fields in exported logs

Before a log record reaches a sink, the following fields are attached to it:

| Field             | Description                                                                                                                                                                                                                        |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deployment_id`   | Identifier of the [deployment][ref-deployments].                                                                                                                                                                                   |
| `deployment_name` | Name of the deployment.                                                                                                                                                                                                            |
| `hostname`        | Host name of the node that the record comes from.                                                                                                                                                                                  |
| `pod_name`        | Name of the pod that the record comes from.                                                                                                                                                                                        |
| `service`         | Name of the component that the record comes from, matching the input name: `cubejs-server`, `refresh-scheduler`, `warmup-job`, or `cubestore`. Records from the `query-history` input use `query-history` on `datadog_logs` sinks. |
| `level`           | Severity of the record, lower-cased: `error`, `warn`, `info`, or `debug`. Records with the `trace` severity are exported as `debug`, and records that carry no severity as `info`.                                                 |
| `status`          | Duplicate of `level`, for tools that expect the severity in a `status` field, e.g. Datadog.                                                                                                                                        |
| `origin`          | Always `cube_cloud`.                                                                                                                                                                                                               |

Records from the `query-history` input carry a different set of fields, see
[Query History export](#query-history-export).

#### Datadog attributes

Sinks of the `datadog_logs` type additionally get the two fields that Datadog
uses for attribution:

| Field      | Description                                                                                                |
| ---------- | ---------------------------------------------------------------------------------------------------------- |
| `ddsource` | Name of the pod that the record comes from, or `query-history` for records from the `query-history` input. |
| `ddtags`   | Comma-separated list of tags. By default, the deployment name and the host name.                           |

To send your own tags to Datadog, list them in the `ddtags` option of the sink.
They are appended to the default ones:

```toml theme={"dark"}
[sinks.datadog]
# type, inputs, default_api_key, etc.
ddtags = [
  "env:production",
  "team:analytics"
]
```

### Sinks for logs

You can use a [wide range of destinations][vector-docs-sinks] for logs,
including the following ones:

* [AWS Cloudwatch][vector-docs-sinks-cloudwatch]
* [AWS S3][vector-docs-sinks-s3], [Google Cloud Storage][vector-docs-sinks-gcs],
  and [Azure Blob Storage][vector-docs-sinks-azureblob]
* [Datadog][vector-docs-sinks-datadog]

Example configuration for exporting all logs, including all Cube Store logs to
[Azure Blob Storage][vector-docs-sinks-azureblob]:

```toml theme={"dark"}
[sinks.azure]
type = "azure_blob"
container_name = "my-logs"
connection_string = "DefaultEndpointsProtocol=https;AccountName=mylogstorage;AccountKey=storageaccountkeybase64encoded;EndpointSuffix=core.windows.net"
inputs = [
  "cubejs-server",
  "refresh-scheduler",
  "warmup-job",
  "cubestore"
]

[sinks.azure.cubestore]
levels = [
  "trace",
  "info",
  "debug",
  "error"
]
```

### Inputs for metrics

Metrics are exported using the `metrics` input. Metrics will have their respective
metric names and\_types: [`gauge`][vector-docs-metrics-gauge] or
[`counter`][vector-docs-metrics-counter].

All metrics of the `counter` type reset to zero at the midnight (UTC) and increment
during the next 24 hours.

You can filter metrics by providing an array of *input names* via the `list` option.

| Input name                  | Metric name, type                              | Description                                                                                                                         |
| --------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `cpu`                       | `cube_cpu_usage_ratio`, `gauge`                | CPU usage of a particular node in the deployment. Usually, a number in the 0—100 range. May exceed 100 if the node is under load    |
| `memory`                    | `cube_memory_usage_ratio`, `gauge`             | Memory usage of a particular node in the deployment. Usually, a number in the 0—100 range. May exceed 100 if the node is under load |
| `requests-count`            | `cube_requests_total`, `counter`               | Number of API requests to the deployment                                                                                            |
| `requests-success-count`    | `cube_requests_success_total`, `counter`       | Number of successful API requests to the deployment                                                                                 |
| `requests-errors-count`     | `cube_requests_errors_total`, `counter`        | Number of errorneous API requests to the deployment                                                                                 |
| `requests-duration`         | `cube_requests_duration_ms_total`, `counter`   | Total time taken to process API requests, milliseconds                                                                              |
| `requests-success-duration` | `cube_requests_duration_ms_success`, `counter` | Total time taken to process successful API requests, milliseconds                                                                   |
| `requests-errors-duration`  | `cube_requests_duration_ms_errors`, `counter`  | Total time taken to process errorneous API requests, milliseconds                                                                   |

You can further filter exported metrics by providing an array of `inputs`. It applies to
metics only.

Example configuration for exporting all metrics from `cubejs-server` to
[Prometheus][vector-docs-sinks-prometheus] using the `prometheus_remote_write`
sink:

```toml theme={"dark"}
[sinks.prometheus]
type = "prometheus_remote_write"
inputs = [
  "metrics"
]
endpoint = "https://prometheus.example.com:8087/api/v1/write"

[sinks.prometheus.auth]
# Strategy, credentials, etc.

[sinks.prometheus.metrics]
list = [
  "cpu",
  "memory",
  "requests-count",
  "requests-errors-count",
  "requests-success-count",
  "requests-duration"
]
inputs = [
  "cubejs-server"
]
```

### Labels on exported metrics

Metrics are exported with the following Prometheus labels:

| Label            | Metrics                                           | Description                                                                                                                                                                    |
| ---------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `pod_name`       | `cube_cpu_usage_ratio`, `cube_memory_usage_ratio` | Name of the pod that the measurement was taken on.                                                                                                                             |
| `deployment_id`  | `cube_requests_*`                                 | Identifier of the [deployment][ref-deployments].                                                                                                                               |
| `api_type`       | `cube_requests_*`                                 | Type of [data API][ref-apis] that served the requests (`rest`, `sql`, etc.), the same values as in [Query History][ref-query-history]. `unknown` if the API type is not known. |
| `request_source` | `cube_requests_*`                                 | Source of the requests: `ai-engineer` for requests coming from AI features, `other` for any other source, `unknown` if the requests carry no source.                           |

Request metrics are reported per `api_type` and `request_source` combination, so
you can break down request counts and latency by data API:

```text theme={"dark"}
cube_requests_total{deployment_id="12345",api_type="rest",request_source="unknown"} 42
cube_requests_total{deployment_id="12345",api_type="sql",request_source="ai-engineer"} 7
```

### Sinks for metrics

Metrics are exported in the Prometheus format which is compatible with the
following sinks:

* [`prometheus_exporter`][vector-docs-sinks-prometheus-exporter] (native to
  [Prometheus][prometheus], compatible with [Mimir][mimir])
* [`prometheus_remote_write`][vector-docs-sinks-prometheus] (compatible with
  [Grafana Cloud][grafana-cloud])

Example configuration for exporting all metrics from `cubejs-server` to
[Prometheus][vector-docs-sinks-prometheus-exporter] using the
`prometheus_exporter` sink:

```toml theme={"dark"}
[sinks.prometheus]
type = "prometheus_exporter"
inputs = [
  "metrics"
]

[sinks.prometheus.metrics]
list = [
  "cpu",
  "memory",
  "requests-count",
  "requests-errors-count",
  "requests-success-count",
  "requests-duration"
]
inputs = [
  "cubejs-server"
]
```

Navigate to **Settings → Monitoring Integrations** to take the
credentials `prometheus_exporter` under **Metrics export**:

<Frame>
  <img />
</Frame>

You can also customize the user name and password for `prometheus_exporter` by
setting `CUBE_CLOUD_MONITORING_METRICS_USER` and
`CUBE_CLOUD_MONITORING_METRICS_PASSWORD` environment variables, respectively.

## Query History export

With Query History export, you can bring [Query History][ref-query-history] data to an
external monitoring solution for further analysis, for example:

* Detect queries that do not hit pre-aggregations.
* Set up alerts for queries that exceed a certain duration.
* Attribute usage to specific users and implement chargebacks.

<Note>
  Query History export is part of the Monitoring Integrations add-on,
  available on the [Enterprise plan](https://cube.dev/pricing).
</Note>

<Warning>
  Query History export also requires the **Monitoring Integrations Tier** of your
  deployment to be set to **Medium (Up to 50 GB/mo)**. You can find it under
  **Settings → Monitoring Integrations**; deployments default to **X-Small (Up to 10
  GB/mo)**.

  On **X-Small** or **Small**, Query History export fails silently: no events reach
  any sink, including a `console` sink, and no error is logged. If the tier is not
  available in your deployment settings, ask your Cube contact or the [Cube support
  team][ref-support] to set it.
</Warning>

<iframe title="YouTube video" />

To configure Query History export, add the `query-history` input to the `inputs`
option of the sink configuration. Example configuration for exporting Query History data
to the standard output of the Vector agent:

```toml theme={"dark"}
[sinks.my_console]
type = "console"
inputs = [
  "query-history"
]
target = "stdout"
encoding = { codec = "json" }
```

Exported data includes the following fields:

| Field                      | Description                                                                       |
| -------------------------- | --------------------------------------------------------------------------------- |
| `trace_id`                 | Unique identifier of the API request.                                             |
| `account_name`             | Name of the Cube Cloud account.                                                   |
| `query_history_link`       | Link to the request in [Query History][ref-query-history].                        |
| `deployment_id`            | Identifier of the [deployment][ref-deployments].                                  |
| `environment_name`         | Name of the [environment][ref-environments], `NULL` for production.               |
| `api_type`                 | Type of [data API][ref-apis] used (`rest`, `sql`, etc.), `NULL` for errors.       |
| `api_query`                | Query executed by the API, represented as string.                                 |
| `security_context`         | [Security context][ref-security-context] of the request, represented as a string. |
| `status`                   | Status of the request: `success` or `error`.                                      |
| `error_message`            | Error message, if any.                                                            |
| `start_time_unix_ms`       | Start time of the execution, Unix timestamp in milliseconds.                      |
| `end_time_unix_ms`         | End time of the execution, Unix timestamp in milliseconds.                        |
| `api_response_duration_ms` | Duration of the execution in milliseconds.                                        |
| `cache_type`               | [Cache type][ref-cache-type]: `no_cache`, `pre_aggregations_in_cube_store`, etc.  |

Unlike other logs, Query History records don't carry the
[fields listed above](#fields-in-exported-logs), except for `origin`. On sinks of
the `datadog_logs` type, they also get `service` and `ddsource` set to
`query-history`, and `ddtags`.

<Note>
  See [this recipe][ref-query-history-export-recipe] for an example of analyzing data from
  Query History export.
</Note>

[ref-autosuspend]: /admin/deployment/auto-suspension#effects-on-experience

[self-sinks-for-metrics]: #configuration-sinks-for-metrics

[vector]: https://vector.dev/

[vector-docs-config]: https://vector.dev/docs/reference/configuration/

[vector-docs-sinks]: https://vector.dev/docs/reference/configuration/sinks/

[vector-docs-sinks-cloudwatch]: https://vector.dev/docs/reference/configuration/sinks/aws_cloudwatch_logs/

[vector-docs-sinks-s3]: https://vector.dev/docs/reference/configuration/sinks/aws_s3/

[vector-docs-sinks-azureblob]: https://vector.dev/docs/reference/configuration/sinks/azure_blob/

[vector-docs-sinks-gcs]: https://vector.dev/docs/reference/configuration/sinks/gcp_cloud_storage/

[vector-docs-sinks-datadog]: https://vector.dev/docs/reference/configuration/sinks/datadog_logs/

[vector-docs-sinks-prometheus]: https://vector.dev/docs/reference/configuration/sinks/prometheus_remote_write/

[vector-docs-sinks-prometheus-exporter]: https://vector.dev/docs/reference/configuration/sinks/prometheus_exporter/

[vector-docs-metrics-gauge]: https://vector.dev/docs/about/under-the-hood/architecture/data-model/metric/#gauge

[vector-docs-metrics-counter]: https://vector.dev/docs/about/under-the-hood/architecture/data-model/metric/#counter

[prometheus]: https://prometheus.io

[mimir]: https://grafana.com/oss/mimir/

[grafana-cloud]: https://grafana.com/products/cloud/

[ref-prod-env]: /admin/deployment/environments#production-environment

[ref-preagg-warmup]: /admin/deployment/warm-up#pre-aggregation-warm-up

[ref-query-history]: /admin/monitoring/query-history

[ref-deployments]: /admin/deployment

[ref-environments]: /admin/deployment/environments

[ref-apis]: /reference

[ref-security-context]: /docs/data-modeling/access-control/context

[ref-cache-type]: /docs/pre-aggregations#cache-type

[ref-query-history-export-recipe]: /admin/monitoring/query-history-export

[ref-support]: /admin/account-billing/support


# Integration with New Relic
Source: https://docs.cube.dev/admin/monitoring/monitoring-integrations/new-relic

Forward Cube Cloud logs and metrics to New Relic with Vector sinks targeting the logs and metrics APIs.

[New Relic](https://newrelic.com) is an all-in-one observability platform.
This guide demonstrates how to set up Cube Cloud to export logs and metrics
to New Relic.

## Configuration

First, enable [monitoring integrations][ref-monitoring-integrations] in Cube
Cloud.

### Exporting logs

To export logs to New Relic, configure the
[`new_relic`](https://vector.dev/docs/reference/configuration/sinks/new_relic/)
sink in your [`vector.toml` configuration file][ref-monitoring-integrations-conf].
Use the `logs` API endpoint.

Example configuration:

```toml theme={"dark"}
[sinks.new_relic_logs]
type = "new_relic"
api = "logs"
inputs = [
  "cubejs-server",
  "refresh-scheduler",
  "warmup-job",
  "cubestore"
]
region = "eu"
compression = "gzip"
account_id = "$CUBE_CLOUD_MONITORING_NEW_RELIC_ACCOUNT_ID"
license_key = "$CUBE_CLOUD_MONITORING_NEW_RELIC_LICENSE_KEY"
```

Commit the configuration for Vector, it should take effect in a minute. Then,
navigate to New Relic and watch the logs coming.

### Exporting metrics

To export metrics to New Relic, configure the
[`new_relic`](https://vector.dev/docs/reference/configuration/sinks/new_relic/)
sink in your [`vector.toml` configuration file][ref-monitoring-integrations-conf].
Use the `metrics` API endpoint.

Example configuration:

```toml theme={"dark"}
[sinks.new_relic_metrics]
type = "new_relic"
api = "metrics"
inputs = [
  "metrics"
]
region = "eu"
compression = "gzip"
account_id = "$CUBE_CLOUD_MONITORING_NEW_RELIC_ACCOUNT_ID"
license_key = "$CUBE_CLOUD_MONITORING_NEW_RELIC_LICENSE_KEY"
```

Commit the configuration for Vector, it should take effect in a minute. Then,
navigate to New Relic and watch the metrics coming.

[ref-monitoring-integrations]: /admin/monitoring/monitoring-integrations

[ref-monitoring-integrations-conf]: /admin/monitoring/monitoring-integrations#configuration


# Integration with Amazon S3
Source: https://docs.cube.dev/admin/monitoring/monitoring-integrations/s3

Amazon S3 is a popular object storage system. This guide demonstrates how to set up Cube Cloud to export logs to Amazon S3.

[Amazon S3](https://aws.amazon.com/s3/) is a popular object storage system.
This guide demonstrates how to set up Cube Cloud to export logs to Amazon S3.

## Configuration

First, enable [monitoring integrations][ref-monitoring-integrations] in Cube
Cloud.

### Exporting logs

To export logs to Amazon S3, start by creating an S3 bucket for Cube Cloud logs.

Then, configure the [`aws_s3`](https://vector.dev/docs/reference/configuration/sinks/aws_s3/)
sink in your [`vector.toml` configuration file][ref-monitoring-integrations-conf].

Example configuration:

```toml theme={"dark"}
[sinks.aws_s3]
type = "aws_s3"
inputs = [
  "cubejs-server",
  "refresh-scheduler",
  "warmup-job",
  "cubestore"
]
bucket = "your-s3-bucket-name"
region = "us-east-1"
compression = "gzip"

[sinks.aws_s3.auth]
access_key_id = "$CUBE_CLOUD_MONITORING_AWS_ACCESS_KEY_ID"
secret_access_key = "$CUBE_CLOUD_MONITORING_AWS_SECRET_ACCESS_KEY"

[sinks.aws_s3.encoding]
codec = "json"

[sinks.aws_s3.healthcheck]
enabled = false
```

Commit the configuration for Vector, it should take effect in a minute. Then,
navigate to your S3 bucket and watch the logs coming.

<Note>
  The `aws_s3` sink can also authenticate with the deployment's OIDC identity
  instead of an access key pair — the credentials apply to the whole Vector agent.
  See [Keyless authentication][ref-keyless-auth].
</Note>

## Troubleshooting

### Bucket region mismatch

You might see the following error message in Vector logs:

```text theme={"dark"}
The bucket you are attempting to access must be addressed using the specified
endpoint. Please send all future requests to this endpoint.
```

This often happens if the bucket on Amazon S3 is in a region that is different
from the one you’ve specified in the configuration for Vector.

[ref-monitoring-integrations]: /admin/monitoring/monitoring-integrations

[ref-monitoring-integrations-conf]: /admin/monitoring/monitoring-integrations#configuration

[ref-keyless-auth]: /admin/monitoring/monitoring-integrations/cloudwatch#keyless-authentication


# Performance Insights
Source: https://docs.cube.dev/admin/monitoring/performance

Use Performance Insights charts in Cube Cloud to interpret API load, queues, and resource behavior when tuning a deployment.

The **Performance** page in Cube Cloud displays charts that help
analyze the performance of your deployment and fine-tune its configuration.
It's recommended to review Performance Insights when the workload changes
or if you face any performance-related issues with your deployment.

<Note>
  Available on [Premium and above plans](https://cube.dev/pricing).
  You can also choose a [Query History tier](/admin/account-billing/pricing#query-history-tiers).
</Note>

## Charts

Charts provide insights into different aspects of your deployment.

### API instances

The **API instances** chart shows the number of API instances
that served queries to the deployment.

You can use this chart to **fine-tune the
[auto-scaling][ref-scalability-api] configuration of API instances**, e.g.,
increase the minimum and maximum number of API instances.

For example, the following chart shows a deployment with sane auto-scaling
limits that don't need adjusting. It looks like the deployment needs to
sustain just a few infrequent load bursts per day and auto-scaling to 3 API
instances does the job just fine:

<Frame>
  <img />
</Frame>

The next chart shows a deployment with auto-scaling limits that definitely
need an adjustment. It looks like the load is so high that most of the time
this deployment has to use at least 4-6 API instances. So, it would be wise
to increase the minimum auto-scaling limit to 6 API instances:

<Frame>
  <img />
</Frame>

When in doubt, consider using a higher minimum auto-scaling limit: when an
additional API instance starts, it needs some time to compile the data model
before it would be able to serve the requests. So, over-provisioning API
instances with a higher minimum auto-scaling limit would allow to decrease
the number of requests that had to wait for the [data model
compilation](#data-model-compilation).

Also, you can use this chart to **fine-tune the
[auto-suspension][ref-auto-sus] configuration**, e.g., by turning
auto-suspension off or increasing the auto-suspension threshold.
For example, the following chart shows a [Shared
deployment][ref-dev-instance] that is only accessed a few times
a day and automatically suspends after a short period of inactivity:

<Frame>
  <img />
</Frame>

The next chart shows a misconfigured [Dedicated
deployment][ref-prod-cluster] that serves the requests throughout the whole
day but was configured to auto-suspend with a tiny threshold:

<Frame>
  <img />
</Frame>

### Cache type

The **Requests by cache type** chart shows the number of API
requests that were fulfilled by specific [cache types][ref-cache-types],
e.g., pre-aggregations, in-memory cache, no cache, etc. For example, the
following chart shows a deployment that fulfills about 50% of requests by
using pre-aggregations:

<Frame>
  <img />
</Frame>

The **Avg. response time by cache type** shows the difference
in the response time for requests that hit pre-aggregations, in-memory cache,
or no cache (i.e., the upstream data source). The next chart shows that
pre-aggregations usually provide sub-second response times while queries to
the data source take much longer:

<Frame>
  <img />
</Frame>

You can use these charts to see if you'd like to have more queries that hit
the cache and have lower response time. In that case, **consider adding more
[pre-aggregations][ref-pre-aggregations] in Cube Store** or fine-tune the
existing ones, e.g., by **[using indexes][ref-indexes] to speed up
pre-aggregations with suboptimal query plans**.

### Data model compilation

The **Requests by data model compilation** chart shows the
number of API requests that had or had not to wait for the data model
compilation. For example, the following chart shows a deployment that
only has a tiny fraction of requests that require the data model to be
compiled:

<Frame>
  <img />
</Frame>

The **Wait time for data model compilation** chart
shows the total time requests had to wait for the data model compilation.
The next chart shows that at certain points of time requests had to wait
dozens of seconds while the data model was being compiled:

<Frame>
  <img />
</Frame>

You can use these charts to **fine-tune the [auto-suspension][ref-auto-sus]
configuration** (e.g., turn it off or increase the threshold so that API
instances suspend less frequently), **identify [multitenancy][ref-multitenancy]
misconfiguration** (e.g., suboptimal bucketing via
[`context_to_app_id`][ref-context-to-app-id]), or
**consider using a [Multi-cluster deployment][ref-multi-cluster]** to
distribute requests to different tenants over a number of Dedicated
deployments.

### Cube Store

The **Saturation for queries by Cube Store workers** chart
shows if Cube Store workers are overloaded with serving **queries**.
High saturation for queries prevents Cube Store workers from fulfilling
requests and results in wait time displayed at the **Wait time for
queries by Cube Store workers** chart.

For example, the following chart shows a deployment that uses 4 Cube Store
workers and almost never lets them come to saturation, resulting in no wait
time for queries:

<Frame>
  <img />
</Frame>

Similarly, the **Saturation for jobs by Cube Store workers**
and **Wait time for jobs by Cube Store workers** charts show if
Cube Store Workers are overloaded with serving **jobs**, i.e., building
pre-aggregations or performing internal tasks such as data compaction.

For example, the following chart shows a misconfigured deployment that uses
8 Cube Store workers and keeps them at full saturation during prolonged
intervals, resulting in huge wait time and, in case of jobs, delayed refresh
of pre-aggregations:

<Frame>
  <img />
</Frame>

The next chart shows that oversaturated Cube Store workers might yield
hours of wait time for queries and jobs:

<Frame>
  <img />
</Frame>

You can use these charts to **fine-tune the [number of Cube Store
workers][ref-scalability-cube-store]** used by your deployment, e.g.,
increase it until you see that there's no saturation and no wait time
for queries and jobs.

[ref-scalability-api]: /admin/deployment/scalability#auto-scaling-of-api-instances

[ref-scalability-cube-store]: /admin/deployment/scalability#sizing-cube-store-workers

[ref-auto-sus]: /admin/deployment/auto-suspension

[ref-dev-instance]: /admin/deployment/deployment-types#shared

[ref-prod-cluster]: /admin/deployment/deployment-types#dedicated

[ref-multi-cluster]: /admin/deployment/deployment-types#multi-cluster

[ref-pre-aggregations]: /docs/pre-aggregations/using-pre-aggregations

[ref-multitenancy]: /embedding/multitenancy

[ref-context-to-app-id]: /reference/configuration/config#context_to_app_id

[ref-cache-types]: /docs/pre-aggregations#cache-type

[ref-indexes]: /docs/pre-aggregations/using-pre-aggregations#using-indexes


# Pre-Aggregations
Source: https://docs.cube.dev/admin/monitoring/pre-aggregations

Monitor pre-aggregation builds, partitions, and refresh history from the Cube Cloud Pre-Aggregations console.

The Pre-Aggregations page in Cube Cloud allows you to inspect all
[pre-aggregations][ref-caching-gs-preaggs] in your deployment at a glance. You
can see which pre-aggregations are accelerating queries, if they are [being
refreshed][ref-caching-using-preaggs-refresh], along with the last 24 hours of
build history.

<Frame>
  <img />
</Frame>

## Exploring pre-aggregations

You can switch between [pre-aggregations](#pre-aggregations) and
[build history](#build-history) by switching between the 
​**Pre-Aggregations** and **Build History** tabs.

## Pre-aggregations

The **Pre-Aggregations** tab shows a list of all configured
[pre-aggregations][ref-caching-gs-preaggs] for the deployment, and is useful for
quickly checking details such as when the last build occurred, how long the
build took to complete, the total size of the pre-aggregated data, and how many
partitions the data is split across. To see more information about a specific
pre-aggregation, click on it.

### Partitions

The **Partitions** tab shows all partitions (as specified by
[`partitionGranularity`][ref-model-ref-preaggs-partition-granularity]) of the
pre-aggregation. In the example below, the pre-aggregation has a single
partition:

<Frame>
  <img />
</Frame>

Pre-aggregations with multiple partitions show a list of all partitions, which
is helpful for checking pre-aggregation partition build times and sizes:

<Frame>
  <img />
</Frame>

Ideally partitions should be of a similar size and build time. If a partition is
taking significantly longer to build than others, it may be worth investigating
why.

If the pre-aggregation requires rebuilding (usually due to the underlying data
changing in a significant way), clicking **Build All** rebuilds **all**
partitions of the pre-aggregation:

<Frame>
  <img />
</Frame>

You can also choose to rebuild **specific** partitions by selecting them and
then clicking the **Build Selected** button:

<Frame>
  <img />
</Frame>

### Definition

The **Definition** tab shows how the [pre-aggregation is defined in the
data model][ref-model-ref-preaggs] without having to switch to the **Data
Model** page:

<Frame>
  <img />
</Frame>

### Preview

To see a sample of the data contained in the pre-aggregation, click the 
​**Preview** tab:

<Frame>
  <img />
</Frame>

This can be used to verify that the data within the pre-aggregation is being
built correctly.

### Used By

The **Used By** tab shows recent queries that used this pre-aggregation
for acceleration:

<Frame>
  <img />
</Frame>

This is especially useful for checking that the pre-aggregation is being used as
expected by queries sent to the deployment.

### Indexes

[Indexes][ref-model-ref-preaggs-index] significantly improve the performance of
configured pre-aggregations. The **Indexes** tab displays any configured
indexes for this pre-aggregation:

<Frame>
  <img />
</Frame>

## Build History

The **Build History** tab shows the last 24 hours of build history for
all pre-aggregations in the deployment. From here, you can see if a
pre-aggregation build succeeded (or failed), how the build was triggered, when
the build started, and how long it took to complete.

<Frame>
  <img />
</Frame>

To see more information about a specific build, click on it:

<Frame>
  <img />
</Frame>

[ref-caching-gs-preaggs]: /docs/pre-aggregations/getting-started-pre-aggregations

[ref-caching-using-preaggs-refresh]: /docs/pre-aggregations/using-pre-aggregations#refresh-strategy

[ref-model-ref-preaggs]: /reference/data-modeling/pre-aggregations

[ref-model-ref-preaggs-index]: /reference/data-modeling/pre-aggregations#indexes

[ref-model-ref-preaggs-partition-granularity]: /reference/data-modeling/pre-aggregations#partition_granularity


# Query History
Source: https://docs.cube.dev/admin/monitoring/query-history

The Query History feature in Cube Cloud is a one-stop shop for all performance and diagnostic information about queries issued for a deployment.

It provides a real-time and historic view of requests to [data APIs][ref-apis] of your
Cube Cloud deployment, so you can check whether queries were accelerated with
[pre-aggregations][ref-caching-gs-preaggs], how long they took to execute, and if they
failed.

<Note>
  You can choose a [Query History tier](/admin/account-billing/pricing#query-history-tiers)
  to fit your retention and throughput needs.
</Note>

You can set the [time range](#setting-the-time-range), [explore queries](#exploring-queries)
and filter them, drill down on specific queries to [see more details](#inspecting-api-queries).

You can also use [Query History export][ref-query-history-export] to bring Query History
data to an external monitoring solution for further analysis.

<br />

<video>
  <source type="video/mp4" />
</video>

## Setting the time range

By default, Cube Cloud shows you a live feed of queries made to the API and
connected [data sources][ref-conf-db].

You can navigate throughout the query history by using the date picker in the
top right corner of the page and selecting a time period:

<Frame>
  <img />
</Frame>

To go back to live mode, click **▶**:

<Frame>
  <img />
</Frame>

## Exploring queries

You can switch between [queries made to the API](#inspecting-api-queries) and
[queries made to connected data sources](#inspecting-database-queries) by
switching between the **API** and **Database** tabs.

<Frame>
  <img />
</Frame>

### All queries and top queries

Clicking **All Queries** will show all queries in order of recency,
while **Top Queries** will show the queries with the largest total duration (hits \* avg duration) in the selected time frame. Both results are limited to 100 unique queries.

<Frame>
  <img />
</Frame>

### Filtering

You can use filters to find queries by various criteria:

* duration,
* cache status,
* whether the query was accelerated with pre-aggregations,
* whether the query yielded an error,
* API type.

<Frame>
  <img />
</Frame>

## Inspecting API queries

In the table, all queries are shown in their collapsed view by default.
To see an expanded view of a query, click on the **❯** button
to the left of any query.

<Frame>
  <img />
</Frame>

Check the columns to see the details:

* **Query** column shows a representation of a query, similar to the
  REST (JSON) API [query format][ref-query-format]. In case of the SQL API, if the
  query is not coercible to a REST (JSON) API query, raw SQL is shown "as is."
* **API** column shows the API type that was used to run the query:
  REST (JSON) API via HTTP transport, REST (JSON) API via WebSockets, GraphQL API, or SQL API.
* **Duration** column shows how long the query took.
* Bolt icon indicates the [cache type][ref-cache-types] that was used to
  fulfill the query.
* **Time** column shows the point in time the query was run at.

To drill down on a specific query, click it to see more information.

### Query

The **Query** tab shows the raw JSON query sent to the Cube Cloud
deployment.

<Frame>
  <img />
</Frame>

### Errors

If the query failed, the **Errors** tab will show you the error message
and stacktrace:

<Frame>
  <img />
</Frame>

### SQL

The **SQL** tab shows the generated SQL query sent by Cube to either your
data source **or** Cube Store if the query was accelerated with a
pre-aggregation:

<Frame>
  <img />
</Frame>

You can also run the SQL query directly against your data source using the [SQL
Runner][ref-workspace-sqlrunner] by clicking **▶️**:

<Frame>
  <img />
</Frame>

### Pre-aggregations

The **Pre-Aggregations** tab shows the
[pre-aggregation][ref-caching-gs-preaggs] used to accelerate this query, if one
was used:

<Frame>
  <img />
</Frame>

If no pre-aggregations were used for this query, you should see the following
screen:

<Frame>
  <img />
</Frame>

Clicking **Accelerate** allows you to add a pre-aggregation to
accelerate similar queries in the future.

### Security context

The **Security Context** tab shows the [security context][ref-security-context]
that was used to process this query:

<Frame>
  <img />
</Frame>

This is helpful in case [multitenancy][ref-multitenancy] is configured.

### Queue graph

The **Queue Graph** tab details any activity in the query queue while
processing the query. This may include other queries that were being processed
or were waiting in the queue by Cube Cloud at the same time as this query:

<Frame>
  <img />
</Frame>

A large number of queries in the queue may indicate that your deployment is
under-provisioned, and you may want to consider scaling up your deployment.

### Flame graph

The **Flame Graph** tab shows a [flame graph][datadog-kb-flamegraph] of a
query's execution time across resources in the Cube Cloud deployment. This is
extremely useful for diagnosing where time is being spent in a query, and can
help identify bottlenecks in your Cube deployment or data source.

<Frame>
  <img />
</Frame>

## Inspecting database queries

### Query

For Database requests, the **Query** tab shows the SQL query compiled by
Cube that is executed on the data source:

<Frame>
  <img />
</Frame>

This can be useful for debugging queries that are failing or taking a long time,
as you can copy the query and run it directly against your data source.

### Errors

If the query failed, the **Errors** tab will show you the error message
and stacktrace:

<Frame>
  <img />
</Frame>

Errors here generally indicate a problem with querying the data source. The
generated SQL query can be copied from the **[Query](#query-2)** tab and
run directly against your data source to debug the issue.

### Events

The **Events** tab shows all data source-related events that occurred
while the query is in the query execution queue:

<Frame>
  <img />
</Frame>

[datadog-kb-flamegraph]: https://www.datadoghq.com/knowledge-center/distributed-tracing/flame-graph/

[ref-caching-gs-preaggs]: /docs/pre-aggregations/getting-started-pre-aggregations

[ref-conf-db]: /admin/connect-to-data/data-sources

[ref-workspace-sqlrunner]: /docs/data-modeling/sql-runner

[ref-query-format]: /reference/core-data-apis/rest-api/query-format

[ref-cache-types]: /docs/pre-aggregations#cache-type

[ref-security-context]: /docs/data-modeling/access-control/context

[ref-multitenancy]: /embedding/multitenancy

[ref-apis]: /reference

[ref-query-history-export]: /admin/monitoring/monitoring-integrations#query-history-export


# Analyzing data from Query History export
Source: https://docs.cube.dev/admin/monitoring/query-history-export

Walk through exporting Query History to Amazon S3 with Vector and analyzing the files with DuckDB inside Cube.

You can use [Query History export][ref-query-history-export] to bring [Query
History][ref-query-history] data to an external monitoring solution for further
analysis.

In this recipe, we will show you how to export Query History data to Amazon S3, and then
analyze it using Cube by reading the data from S3 using DuckDB.

<Warning>
  Before you start, check that the **Monitoring Integrations Tier** of your deployment is
  set to **Medium (Up to 50 GB/mo)**. On a lower tier, [Query History
  export][ref-query-history-export] fails silently — no events reach any sink and no error
  is logged.
</Warning>

<iframe title="YouTube video" />

## Configuration

[Vector configuration][ref-vector-configuration] for exporting Query History to Amazon S3
and also outputting it to the console of the Vector agent in your Cube Cloud deployment.

In the example below, we are using the `aws_s3` sink to export the `cube-query-history-export-demo`
bucket in Amazon S3, but you can use any other storage solution that Vector supports.

```toml theme={"dark"}
[sinks.aws_s3]
type = "aws_s3"
inputs = [
  "query-history"
]
bucket = "cube-query-history-export-demo"
region = "us-east-2"
compression = "gzip"
 
[sinks.aws_s3.auth]
access_key_id = "$CUBE_CLOUD_MONITORING_AWS_ACCESS_KEY_ID"
secret_access_key = "$CUBE_CLOUD_MONITORING_AWS_SECRET_ACCESS_KEY"
 
[sinks.aws_s3.encoding]
codec = "json"
 
[sinks.aws_s3.healthcheck]
enabled = false


[sinks.my_console]
type = "console"
inputs = [
  "query-history"
]
target = "stdout"
encoding = { codec = "json" }
```

You'd also need to set the following environment variables in the **Settings → Environment
variables** page of your Cube Cloud deployment:

```bash theme={"dark"}
CUBE_CLOUD_MONITORING_AWS_ACCESS_KEY_ID=your-access-key-id
CUBE_CLOUD_MONITORING_AWS_SECRET_ACCESS_KEY=your-secret-access-key

CUBEJS_DB_DUCKDB_S3_ACCESS_KEY_ID=your-access-key-id
CUBEJS_DB_DUCKDB_S3_SECRET_ACCESS_KEY=your-secret-access-key
CUBEJS_DB_DUCKDB_S3_REGION=us-east-2
```

<Note>
  The `aws_s3` sink can also authenticate with the deployment's OIDC identity
  instead of an access key pair — the credentials apply to the whole Vector agent.
  See [Keyless authentication][ref-keyless-auth].

  This replaces the `CUBE_CLOUD_MONITORING_AWS_*` pair above, which is Vector's
  **write** path only. The `CUBEJS_DB_DUCKDB_S3_*` variables are separate — they
  belong to the DuckDB data source that reads the exported files back in
  [Data modeling](#data-modeling), and are still required.
</Note>

## Data modeling

Example data model for analyzing data from Query History export that is brought to a
bucket in Amazon S3. The data is accessed directly from S3 using DuckDB.

With this data model, you can run queries that aggregate data by dimensions such as
`status`, `environment_name`, `api_type`, etc. and also calculate metrics like
`count`, `total_duration`, or `avg_duration`:

```yaml theme={"dark"}
cubes:
  - name: requests
    sql: |
      SELECT
        *,
        api_response_duration_ms / 1000 AS api_response_duration,
        EPOCH_MS(start_time_unix_ms) AS start_time,
        EPOCH_MS(end_time_unix_ms) AS end_time
      FROM read_json_auto('s3://cube-query-history-export-demo/**/*.log.gz')
    
    dimensions:
      - name: trace_id
        sql: trace_id
        type: string
        primary_key: true

      - name: deployment_id
        sql: deployment_id
        type: number

      - name: environment_name
        sql: environment_name
        type: string

      - name: api_type
        sql: api_type
        type: string

      - name: api_query
        sql: api_query
        type: string

      - name: security_context
        sql: security_context
        type: string

      - name: cache_type
        sql: cache_type
        type: string

      - name: start_time
        sql: start_time
        type: time

      - name: end_time
        sql: end_time
        type: time

      - name: duration
        sql: api_response_duration
        type: number

      - name: status
        sql: status
        type: string

      - name: error_message
        sql: error_message
        type: string

      - name: user_name
        sql: "SUBSTRING(security_context::JSON ->> 'user', 3, LENGTH(security_context::JSON ->> 'user') - 4)"
        type: string

    segments:
      - name: production_environment
        sql: "{environment_name} IS NULL"

      - name: errors
        sql: "{status} <> 'success'"

    measures:
      - name: count
        type: count

      - name: count_non_production
        description: |
          Counts all non-production environments.
          See for details: https://cube.dev/docs/product/administration/deployment/environments
        type: count
        filters:
          - sql: "{environment_name} IS NOT NULL"

      - name: total_duration
        type: sum
        sql: "{duration}"
        
      - name: avg_duration
        type: number
        sql: "{total_duration} / {count}"

      - name: median_duration
        type: number
        sql: "MEDIAN({duration})"

      - name: min_duration
        type: min
        sql: "{duration}"

      - name: max_duration
        type: max
        sql: "{duration}"
        
    pre_aggregations:
      - name: count_and_durations_by_status_and_start_date
        measures:
          - count
          - min_duration
          - max_duration
          - total_duration
        dimensions:
          - status
        time_dimension: start_time
        granularity: hour
        refresh_key:
          sql: SELECT MAX(end_time) FROM {requests.sql()}
          every: 10 minutes

```

## Result

Example query in Playground:

<Frame>
  <img />
</Frame>

[ref-query-history-export]: /admin/monitoring/monitoring-integrations#query-history-export

[ref-query-history]: /admin/monitoring/query-history

[ref-vector-configuration]: /admin/monitoring/monitoring-integrations#configuration

[ref-keyless-auth]: /admin/monitoring/monitoring-integrations/cloudwatch#keyless-authentication


# Usage Analytics
Source: https://docs.cube.dev/admin/monitoring/usage-analytics

Use built-in Usage Analytics dashboards to understand how your deployments are used — query activity, performance, user adoption, and AI usage.

The **Usage Analytics** page provides a set of pre-built dashboards that show
how your deployments are used: how many queries run and how fast they return,
how effectively the cache serves them, how actively users engage with the
platform, and how much AI activity and token consumption your account generates.

Usage Analytics is itself a Cube application: your account's usage telemetry
is modeled as a curated set of views, and the pre-built dashboards are regular
Cube dashboards on top of them. You can use the same views to
[build your own dashboards](#build-your-own-dashboards).

<Note>
  Available on [Premium and above plans](https://cube.dev/pricing).
  Usage Analytics is only available to account administrators.
</Note>

## Pre-built dashboards

Each dashboard answers a different question about your account's usage.

<Frame>
  <img alt="Usage Analytics overview dashboard" />

  <img alt="Usage Analytics overview dashboard" />
</Frame>

| Dashboard                        | Description                                                                                                                    |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Overview**                     | High-level health and adoption at a glance: requests, error rate, cache hit rate, response time, AI activity, and top tenants. |
| **Query Activity & Performance** | Query volume by API type, latency percentiles, execution-stage breakdown, slowest queries, errors, and activity heatmap.       |
| **Users & Adoption**             | Active users over time, new vs. returning users, engagement frequency, seat utilization, and dormant accounts.                 |
| **AI & Token Tracking**          | AI messages and conversations by surface, AI adoption, token consumption with estimated cost, and latency.                     |

## Build your own dashboards

Usage Analytics runs the full Cube application in
[Creator Mode](/embedding/iframe/creator-mode), embedded inside Cube. Beyond
the pre-built dashboards, you get the complete authoring experience: explore
the usage data, create workbooks, and assemble your own dashboards from it.

Your dashboards query the same three curated views that power the pre-built
ones. Anything you build stays private unless you share it.

| View                 | What it contains                                                                                                                         |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **API Requests**     | Every query hitting your deployments' data APIs, with timing, caching, errors, and the user, tenant, and deployment behind each request. |
| **AI Usage**         | AI messages grouped into conversations and sessions, with context, token consumption, estimated cost, and latency.                       |
| **Users & Adoption** | Users and their engagement: sign-ups, active users, activity frequency, seat utilization, and dormant accounts.                          |

The API Requests view includes the security context behind each request, so
embedded analytics customers can slice usage by tenant — for example, to find
the heaviest tenants or compare per-tenant latency and cache efficiency.

## Query programmatically

Beyond the embedded dashboards, account administrators can mint a short-lived
Cube API token to query the same usage and billing data directly — from the
[REST API](https://cube.dev/docs/product/apis-integrations/rest-api), a BI
tool, or a script — instead of only viewing it in-app.

```bash theme={"dark"}
curl -X POST https://your-account.cubecloud.dev/api/v1/usage-analytics/token \
  -H "Authorization: Bearer <api-token>"
```

The response includes a `token`, the `apiUrl` to send it to, and an
`expiresAt` timestamp:

```json theme={"dark"}
{
  "token": "eyJhbGc...",
  "apiUrl": "https://usage-analytics.cubecloud.dev/cubejs-api/v1",
  "deploymentId": 331,
  "expiresAt": "2026-09-03T13:00:00.000Z"
}
```

The token is scoped to your account, the same way the embedded page is, so
queries only ever see your own data. It expires after **1 hour** — issue a
fresh one for each session or scheduled refresh rather than caching it.
Requires an API key belonging to an account administrator, and Usage
Analytics enabled for the account.

## Data freshness and isolation

Usage Analytics data is available on a slight delay compared to live activity.
For real-time inspection of individual queries, use
[Query History](/admin/monitoring/query-history).

Usage Analytics content is isolated from your own deployments' content: the
views and dashboards described above don't appear in your data model, and your
end users can't access them.


# Google Workspace
Source: https://docs.cube.dev/admin/sso/google-workspace

Walks Google Workspace super admins through SAML single sign-on between Google Admin and Cube Cloud.

Cube Cloud supports authenticating users through Google Workspace, which is
useful when you want your users to access Cube Cloud using single sign on. This
guide will walk you through the steps of configuring SAML authentication in Cube
Cloud with Google Workspace. You **must** be a super administrator in your
Google Workspace to access the Admin Console and create a SAML integration.

<Note>
  Available on [Enterprise plan](https://cube.dev/pricing).
</Note>

## Enable SAML in Cube Cloud

First, we'll enable SAML authentication in Cube Cloud. To do this, log in to
Cube Cloud and

1. Navigate to **Admin → Settings**.
2. On the **Authentication & SSO** tab, enable **SAML**.
3. For a new integration, replace any prefilled **Audience (SP Entity ID)**
   value with the **Single Sign-On URL** shown directly above it.

Take note of the **Single Sign-On URL** and **Audience (SP Entity ID)**
values. You will need them when you configure the SAML integration in Google
Workspace.

## Create a SAML Integration in Google Workspace

Next, we'll create a [SAML app integration for Cube Cloud in Google
Workspace][google-docs-create-saml-app].

1. Log in to [admin.google.com](https://admin.google.com) as an administrator,
   then navigate to

   **Apps → Web and Mobile Apps** from the left sidebar.

2. Click **Add App**, then click **Add custom SAML app**:

<Frame>
  <img />
</Frame>

3. Enter a name for your application and click **Next**. You can
   optionally add a description and upload a logo for the application, but this
   is not required. Click **Continue** to go to the next screen.

<Frame>
  <img />
</Frame>

4. Take note of the **SSO URL**, **Entity ID** and
   **Certificate** values here, as we will need them when we finalize the
   SAML integration in Cube Cloud. Click **Continue** to go to the next screen.

<Frame>
  <img />
</Frame>

5. Enter the following values for the **Service provider details**
   section and click **Continue**.

| Name      | Description                                                |
| --------- | ---------------------------------------------------------- |
| ACS URL   | Use the **Single Sign-On URL** value from Cube Cloud.      |
| Entity ID | Use the **Audience (SP Entity ID)** value from Cube Cloud. |

6. On the final screen, click **Finish**.

7. From the app details page, click **User access** and ensure the app is
   **ON for everyone**:

<Frame>
  <img />
</Frame>

## Complete SAML configuration in Cube Cloud

In this step, we'll finalise the configuration by entering the values from our
SAML integration in Google into Cube Cloud.

1. Return to **Admin → Settings → Authentication & SSO → SAML**.
2. Confirm that **Audience (SP Entity ID)** still matches the **Single
   Sign-On URL** exactly.
3. Enter the following values in the **SAML Settings** section:

| Name               | Description                                          |
| ------------------ | ---------------------------------------------------- |
| Entity ID / Issuer | Use the **Entity ID** value from Google Workspace.   |
| SSO (Sign on) URL  | Use the **SSO URL** value from Google Workspace.     |
| Certificate        | Use the **Certificate** value from Google Workspace. |

4. Enable **Auto-provision new users** if you want users to be automatically
   created in Cube on their first login via this SAML provider. New users
   are assigned the Viewer role by default — see
   [Default role for new users](#default-role-for-new-users) to choose a
   different role. Enable this if you are not using SCIM provisioning.

5. Click **Apply** to save the changes.

<Note>
  Existing working Google Workspace integrations with a blank Audience do not
  need to change immediately. A blank Audience disables audience validation. To
  enable validation, update the Google **Entity ID** and Cube **Audience (SP
  Entity ID)** together, keep another authentication method enabled, and test
  SAML sign-in before you disable the fallback method.
</Note>

## Default role for new users

By default, users auto-provisioned via SAML receive the **Viewer** role.
To assign a different role, expand the **Advanced** section of the SAML
configuration form and pick from **Default role for new users**:

* **Developer**, **Explorer**, or **Viewer** — Cube Cloud's [default
  roles][ref-roles].
* Any [custom role][ref-custom-roles] defined in your account, listed
  below the divider.

The selected role applies **only when a user is first created**. Existing
users are not modified on subsequent SSO logins. It is applied **in
addition to** any roles your identity provider sends via the role
attribute (subject to the `rolesMap`).

<Info>
  Admin status is not assignable through this picker — Admin is controlled
  separately. To grant admin permissions, update the user's role manually
  under [Admin → Users][ref-manage-users].
</Info>

<Warning>
  If the selected role is later renamed or deleted, new users will fall
  back to the **Viewer** role until you pick a valid role here. The Viewer
  fallback applies whenever the configured default cannot be resolved —
  whether that's because no default is set or the configured role no longer
  exists.
</Warning>

## Test SAML authentication

To start using SAML authentication, use the
[single sign-on URL provided by Cube Cloud](#enable-saml-in-cube-cloud)
(typically `<YOUR_CUBE_CLOUD_URL>/sso/saml`) to log in to Cube Cloud.

[google-docs-create-saml-app]: https://support.google.com/a/answer/6087519?hl=en

[ref-roles]: /admin/users-and-permissions/roles-and-permissions

[ref-custom-roles]: /admin/users-and-permissions/custom-roles

[ref-manage-users]: /admin/users-and-permissions/manage-users


# Overview
Source: https://docs.cube.dev/admin/sso/index

Configure how your team accesses Cube Cloud using passwords, social logins, or SAML-based single sign-on.

Authentication & SSO

As an account administrator, you can manage how your team and users access Cube Cloud.

You can authenticate using email and password, a GitHub account, or a Google account.
Cube Cloud also provides single sign-on (SSO) via identity providers supporting
[SAML](#saml), e.g., Okta, Google Workspace, Azure AD, etc.

<Info>
  [SAML](#saml) is available on [Enterprise plan](https://cube.dev/pricing).
</Info>

## Configuration

To manage authentication settings, navigate to **Admin → Settings**
of your Cube Cloud account, and switch to the **Authentication & SSO** tab.

Use the toggles in **Password**, **Google**, and **GitHub**
sections to enable or disable these authentication options.

### SAML

Use the toggle in the **SAML** section to enable or disable the authentication
via an identity provider supporting the [SAML protocol][wiki-saml].
Once it's enabled, you'll see the **SAML Settings** section directly below.

Check the following guides to get tool-specific instructions on configuration:

<CardGroup>
  <Card title="Google Workspace" href="/admin/sso/google-workspace" />

  <Card title="Microsoft Entra ID" href="/admin/sso/microsoft-entra-id" />

  <Card title="Okta" href="/admin/sso/okta" />
</CardGroup>

#### Match SAML service provider identifiers

Cube shows two service provider values in the SAML settings:

| Cube setting                | Identity provider setting            |
| --------------------------- | ------------------------------------ |
| **Single Sign-On URL**      | ACS URL or Reply URL                 |
| **Audience (SP Entity ID)** | Audience, Entity ID, or SP Entity ID |

The **Audience (SP Entity ID)** value validates the audience in SAML responses.
It must exactly match the value configured in your identity provider. Leaving
the field blank disables audience validation and is supported only for
compatibility with existing configurations.

Some identity providers, including Amazon Federate, use one service provider
identifier for both the AuthnRequest issuer and the response audience. For
these providers, set **Audience (SP Entity ID)** in Cube to the **Single
Sign-On URL**, then use that same value as the identity provider's Entity ID
or Audience.

<Note>
  Existing working SAML integrations do not need to change their Audience. When
  you change an existing configuration, keep another authentication method
  enabled until you have tested SAML sign-in in a separate browser session.
</Note>

[wiki-saml]: https://en.wikipedia.org/wiki/SAML_2.0

[ref-apis]: /reference

[ref-dap]: /docs/data-modeling/data-access-policies

[ref-security-context]: /docs/data-modeling/access-control/context

[ref-auth-integration]: /docs/data-modeling/access-control#authentication-integration


# SAML authentication with Microsoft Entra ID
Source: https://docs.cube.dev/admin/sso/microsoft-entra-id/saml

Step-by-step guide for configuring Microsoft Entra ID as a SAML identity provider for Cube sign-in.

With SAML (Security Assertion Markup Language) enabled, you can authenticate
users in Cube through Microsoft Entra ID (formerly Azure Active Directory),
allowing your team to access Cube using single sign-on.

<Note>
  Available on [Enterprise plan](https://cube.dev/pricing).
</Note>

## Prerequisites

Before proceeding, ensure you have the following:

* Admin permissions in Cube.
* Sufficient permissions in Microsoft Entra to create and configure
  Enterprise Applications.

## Enable SAML in Cube

First, enable SAML authentication in Cube:

1. In Cube, navigate to **Admin → Settings**.
2. On the **Authentication & SSO** tab, enable the **SAML**
   toggle.
3. For a new integration, set **Audience (SP Entity ID)** to the
   **Single Sign-On URL** shown directly above it.
4. Take note of the **Single Sign-On URL** and **Audience (SP Entity ID)**
   values — you'll need them when configuring the Enterprise Application in
   Entra.

<Note>
  Existing working Entra integrations with a different Audience do not need to
  change. Keep the existing audience claim override unless you intentionally
  update both sides of the integration.
</Note>

## Create an Enterprise Application in Entra

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com).
2. Go to [Enterprise Applications](https://portal.azure.com/#view/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/~/AppAppsPreview)
   and click **New application**.
3. Select **Create your own application**.
4. Give it a name and choose a **non-gallery application**, then click
   **Create**.

## Configure SAML in Entra

1. In your new Enterprise Application, go to the **Single sign-on**
   section and select **SAML**.
2. In the **Basic SAML Configuration** section, enter the following:
   * **Entity ID** — Use the **Single Sign-On URL** value from Cube.
   * **Reply URL** — Use the **Single Sign-On URL** value from Cube.
3. If the **Audience (SP Entity ID)** value from Cube differs from the
   **Entity ID** configured in the previous step, go to **Attributes & Claims
   → Edit → Advanced settings** and set the audience claim override to the
   Cube value. If the values match, no audience claim override is required.
4. Go to **SAML Certificates → Edit** and select **Sign SAML
   response and assertion** for the **Signing Option**.
5. Download the **Federation Metadata XML** file — you'll need it
   when completing the Cube configuration.

## Configure attribute mappings

Before returning to Cube, configure the SAML claims Entra sends during
login. Cube uses these claims to identify the user and map optional
attributes such as display name.

Create explicit SAML claims in Entra with the names Cube uses by default.

1. In your Entra Enterprise Application, go to **Single sign-on →
   Attributes & Claims**.
2. Add the following claims. Leave **Namespace** blank for each claim:
   * **Email** — Set **Name** to `email` and **Source attribute** to
     `user.userprincipalname` or `user.mail`.
   * **Display name** — Set **Name** to `name` and **Source attribute** to
     `user.displayname`.

If you plan to map Cube roles based on Entra group membership (see
[Map roles by group](#map-roles-by-group) below), also add a group claim:

1. Still in **Attributes & Claims**, click **Add a group claim**.
2. Choose which groups to include (e.g. **Security groups** or **Groups
   assigned to the application**) and pick a **Source attribute** for the
   group name. For most setups, select **sAMAccountName** or
   **Cloud-only group display names** so the assertion carries
   human-readable group names that match the **IdP group name** values
   you'll configure in Cube Cloud.
3. Save the claim.

   Cube reads Entra's canonical groups claim URL
   (`http://schemas.microsoft.com/ws/2008/06/identity/claims/groups`)
   automatically, so no further attribute renaming is required on the
   Entra side.

## Complete configuration in Cube

Return to the SAML configuration page in Cube and provide the identity
provider details. You can do this in one of two ways:

**Option A: Upload metadata file**

1. In the **Import IdP Metadata** section, click **Upload
   Metadata File**.
2. Select the **Federation Metadata XML** file you downloaded from Entra.
   This will automatically populate the **Entity ID / Issuer**,
   **SSO (Sign on) URL**, and **Certificate** fields.

**Option B: Enter details manually**

If you prefer to configure the fields manually, enter the following
values from the Entra **Single sign-on** page:

* **Entity ID / Issuer** — Use the **Microsoft Entra Identifier**
  value.
* **SSO (Sign on) URL** — Use the **Login URL** value.
* **Certificate** — Paste the Base64-encoded certificate from the
  **SAML Certificates** section.

In both options, also configure the following setting:

* **Auto-provision new users** — When enabled, users are automatically
  created in Cube on their first login via this SAML provider. Enable this
  if you want to provision users only when they first access Cube and you
  are not using SCIM provisioning. New users receive the Viewer role by
  default; see [Default role for new users](#default-role-for-new-users)
  to choose a different role.

## Default role for new users

Auto-provisioned users — both via SAML and via [SCIM][ref-scim] — receive
the **Viewer** role by default. To assign a different role, expand the
**Advanced** section of the SAML configuration form and pick from
**Default role for new users**:

* **Developer**, **Explorer**, or **Viewer** — Cube's [default
  roles][ref-roles].
* Any [custom role][ref-custom-roles] defined in your account, listed
  below the divider.

The selected role applies **only when a user is first created** during
provisioning. Existing users are not modified on subsequent SSO logins or
SCIM updates.

<Info>
  Admin status is not assignable through this picker — Admin is controlled
  separately. To grant admin permissions, update the user's role manually
  under [Admin → Users][ref-manage-users].
</Info>

<Warning>
  If the selected role is later renamed or deleted, new users will fall
  back to the **Viewer** role until you pick a valid role here. The Viewer
  fallback applies whenever the configured default cannot be resolved —
  whether that's because no default is set or the configured role no longer
  exists.
</Warning>

## Map roles by group

For finer-grained role assignment, enable **Map roles by group** in the
**Advanced Settings** section to assign Cube roles based on a user's
Entra group memberships.

To configure group-based role mapping:

1. Make sure Entra sends a group claim on the SAML assertion. See the
   group-claim step in [Configure attribute
   mappings](#configure-attribute-mappings).
2. In the SAML configuration form in Cube, expand **Advanced Settings**.
3. (Optional) Under **SAML attribute customization**, set the **Groups
   attribute** to the simple name of the SAML attribute carrying group
   memberships. Defaults to `groups`. Cube also reads Entra's canonical
   groups claim URL automatically, so the default usually works
   out of the box.
4. Enable the **Map roles by group** toggle.
5. Click **Add group mapping** and create one entry per group you want
   to map:
   * **IdP group name** — the group display name as it appears in the
     assertion (case-insensitive). With **Source attribute** set to
     **sAMAccountName** or **Cloud-only group display names**, this is
     the human-readable group name. If you left the default (group object
     ID), use the GUID instead.
   * **Cube role** — pick a default or [custom role][ref-custom-roles].

For SAML SSO, group mappings are evaluated **only when a new user is
auto-provisioned** on first login. If any matching group resolves to a
Cube role, those roles are assigned to the new user **instead of** the
configured [default role](#default-role-for-new-users). The default role
is used as a fallback when no IdP group matches (or when the mapped Cube
roles no longer exist). Existing users' role assignments are never
modified by subsequent logins.

The same mapping is also applied by [SCIM][ref-scim] when group
memberships are pushed, so a single configuration drives both SAML SSO
and SCIM group sync.

## Assign users

Make sure the new Enterprise Application is assigned to the relevant
users or groups in Entra before testing.

## Test the integration

1. In the Entra **Single sign-on** section, click **Test**
   to verify the SAML integration works for your Cube account.
2. Alternatively, copy the **Single Sign-On URL** from Cube,
   open it in a new browser tab, and verify you are redirected to
   Entra for authentication and then back to Cube.

[ext-ms-entra-id]: https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id

[ref-scim]: /admin/sso/microsoft-entra-id/scim

[ref-roles]: /admin/users-and-permissions/roles-and-permissions

[ref-custom-roles]: /admin/users-and-permissions/custom-roles

[ref-manage-users]: /admin/users-and-permissions/manage-users


# SCIM provisioning with Microsoft Entra ID
Source: https://docs.cube.dev/admin/sso/microsoft-entra-id/scim

Automates user and group lifecycle in Cube by connecting SCIM provisioning to Microsoft Entra ID.

With SCIM (System for Cross-domain Identity Management) enabled, you can
automate user provisioning in Cube and keep user groups synchronized
with Microsoft Entra ID (formerly Azure Active Directory).

<Note>
  Available on [Enterprise plan](https://cube.dev/pricing).
</Note>

## Prerequisites

Before proceeding, ensure you have the following:

* Microsoft Entra SAML authentication already configured. If not, complete
  the [SAML setup][ref-saml] first.
* Admin permissions in Cube.
* Sufficient permissions in Microsoft Entra to manage Enterprise Applications.

## Enable SCIM provisioning in Cube

Before configuring SCIM in Microsoft Entra, you need to enable SCIM
provisioning in Cube:

1. In Cube, navigate to **Admin → Settings**.
2. In the **SAML** section, enable **SCIM Provisioning**.

## Generate an API key in Cube

To allow Entra ID to communicate with Cube via SCIM, you'll need to
create a dedicated API key:

1. In Cube, navigate to **Settings → API Keys**.
2. Create a new API key. Give it a descriptive name such as **Entra SCIM**.
3. Copy the generated key and store it securely — you'll need it in the
   next step.

## Set up provisioning in Microsoft Entra

This section assumes you already have a Cube Enterprise Application
in Microsoft Entra. If you haven't created one yet, follow the
[SAML setup guide][ref-saml] first.

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com).
2. Go to **Applications → Enterprise Applications** and open your
   Cube application.
3. Navigate to **Manage → Provisioning**.
4. Set the **Provisioning Mode** to **Automatic**.
5. Under **Admin Credentials**, fill in the following:
   * **Tenant URL** — Your Cube deployment URL with `/api/scim/v2`
     appended. For example: `https://your-deployment.cubecloud.dev/api/scim/v2`
   * **Secret Token** — The API key you generated in the previous step.
6. Click **Test Connection** to verify that Entra ID can reach
   Cube. Proceed once the test is successful.

## Configure attribute mappings

Next, configure which user and group attributes are synchronized with
Cube:

1. In the **Mappings** section, select the object type you want to
   configure — either users or groups.
2. Remove all default attribute mappings **except** the following:
   * **For users**: keep `userName`, `displayName` and `active`.
   * **For groups**: keep `displayName` and `members`.
3. Click **Save**.

<Info>
  Users provisioned via SCIM receive the **Viewer** role by default. To
  choose a different default role (including [custom roles][ref-custom-roles]),
  see [Default role for new users][ref-saml-default-role] on the SAML setup
  page — the setting is shared between SAML and SCIM.

  Admin permissions cannot be assigned through this setting. To grant admin
  permissions, update the user's role manually in Cube under **Admin →
  Users**.
</Info>

## Map roles by SCIM group

If you have configured [Map roles by group][ref-saml-map-roles-by-group]
on the SAML setup page, the same mapping is applied when SCIM provisions
group memberships from Entra — when Entra adds a user to a synchronized
group, Cube assigns the mapped role to that user. Role assignment is
**additive**: removing a user from an Entra group does not strip the
corresponding role; adjust the user's roles in Cube manually.

No separate configuration is required on the SCIM side — once the
mapping is defined on the SAML page, it drives both SAML SSO and SCIM
group sync. Match is on the group **display name** Entra pushes (the
`displayName` attribute in the **Group** mapping, case-insensitive).

## Syncing user attributes

You can sync [user attributes][ref-user-attributes] from Microsoft Entra to
Cube via SCIM, allowing you to centralize user management in Entra.

### Create a user attribute in Cube

In Cube, navigate to **Admin → Settings → User Attributes** and
create a new attribute. Take note of the attribute **reference** name — you will
need it when configuring Entra.

### Create an Entra user attribute

1. In the [Microsoft Entra admin center](https://entra.microsoft.com), navigate
   to **Applications → Enterprise Applications** and open your Cube
   application.
2. Go to **Manage → Provisioning → Mappings**.
3. Select the user mapping you want to add the attribute to.
4. At the bottom of the page, select **Show advanced options**.
5. Select **Edit attribute list for customappsso**.
6. Add a new attribute with the following settings:
   * **Name** — The reference of the attribute you created in Cube,
     prefixed with `urn:cube:params:1.0:UserAttribute:`.
     For example, for an attribute with the reference `country`, enter
     `urn:cube:params:1.0:UserAttribute:country`.
   * **Type** — Select the matching type (`string` or `integer`).
7. Save the changes.

### Create attribute mapping

1. After saving, click **Yes** when prompted.
2. In the **Attribute Mapping** page, click **Add New Mapping**.
3. In the **Target attribute** dropdown, select the attribute you created
   in the previous step.
4. Configure the source mapping to the appropriate Entra field.
5. Click **OK**, then **Save**.

The next time the Entra application syncs, the attribute values will be
provisioned as [user attributes][ref-user-attributes] in Cube.

[ref-saml]: /admin/sso/microsoft-entra-id/saml

[ref-saml-default-role]: /admin/sso/microsoft-entra-id/saml#default-role-for-new-users

[ref-saml-map-roles-by-group]: /admin/sso/microsoft-entra-id/saml#map-roles-by-group

[ref-custom-roles]: /admin/users-and-permissions/custom-roles

[ref-user-attributes]: /admin/users-and-permissions/user-attributes


# SAML authentication with Okta
Source: https://docs.cube.dev/admin/sso/okta/saml

Connects Okta to Cube Cloud with SAML so members authenticate through your existing Okta application.

With SAML (Security Assertion Markup Language) enabled, you can authenticate
users in Cube Cloud through Okta, allowing your team to access Cube Cloud
using single sign-on.

<Note>
  Available on [Enterprise plan](https://cube.dev/pricing).
</Note>

## Prerequisites

Before proceeding, ensure you have the following:

* Admin permissions in Cube Cloud.
* Account administrator permissions in your Okta organization to access
  the Admin Console and create SAML integrations.

## Enable SAML in Cube Cloud

First, enable SAML authentication in Cube Cloud:

1. In Cube Cloud, navigate to **Admin → Settings**.
2. On the **Authentication & SSO** tab, enable the **SAML**
   toggle.
3. For a new integration, set **Audience (SP Entity ID)** to the
   **Single Sign-On URL** shown directly above it. This gives the AuthnRequest
   issuer and response audience one matching service provider identifier.
4. Take note of the **Single Sign-On URL** and **Audience (SP Entity ID)**
   values — you'll need them when configuring the SAML integration in Okta.

<Note>
  Existing working Okta integrations with a different Audience do not need to
  change. If you update the value, change it in Cube and Okta together and test
  SAML sign-in before disabling another authentication method.
</Note>

## Create a SAML integration in Okta

1. Log in to your Okta organization as an administrator, then navigate to
   the Admin Console by clicking **Admin** in the top-right corner.
2. Click **Applications → Applications** from the navigation on the
   left, then click **Create App Integration**.
3. Select **SAML 2.0** and click **Next**.
4. Enter a name for your application and click **Next**.
5. Enter the following values in the **SAML Settings** section:
   * **Single sign on URL** — Use the **Single Sign-On URL**
     value from Cube Cloud.
   * **Audience URI (SP Entity ID)** — Use the **Audience (SP Entity ID)**
     value from Cube Cloud. It must match exactly.
6. Click **Next** to go to the **Feedback** screen, fill in
   any necessary details and click **Finish**.

## Configure attribute statements in Okta

After the application is created, configure attribute statements to map
user attributes from Okta to Cube Cloud:

1. In your SAML app integration, go to the **Sign On** tab.

2. Scroll down to the **Attribute statements** section.

3. Click **Add expression** and create the following entries:

   | Name    | Expression               |
   | ------- | ------------------------ |
   | `email` | `user.profile.email`     |
   | `name`  | `user.profile.firstName` |

4. If you plan to map Cube roles based on Okta group membership (see
   [Map roles by group](#map-roles-by-group) below), also add a **Group
   Attribute Statement**. Scroll to the **Group Attribute Statements**
   section and add:

   | Name     | Filter                 |
   | -------- | ---------------------- |
   | `groups` | **Matches regex** `.*` |

   Adjust the filter to scope which groups Okta sends — e.g.
   **Starts with** `cube-` to limit the assertion to Cube-related groups.
   The attribute name must match the **Groups attribute** value configured
   in Cube Cloud (defaults to `groups`).

## Retrieve SAML details from Okta

Next, retrieve the values you'll need to complete the configuration
in Cube Cloud:

1. In your SAML app integration, go to the **Sign On** tab.
2. In the sidebar, click **View SAML setup instructions**.
3. Take note of the following values from the setup instructions page:
   * **Identity Provider Single Sign-On URL**
   * **Identity Provider Issuer**
   * **X.509 Certificate**

## Complete configuration in Cube Cloud

Return to the SAML configuration page in Cube Cloud and provide the
identity provider details:

* **Entity ID / Issuer** — Use the **Identity Provider Issuer**
  value from Okta.
* **SSO (Sign on) URL** — Use the **Identity Provider Single
  Sign-On URL** value from Okta.
* **Certificate** — Paste the **X.509 Certificate** from Okta.
* **Auto-provision new users** — When enabled, users are automatically
  created in Cube on their first login via this SAML provider. Enable this
  if you want to provision users only when they first access Cube and you
  are not using SCIM provisioning. New users receive the Viewer role by
  default; see [Default role for new users](#default-role-for-new-users)
  to choose a different role.

## Default role for new users

Auto-provisioned users — both via SAML and via [SCIM][ref-scim] — receive
the **Viewer** role by default. To assign a different role, expand the
**Advanced** section of the SAML configuration form and pick from
**Default role for new users**:

* **Developer**, **Explorer**, or **Viewer** — Cube's [default
  roles][ref-roles].
* Any [custom role][ref-custom-roles] defined in your account, listed
  below the divider.

The selected role applies **only when a user is first created** during
provisioning. Existing users are not modified on subsequent SSO logins or
SCIM updates.

<Info>
  Admin status is not assignable through this picker — Admin is controlled
  separately. To grant admin permissions, update the user's role manually
  under [Admin → Users][ref-manage-users].
</Info>

<Warning>
  If the selected role is later renamed or deleted, new users will fall
  back to the **Viewer** role until you pick a valid role here. The Viewer
  fallback applies whenever the configured default cannot be resolved —
  whether that's because no default is set or the configured role no longer
  exists.
</Warning>

## Map roles by group

For finer-grained role assignment, enable **Map roles by group** in the
**Advanced Settings** section to assign Cube Cloud roles based on a user's
Okta group memberships.

To configure group-based role mapping:

1. Make sure Okta sends a group attribute statement on the SAML assertion.
   See step 4 of [Configure attribute statements in
   Okta](#configure-attribute-statements-in-okta).
2. In the SAML configuration form in Cube Cloud, expand **Advanced
   Settings**.
3. (Optional) Under **SAML attribute customization**, set the **Groups
   attribute** to the name of the SAML attribute you configured in Okta.
   Defaults to `groups`.
4. Enable the **Map roles by group** toggle.
5. Click **Add group mapping** and create one entry per group you want to
   map:
   * **IdP group name** — the Okta group **display name** exactly as it
     appears in the SAML assertion (case-insensitive).
   * **Cube Cloud role** — pick a default or [custom role][ref-custom-roles].

For SAML SSO, group mappings are evaluated **only when a new user is
auto-provisioned** on first login. If any matching group resolves to a
Cube Cloud role, those roles are assigned to the new user **instead of**
the configured [default role](#default-role-for-new-users). The default
role is used as a fallback when no IdP group matches (or when the mapped
Cube Cloud roles no longer exist). Existing users' role assignments are
never modified by subsequent logins.

The same mapping is also applied by [SCIM][ref-scim] when group
memberships are pushed, so a single configuration drives both SAML SSO
and SCIM group sync.

## Test SAML authentication

1. Copy the **Single Sign-On URL** from the SAML configuration page
   in Cube Cloud.
2. Open a new browser tab and paste the URL into the address bar, then
   press **Enter**.
3. You should be redirected to Okta to log in. After a successful login,
   you should be redirected back to Cube Cloud.

[okta-docs-create-saml-app]: https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SAML.htm

[ref-scim]: /admin/sso/okta/scim

[ref-roles]: /admin/users-and-permissions/roles-and-permissions

[ref-custom-roles]: /admin/users-and-permissions/custom-roles

[ref-manage-users]: /admin/users-and-permissions/manage-users


# SCIM provisioning with Okta
Source: https://docs.cube.dev/admin/sso/okta/scim

With SCIM (System for Cross-domain Identity Management) enabled, you can automate user provisioning in Cube Cloud and keep user groups synchronized with Okta.

<Note>
  Available on [Enterprise plan](https://cube.dev/pricing).
</Note>

## Prerequisites

Before proceeding, ensure you have the following:

* Okta SAML authentication already configured. If not, complete
  the [SAML setup][ref-saml] first.
* Admin permissions in Cube Cloud.
* Admin permissions in Okta to manage application integrations.

## Enable SCIM provisioning in Cube Cloud

Before configuring SCIM in Okta, you need to enable SCIM
provisioning in Cube Cloud:

1. In Cube, navigate to **Admin → Settings**.
2. In the **SAML** section, enable **SCIM Provisioning**.

## Generate an API key in Cube Cloud

To allow Okta to communicate with Cube Cloud via SCIM, you'll need to
create a dedicated API key:

1. In Cube Cloud, navigate to **Settings → API Keys**.
2. Create a new API key. Give it a descriptive name such as **Okta SCIM**.
3. Copy the generated key and store it securely — you'll need it in the
   next step.

## Enable SCIM provisioning in Okta

This section assumes you already have a Cube Cloud SAML app integration
in Okta. If you haven't created one yet, follow the
[SAML setup guide][ref-saml] first.

1. In the Okta Admin Console, go to **Applications → Applications**
   and open your Cube Cloud application.
2. On the **General** tab, click **Edit** in the
   **App Settings** section.
3. Set the **Provisioning** field to **SCIM** and click
   **Save**.

## Configure SCIM connection in Okta

1. Navigate to the **Provisioning** tab of your Cube Cloud application.
2. In the **Settings → Integration** section, click **Edit**.
3. Fill in the following fields:
   * **SCIM connector base URL** — Your Cube Cloud deployment URL with
     `/api/scim/v2` appended. For example:
     `https://your-deployment.cubecloud.dev/api/scim/v2`
   * **Unique identifier field for users** — `userName`
   * **Supported provisioning actions** — Select **Push New Users**,
     **Push Profile Updates**, and **Push Groups**.
   * **Authentication Mode** — Select **HTTP Header**.
4. In the **HTTP Header** section, paste the API key you generated
   earlier into the **Authorization** field.
5. Click **Test Connector Configuration** to verify that Okta can
   reach Cube Cloud. Proceed once the test is successful.
6. Click **Save**.

## Configure provisioning actions

After saving the SCIM connection, configure which provisioning actions
are enabled for your application:

1. On the **Provisioning** tab, go to **Settings → To App**.
2. Click **Edit** and enable the actions you want:
   * **Create Users** — Automatically create users in Cube Cloud when
     they are assigned in Okta.
   * **Update User Attributes** — Synchronize profile changes from Okta
     to Cube Cloud.
   * **Deactivate Users** — Deactivate users in Cube Cloud when they are
     unassigned or deactivated in Okta.
3. Click **Save**.

## Assign users and groups

For users and groups to be provisioned in Cube Cloud, you need to assign
them to your Cube Cloud application in Okta. This is also required for
group memberships to be correctly synchronized — pushing a group alone
does not assign its members to the application.

1. In your Cube Cloud application, navigate to the **Assignments** tab.
2. Click **Assign** and choose **Assign to Groups** (or
   **Assign to People** for individual users).
3. Select the groups or users you want to provision and click **Assign**,
   then click **Done**.

<Warning>
  If users were assigned to the application before SCIM provisioning was enabled,
  Okta will show the following message in the **Assignments** tab:
  *"User was assigned this application before Provisioning was enabled and not
  provisioned in the downstream application. Click Provision User."*

  To resolve this, click **Provision User** next to each affected user.
  This will trigger SCIM provisioning for them without needing to remove and
  re-add their assignment.
</Warning>

## Push groups to Cube Cloud

To synchronize groups from Okta to Cube Cloud, you need to select which
groups to push:

1. In your Cube Cloud application, navigate to the **Push Groups** tab.
2. Click **Push Groups** and choose how to find your groups — you can
   search by name or rule.
3. Select the groups you want to push to Cube Cloud and click **Save**.

## Default role for SCIM-provisioned users

Users created through SCIM receive the same default role configured for
SAML auto-provisioning — there is no separate SCIM control. By default
this is the **Viewer** role; to choose a different default role (including
[custom roles][ref-custom-roles]), see
[Default role for new users][ref-saml-default-role] on the SAML setup page.

The default role only applies to users created by SCIM (`POST
/api/scim/v2/Users`). Existing users are not modified by subsequent SCIM
profile updates.

## Map roles by SCIM group

If you have configured [Map roles by group][ref-saml-map-roles-by-group]
on the SAML setup page, the same mapping is applied when SCIM pushes
group memberships from Okta — when Okta adds a user to a pushed group,
Cube Cloud assigns the mapped role to that user. Role assignment is
**additive**: removing a user from an Okta group does not strip the
corresponding role; adjust the user's roles in Cube Cloud manually.

No separate configuration is required on the SCIM side — once the
mapping is defined on the SAML page, it drives both SAML SSO and SCIM
group sync. Match is on the group **display name** Okta pushes
(case-insensitive).

[ref-saml]: /admin/sso/okta/saml

[ref-saml-default-role]: /admin/sso/okta/saml#default-role-for-new-users

[ref-saml-map-roles-by-group]: /admin/sso/okta/saml#map-roles-by-group

[ref-custom-roles]: /admin/users-and-permissions/custom-roles


# Time zones
Source: https://docs.cube.dev/admin/time-zones

Run queries in the time zone your readers actually work in — account-wide, per user, and per dashboard.

By default, every query Cube runs buckets time in the deployment's
[default time zone](/docs/data-modeling/configuration#default-time-zone) — the
[`CUBEJS_DEFAULT_TIMEZONE`](/reference/configuration/environment-variables#cubejs_default_timezone)
environment variable, `UTC` unless you change it. That means "orders today" answers the
same question for everyone, regardless of where they sit — which is wrong by up to a day
for anyone outside that zone.

Turning on **user time zones** lets a zone be resolved per account, per user, and per
dashboard instead.

<Warning>
  This feature is **off by default**, and turning it on **moves numbers**. While it is
  off, nothing changes for anyone. Once it is on, a reader whose effective zone differs
  from that default sees different daily, weekly, and monthly totals — because the days
  are cut in a different place.
</Warning>

## What a time zone changes

The effective zone is applied to every query Cube runs on your behalf:

* **Time dimension bucketing** — which rows fall into which day, week, month, or quarter.
* **Relative dates** — `today`, `yesterday`, `this week`, `last 7 days`, and the dates
  the agent resolves when you ask about "today".
* **Date range filters** — the boundaries you type are interpreted in the effective zone.

It applies to charts, dashboards, drill-downs, subtotals and totals, sparklines, period
comparison, [Analytics Chat](/docs/explore-analyze/analytics-chat), and embedded
surfaces alike, so a dashboard's charts and its agent panel always agree.

A time zone is a **display and bucketing** concern only. It never affects what data a
user can see — access control still comes from roles and the security context.

## Turn it on

Go to **Admin → Settings → Time Zones**. Three controls, in the order the decisions are
made:

| Control                       | What it does                                                                                                                                     |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Enable user time zones**    | The master switch. Off by default; while off, no surface resolves a zone at all.                                                                 |
| **Tenant time zone**          | The account-wide zone: everyone gets it unless they override it. Leave it as **Deployment default** to keep using each deployment's own default. |
| **Allow personal time zones** | Whether users may choose their own zone on their Preferences page. On by default once the feature is enabled.                                    |

The last two appear only while the feature is enabled, and they apply to every user in
the account. The UI labels the middle control **Tenant time zone**; this page calls the
zone it sets the *account-wide zone*, matching how the docs scope things.

## Personal time zone

When **Allow personal time zones** is on, each user can pick their own zone under
**Preferences → Time zone** (see [Preferences](/docs/preferences#time-zone)). Only a zone
the user has explicitly chosen is ever applied — Cube never silently uses the browser's
zone, though it will offer the detected zone as a suggestion.

Turning **Allow personal time zones** off makes everyone query in the account-wide zone again,
and existing personal choices stop applying.

## Dashboard time zone

A dashboard is one artifact many people read, so its zone is a property of the dashboard
rather than of whoever opens it. Set it in the dashboard builder under
**Options → Time zone**, which offers three choices:

| Choice                 | Behavior                                                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Deployment default** | Inherit — follow the account-wide zone, or the deployment's own default when no account-wide zone is set.                            |
| **Viewer time zone**   | Resolve per reader, so each viewer sees their own local day. Use this for an operational board.                                      |
| A named zone           | Pin the dashboard — "this dashboard reports in `America/New_York`", and keeps doing so after an admin changes the account-wide zone. |

The zone is stored with the **published** version, so editing a draft does not move the
numbers on the dashboard people are currently reading. Publish to apply it.

**Viewer time zone** is offered only while **Allow personal time zones** is on — without
it, a per-reader promise is one Cube would not keep.

### Reading a dashboard in another zone

A published dashboard shows the zone its numbers are bucketed in, next to its title,
along with where that zone came from — **Set by this dashboard**, **Your own time zone**,
or **Deployment default**.

Where the dashboard leaves the choice open, that control is also a dropdown: pick another
zone to look at the same dashboard in it. This is a temporary lens, not an edit — nothing
is saved, nobody else is affected, and leaving the dashboard drops it.

The zone is shown but **not changeable** when the dashboard is pinned to a named zone, or
when the account does not allow personal time zones. In both cases the zone is not the
reader's to reinterpret.

## Exploration time zone

A saved exploration carries a zone the same way, chosen from the **Time zone** control in
the Explore header. The rows mean what they mean on a dashboard: inherit, resolve per
viewer, or pin a named zone. It saves as soon as you pick it, so anyone who opens the
exploration afterwards gets that zone; readers with view-only access see the zone but
cannot change it.

## How the zone is resolved

Highest priority first.

**A dashboard or a saved exploration:**

1. A reader's temporary lens, or an embed host's `?timezone=` (see
   [embedded time zones](/embedding/iframe/time-zones)).
2. The artifact's own pinned zone.
3. The reader's personal zone — only when the artifact is set to **Viewer time zone**,
   and only when the account allows personal zones.
4. What the artifact inherits: the account-wide embed zone for an embed, otherwise the
   account-wide zone.
5. The deployment's default time zone.

**Ad-hoc surfaces** — a new exploration, a standalone chat — resolve the reader's own
personal zone first, then the account-wide zone. Here the only reader is the person asking, so
their own zone is the right answer.

**Embedded surfaces** follow their own chain, documented in
[embedded time zones](/embedding/iframe/time-zones).

At every level, if nothing resolves, Cube sends no zone and the deployment applies its
default time zone — exactly as it did before this feature existed.

## Valid time zone values

Cube accepts [IANA time zone names][link-tzdb] such as `America/New_York` or
`Asia/Tokyo`. Bare UTC offsets like `+05:30` are **rejected** rather than accepted,
because Cube would compute them in UTC while reporting the offset back — silently wrong.
Legacy aliases are understood (`US/Eastern` resolves to `America/New_York`).

[link-tzdb]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones


# Custom roles
Source: https://docs.cube.dev/admin/users-and-permissions/custom-roles

Define fine-grained custom roles for your organization on the Enterprise plan.

<Info>
  Custom roles are available on the [Enterprise plan](https://cube.dev/pricing).
</Info>

Cube comes with [default roles][ref-default-roles] (Admin, Developer, Explorer, Viewer) that cover common use cases. When you need finer control — for example, to let a user edit the data model on a single deployment but nothing else — you can define **custom roles** with a tailored set of permissions.

[ref-default-roles]: /admin/users-and-permissions/roles-and-permissions

## How custom roles work

Each custom role is built around three concepts:

1. **Base Role** (required) — Viewer, Explorer, or Developer. Determines the user's license tier and the inherited level of access.
2. **Global permissions** — org-wide capabilities such as billing, customization, integrations, and account-wide deployment management.
3. **Deployment permissions** — one or more policies, each targeting "All deployments" or specific deployments.

Permissions stack: a user gets the union of every role assigned to them, so a user with multiple custom roles holds the broadest set of granted permissions.

## Browsing roles

To see the list of custom roles, go to **Admin → Custom Roles** in your Cube account. Click on a role to edit it, or click **Add Role** to create a new one.

## Anatomy of a custom role

The role builder uses a two-column layout. The left column (sticky as you scroll) holds the role's identity and the **Create / Update** button. The right column (scrollable) holds the permission cards.

### Name and description

* **Name** is required and must be unique within the account. The names `Admin`, `Guest`, `Developer`, `None`, and `All` are reserved.
* **Description** is optional but recommended — it shows up alongside the role on the Custom Roles list and on user profile pages.

### Base Role

Every custom role has exactly one **Base Role**. It determines:

* The user's **license tier** — Cube infers the tier from the highest Base Role across all of the user's roles.
* The **inherited** capabilities the role grants out of the box.

| Base Role | Description                                     |
| --------- | ----------------------------------------------- |
| Viewer    | Read-only access to dashboards and chats.       |
| Explorer  | Viewer + create/edit workbooks, run queries.    |
| Developer | Explorer + edit data model, manage deployments. |

Inheritance is hierarchical:

* **Explorer** automatically grants Viewer access.
* **Developer** automatically grants Explorer and Viewer access.

<Note>
  The Base Role is required. Save is disabled until one is selected.
</Note>

#### Auto-bump to Developer

If you check any deployment-scoped action stronger than **Access deployment** (`DeploymentRead`) — for example, **Edit deployment** or **Edit data model** — the Base Role is automatically forced to **Developer**, and the Viewer and Explorer options are disabled with a tooltip:

> Selected actions require Developer role

Removing the elevated action re-enables the lower tiers. This mirrors the server-side rule that any deployment write or data-model write requires the Developer license tier.

### Global permissions

Global permissions are org-wide. Check any number of them on the **Global permissions** card:

| Group                                | Permission                        | What it grants                                  |
| ------------------------------------ | --------------------------------- | ----------------------------------------------- |
| Audit & Billing                      | Manage audit log                  | Access and configure the audit log.             |
| Audit & Billing                      | View billing                      | View invoices and usage.                        |
| Customization                        | Manage chart palettes             | Create and edit org-wide chart palettes.        |
| Customization                        | Manage dashboard themes           | Create and edit org-wide dashboard themes.      |
| Integrations / Network               | Manage OAuth integrations         | Configure OAuth integrations and clients.       |
| Integrations / Network               | Issue OAuth tokens                | Mint OAuth tokens for integrations.             |
| Deployment management (account-wide) | Manage deployments (account-wide) | Create and list deployments across the account. |

### Deployment permissions

Deployment permissions are scoped to specific deployments. A custom role can have any number of **deployment policies**, each represented as its own card. Click **Add deployment policy** to add another card.

Each card has two sections:

#### Scope

Choose which deployments the policy applies to:

* **All deployments** — the policy covers every deployment in the account, including ones added later.
* **Specific deployments** — pick deployments from a searchable multi-select picker.

#### Actions

Either grant **Full access** (a shortcut that enables every current and future deployment-scoped permission) or pick granular actions:

| Group                   | Permission                      | What it grants                                                                                                                                                                                                                                                                             |
| ----------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| General                 | Access deployment               | Foundation permission required to access the deployment at all. A Viewer needs this just to open it.                                                                                                                                                                                       |
| General                 | Edit deployment                 | Modify general deployment settings (name, Build & Deploy, Configuration flags, etc.). Does **not** include environment variables, data sources, or other configuration secrets — see **Manage secrets**.                                                                                   |
| General                 | Delete deployment               | Remove the deployment.                                                                                                                                                                                                                                                                     |
| Configuration & Secrets | Manage secrets                  | View and edit environment variables, manage data sources (add/edit database connections, including the test-connection step), the Model Configuration card on **Settings → Configuration**, Power BI (XMLA) settings, and restarting dev mode to apply saved environment variable changes. |
| Data Model              | View data model                 | Read data model files and dev branches.                                                                                                                                                                                                                                                    |
| Data Model              | Edit data model                 | Edit the data model on any branch, including the main/deploy branch. Allows committing and merging to main, force-syncing main, and starting dev mode against main.                                                                                                                        |
| Data Model              | Edit data model on dev branches | Edit the data model only on non-default branches. Blocks any write that targets the main/deploy branch (including merging to main).                                                                                                                                                        |
| Monitoring              | Access query history            | View deployment query history, performance, and traces.                                                                                                                                                                                                                                    |
| Data Export             | Download data                   | Download query results as CSV from workbooks, Analytics Chat, and published dashboards. Granted by default to the built-in Viewer, Explorer, and Developer roles. See [Data download controls][ref-data-download-controls].                                                                |

When **Full access** is checked, the granular checkboxes appear checked and disabled — granting Full access today also covers any deployment-scoped permissions added in the future.

<Tip>
  **Access deployment** (`DeploymentRead`) and **Download data** (`DownloadData`) are special. They are the only deployment actions that do **not** auto-bump the Base Role to Developer, because Viewers also need them just to open a deployment and download data from it.
</Tip>

[ref-data-download-controls]: /admin/users-and-permissions/roles-and-permissions#restricting-data-downloads

## Walkthroughs

### Create a Viewer with read access to all deployments

A common pattern: someone who consumes dashboards and chats but never edits anything.

<Steps>
  <Step title="Open the role builder">
    Go to **Admin → Custom Roles** and click **Add Role**.
  </Step>

  <Step title="Name it">
    Set the **Name** to, e.g., `Org Viewer`.
  </Step>

  <Step title="Pick the Base Role">
    Select **Viewer**.
  </Step>

  <Step title="Add a deployment policy">
    Click **Add deployment policy**, leave **Scope** on **All deployments**, and check **Access deployment** under General.
  </Step>

  <Step title="Save">
    Click **Create**.
  </Step>
</Steps>

### Create an Explorer for a single deployment

For an analyst who works in one deployment.

<Steps>
  <Step title="Set up the basics">
    Name the role (e.g., `Marketing Analyst`) and pick **Explorer** as the Base Role.
  </Step>

  <Step title="Scope the policy">
    Add a deployment policy, switch **Scope** to **Specific deployments**, and pick the relevant deployment(s) from the picker.
  </Step>

  <Step title="Pick actions">
    Check **Access deployment** so the user can open the deployment, and add **Access query history** if they should see query performance.
  </Step>

  <Step title="Save">
    Click **Create**.
  </Step>
</Steps>

### Create a Developer with Full access to specific deployments

For a data engineer who owns a subset of deployments end-to-end.

<Steps>
  <Step title="Set up the basics">
    Name the role (e.g., `Sales Domain Owner`).
  </Step>

  <Step title="Add the deployment policy">
    Add a deployment policy, switch **Scope** to **Specific deployments**, pick the relevant deployments, and check **Full access**.
  </Step>

  <Step title="Confirm the auto-bump">
    The Base Role automatically switches to **Developer** and the Viewer/Explorer radios are disabled.
  </Step>

  <Step title="Save">
    Click **Create**.
  </Step>
</Steps>

## Assigning roles to users

To assign a custom role to a user:

1. Navigate to **Admin → Users**.
2. Either change the role from the dropdown in the users table, or click into the user's profile page.
3. Add one or more custom roles. Multiple roles stack — the user holds the union of permissions.

See [Manage users][ref-manage-users] for more.

[ref-manage-users]: /admin/users-and-permissions/manage-users

## Validation

The role builder enforces a few rules client-side:

* **Name** is required and must be unique. Reserved names (`Admin`, `Guest`, `Developer`, `None`, `All`) are rejected.
* **Base Role** is required — Save is disabled until one is picked, and an inline error appears if you try to submit without one.
* A deployment policy with **no actions selected** is silently dropped on save (treated as a no-op).
* A deployment policy with **Specific deployments** scope but no deployments selected is also dropped on save.

## Reference: action catalog

This section lists every action a custom role can grant. The internal action names match the names shown in the [audit log][ref-audit-log].

[ref-audit-log]: /admin/monitoring/audit-log

### Base Role actions (Global)

| Internal name | Label     | Description                                     |
| ------------- | --------- | ----------------------------------------------- |
| `AIBIView`    | Viewer    | Read-only access to dashboards and chats.       |
| `AIBIExplore` | Explorer  | Viewer + create/edit workbooks, run queries.    |
| `AIBIDevelop` | Developer | Explorer + edit data model, manage deployments. |

### Global actions

| Internal name                  | Label                             |
| ------------------------------ | --------------------------------- |
| `AuditLogManage`               | Manage audit log                  |
| `BillingRead`                  | View billing                      |
| `ChartPalettesManage`          | Manage chart palettes             |
| `DashboardThemesManage`        | Manage dashboard themes           |
| `OAuthIntegrationsManage`      | Manage OAuth integrations         |
| `OAuthIntegrationsIssueTokens` | Issue OAuth tokens                |
| `DeploymentsManage`            | Manage deployments (account-wide) |

### Deployment-scoped actions

| Internal name             | Label                                                    |
| ------------------------- | -------------------------------------------------------- |
| `All`                     | Full access (every current and future deployment action) |
| `DeploymentRead`          | Access deployment                                        |
| `DeploymentUpdate`        | Edit deployment                                          |
| `DeploymentDelete`        | Delete deployment                                        |
| `SecretsManage`           | Manage secrets                                           |
| `SchemaRead`              | View data model                                          |
| `SchemaUpdate`            | Edit data model                                          |
| `SchemaUpdateDevBranches` | Edit data model on dev branches                          |
| `APMRead`                 | Access query history                                     |
| `DownloadData`            | Download data                                            |


# Manage users
Source: https://docs.cube.dev/admin/users-and-permissions/manage-users

Add users to your Cube account, assign roles, and control their access.

Use the **Admin → Users** page to add people to your Cube account,
change their roles, and control what they can access.

<Info>
  Only users with the Admin role can manage other users.
</Info>

## The user list

The user list displays all users in your account along with their roles
and status. Use the search bar to filter users by name or email.

## Inviting users

To invite a new user:

1. Navigate to **Admin → Users**.
2. Click **Add User**.
3. Enter the user's email address.
4. Select a [role][ref-roles] for the user: Admin, Developer, Explorer, or
   Viewer.
5. Optionally, assign one or more [custom roles][ref-custom-roles].
6. Click **Create** to send the invitation.

After the user is created, an invitation link is generated. You can copy the
link and share it with the user. The user must visit the link to set their
password and activate their account.

### Resending invitations

If a user hasn't activated their account, you can resend or copy the
invitation link from the user list.

## Managing individual users

Click on a user in the user list to access their settings page. From here,
you can:

* Update the user's name
* Change their [role][ref-roles] (Admin, Developer, Explorer, or Viewer)
* Assign or remove [custom roles][ref-custom-roles]
* Add the user to [user groups][ref-groups]
* Set [user attribute][ref-attributes] values for data access control

### Changing a user's role

To change a user's role:

1. Navigate to **Admin → Users** and click on the user.
2. Select a new role from the role dropdown.
3. Save the changes.

Alternatively, you can change a user's role directly from the user list
using the role dropdown.

<Info>
  Admin roles are billed at the developer rate.
</Info>

## Deactivating and reactivating users

Deactivating a user revokes their access to Cube without permanently
removing their account. The user's active sessions are terminated immediately.

To deactivate a user:

1. Navigate to **Admin → Users**.
2. Click the actions menu for the user.
3. Select **Deactivate**.

<Warning>
  You cannot deactivate yourself or the last active Admin user.
</Warning>

To reactivate a deactivated user, follow the same steps and select
**Activate**. The user can then log in again with their existing credentials.

## Deleting users

Deleting a user permanently removes their account from Cube.

To delete a user:

1. Navigate to **Admin → Users**.
2. Click the actions menu for the user.
3. Select **Delete**.

<Warning>
  You cannot delete your own account. Deleting a user is irreversible.
</Warning>

## Provisioning users via SCIM

If your organization uses an identity provider such as [Okta][ref-okta] or
[Microsoft Entra ID][ref-entra-id], you can automate user provisioning and
deprovisioning through SCIM. See the [SSO & Identity Providers][ref-sso]
documentation for setup instructions.

Users created via SCIM — and users auto-provisioned on first SAML
login — receive the **Viewer** role by default. To assign a different
default role (including [custom roles][ref-custom-roles]), configure
**Default role for new users** in the **Advanced** section of your SAML
configuration. The setting is shared between SAML and SCIM.

[ref-roles]: /admin/users-and-permissions/roles-and-permissions

[ref-custom-roles]: /admin/users-and-permissions/custom-roles

[ref-attributes]: /admin/users-and-permissions/user-attributes

[ref-groups]: /admin/users-and-permissions/user-groups

[ref-sso]: /admin/sso

[ref-okta]: /admin/sso/okta/scim

[ref-entra-id]: /admin/sso/microsoft-entra-id/scim


# Roles & Permissions
Source: https://docs.cube.dev/admin/users-and-permissions/roles-and-permissions

_Understanding user roles and permissions in Cube._

Cube has four built-in default roles: Admin, Developer, Explorer, and Viewer. Each role has specific permissions and access levels designed to support different responsibilities within the platform.

The Enterprise tier allows creation of custom roles with a customized set of permissions tailored to your organization's specific needs.

## Permissions matrix

| Permission                                    | Admin | Developer | Explorer | Viewer |
| --------------------------------------------- | :---: | :-------: | :------: | :----: |
| Manage users and account settings             |   ✅   |     ❌     |     ❌    |    ❌   |
| Manage deployments and their settings         |   ✅   |     ✅     |     ❌    |    ❌   |
| Edit semantic model                           |   ✅   |     ✅     |     ❌    |    ❌   |
| Execute SQL queries against data sources      |   ✅   |     ✅     |     ❌    |    ❌   |
| Explore and query semantic models             |   ✅   |     ✅     |     ✅    |    ❌   |
| Create and edit workbooks                     |   ✅   |     ✅     |     ✅    |    ❌   |
| View published dashboards                     |   ✅   |     ✅     |     ✅    |    ✅   |
| Export data from dashboards (CSV, PDF, PNG)   |   ✅   |     ✅     |     ✅    |    ✅   |
| Access Analytics Chat                         |   ✅   |     ✅     |     ✅    |    ✅   |
| Query from external tools (Tableau, Power BI) |   ✅   |     ✅     |     ✅    |    ✅   |

<Info>
  Admin roles are billed at the developer rate.
</Info>

## Restricting data downloads

By default, all roles can download query results as CSV from workbooks, Analytics Chat, and published dashboards. Two controls restrict this:

* **Account-wide** — the **Allow data downloads** switch on the **Admin → Settings** page. Turning it off hides export controls everywhere, for all users — including admins and embeds.
* **Per user** — the **Download data** action in [custom roles][ref-custom-roles]. Built-in roles grant it by default; to remove download access for a group of users, assign them a custom role without it. Admins and anonymous embed viewers bypass it.

The account-wide switch always wins; the permission applies only while downloads are allowed account-wide. Both govern the download button, not data access — query results are still rendered on screen.

[ref-custom-roles]: /admin/users-and-permissions/custom-roles

## Agent Permissions

Agents are connected to Semantic Model Deployments and inherit the permission level of the user they are operating under.

Each agent can be configured to use the *Restrict Views* feature which allows to select the views that are visible to the agent.
This feature should not be used as a security measure. Configure [access policies][ref-data-access-policies] instead.

## Typical Usage Scenarios

* Viewers: Business users who consume published dashboards, use Analytics Chat, and query data through external tools like Tableau or Power BI
* Explorers: Typically data consumers and analysts
* Developers: Usually data stewards and data engineers
* Admins: Typically assigned to data engineers managing the entire Cube instance (billed at the developer rate with additional privileges)

[ref-data-access-policies]: /docs/data-modeling/data-access-policies


# User Attributes
Source: https://docs.cube.dev/admin/users-and-permissions/user-attributes

_Secure data access with user attributes for filtering based on individual permissions._

User attributes allow you to implement row-level security by filtering data based on user-specific values. This documentation explains how to set up and use user attributes for access control.

## Creating User Attributes

1. Go to **Admin → Attributes**
2. Click to create a new attribute
3. Configure the attribute:
   * Set a name
   * Choose the type
   * Optionally set a default value
   * Optionally set a display name

## Setting User Attribute Values

User attributes can be set on a per-user basis:

1. Go to the user's page
2. Locate the attributes section
3. Set the desired attribute value (e.g., setting city to "Los Angeles")

## Implementing Row-Level Access Policy

To filter data based on user attributes, implement an access policy in your views:

```yaml theme={"dark"}
views:
  - name: orders_view
    access_policy:
      - group: "*"  # Applies to all groups
        row_level:
          filters:
            - member: customers_city
              operator: equals
              values: ["{ userAttributes.city }"]
```

## Effect on Queries

When the access policy is implemented, queries will automatically be filtered based on the user's attributes. This ensures users can only access data that matches their attribute values.


# User groups
Source: https://docs.cube.dev/admin/users-and-permissions/user-groups

Organize Cube Cloud users into groups and tie those groups to data access policies instead of managing every account in isolation.

User groups allow you to organize users and manage access collectively.
Instead of assigning [user attributes][ref-user-attributes] to individual users, you can add users to groups for easier management at scale.
[Access policies][ref-dap] can be configured based on groups to control [row-level security][ref-rls].

## Creating groups

To create a user group:

1. Navigate to **Admin → User Groups**
2. Click **Create Group**
3. Enter a group name and optional description
4. Add users to the group

<Frame>
  <img alt="User Groups interface" />
</Frame>

## Assigning roles to groups

<Warning>
  Assigning roles to groups is currently in preview, and the user experience may still
  change. Reach out to the [Cube support team](/admin/account-billing/support) to activate
  this feature for your account.
</Warning>

Open a group and use the **Roles** section to assign [roles][ref-roles] to it. Every member
of the group gains the access that role grants, and removing the role from the group revokes
it from all members immediately.

Roles only ever add permissions — there is no precedence and no deny. A user with a Viewer
role who belongs to a group assigned Developer holds both, and is effectively a Developer.
This includes Admin: anyone who can edit a group's roles can grant administrative access
through it.

The **Effective access** section on a user's page lists the roles a user holds directly and
the roles conferred by a group, with the group named.

[ref-user-attributes]: /admin/users-and-permissions/user-attributes

[ref-roles]: /admin/users-and-permissions/roles-and-permissions

[ref-rls]: /docs/data-modeling/access-control/row-level-security

[ref-dap]: /docs/data-modeling/data-access-policies


# Get app config
Source: https://docs.cube.dev/api-reference/app-theme/get-app-config

/api-reference/api.yaml get /api/v1/app-config



# Authentication
Source: https://docs.cube.dev/api-reference/authentication

Authenticate REST and SCIM requests with a token sent using the Bearer prefix.

How you authenticate depends on which API you call. The REST management API
(`/api/v1/…` and `/build/api/v1/…`) and the SCIM API (`/api/scim/v2/…`) all take
a token in the `Authorization` header with the `Bearer` prefix, and only HTTPS is
accepted.

## REST API (`/api/v1`)

Authenticate deployment, report, and workbook requests with a token sent using
the `Bearer` prefix:

```text theme={"dark"}
Authorization: Bearer <YOUR_TOKEN>
```

The token can be an API key generated in your Cube account settings, or an
OAuth access token from Cube's OAuth flow — both are sent the same way.

If the API key is [scoped to specific deployments](/admin/account-billing/api-keys#deployment-scope),
it only authorizes requests for those deployments. A request targeting a
deployment outside the key's scope returns `403 Forbidden`. Unscoped keys
(**All deployments**) authorize requests for every deployment.

```bash theme={"dark"}
curl --request GET \
  --url 'https://<tenant>.cubecloud.dev/api/v1/deployments' \
  --header 'Authorization: Bearer <YOUR_TOKEN>'
```

The [data model endpoints](/api-reference/introduction#platform-api) under
`/build/api/v1/…` take the same token — only the path prefix differs.

## SCIM API (`/api/scim/v2`)

Authenticate user and group provisioning requests with a SCIM bearer token,
configured in your identity provider's SCIM integration:

```text theme={"dark"}
Authorization: Bearer <YOUR_SCIM_TOKEN>
```

The SCIM API requires the `Bearer` prefix because identity providers (Microsoft
Entra ID, Okta, and others) send credentials this way per
[RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644). The SCIM token is a
Cube API key, so `Api-Key <YOUR_SCIM_TOKEN>` is also accepted here.

Generate a SCIM token in your Cube account settings, then configure it in
your identity provider alongside the
[base URL](/api-reference/introduction#platform-api).

```bash theme={"dark"}
curl --request GET \
  --url 'https://<tenant>.cubecloud.dev/api/scim/v2/Users?count=100&startIndex=1' \
  --header 'Authorization: Bearer <YOUR_SCIM_TOKEN>'
```

<Warning>
  Treat API keys and SCIM tokens like passwords — unless an API key is scoped to
  specific deployments, they grant full access to your account's resources. Store
  them securely and rotate them if they are exposed.
</Warning>

A `401 Unauthorized` response means the credential is missing, malformed, or
expired. A `403 Forbidden` response means the credential is valid but not
authorized for the target — for example, an API key scoped to other deployments.


# Abort chat stream
Source: https://docs.cube.dev/api-reference/chat/abort-chat-stream

/api-reference/chat.yaml post /chat/abort
Stops an in-progress chat stream — for example, when the user cancels a request or navigates away while the agent is still generating a response.

The abort URL is derived from the Chat API URL by replacing `/stream-chat-state` with `/abort`.

A successful cancellation is indicated solely by the `204 No Content` status — the response has no body. Note that the aborted `stream-chat-state` request itself does not fail with an HTTP error: the streaming response already returned `200 OK` when the stream opened, so treat this endpoint's `204` as the confirmation that the stream was aborted.



# Stream chat state
Source: https://docs.cube.dev/api-reference/chat/stream-chat-state

/api-reference/chat.yaml post /chat/stream-chat-state
Real-time streaming conversation with Cube's AI agents for analytics and data exploration.

The response is streamed as newline-delimited JSON (each line is a standalone JSON object
terminated by `\n`) and served with `Content-Type: application/json`. Each line represents a
chat message, a state update, or an error object. Assistant content arrives incrementally —
updates to a previously emitted message carry the same `id` with `isDelta: true`.

Provide `input` to send a new message. Omit `input` (with a `chatId`) to retrieve the current
thread state. If `chatId` is omitted a new thread is created and its id is returned on the
`__cutoff__` message.

Special sentinel messages:
- `__cutoff__` — initial marker emitted before new content; also carries the thread `chatId` and `isStreaming` under `state`.
- `__state__` — final thread snapshot emitted at the end, carrying the full `{ messages: [...] }` state.

Errors mid-stream are emitted as a standalone line `{ "error": "<message>" }` rather than a non-200 status.

Finding the final answer: filter assistant messages where `graphPath[0] === "final"` and
`graphPath.length <= 2`; the last such message is the final answer.

Idempotency: provide a client-generated `messageId` in the format `<timestamp>-message` (a 13+ digit
Unix-millisecond timestamp). If a request with the same `messageId` arrives while a stream for that
message is still active on the thread, the API resubscribes the new request to the existing stream
instead of starting a new one.



# List a dashboard's embed access
Source: https://docs.cube.dev/api-reference/dashboard-embed-access/list-a-dashboards-embed-access

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/workbooks/{workbookId}/embed-access

Return the embed audience of a workbook's published dashboard: the global `allowEmbed` (signed-embedding) flag, whether it is shared with **all embed users**, and the list of individual embed **tenants** it is shared with.

Embed access is a read-only share of the workbook with a system sharing group, so this is scoped to the workbook that owns the dashboard. Requires **read** access to the workbook. Returns `404` if the workbook does not exist or belongs to a different deployment.


# Update a dashboard's embed access
Source: https://docs.cube.dev/api-reference/dashboard-embed-access/update-a-dashboards-embed-access

/api-reference/api.yaml put /api/v1/deployments/{deploymentId}/workbooks/{workbookId}/embed-access

Add, update, or remove one embed audience from a workbook's published dashboard, and/or toggle signed embedding. Returns the updated embed-access view.

Provide exactly one target — `embedTenantName` (a single embed tenant) or `allEmbedUsers: true` (every embed tenant) — together with `action`: `"read"` grants access, `"none"` removes it. Include `allowEmbed` to also flip "Allow signed embedding" in the same request; omit both targets to change only `allowEmbed`.

Requires **manage** access to the workbook. Returns `404` if the workbook or the named embed tenant does not exist, and `400` if the request specifies no change or sets `allowEmbed` on a workbook that has no published dashboard.


# Download a completed dashboard export
Source: https://docs.cube.dev/api-reference/dashboard-exports/download-a-completed-dashboard-export

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/dashboard-exports/{jobId}/download

Stream the rendered file as an attachment, named `dashboard.png` / `dashboard.pdf` unless `?filename=` supplies a different stem (the extension always follows the rendered format).

Returns `409` while the job is still rendering — poll `GET /dashboard-exports/{jobId}` first — `422` if the render failed (terminal: submit a new export rather than retrying this one), and `404` once the job has expired or if it belongs to a different user.


# Export a dashboard as PNG or PDF
Source: https://docs.cube.dev/api-reference/dashboard-exports/export-a-dashboard-as-png-or-pdf

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/dashboard-exports

Submit a render of a published dashboard. Identify it with either `dashboardId` (numeric) or `dashboardPublicId` (string) — supply exactly one; it must belong to this deployment, otherwise `404` is returned.

Returns as soon as the job is accepted, because a render waits for every widget to finish querying. Poll `GET /dashboard-exports/{jobId}` until `status` is `completed`, then fetch the file from `GET /dashboard-exports/{jobId}/download`. The job and its file are dropped at `expiresAt` (5 minutes) — download before then or submit again.

Pass `filters`, `timeGrains` and `memberSwitchers` to render the board with specific control values, exactly as a scheduled notification does; omit them to render its saved defaults.

By default the dashboard renders under the calling user's own security context, so the file shows what that user would see. Requires **manage** access to the dashboard's workbook — the same permission the console's own "Download as PNG / PDF" actions require, because a whole-dashboard render is a bulk data export.

To export on someone else's behalf, pass `renderAs`: the queries behind the image then run under that user's security context instead of yours. **Requires the caller to be a tenant administrator.** Name a console user by `userId` or `email` (`type: USER`), or an embed user by `embedTenantName` + `externalId` (`type: EMBED_USER`). A deactivated console user is not a valid subject and returns `404`; an email is matched case-insensitively.

An embed subject is provisioned if it does not exist yet, and `groups`, `userAttributes` and `securityContext` apply to **this render only** — they are carried on the render's own session and are NOT written to the user's stored context, so exporting for someone never changes what their live embedded sessions see. (Use the embed-tenant users API to change a user's stored context.) An embed subject additionally requires the dashboard's workbook to be shared with that embed tenant, otherwise `403` is returned.

Returns `403` when the workspace has data downloads restricted — including for an on-behalf-of export, which deliberately does **not** bypass that setting the way a built-in scheduled notification does — and `429` when there are already too many exports in flight for the identity being rendered as.


# Get the status of a dashboard export
Source: https://docs.cube.dev/api-reference/dashboard-exports/get-the-status-of-a-dashboard-export

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/dashboard-exports/{jobId}

Progress of a submitted render. Poll until `status` is `completed` (then download it) or `failed` (then read `error`); `pending` and `processing` both mean keep waiting.

Returns `404` once the job has expired, and for a job submitted by a different user — a job is only ever visible to whoever started it.


# Content hashes of the current data-model files (for upload diffing)
Source: https://docs.cube.dev/api-reference/data-model-uploads/content-hashes-of-the-current-data-model-files-for-upload-diffing

/api-reference/api.yaml get /build/api/v1/deployments/{deploymentId}/data-model/file-hashes



# Finish the upload transaction (prune removed files) and trigger a build
Source: https://docs.cube.dev/api-reference/data-model-uploads/finish-the-upload-transaction-prune-removed-files-and-trigger-a-build

/api-reference/api.yaml post /build/api/v1/deployments/{deploymentId}/data-model/upload/finish



# Start a data-model upload transaction
Source: https://docs.cube.dev/api-reference/data-model-uploads/start-a-data-model-upload-transaction

/api-reference/api.yaml post /build/api/v1/deployments/{deploymentId}/data-model/upload/start



# Upload a single file into an open transaction
Source: https://docs.cube.dev/api-reference/data-model-uploads/upload-a-single-file-into-an-open-transaction

/api-reference/api.yaml post /build/api/v1/deployments/{deploymentId}/data-model/upload/file



# Commit (and push) the active branch's pending changes
Source: https://docs.cube.dev/api-reference/data-model/commit-and-push-the-active-branchs-pending-changes

/api-reference/api.yaml post /build/api/v1/deployments/{deploymentId}/commit



# Compile a deployment's data model and report compilation errors
Source: https://docs.cube.dev/api-reference/data-model/compile-a-deployments-data-model-and-report-compilation-errors

/api-reference/api.yaml get /build/api/v1/deployments/{deploymentId}/data-model/validate

Asks the branch's own Cube runtime for `GET /cubejs-api/v1/meta` — the same call the console makes in dev mode — so the verdict is the one that branch's API would give. With neither parameter it validates the deploy branch (production). `branchName` validates a named branch, and `devMode=true` validates the caller's active dev-mode branch; the two are mutually exclusive. Answers 200 with `valid: false` and the compiler's errors when the model doesn't compile — a broken model is a result, not a request error.


# Create a branch (optionally entering dev mode on it)
Source: https://docs.cube.dev/api-reference/data-model/create-a-branch-optionally-entering-dev-mode-on-it

/api-reference/api.yaml post /build/api/v1/deployments/{deploymentId}/branches



# Create or overwrite data-model source files
Source: https://docs.cube.dev/api-reference/data-model/create-or-overwrite-data-model-source-files

/api-reference/api.yaml put /build/api/v1/deployments/{deploymentId}/data-model/files



# Delete a branch
Source: https://docs.cube.dev/api-reference/data-model/delete-a-branch

/api-reference/api.yaml delete /build/api/v1/deployments/{deploymentId}/branches

Deletes the branch and its git ref — the API-side counterpart of pruning a branch in Cube Cloud, for callers that create branches per run (a CI job syncing dbt on every pull request, say) and would otherwise accumulate them forever. Child branches are re-parented onto the deleted branch’s own parent, and anyone viewing the branch in dev mode is moved back to the default branch, so a branch that is currently open is deleted rather than refused. The deploy branch cannot be deleted (400) and an unknown branch is a 404.

`removeOnUpstream=true` additionally deletes the branch on the connected git provider (GitHub/GitLab). It defaults to `false`, so by default the branch is removed from Cube Cloud only and the ref on your own remote is left alone — a CI job cleaning up branches it created itself should opt in explicitly.

`branchName` is a query parameter rather than a path segment because branch names contain slashes (`dbt-sync/main-20260817120000-a1b2c3d4`).


# Delete data-model source files
Source: https://docs.cube.dev/api-reference/data-model/delete-data-model-source-files

/api-reference/api.yaml delete /build/api/v1/deployments/{deploymentId}/data-model/files



# Enable or disable a branch's staging environment
Source: https://docs.cube.dev/api-reference/data-model/enable-or-disable-a-branchs-staging-environment

/api-reference/api.yaml put /build/api/v1/deployments/{deploymentId}/branches/staging-environment

Enabling a branch keeps its staging environment always active and accessible at `<deploymentUrl>/dev-mode/{branchName}/cubejs-api/v1`; disabled (the default) it is only active while the branch is viewed in Cube Cloud. Enabled branches are the ones listed by `GET /api/v1/deployments/{deploymentId}/environments?type=staging`. Only shared branches qualify — personal dev branches and the deploy branch are rejected.


# Enter dev mode (switch to a branch)
Source: https://docs.cube.dev/api-reference/data-model/enter-dev-mode-switch-to-a-branch

/api-reference/api.yaml post /build/api/v1/deployments/{deploymentId}/dev-mode



# Exit dev mode
Source: https://docs.cube.dev/api-reference/data-model/exit-dev-mode

/api-reference/api.yaml delete /build/api/v1/deployments/{deploymentId}/dev-mode



# List a deployment's branches
Source: https://docs.cube.dev/api-reference/data-model/list-a-deployments-branches

/api-reference/api.yaml get /build/api/v1/deployments/{deploymentId}/branches



# List the data-model source files for a deployment
Source: https://docs.cube.dev/api-reference/data-model/list-the-data-model-source-files-for-a-deployment

/api-reference/api.yaml get /build/api/v1/deployments/{deploymentId}/data-model/files

Returns the data-model file tree. `first`/`after` (from the shared cursor params) paginate the **top-level** tree nodes only — a single node can carry a large subtree, so this bounds the number of roots returned, not the total file count. Omit `first` to get the whole tree.


# Merge a branch into its parent branch (git-flow merge)
Source: https://docs.cube.dev/api-reference/data-model/merge-a-branch-into-its-parent-branch-git-flow-merge

/api-reference/api.yaml post /build/api/v1/deployments/{deploymentId}/merge



# Merge a branch straight into the deploy (default) branch
Source: https://docs.cube.dev/api-reference/data-model/merge-a-branch-straight-into-the-deploy-default-branch

/api-reference/api.yaml post /build/api/v1/deployments/{deploymentId}/merge-to-default



# Pull the latest for a branch from its remote and rebuild if changed
Source: https://docs.cube.dev/api-reference/data-model/pull-the-latest-for-a-branch-from-its-remote-and-rebuild-if-changed

/api-reference/api.yaml post /build/api/v1/deployments/{deploymentId}/pull



# Rename data-model source files
Source: https://docs.cube.dev/api-reference/data-model/rename-data-model-source-files

/api-reference/api.yaml post /build/api/v1/deployments/{deploymentId}/data-model/files/rename



# JSON query
Source: https://docs.cube.dev/api-reference/data/json-query

/api-reference/core-data.yaml post /v1/load



# Load Metadata
Source: https://docs.cube.dev/api-reference/data/load-metadata

/api-reference/core-data.yaml get /v1/meta



# SQL query
Source: https://docs.cube.dev/api-reference/data/sql-query

/api-reference/core-data.yaml post /v1/cubesql
Run a SQL query against the Cube [SQL API](/reference/core-data-apis/sql-api) and stream the results. The response is newline-delimited JSON: the first line carries the `schema` (column names and types), optionally `lastRefreshTime`, and optionally `usedPreAggregations` naming the pre-aggregations the result was served from; each subsequent line carries a `data` chunk with one or more result rows.



# Cancel a running dbt sync
Source: https://docs.cube.dev/api-reference/dbt-sync/cancel-a-running-dbt-sync

/api-reference/api.yaml delete /api/v1/deployments/{deploymentId}/dbt-sync/{syncJobId}



# Get the log of a dbt sync
Source: https://docs.cube.dev/api-reference/dbt-sync/get-the-log-of-a-dbt-sync

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/dbt-sync/{syncJobId}/logs



# Get the result of a completed dbt sync
Source: https://docs.cube.dev/api-reference/dbt-sync/get-the-result-of-a-completed-dbt-sync

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/dbt-sync/{syncJobId}/result



# Get the status of a dbt sync
Source: https://docs.cube.dev/api-reference/dbt-sync/get-the-status-of-a-dbt-sync

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/dbt-sync/{syncJobId}



# List dbt syncs for a deployment
Source: https://docs.cube.dev/api-reference/dbt-sync/list-dbt-syncs-for-a-deployment

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/dbt-sync



# Start a dbt sync for a deployment
Source: https://docs.cube.dev/api-reference/dbt-sync/start-a-dbt-sync-for-a-deployment

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/dbt-sync



# Create a deployment with an empty starter project and trigger its first build
Source: https://docs.cube.dev/api-reference/deployment-creation/create-a-deployment-with-an-empty-starter-project-and-trigger-its-first-build

/api-reference/api.yaml post /build/api/v1/deployments

Scaffolds an empty starter project and triggers the first build. When `creationMethod` is `github`, no starter project is scaffolded — connect a repository afterwards via POST /build/api/v1/deployments/:deploymentId/github/connect.


# Advance a deployment to a given onboarding step (e.g. after connecting a source)
Source: https://docs.cube.dev/api-reference/deployments/advance-a-deployment-to-a-given-onboarding-step-eg-after-connecting-a-source

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/creation-step/advance



# Delete deployment
Source: https://docs.cube.dev/api-reference/deployments/delete-deployment

/api-reference/api.yaml delete /api/v1/deployments/{deploymentId}



# Deployment token
Source: https://docs.cube.dev/api-reference/deployments/deployment-token

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/token



# Get deployment
Source: https://docs.cube.dev/api-reference/deployments/get-deployment

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}



# Get deployment settings
Source: https://docs.cube.dev/api-reference/deployments/get-deployment-settings

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/settings

Every setting of a deployment in one payload — the full contents of the console Settings pages (general, configuration flags, deploy, launchpad, Cube Store private storage), plus the read-only values displayed alongside them. Secrets are excluded; read environment variables through `/env-vars` instead. Writes go to `PUT /:deploymentId`, which accepts the same fields and returns this payload.


# Get deployments
Source: https://docs.cube.dev/api-reference/deployments/get-deployments

/api-reference/api.yaml get /api/v1/deployments



# Latest build/compile status for a branch (production build or dev-mode)
Source: https://docs.cube.dev/api-reference/deployments/latest-buildcompile-status-for-a-branch-production-build-or-dev-mode

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/build-status



# List available Cube versions
Source: https://docs.cube.dev/api-reference/deployments/list-available-cube-versions

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/versions

Every Cube version this deployment can be switched to — the same set the console’s version picker offers: the head of each release channel, plus the older versions the tenant has run before (its release history). Pass a listed `releaseChannelVersion` to `PUT /:deploymentId`; anything else is rejected. The container image is resolved server-side and is not part of the write surface.


# List the pods currently scheduled for a deployment
Source: https://docs.cube.dev/api-reference/deployments/list-the-pods-currently-scheduled-for-a-deployment

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/pods



# Recent runtime logs (tail) for a deployment. With no `source`, reads both the production API / worker pods and the dev-mode worker, merged chronologically; scope with `?source=production` or `?source=dev`.
Source: https://docs.cube.dev/api-reference/deployments/recent-runtime-logs-tail-for-a-deployment-with-no-`source`-reads-both-the-production-api-worker-pods-and-the-dev-mode-worker-merged-chronologically;-scope-with-`?source=production`-or-`?source=dev`

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/logs



# Reset a deployment to the first onboarding step (project)
Source: https://docs.cube.dev/api-reference/deployments/reset-a-deployment-to-the-first-onboarding-step-project

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/creation-step/reset



# Update a deployment
Source: https://docs.cube.dev/api-reference/deployments/update-a-deployment

/api-reference/api.yaml put /api/v1/deployments/{deploymentId}

Update any subset of a deployment’s settings — everything the console’s Settings pages own — and read the full settings back. Fields you omit are left alone, and `templateVariables` is merged key-by-key rather than replaced, so setting one configuration flag never clears the others. `releaseChannelVersion` must be one of the versions `GET /:deploymentId/versions` lists for the target channel (in any of the forms it reports) — anything else is a 400, and the container image is resolved from the version rather than sent. Choosing a version that is not the channel’s latest also sets `releaseChannelVersionHold` unless you send it explicitly, so auto-upgrade does not undo the pin.


# Add embed group members
Source: https://docs.cube.dev/api-reference/embed-tenants/add-embed-group-members

/api-reference/api.yaml post /api/v1/embed-tenants/{embedTenantName}/groups/{id}/users

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Adds one or more embed users (1–1000 per request) to a group. Each member is identified by exactly one of `externalId` (the id passed to `generate-session`) or `embedUserId` (the numeric id this API returns). An `externalId` that has never signed in is provisioned as an embed user, so groups can be populated ahead of a user’s first session; an unknown `embedUserId` is a `404` instead. Memberships are added, never replaced: the user’s other groups — including the account-wide `groups` that drive data-model access — are left untouched. Idempotent: the response buckets every requested member into `addedMembers` or `unchangedMembers`.


# Create an embed group
Source: https://docs.cube.dev/api-reference/embed-tenants/create-an-embed-group

/api-reference/api.yaml post /api/v1/embed-tenants/{embedTenantName}/groups

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Creates a group inside the embed tenant. The name must be unique within the tenant and may not start with `system:` (that prefix is reserved for platform-managed groups). The group is immediately usable as a `tenantGroups` entry when generating a creator-mode embed session, and reaches the data model as `system:tenant:{embedTenantName}:{name}`. Returns `400` if the name is taken or reserved.


# Delete an embed group
Source: https://docs.cube.dev/api-reference/embed-tenants/delete-an-embed-group

/api-reference/api.yaml delete /api/v1/embed-tenants/{embedTenantName}/groups/{id}

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Deletes one of the embed tenant’s groups. Returns `400` while the group still has members — remove them first — and `404` if the group does not exist in this tenant.


# Delete embed tenant
Source: https://docs.cube.dev/api-reference/embed-tenants/delete-embed-tenant

/api-reference/api.yaml delete /api/v1/embed-tenants/{embedTenantName}

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Deletes an embed tenant and everything inside it — users, groups, memberships, attributes, policies, and content — plus the tenant's `system:tenant:*` sharing group. Idempotent: deleting a tenant that does not exist succeeds. The name must already be in canonical form (lowercase, per the `embedTenantName` rule); unlike the routes below, a name that differs only in case is rejected with `400` rather than being lowercased, so a typo can never cascade-delete a tenant the caller did not name exactly.


# Get an embed group
Source: https://docs.cube.dev/api-reference/embed-tenants/get-an-embed-group

/api-reference/api.yaml get /api/v1/embed-tenants/{embedTenantName}/groups/{id}

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Returns one of the embed tenant’s groups with its member count, or `404` if no such group exists in this tenant.


# List embed group members
Source: https://docs.cube.dev/api-reference/embed-tenants/list-embed-group-members

/api-reference/api.yaml get /api/v1/embed-tenants/{embedTenantName}/groups/{id}/users

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Lists the embed users that belong to a group, cursor-paginated, most recently added first. Each member carries both its numeric `id` and its `externalId`. Returns `404` if the group does not exist in this tenant.


# List embed groups
Source: https://docs.cube.dev/api-reference/embed-tenants/list-embed-groups

/api-reference/api.yaml get /api/v1/embed-tenants/{embedTenantName}/groups

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Lists the embed tenant's own groups (`embed_user_groups`), cursor-paginated, newest first, each with its member count. These are the groups an embed session references through `tenantGroups`; the implicit `system:tenant:*` sharing group is not included.


# List embed tenants
Source: https://docs.cube.dev/api-reference/embed-tenants/list-embed-tenants

/api-reference/api.yaml get /api/v1/embed-tenants

List the account's embed tenants, cursor-paginated. Supports `first`/`after` pagination and a case-insensitive `search` substring match on the tenant name. Requires an admin API key.


# List embed users
Source: https://docs.cube.dev/api-reference/embed-tenants/list-embed-users

/api-reference/api.yaml get /api/v1/embed-tenants/{embedTenantName}/users

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Lists the embed users belonging to one embed tenant, cursor-paginated and ordered by email. Alongside the numeric `id` this API uses, a user carries the `externalId` your integration knows it by (the id passed to `generate-session`) whenever it was recorded on the account — users provisioned before it was recorded come back without an `externalId`, though they stay addressable by it everywhere it is accepted as input. Use `search` to match a substring of the email or external id, or a complete external id, which resolves a user even when the response cannot echo it back.


# Provision an embed user
Source: https://docs.cube.dev/api-reference/embed-tenants/provision-an-embed-user

/api-reference/api.yaml post /api/v1/embed-tenants/{embedTenantName}/user

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Creates or updates one embed user from the identity your own system knows. An embed user is otherwise created the first time they generate a session, so this is how an integration puts its own directory into Cube up front: a user provisioned here is immediately addressable — listable, searchable, assignable to groups, and selectable wherever the product offers a choice of users — before they have ever opened the embed.

Idempotent, and the body is the desired state: provisioning an `externalId` that already exists updates it rather than failing. `email`, `userProfile.displayName` and `userProfile.picture` are overwritten when supplied and preserved when omitted; each group lane is REPLACED when supplied, preserved when omitted, and cleared by `[]`. The embed tenant itself is created on demand, so it need not exist yet.

Everything set here is exactly what `generate-session` would have set, and a later session for the same `externalId` re-applies whatever it carries — so provisioning changes when a user exists, never what their session grants them.


# Provision embed users in bulk
Source: https://docs.cube.dev/api-reference/embed-tenants/provision-embed-users-in-bulk

/api-reference/api.yaml post /api/v1/embed-tenants/{embedTenantName}/users

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Provisions up to 100 embed users in one request, each exactly as `POST /embed-tenants/{embedTenantName}/user` would. Use it to load a user directory into an embed tenant, and send further requests to cover a directory larger than one batch.

**This endpoint is partially successful.** It returns `200` whenever the request itself is well formed, and reports each user separately:

* `succeeded` — the users that were provisioned, in the order requested.
* `failed` — the entries that were not, each with the `externalId` and an `error` carrying the `status` and `message` the single-user endpoint would have returned (`400` for a group name that does not exist, `429` once the tenant is at its embed-user limit).

Users are applied one at a time in the order given, and earlier ones are not rolled back when a later one fails. Since provisioning is idempotent, resending the whole batch after fixing the failures is safe. A repeated `externalId` within one batch is applied once per entry, so the last one wins.


# Remove embed group members
Source: https://docs.cube.dev/api-reference/embed-tenants/remove-embed-group-members

/api-reference/api.yaml delete /api/v1/embed-tenants/{embedTenantName}/groups/{id}/users

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Removes one or more embed users (1–1000 per request) from a group, identified the same way as when adding them — exactly one of `externalId` or `embedUserId` each. Only this group’s membership is dropped; the users themselves and their other groups are left alone, and unlike adding, an unknown `externalId` is never provisioned. Idempotent: removing a user who is not a member is a no-op. Returns `204 No Content`, or `404` if the group does not exist in this tenant.


# Update an embed group
Source: https://docs.cube.dev/api-reference/embed-tenants/update-an-embed-group

/api-reference/api.yaml patch /api/v1/embed-tenants/{embedTenantName}/groups/{id}

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Updates a group’s description. The name is deliberately immutable: it is part of the security context an embed session carries (`system:tenant:{embedTenantName}:{name}`), so renaming would silently detach the data-model access policies written against it — create a new group instead. Pass an empty `description` to clear it.


# Enable or disable signed embedding for a dashboard
Source: https://docs.cube.dev/api-reference/embed/enable-or-disable-signed-embedding-for-a-dashboard

/api-reference/api.yaml patch /api/v1/embed/dashboard/{publicId}

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Sets the dashboard's "Allow signed embedding" flag (`allowEmbed`), which gates the customer-signed embedding path: with the flag off, embed sessions fetching `GET /api/v1/embed/dashboard/{publicId}` receive `403`. Trusted cube-cloud session flows (screenshoter, creator mode) and dashboards shared with all embed users are not affected by this flag.

Note that the flag alone does not make a dashboard embeddable — it must also be published and shared with the embed tenant. Returns `404` if the dashboard does not exist.


# Exchange a session for an embed token
Source: https://docs.cube.dev/api-reference/embed/exchange-a-session-for-an-embed-token

/api-reference/api.yaml post /api/v1/embed/session/token

Exchanges a one-time embed session id (created via `POST /api/v1/embed/generate-session`) for a signed, short-lived embed JWT used to authenticate the embedded analytics in the browser.

The session is **single-use**: it is consumed (deleted) on the first successful exchange, so a given `sessionId` can be redeemed only once. The returned token is signed with the tenant's embed secret, issued by `cubecloud`, and expires after 24 hours.

This endpoint is unauthenticated — it is called from the embedding client and the session id itself is the credential. Returns `401` if the session id is unknown or has already been redeemed.


# Generate an embed session
Source: https://docs.cube.dev/api-reference/embed/generate-an-embed-session

/api-reference/api.yaml post /api/v1/embed/generate-session

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Creates a one-time embed session for a deployment and returns its `sessionId`.

The session captures the embed context that will be baked into the embed token once redeemed — the target `deploymentId`, the end user's identity (`externalId` / `email` / `userProfile`), their group memberships, `userAttributes`, and an optional `securityContext`. Exchange the returned `sessionId` for a signed embed JWT via `POST /api/v1/embed/session/token` (single use).

The end user can be assigned to two independent kinds of group, which serve different purposes:

* **`groups`** — global, tenant-wide groups for **data-model access control**. Their names are passed verbatim into the Cube security context (`cubeCloud.groups`), where your data model's `access_policy` rules use them to gate cubes, views, members, and row-/column-level filters. They must already exist in the tenant.
* **`tenantGroups`** — per-embed-tenant groups for **sharing and organizing content within a single embed tenant** (e.g. sharing a workbook or dashboard with a group in Creator Mode). Requires `creatorMode: true` and `embedTenantName`; create them inline via `tenantGroupDefinitions`. In the security context they are namespaced as `system:tenant:{embedTenantName}:group:{group}`, so they never collide with a same-named global group.

See the individual request-body fields for the full contract.

`deploymentId` is required and the caller must have read access to it. Embedding must be enabled for the tenant, otherwise `403` is returned.


# Get an embeddable dashboard
Source: https://docs.cube.dev/api-reference/embed/get-an-embeddable-dashboard

/api-reference/api.yaml get /api/v1/embed/dashboard/{publicId}

Returns the dashboard identified by its `publicId` — including its reports/widgets — resolved within the caller's embed session scope, for rendering inside an embedded view.

Access is authorized against the embed user: the dashboard is returned when the user owns its workbook, has been granted workbook access (folder-based or direct), holds `EmbedDashboardRead` on the dashboard, or when it has been shared with all embed users (creator-mode flow). Returns `404` if the dashboard does not exist or is not visible to the caller.

Signed embedding additionally requires the dashboard to have "Allow signed embedding" enabled; the trusted screenshoter and creator-mode session flows are exempt. Returns `403` when embedding is not permitted for the dashboard.


# Run a python report over dashboard-filtered SQL
Source: https://docs.cube.dev/api-reference/embed/run-a-python-report-over-dashboard-filtered-sql

/api-reference/api.yaml post /api/v1/embed/dashboard/{publicId}/python-run

Re-runs the Python analysis attached to one of this dashboard's reports over `sqlQuery` — the report's own query with the dashboard's filters and time grains already applied — and returns the result **without persisting it**.

Authorized against the dashboard, exactly as `GET /api/v1/embed/dashboard/{publicId}` is. The `reportVersionId` must be one of that dashboard's published report snapshots and must belong to `reportId`; anything else returns `403`. The Python itself is read server-side from that snapshot — it is never supplied by the caller.

The analysis runs under the calling embed user's own security context, so row-level security applies to the viewer, and the stored result other viewers see is left untouched. Results are cached briefly per (report, code, SQL, user); failures are not cached. Returns `403` when Python analysis is not enabled for the account.


# Get env variables
Source: https://docs.cube.dev/api-reference/env-variables/get-env-variables

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/env-vars

Lists the deployment environment variables, cursor-paginated via `first`/`after`. Values of secret-named variables (containing PASS, SECRET, TOKEN, KEY, or CREDENTIAL) are returned as `[ENCRYPTED]`.


# Set env variables
Source: https://docs.cube.dev/api-reference/env-variables/set-env-variables

/api-reference/api.yaml put /api/v1/deployments/{deploymentId}/env-vars

Upserts deployment environment variables by name; variables not included keep their existing values. Passing the `[ENCRYPTED]` placeholder (the masked read value) is rejected — omit variables you do not intend to change. New variable names must be POSIX identifiers (`^[A-Za-z_][A-Za-z0-9_]*$`); names already stored on the deployment may be resent unchanged so a legacy name can still be updated or removed.


# Create deployment environment token
Source: https://docs.cube.dev/api-reference/environments/create-deployment-environment-token

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/environments/{environmentId}/tokens



# Create deployment environment token for meta sync
Source: https://docs.cube.dev/api-reference/environments/create-deployment-environment-token-for-meta-sync

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/environments/{environmentId}/tokens-for-meta-sync



# Get deployment environment tokens
Source: https://docs.cube.dev/api-reference/environments/get-deployment-environment-tokens

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/environments/{environmentId}/tokens



# Get deployment environments
Source: https://docs.cube.dev/api-reference/environments/get-deployment-environments

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/environments



# Create a folder
Source: https://docs.cube.dev/api-reference/folders/create-a-folder

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/folders

Create a new folder in a deployment's workspace.

Provide a `name`, and optionally a `parentId` to nest the folder inside an existing one (omit it to create the folder at the workspace root). An optional `position` controls the folder's ordering among its siblings.

Requires the **AI BI User** role (or higher). When `parentId` is set, the caller must additionally have **edit** or **manage** access to that parent folder.

Folders can be nested up to a fixed maximum depth; exceeding it returns `400`.


# Delete a folder
Source: https://docs.cube.dev/api-reference/folders/delete-a-folder

/api-reference/api.yaml delete /api/v1/deployments/{deploymentId}/folders/{folderId}

Delete a folder from a deployment's workspace. Responds with `204 No Content` on success.

The folder must be empty of sub-folders: if it still has child folders, the request is rejected with `400` — delete or move the sub-folders first.

Content directly inside the folder (workbooks, dashboards, reports) is **not** deleted. It is detached and returned to the workspace root.

Requires **manage** access to the folder. Returns `404` if the folder does not exist or belongs to a different deployment.


# List folder ancestors
Source: https://docs.cube.dev/api-reference/folders/list-folder-ancestors

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/folders/{folderId}/ancestors

Return the ancestor chain of a folder, ordered from the workspace root down to (and including) the folder itself.

Use this to render a breadcrumb path for a nested folder. For example, for `Root / Sales / Q1` requested on the `Q1` folder, the response is `[Root, Sales, Q1]`.

Requires visibility access to the target folder. Returns `404` if the folder does not exist or belongs to a different deployment.


# List folders
Source: https://docs.cube.dev/api-reference/folders/list-folders

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/folders

List the folders in a deployment's workspace.

By default this returns the folders at the workspace root. Pass the `parentId` query parameter to list the direct children of a specific folder instead.

Results are scoped to the calling user: only folders the user can see are returned. A folder is visible when the user owns it, has been granted access to it directly, or has access to something inside it (a sub-folder, workbook, or dashboard), in which case the ancestor folders are surfaced as navigation.

This endpoint is not recursive — it returns a single level of the folder tree per call. Use `parentId` to walk deeper, or `GET /folders/{folderId}/ancestors` to resolve a breadcrumb path.

Results are returned in pages using cursor-based pagination: pass `first` to set the page size and `after` (the previous response's `pageInfo.endCursor`) to fetch the next page. The legacy `data` and `count` fields are still populated for backwards compatibility but are deprecated in favour of `items` and `pageInfo`.


# Update a folder
Source: https://docs.cube.dev/api-reference/folders/update-a-folder

/api-reference/api.yaml put /api/v1/deployments/{deploymentId}/folders/{folderId}

Update a folder's metadata — its `name` and/or its `position` among its siblings. Both fields are optional; only the fields you send are changed.

This endpoint does **not** move a folder to a different parent. To re-parent a folder, use `POST /workspace/move` with `type: FOLDER`.

Requires **edit** access to the folder. Returns `404` if the folder does not exist or belongs to a different deployment.


# Connect a deployment to a GitHub repository and trigger a build
Source: https://docs.cube.dev/api-reference/github-connection/connect-a-deployment-to-a-github-repository-and-trigger-a-build

/api-reference/api.yaml post /build/api/v1/deployments/{deploymentId}/github/connect



# List branches of a repository
Source: https://docs.cube.dev/api-reference/github/list-branches-of-a-repository

/api-reference/api.yaml get /api/v1/github/repositories/{owner}/{repo}/branches



# List repositories accessible to a GitHub App installation
Source: https://docs.cube.dev/api-reference/github/list-repositories-accessible-to-a-github-app-installation

/api-reference/api.yaml get /api/v1/github/installations/{installationId}/repositories



# List the user's GitHub App installations (orgs/accounts)
Source: https://docs.cube.dev/api-reference/github/list-the-users-github-app-installations-orgsaccounts

/api-reference/api.yaml get /api/v1/github/installations



# Whether GitHub is linked, plus the link/install URLs
Source: https://docs.cube.dev/api-reference/github/whether-github-is-linked-plus-the-linkinstall-urls

/api-reference/api.yaml get /api/v1/github/status



# Introduction
Source: https://docs.cube.dev/api-reference/introduction

Cube's HTTP APIs — query your data with the Core Data API, stream agent conversations with the AI API, and manage Cube with the Platform API.

Cube exposes three HTTP API families, each for a different job and with slightly
different authentication:

| API               | What it's for                                                                             | Authentication                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Core Data API** | Query your data model over HTTP — run queries (`/v1/load`) and read metadata (`/v1/meta`) | Cube API token (a JWT) sent **directly** in the `Authorization` header — no prefix |
| **AI API**        | Stream conversations with Cube AI agents (`/chat/stream-chat-state`)                      | Cube API key with the **`Api-Key`** prefix                                         |
| **Platform API**  | Manage Cube — deployments, data models, reports, workbooks, users, policies, and more     | **`Bearer`** prefix for REST and SCIM 2.0                                          |

The exact header for each is shown above. The Platform and SCIM schemes are
detailed on the [Authentication](/api-reference/authentication) page; the Core
Data and AI headers are also documented on their own reference pages.

## Available endpoints

Each API family has its own base URL — copy the exact host from the Cube
interface where noted. Only HTTPS is accepted, and every request must be
authenticated (see [Authentication](/api-reference/authentication)).

### Core Data API

Base URL — your deployment's data API host (the `/cubejs-api` base path is configurable):

```text theme={"dark"}
https://{deployment}.{region}.cubecloudapp.dev/cubejs-api
```

| Endpoint                                      | Path               |
| --------------------------------------------- | ------------------ |
| [JSON query](/api-reference/data/json-query)  | `POST /v1/load`    |
| [SQL query](/api-reference/data/sql-query)    | `POST /v1/cubesql` |
| [Metadata](/api-reference/data/load-metadata) | `GET /v1/meta`     |

### AI API

Base URL — your agent's Chat API URL (copy it from **Admin → Agents → Chat API URL**):

```text theme={"dark"}
https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}
```

| Endpoint                                                   | Path                           |
| ---------------------------------------------------------- | ------------------------------ |
| [Stream chat state](/api-reference/chat/stream-chat-state) | `POST /chat/stream-chat-state` |

### Platform API

Base URL — your tenant host:

```text theme={"dark"}
https://{tenant}.cubecloud.dev
```

Endpoints live under three path prefixes on that host, all taking the same token:

| Prefix            | What it covers                                                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `/api/v1/…`       | Management of deployments, workspace content, users, policies, and embedding                                                   |
| `/build/api/v1/…` | Data model authoring — files, uploads, dev mode, and branches. Routed to the build workers that own a deployment's data model. |
| `/api/scim/v2/…`  | SCIM 2.0 user and group provisioning                                                                                           |

Resources by entity:

| Entity                                                                                                                                  | Resource                                                                 | Version  |
| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -------- |
| [Deployments](/api-reference/deployments/get-deployments)                                                                               | `/api/v1/deployments`                                                    | v1       |
| [Deployment Creation](/api-reference/deployment-creation/create-a-deployment-with-an-empty-starter-project-and-trigger-its-first-build) | `/build/api/v1/deployments`                                              | v1       |
| [Environments](/api-reference/environments/get-deployment-environments)                                                                 | `/api/v1/deployments/{deploymentId}/environments`                        | v1       |
| [Env Variables](/api-reference/env-variables/get-env-variables)                                                                         | `/api/v1/deployments/{deploymentId}/env-vars`                            | v1       |
| [Regions](/api-reference/regions/list-regions)                                                                                          | `/api/v1/regions`                                                        | v1       |
| [Data Model](/api-reference/data-model/list-a-deployments-branches)                                                                     | `/build/api/v1/deployments/{deploymentId}`                               | v1       |
| [Data Model Uploads](/api-reference/data-model-uploads/content-hashes-of-the-current-data-model-files-for-upload-diffing)               | `/build/api/v1/deployments/{deploymentId}/data-model`                    | v1       |
| [GitHub](/api-reference/github/list-repositories-accessible-to-a-github-app-installation)                                               | `/api/v1/github`                                                         | v1       |
| [GitHub Connection](/api-reference/github-connection/connect-a-deployment-to-a-github-repository-and-trigger-a-build)                   | `/build/api/v1/deployments/{deploymentId}/github/connect`                | v1       |
| [dbt Sync](/api-reference/dbt-sync/list-dbt-syncs-for-a-deployment)                                                                     | `/api/v1/deployments/{deploymentId}/dbt-sync`                            | v1       |
| [Folders](/api-reference/folders/list-folders)                                                                                          | `/api/v1/deployments/{deploymentId}/folders`                             | v1       |
| [Reports](/api-reference/reports/list-reports)                                                                                          | `/api/v1/deployments/{deploymentId}/reports`                             | v1       |
| [Workbooks](/api-reference/workbooks/get-workbooks)                                                                                     | `/api/v1/deployments/{deploymentId}/workbooks`                           | v1       |
| [Notifications](/api-reference/notifications/list-scheduled-notifications)                                                              | `/api/v1/deployments/{deploymentId}/notifications`                       | v1       |
| [Workspace](/api-reference/workspace/list-shared-workspace-items)                                                                       | `/api/v1/deployments/{deploymentId}`                                     | v1       |
| [Users](/api-reference/users/update-my-settings)                                                                                        | `/api/v1/users/me/settings`                                              | v1       |
| [Users Admin](/api-reference/users-admin/create-user)                                                                                   | `/api/v1/users`                                                          | v1       |
| [User Attributes](/api-reference/user-attributes/get-user-attributes)                                                                   | `/api/v1/user-attributes`                                                | v1       |
| [User Attribute Values](/api-reference/user-attribute-values/upsert-user-attribute-value)                                               | `/api/v1/user-attribute-values`                                          | v1       |
| [Tenant Settings](/api-reference/tenant-settings/get-tenant-settings)                                                                   | `/api/v1/tenant/settings`                                                | v1       |
| [OAuth Integrations](/api-reference/oauth-integrations/list-oauth-integrations)                                                         | `/api/v1/oauth-integrations`                                             | v1       |
| [User OAuth Tokens](/api-reference/user-oauth-tokens/list-user-oauth-tokens)                                                            | `/api/v1/user-oauth-tokens`                                              | v1       |
| [OIDC Token Configs](/api-reference/oidc-token-configs/list-oidc-token-configs)                                                         | `/api/v1/oidc-token-configs`                                             | v1       |
| [App Theme](/api-reference/app-theme/get-app-config)                                                                                    | `/api/v1/app-config`                                                     | v1       |
| [Embed](/api-reference/embed/get-an-embeddable-dashboard)                                                                               | `/api/v1/embed`                                                          | v1       |
| [Embed Tenants](/api-reference/embed-tenants/list-embed-tenants)                                                                        | `/api/v1/embed-tenants`                                                  | v1       |
| [Dashboard Embed Access](/api-reference/dashboard-embed-access/list-a-dashboards-embed-access)                                          | `/api/v1/deployments/{deploymentId}/workbooks/{workbookId}/embed-access` | v1       |
| [Usage Analytics](/api-reference/usage-analytics/issue-a-cube-api-token-for-usage-analytics)                                            | `/api/v1/usage-analytics/token`                                          | v1       |
| [OpenAPI Spec](/api-reference/openapi-spec/get-the-openapi-specification)                                                               | `/api/v1/spec`                                                           | v1       |
| [Dashboard Exports](/api-reference/dashboard-exports/export-a-dashboard-as-png-or-pdf)                                                  | `/api/v1/deployments/{deploymentId}/dashboard-exports`                   | v1       |
| [Users (SCIM)](/api-reference/scim-users/list-users)                                                                                    | `/api/scim/v2/Users`                                                     | SCIM 2.0 |
| [Groups (SCIM)](/api-reference/scim-groups/list-groups)                                                                                 | `/api/scim/v2/Groups`                                                    | SCIM 2.0 |

## Client libraries

### Core Data API

Query the Core Data API from JavaScript or TypeScript with Cube's JS client,
[`@cubejs-client/core`](https://www.npmjs.com/package/@cubejs-client/core), which
also ships React, Vue, and Angular bindings and a WebSocket transport for
real-time updates. See the [JavaScript SDK](/reference/javascript-sdk) reference
for full usage.

```bash theme={"dark"}
npm install @cubejs-client/core
```

### Platform API

The recommended way to call the Platform API from JavaScript or TypeScript is the
official client, [`@cube-dev/platform-client`](https://www.npmjs.com/package/@cube-dev/platform-client).
It wraps the OpenAPI spec on this site with end-to-end types for every endpoint,
request, and response, plus optional [React Query](https://tanstack.com/query)
bindings.

<CodeGroup>
  ```bash npm theme={"dark"}
  npm install @cube-dev/platform-client
  ```

  ```bash yarn theme={"dark"}
  yarn add @cube-dev/platform-client
  ```

  ```bash pnpm theme={"dark"}
  pnpm add @cube-dev/platform-client
  ```
</CodeGroup>

Create a client with your tenant's base URL and an auth header (see
[Authentication](/api-reference/authentication)), then call any endpoint through
the fully-typed `fetchClient`:

```ts theme={"dark"}
import { createCubePlatformClient } from '@cube-dev/platform-client';

const client = createCubePlatformClient({
  baseUrl: 'https://<tenant>.cubecloud.dev',
  // Returned on every request — provide the Platform API auth header.
  getHeaders: () => ({ Authorization: `Bearer ${process.env.CUBE_API_KEY}` }),
});

const { data, error } = await client.fetchClient.GET('/api/v1/deployments/', {
  params: { query: { first: 50 } },
});

for (const deployment of data?.items ?? []) {
  console.log(deployment.id, deployment.name);
}
```

#### React Query bindings

The `@cube-dev/platform-client/react-query` entry point adds a provider and typed
hooks built on `@tanstack/react-query` (a peer dependency alongside `react`):

```tsx theme={"dark"}
import { createCubePlatformClient } from '@cube-dev/platform-client';
import {
  CubePlatformApiProvider,
  useCubePlatformApiQuery,
} from '@cube-dev/platform-client/react-query';

const client = createCubePlatformClient({ baseUrl, getHeaders });

function App() {
  return (
    <CubePlatformApiProvider client={client}>
      <Deployments />
    </CubePlatformApiProvider>
  );
}

function Deployments() {
  const { data } = useCubePlatformApiQuery('get', '/api/v1/deployments/');
  return <ul>{data?.items.map((d) => <li key={d.id}>{d.name}</li>)}</ul>;
}
```

<Info>
  Schema types are exported as `PlatformApiSchemas` (e.g.
  `PlatformApiSchemas['Deployment']`). See the package
  [`CHANGELOG`](/api-reference/changelog) for release notes and breaking changes.
</Info>


# Add notification recipients
Source: https://docs.cube.dev/api-reference/notifications/add-notification-recipients

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/notifications/{id}/recipients

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Subscribes one or more recipients (1–1000 per request) to a notification. Each recipient is one of: a main console `USER` (identified by `userId` or `email`); an `EMBED_USER` (identified by `embedTenantName` + `externalId`, auto-provisioned if it does not yet exist, and optionally given `securityContext`, `userAttributes`, and `groups` that drive per-recipient rendering); or `SLACK` — **not yet supported**, a request containing a Slack recipient is rejected with `400`. Every recipient must resolve to a valid email (an embed user’s `email`, or an email-shaped `externalId`); otherwise the whole request fails with `400` before anything is written. The operation is idempotent: the response buckets each recipient into `createdRecipients`, `updatedRecipients` (an existing recipient whose embed properties changed), or `unchangedRecipients`.


# Create a scheduled notification
Source: https://docs.cube.dev/api-reference/notifications/create-a-scheduled-notification

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/notifications

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Creates a scheduled notification — a recurring run of a dashboard whose rendered result is delivered to its recipients. The cadence is set by `scheduleType` plus the relevant time fields (`minute`, `hour`, `dayOfWeek`, `dayOfMonth`) or a raw `customCron` expression when `scheduleType` is `CUSTOM`; `timezone` defaults to UTC. Identify the target dashboard with either `dashboardId` (numeric) or `dashboardPublicId` (string) — supply exactly one; it must belong to this deployment, otherwise `404` is returned. The created notification has no recipients — add them via `POST /notifications/{id}/recipients`.


# Delete a scheduled notification
Source: https://docs.cube.dev/api-reference/notifications/delete-a-scheduled-notification

/api-reference/api.yaml delete /api/v1/deployments/{deploymentId}/notifications/{id}

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Permanently deletes a scheduled notification and all of its recipients (main, embed, and Slack) in a single cascade. Returns `204 No Content` on success, or `404` if the notification does not belong to this deployment.


# Get a scheduled notification
Source: https://docs.cube.dev/api-reference/notifications/get-a-scheduled-notification

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/notifications/{id}

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Returns a single scheduled notification by id, including its cron expression, timezone, enabled state, notification format, and a human-readable schedule summary. Returns `404` if the notification does not exist or does not belong to this deployment.


# List notification recipients
Source: https://docs.cube.dev/api-reference/notifications/list-notification-recipients

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/notifications/{id}/recipients

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Returns the recipients subscribed to a notification, cursor-paginated and ordered by creation time (newest first). Recipients span three kinds, distinguished by `type`: `USER` (a main console user, with `userId` + `email`), `EMBED_USER` (an embed user, with `embedUserId`, `embedTenantName`, `externalId`, and `email`), and `SLACK` (a channel, with `channelId` + `channelName`). Returns `404` if the notification is not part of this deployment.


# List scheduled notifications
Source: https://docs.cube.dev/api-reference/notifications/list-scheduled-notifications

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/notifications

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Returns the deployment’s scheduled notifications (recurring dashboard runs), ordered by creation time (newest first) and cursor-paginated. Optionally filter to a single dashboard with either `dashboardId` (numeric) or `dashboardPublicId` (string), and/or to the notifications a single recipient receives — a user (`recipientUserId` or `recipientEmail`) or an embed user (`recipientEmbedTenantName` + `recipientExternalId`). At most one identifier per dashboard/recipient dimension. Each item describes the schedule only; recipients are managed through the `/recipients` sub-resource.


# Remove notification recipients
Source: https://docs.cube.dev/api-reference/notifications/remove-notification-recipients

/api-reference/api.yaml delete /api/v1/deployments/{deploymentId}/notifications/{id}/recipients

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Unsubscribes one or more recipients (1–1000 per request) from a notification. Each entry is identified by `type` plus the `id` returned by the API — `userId` for `USER`, `embedUserId` for `EMBED_USER`, or `channelId` for `SLACK`. `EMBED_USER` entries must also include `embedTenantName`, which locates the recipient’s storage partition. Removals are idempotent (deleting a recipient that isn’t subscribed is a no-op). Returns `204 No Content`, or `404` if the notification is not part of this deployment.


# Update a scheduled notification
Source: https://docs.cube.dev/api-reference/notifications/update-a-scheduled-notification

/api-reference/api.yaml put /api/v1/deployments/{deploymentId}/notifications/{id}

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Updates a notification’s schedule definition. Any subset of the schedule fields may be supplied (`scheduleType` + time fields or `customCron`, `timezone`), along with `isEnabled`, `notificationEnabled`, and `notificationFormat`. Omitted fields are left unchanged. This endpoint never modifies recipients — manage those through the `/recipients` sub-resource. Returns `404` if the notification is not part of this deployment.


# Create OAuth integration
Source: https://docs.cube.dev/api-reference/oauth-integrations/create-oauth-integration

/api-reference/api.yaml post /api/v1/oauth-integrations



# Delete OAuth integration
Source: https://docs.cube.dev/api-reference/oauth-integrations/delete-oauth-integration

/api-reference/api.yaml delete /api/v1/oauth-integrations/{id}



# Get OAuth integration
Source: https://docs.cube.dev/api-reference/oauth-integrations/get-oauth-integration

/api-reference/api.yaml get /api/v1/oauth-integrations/{id}



# List OAuth integrations
Source: https://docs.cube.dev/api-reference/oauth-integrations/list-oauth-integrations

/api-reference/api.yaml get /api/v1/oauth-integrations



# Update OAuth integration
Source: https://docs.cube.dev/api-reference/oauth-integrations/update-oauth-integration

/api-reference/api.yaml put /api/v1/oauth-integrations/{id}



# Create OIDC token config
Source: https://docs.cube.dev/api-reference/oidc-token-configs/create-oidc-token-config

/api-reference/api.yaml post /api/v1/oidc-token-configs



# Delete OIDC token config
Source: https://docs.cube.dev/api-reference/oidc-token-configs/delete-oidc-token-config

/api-reference/api.yaml delete /api/v1/oidc-token-configs/{id}



# Get OIDC token config
Source: https://docs.cube.dev/api-reference/oidc-token-configs/get-oidc-token-config

/api-reference/api.yaml get /api/v1/oidc-token-configs/{id}



# List OIDC token configs
Source: https://docs.cube.dev/api-reference/oidc-token-configs/list-oidc-token-configs

/api-reference/api.yaml get /api/v1/oidc-token-configs



# Update OIDC token config
Source: https://docs.cube.dev/api-reference/oidc-token-configs/update-oidc-token-config

/api-reference/api.yaml put /api/v1/oidc-token-configs/{id}



# Get the OpenAPI specification
Source: https://docs.cube.dev/api-reference/openapi-spec/get-the-openapi-specification

/api-reference/api.yaml get /api/v1/spec

The full OpenAPI 3.1 document for this API, as served by the build handling the request — every path, parameter, request body and schema. Intended for runtime discovery by clients and agents; `cube spec` wraps it with filtering.


# List regions
Source: https://docs.cube.dev/api-reference/regions/list-regions

/api-reference/api.yaml get /api/v1/regions

Lists the regions available to the account, cursor-paginated via `first`/`after`. The legacy `data` field returns the full, unpaginated list and is deprecated — use `items` + `pageInfo` instead.


# Connect a report to the calling spreadsheet
Source: https://docs.cube.dev/api-reference/reports/connect-a-report-to-the-calling-spreadsheet

/api-reference/api.yaml put /api/v1/deployments/{deploymentId}/reports/{reportId}/connect-workbook

Link a report to the caller's own spreadsheet by recording its placement
(workbook id + result location) so the add-in can list and refresh it there.

This upserts only the placement for the given workbook and never changes the
report's query, name, or other definition — so, like refresh, it requires only
read access to the report. A user who can view a report can place its data into
their own sheet without being its creator or having edit rights.


# Create a report
Source: https://docs.cube.dev/api-reference/reports/create-a-report

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/reports

Create a report in a deployment.

You may supply your own `publicId` (a 12-character `[0-9A-Za-z]` id) to key the report for as-code management; omit it to have one generated. It must be an id you chose — the auto-generated placeholder ids shown for reports that have no stable id yet are a reserved, non-unique shape and are rejected with `400`.


# Create or update a report by publicId
Source: https://docs.cube.dev/api-reference/reports/create-or-update-a-report-by-publicid

/api-reference/api.yaml put /api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId}

Idempotent create-or-update ("upsert") of a report keyed by its portable `publicId` — the stable identity for managing dashboards as code (CI/CD pipelines re-applying the same definition against any environment).

If a report with this `publicId` exists in the deployment, it is updated with the fields you send (same semantics as `PUT /reports/:reportId`); otherwise a new report is created with this `publicId`. Re-applying the same request is a no-op. The `publicId` must be a 12-character alphanumeric id (`[0-9A-Za-z]`); mint one client-side when authoring the definition.

This endpoint returns `409` for three different reasons, distinguished by the response body's `code` — handle them differently:

* **No `code`** — the `publicId` already belongs to a report in a **different** deployment. Because `publicId` is unique across the account, it is rejected rather than silently updating across deployments (reported regardless of whether you have access to that report). This is **permanent**: retrying will not help; use a different `publicId`.
* **`code: "upsert_branch_changed"`** — whether this request creates or updates is decided, and access-checked, before it is applied; another writer changed that in between (created or deleted the report with this `publicId`). The request was rejected rather than applied under the wrong permission check. This is **transient: retry the request**. It only happens when two writers target the same `publicId` concurrently, e.g. two pipeline runs applying the same bundle at once.
* **`code: "ambiguous_legacy_id"`** — the id given is one of the ids synthesized for reports that predate stable ids (see below), and it matches more than one of them, so it cannot identify a single report. Nothing was changed. This is **permanent**, and the fix is different from the case above: assign the report you mean a `publicId` of your own with `PUT /deployments/{deploymentId}/reports/{reportId}`, then key on that.

**Reports created before stable ids** do not store a `publicId`; the API synthesizes one for them from the report's internal id. Those synthesized ids are **not unique** — several reports can share one, and in practice most do. This endpoint resolves such an id only when it is unambiguous, adopting it as the report's real `publicId` at that point; otherwise it returns the `ambiguous_legacy_id` conflict above.

For anything you intend to manage as code, do not rely on a synthesized id: give the report a `publicId` you chose. `PUT /deployments/{deploymentId}/reports/{reportId}` accepts `publicId` for exactly this, on any report that does not have one yet (it is write-once — a report's existing `publicId` cannot be changed, since clients may already have stored it).

`source` is **create-only**: it is recorded when the report is first created and ignored on subsequent updates (it describes where the report originated, not its current definition).

Access: updating requires **edit** access to the existing report; creating requires the same access as `POST /reports`.


# Delete report
Source: https://docs.cube.dev/api-reference/reports/delete-report

/api-reference/api.yaml delete /api/v1/deployments/{deploymentId}/reports/{reportId}



# Disconnect a report from one spot in a spreadsheet
Source: https://docs.cube.dev/api-reference/reports/disconnect-a-report-from-one-spot-in-a-spreadsheet

/api-reference/api.yaml delete /api/v1/deployments/{deploymentId}/reports/{reportId}/connect-workbook

Remove a single placement of a report — one sheet + anchor in one
spreadsheet — leaving every other placement, in this workbook and in others, alone.

Address the placement by `placementId`, or (for placements recorded before ids
existed) by `externalWorkbookId` plus `sheetName` and `anchorCell` — or a
`resultLocation` naming both. Neither the sheet name nor the anchor is optional in
that form: matching is by sheet + anchor, and a target missing either addresses
nothing.

`sheetId` is an optional extra, not a substitute for `sheetName`: a placement
written before that field existed has only a name, and no id the server could
resolve to it, so an id-only address would match nothing while looking correct.

Send a `sheetId` only when you know it is the one the placement was stored with.
It NARROWS the target — a placement recorded under a different id is not matched,
even when the sheet name and anchor agree, because the stored name may belong to a
tab that has since been renamed and the id is the only stable identity. If your id
may have moved on (a tab deleted and recreated under the same name reports a new
one), address the placement by `placementId`, or by sheet name with no
`sheetId` at all.

A target that matches no placement succeeds and changes nothing, so retrying is
safe.

Like connecting, this records nothing about the report's definition and so requires
only read access: unplacing a report from your own sheet is not an edit to the report.


# Get report
Source: https://docs.cube.dev/api-reference/reports/get-report

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/reports/{reportId}



# List reports
Source: https://docs.cube.dev/api-reference/reports/list-reports

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/reports

List the reports in a deployment, scoped to the reports the calling user can access.

Results are returned in pages using cursor-based pagination: pass `first` to set the page size and `after` (the previous response's `pageInfo.endCursor`) to fetch the next page.

Cursor pagination is not supported when sorting by `lastViewedAt` (a per-viewer sort with no stable cursor column).


# Refresh report
Source: https://docs.cube.dev/api-reference/reports/refresh-report

/api-reference/api.yaml put /api/v1/deployments/{deploymentId}/reports/{reportId}/refresh



# Update a report
Source: https://docs.cube.dev/api-reference/reports/update-a-report

/api-reference/api.yaml put /api/v1/deployments/{deploymentId}/reports/{reportId}

Update a report. All fields are optional; only the fields you send are changed.

`publicId` is **write-once**: you may assign one to a report that does not have one yet — which is how a report created before stable ids is adopted into as-code management, so `PUT /reports/by-public-id/{publicId}` can key on it — but a report's existing `publicId` cannot be changed, since clients may already have stored it. Attempting to change it returns `400`; a `publicId` already used by another report returns `409`.

The id you assign must be one you chose (any distinct 12-character `[0-9A-Za-z]` id). The auto-generated placeholder id shown for a report that has no stable id yet cannot be assigned — it is not unique — and is rejected with `400`.

Requires **edit** access to the report.


# Create group
Source: https://docs.cube.dev/api-reference/scim-groups/create-group

/api-reference/scim.yaml post /scim/v2/Groups
Provisions a new group.



# Delete group
Source: https://docs.cube.dev/api-reference/scim-groups/delete-group

/api-reference/scim.yaml delete /scim/v2/Groups/{id}
Deletes a group by its SCIM `id`. Member users are not deleted.



# Get group
Source: https://docs.cube.dev/api-reference/scim-groups/get-group

/api-reference/scim.yaml get /scim/v2/Groups/{id}
Returns a single group by its SCIM `id`.



# List groups
Source: https://docs.cube.dev/api-reference/scim-groups/list-groups

/api-reference/scim.yaml get /scim/v2/Groups
Returns a paginated ListResponse of groups.



# Patch group
Source: https://docs.cube.dev/api-reference/scim-groups/patch-group

/api-reference/scim.yaml patch /scim/v2/Groups/{id}
Applies a partial update to a group using a SCIM PatchOp. Commonly used
to add or remove members without resending the entire membership list.




# Replace group
Source: https://docs.cube.dev/api-reference/scim-groups/replace-group

/api-reference/scim.yaml put /scim/v2/Groups/{id}
Replaces all attributes of an existing group, including its full membership list.



# Create user
Source: https://docs.cube.dev/api-reference/scim-users/create-user

/api-reference/scim.yaml post /scim/v2/Users
Provisions a new user.



# Delete user
Source: https://docs.cube.dev/api-reference/scim-users/delete-user

/api-reference/scim.yaml delete /scim/v2/Users/{id}
De-provisions (deletes) a user by their SCIM `id`.



# Get user
Source: https://docs.cube.dev/api-reference/scim-users/get-user

/api-reference/scim.yaml get /scim/v2/Users/{id}
Returns a single user by their SCIM `id`.



# List users
Source: https://docs.cube.dev/api-reference/scim-users/list-users

/api-reference/scim.yaml get /scim/v2/Users
Returns a paginated [ListResponse](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2)
of users. Use the `filter` parameter to look a user up by `userName`,
for example `userName eq "jane@example.com"`.




# Patch user
Source: https://docs.cube.dev/api-reference/scim-users/patch-user

/api-reference/scim.yaml patch /scim/v2/Users/{id}
Applies a partial update to a user using a SCIM
[PatchOp](https://datatracker.ietf.org/doc/html/rfc7644#section-3.5.2).
Commonly used to deactivate a user by setting `active` to `false`.




# Replace user
Source: https://docs.cube.dev/api-reference/scim-users/replace-user

/api-reference/scim.yaml put /scim/v2/Users/{id}
Replaces all attributes of an existing user with the supplied representation.



# Get tenant settings
Source: https://docs.cube.dev/api-reference/tenant-settings/get-tenant-settings

/api-reference/api.yaml get /api/v1/tenant/settings



# Update tenant settings
Source: https://docs.cube.dev/api-reference/tenant-settings/update-tenant-settings

/api-reference/api.yaml put /api/v1/tenant/settings



# Issue a Cube API token for Usage Analytics
Source: https://docs.cube.dev/api-reference/usage-analytics/issue-a-cube-api-token-for-usage-analytics

/api-reference/api.yaml post /api/v1/usage-analytics/token

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Issues a short-lived Cube API token for Cube's internal **Usage Analytics** deployment — the data shown on **Admin → Usage Analytics** — so you can query your own usage and billing data programmatically (REST API, BI tools, scripts) instead of only through the embedded page.

The token is scoped to your account: it carries the same server-resolved security context as the embedded Usage Analytics page, so queries only ever see your own data. Send it as `Authorization: Bearer <token>` on requests to the returned `apiUrl` (the deployment's [Cube REST API](https://cube.dev/docs/product/apis-integrations/rest-api)).

Tokens expire after 1 hour (see `expiresAt`). Issue a fresh one per session or scheduled refresh — issuing is idempotent and cheap.

Requires Usage Analytics to be enabled for the account, otherwise `404` is returned.


# Get user attribute values
Source: https://docs.cube.dev/api-reference/user-attribute-values/get-user-attribute-values

/api-reference/api.yaml get /api/v1/user-attribute-values/{userId}



# Upsert user attribute value
Source: https://docs.cube.dev/api-reference/user-attribute-values/upsert-user-attribute-value

/api-reference/api.yaml post /api/v1/user-attribute-values



# Create user attribute
Source: https://docs.cube.dev/api-reference/user-attributes/create-user-attribute

/api-reference/api.yaml post /api/v1/user-attributes



# Get user attributes
Source: https://docs.cube.dev/api-reference/user-attributes/get-user-attributes

/api-reference/api.yaml get /api/v1/user-attributes

List user attributes, newest first, cursor-paginated via `first`/`after`. The legacy `offset`/`limit` query params and the `data`/`count` response fields are deprecated — use `items` + `pageInfo` instead.


# Update user attribute
Source: https://docs.cube.dev/api-reference/user-attributes/update-user-attribute

/api-reference/api.yaml put /api/v1/user-attributes/{id}



# Get user OAuth token
Source: https://docs.cube.dev/api-reference/user-oauth-tokens/get-user-oauth-token

/api-reference/api.yaml get /api/v1/user-oauth-tokens/{integrationId}



# Initiate OAuth flow
Source: https://docs.cube.dev/api-reference/user-oauth-tokens/initiate-oauth-flow

/api-reference/api.yaml post /api/v1/user-oauth-tokens/{integrationId}/initiate



# List user OAuth tokens
Source: https://docs.cube.dev/api-reference/user-oauth-tokens/list-user-oauth-tokens

/api-reference/api.yaml get /api/v1/user-oauth-tokens



# Revoke user OAuth token
Source: https://docs.cube.dev/api-reference/user-oauth-tokens/revoke-user-oauth-token

/api-reference/api.yaml delete /api/v1/user-oauth-tokens/{integrationId}



# Apply an action to many users
Source: https://docs.cube.dev/api-reference/users-admin/apply-an-action-to-many-users

/api-reference/api.yaml post /api/v1/users/bulk

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Apply one action to up to 100 users in a single request.

Request body:

* `action` — `DEACTIVATE` (revoke access and end the users' sessions), `ACTIVATE` (restore access to deactivated users), or `DELETE` (remove the users outright).
* `userIds` — the users to act on. Repeated ids are collapsed, so the response holds exactly one entry per distinct user requested.

**This endpoint is partially successful.** It returns `200` whenever the request itself is well formed, and reports each user's outcome separately:

* `succeeded` — ids of the users the action was applied to.
* `failed` — the users it was not applied to, each with an `error` carrying the `status` and `message` the single-user endpoint would have returned (`404` for an unknown id, `403` when a guard refuses the change).

An empty `failed` array means the whole batch applied. Users are processed one at a time in the order given, each in its own transaction, so earlier changes are **not** rolled back when a later user fails — the response is the record of what was applied.

Every guard of the single-user endpoints still applies, per user:

* The caller's own id fails rather than the request: `DEACTIVATE` on self is `403`, `DELETE` on self is `400`.
* A tenant must always keep at least one active, direct admin, so the action that would remove the last one fails with `403` while the rest of the batch still applies.

Reapplying an action a user is already in (deactivating a deactivated user) succeeds as a no-op.


# Create user
Source: https://docs.cube.dev/api-reference/users-admin/create-user

/api-reference/api.yaml post /api/v1/users



# Delete user
Source: https://docs.cube.dev/api-reference/users-admin/delete-user

/api-reference/api.yaml delete /api/v1/users/{id}



# Update user
Source: https://docs.cube.dev/api-reference/users-admin/update-user

/api-reference/api.yaml put /api/v1/users/{id}



# Update my settings
Source: https://docs.cube.dev/api-reference/users/update-my-settings

/api-reference/api.yaml patch /api/v1/users/me/settings

Merge a partial patch into the authenticated user's own settings. Omitted fields are left as they are; `sheets` merges field-by-field, and an explicit `null` clears it.


# Clone a workbook
Source: https://docs.cube.dev/api-reference/workbooks/clone-a-workbook

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/workbooks/{workbookId}/duplicate

Create a full copy of a workbook, including its reports and its published dashboard, and return the new workbook.

The clone is named "Copy of \{original name}". All report references inside the dashboard (and the dashboard draft) are re-pointed at the copied reports, so the duplicate is fully self-contained and independent of the original. Per-user view history (last-viewed timestamps) is **not** carried over.

The clone does **not** inherit the source's sharing: no user or group policies are copied, and signed embedding (`allowEmbed`) starts disabled on the cloned dashboard even when it is enabled on the source.

Placement follows the caller's access to the source's folder. With **edit** access to that folder the clone (and its reports) is created alongside the original, and therefore inherits the access that folder grants. With only **read** access — or when the source is at the root — the clone is created at the workspace root instead, so a viewer never writes into a folder they don't control.

Requires **read** access to the source workbook and the **AI BI User** role (or higher). The new workbook is owned by the calling user.

Creator-mode embed sessions can also clone a workbook from the **shared workspace** (the items listed by `GET /shared-workspace`) by passing `{ "shared": true }` in the request body — `workbookId` is then resolved against the shared workspace instead of the caller's own. Such a clone is built from the workbook's **published dashboard**: a fresh report is created per report snapshot, the dashboard is re-published onto the new workbook, and the same config seeds the workbook's draft — the source's live reports and unpublished draft are not copied. The clone is placed at the workspace root. Requires the workbook to have a published dashboard (`400` otherwise); `403` for non-creator-mode callers.

If the deployment's plan enforces a workbook limit and it has been reached, the request is rejected with `400`. Returns `404` if the workbook does not exist or belongs to a different deployment.


# Create or update a workbook by slug
Source: https://docs.cube.dev/api-reference/workbooks/create-or-update-a-workbook-by-slug

/api-reference/api.yaml put /api/v1/deployments/{deploymentId}/workbooks/by-slug/{slug}

Idempotent create-or-update ("upsert") of a workbook keyed by its deployment-scoped slug — the portable identity for managing dashboards as code (CI/CD pipelines re-applying the same definition against any environment).

If a workbook with this slug exists in the deployment, it is updated: only the fields you send are changed, and `meta` is merged into the existing metadata (a `meta.dashboardDraft` is validated like everywhere else). Otherwise a new workbook is created with this slug. The slug is normalized (trimmed, lowercased) before matching. Re-applying the same request is a no-op.

Access: updating requires **edit** access to the workbook holding the slug (requests that include `folderId` require **manage** access, plus **edit** access to the destination folder); creating requires the same access as `POST /workbooks` (AI BI User role or higher).

Whether this request creates or updates is decided — and access-checked — before it is applied. If another writer changes that in between (creates or deletes the workbook holding this slug), the request is rejected with `409` and `code: "upsert_branch_changed"` rather than applied under the wrong permission check. This is **transient: retry the request**. It only happens when two writers target the same slug concurrently — for example two pipeline runs applying the same bundle at once, where one creates the workbook and the other must then retry into the update path.

Returns `404` if the deployment does not exist.


# Create workbook
Source: https://docs.cube.dev/api-reference/workbooks/create-workbook

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/workbooks



# Delete workbook
Source: https://docs.cube.dev/api-reference/workbooks/delete-workbook

/api-reference/api.yaml delete /api/v1/deployments/{deploymentId}/workbooks/{workbookId}



# Get workbook
Source: https://docs.cube.dev/api-reference/workbooks/get-workbook

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/workbooks/{workbookId}



# Get workbooks
Source: https://docs.cube.dev/api-reference/workbooks/get-workbooks

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/workbooks



# Publish dashboard
Source: https://docs.cube.dev/api-reference/workbooks/publish-dashboard

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/workbooks/{workbookId}/publish



# Update a workbook
Source: https://docs.cube.dev/api-reference/workbooks/update-a-workbook

/api-reference/api.yaml put /api/v1/deployments/{deploymentId}/workbooks/{workbookId}

Update a workbook's properties. All fields are optional; only the fields you send are changed.

* `name` — rename the workbook.
* `meta` — replace the workbook's metadata object.
* `folderId` — move the workbook between folders. Set it to a folder id to move the workbook into that folder, or to `null` to move it back to the workspace root.

Access depends on what you change. Renaming or editing metadata requires **edit** access to the workbook. Moving the workbook (any request that includes `folderId`) requires **manage** access to the workbook, plus **edit** access to the destination folder when moving into one.

To move a workbook you can use either this endpoint or the unified `POST /workspace/move`. Returns `404` if the workbook does not exist or belongs to a different deployment.


# Update published dashboard AI widget thread
Source: https://docs.cube.dev/api-reference/workbooks/update-published-dashboard-ai-widget-thread

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/workbooks/{workbookId}/dashboard/ai-widget-thread



# Update workbook dashboard
Source: https://docs.cube.dev/api-reference/workbooks/update-workbook-dashboard

/api-reference/api.yaml put /api/v1/deployments/{deploymentId}/workbooks/{workbookId}/dashboard



# Delete workspace items in bulk
Source: https://docs.cube.dev/api-reference/workspace/delete-workspace-items-in-bulk

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/workspace/bulk-delete

Delete up to 100 workspace items — workbooks, reports, and folders, mixed freely — in a single request.

Request body:

* `items` — the items to delete, each `{ type, id }` with `type` one of `WORKBOOK`, `REPORT`, `FOLDER`. Repeated references to the same item are collapsed, so the response holds exactly one entry per distinct item requested.

**This endpoint is partially successful.** It returns `200` whenever the request itself is well formed, and reports each item's outcome separately:

* `deleted` — the `(type, id)` of each item that was deleted.
* `failed` — the items that were not deleted, each with the `(type, id)` requested and an `error` carrying the `status` and `message` the per-type delete endpoint would have returned for it (`403` when the caller lacks access, `404` when the item does not exist or belongs to another deployment, `400` when a folder still has sub-folders).

An empty `failed` array means the whole batch applied. Items are deleted one at a time in the order given, each in its own transaction, so **deletions are not rolled back** when a later item fails — the response is the record of what was applied. Deleting a folder does not delete the workbooks, dashboards, and reports directly inside it: they are detached and returned to the workspace root, matching `DELETE /folders/:folderId`.

Access is checked per item with the same rules as the per-type delete endpoints: **manage** access for a workbook or folder, and **edit** access plus the report-manage permission for a report.


# List shared workspace items
Source: https://docs.cube.dev/api-reference/workspace/list-shared-workspace-items

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/shared-workspace

List the workspace items (folders, workbooks, reports) that have been shared with embed users via the built-in "All embed users" group or the caller's per-embed-tenant `system:tenant:{embedTenantName}` group.

Unlike `GET /workspace`, this feed is not per-user: every valid embed caller from the same embed tenant sees the same set, scoped to what those groups have been granted. Owner identities are blanked out so they are not exposed to embed users.

Accepts the same `folderId`, `types`, `search`, sorting, and cursor-pagination parameters as `GET /workspace`. Folders reachable only because a nested item inside them was shared are surfaced as navigation, but their unshared siblings stay hidden.


# List workspace items
Source: https://docs.cube.dev/api-reference/workspace/list-workspace-items

/api-reference/api.yaml get /api/v1/deployments/{deploymentId}/workspace

List the items in a deployment's workspace — folders, workbooks, and reports — in a single unified, paginated feed.

By default this returns the items at the workspace root. Pass `folderId` to list the contents of a specific folder instead. Folders are always returned ahead of other item types so they render at the top of a listing.

Supported query parameters:

* `folderId` — list the contents of this folder (omit for the root).
* `types` — restrict the results to one or more item types (`FOLDER`, `WORKBOOK`, `REPORT`). Repeat the parameter to pass several.
* `search` — case-insensitive substring match on item names; searches across all folders, not just the current level.
* `orderByField` / `orderByDirection` — sort the non-folder items (e.g. by `name`, `updated_at`, `created_at`, or `viewer_last_viewed_at`).
* `first` / `after` — cursor-based pagination.

Results are scoped to the calling user: only items the user can access are returned.


# Move a workspace item
Source: https://docs.cube.dev/api-reference/workspace/move-a-workspace-item

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/workspace/move

Move any workspace item — a workbook, report, or folder — into a folder, in one unified endpoint. Returns the moved item.

Request body:

* `type` — the item type: `WORKBOOK`, `REPORT`, or `FOLDER`.
* `id` — the id of the item to move.
* `folderId` — the destination folder id, or `null` to move the item to the workspace root. For a folder, this becomes its new parent.

Access requirements depend on the item type and mirror the per-type rules:

* **Workbook** — manage access to the workbook, plus edit access to the destination folder when moving into one.
* **Report** — edit access to the report (with the report-manage permission).
* **Folder** — manage access to the folder being moved, plus manage or edit access to the destination parent folder.

Moving a folder into one of its own descendants, or exceeding the maximum folder depth, is rejected with `400`. Returns `404` if the item does not exist or belongs to a different deployment.


# Move workspace items in bulk
Source: https://docs.cube.dev/api-reference/workspace/move-workspace-items-in-bulk

/api-reference/api.yaml post /api/v1/deployments/{deploymentId}/workspace/bulk-move

Move up to 100 workspace items — workbooks, reports, and folders, mixed freely — into one destination folder in a single request.

Request body:

* `items` — the items to move, each `{ type, id }` with `type` one of `WORKBOOK`, `REPORT`, `FOLDER`. Repeated references to the same item are collapsed, so the response holds exactly one entry per distinct item requested.
* `folderId` — the destination folder id for the whole batch, or `null` to move the items to the workspace root. For a folder item this becomes its new parent.

**This endpoint is partially successful.** It returns `200` whenever the request itself is well formed, and reports each item's outcome separately:

* `moved` — the items that were moved, serialized exactly as `POST /workspace/move` returns them.
* `failed` — the items that were not moved, each with the `(type, id)` requested and an `error` carrying the `status` and `message` the single-item move would have returned for it (`403` when the caller lacks access, `404` when the item does not exist or belongs to another deployment, `400` for an invalid move such as a folder into its own descendant).

An empty `failed` array means the whole batch applied. Items are applied one at a time in the order given, each in its own transaction, so earlier moves are **not** rolled back when a later item fails — the response is the record of what was applied.

Access is checked per item with the same rules as the single-item move, so a batch mixing items the caller may and may not move applies the permitted ones and reports the rest.


# Architecture
Source: https://docs.cube.dev/cube-core/architecture

Learn about Cube Core's production deployment architecture, including API instances, refresh workers, and Cube Store.

A typical production deployment of Cube Core includes several components
working together. This page describes the architecture and how each
component fits in.

## Components

As shown in the diagram below, a typical production deployment of Cube includes
the following components:

* One or multiple API instances
* A Refresh Worker
* A Cube Store cluster

<div>
  <img alt="Deployment Overview" />
</div>

**API Instances** process incoming API requests and query either Cube Store for
pre-aggregated data or connected database(s) for raw data. The **Refresh
Worker** builds and refreshes pre-aggregations in the background. **Cube Store**
ingests pre-aggregations built by Refresh Worker and responds to queries from
API instances.

API instances and Refresh Workers can be configured via [environment
variables][ref-config-env] or the [`cube.js` configuration file][ref-config-js].
They also need access to the data model files. Cube Store clusters can be
configured via environment variables.

You can find an example Docker Compose configuration for a Cube deployment in
the platform-specific guide for \[Docker]\[ref-deploy-docker].

## API instances

API instances process incoming API requests and query either Cube Store for
pre-aggregated data or connected data sources for raw data. It is possible to
horizontally scale API instances and use a load balancer to balance incoming
requests between multiple API instances.

The [Cube Docker image][dh-cubejs] is used for API Instance.

API instances can be configured via environment variables or the `cube.js`
configuration file, and **must** have access to the data model files (as
specified by [`schema_path`][ref-conf-ref-schemapath].

## Refresh Worker

A Refresh Worker updates pre-aggregations and invalidates the in-memory cache in
the background. They also keep the refresh keys up-to-date for all data models
and pre-aggregations. Please note that the in-memory cache is just invalidated
but not populated by Refresh Worker. In-memory cache is populated lazily during
querying. On the other hand, pre-aggregations are eagerly populated and kept
up-to-date by Refresh Worker.

The [Cube Docker image][dh-cubejs] can be used for creating Refresh Workers; to
make the service act as a Refresh Worker, `CUBEJS_REFRESH_WORKER=true` should be
set in the environment variables.

## Cube Store

Cube Store is the purpose-built pre-aggregations storage for Cube.

Cube Store uses a distributed query engine architecture. In every Cube Store
cluster:

* a one or many [router nodes](#cube-store-router) handle incoming
  connections, manages database metadata, builds query plans, and orchestrates
  their execution
* multiple [worker nodes](#cube-store-worker) ingest warmed up data
  and execute queries in parallel
* a local or cloud-based blob storage keeps pre-aggregated data in columnar
  format

<div>
  <img alt="Cube Store Router with two Cube Store Workers" />
</div>

By default, Cube Store listens on the port `3030` for queries coming from Cube.
The port could be changed by setting `CUBESTORE_HTTP_PORT` environment variable.
In a case of using custom port, please make sure to change
[`CUBEJS_CUBESTORE_PORT`](/reference/configuration/environment-variables#cubejs_cubestore_port) environment variable for Cube API Instances and Refresh
Worker.

Both the router and worker use the [Cube Store Docker image][dh-cubestore]. The
following environment variables should be used to manage the roles:

| Environment Variable    | Specify on Router? | Specify on Worker? |
| ----------------------- | ------------------ | ------------------ |
| `CUBESTORE_SERVER_NAME` | ✅ Yes              | ✅ Yes              |
| `CUBESTORE_META_PORT`   | ✅ Yes              | —                  |
| `CUBESTORE_WORKERS`     | ✅ Yes              | ✅ Yes              |
| `CUBESTORE_WORKER_PORT` | —                  | ✅ Yes              |
| `CUBESTORE_META_ADDR`   | —                  | ✅ Yes              |

<Info>
  Looking for a deeper dive on Cube Store architecture? Check out
  [this presentation](https://docs.google.com/presentation/d/1oQ-koloag0UcL-bUHOpBXK4txpqiGl41rxhgDVrw7gw/)
  by our CTO, [Pavel][gh-pavel].
</Info>

### Cube Store Router

<div>
  <img alt="Cube Store Router with two Cube Store Workers" />
</div>

The Router in a Cube Store cluster is responsible for receiving queries from
Cube, managing metadata for the Cube Store cluster, and query planning and
distribution for the Workers. It also [provides a MySQL-compatible
interface][ref-caching-inspect-sql] that can be used to query pre-aggregations
from Cube Store directly. Cube **only** communicates with the Router, and does
not interact with Workers directly.

[ref-caching-inspect-sql]: /docs/pre-aggregations/using-pre-aggregations#inspecting-pre-aggregations

### Cube Store Worker

<div>
  <img alt="Cube Store Router with two Cube Store Workers" />
</div>

Workers in a Cube Store cluster receive and execute subqueries from the Router,
and directly interact with the underlying distributed storage for insertions,
selections and pre-aggregation warmup. Workers **do not** interact with each
other directly, and instead rely on the Router to distribute queries and manage
any associated metadata.

### Scaling

Although Cube Store *can* be run in single-instance mode, this is often
unsuitable for production deployments. For high concurrency and data throughput,
we **strongly** recommend running Cube Store as a cluster of multiple instances
instead. Because the storage layer is decoupled from the query processing
engine, you can horizontally scale your Cube Store cluster for as much
concurrency as you require.

A sample Docker Compose stack setting Cube Store cluster up might look like:

```yaml theme={"dark"}
services:
  cubestore_router:
    image: cubejs/cubestore:latest
    environment:
      - CUBESTORE_WORKERS=cubestore_worker_1:10001,cubestore_worker_2:10002
      - CUBESTORE_REMOTE_DIR=/cube/data
      - CUBESTORE_META_PORT=9999
      - CUBESTORE_SERVER_NAME=cubestore_router:9999
    volumes:
      - .cubestore:/cube/data
    depends_on:
      - cubestore_worker_1
      - cubestore_worker_2

  cubestore_worker_1:
    image: cubejs/cubestore:latest
    environment:
      - CUBESTORE_WORKERS=cubestore_worker_1:10001,cubestore_worker_2:10002
      - CUBESTORE_SERVER_NAME=cubestore_worker_1:10001
      - CUBESTORE_WORKER_PORT=10001
      - CUBESTORE_REMOTE_DIR=/cube/data
      - CUBESTORE_META_ADDR=cubestore_router:9999
    volumes:
      - .cubestore:/cube/data

  cubestore_worker_2:
    image: cubejs/cubestore:latest
    environment:
      - CUBESTORE_WORKERS=cubestore_worker_1:10001,cubestore_worker_2:10002
      - CUBESTORE_SERVER_NAME=cubestore_worker_2:10002
      - CUBESTORE_WORKER_PORT=10002
      - CUBESTORE_REMOTE_DIR=/cube/data
      - CUBESTORE_META_ADDR=cubestore_router:9999
    volumes:
      - .cubestore:/cube/data
```

### Storage

Cube Store makes use of a separate storage layer for storing metadata as well as
for persisting pre-aggregations as Parquet files. Cube Store can use both AWS S3
and Google Cloud, or if desired, a local path on the server if all nodes of a
cluster run on a single machine.

A simplified example using AWS S3 might look like:

```yaml theme={"dark"}
services:
  cubestore_router:
    image: cubejs/cubestore:latest
    environment:
      - CUBESTORE_SERVER_NAME=cubestore_router:9999
      - CUBESTORE_META_PORT=9999
      - CUBESTORE_WORKERS=cubestore_worker_1:9001
      - CUBESTORE_S3_BUCKET=<BUCKET_NAME_IN_S3>
      - CUBESTORE_S3_REGION=<BUCKET_REGION_IN_S3>
      - CUBESTORE_AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID>
      - CUBESTORE_AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY>
  cubestore_worker_1:
    image: cubejs/cubestore:latest
    environment:
      - CUBESTORE_SERVER_NAME=cubestore_worker_1:9001
      - CUBESTORE_WORKER_PORT=9001
      - CUBESTORE_META_ADDR=cubestore_router:9999
      - CUBESTORE_WORKERS=cubestore_worker_1:9001
      - CUBESTORE_S3_BUCKET=<BUCKET_NAME_IN_S3>
      - CUBESTORE_S3_REGION=<BUCKET_REGION_IN_S3>
      - CUBESTORE_AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID>
      - CUBESTORE_AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY>
    depends_on:
      - cubestore_router
```

Instead of static access keys, Cube Store can authenticate to S3 using AWS Web
Identity (for example, IRSA on Amazon EKS). Leave `CUBESTORE_AWS_ACCESS_KEY_ID`
unset and provide
[`CUBESTORE_AWS_WEB_IDENTITY_TOKEN_FILE`][ref-config-env-cubestore-web-identity]
and [`CUBESTORE_AWS_ROLE_ARN`][ref-config-env]; Cube Store then assumes the role
via STS and refreshes credentials automatically when the token file changes.

[dh-cubejs]: https://hub.docker.com/r/cubejs/cube

[dh-cubestore]: https://hub.docker.com/r/cubejs/cubestore

[ref-config-env]: /reference/configuration/environment-variables

[ref-config-env-cubestore-web-identity]: /reference/configuration/environment-variables#cubestore_aws_web_identity_token_file

[ref-config-js]: /reference/configuration/config

[ref-conf-ref-schemapath]: /reference/configuration/config#schema_path

[gh-pavel]: https://github.com/paveltiunov


# Deploying Cube Core with Docker
Source: https://docs.cube.dev/cube-core/deployment

This guide walks you through deploying Cube with Docker.

<Warning>
  This is an example of a production-ready deployment, but real-world deployments
  can vary significantly depending on desired performance and scale.
</Warning>

<Info>
  If you'd like to deploy Cube to [Kubernetes](https://kubernetes.io), please
  refer to the following resources with Helm charts:
  [`gadsme/charts`](https://github.com/gadsme/charts) or
  [`OpstimizeIcarus/cubejs-helm-charts-kubernetes`](https://github.com/OpstimizeIcarus/cubejs-helm-charts-kubernetes/tree/release-v0.1).

  These resources are community-maintained, and they are not maintained by the
  Cube team. Please direct questions related to these resources to their authors.
</Info>

## Prerequisites

* [Docker Desktop][link-docker-app]

## Configuration

Create a Docker Compose stack by creating a `docker-compose.yml`. A
production-ready stack would at minimum consist of:

* One or more Cube API instance
* A Cube Refresh Worker
* A Cube Store Router node
* One or more Cube Store Worker nodes

An example stack using BigQuery as a data source is provided below:

<Info>
  **Using macOS or Windows?** Use `CUBEJS_DB_HOST=host.docker.internal` instead of
  `localhost` if your database is on the same machine.
</Info>

<Info>
  **Using macOS on Apple Silicon (arm64)?** Use the `arm64v8` tag for Cube Store
  [Docker images](https://hub.docker.com/r/cubejs/cubestore/tags?page=\&page_size=\&ordering=\&name=arm64v8),
  e.g., `cubejs/cubestore:arm64v8`.
</Info>

<Info>
  Note that it's a best practice to use specific locked versions, e.g.,
  `cubejs/cube:v0.36.0`, instead of `cubejs/cube:latest` in production.
</Info>

```yaml theme={"dark"}
services:
  cube_api:
    restart: always
    image: cubejs/cube:latest
    ports:
      - 4000:4000
    environment:
      - CUBEJS_DB_TYPE=bigquery
      - CUBEJS_DB_BQ_PROJECT_ID=cube-bq-cluster
      - CUBEJS_DB_BQ_CREDENTIALS=<BQ-KEY>
      - CUBEJS_DB_EXPORT_BUCKET=cubestore
      - CUBEJS_CUBESTORE_HOST=cubestore_router
      - CUBEJS_API_SECRET=secret
    volumes:
      - .:/cube/conf
    depends_on:
      - cube_refresh_worker
      - cubestore_router
      - cubestore_worker_1
      - cubestore_worker_2

  cube_refresh_worker:
    restart: always
    image: cubejs/cube:latest
    environment:
      - CUBEJS_DB_TYPE=bigquery
      - CUBEJS_DB_BQ_PROJECT_ID=cube-bq-cluster
      - CUBEJS_DB_BQ_CREDENTIALS=<BQ-KEY>
      - CUBEJS_DB_EXPORT_BUCKET=cubestore
      - CUBEJS_CUBESTORE_HOST=cubestore_router
      - CUBEJS_API_SECRET=secret
      - CUBEJS_REFRESH_WORKER=true
    volumes:
      - .:/cube/conf

  cubestore_router:
    restart: always
    image: cubejs/cubestore:latest
    environment:
      - CUBESTORE_WORKERS=cubestore_worker_1:10001,cubestore_worker_2:10002
      - CUBESTORE_REMOTE_DIR=/cube/data
      - CUBESTORE_META_PORT=9999
      - CUBESTORE_SERVER_NAME=cubestore_router:9999
    volumes:
      - .cubestore:/cube/data

  cubestore_worker_1:
    restart: always
    image: cubejs/cubestore:latest
    environment:
      - CUBESTORE_WORKERS=cubestore_worker_1:10001,cubestore_worker_2:10002
      - CUBESTORE_SERVER_NAME=cubestore_worker_1:10001
      - CUBESTORE_WORKER_PORT=10001
      - CUBESTORE_REMOTE_DIR=/cube/data
      - CUBESTORE_META_ADDR=cubestore_router:9999
    volumes:
      - .cubestore:/cube/data
    depends_on:
      - cubestore_router

  cubestore_worker_2:
    restart: always
    image: cubejs/cubestore:latest
    environment:
      - CUBESTORE_WORKERS=cubestore_worker_1:10001,cubestore_worker_2:10002
      - CUBESTORE_SERVER_NAME=cubestore_worker_2:10002
      - CUBESTORE_WORKER_PORT=10002
      - CUBESTORE_REMOTE_DIR=/cube/data
      - CUBESTORE_META_ADDR=cubestore_router:9999
    volumes:
      - .cubestore:/cube/data
    depends_on:
      - cubestore_router
```

## Set up reverse proxy

In production, the Cube API should be served over an HTTPS connection to ensure
security of the data in-transit. We recommend using a reverse proxy; as an
example, let's use [NGINX][link-nginx].

<Info>
  You can also use a reverse proxy to enable HTTP 2.0 and GZIP compression
</Info>

First we'll create a new server configuration file called `nginx/cube.conf`:

```nginx theme={"dark"}
server {
  listen 443 ssl;
  server_name cube.my-domain.com;

  ssl_protocols               TLSv1 TLSv1.1 TLSv1.2;
  ssl_ecdh_curve              secp384r1;
  # Replace the ciphers with the appropriate values
  ssl_ciphers                 "ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384 OLD_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 OLD_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256";
  ssl_prefer_server_ciphers   on;
  ssl_certificate             /etc/ssl/private/cert.pem;
  ssl_certificate_key         /etc/ssl/private/key.pem;
  ssl_session_timeout         10m;
  ssl_session_cache           shared:SSL:10m;
  ssl_session_tickets         off;
  ssl_stapling                on;
  ssl_stapling_verify         on;

  location / {
    proxy_pass http://cube:4000/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
  }
}
```

Then we'll add a new service to our Docker Compose stack:

```yaml theme={"dark"}
services:
  ...
  nginx:
    image: nginx
    ports:
      - 443:443
    volumes:
      - ./nginx:/etc/nginx/conf.d
      - ./ssl:/etc/ssl/private
```

Don't forget to create a `ssl` directory with the `cert.pem` and `key.pem` files
inside so the Nginx service can find them.

For automatically provisioning SSL certificates with LetsEncrypt, [this blog
post][medium-letsencrypt-nginx] may be useful.

## Security

### Use JSON Web Tokens

Cube can be configured to use industry-standard JSON Web Key Sets for securing
its API and limiting access to data. To do this, we'll define the relevant
options on our Cube API instance:

<Warning>
  If you're using [`queryRewrite`][ref-config-queryrewrite] for access control,
  then you must also configure
  [`scheduledRefreshContexts`][ref-config-sched-ref-ctx] so the refresh workers
  can correctly create pre-aggregations.
</Warning>

```yaml theme={"dark"}
services:
  cube_api:
    image: cubejs/cube:latest
    ports:
      - 4000:4000
    environment:
      - CUBEJS_DB_TYPE=bigquery
      - CUBEJS_DB_BQ_PROJECT_ID=cube-bq-cluster
      - CUBEJS_DB_BQ_CREDENTIALS=<BQ-KEY>
      - CUBEJS_DB_EXPORT_BUCKET=cubestore
      - CUBEJS_CUBESTORE_HOST=cubestore_router
      - CUBEJS_API_SECRET=secret
      - CUBEJS_JWK_URL=https://cognito-idp.<AWS_REGION>.amazonaws.com/<USER_POOL_ID>/.well-known/jwks.json
      - CUBEJS_JWT_AUDIENCE=<APPLICATION_URL>
      - CUBEJS_JWT_ISSUER=https://cognito-idp.<AWS_REGION>.amazonaws.com/<USER_POOL_ID>
      - CUBEJS_JWT_ALGS=RS256
      - CUBEJS_JWT_CLAIMS_NAMESPACE=<CLAIMS_NAMESPACE>
    volumes:
      - .:/cube/conf
    depends_on:
      - cubestore_worker_1
      - cubestore_worker_2
      - cube_refresh_worker
```

### Securing Cube Store

All Cube Store nodes (both router and workers) should only be accessible to Cube
API instances and refresh workers. To do this with Docker Compose, we simply
need to make sure that none of the Cube Store services have any exposed

## Monitoring

All Cube logs can be found by through the Docker Compose CLI:

```bash theme={"dark"}
docker-compose ps

           Name                           Command               State                    Ports
---------------------------------------------------------------------------------------------------------------------------------
cluster_cube_1                 docker-entrypoint.sh cubej ...   Up      0.0.0.0:4000->4000/tcp,:::4000->4000/tcp
cluster_cubestore_router_1     ./cubestored                     Up      3030/tcp, 3306/tcp
cluster_cubestore_worker_1_1   ./cubestored                     Up      3306/tcp, 9001/tcp
cluster_cubestore_worker_2_1   ./cubestored                     Up      3306/tcp, 9001/tcp

docker-compose logs

cubestore_router_1    | 2021-06-02 15:03:20,915 INFO  [cubestore::metastore] Creating metastore from scratch in /cube/.cubestore/data/metastore
cubestore_router_1    | 2021-06-02 15:03:20,950 INFO  [cubestore::cluster] Meta store port open on 0.0.0.0:9999
cubestore_router_1    | 2021-06-02 15:03:20,951 INFO  [cubestore::mysql] MySQL port open on 0.0.0.0:3306
cubestore_router_1    | 2021-06-02 15:03:20,952 INFO  [cubestore::http] Http Server is listening on 0.0.0.0:3030
cube_1                | 🚀 Cube API server (vX.XX.XX) is listening on 4000
cubestore_worker_2_1  | 2021-06-02 15:03:24,945 INFO  [cubestore::cluster] Worker port open on 0.0.0.0:9001
cubestore_worker_1_1  | 2021-06-02 15:03:24,830 INFO  [cubestore::cluster] Worker port open on 0.0.0.0:9001
```

## Update to the latest version

Find the latest stable release version [from
Docker Hub][link-cubejs-docker]. Then update your `docker-compose.yml` to use
a specific tag instead of `latest`:

```yaml theme={"dark"}
services:
  cube_api:
    image: cubejs/cube:v0.36.0
    ports:
      - 4000:4000
    environment:
      - CUBEJS_DB_TYPE=bigquery
      - CUBEJS_DB_BQ_PROJECT_ID=cube-bq-cluster
      - CUBEJS_DB_BQ_CREDENTIALS=<BQ-KEY>
      - CUBEJS_DB_EXPORT_BUCKET=cubestore
      - CUBEJS_CUBESTORE_HOST=cubestore_router
      - CUBEJS_API_SECRET=secret
    volumes:
      - .:/cube/conf
    depends_on:
      - cubestore_router
      - cube_refresh_worker
```

## Extend the Docker image

If you need to use dependencies (i.e., Python or npm packages) with native
extensions inside [configuration files][ref-config-files] or [dynamic data
models][ref-dynamic-data-models], build a custom Docker image.

You can do this by creating a `Dockerfile` and a corresponding
`.dockerignore` file:

```bash theme={"dark"}
touch Dockerfile
touch .dockerignore
```

Add this to the `Dockerfile`:

```dockerfile theme={"dark"}
FROM cubejs/cube:latest

COPY . .
RUN apt update && apt install -y pip
RUN pip install -r requirements.txt
RUN npm install
```

And this to the `.dockerignore`:

```gitignore theme={"dark"}
model
cube.py
cube.js
.env
node_modules
npm-debug.log
```

Then start the build process by running the following command:

```bash theme={"dark"}
docker build -t <YOUR-USERNAME>/cube-custom-image .
```

Finally, update your `docker-compose.yml` to use your newly-built image:

```yaml theme={"dark"}
services:
  cube_api:
    image: <YOUR-USERNAME>/cube-custom-image
    ports:
      - 4000:4000
    environment:
      - CUBEJS_API_SECRET=secret
      # Other environment variables
    volumes:
      - .:/cube/conf
    depends_on:
      - cubestore_router
      - cube_refresh_worker
      # Other container dependencies
```

Note that you shoudn't mount the whole current folder (`.:/cube/conf`)
if you have dependencies in `package.json`. Doing so would effectively
hide the `node_modules` folder inside the container, where dependency files
installed with `npm install` reside, and result in errors like this:
`Error: Cannot find module 'my_dependency'`. In that case, mount individual files:

```yaml theme={"dark"}
    # ...
    volumes:
      - ./model:/cube/conf/model
      - ./cube.js:/cube/conf/cube.js
      # Other necessary files
```

## Production checklist

<Info>
  Thinking of migrating to the cloud instead? [Click
  here][blog-migrate-to-cube-cloud] to learn more about migrating a self-hosted
  installation to [Cube Cloud][link-cube-cloud].
</Info>

This is a checklist for configuring and securing Cube for a production
deployment.

### Disable Development Mode

When running Cube in production environments, make sure development mode is
disabled both on API Instances and Refresh Worker. You can read more about what
development mode changes [here][link-cubejs-dev-vs-prod].

<Warning>
  **Development mode is an authentication bypass.** Cube is in development mode when
  `CUBEJS_DEV_MODE=true`, and also whenever `NODE_ENV` is not `production`. When Cube
  is started through the `cubejs` CLI — which is what the official Docker images run —
  setting `CUBEJS_DEV_MODE=true` additionally forces `NODE_ENV=development`, which
  switches off JWT verification on the
  [REST (JSON)](/reference/core-data-apis/rest-api) and
  [GraphQL](/reference/core-data-apis/graphql-api) APIs: they then accept requests with
  no token at all.

  Development mode also mounts [Playground](/docs/explore-analyze/playground) and its
  supporting endpoints with no authentication whatsoever. Anyone who can reach the
  instance is handed a ready-to-use API token, and can mint further ones carrying any
  security context signed with your API secret — and so query every data API as any user,
  bypassing [member-level access
  control](/docs/data-modeling/access-control/member-level-security) and [row-level
  security](/docs/data-modeling/access-control/row-level-security). The same endpoints
  read your data model files and the table schema of every connected data source, and
  overwrite your data model and your `.env`. With `CUBEJS_DEV_MODE=true` and no
  [`CUBEJS_SQL_PASSWORD`](/reference/configuration/environment-variables#cubejs_sql_password)
  set, the SQL API accepts any credentials as well, allowing arbitrary SQL against
  connected data sources.

  This is intentional. Development mode is designed to run on a developer's local
  machine for ease of use and debugging. Never run it where anyone else can reach it,
  never expose it to the internet, and never use it in production. Using development
  mode in the Cube cloud platform is highly discouraged — it bypasses the platform's
  security model.

  To keep it off: `cubejs server` and the official Docker images already set
  `NODE_ENV=production`, so leaving `CUBEJS_DEV_MODE` unset — its default — is enough
  there. If you embed `@cubejs-backend/server-core` directly rather than starting Cube
  through the `cubejs` CLI, set `NODE_ENV=production` yourself, since an unset `NODE_ENV`
  puts the instance in development mode whatever the flag says.
</Warning>

<Info>
  `CUBEJS_DEV_MODE` defaults to `false`, and the official Docker images already set
  `NODE_ENV=production` — as does `cubejs server` itself — so on a Docker deployment
  leaving the flag unset is enough. Setting `NODE_ENV` below as well is belt-and-braces;
  it matters only if you embed `@cubejs-backend/server-core` directly, where an unset
  `NODE_ENV` puts the instance in development mode whatever the flag says.
</Info>

```dotenv theme={"dark"}
# Keep development mode off. Under the `cubejs` CLI and the official images,
# setting this to `true` also forces NODE_ENV=development, switching off JWT
# verification on the data APIs
CUBEJS_DEV_MODE=false

# Already set by the official images and by `cubejs server`; set it explicitly if
# you start Cube some other way
NODE_ENV=production
```

### Set up Refresh Worker

To refresh in-memory cache and [pre-aggregations][ref-schema-ref-preaggs] in the
background, we recommend running a separate Cube Refresh Worker instance. This
allows your Cube API Instance to continue to serve requests with high
availability.

```dotenv theme={"dark"}
# Set to true so a Cube instance acts as a refresh worker
CUBEJS_REFRESH_WORKER=true
```

### Set up Cube Store

<Warning>
  While Cube can operate with in-memory cache and queue storage, there're multiple
  parts of Cube which require Cube Store in production mode. Replicating Cube
  instances without Cube Store can lead to source database degraded performance,
  various race conditions and cached data inconsistencies.
</Warning>

Cube Store manages in-memory cache, queue and pre-aggregations for Cube. Follow
the [instructions here][ref-caching-cubestore] to set it up.

Depending on your database, Cube may need to "stage" pre-aggregations inside
your database first before ingesting them into Cube Store. In this case, Cube
will require write access to a dedicated schema inside your database.
The schema name is `prod_pre_aggregations` by default. It can be set using the
[`pre_aggregations_schema` configration option][ref-conf-preaggs-schema].

<Info>
  You may consider enabling an export bucket which allows Cube to build large
  pre-aggregations in a much faster manner. It is currently supported for
  BigQuery, Redshift, Snowflake, and some other data sources. Check [the relevant
  documentation for your configured database][ref-config-connect-db] to set it up.
</Info>

### Secure the deployment

If you're using JWTs, you can configure Cube to correctly decode them and inject
their contents into the [Security Context][ref-sec-ctx]. Add your authentication
provider's configuration under [the `jwt` property of your `cube.js`
configuration file][ref-config-jwt], or if using environment variables, see
`CUBEJS_JWK_*`, `CUBEJS_JWT_*` in the [Environment Variables
reference][ref-env-vars].

### Set up health checks

Cube provides [Kubernetes-API compatible][link-k8s-healthcheck-api] health check
(or probe) endpoints that indicate the status of the deployment. Configure your
monitoring service of choice to use the [`/readyz`][ref-api-readyz] and
[`/livez`][ref-api-livez] API endpoints so you can check on the Cube
deployment's health and be alerted to any issues.

### Appropriate cluster sizing

There's no one-size-fits-all when it comes to sizing a Cube cluster and its
resources. Resources required by Cube significantly depend on the amount of
traffic Cube needs to serve and the amount of data it needs to process. The
following sizing estimates are based on default settings and are very generic,
which may not fit your Cube use case, so you should always tweak resources based
on consumption patterns you see.

#### Memory and CPU

Each Cube cluster should contain at least 2 Cube API instances. Every Cube API
instance should have at least 3GB of RAM and 2 CPU cores allocated for it.

Refresh workers tend to be much more CPU and memory intensive, so at least 6GB
of RAM is recommended. Please note that to take advantage of all available RAM,
the Node.js heap size should be adjusted accordingly by using the
[`--max-old-space-size` option][node-heap-size]:

```sh theme={"dark"}
NODE_OPTIONS="--max-old-space-size=6144"
```

[node-heap-size]: https://nodejs.org/api/cli.html#--max-old-space-sizesize-in-megabytes

The Cube Store router node should have at least 6GB of RAM and 4 CPU cores
allocated for it. Every Cube Store worker node should have at least 8GB of RAM
and 4 CPU cores allocated for it. The Cube Store cluster should have at least
two worker nodes.

#### RPS and data volume

Depending on data model size, every Core Cube API instance can serve 1 to 10
requests per second. Every Core Cube Store router node can serve 50-100 queries
per second. As a rule of thumb, you should provision 1 Cube Store worker node
per one Cube Store partition or 1M of rows scanned in a query. For example if
your queries scan 16M of rows per query, you should have at least 16 Cube Store
worker nodes provisioned. Please note that the number of raw data rows doesn't
usually equal the number of rows in pre-aggregation. At the same time, queries
don't usually scan all the data in pre-aggregations, as Cube Store uses
partition pruning to optimize queries. `EXPLAIN ANALYZE` can be used to see
scanned partitions involved in a Cube Store query. Cube Cloud ballpark
performance numbers can differ as it has different Cube runtime.

### Optimize usage

<Note>
  See [this recipe][ref-data-store-cost-saving-guide] to learn how to optimize
  data source usage.
</Note>

[blog-migrate-to-cube-cloud]: https://cube.dev/blog/migrating-from-self-hosted-to-cube-cloud/

[link-cube-cloud]: https://cubecloud.dev

[link-cubejs-dev-vs-prod]: /reference/configuration/environment-variables#cubejs_dev_mode

[link-k8s-healthcheck-api]: https://kubernetes.io/docs/reference/using-api/health-checks/

[ref-config-connect-db]: /admin/connect-to-data/data-sources

[ref-caching-cubestore]: /docs/pre-aggregations/running-in-production

[ref-conf-preaggs-schema]: /reference/configuration/config#pre_aggregations_schema

[ref-env-vars]: /reference/configuration/environment-variables

[ref-schema-ref-preaggs]: /reference/data-modeling/pre-aggregations

[ref-sec-ctx]: /docs/data-modeling/access-control/context

[ref-config-jwt]: /reference/configuration/config#jwt

[ref-api-readyz]: /reference/core-data-apis/rest-api/reference#readyz

[ref-api-livez]: /reference/core-data-apis/rest-api/reference#livez

[ref-data-store-cost-saving-guide]: /recipes/configuration/data-store-cost-saving-guide

[medium-letsencrypt-nginx]: https://pentacent.medium.com/nginx-and-lets-encrypt-with-docker-in-less-than-5-minutes-b4b8a60d3a71

[link-cubejs-docker]: https://hub.docker.com/r/cubejs/cube

[link-docker-app]: https://www.docker.com/products/docker-app

[link-nginx]: https://www.nginx.com/

[ref-config-files]: /admin/connect-to-data#cubepy-and-cubejs-files

[ref-dynamic-data-models]: /docs/data-modeling/dynamic

[ref-config-queryrewrite]: /reference/configuration/config#queryrewrite

[ref-config-sched-ref-ctx]: /reference/configuration/config#scheduledrefreshcontexts


# Add a pre-aggregation
Source: https://docs.cube.dev/cube-core/getting-started/add-a-pre-aggregation

Hands-on walkthrough of accepting a Playground pre-aggregation suggestion, updating the data model, and rerunning an accelerated query.

In this step, we'll add a pre-aggregation to optimize the performance of a
specific query. Pre-aggregations are a caching technique that massively reduces
query time from seconds to milliseconds. They are extremely useful for speeding
up queries that are run frequently.

From the **Build** tab, execute a query:

<Frame>
  <img alt="Cube Developer Playground Screen showing query results" />
</Frame>

Just above the results, click on **Query was not accelerated with
pre-aggregation** to bring up the pre-aggregation suggestion:

<Frame>
  <img alt="Cube Developer Playground Screen showing pre-aggregation suggestion" />
</Frame>

A pre-aggregation will be automatically suggested for the query;
click **Add to the Data Model** and then retry the query in the
Playground. This time, the query should be accelerated with a pre-aggregation:

<Frame>
  <img alt="Cube Developer Playground Screen querying a pre-aggregation" />
</Frame>

And with that, we conclude our Getting Started with Cube guide. If you'd like to
learn more about Cube, [check out this page][next].

[next]: /cube-core/getting-started/learn-more


# Create a project
Source: https://docs.cube.dev/cube-core/getting-started/create-a-project

In this step, we will create a Cube Core project on your computer, connect a data source, and generate data models.

## Scaffold a project

Start by opening your terminal to create a new folder for the project, then
create a `docker-compose.yml` file within it:

```bash theme={"dark"}
mkdir my-first-cube-project
cd my-first-cube-project
touch docker-compose.yml
```

Open the `docker-compose.yml` file and add the following content:

```yaml theme={"dark"}
services:
  cube:
    image: cubejs/cube:latest
    ports:
      - 4000:4000
      - 15432:15432
    environment:
      - CUBEJS_DEV_MODE=true
    volumes:
      - .:/cube/conf
```

Note that we're setting the [`CUBEJS_DEV_MODE`](/reference/configuration/environment-variables#cubejs_dev_mode) environment variable to `true` to
enable [development mode](/reference/configuration/environment-variables#cubejs_dev_mode). This is
handy for local development but not suitable for
[production](/cube-core/running-in-production).

<Warning>
  **Development mode is an authentication bypass.** Cube is in development mode when
  `CUBEJS_DEV_MODE=true`, and also whenever `NODE_ENV` is not `production`. When Cube
  is started through the `cubejs` CLI — which is what the official Docker images run —
  setting `CUBEJS_DEV_MODE=true` additionally forces `NODE_ENV=development`, which
  switches off JWT verification on the
  [REST (JSON)](/reference/core-data-apis/rest-api) and
  [GraphQL](/reference/core-data-apis/graphql-api) APIs: they then accept requests with
  no token at all.

  Development mode also mounts [Playground](/docs/explore-analyze/playground) and its
  supporting endpoints with no authentication whatsoever. Anyone who can reach the
  instance is handed a ready-to-use API token, and can mint further ones carrying any
  security context signed with your API secret — and so query every data API as any user,
  bypassing [member-level access
  control](/docs/data-modeling/access-control/member-level-security) and [row-level
  security](/docs/data-modeling/access-control/row-level-security). The same endpoints
  read your data model files and the table schema of every connected data source, and
  overwrite your data model and your `.env`. With `CUBEJS_DEV_MODE=true` and no
  [`CUBEJS_SQL_PASSWORD`](/reference/configuration/environment-variables#cubejs_sql_password)
  set, the SQL API accepts any credentials as well, allowing arbitrary SQL against
  connected data sources.

  This is intentional. Development mode is designed to run on a developer's local
  machine for ease of use and debugging. Never run it where anyone else can reach it,
  never expose it to the internet, and never use it in production. Using development
  mode in the Cube cloud platform is highly discouraged — it bypasses the platform's
  security model.

  To keep it off: `cubejs server` and the official Docker images already set
  `NODE_ENV=production`, so leaving `CUBEJS_DEV_MODE` unset — its default — is enough
  there. If you embed `@cubejs-backend/server-core` directly rather than starting Cube
  through the `cubejs` CLI, set `NODE_ENV=production` yourself, since an unset `NODE_ENV`
  puts the instance in development mode whatever the flag says.
</Warning>

<Info>
  If you're using Linux as the Docker host OS, you'll also need to add
  `network_mode: 'host'` to your `docker-compose.yml`.
</Info>

## Start the development server

From the newly-created project directory, run the following command to start
Cube:

```bash theme={"dark"}
docker compose up -d
```

<Info>
  Using Windows? Remember to use [PowerShell][powershell-docs] or
  [WSL2][wsl2-docs] to run the command below.
</Info>

## Connect a data source

Head to [http://localhost:4000](http://localhost:4000) to open the [Developer
Playground][ref-devtools-playground].

The Playground has a database connection wizard that loads when Cube is first
started up and no `.env` file is found. After database credentials have been set
up, an `.env` file will automatically be created and populated with credentials.

<Frame>
  <img />
</Frame>

<Info>
  Want to use a sample database instead? Select **PostgreSQL** and use the
  credentials below:

  <br />

  | Field    | Value              |
  | -------- | ------------------ |
  | Host     | `demo-db.cube.dev` |
  | Port     | `5432`             |
  | Database | `ecom`             |
  | Username | `cube`             |
  | Password | `12345`            |
</Info>

After selecting the data source, enter valid credentials for it and
click **Apply**. Check the [Connecting to Databases][ref-conf-db] page
for more details on specific data sources.

<Frame>
  <img />
</Frame>

You should see tables available to you from the configured database; select the
`orders` table. After selecting the table, click **Generate Data Model**
and pick either **YAML** (recommended) or **JavaScript** format:

<Frame>
  <img />
</Frame>

Finally, click **Build** in the dialog, which should take you to
the **Build** page.

You're now ready for the next step, [querying the
data][ref-getting-started-core-query-cube].

[powershell-docs]: https://learn.microsoft.com/en-us/powershell/

[ref-conf-db]: /admin/connect-to-data/data-sources

[ref-getting-started-core-query-cube]: /cube-core/getting-started/query-data

[ref-devtools-playground]: /docs/explore-analyze/playground

[wsl2-docs]: https://learn.microsoft.com/en-us/windows/wsl/install


# Getting Started with Cube Core
Source: https://docs.cube.dev/cube-core/getting-started/index

Create a project, connect a database, query data, and add a pre-aggregation in self-hosted Cube Core.

Getting started with Cube Core

First, we'll create a new project, connect it to a database and generate a data
model from it. Then, we'll run queries using the Developer Playground and APIs.
Finally, we'll add a pre-aggregation to optimize query latency down to
milliseconds.

This guide will walk you through the following tasks:

* [Create a new project](/cube-core/getting-started/create-a-project)
* [Run queries using the Developer Playground and APIs](/cube-core/getting-started/query-data)
* [Add a pre-aggregation to optimize query performance](/cube-core/getting-started/add-a-pre-aggregation)

If you'd prefer to try Cube Cloud, then you can refer to [Getting Started using
Cube Cloud][ref-getting-started-cloud-overview] instead.

[ref-getting-started-cloud-overview]: /docs/getting-started/cloud


# Learn more
Source: https://docs.cube.dev/cube-core/getting-started/learn-more

Now that you've set up your first project, learn more about what else Cube can do for you.

## Data Modeling

Learn more about [data modeling](/docs/data-modeling/overview)
and how to effectively define metrics in your data models.

## Querying

Cube can be queried in a variety of ways. Explore how to use
[REST (JSON) API](/reference/core-data-apis/rest-api), [GraphQL API](/reference/core-data-apis/graphql-api), and
[SQL API](/reference/core-data-apis/sql-api), or how to
[connect a BI or data visualization tool](/admin/connect-to-data/visualization-tools).

## Caching

Learn more about the [two-level cache](/docs/pre-aggregations) and how
[pre-aggregations help speed up queries](/docs/pre-aggregations/getting-started-pre-aggregations).

## Access Control

Cube uses [JSON Web Tokens](https://jwt.io/) to
[authenticate requests for the HTTP APIs](/docs/data-modeling/access-control), and
[`check_sql_auth`](/reference/configuration/config#check_sql_auth) to
[authenticate requests for the SQL API](/reference/core-data-apis/sql-api/security).


# Query data
Source: https://docs.cube.dev/cube-core/getting-started/query-data

Surveys ways to explore and consume modeled data—Playground, APIs, client SDKs, and BI or app integrations—after cubes are defined.

In this step, you will learn how to query your data using the data models you
created in the previous step. Cube provides several ways to query your data, and
we'll go over them here.

## Playground

[Playground](/docs/explore-analyze/playground) is a web-based tool which allows for
model generation and data exploration. On the **Build** tab, you can
select the measures and dimensions, and then run the query. Let's do this for
the `orders` cube you generated in the previous step.

Click **+ Measure** to display the available measures and add
`orders.count`, then click **+ Dimension** for available dimensions and
add `orders.status`:

<Frame>
  <img />
</Frame>

Then, click **Run** to execute the query and see the results:

<Frame>
  <img />
</Frame>

Please feel free to experiment: select other measures or dimensions, pick a
granularity for the time dimension instead of **w/o grouping**, or choose
another chart type instead of **Table**.

## APIs and integrations

Cube provides a [rich set of options][ref-downstream] to deliver data to other
tools: a suite of APIs, [JavaScript SDKs][ref-frontend-int], and integrations.

Connectivity to BI tools and data notebooks is enabled by the [SQL
API][ref-sql-api] which is Postgres-compatible: if something connects to
Postgres, it will work with Cube. Check the **Connect to BI** tab for
connection instructions for specific BI tools:

<Frame>
  <img />
</Frame>

Connectivity to data applications is enabled by the [REST (JSON) API][ref-rest-api] and
the [GraphQL API][ref-graphql-api] as well as [JavaScript
SDKs][ref-frontend-int]. Check the **Frontend Integrations** tab for
usage instructions for these APIs:

<Frame>
  <img />
</Frame>

Now that we've seen how to use Cube's APIs, let's take a look at [how to add
pre-aggregations][next] to speed up your queries.

[ref-graphql-api]: /reference/core-data-apis/graphql-api

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-downstream]: /admin/connect-to-data/visualization-tools

[ref-frontend-int]: /reference/javascript-sdk

[ref-sql-api]: /reference/core-data-apis/sql-api

[next]: /cube-core/getting-started/add-a-pre-aggregation


# Cube Core
Source: https://docs.cube.dev/cube-core/index

Cube Core is the open-source semantic layer you can self-host with Docker.

Cube Core is the open-source version of Cube that you can deploy and manage yourself using Docker.

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/cube-core/getting-started">
    Get Cube Core running locally in minutes
  </Card>

  <Card title="Deployment" icon="server" href="/cube-core/deployment">
    Deploy to production with Docker
  </Card>

  <Card title="Configuration" icon="settings-2" href="/reference/configuration/environment-variables">
    Environment variables and config options
  </Card>

  <Card title="Authentication" icon="lock" href="/embedding/authentication/jwt">
    Set up JWT authentication
  </Card>
</CardGroup>


# Running in production
Source: https://docs.cube.dev/cube-core/running-in-production

Cube makes use of two different kinds of cache:

* In-memory storage of query results
* Pre-aggregations

Cube Store is enabled by default when running Cube in development mode. In
production, Cube Store **must** run as a separate process. The easiest way to do
this is to use the official Docker images for Cube and Cube Store.

<Warning>
  Development mode is an authentication bypass. Cube is in development mode when
  `CUBEJS_DEV_MODE=true` — which, under the `cubejs` CLI and the official Docker images,
  also forces `NODE_ENV=development` and so switches off JWT verification on the
  REST (JSON) and GraphQL APIs — and whenever `NODE_ENV` is not
  `production`. Playground's endpoints are served with no authentication too: anyone who
  can reach the instance is handed a ready-to-use API token, can mint others carrying any
  security context, can read your data model files, and can overwrite your data model and
  your `.env`. With `CUBEJS_DEV_MODE=true` and no
  [`CUBEJS_SQL_PASSWORD`](/reference/configuration/environment-variables#cubejs_sql_password)
  set, the SQL API accepts any credentials as well, allowing arbitrary SQL against
  connected data sources. Use it only on a local development machine, never in
  production. See
  [`CUBEJS_DEV_MODE`](/reference/configuration/environment-variables#cubejs_dev_mode).
</Warning>

<Info>
  Using Windows? We **strongly** recommend using [WSL2 for Windows 10][link-wsl2]
  to run the following commands.
</Info>

You can run Cube Store with Docker with the following command:

```bash theme={"dark"}
docker run -p 3030:3030 cubejs/cubestore
```

<Info>
  Cube Store can further be configured via environment variables. To see a
  complete reference, please consult the `CUBESTORE_*` environment variables in
  the [Environment Variables reference][ref-config-env].
</Info>

Next, run Cube and tell it to connect to Cube Store running on `localhost` (on
the default port `3030`):

```bash theme={"dark"}
docker run -p 4000:4000 \
  -e CUBEJS_CUBESTORE_HOST=localhost \
  -v ${PWD}:/cube/conf \
  cubejs/cube
```

In the command above, we're specifying [`CUBEJS_CUBESTORE_HOST`](/reference/configuration/environment-variables#cubejs_cubestore_host) to let Cube know
where Cube Store is running.

You can also use Docker Compose to achieve the same:

```yaml theme={"dark"}
services:
  cubestore:
    image: cubejs/cubestore:latest
    environment:
      - CUBESTORE_REMOTE_DIR=/cube/data
    volumes:
      - .cubestore:/cube/data

  cube:
    image: cubejs/cube:latest
    ports:
      - 4000:4000
    environment:
      - CUBEJS_CUBESTORE_HOST=localhost
    depends_on:
      - cubestore
    links:
      - cubestore
    volumes:
      - ./model:/cube/conf/model
```

## Architecture

<div>
  <img alt="Cube Store cluster with Cube" />
</div>

A Cube Store cluster consists of at least one Router and one or more Worker
instances. Cube sends queries to the Cube Store Router, which then distributes
the queries to the Cube Store Workers. The Workers then execute the queries and
return the results to the Router, which in turn returns the results to Cube.

## Scaling

<Warning>
  Cube Store *can* be run in a single instance mode, but this is usually
  unsuitable for production deployments. For high concurrency and data throughput,
  we **strongly** recommend running Cube Store as a cluster of multiple instances
  instead.
</Warning>

Scaling Cube Store for a higher concurrency is relatively simple when running in
cluster mode. Because [the storage layer](#storage) is decoupled from the query
processing engine, you can horizontally scale your Cube Store cluster for as
much concurrency as you require.

In cluster mode, Cube Store runs two kinds of nodes:

* one or more **router** nodes handle incoming client connections, manage
  database metadata and serve simple queries.
* multiple **worker** nodes which execute SQL queries

Cube Store querying performance is optimal when the count of partitions in a
single query is less than or equal to the worker count. For example, you have a
200 million rows table that is partitioned by day, which is ten daily Cube
partitions or 100 Cube Store partitions in total. The query sent by the user
contains filters, and the resulting scan requires reading 16 Cube Store
partitions in total. Optimal query performance, in this case, can be achieved
with 16 or more workers. You can use `EXPLAIN` and `EXPLAIN ANALYZE` SQL
commands to see how many partitions would be used in a specific Cube Store
query.

Resources required for the main node and workers can vary depending on the
configuration. With default settings, you should expect to allocate at least 4
CPUs and up to 8GB per main or worker node.

The configuration required for each node can be found in the table below. More
information about these variables can be found [in the Environment Variables
reference][ref-config-env].

| Environment Variable    | Specify on Router? | Specify on Worker? |
| ----------------------- | ------------------ | ------------------ |
| `CUBESTORE_SERVER_NAME` | ✅ Yes              | ✅ Yes              |
| `CUBESTORE_META_PORT`   | ✅ Yes              | —                  |
| `CUBESTORE_WORKERS`     | ✅ Yes              | ✅ Yes              |
| `CUBESTORE_WORKER_PORT` | —                  | ✅ Yes              |
| `CUBESTORE_META_ADDR`   | —                  | ✅ Yes              |

`CUBESTORE_WORKERS` and `CUBESTORE_META_ADDR` variables should be set with
stable addresses, which should not change. You can use stable DNS names and put
load balancers in front of your worker and router instances to fulfill stable
name requirements in environments where stable IP addresses can't be guaranteed.

<Info>
  To fully take advantage of the worker nodes in the cluster, we **strongly**
  recommend using [partitioned pre-aggregations][ref-caching-partitioning].
</Info>

A sample Docker Compose stack for the single machine setting this up might look
like:

```yaml theme={"dark"}
services:
  cubestore_router:
    restart: always
    image: cubejs/cubestore:latest
    environment:
      - CUBESTORE_SERVER_NAME=cubestore_router:9999
      - CUBESTORE_META_PORT=9999
      - CUBESTORE_WORKERS=cubestore_worker_1:9001,cubestore_worker_2:9001
      - CUBESTORE_REMOTE_DIR=/cube/data
    volumes:
      - .cubestore:/cube/data
  cubestore_worker_1:
    restart: always
    image: cubejs/cubestore:latest
    environment:
      - CUBESTORE_SERVER_NAME=cubestore_worker_1:9001
      - CUBESTORE_WORKER_PORT=9001
      - CUBESTORE_META_ADDR=cubestore_router:9999
      - CUBESTORE_WORKERS=cubestore_worker_1:9001,cubestore_worker_2:9001
      - CUBESTORE_REMOTE_DIR=/cube/data
    depends_on:
      - cubestore_router
    volumes:
      - .cubestore:/cube/data
  cubestore_worker_2:
    restart: always
    image: cubejs/cubestore:latest
    environment:
      - CUBESTORE_SERVER_NAME=cubestore_worker_2:9001
      - CUBESTORE_WORKER_PORT=9001
      - CUBESTORE_META_ADDR=cubestore_router:9999
      - CUBESTORE_WORKERS=cubestore_worker_1:9001,cubestore_worker_2:9001
      - CUBESTORE_REMOTE_DIR=/cube/data
    depends_on:
      - cubestore_router
    volumes:
      - .cubestore:/cube/data
  cube:
    image: cubejs/cube:latest
    ports:
      - 4000:4000
    environment:
      - CUBEJS_CUBESTORE_HOST=cubestore_router
    depends_on:
      - cubestore_router
    volumes:
      - .:/cube/conf
```

## Replication and High Availability

The open-source version of Cube Store doesn't support replicating any of its
nodes. The router node and every worker node should always have only one
instance copy if served behind the load balancer or service address. Replication
will lead to undefined behavior of the cluster, including connection errors and
data loss. If any cluster node is down, it'll lead to a complete cluster outage.
If Cube Store replication and high availability are required, please consider
using Cube Cloud.

## Storage

Cube Store cluster uses both persistent and scratch storage.

### Persistent storage

Cube Store makes use of a separate storage layer for storing metadata as well as
for persisting pre-aggregations as Parquet files.

Cube Store can be configured to use either AWS S3, Google Cloud Storage (GCS), or
Azure Blob Storage as persistent storage. If desired, a local path on
the server can also be used in case all Cube Store cluster nodes are
co-located on a single machine.

<Info>
  Cube Store can only use one type of remote storage at the same time.
</Info>

<Warning>
  Cube Store requires strong consistency guarantees from an underlying distributed
  storage. AWS S3, Google Cloud Storage, and Azure Blob Storage are the only known
  implementations that provide them. Using other implementations in production is
  discouraged and can lead to consistency and data corruption errors.
</Warning>

<Note>
  Available on [Enterprise plan](https://cube.dev/pricing).
</Note>

<Info>
  As an additional layer on top of standard AWS S3, Google Cloud Storage (GCS), or
  Azure Blob Storage encryption, persistent storage can optionally use [Parquet
  encryption](#data-at-rest-encryption) for data-at-rest protection.
</Info>

A simplified example using AWS S3 might look like:

```yaml theme={"dark"}
services:
  cubestore_router:
    image: cubejs/cubestore:latest
    environment:
      - CUBESTORE_SERVER_NAME=cubestore_router:9999
      - CUBESTORE_META_PORT=9999
      - CUBESTORE_WORKERS=cubestore_worker_1:9001
      - CUBESTORE_S3_BUCKET=<BUCKET_NAME_IN_S3>
      - CUBESTORE_S3_REGION=<BUCKET_REGION_IN_S3>
      - CUBESTORE_AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID>
      - CUBESTORE_AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY>

  cubestore_worker_1:
    image: cubejs/cubestore:latest
    environment:
      - CUBESTORE_SERVER_NAME=cubestore_worker_1:9001
      - CUBESTORE_WORKER_PORT=9001
      - CUBESTORE_META_ADDR=cubestore_router:9999
      - CUBESTORE_WORKERS=cubestore_worker_1:9001
      - CUBESTORE_S3_BUCKET=<BUCKET_NAME_IN_S3>
      - CUBESTORE_S3_REGION=<BUCKET_REGION_IN_S3>
      - CUBESTORE_AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID>
      - CUBESTORE_AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY>
    depends_on:
      - cubestore_router
```

Note that you can’t use the same bucket as an export bucket and persistent
storage for Cube Store. It's recommended to use two separate buckets.

### Scratch storage

Separately from persistent storage, Cube Store requires local scratch space
to warm up partitions by downloading Parquet files before querying them.

By default, this folder should be mounted to `.cubestore/data` inside the
container and can be configured by `CUBESTORE_DATA_DIR` environment variable.
It is advised to use local SSDs for this scratch space to maximize querying
performance.

### AWS

Cube Store can retrieve security credentials from instance metadata
automatically. This means you can skip defining the
`CUBESTORE_AWS_ACCESS_KEY_ID` and `CUBESTORE_AWS_SECRET_ACCESS_KEY` environment
variables.

<Warning>
  Cube Store currently does not take the key expiration time returned from
  instance metadata into account; instead the refresh duration for the key is
  defined by `CUBESTORE_AWS_CREDS_REFRESH_EVERY_MINS`, which is set to `180` by
  default.
</Warning>

### Garbage collection

Cleanup isn’t done in export buckets; however, it's done in the persistent
storage of Cube Store. The default time-to-live (TTL) for orphaned
pre-aggregation tables is one day.

Refresh worker should be able to finish pre-aggregation refresh before
garbage collection starts. It means that all pre-aggregation partitions
should be built before any tables are removed.

#### Supported file systems

The garbage collection mechanism relies on the ability of the underlying file
system to report the creation time of a file.

If the file system does not support getting the creation time, you will see the
following error message in Cube Store logs:

```text theme={"dark"}
ERROR [cubestore::remotefs::cleanup] <pid:1>
error while getting created time for file "<name>.chunk.parquet":
creation time is not available for the filesystem
```

<Note>
  XFS is known to not support getting the creation time of a file.
  Please see [this issue](https://github.com/cube-js/cube/issues/7905#issuecomment-2504212623)
  for possible workarounds.
</Note>

## Security

### Authentication

Cube Store does not have any in-built authentication mechanisms. For this reason,
we recommend running your Cube Store cluster with a network configuration that
only allows access from the Cube deployment.

### Data-at-rest encryption

[Persistent storage](#persistent-storage) is secured using the standard AWS S3,
Google Cloud Storage (GCS), or Azure Blob Storage encryption.

Cube Store also provides optional data-at-rest protection by utilizing the
[modular encryption mechanism][link-parquet-encryption] of Parquet files in its
persistent storage. Pre-aggregation data is secured using the [AES cipher][link-aes]
with 256-bit keys. Data encyption and decryption are completely seamless to Cube
Store operations.

<Note>
  Available on the [Enterprise plan](https://cube.dev/pricing).
  Also requires the M [Cube Store Worker tier](/admin/account-billing/pricing#cube-store-worker-tiers).
</Note>

You can provide, rotate, or drop your own [customer-managed keys][ref-cmk] (CMK)
for Cube Store via the **Encryption Keys** page in Cube Cloud.

## Troubleshooting

### Heavy pre-aggregations

When building some pre-aggregations, you might encounter the following error:

```text theme={"dark"}
Error: Error during create table: CREATE TABLE <REDACTED>
Error: Query execution timeout after 10 min of waiting
```

It means that your pre-aggregation is too heavy and takes too long to build.

As a temporary solution, you can increase the timeout for all queies that Cube
runs against your data source via the [`CUBEJS_DB_QUERY_TIMEOUT`](/reference/configuration/environment-variables#cubejs_db_query_timeout) environment variable.

However, it is recommended that you optimize your pre-aggregations instead:

* Use an export bucket if your [data source][ref-data-sources] supports it. Cube will then load the pre-aggregation data in a much more efficient way.
* Use [partitions][ref-pre-agg-partitions]. Cube will then run a separate query to build each partition.
* Build pre-aggregations [incrementally][ref-pre-agg-incremental]. Cube will then build only the necessary partitions with each pre-aggregation refresh.
* Set an appropriate [build range][ref-pre-agg-build-range] if you don't need to query the whole date range. Cube will then include only the necessary data in the pre-aggregation.
* Check that your pre-aggregation includes only necessary dimensions. Each additional dimension usually increases the volume of the pre-aggregation data.
  * If you include a high cardinality dimension, Cube needs to store a lot of data in the pre-aggregation. For example, if you include the primary key into the pre-aggregation, Cube will effectively need to store a copy of the original table in the pre-aggregation, which is rarely useful.
  * If a single pre-aggregation is used by queries with different sets of dimensions, consider creating separate pre-aggregations for each set of dimensions. This way, Cube will only include necessary data in each pre-aggregation.
* Check if you have a heavy calculation in the [`sql` expression][ref-cube-sql] of your cubes (rather than a simple `sql_table` reference). If it's the case, you can build an additional [`original_sql` pre-aggregation][ref-pre-agg-original-sql] and [instruct][ref-pre-agg-use-original-sql] Cube to use it when building other pre-aggregations for this cube.

### MinIO

When using MinIO for persistent storage, you might encounter the following error:

```text theme={"dark"}
Error: Error during upload of <REDACTED>
File <REDACTED> can't be listed after upload.
Either there's Cube Store cluster misconfiguration,
or storage can't provide the required consistency.
```

Most likely, it happens because MinIO is not providing strong consistency guarantees,
as required for Cube Store's [persistent storage](#persistent-storage).
You can either try configuring MinIO to provide strong consistency or switch to
using S3 or GCS.

<Warning>
  The support for MinIO as persistent storage in Cube Store was contributed by the community.
  It's not supported by Cube or the vendor.
</Warning>

[link-wsl2]: https://docs.microsoft.com/en-us/windows/wsl/install-win10

[ref-caching-partitioning]: /docs/pre-aggregations/using-pre-aggregations#partitioning

[ref-config-env]: /reference/configuration/environment-variables

[link-parquet-encryption]: https://parquet.apache.org/docs/file-format/data-pages/encryption/

[link-aes]: https://en.wikipedia.org/wiki/Advanced_Encryption_Standard

[ref-cmk]: /admin/deployment/encryption-keys

[ref-data-sources]: /admin/connect-to-data/data-sources

[ref-pre-agg-partitions]: /docs/pre-aggregations/using-pre-aggregations#partitioning

[ref-pre-agg-incremental]: /reference/data-modeling/pre-aggregations#incremental

[ref-pre-agg-build-range]: /reference/data-modeling/pre-aggregations#build_range_start-and-build_range_end

[ref-cube-sql]: /reference/data-modeling/cube#sql

[ref-pre-agg-original-sql]: /reference/data-modeling/pre-aggregations#original_sql

[ref-pre-agg-use-original-sql]: /reference/data-modeling/pre-aggregations#use_original_sql_pre_aggregations


# Security context
Source: https://docs.cube.dev/docs/data-modeling/access-control/context

How Cube derives verified user claims from inbound JWTs and where those claims plug into query rewrite and compile-time logic.

Your authentication server issues JWTs to your client application, which, when
sent as part of the request, are verified and decoded by Cube to get security
context claims to evaluate access control rules. Inbound JWTs are decoded and
verified using industry-standard [JSON Web Key Sets (JWKS)][link-auth0-jwks].

For access control or authorization, Cube allows you to define granular access
control rules for every cube in your data model. Cube uses both the request and
security context claims in the JWT token to generate a SQL query, which includes
row-level constraints from the access control rules.

JWTs sent to Cube should be passed in the `Authorization: <JWT>` header to
authenticate requests.

JWTs can also be used to pass additional information about the user, known as a
**security context**. A security context is a verified set of claims about the
current user that the Cube server can use to ensure that users only have access
to the data that they are authorized to access.

It will be accessible as the [`securityContext`][ref-config-sec-ctx] property
inside:

* The [`query_rewrite`][ref-config-queryrewrite] configuration option in your
  Cube configuration  file.
* the [`COMPILE_CONTEXT`][ref-cubes-compile-ctx] global, which is used to
  support [multi-tenant deployments][link-multitenancy].

## Contents

By convention, the contents of the security context should be an object (dictionary)
with nested structure:

```json theme={"dark"}
{
  "sub": "1234567890",
  "iat": 1516239022,
  "user_name": "John Doe",
  "user_id": 42,
  "location": {
    "city": "San Francisco",
    "state": "CA"
  }
}
```

### Reserved elements

Some features of Cube Cloud (e.g., [authentication integration][ref-auth-integration])
use the `cubeCloud` element in the security context.
This element is reserved and should not be used for other purposes.

## Using query\_rewrite

You can use [`query_rewrite`][ref-config-queryrewrite] to amend incoming queries
with filters. For example, let's take the following query:

```json theme={"dark"}
{
  "measures": [
    "orders_view.count"
  ],
  "dimensions": [
    "orders_view.status"
  ]
}
```

We'll also use the following as a JWT payload; `user_id`, `sub` and `iat` will
be injected into the security context:

```json theme={"dark"}
{
  "sub": "1234567890",
  "iat": 1516239022,
  "user_id": 42
}
```

<Warning>
  Cube expects the context to be an object. If you don't provide an object as the
  JWT payload, you will receive the following error:

  ```bash theme={"dark"}
  Cannot create proxy with a non-object as target or handler
  ```
</Warning>

To ensure that users making this query only receive their own orders, define
`query_rewrite` in the configuration file:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('query_rewrite')
  def query_rewrite(query: dict, ctx: dict) -> dict:
    if 'user_id' in ctx['securityContext']:
      query['filters'].append({
        'member': 'orders_view.users_id',
        'operator': 'equals',
        'values': [ctx['securityContext']['user_id']]
      })
    return query
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    queryRewrite: (query, { securityContext }) => {
      
      if (securityContext.user_id) {
        query.filters.push({
          member: "orders_view.users_id",
          operator: "equals",
          values: [securityContext.user_id]
        })
      }

      return query
    }
  }
  ```
</CodeGroup>

To test this, we can generate an API token as follows:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  # Install the PyJWT with pip install PyJWT
  import jwt
  import datetime

  # Secret key to sign the token
  CUBE_API_SECRET = 'secret'

  # Create the token
  token_payload = {
    'user_id': 42
  }

  # Generate the JWT token
  token = jwt.encode(token_payload, CUBE_API_SECRET, algorithm='HS256')
  ```

  ```javascript title="JavaScript" theme={"dark"}
  const jwt = require("jsonwebtoken")
  const CUBE_API_SECRET = "secret"

  const cubeToken = jwt.sign({ user_id: 42 }, CUBE_API_SECRET, {
    expiresIn: "30d"
  })
  ```
</CodeGroup>

Using this token, we authorize our request to the Cube API by passing it in the
Authorization HTTP header.

```bash theme={"dark"}
curl \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1Ijp7ImlkIjo0Mn0sImlhdCI6MTU1NjAyNTM1MiwiZXhwIjoxNTU4NjE3MzUyfQ._8QBL6nip6SkIrFzZzGq2nSF8URhl5BSSSGZYp7IJZ4" \
  -G \
  --data-urlencode 'query={"measures":["orders.count"]}' \
  http://localhost:4000/cubejs-api/v1/load
```

And Cube will generate the following SQL:

```sql theme={"dark"}
SELECT
  "orders".STATUS "orders_view__status",
  count("orders".ID) "orders_view__count"
FROM
  ECOM.ORDERS AS "orders"
  LEFT JOIN ECOM.USERS AS "users" ON "orders".USER_ID = "users".ID
WHERE
  ("users".ID = 42)
GROUP BY
  1
ORDER BY
  2 DESC
LIMIT
  5000
```

## Using COMPILE\_CONTEXT

`COMPILE_CONTEXT` can be used to create fully dynamic data models. It enables you to create multiple versions of data model based on the incoming security context.
The first thing you need to do is to define the mapping rule from a security context to the id of the compiled data model.
It is done with `context_to_app_id` configuration option.

```python theme={"dark"}
from cube import config
 
@config('context_to_app_id')
def context_to_app_id(ctx: dict) -> str:
  return ctx['securityContext']['team']
```

It is common to use some field from the incoming security context as an id for your data model.
In our example, as illustrated below, we are using `team` property of the security context as a data model id.

<Frame>
  <img alt="COMPILE_CONTEXT mapping" />
</Frame>

Once you have this mapping, you can use `COMPILE_CONTEXT` inside your data model.
In the example below we are passing it as a variable into `masked` helper function.

```yaml theme={"dark"}
cubes:
  - name: users
    sql_table: ECOM.USERS
    public: false

    dimensions:
      - name: last_name
        sql: {{ masked('LAST_NAME', COMPILE_CONTEXT.securityContext) }}
        type: string
```

This `masked` helper function is defined in `model/globals.py` as follows: it checks if the current `team` is inside the list of trusted teams.
If that's the case, it will render the SQL to get the value of the dimension; if not, it will return just the masked string.

```python theme={"dark"}
from cube import TemplateContext
 
template = TemplateContext()

@template.function('masked')
def masked(sql, security_context):
  trusted_teams = ['cx', 'exec' ]
  is_trusted_team = security_context.setdefault('team') in trusted_teams
  if is_trusted_team:
    return sql
  else:
    return "'--- masked ---'"
```

### Usage with pre-aggregations

To generate pre-aggregations that rely on `COMPILE_CONTEXT`, [configure
`scheduledRefreshContexts` in your `cube.js` configuration
file][ref-config-sched-refresh].

### Usage for member-level security

You can also use `COMPILE_CONTEXT` to control whether a data model entity should be
public or private [dynamically][ref-dynamic-data-modeling].

In the example below, the `customers` view would only be visible to a subset
of [tenants][ref-multitenancy] that have the `team` property set to `marketing`
in the security context:

```ymltitle="model/views/customers.yml" theme={"dark"}
views:
  - name: customers
    public: "{{ is_accessible_by_team('marketing', COMPILE_CONTEXT) }}"
```

```pythontitle="model/globals.py" theme={"dark"}
from cube import TemplateContext

template = TemplateContext()

@template.function('is_accessible_by_team')
def is_accessible_by_team(team: str, ctx: dict) -> bool:
  return team == ctx['securityContext'].setdefault('team', 'default')
```

If you'd like to keep a data model entity public but prevent access to it
anyway, you can use the \[`query_rewrite` configuration option]\[ref-query-rewrite] for that.

## Testing during development

During development, it is often useful to be able to edit the security context
to test access control rules. The [Developer
Playground][ref-devtools-playground] allows you to set your own JWTs, or you can
build one from a JSON object.

## Enriching the security context

Sometimes it is convenient to enrich the security context with additional attributes
before it is used to evaluate access control rules.

### Extending the security context

You can use the [`extend_context`][ref-extend-context] configuration option to
enrich the security context with additional attributes.

### Authentication integration

When using Cube Cloud, you can enrich the security context with information about
an authenticated user, obtained during their authentication.

You can enable the authentication integration by navigating to the **Settings → Configuration**
of your Cube Cloud deployment and using the **Enable Cloud Auth Integration** toggle.

## Common patterns

### Enforcing mandatory filters

You can use `query_rewrite` to enforce mandatory filters that apply to all queries. This is useful when you need to ensure certain conditions are always met, such as filtering data by date range or restricting access to specific data subsets.

For example, if you want to only show orders created after a specific date across all queries, you can add a mandatory filter:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('query_rewrite')
  def query_rewrite(query: dict, ctx: dict) -> dict:
    query['filters'].append({
      'member': 'orders.created_at',
      'operator': 'afterDate',
      'values': ['2019-12-30']
    })
    return query
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    queryRewrite: (query) => {
      query.filters.push({
        member: `orders.created_at`,
        operator: "afterDate",
        values: ["2019-12-30"]
      })

      return query
    }
  }
  ```
</CodeGroup>

This filter will be automatically applied to all queries, ensuring that only orders created after December 30th, 2019 are returned, regardless of any other filters specified in the query.

### Enforcing role-based access

You can use `query_rewrite` to enforce role-based access control by filtering data based on the user's role from the security context.

For example, to restrict access so that users with the `operator` role can only view processing orders, while users with the `manager` role can only view shipped and completed orders:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('query_rewrite')
  def query_rewrite(query: dict, ctx: dict) -> dict:
    if not ctx['securityContext'].get('role'):
      raise ValueError("No role found in Security Context!")

    role = ctx['securityContext']['role']
    
    if role == "manager":
      query['filters'].append({
        'member': 'orders.status',
        'operator': 'equals',
        'values': ['shipped', 'completed']
      })
    elif role == "operator":
      query['filters'].append({
        'member': 'orders.status',
        'operator': 'equals',
        'values': ['processing']
      })

    return query
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    queryRewrite: (query, { securityContext }) => {
      if (!securityContext.role) {
        throw new Error("No role found in Security Context!")
      }

      if (securityContext.role == "manager") {
        query.filters.push({
          member: "orders.status",
          operator: "equals",
          values: ["shipped", "completed"]
        })
      }

      if (securityContext.role == "operator") {
        query.filters.push({
          member: "orders.status",
          operator: "equals",
          values: ["processing"]
        })
      }

      return query
    }
  }
  ```
</CodeGroup>

### Enforcing column-based access

You can use `query_rewrite` to enforce column-based access control by filtering data based on relationships and user attributes from the security context.

For example, to restrict suppliers to only see their own products based on their email:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('query_rewrite')
  def query_rewrite(query: dict, ctx: dict) -> dict:
    cube_names = [
      *(query.get('dimensions', [])),
      *(query.get('measures', []))
    ]
    cube_names = [e.split(".")[0] for e in cube_names]

    if "products" in cube_names:
      email = ctx['securityContext'].get('email')
      if not email:
        raise ValueError("No email found in Security Context!")

      query['filters'].append({
        'member': 'suppliers.email',
        'operator': 'equals',
        'values': [email]
      })

    return query
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    queryRewrite: (query, { securityContext }) => {
      const cubeNames = [
        ...(query.dimensions || []),
        ...(query.measures || [])
      ].map((e) => e.split(".")[0])

      if (cubeNames.includes("products")) {
        if (!securityContext.email) {
          throw new Error("No email found in Security Context!")
        }

        query.filters.push({
          member: `suppliers.email`,
          operator: "equals",
          values: [securityContext.email]
        })
      }

      return query
    }
  }
  ```
</CodeGroup>

### Controlling access to cubes and views

You can use `extend_context` and `COMPILE_CONTEXT` to control access to cubes and views based on user properties from the security context.

For example, to make a view accessible only to users with a `department` claim set to `finance`:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('extend_context')
  def extend_context(ctx: dict) -> dict:
    return {
      'securityContext': {
        **ctx['securityContext'],
        'isFinance': ctx['securityContext'].get('department') == 'finance'
      }
    }
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    extendContext: ({ securityContext }) => {
      return {
        securityContext: {
          ...securityContext,
          isFinance: securityContext.department === "finance"
        }
      }
    }
  }
  ```
</CodeGroup>

Then in your data model, use `COMPILE_CONTEXT` to control visibility:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: total_revenue_per_customer
      public: {{ COMPILE_CONTEXT['securityContext']['isFinance'] }}
      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`total_revenue_per_customer`, {
    public: COMPILE_CONTEXT.securityContext.isFinance,
    // ...
  })
  ```
</CodeGroup>

[link-auth0-jwks]: https://auth0.com/docs/tokens/json-web-tokens/json-web-key-sets

[link-multitenancy]: /embedding/multitenancy

[ref-config-queryrewrite]: /reference/configuration/config#query_rewrite

[ref-config-sched-refresh]: /reference/configuration/config#scheduledrefreshcontexts

[ref-config-sec-ctx]: /reference/configuration/config#securitycontext

[ref-cubes-compile-ctx]: /reference/data-modeling/context-variables#compile_context

[ref-devtools-playground]: /docs/explore-analyze/playground#editing-the-security-context

[ref-auth-integration]: /docs/data-modeling/access-control#authentication-integration

[ref-extend-context]: /reference/configuration/config#extend_context

[ref-dynamic-data-modeling]: /docs/data-modeling/dynamic

[ref-multitenancy]: /embedding/multitenancy


# Access Control
Source: https://docs.cube.dev/docs/data-modeling/access-control/index

Learn how Cube separates authentication and authorization to control who can access your data and platform features.

Access control

Access control in Cube involves *authentication* and *authorization*.

## Authentication

Authentication determines if a user can access Cube.

* **Cube** cloud platform provides built-in authentication mechanisms. Users are assigned
  [roles and permissions][ref-roles-perms] that determine available features of the Cube
  platform.
* **Cube Core** provides several [authentication methods][ref-auth-methods] for its API
  endpoints.

## Authorization

Authorization determines what data a user can access though Cube.

Authorization is managed declaratively via [access policies][ref-dap], a built-in
capability of Cube's data modeling layer. There are also programmatic controls for
advanced use cases, such as the [`query_rewrite`][ref-query-rewrite] configuration
parameter.

* **Cube** cloud platform applies access policies to users based on their
  [groups][ref-user-groups] and [attributes][ref-user-attributes].
* **Cube Core** applies access policies to users based on their groups derived from the
  [security context][ref-sec-ctx]. See the [`context_to_groups`][ref-ctx-to-groups]
  configuration parameter for details.

[ref-roles-perms]: /admin/users-and-permissions/roles-and-permissions

[ref-auth-methods]: /embedding/authentication/jwt

[ref-user-groups]: /admin/users-and-permissions/user-groups

[ref-user-attributes]: /admin/users-and-permissions/user-attributes

[ref-sec-ctx]: /docs/data-modeling/access-control/context

[ref-dap]: /docs/data-modeling/data-access-policies

[ref-query-rewrite]: /reference/configuration/config#query_rewrite

[ref-ctx-to-groups]: /reference/configuration/config#context_to_groups


# Member-level security
Source: https://docs.cube.dev/docs/data-modeling/access-control/member-level-security

Covers restricting which cubes, views, and members end users can query, including defaults and policy configuration with includes and excludes.

The data model serves as a facade of your data. With member-level security,
you can define whether [data model entities][ref-data-modeling-concepts] (cubes, views,
and their members) are exposed to end users and can be queried via [APIs &
integrations][ref-apis].

Member-level security in Cube is similar to column-level security in SQL databases.
Defining whether users have access to [cubes][ref-cubes] and [views][ref-views] is
similar to defining access to database tables; defining whether they have access
to dimensions and measures — to columns.

**By default, all cubes, views, and their members are *public*,** meaning that they
can be accessed by any users and they are also visible during data model introspection.

## Managing member-level access

You can use [access policies][ref-dap] to configure member-level access
for different groups. With the `access_policy` parameter in
[cubes][ref-ref-cubes] and [views][ref-ref-views], you can define which members
are accessible to users with specific groups.

Use the `member_level` parameter to specify either:

* `includes`: a list of allowed members, or
* `excludes`: a list of disallowed members

You can use `"*"` as a shorthand to include or exclude all members.

<Info>
  When you define access policies for specific groups, access is automatically denied to all other groups. You don't need to create a default policy that denies access.
</Info>

In the following example, member-level access is configured for different groups:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: orders_view
      cubes:
        - join_path: orders
          includes:
            - status
            - created_at
            - count
            - count_7d
            - count_30d
      
      access_policy:
        # Managers can access all members except for `count`
        - group: manager
          member_level:
            excludes:
              - count
        
        # Observers can access all members except for `count` and `count_7d`
        - group: observer
          member_level:
            excludes:
              - count
              - count_7d
        
        # Guests can only access the `count_30d` measure
        - group: guest
          member_level:
            includes:
              - count_30d
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`orders_view`, {
    cubes: [
      {
        join_path: orders,
        includes: [
          `status`,
          `created_at`,
          `count`,
          `count_7d`,
          `count_30d`
        ]
      }
    ],

    access_policy: [
      {
        // Managers can access all members except for `count`
        group: `manager`,
        member_level: {
          excludes: [
            `count`
          ]
        }
      },
      {
        // Observers can access all members except for `count` and `count_7d`
        group: `observer`,
        member_level: {
          excludes: [
            `count`,
            `count_7d`
          ]
        }
      },
      {
        // Guests can only access the `count_30d` measure
        group: `guest`,
        member_level: {
          includes: [
            `count_30d`
          ]
        }
      }
    ]
  })
  ```
</CodeGroup>

This configuration results in the following access:

| Group           | Access                                        |
| --------------- | --------------------------------------------- |
| `manager`       | All members except for `count`                |
| `observer`      | All members except for `count` and `count_7d` |
| `guest`         | Only the `count_30d` measure                  |
| All other users | No access to this view at all                 |

Access policies also respect member-level security restrictions configured via
`public` parameters. For more details, see the [access policies
reference][ref-dap-ref].

<Info>
  If you want to return masked values for restricted members instead of hiding
  them entirely, see [data masking][ref-data-masking] in access policies.
</Info>

[ref-data-modeling-concepts]: /docs/data-modeling/overview

[ref-apis]: /reference

[ref-cubes]: /docs/data-modeling/cubes

[ref-views]: /docs/data-modeling/views

[ref-dap]: /docs/data-modeling/data-access-policies

[ref-ref-cubes]: /reference/data-modeling/cube

[ref-ref-views]: /reference/data-modeling/view

[ref-dev-mode]: /docs/data-modeling/dev-mode

[ref-playground]: /docs/explore-analyze/playground

[ref-dap-ref]: /reference/data-modeling/data-access-policies

[ref-cubes-public]: /reference/data-modeling/cube#public

[ref-views-public]: /reference/data-modeling/view#public

[ref-measures-public]: /reference/data-modeling/measures#public

[ref-dimensions-public]: /reference/data-modeling/dimensions#public

[ref-hierarchies-public]: /reference/data-modeling/hierarchies#public

[ref-segments-public]: /reference/data-modeling/segments#public

[ref-dynamic-data-modeling]: /docs/data-modeling/dynamic

[ref-security-context]: /docs/data-modeling/access-control/context

[ref-data-masking]: /docs/data-modeling/data-access-policies#data-masking


# Row-level security
Source: https://docs.cube.dev/docs/data-modeling/access-control/row-level-security

Covers applying group- and attribute-based filters so query results only include rows users are allowed to see.

The data model serves as a facade of your data. With row-level security,
you can define whether some [data model][ref-data-modeling-concepts] facts are exposed
to end users and can be queried via [APIs & integrations][ref-apis].

Row-level security in Cube is similar to row-level security in SQL databases.
Defining whether users have access to specific facts from [cubes][ref-cubes] and
[views][ref-views] is similar to defining access to rows in database tables.

**By default, all rows are *public*,** meaning that no filtering is applied to
data model facts when they are accessed by any users.

## Managing row-level access

You can use [access policies][ref-dap] to manage both [member-level][ref-mls]
and row-level security based on groups and [user attributes][ref-security-context].

Here's an example of how to filter rows by a user attribute using access policies:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      access_policy:
        - group: manager
          row_level:
            filters:
              - member: country
                operator: equals
                values: [ "{ userAttributes.country }" ]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    access_policy: [
      {
        group: `manager`,
        row_level: {
          filters: [
            {
              member: `country`,
              operator: `equals`,
              values: [ userAttributes.country ]
            }
          ]
        }
      }
    ]
  })
  ```
</CodeGroup>

[ref-data-modeling-concepts]: /docs/data-modeling/overview

[ref-apis]: /reference

[ref-cubes]: /docs/data-modeling/cubes

[ref-views]: /docs/data-modeling/views

[ref-cubes-sql]: /reference/data-modeling/cube#sql

[ref-dynamic-data-modeling]: /docs/data-modeling/dynamic

[ref-dap]: /docs/data-modeling/data-access-policies

[ref-mls]: /docs/data-modeling/access-control/member-level-security

[ref-security-context]: /docs/data-modeling/access-control/context


# Access Policies viewer
Source: https://docs.cube.dev/docs/data-modeling/access-policies-viewer

Audit row-level, member-level, and member-masking access policies that govern your data model from the Cube Cloud UI, grouped by user group.

The Access Policies viewer surfaces, in one place, every [access policy][ref-access-policies]
defined in your [data model][ref-data-modeling] — row-level filters, member-level
restrictions, and member masking — broken down by the user [groups][ref-user-groups]
they apply to.

Use it to audit who can see which cubes and views, and how each policy is composed,
without grepping through `cube` files or running test queries.

<Info>
  The viewer is read-only. Access policies themselves are authored in the
  [data model][ref-access-policies] using `access_policy` blocks; this page
  visualizes the resolved rules so you can review and debug them.
</Info>

## Opening the viewer

In Cube Cloud, navigate to the **Model** module and click **Access Policies** in
the sub-sidebar. The viewer reflects whichever branch and build you are currently
viewing, so policies you are editing in [development mode][ref-dev-mode] appear
alongside what is live in production.

You need the `PlaygroundRead` permission to open the viewer.

## List view

The list view shows one row per group declared anywhere in the data model:

<Frame>
  <img alt="Access Policies list view, with one row per user group" />
</Frame>

| Column             | What it shows                                                                                                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Group**          | Name of the group. The wildcard entry `*` is rendered as **All Groups** — this is the catch-all default policy applied when no other policy matches.                         |
| **Policies**       | Number of cubes and views with an explicit policy for this group. Hover the cell to see the full list of cube and view names.                                                |
| **Default Policy** | Number of cubes and views this group can access without an explicit policy — the union of cubes covered by the wildcard `*` policy and any cubes that have no policy at all. |

Cubes and views with no `access_policy` block defined are considered fully open;
they appear under **Default Policy** for every group.

Click a row to drill into the per-cube breakdown for that group.

## Per-policy detail view

The detail view shows one row per cube or view that the selected group can
access, with the resolved policy expanded across four columns:

| Column                  | What it shows                                                                                                                                                                                              |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cube / View**         | Name of the cube or view, with an icon distinguishing the two.                                                                                                                                             |
| **Condition**           | The number of [`condition`][ref-policy-condition] expressions on the policy, or `—` if the policy applies unconditionally. Conditions are arbitrary expressions defined in the model.                      |
| **Member-level Access** | One of three states: **Allow All** (no member-level restrictions), **Deny All** (member access is fully denied), or **Allow:** followed by the resolved set of allowed dimensions, segments, and measures. |
| **Member Masking**      | `—` if no [member masking][ref-mls-masking] applies, otherwise the list of masked dimensions.                                                                                                              |
| **Row-level Access**    | Either **Allow All**, or **Filters on:** followed by the dimensions referenced by the row-level filter.                                                                                                    |

Member names are shortened to the last path segment for readability — for
example, `orders.user.email` is shown as `email`.

## What the viewer does not do

The viewer is intentionally scoped to inspecting policies that are already
defined in the model. It does not:

* Create, edit, or delete access policies. Edit `access_policy` blocks in your
  data model and commit through your normal Git workflow.
* Show which individual users belong to a given group. See
  [User groups][ref-user-groups] for membership management.
* Run preview queries against a policy. To verify behavior end-to-end, switch
  the security context and issue queries against your development API.

[ref-data-modeling]: /docs/data-modeling/overview

[ref-access-policies]: /docs/data-modeling/data-access-policies

[ref-policy-condition]: /reference/data-modeling/data-access-policies#conditions

[ref-mls-masking]: /docs/data-modeling/data-access-policies#data-masking

[ref-dev-mode]: /docs/data-modeling/dev-mode

[ref-user-groups]: /admin/users-and-permissions/user-groups


# AI context
Source: https://docs.cube.dev/docs/data-modeling/ai-context

Improve AI accuracy and trust by enriching your semantic layer with descriptions and AI-specific context that helps agents generate better insights.

When using [Analytics Chat][ref-analytics-chat] or other AI-powered features,
the AI agent relies on your data model to understand your data. You can
optimize your data model to help the AI generate more accurate queries and
provide better insights.

There are two ways to provide additional context to the AI:

* **Descriptions** — visible to both end users and the AI agent.
* **AI context via `meta`** — only visible to the AI agent, not exposed in the
  user interface.

## Using descriptions

The [`description`][ref-cube-description] parameter on cubes, views, measures,
dimensions, and segments provides human-readable context that is displayed in
the UI and also consumed by the AI agent.

Use descriptions to clarify the meaning of a member for both your team and
end users:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders
      description: All orders including pending, shipped, and completed

      measures:
        - name: total_revenue
          sql: amount
          type: sum
          description: Total revenue from completed orders only
          filters:
            - sql: "{CUBE}.status = 'completed'"

      dimensions:
        - name: status
          sql: status
          type: string
          description: "Current order status: pending, shipped, or completed"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,
    description: `All orders including pending, shipped, and completed`,

    measures: {
      total_revenue: {
        sql: `amount`,
        type: `sum`,
        description: `Total revenue from completed orders only`,
        filters: [{ sql: `${CUBE}.status = 'completed'` }]
      }
    },

    dimensions: {
      status: {
        sql: `status`,
        type: `string`,
        description: `Current order status: pending, shipped, or completed`
      }
    }
  })
  ```
</CodeGroup>

Descriptions are a good starting point because they serve double duty — they
help end users understand the data and also give the AI agent context for
query generation.

## Using AI context

If you want to provide context to the AI agent **without exposing it in the
user interface**, use the `ai_context` key inside the
[`meta`][ref-cube-meta] parameter. The `meta` parameter accepts custom
metadata on views, measures, and dimensions.

<Note>
  `ai_context` must be defined on **views** or on **individual members**
  (measures, dimensions). `ai_context` defined at the cube level is **not
  consumed by the AI agent**.
</Note>

Each `ai_context` value is limited to 2,000 characters; anything longer is
silently truncated before it reaches the agent.

Use `ai_context` on [views][ref-view-meta] to provide high-level guidance,
and on individual members for member-specific instructions:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: revenue_overview
      description: Revenue metrics and breakdowns
      meta:
        ai_context: >
          This is the primary view for revenue analysis. It combines
          order, product, and user data. Use this view when users ask
          about sales, revenue, or product performance.

      cubes:
        - join_path: order_items
          includes:
            - total_sale_price
            - count
            - status
            - created_at
        - join_path: order_items.products
          includes:
            - brand
            - category
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`revenue_overview`, {
    description: `Revenue metrics and breakdowns`,
    meta: {
      ai_context: `This is the primary view for revenue analysis. It combines
        order, product, and user data. Use this view when users ask about
        sales, revenue, or product performance.`
    },

    cubes: [
      {
        join_path: order_items,
        includes: [
          `total_sale_price`,
          `count`,
          `status`,
          `created_at`
        ]
      },
      {
        join_path: order_items.products,
        includes: [
          `brand`,
          `category`
        ]
      }
    ]
  })
  ```
</CodeGroup>

For member-level context, define `ai_context` directly on the measure or
dimension:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: order_items
      sql_table: ECOMMERCE.ORDER_ITEMS

      measures:
        - name: total_sale_price
          sql: sale_price
          type: sum
          format: currency
          meta:
            ai_context: >
              Use this measure for any revenue-related questions.
              It includes all line items regardless of order status.

      dimensions:
        - name: created_at
          sql: created_at
          type: time
          meta:
            ai_context: >
              This is the order creation timestamp in UTC.
              For delivery analysis, use delivered_at instead.
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`order_items`, {
    sql_table: `ECOMMERCE.ORDER_ITEMS`,

    measures: {
      total_sale_price: {
        sql: `sale_price`,
        type: `sum`,
        format: `currency`,
        meta: {
          ai_context: `Use this measure for any revenue-related questions.
            It includes all line items regardless of order status.`
        }
      }
    },

    dimensions: {
      created_at: {
        sql: `created_at`,
        type: `time`,
        meta: {
          ai_context: `This is the order creation timestamp in UTC.
            For delivery analysis, use delivered_at instead.`
        }
      }
    }
  })
  ```
</CodeGroup>

You can also override member-level `ai_context` when including members in
a view — for example, to define synonyms or acronyms that only apply in the
context of that view:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: sales_overview
      description: Sales metrics and breakdowns
      meta:
        ai_context: >
          This view is for sales performance analysis across brands.

      cubes:
        - join_path: order_items
          includes:
            - total_sale_price
        - join_path: order_items.products
          includes:
            - name: brand
              meta:
                ai_context: >
                  Common acronyms: LC = Lucky Charms,
                  HNC = Honey Nut Cheerios.
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`sales_overview`, {
    description: `Sales metrics and breakdowns`,
    meta: {
      ai_context: `This view is for sales performance analysis across brands.`
    },

    cubes: [
      {
        join_path: order_items,
        includes: [`total_sale_price`]
      },
      {
        join_path: order_items.products,
        includes: [
          {
            name: `brand`,
            meta: {
              ai_context: `Common acronyms: LC = Lucky Charms,
                HNC = Honey Nut Cheerios.`
            }
          }
        ]
      }
    ]
  })
  ```
</CodeGroup>

## Descriptions vs. AI context

|                      | `description`                                | `meta.ai_context`           |
| -------------------- | -------------------------------------------- | --------------------------- |
| Visible in the UI    | Yes                                          | No                          |
| Used by the AI agent | Yes                                          | Yes                         |
| Supported on         | Cubes, views, measures, dimensions, segments | Views, measures, dimensions |
| Length limit         | None                                         | 2,000 characters            |

Use `description` when the context is useful to both end users and the AI
agent. Use `ai_context` when you want to provide additional instructions or
context that is only relevant to the AI agent — for example, guidance on
which measures to prefer, nuances about data quality, or business logic that
would be confusing in a user-facing description.

You can use both together. The AI agent reads both the `description` and
`ai_context` when generating queries:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: order_items
      sql_table: ECOMMERCE.ORDER_ITEMS
      description: Line items for all orders

      measures:
        - name: total_sale_price
          sql: sale_price
          type: sum
          format: currency
          description: Total revenue across all line items
          meta:
            ai_context: >
              This is the primary revenue metric. Always use this
              instead of summing the sale_price column directly.
              When users ask about "sales", they mean this measure.
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`order_items`, {
    sql_table: `ECOMMERCE.ORDER_ITEMS`,
    description: `Line items for all orders`,

    measures: {
      total_sale_price: {
        sql: `sale_price`,
        type: `sum`,
        format: `currency`,
        description: `Total revenue across all line items`,
        meta: {
          ai_context: `This is the primary revenue metric. Always use this
            instead of summing the sale_price column directly.
            When users ask about "sales", they mean this measure.`
        }
      }
    }
  })
  ```
</CodeGroup>

## Best practices

* **Add descriptions to all public members.** Descriptions help both end users
  and the AI agent understand your data model.
* **Use AI context for agent-specific guidance.** If you need to tell the AI
  agent which measure to prefer or how to interpret ambiguous terms, use
  `ai_context`.
* **Define context on views or individual members.** `ai_context` defined
  at the cube level is not consumed by the AI agent. Place it on the view
  itself or on individual measures and dimensions.
* **Be specific.** Vague context like "important metric" is less helpful than
  "use this measure when users ask about monthly recurring revenue."
* **Document relationships.** Use AI context to explain how cubes relate to each
  other and which views to prefer for common questions.
* **Keep it up to date.** As your data model evolves, update descriptions and AI
  context to reflect the current state.

[ref-analytics-chat]: /docs/explore-analyze/analytics-chat

[ref-cube-description]: /reference/data-modeling/cube#description

[ref-cube-meta]: /reference/data-modeling/cube#meta

[ref-view-meta]: /reference/data-modeling/view#meta


# Syntax
Source: https://docs.cube.dev/docs/data-modeling/concepts/syntax

Specifies the model directory layout, file naming, and when to use YAML versus JavaScript for Cube data model files.

Entities within the data model (e.g., cubes, views, etc.) should be placed under
the `model` [folder][self-folder-structure], follow [naming
conventions][self-naming], and be defined using a supported
[syntax][self-syntax].

## Folder structure

Data model files should be placed inside the `model` folder. You can use the
[`schema_path` configuration option][ref-config-model-path] to override the
folder name or the [`repository_factory` configuration
option][ref-config-repository-factory] to dynamically define the folder name and
data model file contents.

It's recommended to place each cube or view in a separate file, in `model/cubes`
and `model/views` folders, respectively. [View groups][ref-view-groups] can be
defined alongside views or in their own files. Example:

```tree theme={"dark"}
model
├── cubes
│   ├── orders.yml
│   ├── products.yml
│   └── users.yml
└── views
    ├── revenue.yml
    └── view_groups.yml
```

## Model syntax

Cube supports two ways to define data model files: with [YAML][wiki-yaml] or
JavaScript syntax. YAML data model files should have the `.yml` extension,
whereas JavaScript data model files should end with `.js`. You can mix YAML and
JavaScript files within a single data model.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql: |
        SELECT *
        FROM orders, line_items
        WHERE orders.id = line_items.order_id

  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql: `
      SELECT *
      FROM orders, line_items
      WHERE orders.id = line_items.order_id
    `
  })
  ```
</CodeGroup>

You can define the data model statically or build [dynamic data
models][ref-dynamic-data-models] programmatically. YAML data models use
[Jinja and Python][ref-dynamic-data-models-jinja] whereas JavaScript data
models use [JavaScript][ref-dynamic-data-models-js].

It is recommended to default to YAML syntax because of its
simplicity and readability. However, JavaScript might provide more flexibility
for dynamic data modeling.

<Note>
  See [Cube style guide][ref-style-guide] for more recommendations on syntax and structure.
</Note>

## Naming

Common rules apply to names of entities within the data model. All names must:

* Start with a letter.
* Consist of letters, numbers, and underscore (`_`) symbols only.
* Not be a [reserved keyword in Python][link-python-reserved-words], e.g., `from`, `return`, or `yield`.
* When using the DAX API, not clash with the names of columns in date hierarchies.
* Be unique within their scope. Cube and view names must be unique across the data
  model; members (measures, dimensions, segments, pre-aggregations, hierarchies) must
  be unique within their cube; and folder names must be unique within their view. Cube
  will report an error for duplicates.

It is also recommended that names use [snake case][wiki-snake-case].

Good examples of names:

* `orders`, `stripe_invoices`, or `base_payments` (cubes)
* `opportunities`, `cloud_accounts`, or `arr` (views)
* `count`, `avg_price`, or `total_amount_shipped` (measures)
* `name`, `is_shipped`, or `created_at` (dimensions)
* `main`, `orders_by_status`, or `lambda_invoices` (pre-aggregations)

## SQL expressions

When defining cubes, you would often provide SQL snippets in `sql` and
`sql_table` parameters.

Provided SQL expressions should match your database SQL dialect, e.g.,
to aggregate a list of strings, you would probably pick the [`LISTAGG`
function][link-snowflake-listagg] in Snowflake and the [`STRING_AGG`
function][link-bigquery-stringagg] in BigQuery.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      measures:
        - name: statuses
          sql: "STRING_AGG(status)"
          type: string

      dimensions:
        - name: status
          sql: "UPPER(status)"
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    measures: {
      statuses: {
        sql: `STRING_AGG(status)`,
        type: `string`
      }
    },

    dimensions: {
      status: {
        sql: `UPPER(status)`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

<Note>
  Currently, Cube does not wrap your SQL snippets in parentheses during SQL
  generation. In case of non-trivial snippets, this may lead to unexpected results.
  Please [track this issue](https://github.com/cube-js/cube/issues/6373).
</Note>

### User-defined functions

If you have created a [user-defined function][link-sql-udf] (UDF) in your data
source, you can use it in the `sql` parameter as well.

### Case sensitivity

If your database uses case-sensitive identifiers, make sure to properly
quote table and column names. For example, here's how you can reference
a Postgres table that contains uppercase letters in its name:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: 'public."Orders"'
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `public."Orders"`
  })
  ```
</CodeGroup>

## References

To write versatile data models, it is important to be able to reference
members of cubes and views, such as measures or dimensions, as well as
table columns. Cube supports the following syntax for references.

### `column`

Most commonly, you would use bare column names in the `sql` parameter of
measures or dimensions. In the following example, `name` references
the respective column of the `users` table.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      dimensions:
        - name: name
          sql: name
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    dimensions: {
      name: {
        sql: `name`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

This syntax works great for simple use cases. However, if your cubes have
joins and joined cubes have columns with the same name, the generated SQL
query might become ambiguous. See below how to work around that.

### `{member}`

When defining measures and dimensions, you can also reference other members
of the same cube by wrapping their names in curly braces. In the following
example, the `full_name` dimension references `name` and `surname` dimensions
of the same cube.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      dimensions:
        - name: name
          sql: name
          type: string

        - name: surname
          sql: "UPPER(surname)"
          type: string

        - name: full_name
          sql: "CONCAT({name}, ' ', {surname})"
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    dimensions: {
      name: {
        sql: `name`,
        type: `string`
      },

      surname: {
        sql: `UPPER(surname)`,
        type: `string`
      },

      full_name: {
        sql: `CONCAT(${name}, ' ', ${surname})`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

<Note>
  You can safely reference a member whose `sql` is a compound expression, such as
  arithmetic (`{price} + {tax}`) or boolean logic (`{is_paid} OR {is_pending}`). When you
  reference such a member inside an arithmetic or logical expression, Cube wraps it in
  parentheses automatically, so operator precedence is preserved. For example, if
  `price_with_tax` is defined as `{price} + {tax}`, then referencing it as
  `{price_with_tax} * {quantity}` generates `(price + tax) * quantity`. Cube only adds these
  parentheses where they are needed — a reference that already sits in a safe position, such as
  a function argument (`ABS({price_with_tax})`) or a `CAST(...)`, is left unwrapped.
</Note>

This syntax works great for simple use cases. However, there are cases
(like [subquery][ref-subquery]) when you'd like to reference members of
other cubes. See below how to do that.

### `{time_dimension.granularity}`

When referencing a [time dimension][ref-time-dimension], you can specificy a
granularity to refer to a time value with that specific granularity. It can be
one of the [default granularities][ref-default-granularities] (e.g., `year` or
`week`) or a [custom granularity][ref-custom-granularities]:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      dimensions:
        - name: created_at
          sql: created_at
          type: time

          granularities:
            - name: sunday_week
              interval: 1 week
              offset: -1 day

        - name: created_at__year
          sql: "{created_at.year}"
          type: time

        - name: created_at__sunday_week
          sql: "{created_at.sunday_week}"
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    dimensions: {
      created_at: {
        sql: `created_at`,
        type: `time`,

        granularities: {
          sunday_week: {
            interval: `1 week`,
            offset: `-1 day`
          }
        }
      },

      created_at__year: {
        sql: `${created_at.year}`,
        type: `time`
      },

      created_at__sunday_week: {
        sql: `${created_at.sunday_week}`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

### `{cube}.column`, `{cube.member}`

You can qualify column and member names with the name of a cube to remove
the ambiguity when cubes are joined and reference members of other cubes.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      joins:
        - name: contacts
          sql: "{users}.contact_id = {contacts.id}"
          relationship: one_to_one

      dimensions:
        - name: id
          sql: "{users}.id"
          type: number
          primary_key: true

        - name: name
          sql: "COALESCE({users.name}, {contacts.name})"
          type: string

    - name: contacts
      sql_table: contacts

      dimensions:
        - name: id
          sql: "{contacts}.id"
          type: number
          primary_key: true

        - name: name
          sql: "{contacts}.name"
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    joins: {
      contacts: {
        sql: `${users}.contact_id = ${contacts.id}`,
        relationship: `one_to_one`
      }
    },

    dimensions: {
      id: {
        sql: `${users}.id`,
        type: `number`,
        primary_key: true
      },

      name: {
        sql: `COALESCE(${users}.name, ${contacts.name})`,
        type: `string`
      }
    }
  })

  cube(`contacts`, {
    sql_table: `contacts`,

    dimensions: {
      id: {
        sql: `${contacts}.id`,
        type: `number`,
        primary_key: true
      },

      name: {
        sql: `${contacts}.name`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

In production, using fully-qualified names is generally encouraged since it
removes the ambiguity and keeps data model code maintainable as it grows.
However, always referring to the current cube by its name leads to code
repetition and violates the DRY principle. See below how to solve that.

### `{cube1.cube2.member}`

You can also qualify member names with more than one cube name, separated by a dot, to
provide a [join path][ref-join-paths] and remove the ambiguity of join resolution. Join
paths can be used in [calculated members][ref-calculated-members], [views][ref-views],
and [pre-aggregation][ref-preaggs] definitions.

In the following example, four cubes are joined together, forming a [*diamond
subgraph*][ref-diamond-subgraphs] in the join tree: `a` joins to `b` and `c`, and both
`b` and `c` join to `d`. As you can see, join paths in the `d_via_b` and `d_via_c`
dimensions of `a` are then used to specify which intermediate cube to use when resolving
the dimension from `d`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: a
      sql: |
        SELECT 1 AS id UNION ALL
        SELECT 2 AS id UNION ALL
        SELECT 3 AS id

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: d_via_b
          sql: "{b.d.id}"
          type: number

        - name: d_via_c
          sql: "{c.d.id}"
          type: number

      joins:
        - name: b
          sql: "{a.id} = {b.id}"
          relationship: one_to_one

        - name: c
          sql: "{a.id} = {c.id}"
          relationship: one_to_one

    - name: b
      sql: |
        SELECT 1 AS id UNION ALL
        SELECT 2 AS id UNION ALL
        SELECT 3 AS id

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

      joins:
        - name: d
          sql: "{b.id} = {d.id}"
          relationship: one_to_one

    - name: c
      sql: |
        SELECT 1 AS id UNION ALL
        SELECT 2 AS id UNION ALL
        SELECT 3 AS id

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

      joins:
        - name: d
          sql: "{c.id} = {d.id}"
          relationship: one_to_one

    - name: d
      sql: |
        SELECT 1 AS id UNION ALL
        SELECT 2 AS id UNION ALL
        SELECT 3 AS id

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`a`, {
    sql: `
      SELECT 1 AS id UNION ALL
      SELECT 2 AS id UNION ALL
      SELECT 3 AS id
    `,

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      },

      d_via_b: {
        sql: `${b.d.id}`,
        type: `number`
      },

      d_via_c: {
        sql: `${c.d.id}`,
        type: `number`
      }
    },

    joins: {
      b: {
        sql: `${a.id} = ${b.id}`,
        relationship: `one_to_one`
      },

      c: {
        sql: `${a.id} = ${c.id}`,
        relationship: `one_to_one`
      }
    }
  })

  cube(`b`, {
    sql: `
      SELECT 1 AS id UNION ALL
      SELECT 2 AS id UNION ALL
      SELECT 3 AS id
    `,

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      }
    },

    joins: {
      d: {
        sql: `${b.id} = ${d.id}`,
        relationship: `one_to_one`
      }
    }
  })

  cube(`c`, {
    sql: `
      SELECT 1 AS id UNION ALL
      SELECT 2 AS id UNION ALL
      SELECT 3 AS id
    `,

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      }
    },

    joins: {
      d: {
        sql: `${c.id} = ${d.id}`,
        relationship: `one_to_one`
      }
    }
  })

  cube(`d`, {
    sql: `
      SELECT 1 AS id UNION ALL
      SELECT 2 AS id UNION ALL
      SELECT 3 AS id
    `,

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      }
    }
  })
  ```
</CodeGroup>

### `{CUBE}` variable

You can use a handy `{CUBE}` [context variable][ref-context-variables]
(mind the uppercase) to reference the current cube so you don't have to
repeat the its name over and over. It works both for column and member
references.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      joins:
        - name: contacts
          sql: "{CUBE}.contact_id = {contacts.id}"
          relationship: one_to_one

      dimensions:
        - name: id
          sql: "{CUBE}.id"
          type: number
          primary_key: true

        - name: name
          sql: "COALESCE({CUBE.name}, {contacts.name})"
          type: string

    - name: contacts
      sql_table: contacts

      dimensions:
        - name: id
          sql: "{CUBE}.id"
          type: number
          primary_key: true

        - name: name
          sql: "{CUBE}.name"
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    joins: {
      contacts: {
        sql: `${CUBE}.contact_id = ${contacts.id}`,
        relationship: `one_to_one`
      }
    },

    dimensions: {
      id: {
        sql: `${CUBE}.id`,
        type: `number`,
        primary_key: true
      },

      name: {
        sql: `COALESCE(${CUBE}.name, ${contacts.name})`,
        type: `string`
      }
    }
  })

  cube(`contacts`, {
    sql_table: `contacts`,

    dimensions: {
      id: {
        sql: `${CUBE}.id`,
        type: `number`,
        primary_key: true
      },

      name: {
        sql: `${CUBE}.name`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

Check the `{users.name}` dimension. Referencing another cube in the
dimension definition instructs Cube to make an implicit join to that cube.
For example, using the data model above, we can make the following query:

```json theme={"dark"}
{
  "dimensions": ["users.name"]
}
```

The resulting generated SQL query would look like this:

```sql theme={"dark"}
SELECT COALESCE("users".name, "contacts".name) "users__name"
FROM users "users"
LEFT JOIN contacts "contacts"
  ON "users".contact_id = "contacts".id
```

### `{cube.sql()}` function

When defining a cube, you can reference the `sql` parameter of another cube,
effectively reusing the SQL query it's defined on. This is particularly useful
when defining [polymorphic cubes][ref-polymorphism] or using [data blending][ref-data-blending].

Consider the following data model:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: organisms
      sql_table: organisms

    - name: animals
      sql: |
        SELECT *
        FROM {organisms.sql()}
        WHERE kingdom = 'animals'

    - name: dogs
      sql: |
        SELECT *
        FROM {animals.sql()}
        WHERE species = 'dogs'

      measures:
        - name: count
          type: count
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`organisms`, {
    sql_table: `organisms`
  })

  cube(`animals`, {
    sql: `
      SELECT *
      FROM ${organisms.sql()}
      WHERE kingdom = 'animals'
    `
  })

  cube(`dogs`, {
    sql: `
      SELECT *
      FROM ${animals.sql()}
      WHERE species = 'dogs'
    `,

    measures: {
      count: {
        type: `count`
      }
    }
  })
  ```
</CodeGroup>

If you query for `dogs.count`, Cube will generate the following SQL:

```sql theme={"dark"}
SELECT count(*) "dogs__count"
FROM (
  SELECT *
  FROM (
    SELECT *
    FROM organisms
    WHERE kingdom = 'animals'
  )
  WHERE species = 'dogs'
) AS "dogs"
```

### Curly braces and escaping

As you can see in the examples above, within [SQL expressions][self-sql-expressions],
curly braces are used to reference cubes and members.

In YAML data models, use `{reference}`:

```yaml theme={"dark"}
cubes:
  - name: orders
    sql: |
      SELECT id, created_at
      FROM {other_cube.sql()}

    dimensions:
      - name: status
        sql: status
        type: string

      - name: status_x2
        sql: "{status} || ' ' || {status}"
        type: string
```

In JavaScript data models, use `${reference}` in [JavaScript template
literals][link-js-template-literals] (mind the dollar sign):

```javascript theme={"dark"}
cube(`orders`, {
  sql: `
    SELECT id, created_at
    FROM ${other_cube.sql()}
  `,

  dimensions: {
    status: {
      sql: `status`,
      type: `string`
    },

    status_x2: {
      sql: `${status} || ' ' || ${status}`,
      type: `string`
    }
  }
})
```

If you need to use literal, non-referential curly braces in YAML, e.g.,
to define a JSON object, you can escape them with a backslash:

```yaml theme={"dark"}
cubes:
  - name: json_object_in_postgres
    sql: SELECT CAST('\{"key":"value"\}'::JSON AS TEXT) AS json_column

  - name: csv_from_s3_in_duckdb
    sql: |
      SELECT *
      FROM read_csv(
        's3://bbb/aaa.csv',
        delim = ',',
        header = true,
        columns=\{'time':'DATE','count':'NUMERIC'\}
      )
```

### Non-SQL references

Outside [SQL expressions][self-sql-expressions], `column` is not recognized
as a column name; it is rather recognized as a member name. It means that,
outside `sql` and `sql_table` parameters, you can skip the curly braces and
reference members by their names directly: `member`, `cube_name.member`, or
`CUBE.member`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      dimensions:
        - name: status
          sql: status
          type: string

      measures:
        - name: count
          type: count

      pre_aggregations:
        - name: orders_by_status
          dimensions:
            - CUBE.status
          measures:
            - CUBE.count
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    dimensions: {
      status: {
        sql: `status`,
        type: `string`
      }
    },

    measures: {
      count: {
        type: `count`
      }
    },

    pre_aggregations: {
      orders_by_status: {
        dimensions: [CUBE.status],
        measures: [CUBE.count]
      }
    }
  })
  ```
</CodeGroup>

## Context variables

In addition to the `CUBE` variable, you can also use a few more [context
variables][ref-context-variables] within your data model. They are
generally useful for two purposes: optimizing generated SQL queries and
defining dynamic data models.

## Troubleshooting

### `Can't parse timestamp`

Sometimes, you might come across the following error message: `Can't parse timestamp:
2023-11-07T14:33:23.16.000`.

It indicates that the data source was unable to recognize the value of a [time
dimension][ref-time-dimension] as a timestamp. Please check that the [SQL
expression](#sql-expressions) of this time dimension evaluates to a `TIMESTAMP` type.

<Note>
  Check [this recipe][ref-recipe-string-time-dimensions] to see how you can work around
  string values in time dimensions.
</Note>

[self-folder-structure]: #folder-structure

[self-naming]: #naming

[self-syntax]: #code-syntax

[self-sql-expressions]: #sql-expressions

[ref-dynamic-data-models]: /docs/data-modeling/dynamic

[ref-dynamic-data-models-jinja]: /docs/data-modeling/dynamic/jinja

[ref-dynamic-data-models-js]: /docs/data-modeling/dynamic/javascript

[ref-context-variables]: /reference/data-modeling/context-variables

[ref-config-model-path]: /reference/configuration/config#schemapath

[ref-config-repository-factory]: /reference/configuration/config#repositoryfactory

[ref-subquery]: /docs/data-modeling/dimensions#subquery-dimensions

[wiki-snake-case]: https://en.wikipedia.org/wiki/Snake_case

[wiki-yaml]: https://en.wikipedia.org/wiki/YAML

[link-snowflake-listagg]: https://docs.snowflake.com/en/sql-reference/functions/listagg

[link-bigquery-stringagg]: https://cloud.google.com/bigquery/docs/reference/standard-sql/functions-and-operators#string_agg

[link-sql-udf]: https://en.wikipedia.org/wiki/User-defined_function#Databases

[ref-time-dimension]: /reference/data-modeling/dimensions#type

[ref-default-granularities]: /docs/data-modeling/dimensions#time-dimensions

[ref-custom-granularities]: /reference/data-modeling/dimensions#granularities

[ref-style-guide]: /recipes/data-modeling/style-guide

[ref-polymorphism]: /recipes/data-modeling/polymorphic-cubes

[ref-data-blending]: /docs/data-modeling/concepts/data-blending

[link-js-template-literals]: https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Scripting/Strings#embedding_javascript

[link-python-reserved-words]: https://docs.python.org/3/reference/lexical_analysis.html#keywords

[ref-time-dimension]: /docs/data-modeling/dimensions#time-dimensions

[ref-recipe-string-time-dimensions]: /recipes/data-modeling/string-time-dimensions

[ref-view-groups]: /reference/data-modeling/view-group

[ref-views]: /docs/data-modeling/views

[ref-preaggs]: /reference/data-modeling/pre-aggregations

[ref-join-paths]: /docs/data-modeling/joins#join-paths

[ref-calculated-members]: /docs/data-modeling/measures#calculated-measures

[ref-diamond-subgraphs]: /docs/data-modeling/joins#diamond-subgraphs


# Configuration
Source: https://docs.cube.dev/docs/data-modeling/configuration

Configure model-level query defaults for a Cube deployment — query time zone, row limits, and query timeout.

The **Model Configuration** section in deployment settings is where you set
model-level defaults that every query in a [deployment][ref-deployment-types]
inherits unless it overrides them explicitly: the query time zone, default
and maximum row limits, and the per-query timeout.

<Frame>
  <img alt="Model Configuration section in deployment settings" />
</Frame>

To open it, go to **Settings** → **Configuration** in the deployment
sidebar.

<Note>
  Model Configuration is a curated, typed UI for the most common
  model-level environment variables. Anything set here can also be set
  through the [Environment Variables][ref-env-vars] page directly.
</Note>

## Default time zone

The time zone used to interpret and return time dimensions when a query
doesn't specify one. Accepts any TZ database name, such as
`America/Los_Angeles` or `Europe/Berlin`. Defaults to `UTC`.

Backed by the
[`CUBEJS_DEFAULT_TIMEZONE`](/reference/configuration/environment-variables#cubejs_default_timezone)
environment variable. See [time zone][ref-time-zone] in the queries
reference for how Cube applies it to time dimensions and date ranges.

## Default row limit

The [row limit][ref-row-limit] applied to a query when it doesn't include
an explicit `LIMIT`. Defaults to `10,000`.

Lower this if most of your dashboards aggregate to a small number of rows
and you want to catch run-away "select everything" queries earlier. Raise
it if you're frequently truncating legitimate result sets.

Backed by
[`CUBEJS_DB_QUERY_DEFAULT_LIMIT`](/reference/configuration/environment-variables#cubejs_db_query_default_limit).

## Maximum row limit

The hard cap on row count for any query. Any explicit `LIMIT` is reduced
to this value, regardless of what the client requested. Defaults to
`50,000`.

This is the guardrail that protects the deployment from out-of-memory
crashes and accidental full-table extracts.

<Warning>
  Raising the maximum row limit can cause out-of-memory crashes and makes
  the deployment more vulnerable to denial-of-service attacks if the APIs
  are exposed to untrusted clients. Increase it only when you have a
  specific use case that requires it.
</Warning>

Backed by
[`CUBEJS_DB_QUERY_LIMIT`](/reference/configuration/environment-variables#cubejs_db_query_limit).
[SQL API][ref-sql-api] queries running in streaming mode can exceed this
cap by design.

## Query timeout

The per-query timeout applied to the upstream data source. Accepts a
duration string (`10m`, `30s`, `2h`) or a plain number of seconds.
Defaults to `10m`.

If a query exceeds this timeout, Cube cancels it and returns an error to
the client. Tune this based on the slowest legitimate query you expect to
run against the data source.

Backed by
[`CUBEJS_DB_QUERY_TIMEOUT`](/reference/configuration/environment-variables#cubejs_db_query_timeout).

## Auto-run

The deployment-wide default for whether [Explore][ref-explore] and
[Workbooks][ref-workbooks] tabs run their query automatically as you build it,
or wait for you to click **Run query**. Defaults to on.

A semantic view's [`meta.auto_run`][ref-view-auto-run] setting and a user's
own per-tab toggle both take precedence over this deployment default.

Backed by
[`CUBEJS_AUTO_RUN_MODE`](/reference/configuration/environment-variables#cubejs_auto_run_mode).

## Applying changes

Saving Model Configuration restarts the deployment's development-mode
worker so the new values take effect immediately for the
[development environment][ref-environments-dev]. Production environments
pick up the changes on the next build or deploy.

[ref-deployment-types]: /admin/deployment/deployment-types

[ref-env-vars]: /reference/configuration/environment-variables

[ref-time-zone]: /reference/core-data-apis/queries#time-zone

[ref-row-limit]: /reference/core-data-apis/queries#row-limit

[ref-sql-api]: /reference/core-data-apis/sql-api

[ref-environments-dev]: /admin/deployment/environments#development-environments

[ref-explore]: /docs/explore-analyze/explore

[ref-workbooks]: /docs/explore-analyze/workbooks/querying-data

[ref-view-auto-run]: /reference/data-modeling/view#auto_run


# Content Validator
Source: https://docs.cube.dev/docs/data-modeling/content-validator

Find workbook reports that reference data model fields or views that no longer exist, and fix or remove them before a model change breaks live dashboards.

The Content Validator finds workbook reports whose queries reference data model
members — individual fields or whole views — that no longer exist in your
current data model. Use it to catch and fix broken content while you are
changing the model, before the change ships and breaks live
[dashboards][ref-dashboards].

## Opening the Content Validator

In Cube Cloud, navigate to the **Data Model** module and select the
**Content Validator** tab.

<Frame>
  <img alt="Content Validator tab showing a findings table with broken field and view references" />
</Frame>

Validation runs in real time, right when you open the tab — there is no
background job to schedule or wait for.

## How validation works

The Content Validator checks every [workbook][ref-workbooks] in the
deployment. For each workbook, it validates the workbook's draft reports as
well as the report snapshots of its published [dashboard][ref-dashboards].
Each report's query is checked with the same query parser the report editor
uses, so a reference flagged here is exactly the broken reference a viewer
would hit when opening that report.

Validation is branch-aware: reports are checked against the data model of
whatever context you are currently in — your
[development mode][ref-dev-mode], a shared branch, or production. The page
header names the context you are validating against, so you always know which
version of the model the findings apply to.

<Info>
  The Content Validator uses the full data model, ignoring visibility settings
  and access policies. A report referencing a member that is hidden with
  [`public: false`][ref-cube-public] or restricted by an
  [access policy][ref-access-policies] is **not** flagged — the member still
  exists in the model. Only references to members that are truly gone are
  reported.
</Info>

## Reviewing findings

Each broken reference is one row in the findings table:

| Column      | What it shows                                                                             |
| ----------- | ----------------------------------------------------------------------------------------- |
| **Content** | The report name and the workbook it belongs to.                                           |
| **State**   | Whether the finding is in a **Draft** report or a **Published** dashboard snapshot.       |
| **Field**   | The broken member reference, e.g., `orders.total`.                                        |
| **Error**   | The parser error, e.g., `No such field "orders.total"` or `No such view "sessions_view"`. |
| **Status**  | The state of the reference — **Missing**.                                                 |

There are two kinds of findings:

* **Missing field** — the report references a member (a measure or a
  dimension) that no longer exists in an otherwise valid view.
* **Missing view** — the report queries a view that no longer exists in the
  data model.

Use the search box above the table to filter findings by report, workbook, or
member name, and the **All** / **Draft** / **Published** filter to focus on
one kind of content.

If every reference resolves, the page shows *No broken references found*.

## Fixing broken references

How you fix a finding depends on whether it is in a draft report or a
published dashboard snapshot:

* **Draft reports** are editable in place. Each draft finding offers
  **Open**, **Replace**, and **Delete** actions.
* **Published dashboards** are immutable snapshots — they only change when
  their dashboard is republished. Published findings offer only an **Open**
  action; to fix one, update the draft report in its workbook and republish
  the dashboard.

### Open

**Open** navigates to the content itself: the report in its workbook for a
draft finding, or the live published dashboard for a published finding.

### Replace

**Replace** swaps the broken reference for an existing one across the
report's saved query. Clicking it opens a dialog with a searchable picker of
valid replacements — members of the same view for a missing field, or other
views for a missing view.

* If several draft reports share the same broken reference, the dialog offers
  a **Replace in all affected reports** checkbox (enabled by default) so you
  can fix them all in one action.
* If a published dashboard references the same member, the dialog notes that
  it will keep its current snapshot until the dashboard is republished.

When you apply a replacement, Cube rewrites each affected report's saved
query, persists it, and re-runs validation, so fixed rows clear from the
table immediately. The rewrite is precise: only references to the broken
member are updated, while same-named members of other views are left
untouched.

### Delete

**Delete** permanently removes the report from its workbook — use it for
reports that are no longer worth fixing. A confirmation dialog is shown
before anything is deleted, and validation re-runs afterwards.

## Scope and limitations

* The Content Validator validates reports whose queries are stored as
  semantic SQL. A report whose query the parser cannot read is counted as
  *not checked* — it is neither flagged as broken nor asserted to be clean.
  When this happens, the summary shows a *N reports could not be checked*
  note.
* Validation covers each workbook's draft reports and its published dashboard
  snapshots.
* **Replace** and **Delete** act on draft reports only. Fixing published
  content is a two-step process: fix the draft, then republish the dashboard.

[ref-workbooks]: /docs/explore-analyze/workbooks

[ref-dashboards]: /docs/explore-analyze/dashboards

[ref-dev-mode]: /docs/data-modeling/dev-mode

[ref-cube-public]: /reference/data-modeling/cube#public

[ref-access-policies]: /docs/data-modeling/data-access-policies


# Cubes
Source: https://docs.cube.dev/docs/data-modeling/cubes

Cubes represent the tables in your database. Each cube maps to a table or query in your data source and contains measures, dimensions, joins, and pre-aggregations.

Cubes represent the tables in your database. Each cube maps to a single
table in your [data source][ref-data-sources] and contains the business
logic — [measures][ref-measures], [dimensions][ref-dimensions],
[joins][ref-joins], and [pre-aggregations][ref-pre-aggs] — that defines
how that data can be queried.

<Note>
  See the [cube reference][ref-cube-reference] for the full list of
  parameters and configuration options.
</Note>

## Defining a cube

A cube points to a table in your data source using `sql_table`:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`
  })
  ```
</CodeGroup>

You can also use the `sql` property for more complex queries:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql: |
        SELECT *
        FROM orders, line_items
        WHERE orders.id = line_items.order_id
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql: `
      SELECT *
      FROM orders, line_items
      WHERE orders.id = line_items.order_id
    `
  })
  ```
</CodeGroup>

<Tip>
  If you're using dbt, see [this recipe][ref-cube-with-dbt] to streamline
  defining cubes on top of dbt models.
</Tip>

## Cube members

Each cube contains definitions for its members: dimensions, measures,
and segments.

### Dimensions

[Dimensions][ref-dimensions] represent the properties of a single data
point — the attributes you group by and filter on, such as `status`,
`city`, or `created_at`:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: status
          sql: status
          type: string

        - name: created_at
          sql: created_at
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      },

      status: {
        sql: `status`,
        type: `string`
      },

      created_at: {
        sql: `created_at`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

Time dimensions enable grouping by granularity (year, quarter, month,
week, day, hour, minute, second) and are essential for
[partitioned pre-aggregations][ref-partition-preaggs].

### Measures

[Measures][ref-measures] represent aggregated values over a set of data
points — counts, sums, averages, and custom calculations:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: count
          type: count

        - name: total_amount
          sql: amount
          type: sum

        - name: average_amount
          sql: amount
          type: avg
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      count: {
        type: `count`
      },

      total_amount: {
        sql: `amount`,
        type: `sum`
      },

      average_amount: {
        sql: `amount`,
        type: `avg`
      }
    }
  })
  ```
</CodeGroup>

Measures can reference other measures to create
[calculated measures][ref-calculated-measures], and you can apply
[filters][ref-measure-filters] to create filtered aggregations like
"count of completed orders."

### Segments

[Segments][ref-segments] are predefined filters on a cube. They allow
you to define commonly used filter logic once and reuse it across
queries:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      segments:
        - name: completed
          sql: "{CUBE}.status = 'completed'"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    segments: {
      completed: {
        sql: `${CUBE}.status = 'completed'`
      }
    }
  })
  ```
</CodeGroup>

## Joins

[Joins][ref-joins] define relationships between cubes, forming the data
graph that Cube uses to generate multi-table SQL queries:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      joins:
        - name: users
          relationship: many_to_one
          sql: "{CUBE}.user_id = {users.id}"

        - name: line_items
          relationship: one_to_many
          sql: "{CUBE}.id = {line_items.order_id}"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    joins: {
      users: {
        relationship: `many_to_one`,
        sql: `${CUBE}.user_id = ${users.id}`
      },

      line_items: {
        relationship: `one_to_many`,
        sql: `${CUBE}.id = ${line_items.order_id}`
      }
    }
  })
  ```
</CodeGroup>

Cube supports `one_to_one`, `many_to_one`, and `one_to_many` relationship
types. See [working with joins][ref-working-with-joins] for advanced
patterns like cross-database joins and join direction control.

## Pre-aggregations

[Pre-aggregations][ref-pre-aggs] are materialized summaries of cube data
that dramatically speed up query execution. Cube automatically matches
incoming queries to the best available pre-aggregation:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: main
          measures:
            - count
            - total_amount
          dimensions:
            - status
          time_dimension: created_at
          granularity: day
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    pre_aggregations: {
      main: {
        measures: [count, total_amount],
        dimensions: [status],
        time_dimension: created_at,
        granularity: `day`
      }
    }
  })
  ```
</CodeGroup>

Pre-aggregations support [partitioning][ref-partition-preaggs] by time
and [incremental refreshes][ref-incremental-preaggs] to keep materialized
data up-to-date efficiently.

## Designing effective cubes

### One cube per entity

Map each cube to a single business entity — `orders`, `users`,
`products`, `line_items`. Use [joins](#joins) to connect them rather than
creating wide cubes with data from multiple tables.

### Keep naming consistent

Use clear, consistent naming for members. Dimensions should describe
attributes (`status`, `city`, `created_at`), and measures should describe
aggregations (`count`, `total_revenue`, `average_order_value`). Add
[`description`][ref-cube-description] and [`title`][ref-cube-title] for
user-friendly display.

### Control visibility

Use [`public`][ref-cube-public] to hide cubes that should not be
directly queried by end-users. In most data models, cubes are internal
building blocks and [views][ref-views] are the public interface:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: base_orders
      public: false
      sql_table: orders

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`base_orders`, {
    public: false,
    sql_table: `orders`,

    // ...
  })
  ```
</CodeGroup>

### Scale with extension and polymorphism

When cubes share common members, use [`extends`][ref-extending-cubes] to
avoid duplication. For data models with many similar entities,
[polymorphic cubes][ref-polymorphic-cubes] let you define a base cube
and specialize it per entity.

## Next steps

* See the [cube reference][ref-cube-reference] for the full list of
  parameters
* Learn about [views][ref-views] to expose cubes to end-users
* Explore [calculated measures][ref-calculated-measures] for derived metrics
* Use the [Semantic Model IDE][ref-ide] to develop cubes interactively

[wiki-view-sql]: https://en.wikipedia.org/wiki/View_\(SQL\)

[ref-data-sources]: /admin/connect-to-data

[ref-cube-reference]: /reference/data-modeling/cube

[ref-cube-description]: /reference/data-modeling/cube#description

[ref-cube-title]: /reference/data-modeling/cube#title

[ref-cube-public]: /reference/data-modeling/cube#public

[ref-measures]: /reference/data-modeling/measures

[ref-dimensions]: /reference/data-modeling/dimensions

[ref-segments]: /reference/data-modeling/segments

[ref-joins]: /reference/data-modeling/joins

[ref-pre-aggs]: /reference/data-modeling/pre-aggregations

[ref-views]: /docs/data-modeling/views

[ref-extending-cubes]: /docs/data-modeling/extending-cubes

[ref-polymorphic-cubes]: /recipes/data-modeling/polymorphic-cubes

[ref-calculated-measures]: /docs/data-modeling/measures#calculated-measures

[ref-measure-filters]: /reference/data-modeling/measures#filters

[ref-working-with-joins]: /docs/data-modeling/joins

[ref-partition-preaggs]: /docs/pre-aggregations/matching-pre-aggregations#partitioning

[ref-incremental-preaggs]: /reference/data-modeling/pre-aggregations#incremental

[ref-cube-with-dbt]: /recipes/data-modeling/dbt

[ref-ide]: /docs/data-modeling/data-model-ide


# Access policies
Source: https://docs.cube.dev/docs/data-modeling/data-access-policies

Declares group-scoped policies that combine member access, row filters, and masking rules directly in the data model.

Access policies provide a holistic mechanism to manage [member-level](#member-level-access),
[row-level](#row-level-access) security, and [data masking](#data-masking) for
different user groups. You can define access control rules in data model files,
allowing for an organized and maintainable approach to security.

## Policies

You can define policies that target specific groups and contain member-level and (or)
row-level security rules:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      access_policy:
          #   For the `manager` group,
          #   allow access to all members
          #   but filter rows by the user's country
        - group: manager
          member_level:
            includes: "*"
          row_level:
            filters:
              - member: country
                operator: equals
                values: [ "{ userAttributes.country }" ]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    access_policy: [
      {
        // For all groups, restrict access entirely
        group: `*`,
        member_level: {
          includes: []
        }
      },
      {
        // For the `manager` group,
        //   allow access to all members
        //   but filter rows by the user's country
        group: `manager`,
        member_level: {
          includes: `*`
        },
        row_level: {
          filters: [
            {
              member: `country`,
              operator: `equals`,
              values: [ userAttributes.country ]
            }
          ]
        }
      }
    ]
  })
  ```
</CodeGroup>

While you can define access policies on both cubes and views, it is more common to define them on views.

For more details on available parameters, check out the [access policies reference][ref-ref-dap].

## Policy evaluation

When processing a request, Cube will evaluate the access policies and combine them
with relevant custom security rules, e.g., [`public` parameters][ref-mls-public] for member-level security
and `query_rewrite` filters for row-level security.

### The permission space

It helps to think of access control as a **two-dimensional permission space** —
a grid of **members** (the columns a user may query: dimensions and measures)
and **rows** (the records a user may see):

* one axis is **members** — *what* a user can look at;
* the other axis is **rows** — *which* records they can look at.

Each access policy grants visibility over a rectangular region of this space:
its `member_level` chooses the members (the horizontal extent) and its
`row_level` chooses the rows (the vertical extent). Defaults *widen* the region —
a policy with no `row_level` (or with `row_level: { allow_all: true }`) spans
**every row**, and a policy with no `member_level` spans **every member**.
`member_masking` marks part of a region as **visible but masked** rather than
fully readable.

A user usually matches more than one policy (for example, through multiple
[groups](#custom-mapping)), so their effective access is the combination of
every region granted by every matching policy:

* **Members are unioned.** A member is accessible if **any** matching policy
  grants it. A user who matches several policies sees every member those
  policies expose, even when no single policy exposes all of them.
* **Rows are intersected across the queried members.** For each queried member,
  the visible rows are the **union** of the row filters of the policies that
  grant that member (a policy with no row filter adds no restriction). A row is
  returned only when it is visible for **every** queried member.
* **A member is masked** when no granting policy gives it unconditional full
  access through `member_level`, but some matching policy lists it under
  `member_masking`.
* **Access is denied** (an empty result) only when a queried member is granted
  by **no** matching policy at all.

#### Diagram and behavior

Consider an `orders_view` matched by two of a user's groups:

* the `support` group — `member_level: [status, count]`, `row_level` restricted
  to `region = 'US'`;
* the `finance` group — `member_level: [count, revenue]`, `row_level` restricted
  to `region = 'EU'`.

The two policies cover overlapping regions of the permission space. `count` sits
in the overlap (both policies grant it); `status` and `revenue` are each granted
by only one policy:

```text theme={"dark"}
  members
         ▲
         │          ┌───────────────────────────────────────┐
 revenue │          │            finance policy             │
         │ ┌────────┼──────────────┐                        │
   count │ │        │   overlap    │                        │
         │ │        └──────────────┼────────────────────────┘
  status │ │    support policy     │
         │ └───────────────────────┘
         └───────────────────────────────────────────────────▶ rows
                   US region                EU region
```

For a user in **both** groups, the readable cells (✓) of the permission space are:

|           |  `US` rows  |  `EU` rows  |
| --------- | :---------: | :---------: |
| `status`  | ✓ (support) |      —      |
| `count`   | ✓ (support) | ✓ (finance) |
| `revenue` |      —      | ✓ (finance) |

Because rows are intersected across the queried members, the visible rows depend
on *which* members the query selects:

| Queried members              | How rows resolve     | Visible rows        |
| ---------------------------- | -------------------- | ------------------- |
| `status`, `count`            | `US` ∩ (`US` ∪ `EU`) | `US` rows           |
| `count`, `revenue`           | (`US` ∪ `EU`) ∩ `EU` | `EU` rows           |
| `count`                      | `US` ∪ `EU`          | all rows            |
| `status`, `count`, `revenue` | `US` ∩ `EU`          | none (empty result) |

* Querying `status` and `count` returns only `US` rows: `status` is granted only
  by the `support` policy, so records outside the US can never satisfy the query.
* Querying `count` alone returns all rows: both policies grant `count`, so its
  visible rows are the union of the two regions.
* Querying `status`, `count`, and `revenue` returns nothing: `status` is visible
  only on `US` rows and `revenue` only on `EU` rows, and no record is in both.
  The result is empty rather than leaking US-only members onto EU rows.

<Info>
  A policy without a `row_level` filter defaults to **all rows** (allow-all). So
  when every policy that grants the queried members is filter-less, there is no
  row restriction at all — the members are simply unioned and all rows are
  returned. Row filters only narrow the result when a granting policy defines them.
</Info>

### Member-level access

Member-level security rules in access policies are *combined together*
with `public` parameters of cube and view members using the *AND* semantics.
Both will apply to the request.

*When querying a view,* member-level security rules defined in the view are ***not** combined together*
with member-level security rules defined in relevant cubes.
**Only the ones from the view will apply to the request.**

<Info>
  This is consistent with how column-level security works in SQL databases. If you have
  a view that exposes a subset of columns from a table, it doesnt matter if the
  columns in the table are public or not, the view will expose them anyway.
</Info>

### Row-level access

Row-level filters in access policies are *combined together* with filters defined
using the `query_rewrite` configuration option.
Both will apply to the request.

*When querying a view,* row-level filters defined in the view are *combined together*
with row-level filters defined in relevant cubes. Both will apply to the request.

<Info>
  This is consistent with how row-level security works in SQL databases. If you have
  a view that exposes a subset of rows from another view, the result set will be
  filtered by the row-level security rules of both views.
</Info>

### Data masking

With data masking, you can return masked values for restricted members instead
of denying access entirely. Users who don't have full access to a member will
see a transformed value (e.g., `***`, `-1`, `NULL`) rather than receiving an error.

To use data masking, define a [`mask` parameter][ref-ref-mask-dim] on dimensions
or measures, and add `member_masking` to your access policy alongside `member_level`.
Members in `member_level` get real values; members not in `member_level` but in
`member_masking` get masked values; members in neither are denied.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      dimensions:
        - name: status
          sql: status
          type: string

        - name: secret_code
          sql: secret_code
          type: string
          mask:
            sql: "CONCAT('***', RIGHT({CUBE}.secret_code, 3))"

        - name: revenue
          sql: revenue
          type: number
          mask: -1

      measures:
        - name: count
          type: count
          mask: 0

      access_policy:
        - group: manager
          member_level:
            includes:
              - status
              - count
          member_masking:
            includes: "*"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    dimensions: {
      status: {
        sql: `status`,
        type: `string`
      },

      secret_code: {
        sql: `secret_code`,
        type: `string`,
        mask: {
          sql: `CONCAT('***', RIGHT(${CUBE}.secret_code, 3))`
        }
      },

      revenue: {
        sql: `revenue`,
        type: `number`,
        mask: -1
      }
    },

    measures: {
      count: {
        type: `count`,
        mask: 0
      }
    },

    access_policy: [
      {
        group: `manager`,
        member_level: {
          includes: [`status`, `count`]
        },
        member_masking: {
          includes: `*`
        }
      }
    ]
  })
  ```
</CodeGroup>

With this policy, users in the `manager` group will see:

| Member        | Value                                       |
| ------------- | ------------------------------------------- |
| `status`      | Real value (full access via `member_level`) |
| `count`       | Real value (full access via `member_level`) |
| `secret_code` | Masked via SQL: `***xyz`                    |
| `revenue`     | Masked: `-1`                                |

If no `mask` is defined on a member, the default mask value is `NULL`. You can
customize defaults with the `CUBEJS_ACCESS_POLICY_MASK_STRING`,
`CUBEJS_ACCESS_POLICY_MASK_NUMBER`, `CUBEJS_ACCESS_POLICY_MASK_BOOLEAN`, and
`CUBEJS_ACCESS_POLICY_MASK_TIME` environment variables.

<Warning>
  SQL masks (`mask: { sql: "..." }`) on measures are not applied in ungrouped
  queries (e.g., `SELECT *` via the SQL API), because SQL mask expressions
  typically reference columns that are not meaningful in a per-row context.
  Static masks (`mask: -1`, `mask: 0`) are applied in all cases.

  If you need to mask a measure in ungrouped queries with a dynamic expression,
  define it as a dimension with an SQL mask instead, and reference that masked
  dimension in your query.
</Warning>

#### Masking across multiple policies

Because member access is [unioned](#the-permission-space), **full access wins
over masking**. If any matching policy grants a member unconditional full access
through `member_level` (with no `row_level` filter), the user sees the **real**
value — even if another matching policy lists that member under `member_masking`.

Masking only takes effect when **no** matching policy grants unconditional full
access. There are two sub-cases:

* **Masked only.** The member is exposed solely through `member_masking` (or any
  full-access policy is itself row-restricted). The member is masked for **all**
  rows.
* **Conditionally unmasked.** Another policy grants full access *and* defines a
  `row_level` filter — full access is conditional on that filter. Masking then
  becomes **conditional on the row filter**: rows matching the filter show the
  real value, while the rest show the masked value. The generated SQL is roughly
  `CASE WHEN {rowFilter} THEN {value} ELSE {mask} END`.

<Info>
  This lets you combine a broad masking policy (e.g. the `*` group sees masked
  values) with a narrower policy that reveals real values only for the rows a
  group is entitled to (its `row_level` range).
</Info>

If the query itself already constrains rows to a subset of the conditional
mask's row filter — an equally or more restrictive filter on the same member
(for example, the query filters `country = 'US'` and the mask filter is
`country = 'US'`) — then every returned row would show the real value anyway.
In that case the `CASE WHEN` is unnecessary and the member is **unmasked**. This
also lets a conditionally-masked *aggregate measure* render its real value
instead of being masked, even without grouping by the filter's member.

#### Conditional masking on measures

Conditional masking is evaluated **per row**, which works naturally for
dimensions (the `CASE WHEN` expression is part of the `GROUP BY`). For an
**aggregate measure** (e.g. `sum`, `count`), that per-row expression can only be
applied when the members referenced by the row filter are part of the query's
`GROUP BY`.

When a query selects a conditionally-masked measure but **does not group by the
members referenced in the row filter**, Cube cannot decide the condition per
aggregated group. Rather than emit invalid SQL (where the filter column is
neither grouped nor aggregated — which fails on strict engines like BigQuery),
it renders the **mask value for the entire measure** (`NULL` by default) instead
of the conditional expression.

| Query groups by the row filter's members? | Result for the measure                                      |
| ----------------------------------------- | ----------------------------------------------------------- |
| Yes                                       | Conditional: real value for matching rows, masked otherwise |
| No                                        | Fully masked (the mask value, e.g. `NULL`)                  |

<Tip>
  If you need a row-aware value for a measure regardless of grouping, add the row
  filter's member (the dimension it filters on) to your query's dimensions so it
  becomes part of the `GROUP BY`.
</Tip>

*When querying a view,* data masking follows the same pattern as row-level
security: masking rules from both the view and relevant cubes are applied.

For more details on available parameters, check out the
[`member_masking` reference][ref-ref-dap-masking].

## Common patterns

### Restrict access to specific groups

To restrict access to a view to only specific groups, define access policies for those groups. Access is automatically denied to all other groups:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: sensitive_data_view
      # ...
      
      access_policy:
        # Allow access only to the `analysts` group
        - group: analysts
          member_level:
            includes: "*"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`sensitive_data_view`, {
    // ...
    
    access_policy: [
      {
        // Allow access only to the `analysts` group
        group: `analysts`,
        member_level: {
          includes: `*`
        }
      }
    ]
  })
  ```
</CodeGroup>

You can also use the `groups` parameter (plural) to apply the same policy to multiple groups at once:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: sensitive_data_view
      # ...
      
      access_policy:
        # Allow access to multiple groups using groups array
        - groups: [analysts, managers]
          member_level:
            includes: "*"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`sensitive_data_view`, {
    // ...
    
    access_policy: [
      {
        // Allow access to multiple groups using groups array
        groups: [`analysts`, `managers`],
        member_level: {
          includes: `*`
        }
      }
    ]
  })
  ```
</CodeGroup>

### Filter by user attribute

You can filter data based on user attributes to ensure users only see data they're authorized to access. For example, sales people can see only their own deals, while sales managers can see all deals:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: deals_view
      # ...
      
      access_policy:
        # Sales people can only see their own deals
        - group: sales
          member_level:
            includes: "*"
          row_level:
            filters:
              - member: sales_person_id
                operator: equals
                values: [ "{ userAttributes.userId }" ]
        
        # Sales managers can see all deals
        - group: sales_manager
          member_level:
            includes: "*"
          # No row-level filters - full access to all rows
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`deals_view`, {
    // ...
    
    access_policy: [
      {
        // Sales people can only see their own deals
        group: `sales`,
        member_level: {
          includes: `*`
        },
        row_level: {
          filters: [
            {
              member: `sales_person_id`,
              operator: `equals`,
              values: [ userAttributes.userId ]
            }
          ]
        }
      },
      {
        // Sales managers can see all deals
        group: `sales_manager`,
        member_level: {
          includes: `*`
        }
        // No row-level filters - full access to all rows
      }
    ]
  })
  ```
</CodeGroup>

### Filter by multiple user attributes

You can pass multiple values in the `values` array to match a dimension against
more than one user attribute. This is useful when users may have access based on
multiple properties, such as a country and a custom country property:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: deals_view
      # ...
      
      access_policy:
        - group: sales
          member_level:
            includes: "*"
          row_level:
            filters:
              - member: users_country
                operator: equals
                values: [ "{ userAttributes.country }", "{ userAttributes.customCountryProperty }" ]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`deals_view`, {
    // ...
    
    access_policy: [
      {
        group: `sales`,
        member_level: {
          includes: `*`
        },
        row_level: {
          filters: [
            {
              member: `users_country`,
              operator: `equals`,
              values: [
                userAttributes.country,
                userAttributes.customCountryProperty
              ]
            }
          ]
        }
      }
    ]
  })
  ```
</CodeGroup>

### Mask sensitive members

You can mask sensitive members for most users while granting full access to
privileged groups:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: orders_view
      # ...

      access_policy:
        # Default: all members masked
        - group: "*"
          member_level:
            includes: []
          member_masking:
            includes: "*"

        # Admins: full access
        - group: admin
          member_level:
            includes: "*"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`orders_view`, {
    // ...

    access_policy: [
      {
        // Default: all members masked
        group: `*`,
        member_level: {
          includes: []
        },
        member_masking: {
          includes: `*`
        }
      },
      {
        // Admins: full access
        group: `admin`,
        member_level: {
          includes: `*`
        }
      }
    ]
  })
  ```
</CodeGroup>

### Mandatory filters

You can apply mandatory row-level filters to specific groups to ensure they only see data matching certain criteria:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: country_data_view
      # ...
      
      access_policy:
        # Allow access only to the `sales` and `marketing` groups with country filtering
        - groups: [sales, marketing]
          member_level:
            includes: "*"
          row_level:
            filters:
              - member: users_country
                operator: equals
                values: ["Brasil"]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`country_data_view`, {
    // ...
    
    access_policy: [
      {
        // Allow access only to the `sales` and `marketing` groups with country filtering
        groups: [`sales`, `marketing`],
        member_level: {
          includes: `*`
        },
        row_level: {
          filters: [
            {
              member: `users_country`,
              operator: `equals`,
              values: [`Brasil`]
            }
          ]
        }
      }
    ]
  })
  ```
</CodeGroup>

## Custom mapping

Cube cloud platform automatically maps authenticated users to groups for access policies.
If you are using Cube Core or authenticating against [Core Data APIs][ref-core-data-apis] directly, you might need to map the security context to groups manually.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  # cube.py
  from cube import config

  @config('context_to_groups')
  def context_to_groups(ctx: dict) -> list[str]:
    return ctx['securityContext'].get('groups', ['default'])
  ```

  ```javascript title="JavaScript" theme={"dark"}
  // cube.js
  module.exports = {
    contextToGroups: ({ securityContext }) => {
      return securityContext.groups || ['default']
    }
  }
  ```
</CodeGroup>

A user can have more than one group.

## Using securityContext

The [`userAttributes`][ref-sec-ctx] object is only available in Cube Cloud platform. If you are using Cube Core or authenticating against [Core Data APIs][ref-core-data-apis] directly, you won't have access to `userAttributes`. Instead, you need to use `securityContext` directly when referencing user attributes in access policies (e.g., in `row_level` filters or `conditions`). For example, use `securityContext.userId` instead of `userAttributes.userId`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      access_policy:
        - group: manager
          row_level:
            filters:
              - member: country
                operator: equals
                values: [ "{ securityContext.country }" ]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    access_policy: [
      {
        group: `manager`,
        row_level: {
          filters: [
            {
              member: `country`,
              operator: `equals`,
              values: [ securityContext.country ]
            }
          ]
        }
      }
    ]
  })
  ```
</CodeGroup>

[ref-mls-public]: /docs/data-modeling/access-control/member-level-security#managing-member-level-access

[ref-sec-ctx]: /docs/data-modeling/access-control/context

[ref-ref-dap]: /reference/data-modeling/data-access-policies

[ref-ref-dap-masking]: /reference/data-modeling/data-access-policies#member-masking

[ref-ref-mask-dim]: /reference/data-modeling/dimensions#mask

[ref-core-data-apis]: /reference/core-data-apis


# Data Model IDE
Source: https://docs.cube.dev/docs/data-modeling/data-model-ide

Covers the browser code editor for full data modeling features, branch-based dev APIs, and testing model changes before they reach production traffic.

Data model editor provides the code-first experience for building and enhancing the
[data model][ref-data-modeling] of your semantic layer from within your web browser.

Unlike the [Visual Modeler][ref-visual-model] editor, it provides the freedom to use all
available data modeling features at the expense of a code-centric experience.

Cube Cloud can create branch-based development API instances to quickly test
changes in the data model in your frontend applications before pushing them into
production.

<iframe title="Loom video" />

## Development Mode

In development mode, you can safely make changes to your project without
affecting production deployment. Development mode uses a separate Git branch and
allows testing your changes in Playground or via a separate API endpoint
specific to this branch. This development API hot-reloads your data model
changes, allowing you to quickly test API changes from your applications.

To enter development mode, navigate to the **Data Model** screen and
click **Dev Mode**.

<Frame>
  <img alt="Entering dev mode" />
</Frame>

If you are entering development mode from the main branch, you will be asked to
choose an existing branch or create a new one. You can configure whether it's possible
to commit directly to the main branch in the deployment settings.

<Frame>
  <img alt="Entering dev mode modal" />
</Frame>

When development mode is active, the status of the development API will be shown
at the top of the screen. After any changes to the project, the API
will hot-reload, and the API status will indicate when it's ready.

You can exit development mode by clicking **Dev Mode X** in the purple banner. If
you've been editing a data model and navigate away, Cube Cloud will warn you if
there are any unsaved changes:

<Frame>
  <img alt="Unsaved changes warning modal" />
</Frame>

## Git integration

To add more Git branches to your Cube Cloud deployment and/or switch between
them, click the branch name in the status bar:

<Frame>
  <img alt="Branch switcher" />
</Frame>

Speaking of Git branches, you can now easily add and remove branches with the
same switcher; click **Add Branch** and enter a name for the new branch
in the popup:

<Frame>
  <img alt="Create a new branch" />
</Frame>

These branches are shared, meaning everyone who has access to the deployment can
see and edit them. This makes them extremely useful for out-of-band experiments
where you can quickly test things in Cube Cloud without having to go through a
CI/CD process.

Unused branches can also be deleted. Ensure you are already on the branch you
want to delete, then open the switcher and click **Remove Branch**:

<Frame>
  <img alt="Delete a branch" />
</Frame>

To share a link to the branch you're currently viewing, click the copy-link
button next to the branch switcher. It copies the current URL with
`?branch=<branch-name>` appended; opening that link switches the recipient to
the same branch.

## Generating data model files

You can generate data model files when [creating a new
deployment][ref-creating-deployment] or at later moment. To open the data model
wizard, click on the **...** button on the right and select **Generate
data model**:

<Frame>
  <img />
</Frame>

It is safe to generate data model files for tables that already have matching cubes.
In that case, existing files will be renamed by appending `.backup` to their names.
You would also be able to review changes to files on the **Changes** tab:

<Frame>
  <img />
</Frame>

[ref-data-modeling]: /docs/data-modeling/overview

[ref-creating-deployment]: /admin/deployment#creating-a-new-deployment

[ref-visual-model]: /docs/data-modeling/visual-modeler


# Development mode
Source: https://docs.cube.dev/docs/data-modeling/dev-mode

Outlines development mode in Cube Cloud—branch-scoped APIs, save and commit flows, and safe iteration before promoting changes to production.

Development mode allows to test and debug the data model in an isolated
[development environment][ref-environments-dev] before releasing any changes to production.

<Warning>
  This page describes development mode in the Cube cloud platform. It is unrelated to
  Cube Core's development mode — which is on when
  [`CUBEJS_DEV_MODE=true`](/reference/configuration/environment-variables#cubejs_dev_mode)
  or whenever `NODE_ENV` is not `production` — and which is an **authentication bypass**.
  Under the `cubejs` CLI and the official Docker images, setting the flag also forces
  `NODE_ENV=development`, switching off JWT verification on the data APIs. Playground's
  endpoints are served with no authentication at all, so
  anyone who can reach the instance can mint an API token carrying any security context
  (signed with the API secret), read the data model, and overwrite it and `.env`. With
  `CUBEJS_DEV_MODE=true` and no
  [`CUBEJS_SQL_PASSWORD`](/reference/configuration/environment-variables#cubejs_sql_password)
  set, the SQL API accepts any credentials as well. That is intentional — it is designed
  to run on a developer's local machine for ease of use and debugging. Never use it in
  production, and using it in the Cube cloud platform is highly discouraged because it
  bypasses the platform's security model.
</Warning>

When you enter the development mode, you'll have access to your personal API endpoints
that will track the branch you're on and will be updated automatically when you make
changes to the data model.

## Development flow

### Save changes

When you make changes to the data model, you can save them by clicking the "Save all" button in the actions bar at the top of the screen.

<Frame>
  <img alt="Save all button" />
</Frame>

### Commit & Sync

After saving changes, you can commit them to the branch you're working on by clicking the "Commit & Sync" button in the actions bar.

<Frame>
  <img alt="Commit & Sync button" />
</Frame>

<Frame>
  <img alt="Commit & Sync modal" />
</Frame>

### Merge or Create a Pull Request

After committing changes, you can merge them into the parent branch or create a pull request by clicking the "Merge" or "Create a Pull Request" button in the actions bar.

<Frame>
  <img alt="Merge and Create a Pull Request buttons" />
</Frame>

<Frame>
  <img alt="Merge modal" />
</Frame>

### Updating the branch

When there are changes in the parent branch, you can update your active branch by pulling changes from the parent branch.
If your active branch got updated in the connected repository, you can update it by pulling changes from the remote.

<Frame>
  <img alt="Pull from Parent branch button" />
</Frame>

### Resolving conflicts

In some cases, you may encounter conflicts when merging or pulling changes from the parent branch or remote.
If this happens, you'll see a warning about conflicts in the actions bar.
You'll then be able to either resolve them manually or discard the changes.

<Frame>
  <img alt="Conflict Resolution UI" />
</Frame>

## Deep-link into development mode

You can link directly into development mode on the Semantic Model IDE by
adding query parameters to the page URL:

* `?branch=<name>` switches to the given branch, entering development mode
  if you're already in it (or staying read-only otherwise).
* `?devmode=true` enters development mode on the current branch. Combine it
  with `?branch=` to enter development mode on a specific branch in one step:

```text theme={"dark"}
https://your-tenant.cubecloud.dev/d/DEPLOYMENT_ID/schema?branch=my-branch&devmode=true
```

Both parameters are stripped from the URL once applied. They're a no-op for
users without permission to use development mode.

## Finding endpoints

In Development Mode, you'll have dedicated endpoints that will track the branch you're on.
They will be shown on the Overview page:

<div>
  <img alt="Development Mode Overview page showing available endpoints" />
</div>

Read more about the available endpoints on the [Environments][ref-environments-endpoints] page.

## Behavior with CLI deployments

Development mode is fully available on deployments that are configured to
[deploy with CLI][ref-deploy-with-cli]: you can enter dev mode, switch
branches, save and commit changes, and merge into the production branch from
the Cube Cloud UI.

However, on CLI deployments, **none of these actions trigger a production
build or redeploy** — production only changes when somebody explicitly runs
`cubejs-cli deploy` against the deployment, and the next deploy overwrites
any changes made through the UI. See [Deploy with CLI →
Development mode][ref-deploy-with-cli-dev-mode] for the full behavior.

## Limitations

The Development API has some limitations compared to Production, and it is
important to be aware of these as they may affect your development process.

### Autoscaling

The Development API **does not** support autoscaling. If you need to test
autoscaling, we recommend creating a separate deployment using a different Git
branch of the same repository.

### Scheduled refresh

Scheduled refresh is also disabled in the Development API. If you need to test
scheduled refreshes, we recommend creating a separate deployment using a
different Git branch of the same repository.

[ref-environments-dev]: /admin/deployment/environments#development-environments

[ref-environments-endpoints]: /admin/deployment/environments#api-endpoints

[ref-deploy-with-cli]: /admin/deployment/continuous-deployment#deploy-with-cli

[ref-deploy-with-cli-dev-mode]: /admin/deployment/continuous-deployment#development-mode-with-cli-deployments


# Dimensions
Source: https://docs.cube.dev/docs/data-modeling/dimensions

Dimensions are attributes that describe individual rows of data — the fields you group by and filter on, such as status, city, or created_at.

Dimensions represent attributes of individual rows in your data. They are
the fields you group by and filter on — things like `status`, `city`,
`product_name`, or `created_at`. Each dimension maps to a column or SQL
expression in your data source.

<Note>
  See the [dimensions reference][ref-dimensions-ref] for the full list of
  parameters and configuration options.
</Note>

## Defining dimensions

A dimension specifies the SQL expression and its type:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: status
          sql: status
          type: string

        - name: created_at
          sql: created_at
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    dimensions: {
      id: { sql: `id`, type: `number`, primary_key: true },
      status: { sql: `status`, type: `string` },
      created_at: { sql: `created_at`, type: `time` }
    }
  })
  ```
</CodeGroup>

### Dimension types

| Data type in SQL               | Dimension type in Cube |
| ------------------------------ | ---------------------- |
| `timestamp`, `date`, `time`    | [`time`][ref-type]     |
| `text`, `varchar`              | [`string`][ref-type]   |
| `integer`, `bigint`, `decimal` | [`number`][ref-type]   |
| `boolean`                      | [`boolean`][ref-type]  |

### Primary keys

Every cube that participates in [joins][ref-joins] should define a
[`primary_key`][ref-primary-key] dimension. Cube uses primary keys to avoid
fanouts — when rows get duplicated during joins and aggregates are
over-counted. Composite primary keys can be created by concatenating columns:

```yaml theme={"dark"}
dimensions:
  - name: composite_key
    sql: "CONCAT({CUBE}.order_id, '-', {CUBE}.product_id)"
    type: string
    primary_key: true
```

## Time dimensions

Time dimensions are dimensions of the [`time` type][ref-type]. They enable
grouping by time granularity (year, quarter, month, week, day, hour, minute,
second) and are essential for time-series analysis.

```yaml theme={"dark"}
dimensions:
  - name: created_at
    sql: created_at
    type: time
```

When queried, you can group by any built-in granularity without defining
additional dimensions.

### Custom granularities

You can define [custom granularities][ref-granularities] for time dimensions
when the built-in ones don't fit — for example, weeks starting on Sunday
or fiscal years:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      dimensions:
        - name: created_at
          sql: created_at
          type: time
          granularities:
            - name: sunday_week
              interval: 1 week
              offset: -1 day

            - name: fiscal_year
              interval: 1 year
              offset: 1 month
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    dimensions: {
      created_at: {
        sql: `created_at`,
        type: `time`,
        granularities: {
          sunday_week: { interval: `1 week`, offset: `-1 day` },
          fiscal_year: { interval: `1 year`, offset: `1 month` }
        }
      }
    }
  })
  ```
</CodeGroup>

Time dimensions are essential for performance features like
[partitioned pre-aggregations][ref-partition-preaggs] and
[incremental refreshes][ref-incremental-preaggs].

<Note>
  See the following recipes:

  * For a [custom granularity][ref-custom-granularity-recipe] example.
  * For a [custom calendar][ref-custom-calendar-recipe] example.
</Note>

## Proxy dimensions

Proxy dimensions reference dimensions from the same cube or other cubes,
providing a way to reuse existing definitions and reduce code duplication.

### Within the same cube

Reference existing dimensions to build derived ones without duplicating SQL:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      dimensions:
        - name: initials
          sql: "SUBSTR(first_name, 1, 1)"
          type: string

        - name: last_name
          sql: "UPPER(last_name)"
          type: string

        - name: full_name
          sql: "{initials} || '. ' || {last_name}"
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    dimensions: {
      initials: { sql: `SUBSTR(first_name, 1, 1)`, type: `string` },
      last_name: { sql: `UPPER(last_name)`, type: `string` },
      full_name: { sql: `${initials} || '. ' || ${last_name}`, type: `string` }
    }
  })
  ```
</CodeGroup>

### From other cubes

If cubes are [joined][ref-joins], you can bring a dimension from one cube
into another. Cube generates the necessary joins automatically:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      joins:
        - name: users
          sql: "{CUBE}.user_id = {users.id}"
          relationship: many_to_one

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: user_name
          sql: "{users.name}"
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    joins: {
      users: {
        sql: `${CUBE}.user_id = ${users.id}`,
        relationship: `many_to_one`
      }
    },

    dimensions: {
      id: { sql: `id`, type: `number`, primary_key: true },
      user_name: { sql: `${users.name}`, type: `string` }
    }
  })
  ```
</CodeGroup>

### Time dimension granularity references

When referencing a time dimension, you can specify a granularity to create
a proxy dimension at that specific granularity — including
[custom granularities](#custom-granularities):

```yaml theme={"dark"}
dimensions:
  - name: created_at
    sql: created_at
    type: time
    granularities:
      - name: sunday_week
        interval: 1 week
        offset: -1 day

  - name: created_at_year
    sql: "{created_at.year}"
    type: time

  - name: created_at_sunday_week
    sql: "{created_at.sunday_week}"
    type: time
```

## Subquery dimensions

Subquery dimensions reference [measures][ref-measures-page] from other cubes,
effectively turning an aggregate into a per-row value. This enables nested
aggregations — for example, calculating the average of per-customer order counts.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      joins:
        - name: users
          sql: "{users}.id = {CUBE}.user_id"
          relationship: many_to_one

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

      measures:
        - name: count
          type: count

    - name: users
      sql_table: users

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: name
          sql: name
          type: string

        - name: order_count
          sql: "{orders.count}"
          type: number
          sub_query: true

      measures:
        - name: avg_order_count
          sql: "{order_count}"
          type: avg
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    joins: {
      users: {
        sql: `${users}.id = ${CUBE}.user_id`,
        relationship: `many_to_one`
      }
    },

    dimensions: {
      id: { sql: `id`, type: `number`, primary_key: true }
    },

    measures: {
      count: { type: `count` }
    }
  })

  cube(`users`, {
    sql_table: `users`,

    dimensions: {
      id: { sql: `id`, type: `number`, primary_key: true },
      name: { sql: `name`, type: `string` },

      order_count: {
        sql: `${orders.count}`,
        type: `number`,
        sub_query: true
      }
    },

    measures: {
      avg_order_count: {
        sql: `${order_count}`,
        type: `avg`
      }
    }
  })
  ```
</CodeGroup>

The `order_count` subquery dimension computes the order count per user.
The `avg_order_count` measure then averages those per-user values. Cube
implements this as a correlated subquery via joins for optimal performance.

<Note>
  See the following recipes:

  * How to calculate [nested aggregates][ref-nested-aggregates-recipe].
  * How to calculate [filtered aggregates][ref-filtered-aggregates-recipe].
</Note>

## Links

Dimensions can declare **links** — clickable navigation targets that supporting
tools (such as [Cube Cloud Workbooks][ref-workbooks]) surface next to the
dimension's values.

`links` is a **list**, so a single dimension can declare **any number of
links** — they all appear together in the cell menu. Each link points either to
an **external URL** (`url`) or to **another Cube Cloud dashboard** (`dashboard`,
a drill-in), and its URL is built per row from the dimension's data. The example
below declares two links on one dimension (an external search and a drill-in).

<Note>
  Dimension `links` require Cube **v1.6.53** or newer.
</Note>

### Parameters

`links` is a list of link objects. Each link accepts:

| Parameter   | Required?                       | Description                                                                                                                                                                                                                                                                                                                         |
| ----------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | **Required**                    | Identifier, unique within the dimension. Also used in the synthetic dimension name (see [Behavior](#behavior)).                                                                                                                                                                                                                     |
| `label`     | **Required**                    | The text shown for the link in the UI.                                                                                                                                                                                                                                                                                              |
| `url`       | **Either `url` or `dashboard`** | SQL expression that builds an **external** URL per row. May [reference][ref-references] columns and other dimensions.                                                                                                                                                                                                               |
| `dashboard` | **Either `url` or `dashboard`** | The target Cube Cloud dashboard's **slug** (a **drill-in**). Each link sets exactly one of `url` or `dashboard` — never both — but different links on the same dimension can mix the two.                                                                                                                                           |
| `icon`      | Optional                        | A [Tabler icon][link-tabler] name (see [Icons](#icons)). Defaults to a generic link icon.                                                                                                                                                                                                                                           |
| `primary`   | Optional                        | Marks the link that renders **inline** on the cell value (see [Behavior](#behavior)). At most one link per dimension may set it.                                                                                                                                                                                                    |
| `target`    | Optional                        | Where to open the link: `blank` (new tab) or `self` (same tab). The default depends on the link kind — `url:` links default to `blank`, `dashboard:` drill-ins default to `self` (in-app). An explicit `target` is honored for both (on `dashboard:` drill-ins this requires Cube **v1.7.5** or newer; see [Behavior](#behavior)).  |
| `params`    | Optional                        | Extra per-row parameters. For `url:` they are appended as query parameters. For `dashboard:` they become **equality filters** on the target dashboard — each `key` is a member of the target dashboard's view (a cube path such as `orders.status` is auto-resolved to the matching view member), and `value` is the per-row value. |

### Example

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      dimensions:
        - name: status
          sql: status
          type: string
          links:
            # External link — opens a URL built from the row's value.
            # `primary` makes it render inline on the cell value.
            - name: search
              label: Search the web
              url: "CONCAT('https://www.google.com/search?q=order+', {CUBE}.status)"
              icon: brand-google
              target: blank
              primary: true

            # Drill-in link — opens another Cube Cloud dashboard, filtered by the row
            - name: details
              label: Open order details
              dashboard: orders-detail   # the target dashboard's slug
              params:
                - key: orders_view.status
                  value: "{CUBE}.status"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    dimensions: {
      status: {
        sql: `status`,
        type: `string`,
        links: [
          // External link — opens a URL built from the row's value.
          // `primary` makes it render inline on the cell value.
          {
            name: `search`,
            label: `Search the web`,
            url: `CONCAT('https://www.google.com/search?q=order+', ${CUBE}.status)`,
            icon: `brand-google`,
            target: `blank`,
            primary: true
          },
          {
            name: `details`,
            label: `Open order details`,
            dashboard: `orders-detail`,
            params: [{ key: `orders_view.status`, value: `${CUBE}.status` }]
          }
        ]
      }
    }
  })
  ```
</CodeGroup>

### Icons

`icon` accepts any name from the [Tabler icon set][link-tabler] — the
kebab-case name **without** any prefix, for example `brand-google`,
`external-link`, `layout-dashboard`, or `send`. Browse and search the available
names at [tabler.io/icons][link-tabler]. If `icon` is omitted, a default link
icon is shown.

### Setting a dashboard slug

A `dashboard:` link targets another dashboard by its **slug** — a short, stable,
human-readable identifier (e.g. `orders-detail`). The slug is **portable across
environments**: it is resolved within the current deployment, so the same model
works in development and production without hardcoding dashboard IDs.

To set a slug in Cube Cloud, open the target dashboard, open its **options
sidebar**, and fill the **Slug** field (see
[Dashboards → Dashboard slug](/docs/explore-analyze/dashboards#dashboard-slug)).
Slugs are **unique per deployment**, and the `dashboard:` value in your link must
match the slug exactly.

**There is no required order.** You can write the `dashboard:` slug in the model
first (it won't break anything — a link whose slug doesn't yet resolve is simply
skipped in the cell menu) and set the dashboard's slug later, or set the
dashboard slug first and reference it from the model afterwards. The link starts
working as soon as both sides use the same slug.

### Behavior

* **Per-row resolution** — each link's `url` (and its `params`) is evaluated for
  every row, so the destination reflects the clicked cell. Internally a link
  compiles to a hidden **synthetic dimension** named
  `<dimension>___link_<name>_url` holding the resolved URL; it is added to the
  query automatically and is never shown as a column.
* **Null values** — if the source value (and thus the resolved URL) is null for
  a row, that link is omitted from the menu for that row.
* **Where links appear** — in Cube Cloud, links surface in the table
  [**cell menu**](/docs/explore-analyze/charts/chart-types/table#cell-menu) on
  every results table (dashboard and workbook table charts, embedded dashboards,
  and Explore / SQL results). A left-click on a cell opens the menu listing the
  dimension's links, alongside **Copy value** and, on measures, **Drill down**.
* **Inline rendering** — the link marked `primary` also renders **inline**, as a
  clickable link on the cell value itself, with no chart configuration. The
  remaining links stay in the cell menu, which still lists every link. In a
  workbook table chart, the **Style** tab can override which declared link
  renders inline for a column; see
  [Inline links](/docs/explore-analyze/charts/chart-types/table#inline-links).
* **Drill-in vs external** — a `dashboard:` link navigates **in-app, in the same
  tab** by default; an explicit `target` is honored (`blank` opens a new tab,
  `self` stays in-app), and a Cmd/Ctrl-click always opens a new tab. A `url:`
  link opens per its `target` (`blank` by default). Honoring an explicit `target`
  on a drill-in requires Cube **v1.7.5** or newer — older runtimes always navigate
  drill-ins in-app regardless of `target`.
* **Filters** — for `dashboard:` links, each `params` entry becomes an
  **equality filter** on the target (the `key` is a view member, the `value` is
  the per-row value). An unknown or inaccessible target slug is skipped
  gracefully — the user is notified and no navigation happens.

See the [`links` reference][ref-dimensions-ref] for the canonical parameter
list.

## Hierarchies

Dimensions can be organized into [hierarchies][ref-hierarchies] to define
drill-down paths (e.g., Country → State → City):

```yaml theme={"dark"}
cubes:
  - name: users
    # ...

    dimensions:
      - name: country
        sql: country
        type: string

      - name: state
        sql: state
        type: string

      - name: city
        sql: city
        type: string

    hierarchies:
      - name: location
        levels:
          - country
          - state
          - city
```

## Next steps

* See the [dimensions reference][ref-dimensions-ref] for all parameters
* Learn about [measures][ref-measures-page] for aggregated calculations
* Explore [custom granularities][ref-granularities] for fiscal calendars
  and non-standard time periods

[ref-dimensions-ref]: /reference/data-modeling/dimensions

[ref-workbooks]: /docs/explore-analyze/workbooks

[ref-references]: /docs/data-modeling/concepts/syntax#references

[link-tabler]: https://tabler.io/icons

[ref-measures-page]: /docs/data-modeling/measures

[ref-joins]: /docs/data-modeling/joins

[ref-type]: /reference/data-modeling/dimensions#type

[ref-primary-key]: /reference/data-modeling/dimensions#primary_key

[ref-granularities]: /reference/data-modeling/dimensions#granularities

[ref-hierarchies]: /reference/data-modeling/hierarchies

[ref-partition-preaggs]: /docs/pre-aggregations/matching-pre-aggregations#partitioning

[ref-incremental-preaggs]: /reference/data-modeling/pre-aggregations#incremental

[ref-custom-granularity-recipe]: /recipes/data-modeling/custom-granularity

[ref-custom-calendar-recipe]: /recipes/data-modeling/custom-calendar

[ref-nested-aggregates-recipe]: /recipes/data-modeling/nested-aggregates

[ref-filtered-aggregates-recipe]: /recipes/data-modeling/filtered-aggregates


# Export and import
Source: https://docs.cube.dev/docs/data-modeling/dynamic/code-reusability-export-and-import

This functionality only works with data models written in JavaScript, not YAML.

<Info>
  This functionality only works with data models written in JavaScript, not YAML.
</Info>

In Cube, your data model is code, and code is much easier to manage when it is
in small, digestible chunks. It is best practice to keep files small and
containing only relevant and non-duplicated code. As your data model grows,
maintaining and debugging is much easier with a well-organized codebase.

Cube data models in JavaScript supports ES6-style [`export`][mdn-js-es6-export]
and [`import`][mdn-js-es6-import] statements, which allow writing code in one
file and sharing it, so it can be used by another file or files.

There are several typical use cases in Cube where it is considered best practice
to extract some variables or functions and then import it when needed.

## Managing constants

Quite often, you may want to have an array of test user IDs to exclude from your
analysis. You can define it once and `export` it like this:

```javascript theme={"dark"}
// in constants.js
export const TEST_USER_IDS = [1, 2, 3, 4, 5]
```

Later, you can `import` into the cube whenever needed:

```javascript theme={"dark"}
// in Users.js
import { TEST_USER_IDS } from "./constants"

cube(`users`, {
  // ...

  measures: {
    // ...
  },

  dimensions: {
    // ...
  },

  segments: {
    exclude_test_users: {
      sql: `${CUBE}.id NOT IN (${TEST_USER_IDS.join(", ")})`
    }
  }
})
```

## Helper functions

You can assign some commonly used SQL snippets to JavaScript functions. The
example below shows a parsing helper function, which can be used across any
number of cubes to correctly parse a date if it was stored as a string.

You can read more about working with [string time dimensions
here][ref-schema-string-time-dims].

```javascript theme={"dark"}
// in helpers.js
export const parseDateWithTimeZone = (column) =>
  `PARSE_TIMESTAMP('%F %T %Ez', ${column})`
```

```javascript theme={"dark"}
// in events.js
import { parseDateWithTimeZone } from "./helpers"

cube(`events`, {
  sql_table: `events`,
  // ...

  dimensions: {
    date: {
      sql: `${parseDateWithTimeZone("date")}`,
      type: `time`
    }
  }
})
```

## Import from parent directories

You may need to import from parent directories as Cube flattens nested
directories. The example below shows a correct way to import a helper function,
which is located in a parent directory.

```tree theme={"dark"}
.
├── README.md
├── cube.js
├── package.json
└── model/
    ├── shared_utils/
    │   └── utils.js
    └── sales/
        └── orders.js
```

```javascript theme={"dark"}
// in model/sales/orders.js
import { capitalize } from "./shared_utils/utils"
```

```javascript theme={"dark"}
// in model/shared_utils/utils.js
export const capitalize = (s) => s.charAt(0).toUpperCase() + s.slice(1)
```

[mdn-js-es6-export]: https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export

[mdn-js-es6-import]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import

[ref-schema-string-time-dims]: /recipes/data-modeling/string-time-dimensions


# Dynamic Data Models
Source: https://docs.cube.dev/docs/data-modeling/dynamic/index

Generate data models programmatically using Jinja with Python or JavaScript for dynamic schema creation.

Cube supports authoring data models dynamically — useful for de-duplicating
common patterns across cubes, generating models from a remote source, or
adapting the schema per tenant at runtime.

Pick the approach that matches the language your data models are written in:

<CardGroup>
  <Card title="Jinja & Python" icon="brand-python" href="/docs/data-modeling/dynamic/jinja">
    Template YAML data models with Jinja, and use Python for loops, includes,
    and runtime generation.
  </Card>

  <Card title="JavaScript" icon="brand-javascript" href="/docs/data-modeling/dynamic/javascript">
    Generate cubes and views on-the-fly from JavaScript data models using
    `asyncModule()`.
  </Card>
</CardGroup>

## How it fits together

The diagrams below show how YAML and JavaScript data models are parsed and
compiled before they're served by Cube.

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>


# Data modeling with JavaScript
Source: https://docs.cube.dev/docs/data-modeling/dynamic/javascript

This functionality only works with data models written in JavaScript, not YAML.

<Info>
  This functionality only works with data models written in JavaScript, not YAML.

  For similar functionality in YAML, see [Dynamic data models with Jinja and Python](/docs/data-modeling/dynamic/jinja).
</Info>

Cube allows data models to be created on-the-fly using a special
[`asyncModule()`][ref-async-module] function only available in the
[execution environment][ref-schema-env]. `asyncModule()` allows registering an
async function to be executed at the end of the data model compile phase so
additional definitions can be added. This is often useful in situations where
data model properties can be dynamically updated through an API, for example.

<Warning>
  Each `asyncModule` call will be invoked only once per data model compilation.
</Warning>

[ref-schema-env]: /docs/data-modeling/dynamic/schema-execution-environment

[ref-async-module]: /docs/data-modeling/dynamic/schema-execution-environment#asyncmodule

When creating data models via `asyncModule()`, it is important to be aware of
the following differences compared to statically defined ones with `cube()`:

* The `sql` and `drill_members` properties for both dimensions and measures must
  be of type `() => string` and `() => string[]` accordingly

Cube supports importing JavaScript logic from other files in a data model, so it
is useful to declare utility functions for handling the above differences in a
separate file:

```javascript theme={"dark"}
// model/utils.js
export const convertStringPropToFunction = (propNames, dimensionDefinition) => {
  let newResult = { ...dimensionDefinition };
  propNames.forEach((propName) => {
    const propValue = newResult[propName];

    if (!propValue) {
      return;
    }

    newResult[propName] = () => propValue;
  });
  return newResult;
};

export const transformDimensions = (dimensions) => {
  return Object.keys(dimensions).reduce((result, dimensionName) => {
    const dimensionDefinition = dimensions[dimensionName];
    return {
      ...result,
      [dimensionName]: convertStringPropToFunction(
        ["sql"],
        dimensionDefinition
      ),
    };
  }, {});
};

export const transformMeasures = (measures) => {
  return Object.keys(measures).reduce((result, dimensionName) => {
    const dimensionDefinition = measures[dimensionName];
    return {
      ...result,
      [dimensionName]: convertStringPropToFunction(
        ["sql", "drill_members"],
        dimensionDefinition
      ),
    };
  }, {});
};
```

## Generation

In the following example, we retrieve a JSON object representing all our cubes
using `fetch()`, transform some of the properties to be functions that return a
string, and then finally use the [`cube()` global function][ref-globals] to
generate data models from that data:

[ref-globals]: /docs/data-modeling/dynamic/schema-execution-environment#cube-js-globals-cube-and-others

```javascript theme={"dark"}
// model/cubes/DynamicDataModel.js
const fetch = require("node-fetch");
import {
  convertStringPropToFunction,
  transformDimensions,
  transformMeasures,
} from "./utils";

asyncModule(async () => {
  const dynamicCubes = await (
    await fetch("http://your-api-endpoint/dynamicCubes")
  ).json();

  console.log(dynamicCubes);
  // [
  //   {
  //      name: 'dynamic_cube_model',
  //      sql_table: 'my_table',
  //
  //      measures: {
  //        price: {
  //          sql: `price`,
  //          type: `number`,
  //        }
  //      },
  //
  //      dimensions: {
  //        color: {
  //          sql: `color`,
  //          type: `string`,
  //        },
  //      },
  //   },
  // ]

  dynamicCubes.forEach((dynamicCube) => {
    const dimensions = transformDimensions(dynamicCube.dimensions);
    const measures = transformMeasures(dynamicCube.measures);

    cube(dynamicCube.name, {
      sql: dynamicCube.sql,
      dimensions,
      measures,
      pre_aggregations: {
        main: {
          // ...
        },
      },
    });
  });
});
```

## Usage with `schema_version`

It is also useful to be able to recompile the data model when there are changes
in the underlying input data. For this purpose, the [`schema_version`
][link-config-schema-version] value in the `cube.js` configuration options can
be specified as an asynchronous function:

```javascript theme={"dark"}
// cube.js
module.exports = {
  schemaVersion: async ({ securityContext }) => {
    const schemaVersions = await (
      await fetch("http://your-api-endpoint/schema_version")
    ).json();

    return schemaVersions[securityContext.tenantId];
  },
};
```

[link-config-schema-version]: /reference/configuration/config#schema_version

## Usage with COMPILE\_CONTEXT

The `COMPILE_CONTEXT` global object can also be used in conjunction with async
data model creation to allow for multi-tenant deployments of Cube.

In an example scenario where all tenants share the same cube, but see different
dimensions and measures, you could do the following:

```javascript theme={"dark"}
// model/cubes/DynamicDataModel.js
const fetch = require("node-fetch");
import {
  convertStringPropToFunction,
  transformDimensions,
  transformMeasures,
} from "./utils";

asyncModule(async () => {
  const {
    securityContext: { tenantId },
  } = COMPILE_CONTEXT;

  const dynamicCubes = await (
    await fetch(`http://your-api-endpoint/dynamicCubes`)
  ).json();

  const allowedDimensions = await (
    await fetch(`http://your-api-endpoint/dynamicDimensions/${tenantId}`)
  ).json();

  const allowedMeasures = await (
    await fetch(`http://your-api-endpoint/dynamicMeasures/${tenantId}`)
  ).json();

  dynamicCubes.forEach((dynamicCube) => {
    const dimensions = transformDimensions(allowedDimensions);
    const measures = transformMeasures(allowedMeasures);

    cube(dynamicCube.name, {
      sql: dynamicCube.sql,
      title: `${dynamicCube.title}-${tenantId}`,
      dimensions,
      measures,
      pre_aggregations: {
        main: {
          // ...
        },
      },
    });
  });
});
```

## Usage with data\_source

When using multiple databases, you'll need to ensure you set the
[`data_source`][ref-schema-datasource] property for any asynchronously-created
data models, as well as ensuring the corresponding database drivers are set up with
[`driverFactory()`][ref-config-driverfactory] in your [`cube.js` configuration
file][ref-config].

[ref-schema-datasource]: /reference/data-modeling/cube#data_source

[ref-config-driverfactory]: /reference/configuration/config#driver_factory

[ref-config]: /reference/configuration/config

For an example scenario where data models may use either MySQL or Postgres
databases, you could do the following:

```javascript theme={"dark"}
// model/cubes/DynamicDataModel.js
const fetch = require("node-fetch");
import {
  convertStringPropToFunction,
  transformDimensions,
  transformMeasures,
} from "./utils";

asyncModule(async () => {
  const dynamicCubes = await (
    await fetch("http://your-api-endpoint/dynamicCubes")
  ).json();

  dynamicCubes.forEach((dynamicCube) => {
    const dimensions = transformDimensions(dynamicCube.dimensions);
    const measures = transformMeasures(dynamicCube.measures);

    cube(dynamicCube.name, {
      data_source: dynamicCube.data_source,
      sql: dynamicCube.sql,
      dimensions,
      measures,
      pre_aggregations: {
        main: {
          // ...
        },
      },
    });
  });
});
```

```javascript theme={"dark"}
// cube.js
const MySQLDriver = require("@cubejs-backend/mysql-driver");
const PostgresDriver = require("@cubejs-backend/postgres-driver");

module.exports = {
  driverFactory: ({ dataSource }) => {
    if (dataSource === "mysql") {
      return new MySQLDriver({ database: dataSource });
    }

    return new PostgresDriver({ database: dataSource });
  },
};
```


# Data modeling with YAML, Jinja, and Python
Source: https://docs.cube.dev/docs/data-modeling/dynamic/jinja

Jinja and Python techniques for templating YAML models—loops, includes, and runtime generation—to keep large or multi-tenant schemas maintainable.

Cube supports authoring dynamic data models using the [Jinja templating
language][jinja] and Python. This allows de-duplicating common patterns in your data models
as well as dynamically generating data models from a remote data source.

Jinja is supported in all YAML data model files.

## YAML

It is recommended to default to YAML syntax because of its simplicity and readability.

### Folded and literal strings

Sometimes you might want to use multi-line strings in YAML-based data models, e.g.,
in parameters such as `sql` or `description`. It is recommended to use [literal][ref-yaml-literal]
(`|`) string style in such cases as it preserves line breaks.

```yaml theme={"dark"}
cubes:
  - name: orders
    description: |
      This cube represents customer orders.
      It includes measures for total sales and order count.
    sql: |
      -- Fetch only relevant columns
      SELECT id, created_at, total_amount
      FROM staging.orders
```

## Jinja

Please check the [Jinja documentation][jinja-docs] for details on Jinja syntax.

### Previewing YAML

You can preview the data model code after applying Jinja templates in the **[Data
Model][ref-data-model-editor]** editor by clicking **... → Jinja Preview**
on files that contain Jinja templates in the sidebar.

<Note>
  Currently, there's no way to preview the data model code in YAML after applying
  Jinja templates in Cube Core. Please [track this issue](https://github.com/cube-js/cube/issues/8134).
</Note>

You can also view the resulting data model in [Playground][ref-payground] and [Visual
Model][ref-visual-model]. Also, you can introspect the data model using the
[`/v1/meta` REST (JSON) API endpoint][ref-meta-api].

### Loops

Jinja supports [looping][jinja-docs-for-loop] over lists and dictionaries. In
the following example, we loop over a list of nested properties and generate a
`LEFT JOIN UNNEST` clause for each one: for each one:

```yaml theme={"dark"}
{%- set nested_properties = [
  "referrer",
  "href",
  "host",
  "pathname",
  "search"
] -%}

cubes:
  - name: analytics
    sql: |
      SELECT
      {%- for prop in nested_properties %}
        {{ prop }}_prop.value AS {{ prop }}
      {%- endfor %}
      FROM public.events
      {%- for prop in nested_properties %}
      LEFT JOIN UNNEST(properties) AS {{ prop }}_prop ON {{ prop }}_prop.key = '{{ prop }}'
      {%- endfor %}
```

Another useful pattern is to loop over a dictionary of values and generate a
measure for each one, as in the following example:

```yaml theme={"dark"}
{%- set metrics = {
  "mau": 30,
  "wau": 7,
  "day": 1
} %}

cubes:
  - name: orders
    sql_table: public.orders

    measures:
      {%- for name, days in metrics | items %}
      - name: {{ name | safe }}
        type: count_distinct
        sql: user_id
        rolling_window:
          trailing: {{ days }} day
          offset: start
      {% endfor %}
```

### Macros

Cube data models also support Jinja macros, which allow you to define reusable
snippets of code. You can read more about macros in the [Jinja
documentation][jinja-docs-macros].

In the following example, we define a macro called `dimension()` which generates
a dimension definition in Cube. This macro is then invoked multiple times to
generate multiple dimensions:

```yaml theme={"dark"}
{# Declare the macro before using it, otherwise Jinja will throw an error. #}
{%- macro dimension(column_name, type='string', primary_key=False) -%}
      - name: {{ column_name }}
        sql: {{ column_name }}
        type: {{ type }}
        {% if primary_key -%}
        primary_key: true
        {% endif -%}
{% endmacro -%}

cubes:
  - name: orders
    sql_table: public.orders

    dimensions:
      {{ dimension('id', 'number', primary_key=True) }}
      {{ dimension('status') }}
      {{ dimension('created_at', 'time') }}
      {{ dimension('completed_at', 'time') }}
```

You could also use macros to generate SQL snippets for use in the `sql`
property:

```yaml theme={"dark"}
{%- macro cents_to_dollars(column_name, precision=2) -%}
  ({{ column_name }} / 100)::NUMERIC(16, {{ precision }})
{%- endmacro -%}

cubes:
  - name: payments
    sql: |
      SELECT
        id AS payment_id,
        {{ cents_to_dollars('amount') }} AS amount_usd
      FROM app_data.payments
```

### Reusing macros across files

You can define macros in dedicated `.jinja` files and import them into your
data model files using Jinja's [`import`][jinja-docs-import] statement. This
is useful for sharing common patterns across multiple cubes and views.

Consider the following project structure:

```tree theme={"dark"}
.
└── cube/
    ├── model/
    │   ├── cubes/
    │   │   └── orders.yml
    │   ├── views/
    │   └── macros/
    │       └── common_dimensions.jinja
    └── cube.py
```

First, define reusable macros in a `.jinja` file under the `macros/` directory:

```yamltitle="model/macros/common_dimensions.jinja" theme={"dark"}
{%- macro dimension(column_name, type='string', primary_key=False) -%}
      - name: {{ column_name }}
        sql: {{ column_name }}
        type: {{ type }}
        {% if primary_key -%}
        primary_key: true
        {% endif -%}
{% endmacro -%}

{%- macro cents_to_dollars(column_name, precision=2) -%}
  ({{ column_name }} / 100)::NUMERIC(16, {{ precision }})
{%- endmacro -%}
```

Then, import and use those macros in your data model files:

```yamltitle="model/cubes/orders.yml" theme={"dark"}
{%- import "macros/common_dimensions.jinja" as common -%}

cubes:
  - name: orders
    sql_table: public.orders

    dimensions:
      {{ common.dimension('id', 'number', primary_key=True) }}
      {{ common.dimension('status') }}
      {{ common.dimension('created_at', 'time') }}

    measures:
      - name: amount_usd
        type: sum
        sql: "{{ common.cents_to_dollars('amount') }}"
```

The import path is relative to the `model/` directory.

### Escaping unsafe strings

[Auto-escaping][jinja-docs-autoescaping] of unsafe string values in Jinja
templates is enabled by default. It means that any strings coming from Python
might get wrapped in quotes, potentially breaking YAML syntax.

You can work around that by using the [`safe` Jinja
filter][jinja-docs-filters-safe] with such string values:

```yaml theme={"dark"}
cubes:
  - name: my_cube
    description: {{ get_unsafe_string() | safe }}
```

Alternatively, you can wrap unsafe strings into instances of the following
class in your Python code, effectively marking them as safe. This is
particularly useful for library code, e.g., similar to the
[`cube_dbt`][ref-cube-dbt] package.

```python theme={"dark"}
class SafeString(str):
  is_safe: bool

  def __init__(self, v: str):
    self.is_safe = True
```

## Python

### Template context

You can use Python to declare functions that can be invoked and variables that can be
referenced from within a Jinja template. These functions and variables must be defined
in `model/globals.py` file and registered in the `TemplateContext` instance.

<Note>
  See the [`TemplateContext` reference][ref-cube-template-context] for more details.
</Note>

In the following example, we declare a function called `load_data` that supposedly loads
data from a remote API endpoint. We will then use the function to generate a data model:

```python theme={"dark"}
from cube import TemplateContext
 
template = TemplateContext()

@template.function('load_data')
def load_data():
   client = MyApiClient("example.com")
   return client.load_data()


class MyApiClient:
  def __init__(self, api_url):
    self.api_url = api_url

  # mock API call
  def load_data(self):
    api_response = {
      "cubes": [
        {
          "name": "cube_from_api",
          "measures": [
            { "name": "count", "type": "count" },
            { "name": "total", "type": "sum", "sql": "amount" }
          ],
          "dimensions": []
        },
        {
          "name": "cube_from_api_with_dimensions",
          "measures": [
            { "name": "active_users", "type": "count_distinct", "sql": "user_id" }
          ],
          "dimensions": [
            { "name": "city", "sql": "city_column", "type": "string" }
          ]
        }
      ]
    }
    return api_response
```

Now that we've decorated our function with the `@template.function` decorator, we can
call it from within a Jinja template. In the following example, we'll call the
`load_data()` function and use the result to generate a data model.

```yaml theme={"dark"}
cubes:
  {# Here we use the decorated function from earlier #}
  {%- for cube in load_data()["cubes"] %}

  - name: {{ cube.name }}

  {%- if cube.measures is not none and cube.measures|length > 0 %}
    measures:
      {%- for measure in cube.measures %}
      - name: {{ measure.name }}
        type: {{ measure.type }}
      {%- if measure.sql %}
        sql: {{ measure.sql }}
      {%- endif %}
      {%- endfor %}
  {%- endif %}

  {%- if cube.dimensions is not none and cube.dimensions|length > 0 %}
    dimensions:
      {%- for dimension in cube.dimensions %}
      - name: {{ dimension.name }}
        type: {{ dimension.type }}
        sql: {{ dimension.sql }}
      {%- endfor %}
  {%- endif %}
  {%- endfor %}
```

### Imports

In the `model/globals.py` file (or the `cube.py` configuration file), you can
import modules from the current directory. In the following example, we import a function
from the `utils` module and use it to populate a variable in the template context:

```pythontitle="model/utils.py" theme={"dark"}
def answer_to_main_question() -> str:
  return "42"
```

```pythontitle="model/globals.py" theme={"dark"}
from cube import TemplateContext
from utils import answer_to_main_question

template = TemplateContext()

answer = answer_to_main_question()
template.add_variable('answer', answer)
```

### Dependencies

If you need to use dependencies in your dynamic data model (or your `cube.py`
configuration file), you can list them in the `requirements.txt` file in the root
directory of your Cube deployment. They will be automatically installed with `pip` on
the startup.

<Info>
  [`cube` package][ref-cube-package] is available out of the box, it doesn't need to be
  listed in `requirements.txt`.
</Info>

If you use dbt for data transformation, you might find the [`cube_dbt`
package][ref-cube-dbt-package] useful. It provides a set of utilities that simplify
defining the data model in YAML [based on dbt models][ref-cube-with-dbt].

If you need to use dependencies with native extensions, build a [custom Docker
image][ref-docker-image-extension].

[jinja]: https://jinja.palletsprojects.com/

[jinja-docs]: https://jinja.palletsprojects.com/en/3.1.x/templates/

[jinja-docs-for-loop]: https://jinja.palletsprojects.com/en/3.1.x/templates/#for

[jinja-docs-macros]: https://jinja.palletsprojects.com/en/3.1.x/templates/#macros

[jinja-docs-import]: https://jinja.palletsprojects.com/en/3.1.x/templates/#import

[jinja-docs-autoescaping]: https://jinja.palletsprojects.com/en/3.1.x/api/#autoescaping

[jinja-docs-filters-safe]: https://jinja.palletsprojects.com/en/3.1.x/templates/#jinja-filters.safe

[ref-cube-dbt]: /reference/data-modeling/cube_dbt

[ref-visual-model]: /docs/data-modeling/visual-modeler

[ref-docker-image-extension]: /admin/deployment/core#extend-the-docker-image

[ref-cube-package]: /reference/data-modeling/cube-package

[ref-cube-template-context]: /reference/data-modeling/cube-package#templatecontext-class

[ref-cube-dbt-package]: /reference/data-modeling/cube_dbt

[ref-cube-with-dbt]: /recipes/data-modeling/dbt

[ref-data-model-editor]: /docs/data-modeling/data-model-ide

[ref-payground]: /docs/explore-analyze/playground

[ref-meta-api]: /reference/core-data-apis/rest-api/reference#base_path/v1/meta

[ref-yaml-literal]: https://yaml.org/spec/1.2.2/#812-literal-style

[ref-yaml-folded]: https://yaml.org/spec/1.2.2/#813-folded-style


# Execution Environment (JavaScript)
Source: https://docs.cube.dev/docs/data-modeling/dynamic/schema-execution-environment

How JavaScript model code runs inside Cube’s Node VM, including custom require, forbidden globals, and constraints compared to normal Node scripts.

Cube Data Model Compiler uses [Node.js VM][nodejs-vm] to execute data model
compiler code. It gives required flexibility allowing transpiling data model
files before they get executed, storing data models in external databases and
executing untrusted code in a safe manner. Cube data model JavaScript is
standard JavaScript supported by Node.js starting in version 8 with the
following exceptions.

## Require

Being executed in VM, data model JavaScript code doesn't have access to [Node.js
require][nodejs-require] directly. Instead `require()` is implemented by Data
Model Compiler to provide access to other data model files and to regular
Node.js modules. Besides that, the data model `require()` can resolve Cube
packages such as `Funnels` unlike standard Node.js `require()`.

## Node.js globals (process.env, console.log and others)

Data model JavaScript code doesn't have access to any standard Node.js globals
like `process` or `console`. In order to access `process.env`, utility functions
can be added outside the `model/` directory:

**tablePrefix.js:**

```javascript theme={"dark"}
exports.tableSchema = () => process.env.TABLE_SCHEMA
```

**model/cubes/Users.js**:

```javascript theme={"dark"}
import { tableSchema } from "../tablePrefix"

cube(`users`, {
  sql_table: `${tableSchema()}.users`,

  // ...
})
```

## console.log

Data models cannot access `console.log` due to a separate [VM
instance][nodejs-vm] that runs it. Suppose you find yourself writing complex
logic for SQL generation that depends on a lot of external input. In that case,
you probably want to introduce a helper service outside of the [data model
directory][ref-schema-path] that you can debug as usual Node.js code.

## Cube globals (cube and others)

Cube defines `cube()`, `context()` and `asyncModule()` global variable functions
in order to provide API for data model configuration which aren't normally
accessible outside of a Cube data model.

## Import / Export

Data model JavaScript files are transpiled to convert ES6 `import` and `export`
expressions to corresponding Node.js calls. In fact `import` is routed to
[Require][self-require] method.

`export` can be used to define named exports as well as default ones:

**constants.js:**

```javascript theme={"dark"}
export const TEST_USER_IDS = [1, 2, 3, 4, 5]
```

**usersSql.js:**

```javascript theme={"dark"}
export default (usersTable) => `select * from ${usersTable}`
```

Later, you can `import` into the cube, wherever needed:

**Users.js**:

```javascript theme={"dark"}
// in users.js
import { TEST_USER_IDS } from "./constants"
import usersSql from "./usersSql"

cube(`users`, {
  sql: usersSql(`users`),
  measures: {
    /* ... */
  },

  dimensions: {
    /* ... */
  },

  segments: {
    excludeTestUsers: {
      sql: `${CUBE}.id NOT IN (${TEST_USER_IDS.join(", ")})`
    }
  }
})
```

## asyncModule

Data models can be externally stored and retrieved through an asynchronous
operation using the `asyncModule()`. For more information, consult the [dynamic
data model creation][ref-dynamic-schemas].

## Context symbols transpile

Cube uses a custom transpiler to optimize boilerplate code around referencing
cubes and cube members. There are reserved property names inside `cube`
definition that undergo reference resolve transpiling process:

* `sql`
* `measures`
* `dimensions`
* `segments`
* `time_dimension`
* `drill_members`
* `context_members`

Each of these properties inside `cube` and `context` definitions are transpiled
to functions with resolved arguments. For example:

```javascript theme={"dark"}
cube(`users`, {
  // ...

  measures: {
    count: {
      type: `count`
    },

    ratio: {
      sql: `SUM(${CUBE}.amount) / ${count}`,
      type: `number`
    }
  }
})
```

is transpiled to:

```javascript theme={"dark"}
cube(`users`, {
  // ...

  measures: {
    count: {
      type: `count`
    },

    ratio: {
      sql: (CUBE, count) => `SUM(${CUBE}.amount) / ${count}`,
      type: `number`
    }
  }
})
```

So for example if you want to pass the definition of `ratio` outside of the
cube, you would define it as:

```javascript theme={"dark"}
const measureRatioDefinition = {
  sql: (CUBE, count) => `sum(${CUBE}.amount) / ${count}`,
  type: `number`
}

cube(`users`, {
  // ...

  measures: {
    count: {
      type: `count`
    },

    ratio: measureRatioDefinition
  }
})
```

[nodejs-vm]: https://nodejs.org/api/vm.html

[nodejs-require]: https://nodejs.org/api/modules.html#modules_require_id

[ref-dynamic-schemas]: /docs/data-modeling/dynamic

[self-require]: #require

[ref-schema-path]: /reference/configuration/config#schema_path


# Extending cubes
Source: https://docs.cube.dev/docs/data-modeling/extending-cubes

Use extends on cubes to inherit and merge members from a parent so shared measures, dimensions, and joins stay defined once.

The `extends` parameter, supported for [cubes][ref-cube-extends] and
[views][ref-view-extends], allows you to create a *child* cube (or a view) that reuses
all declared members of a *parent* cube (or a view). This helps build reusable data models.

Cubes declare members such as measures, dimensions, and segments. When a child cube extends
the parent cube, lists of measures, dimensions, and segments are merged.
For example, if the parent cube defines the `a` measure and the child cube defines the `b`
measure, the resulting cube will have both measures `a` and `b`.

The usual pattern is to extract common measures, dimensions, and joins into
the parent cube and then extend from it. This helps prevent code duplication
and makes code easier to maintain and refactor.

In the example below, the `base_events` cube defines the common events measures,
dimensions, and a join to the `users` cube:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: base_events
      sql_table: events

      joins:
        - name: users
          relationship: many_to_one
          sql: "{CUBE}.user_id = {users.id}"

      measures:
        - name: count
          type: count

      dimensions:
        - name: timestamp
          sql: time
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`base_events`, {
    sql_table: `events`,

    joins: {
      users: {
        relationship: `many_to_one`,
        sql: `${CUBE}.user_id = ${users.id}`
      }
    },

    measures: {
      count: {
        type: `count`
      }
    },

    dimensions: {
      timestamp: {
        sql: `time`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

<Info>
  It’s important to use the [`CUBE` variable][ref-cube-variable] when referencing members
  and columns of the cube. Not specifying the cube name or using `${base_events}` does not
  work when the cube is extended.
</Info>

The `product_purchases` and `page_views` cubes are extended from `base_events`
and define only the specific dimensions: `product_name` for product purchases
and `page_path` for page views.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: product_purchases
      sql_table: product_purchases
      extends: base_events

      dimensions:
        - name: product_name
          sql: product_name
          type: string

    - name: page_views
      sql_table: page_views
      extends: base_events

      dimensions:
        - name: page_path
          sql: page_path
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`product_purchases`, {
    sql_table: `product_purchases`,
    extends: base_events,

    dimensions: {
      product_name: {
        sql: `product_name`,
        type: `string`
      }
    }
  })

  cube(`page_views`, {
    sql_table: `page_views`,
    extends: base_events,

    dimensions: {
      page_path: {
        sql: `page_path`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

## Usage with `FILTER_PARAMS`

If the parent cube is using [`FILTER_PARAMS`][ref-schema-ref-cube-filter-params]
in any `sql` parameter, then child cubes can accomodate to that in two ways.

First, the `sql` parameter can be overridden in each child cube:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: product_purchases
      sql: |
        SELECT *
        FROM events
        WHERE {FILTER_PARAMS.product_purchases.timestamp.filter('time')}

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`product_purchases`, {
    sql: `
      SELECT *
      FROM events
      WHERE ${FILTER_PARAMS.product_purchases.timestamp.filter("time")}
    `,

    // ...
  })
  ```
</CodeGroup>

Alternatively, all filters can be put inside the parent cube and referenced
in the child cubes using `AND`. The unused filters will be rendered to `1 = 1`
in the SQL query:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: base_events
      sql: |
        SELECT *
        FROM events
        WHERE
          {FILTER_PARAMS.base_events.timestamp.filter('time')} AND
          {FILTER_PARAMS.product_purchases.timestamp.filter('time')} AND
          {FILTER_PARAMS.page_views.timestamp.filter('time')}

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`base_events`, {
    sql: `
      SELECT *
      FROM events
      WHERE
        {$FILTER_PARAMS.base_events.timestamp.filter('time')} AND
        {$FILTER_PARAMS.product_purchases.timestamp.filter('time')} AND
        {$FILTER_PARAMS.page_views.timestamp.filter('time')}
    `,

    // ...
  })
  ```
</CodeGroup>

[ref-cube-extends]: /reference/data-modeling/cube#extends

[ref-view-extends]: /reference/data-modeling/view#extends

[ref-schema-ref-cube-filter-params]: /reference/data-modeling/context-variables#filter_params

[ref-cube-variable]: /docs/data-modeling/concepts/syntax#cube-variable


# Joins
Source: https://docs.cube.dev/docs/data-modeling/joins

Joins define relationships between cubes, allowing Cube to automatically generate multi-table SQL queries when views combine data from multiple cubes.

Joins define how cubes connect to each other. When a [view][ref-views]
includes members from multiple cubes, Cube uses these relationships to
automatically generate SQL `JOIN` clauses — so end-users can explore data
across tables without writing SQL.

<Note>
  See the [joins reference][ref-schema-ref-joins-relationship] for the full
  list of parameters and configuration options.
</Note>

## Relationship types

Cube supports three relationship types: `one_to_one`, `one_to_many`, and
`many_to_one`. The relationship type determines which table becomes the left
side of the `LEFT JOIN` in the generated SQL.

Consider two cubes, `orders` and `customers`. An order belongs to one
customer, but a customer can have many orders:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      joins:
        - name: customers
          relationship: many_to_one
          sql: "{CUBE}.customer_id = {customers.id}"

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: status
          sql: status
          type: string

      measures:
        - name: count
          type: count

    - name: customers
      sql_table: customers

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: company
          sql: company
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    joins: {
      customers: {
        relationship: `many_to_one`,
        sql: `${CUBE}.customer_id = ${customers.id}`
      }
    },

    dimensions: {
      id: { sql: `id`, type: `number`, primary_key: true },
      status: { sql: `status`, type: `string` }
    },

    measures: {
      count: { type: `count` }
    }
  })

  cube(`customers`, {
    sql_table: `customers`,

    dimensions: {
      id: { sql: `id`, type: `number`, primary_key: true },
      company: { sql: `company`, type: `string` }
    }
  })
  ```
</CodeGroup>

The `many_to_one` join on `orders` means: many orders belong to one customer.
When a view includes members from both cubes, Cube generates SQL with `orders`
on the left and `customers` on the right:

```sql theme={"dark"}
SELECT
  "orders".status,
  "customers".company,
  COUNT("orders".id)
FROM orders AS "orders"
LEFT JOIN customers AS "customers"
  ON "orders".customer_id = "customers".id
GROUP BY 1, 2
```

Because `orders` is on the left side of the `LEFT JOIN`, all orders are
preserved — including guest checkouts with no matching customer.

<Tip>
  As a rule of thumb, define joins on the **fact table** (e.g., `orders`)
  pointing toward the **dimension table** (e.g., `customers`) using
  `many_to_one`. This ensures the fact table is always the base of the query,
  preserving all its rows.
</Tip>

### Many-to-many relationships

A many-to-many relationship requires an associative (junction) table. For
example, `posts` and `topics` are connected through a `post_topics` table:

<Frame>
  <img alt="Many-to-Many Entity Diagram for posts, topics and post_topics" />
</Frame>

Model this with an associative cube, chaining the joins so they flow in one
direction (`posts → post_topics → topics`):

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: posts
      sql_table: posts

      joins:
        - name: post_topics
          relationship: one_to_many
          sql: "{CUBE}.id = {post_topics.post_id}"

    - name: post_topics
      sql_table: post_topics

      joins:
        - name: topics
          relationship: many_to_one
          sql: "{CUBE}.topic_id = {topics.id}"

      dimensions:
        - name: id
          sql: "CONCAT({CUBE}.post_id, {CUBE}.topic_id)"
          type: string
          primary_key: true

    - name: topics
      sql_table: topics

      dimensions:
        - name: id
          sql: id
          type: string
          primary_key: true

        - name: name
          sql: name
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`posts`, {
    sql_table: `posts`,

    joins: {
      post_topics: {
        relationship: `one_to_many`,
        sql: `${CUBE}.id = ${post_topics.post_id}`
      }
    }
  })

  cube(`post_topics`, {
    sql_table: `post_topics`,

    joins: {
      topics: {
        relationship: `many_to_one`,
        sql: `${CUBE}.topic_id = ${topics.id}`
      }
    },

    dimensions: {
      id: {
        sql: `CONCAT(${CUBE}.post_id, ${CUBE}.topic_id)`,
        type: `string`,
        primary_key: true
      }
    }
  })

  cube(`topics`, {
    sql_table: `topics`,

    dimensions: {
      id: { sql: `id`, type: `string`, primary_key: true },
      name: { sql: `name`, type: `string` }
    }
  })
  ```
</CodeGroup>

A view can then expose this through the `join_path`:

```yaml theme={"dark"}
views:
  - name: posts_with_topics
    cubes:
      - join_path: posts
        includes:
          - title
          - count

      - join_path: posts.post_topics.topics
        prefix: true
        includes:
          - name
```

## Direction of joins

**All joins are directed.** They flow from the source cube (where the join
is defined) to the target cube (the one referenced). Cube places the source
cube on the left side of the `LEFT JOIN` and the target on the right.

This matters because the left table preserves all its rows, while the right
table contributes matching rows or `NULL`. The direction you choose affects
which records appear in the result set.

For example, if `orders` defines a `many_to_one` join to `customers`:

* `orders` is the base → all orders are preserved, even guest checkouts
* `customers` without orders won't appear

If instead `customers` defined a `one_to_many` join to `orders`:

* `customers` is the base → all customers are preserved, even those without orders
* Guest checkout orders (with no matching customer) won't appear

### Using views to control direction

Views let you control which join path is followed via the
[`join_path`][ref-view-join-path] parameter. This is the recommended way to
handle cases where you need different join directions for different use cases:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      joins:
        - name: customers
          sql: "{CUBE}.customer_id = {customers.id}"
          relationship: many_to_one

      measures:
        - name: count
          type: count

        - name: total_revenue
          sql: revenue
          type: sum

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

    - name: customers
      sql_table: customers

      joins:
        - name: orders
          sql: "{CUBE}.id = {orders.customer_id}"
          relationship: one_to_many

      measures:
        - name: count
          type: count

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: name
          sql: name
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    joins: {
      customers: {
        sql: `${CUBE}.customer_id = ${customers.id}`,
        relationship: `many_to_one`
      }
    },

    measures: {
      count: { type: `count` },
      total_revenue: { sql: `revenue`, type: `sum` }
    },

    dimensions: {
      id: { sql: `id`, type: `number`, primary_key: true }
    }
  })

  cube(`customers`, {
    sql_table: `customers`,

    joins: {
      orders: {
        sql: `${CUBE}.id = ${orders.customer_id}`,
        relationship: `one_to_many`
      }
    },

    measures: {
      count: { type: `count` }
    },

    dimensions: {
      id: { sql: `id`, type: `number`, primary_key: true },
      name: { sql: `name`, type: `string` }
    }
  })
  ```
</CodeGroup>

Now you can create two views for two different analytical needs:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: revenue_per_customer
      description: All orders with customer details. Includes guest checkouts.
      cubes:
        - join_path: orders
          includes:
            - count
            - total_revenue

        - join_path: orders.customers
          includes:
            - name

    - name: customer_activity
      description: All customers with their order activity. Includes customers without orders.
      cubes:
        - join_path: customers
          includes:
            - name
            - count

        - join_path: customers.orders
          prefix: true
          includes:
            - count
            - total_revenue
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`revenue_per_customer`, {
    description: `All orders with customer details. Includes guest checkouts.`,
    cubes: [
      {
        join_path: orders,
        includes: [`count`, `total_revenue`]
      },
      {
        join_path: orders.customers,
        includes: [`name`]
      }
    ]
  })

  view(`customer_activity`, {
    description: `All customers with their order activity. Includes customers without orders.`,
    cubes: [
      {
        join_path: customers,
        includes: [`name`, `count`]
      },
      {
        join_path: customers.orders,
        prefix: true,
        includes: [`count`, `total_revenue`]
      }
    ]
  })
  ```
</CodeGroup>

The `revenue_per_customer` view follows the `orders → customers` path, so all
orders are preserved. The `customer_activity` view follows
`customers → orders`, so all customers are preserved.

## Diamond subgraphs

A *diamond subgraph* occurs when there's more than one join path between two
cubes — for example, `users.schools.countries` and
`users.employers.countries`. This can lead to ambiguous query generation.

Views resolve this ambiguity by specifying the exact `join_path` for each
included cube. For example, if cube `a` joins to both `b` and `c`, and both
`b` and `c` join to `d`, a view can specify which path to follow:

```yaml theme={"dark"}
views:
  - name: a_with_d_via_b
    cubes:
      - join_path: a
        includes: "*"

      - join_path: a.b.d
        prefix: true
        includes:
          - value

  - name: a_with_d_via_c
    cubes:
      - join_path: a
        includes: "*"

      - join_path: a.c.d
        prefix: true
        includes:
          - value
```

Each view follows a specific, unambiguous path through the data graph.

## Join paths in calculated members

When referencing a member of another cube in a [calculated member][ref-calculated-members],
you can use a join path to specify the exact route. This uses dot-separated
cube names:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      dimensions:
        - name: customer_country
          sql: "{customers.country}"
          type: string

        - name: shipping_country
          sql: "{shipping_addresses.country}"
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    dimensions: {
      customer_country: {
        sql: `${customers.country}`,
        type: `string`
      },

      shipping_country: {
        sql: `${shipping_addresses.country}`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

## Troubleshooting

### `Can't find join path`

The error `Can't find join path to join 'cube_a', 'cube_b'` means the cubes
included in a view or query can't be connected through the defined joins.

Check that:

* Joins are defined with the correct [direction](#direction-of-joins)
* There is a continuous path from the source cube to the target cube
* You're using the [`join_path`][ref-view-join-path] parameter in views to
  specify the exact path

### `Primary key is required when join is defined`

Cube uses primary keys to avoid fanouts — when rows get duplicated during
joins and aggregates are over-counted. Define a [primary key][ref-primary-key]
dimension in every cube that participates in joins.

If your data doesn't have a natural primary key, create a composite one:

```yaml theme={"dark"}
cubes:
  - name: events
    # ...

    dimensions:
      - name: composite_key
        sql: CONCAT(column_a, '-', column_b, '-', column_c)
        type: string
        primary_key: true
```

[ref-schema-ref-joins-relationship]: /reference/data-modeling/joins

[ref-views]: /docs/data-modeling/views

[ref-view-join-path]: /reference/data-modeling/view#join_path

[ref-calculated-members]: /docs/data-modeling/measures#calculated-measures

[ref-primary-key]: /reference/data-modeling/dimensions#primary_key

[ref-visual-model]: /docs/data-modeling/visual-modeler


# Measures
Source: https://docs.cube.dev/docs/data-modeling/measures

Measures compute aggregated values across rows — counts, sums, averages, and more complex calculations like rolling windows, time shifts, and rankings.

While [dimensions][ref-dimensions-page] describe attributes of individual rows,
measures compute values across rows — sums, counts, averages, and other
aggregations. Measures can aggregate columns directly (like `sum of revenue`)
or reference other measures to create compound metrics (like `revenue / count`).

<Note>
  See the [measures reference][ref-measures-ref] for the full list of parameters
  and configuration options.
</Note>

## Defining measures

A measure specifies the SQL expression to aggregate and the aggregation type:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      measures:
        - name: count
          type: count

        - name: total_amount
          sql: amount
          type: sum

        - name: average_amount
          sql: amount
          type: avg
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    measures: {
      count: { type: `count` },
      total_amount: { sql: `amount`, type: `sum` },
      average_amount: { sql: `amount`, type: `avg` }
    }
  })
  ```
</CodeGroup>

## Filtered measures

You can apply [filters][ref-filters] to a measure to create conditional
aggregations. Only rows matching the filter are included:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: count
          type: count

        - name: completed_count
          type: count
          filters:
            - sql: "{CUBE}.status = 'completed'"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      count: { type: `count` },

      completed_count: {
        type: `count`,
        filters: [{ sql: `${CUBE}.status = 'completed'` }]
      }
    }
  })
  ```
</CodeGroup>

When `completed_count` is queried, Cube generates SQL with a `CASE` expression:

```sql theme={"dark"}
SELECT
  COUNT(CASE WHEN (orders.status = 'completed') THEN 1 END) AS completed_count
FROM orders
```

## Calculated measures

Calculated measures perform calculations on other measures using SQL functions
and operators. They provide a way to decompose complex metrics (e.g., ratios
or percents) into formulas involving simpler measures.

### Referencing measures in the same cube

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: count
          type: count

        - name: completed_count
          type: count
          filters:
            - sql: "{CUBE}.status = 'completed'"

        - name: completed_ratio
          sql: "1.0 * {completed_count} / NULLIF({count}, 0)"
          type: number
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      count: { type: `count` },

      completed_count: {
        type: `count`,
        filters: [{ sql: `${CUBE}.status = 'completed'` }]
      },

      completed_ratio: {
        sql: `1.0 * ${completed_count} / NULLIF(${count}, 0)`,
        type: `number`
      }
    }
  })
  ```
</CodeGroup>

### Referencing measures from other cubes

If cubes are [joined][ref-joins], you can reference measures across cubes.
Cube generates the necessary joins automatically:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      # ...

      joins:
        - name: orders
          sql: "{CUBE}.id = {orders}.user_id"
          relationship: one_to_many

      measures:
        - name: count
          type: count

        - name: purchases_to_users_ratio
          sql: "1.0 * {orders.purchases} / NULLIF({CUBE.count}, 0)"
          type: number
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    // ...

    joins: {
      orders: {
        sql: `${CUBE}.id = ${orders}.user_id`,
        relationship: `one_to_many`
      }
    },

    measures: {
      count: { type: `count` },

      purchases_to_users_ratio: {
        sql: `1.0 * ${orders.purchases} / NULLIF(${CUBE.count}, 0)`,
        type: `number`
      }
    }
  })
  ```
</CodeGroup>

## Multi-stage measures

Multi-stage measures are calculated in two or more stages, enabling
calculations on already-aggregated data. Each stage results in one or more
CTEs in the generated SQL query.

<Warning>
  Multi-stage measures are powered by Tesseract, the [next-generation data
  modeling engine][link-tesseract]. In versions before v1.7.0, it was not enabled by default.
</Warning>

### Rolling windows

Rolling window measures calculate metrics over a moving window of time, such
as cumulative counts or moving averages. Use the
[`rolling_window`][ref-rolling-window] parameter:

```yaml theme={"dark"}
measures:
  - name: cumulative_count
    type: count
    rolling_window:
      trailing: unbounded

  - name: trailing_month_count
    sql: id
    type: count
    rolling_window:
      trailing: 1 month
```

### Period-to-date

Period-to-date measures analyze data from the start of a period to the current
date — year-to-date (YTD), quarter-to-date (QTD), or month-to-date (MTD):

```yaml theme={"dark"}
measures:
  - name: revenue_ytd
    sql: revenue
    type: sum
    rolling_window:
      type: to_date
      granularity: year

  - name: revenue_qtd
    sql: revenue
    type: sum
    rolling_window:
      type: to_date
      granularity: quarter
```

### Time shift

Time-shift measures calculate the value of another measure at a different
point in time, typically for period-over-period comparisons like
year-over-year growth. Use the [`time_shift`][ref-time-shift] parameter:

```yaml theme={"dark"}
measures:
  - name: revenue
    sql: revenue
    type: sum

  - name: revenue_prior_year
    multi_stage: true
    sql: "{revenue}"
    type: number
    time_shift:
      - interval: 1 year
        type: prior
```

You can combine time shift with period-to-date for comparisons like
"this year's YTD vs. last year's YTD":

```yaml theme={"dark"}
measures:
  - name: revenue_ytd
    sql: revenue
    type: sum
    rolling_window:
      type: to_date
      granularity: year

  - name: revenue_prior_year_ytd
    multi_stage: true
    sql: "{revenue_ytd}"
    type: number
    time_shift:
      - time_dimension: time
        interval: 1 year
        type: prior
```

Time-shift measures can also be used with [calendar cubes][ref-calendar-cubes]
to customize how time-shifting works, e.g., to shift by retail calendar
periods.

### Percent of total (fixed dimension)

Use the [`grain`][ref-grain] parameter with `keep_only` to fix the inner
aggregation to specific dimensions, enabling percent-of-total calculations:

```yaml theme={"dark"}
measures:
  - name: revenue
    sql: revenue
    type: sum

  - name: country_revenue
    multi_stage: true
    sql: "{revenue}"
    type: sum
    grain:
      keep_only:
        - country

  - name: country_revenue_percentage
    multi_stage: true
    sql: "{revenue} / NULLIF({country_revenue}, 0)"
    type: number
```

### Share of total (filter override)

Use the [`filter`][ref-filter] parameter to override the filters that a
multi-stage measure inherits from the query. This enables "share of total"
calculations where the denominator must ignore a filter applied by the query.

In the example below, `amount_all_statuses` uses `exclude` to drop the `status`
filter, so it always aggregates across all statuses. When the query is filtered
to a single status, `total_amount` reflects that status while
`amount_all_statuses` stays the full per-category total, and
`percent_of_total` is the share that the filtered status represents:

```yaml theme={"dark"}
measures:
  - name: total_amount
    sql: amount
    type: sum

  - name: amount_all_statuses
    multi_stage: true
    sql: "{total_amount}"
    type: number
    filter:
      exclude:
        - status

  - name: percent_of_total
    multi_stage: true
    sql: "100.0 * {total_amount} / NULLIF({amount_all_statuses}, 0)"
    type: number
    format: percent
```

### Nested aggregates

Use the [`grain`][ref-grain] parameter with `include` to compute an aggregate
of an aggregate, e.g., the average of per-customer averages:

```yaml theme={"dark"}
measures:
  - name: avg_order_value
    sql: amount
    type: avg

  - name: avg_customer_order_value
    multi_stage: true
    sql: "{avg_order_value}"
    type: avg
    grain:
      include:
        - customer_id
```

When a nested aggregate combines two or more other multi-stage measures that
share the same grain, set [`grain`][ref-grain] on the **combining** measure —
not on each of its inputs. For example, to average a per-day ratio, group the
per-day components by day through the combining measure:

```yaml theme={"dark"}
measures:
  - name: total_amount
    sql: amount
    type: sum

  - name: total_count
    sql: id
    type: count

  # Intermediate multi-stage measures — the grain is set on the combining
  # measure below, so these inherit it and are joined on the shared grain.
  - name: daily_amount
    multi_stage: true
    sql: "{total_amount}"
    type: number

  - name: daily_count
    multi_stage: true
    sql: "{total_count}"
    type: number

  - name: avg_daily_order_value
    multi_stage: true
    sql: "1.0 * {daily_amount} / NULLIF({daily_count}, 0)"
    type: avg
    grain:
      include:
        - created_at
```

<Warning>
  `grain` fixes the inner grain of the measure it's declared on and does not
  expose the added dimension to a measure built on top of it. If each input
  measure declares the same `grain.include` (rather than the combining measure),
  the inputs no longer carry a shared grouping key, so they are combined with a
  cross join instead of being joined on that key — producing incorrect results.
  Declare `grain` on the combining measure so its inputs are joined on the shared
  grain.
</Warning>

### Ranking

Use the [`grain`][ref-grain] parameter with `exclude` to rank items within
groups:

```yaml theme={"dark"}
measures:
  - name: revenue
    sql: revenue
    type: sum

  - name: product_rank
    multi_stage: true
    order_by:
      - sql: "{revenue}"
        dir: asc
    grain:
      exclude:
        - product
    type: rank
```

<Note>
  `grain` replaces the standalone `group_by`, `reduce_by`, and `add_group_by`
  parameters, which remain supported. See the [`grain`][ref-grain] reference for
  the migration mapping.
</Note>

### Conditional measures

Conditional measures depend on the value of a dimension, using the
[`case`][ref-case] parameter with [`switch` dimensions][ref-switch-dim]:

```yaml theme={"dark"}
measures:
  - name: amount_in_currency
    multi_stage: true
    case:
      switch: "{CUBE.currency}"
      when:
        - value: EUR
          sql: "{CUBE.amount_eur}"
        - value: GBP
          sql: "{CUBE.amount_gbp}"
      else:
        sql: "{CUBE.amount_usd}"
    type: number
```

## Formatting

Use the [`format`][ref-format] parameter to control how measures are displayed:

```yaml theme={"dark"}
measures:
  - name: total_revenue
    sql: revenue
    type: sum
    format: currency

  - name: conversion_rate
    sql: "1.0 * {completed_count} / NULLIF({count}, 0)"
    type: number
    format: percent
```

## Next steps

* See the [measures reference][ref-measures-ref] for all parameters
* Learn about [dimensions][ref-dimensions-page] for grouping and filtering
* Explore [pre-aggregations][ref-pre-aggs] to accelerate measure queries
* See the [period-over-period recipe][ref-pop-recipe] for advanced time
  comparisons

[ref-measures-ref]: /reference/data-modeling/measures

[ref-dimensions-page]: /docs/data-modeling/dimensions

[ref-joins]: /docs/data-modeling/joins

[ref-pre-aggs]: /reference/data-modeling/pre-aggregations

[ref-type]: /reference/data-modeling/measures#type

[ref-filters]: /reference/data-modeling/measures#filters

[ref-format]: /reference/data-modeling/measures#format

[ref-rolling-window]: /reference/data-modeling/measures#rolling_window

[ref-time-shift]: /reference/data-modeling/measures#time_shift

[ref-grain]: /reference/data-modeling/measures#grain

[ref-filter]: /reference/data-modeling/measures#filter

[ref-case]: /reference/data-modeling/measures#case

[ref-switch-dim]: /reference/data-modeling/dimensions#type

[ref-calendar-cubes]: /docs/data-modeling/concepts/calendar-cubes

[ref-pop-recipe]: /recipes/data-modeling/period-over-period

[link-tesseract]: https://cube.dev/blog/introducing-next-generation-data-modeling-engine


# Multi-fact views
Source: https://docs.cube.dev/docs/data-modeling/multi-fact-views

Analyze data across multiple fact tables that share common dimensions like time or customers, without row multiplication or manual workarounds.

In many data models, you have multiple fact tables that share common
dimensions but have no direct relationship to each other. For example,
an e-commerce company tracks both orders and returns:

* **`orders`** — one row per order, with `customer_id` and `created_at`
* **`returns`** — one row per return, with `customer_id` and `created_at`
* **`customers`** — one row per customer
* **`dates`** — a date spine

Both `orders` and `returns` join to `customers` and `dates`, but they don't
join to each other:

```
           customers
          /         \
    orders           returns
          \         /
            dates
```

You need a report showing `orders_count`, `total_revenue`, `returns_count`,
and `total_refunds` grouped by customer and month. But joining `orders` and
`returns` directly would produce a cross product — every order matched with
every return for that customer and date — inflating all counts and sums.

## How multi-fact views solve this

In a regular [view][ref-views], there is a single **root cube** — the first
cube listed in the view's `cubes` array. All joins flow from this root, and
Cube uses it as the base table in the generated SQL.

Multi-fact views work differently. When a view includes measures from
**multiple fact tables**, Cube selects the root dynamically at query time
based on which measures are requested. Each fact table gets its own
aggregating subquery, and the results are joined on the shared dimensions.
No fanout, no manual workarounds.

<Warning>
  Multi-fact views are powered by Tesseract, the [next-generation data modeling
  engine][link-tesseract]. In versions before v1.7.0, it was not enabled by default.
</Warning>

## How to model it

### 1. Define the cubes

Each fact table becomes a cube with explicit joins to the shared dimension
tables:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: customers
      sql_table: customers

      dimensions:
        - name: id
          type: number
          sql: id
          primary_key: true
        - name: name
          type: string
          sql: name
        - name: city
          type: string
          sql: city

    - name: dates
      sql_table: dates

      dimensions:
        - name: date
          type: time
          sql: date
          primary_key: true

    - name: orders
      sql_table: orders

      joins:
        - name: customers
          relationship: many_to_one
          sql: "{orders}.customer_id = {customers.id}"
        - name: dates
          relationship: many_to_one
          sql: "DATE_TRUNC('day', {orders}.created_at) = {dates.date}"

      dimensions:
        - name: id
          type: number
          sql: id
          primary_key: true
        - name: status
          type: string
          sql: status

      measures:
        - name: count
          type: count
        - name: total_amount
          type: sum
          sql: amount

    - name: returns
      sql_table: returns

      joins:
        - name: customers
          relationship: many_to_one
          sql: "{returns}.customer_id = {customers.id}"
        - name: dates
          relationship: many_to_one
          sql: "DATE_TRUNC('day', {returns}.created_at) = {dates.date}"

      dimensions:
        - name: id
          type: number
          sql: id
          primary_key: true

      measures:
        - name: count
          type: count
        - name: total_refund
          type: sum
          sql: refund_amount
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`customers`, {
    sql_table: `customers`,

    dimensions: {
      id: { sql: `id`, type: `number`, primary_key: true },
      name: { sql: `name`, type: `string` },
      city: { sql: `city`, type: `string` }
    }
  })

  cube(`dates`, {
    sql_table: `dates`,

    dimensions: {
      date: { sql: `date`, type: `time`, primary_key: true }
    }
  })

  cube(`orders`, {
    sql_table: `orders`,

    joins: {
      customers: {
        relationship: `many_to_one`,
        sql: `${orders}.customer_id = ${customers.id}`
      },
      dates: {
        relationship: `many_to_one`,
        sql: `DATE_TRUNC('day', ${orders}.created_at) = ${dates.date}`
      }
    },

    dimensions: {
      id: { sql: `id`, type: `number`, primary_key: true },
      status: { sql: `status`, type: `string` }
    },

    measures: {
      count: { type: `count` },
      total_amount: { sql: `amount`, type: `sum` }
    }
  })

  cube(`returns`, {
    sql_table: `returns`,

    joins: {
      customers: {
        relationship: `many_to_one`,
        sql: `${returns}.customer_id = ${customers.id}`
      },
      dates: {
        relationship: `many_to_one`,
        sql: `DATE_TRUNC('day', ${returns}.created_at) = ${dates.date}`
      }
    },

    dimensions: {
      id: { sql: `id`, type: `number`, primary_key: true }
    },

    measures: {
      count: { type: `count` },
      total_refund: { sql: `refund_amount`, type: `sum` }
    }
  })
  ```
</CodeGroup>

The critical detail: both `orders` and `returns` declare direct joins to
`customers` and `dates`. This tells Cube that these dimension tables are shared
between the two facts.

### 2. Create a view

The view brings both fact tables and the shared dimension tables together.
Dimension tables are included at root-level join paths (not nested under a
specific fact), which makes their dimensions common to both facts. Use
`prefix` to disambiguate identically named members across fact cubes:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: customer_overview
      cubes:
        - join_path: orders
          prefix: true
          includes:
            - count
            - total_amount
        - join_path: returns
          prefix: true
          includes:
            - count
            - total_refund
        - join_path: customers
          includes:
            - name
            - city
        - join_path: dates
          includes:
            - date
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`customer_overview`, {
    cubes: [
      {
        join_path: orders,
        prefix: true,
        includes: [`count`, `total_amount`]
      },
      {
        join_path: returns,
        prefix: true,
        includes: [`count`, `total_refund`]
      },
      {
        join_path: customers,
        includes: [`name`, `city`]
      },
      {
        join_path: dates,
        includes: [`date`]
      }
    ]
  })
  ```
</CodeGroup>

When you query `orders_count`, `orders_total_amount`, `returns_count`, and
`returns_total_refund` grouped by `name`, `city`, and `date`, Cube detects
the two separate fact roots and automatically executes a multi-fact query.

## What Cube does under the hood

Cube executes the query in three stages:

### 1. Separate aggregating subqueries

Each fact table gets its own independent subquery that joins only the tables
it needs, applies relevant filters, and aggregates by the common dimensions:

* **Subquery 1** (orders): joins `orders` → `customers` and `orders` → `dates`,
  computes `COUNT(*)` and `SUM(amount)`, grouped by `name`, `city`, `date`
* **Subquery 2** (returns): joins `returns` → `customers` and `returns` → `dates`,
  computes `COUNT(*)` and `SUM(refund_amount)`, grouped by `name`, `city`, `date`

### 2. Join on common dimensions

The subquery results are joined with `FULL JOIN` on all common dimension
columns (`name`, `city`, `date`). This preserves rows that exist in only one
fact table — a customer who placed orders but never returned anything still
appears in the results.

### 3. Final result

The combined result shows measures from each fact table side by side:

| name    | city     | date       | orders\_count | orders\_total\_amount | returns\_count | returns\_total\_refund |
| ------- | -------- | ---------- | ------------- | --------------------- | -------------- | ---------------------- |
| Alice   | New York | 2025-01-15 | 2             | 200.00                | 0              | NULL                   |
| Alice   | New York | 2025-02-10 | 2             | 225.00                | 1              | 100.00                 |
| Bob     | Seattle  | 2025-01-20 | 3             | 550.00                | 2              | 130.00                 |
| Charlie | New York | 2025-02-05 | 0             | NULL                  | 2              | 100.00                 |
| Diana   | Boston   | 2025-03-01 | 1             | 400.00                | 0              | NULL                   |

Charlie has no orders and Diana has no returns — both are still included
with `NULL` values for the missing fact table.

## Combining facts in one measure

Putting measures from two facts side by side is often not the goal — you want a
single metric derived from both, such as revenue per order where revenue and
order count come from different fact tables. Neither cube can define it, because
neither can reference the other's measures.

Define it as a [measure of the view][ref-view-measures] instead, and mark it
[`multi_stage`][ref-multi-stage]:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: customer_overview
      cubes:
        - join_path: orders
          prefix: true
          includes:
            - count
            - total_amount
        - join_path: returns
          prefix: true
          includes:
            - total_refund
        - join_path: customers
          includes:
            - name
            - city
        - join_path: dates
          includes:
            - date

      measures:
        - name: refund_rate
          type: number
          multi_stage: true
          sql: "{CUBE.returns_total_refund} / NULLIF({CUBE.orders_total_amount}, 0)"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`customer_overview`, {
    cubes: [
      {
        join_path: orders,
        prefix: true,
        includes: [`count`, `total_amount`]
      },
      {
        join_path: returns,
        prefix: true,
        includes: [`total_refund`]
      },
      {
        join_path: customers,
        includes: [`name`, `city`]
      },
      {
        join_path: dates,
        includes: [`date`]
      }
    ],

    measures: {
      refund_rate: {
        type: `number`,
        multi_stage: true,
        sql: `${CUBE.returns_total_refund} / NULLIF(${CUBE.orders_total_amount}, 0)`
      }
    }
  })
  ```
</CodeGroup>

`multi_stage` is what makes this work. It defers the expression to a stage that
runs *after* the per-fact subqueries have been aggregated and joined, so the
division happens once per row of the combined result:

```sql theme={"dark"}
-- one aggregating subquery per fact, at the query's grain
SUM(orders.amount)   GROUP BY city
SUM(returns.refund)  GROUP BY city
-- final stage, once the two are joined on city
total_refund / NULLIF(total_amount, 0)
```

Without `multi_stage`, the same expression is planned as an ordinary calculated
measure. Cube then looks for a single join tree covering both fact cubes, finds
none — the facts only meet through the shared dimensions — and the query fails
with `Can't find join path to join …`, naming both facts. If you see that error
on a measure that spans facts, `multi_stage` is what's missing.

The measure is queried like any other, on its own or next to its components, and
grouped by any of the shared dimensions.

## Joining views in the SQL API

You don't have to define a dedicated multi-fact view to get multi-fact
behavior. The [SQL API][ref-sql-api] produces the same query when you **join
two or more views on a dimension they share** and group by that dimension.

Suppose `orders_view` and `returns_view` are two separate views that each
expose the customer's `name` (both backed by the same underlying
`customers.name` member). Joining them on `name` and grouping by it triggers a
multi-fact query:

```sql theme={"dark"}
SELECT
  o.name,
  MEASURE(o.total_amount),
  MEASURE(r.total_refund)
FROM orders_view o
LEFT JOIN returns_view r ON r.name = o.name
GROUP BY 1
```

Cube recognizes that both `name` columns resolve to the same cube member,
merges the two view scans into a single multi-fact query, and runs it with the
separate-subquery-then-join strategy described
[above](#what-cube-does-under-the-hood).

This rewrite applies only when:

* Both sides of the join condition resolve to the **same underlying cube
  member** (a shared dimension), and the join key is composed only of
  dimensions.
* The query is **grouped by the join key** — every grouped dimension is the
  shared join key. Ungrouped joins (such as `SELECT *`) and queries that group
  by a different dimension are not merged and fall back to standard join
  handling.

### Joining three or more views

The rewrite is not limited to two views. Chained joins on the same shared key
are merged into a single multi-fact query, with each view contributing its own
aggregating subquery:

```sql theme={"dark"}
SELECT
  o.name,
  MEASURE(o.total_amount),
  MEASURE(r.total_refund),
  MEASURE(p.total_paid)
FROM orders_view o
FULL JOIN returns_view r ON r.name = o.name
FULL JOIN payments_view p ON p.name = o.name
GROUP BY 1
```

### Joining on a time dimension

A common multi-fact pattern joins facts on a shared time dimension and groups by
a truncated grain. **Join on `DATE_TRUNC` at the same granularity you group by:**

```sql theme={"dark"}
SELECT DATE_TRUNC('day', o.created_at), MEASURE(o.total_amount), MEASURE(r.total_refund)
FROM orders_view o
JOIN returns_view r ON DATE_TRUNC('day', r.created_at) = DATE_TRUNC('day', o.created_at)
GROUP BY 1
```

The grouped column is emitted as a time dimension with its granularity. A join
written on `DATE_TRUNC` is an `INNER` join (the SQL planner expresses it as a
filtered cross join), so both sides must share a key; both truncated columns
must resolve to the same underlying time member at the same granularity.

The join-key granularity must match the `GROUP BY` granularity, because the
facts are stitched together at the grain you group by. This has two
consequences:

* Joining on `DATE_TRUNC('month', …)` while grouping by `DATE_TRUNC('day', …)`
  is not merged (it would silently stitch at day grain, diverging from the
  month-grain join).
* Joining on the **raw** time column (`ON r.created_at = o.created_at`, an
  exact-timestamp join) while grouping by `DATE_TRUNC('day', …)` is likewise not
  merged — the row-grain join doesn't match the day-grain group-by. Truncate the
  join key to the grain you group by instead.

In both cases the query falls back to standard join handling.

You can also combine a `DATE_TRUNC` equality with a plain dimension equality in
the same join (a composite key), and group by both:

```sql theme={"dark"}
SELECT DATE_TRUNC('day', o.created_at), o.name, MEASURE(o.total_amount), MEASURE(r.total_refund)
FROM orders_view o
JOIN returns_view r
  ON DATE_TRUNC('day', r.created_at) = DATE_TRUNC('day', o.created_at)
 AND r.name = o.name
GROUP BY 1, 2
```

### Filtering the join

Filters on top of the join are pushed into the merged query:

* A `WHERE` clause is pushed into the merged scan, becoming a filter on the
  member the predicate refers to.
* A predicate in the `ON` clause that the planner can attach to a single side
  (for example, a condition on the optional side of a `LEFT JOIN`) becomes a
  filter on that fact. Predicates that the SQL planner can't push to one side
  of an outer join (such as a left-table condition in a `LEFT JOIN ON`) aren't
  supported by the planner and will raise an error.

Pushing the predicate in is only the first step: the merged query is then
planned like any other multi-fact query, so the member it filters on must be
[shared by all facts](#filters-and-segments).

### Join type

The facts are stitched together with a `FULL JOIN` on the shared key, and the
`JOIN` type in your SQL controls which rows are kept:

| SQL join            | Result                                                                    |
| ------------------- | ------------------------------------------------------------------------- |
| `FULL [OUTER] JOIN` | every key from either view (default multi-fact behavior)                  |
| `INNER JOIN`        | only keys present in **both** views                                       |
| `LEFT JOIN`         | every key from the left view; right-side measures are `NULL` when missing |
| `RIGHT JOIN`        | every key from the right view; left-side measures are `NULL` when missing |

## Common patterns

### Time as the shared dimension

The most common multi-fact pattern uses time as the shared dimension.
For example, you might have `page_views`, `signups`, and `purchases` that all
have timestamps but no direct relationship. By joining each to a shared
`dates` cube, you can analyze conversion funnels — page views vs. signups
vs. purchases by day — without any row multiplication.

### More than two fact tables

Multi-fact queries are not limited to two fact tables. If a view includes
three or more facts, each gets its own aggregating subquery, and all results
are joined on the common dimensions.

### Facts that don't share all dimensions

Every root fact table must be joinable to the **same set of common dimension
tables**. If a fact table doesn't naturally have a foreign key for one of the
common dimensions, you can create a synthetic join:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: refunds
      sql: >
        SELECT *, NULL AS customer_id FROM refunds
      joins:
        - name: customers
          relationship: many_to_one
          sql: "{refunds}.customer_id = {customers.id}"
        - name: dates
          relationship: many_to_one
          sql: "DATE_TRUNC('day', {refunds}.created_at) = {dates.date}"

      dimensions:
        - name: id
          type: number
          sql: id
          primary_key: true

      measures:
        - name: count
          type: count
        - name: total_amount
          type: sum
          sql: amount
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`refunds`, {
    sql: `SELECT *, NULL AS customer_id FROM refunds`,

    joins: {
      customers: {
        relationship: `many_to_one`,
        sql: `${refunds}.customer_id = ${customers.id}`
      },
      dates: {
        relationship: `many_to_one`,
        sql: `DATE_TRUNC('day', ${refunds}.created_at) = ${dates.date}`
      }
    },

    dimensions: {
      id: { sql: `id`, type: `number`, primary_key: true }
    },

    measures: {
      count: { type: `count` },
      total_amount: { sql: `amount`, type: `sum` }
    }
  })
  ```
</CodeGroup>

The `NULL AS customer_id` makes the join syntactically valid. Refund rows
won't match a specific customer, but the subquery can still participate in
the multi-fact join on the full set of common dimensions.

## Filters and segments

**Common dimension filters** (like `city = 'New York'` or `date > '2025-01-01'`)
are applied to every subquery, ensuring consistent filtering across all facts.

**Measure filters** (like `orders_count > 1`) are applied as `HAVING`
conditions after the subqueries are joined.

**Fact-specific filters and [segments][ref-segments]** — anything that belongs to
one fact table rather than a shared dimension — can't be used in a multi-fact
query, however it is written: a `WHERE` clause in the SQL API, a filter in the
REST (JSON) API, or a segment. Every grouped dimension, filter and segment has
to be reachable from all facts, so a query that carries one fails with
`Can't find join path to join …`. The same members are fine as soon as only
that fact's measures are requested, since the query is no longer multi-fact.

To narrow one fact inside a multi-fact query, put the condition in the measure's
own [`filters`][ref-measure-filters] on its cube. It travels with the measure
into that fact's subquery and leaves the others alone:

```yaml theme={"dark"}
measures:
  - name: completed_amount
    sql: amount
    type: sum
    filters:
      - sql: "{CUBE}.status = 'completed'"
```

## Join path requirements

* Each fact cube must declare **direct joins** to all shared dimension tables
* Dimension tables should be included in the view at **root-level join paths**,
  not nested under a specific fact (e.g., `customers`, not `orders.customers`)
* Use `prefix` on fact cubes to disambiguate identically named members
* Everything a multi-fact query groups or filters by must be shared by all facts

[ref-views]: /docs/data-modeling/views

[ref-view-ref]: /reference/data-modeling/view

[ref-segments]: /reference/data-modeling/segments

[ref-measure-filters]: /reference/data-modeling/measures#filters

[ref-multi-stage]: /reference/data-modeling/measures#multi_stage

[ref-view-measures]: /reference/data-modeling/view#measures

[ref-sql-api]: /reference/core-data-apis/sql-api

[link-tesseract]: https://cube.dev/blog/introducing-tesseract


# Getting started
Source: https://docs.cube.dev/docs/data-modeling/overview

Build a reusable semantic layer that provides the shared context for AI agents, BI dashboards, and embedded analytics — turning warehouse tables into governed metrics and dimensions.

<Frame>
  <img />
</Frame>

Let’s use a users table with the following columns as an example:

| id | paying | city          | company\_name |
| -- | ------ | ------------- | ------------- |
| 1  | true   | San Francisco | Pied Piper    |
| 2  | true   | Palo Alto     | Raviga        |
| 3  | true   | Redwood       | Aviato        |
| 4  | false  | Mountain View | Bream-Hall    |
| 5  | false  | Santa Cruz    | Hooli         |

We can start with a set of simple questions about users we want to answer:

* How many users do we have?
* How many paying users?
* What is the percentage of paying users out of the total?
* How many users, paying or not, are from different cities and companies?

We don’t need to write SQL queries for every question, since the data model
allows building well-organized and reusable SQL.

## 1. Creating a Cube

In Cube, [cubes][ref-schema-cube] are used to organize tables and connections
between tables. Usually one cube is created for each table in the database,
such as `users`, `orders`, `products`, etc. In the `sql_table` parameter of the
cube we define a base table for this cube. In our case, the base table is simply
our `users` table.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`
  })
  ```
</CodeGroup>

## 2. Adding Measures and Dimensions

Once the base table is defined, the next step is to add
[measures][ref-schema-measures] and [dimensions][ref-schema-dimensions] to the
cube.

<Info>
  **Measures** are referred to as quantitative data, such as number of units sold,
  number of unique visits, profit, and so on.

  **Dimensions** are referred to as categorical data, such as state, gender,
  product name, or units of time (e.g., day, week, month).
</Info>

Let's go ahead and create our first measure and two dimensions:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      measures:
        - name: count
          sql: id
          type: count

      dimensions:
        - name: city
          sql: city
          type: string

        - name: company_name
          sql: company_name
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    measures: {
      count: {
        sql: `id`,
        type: `count`
      }
    },

    dimensions: {
      city: {
        sql: `city`,
        type: `string`
      },

      company_name: {
        sql: `company_name`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

Let's break down the above code snippet piece-by-piece. After defining the base
table for the cube (with the `sql_table` property), we create a `count` measure
in the `measures` block. The `count` [type][ref-schema-types-formats] and sql
`id` means that when this measure will be requested via an API, Cube will
generate and execute the following SQL:

```sql theme={"dark"}
SELECT COUNT(id) AS count
FROM users;
```

When we apply a city dimension to the measure to see "Where are users based?",
Cube will generate SQL with a `GROUP BY` clause:

```sql theme={"dark"}
SELECT city, COUNT(id) AS count
FROM users
GROUP BY 1;
```

You can add as many dimensions as you want to your query when you perform
grouping.

## 3. Adding Filters to Measures

Now let's answer the next question – "How many paying users do we have?". To
accomplish this, we will introduce **measure filters**:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users

      measures:
        - name: count
          sql: id
          type: count

        - name: paying_count
          sql: id
          type: count
          filters:
            - sql: "{CUBE}.paying = 'true'"

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    measures: {
      count: {
        sql: `id`,
        type: `count`
      },

      paying_count: {
        sql: `id`,
        type: `count`,
        filters: [{ sql: `${CUBE}.paying = 'true'` }]
      }
    },

    // ...
  })
  ```
</CodeGroup>

<Info>
  It is best practice to prefix references to table columns with the name of the
  cube or with the `CUBE` constant when referencing the current cube's column.
</Info>

That's it! Now we have the `paying_count` measure, which shows only our paying
users. When this measure is requested, Cube will generate the following SQL:

```sql theme={"dark"}
SELECT
  COUNT(
    CASE WHEN (users.paying = 'true') THEN users.id END
  ) AS paying_count
FROM users
```

Since the `filters` property is an array, you can apply as many filters as
required. `paying_count` can be used with dimensions the same way as a simple
`count`. We can group `paying_count` by `city` and `companyName` simply by
adding these dimensions alongside measures in the requested query.

## 4. Using Calculated Measures

To answer "What is the percentage of paying users out of the total?", we need to
calculate the paying users ratio, which is basically `paying_count / count`.
Cube makes it extremely easy to perform this kind of calculation by defining a
[calculated measure][ref-calculated-measures]. Let's add a new measure to our cube
called `paying_percentage`:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users

      measures:
        - name: count
          sql: id
          type: count

        - name: paying_count
          sql: id
          type: count
          filters:
            - sql: "{CUBE}.paying = 'true'"

        - name: paying_percentage
          sql: "1.0 * {paying_count} / {count}"
          type: number
          format: percent

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    measures: {
      count: {
        sql: `id`,
        type: `count`
      },

      paying_count: {
        sql: `id`,
        type: `count`,
        filters: [{ sql: `${CUBE}.paying = 'true'` }]
      },

      paying_percentage: {
        sql: `1.0 * ${paying_count} / ${count}`,
        type: `number`,
        format: `percent`
      }
    },

    // ...
  })
  ```
</CodeGroup>

Here we defined a calculated measure `paying_percentage`, which divides
`paying_count` by `count`. This example shows how you can reference measures
inside other measure definitions. When you request the `paying_percentage`
measure via an API, the following SQL will be generated:

```sql theme={"dark"}
SELECT
  1.0 * COUNT(
    CASE WHEN (users.paying = 'true') THEN users.id END
  ) / COUNT(users.id) AS paying_percentage
FROM users
```

As with other measures, `paying_percentage` can be used with dimensions.

## 5. Creating a View

[Views][ref-views] sit on top of cubes and create a facade of your whole data
model, with which data consumers can interact. They are useful for defining
metrics, managing governance, and controlling which part of the data model is
exposed to end-users.

Let's create a view that exposes our users data:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: users_view

      cubes:
        - join_path: users
          includes:
            - "*"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`users_view`, {
    cubes: [
      {
        join_path: users,
        includes: `*`
      }
    ]
  })
  ```
</CodeGroup>

End-users query data through views in Cube. This gives you a layer of
abstraction that makes it easier to manage changes to the underlying data
model.

## 6. Next Steps

1. [Explore][ref-explore] your data model
2. Use [Workbooks][ref-workbooks] to save your analysis and present it as a dashboard

[ref-backend-restapi]: /reference/core-data-apis/rest-api/reference

[ref-schema-cube]: /reference/data-modeling/cube

[ref-schema-measures]: /reference/data-modeling/measures

[ref-schema-dimensions]: /reference/data-modeling/dimensions

[ref-schema-types-formats]: /reference/data-modeling/measures#type

[ref-backend-query-format]: /reference/core-data-apis/rest-api/query-format

[ref-demo-deployment]: /admin/deployment#demo-deployments

[ref-apis]: /reference

[ref-calculated-measures]: /docs/data-modeling/measures#calculated-measures

[ref-views]: /reference/data-modeling/view

[ref-explore]: /docs/explore-analyze/explore

[ref-workbooks]: /docs/explore-analyze/workbooks


# View groups
Source: https://docs.cube.dev/docs/data-modeling/view-groups

View groups organize views into named collections by domain or purpose, helping downstream consumers — including AI agents and embedded analytics — navigate large data models.

When a data model contains many [views][ref-views], view groups help organize
them into named collections by domain or purpose — for example, `sales`,
`finance`, or `people`. View groups are exposed through the
[`/v1/meta`][ref-meta-endpoint] API, making it easier for downstream tools,
AI agents, and embedded analytics to present a navigable catalog.

<Note>
  See the [view group reference][ref-view-group-ref] for the full list of
  parameters and configuration options.
</Note>

## Defining a view group

A view group is a top-level entity, defined alongside views. At minimum it
needs a `name`; adding a `title` makes it easier to navigate in downstream
tools.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  view_groups:
    - name: sales
      title: Sales
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view_group(`sales`, {
    title: `Sales`
  })
  ```
</CodeGroup>

## Assigning views to a group

To assign a view to a group, list its name on the group via the
[`includes`][ref-view-group-includes] parameter. This keeps the full
membership in one place, which makes it easy to review a group at a glance.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  view_groups:
    - name: sales
      title: Sales
      includes:
        - orders_overview
        - revenue
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view_group(`sales`, {
    title: `Sales`,
    includes: [`orders_overview`, `revenue`]
  })
  ```
</CodeGroup>

A view can belong to more than one group — list it under the `includes`
parameter of every group it should appear in.

## Nesting

View groups can be nested, similar to [nested folders][ref-view-nesting]. Add a
nested view group — with its own `name`, `title`, `description`, and
`includes` — directly inside a parent group's `includes`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  view_groups:
    - name: sales
      title: Sales
      includes:
        - orders_overview
        - revenue

        - name: enterprise_sales
          title: Enterprise Sales
          includes:
            - enterprise_deals
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view_group(`sales`, {
    title: `Sales`,
    includes: [
      `orders_overview`,
      `revenue`,
      {
        name: `enterprise_sales`,
        title: `Enterprise Sales`,
        includes: [`enterprise_deals`]
      }
    ]
  })
  ```
</CodeGroup>

## Where view groups live in the model

By [convention][ref-syntax], view groups are typically defined alongside
views in the `model/views` folder — for example, in a dedicated
`view_groups.yml` file. They behave like any other top-level data model
entity and can be split across multiple files as your model grows.

## Next steps

* See the [view group reference][ref-view-group-ref] for the full list of
  parameters
* Learn about [views][ref-views] and how they curate cubes for downstream
  consumers
* Explore [AI context][ref-ai-context] to improve AI query accuracy

[ref-views]: /docs/data-modeling/views

[ref-view-nesting]: /reference/data-modeling/view#nesting

[ref-syntax]: /docs/data-modeling/concepts/syntax

[ref-ai-context]: /docs/data-modeling/ai-context

[ref-view-group-ref]: /reference/data-modeling/view-group

[ref-view-group-includes]: /reference/data-modeling/view-group#includes

[ref-meta-endpoint]: /reference/core-data-apis/rest-api/reference


# Views
Source: https://docs.cube.dev/docs/data-modeling/views

Views are curated datasets that sit on top of cubes and create a user-friendly facade of your data model for downstream consumers, AI agents, and embedded analytics.

Views sit on top of the data graph of [cubes][ref-cubes] and create a facade
of your whole data model with which data consumers can interact. They bring
together relevant measures, dimensions, and join paths into a logical
structure that matches how business users think about their data.

<Frame>
  <img />
</Frame>

<Note>
  See the [view reference][ref-view-reference] for the full list of
  parameters and configuration options.
</Note>

## Why views matter

Views are the primary interface between your data model and your users.
While cubes model the raw relationships and logic in your warehouse, views
reshape that model into business-friendly datasets for easier exploration.

<AccordionGroup>
  <Accordion title="Self-service analytics">
    Views shield end-users from complex database schemas, table
    relationships, and raw SQL. Business users can pick fields from
    a curated dataset in [Explore][ref-explore] or
    [Workbooks][ref-workbooks] without needing to understand the joins
    or cube structure underneath.

    For example, an analyst could pick `product`, `total_amount`, and
    `users_city` from an `orders` view without thinking about the underlying
    join path from `base_orders` through `line_items` to `products`.
  </Accordion>

  <Accordion title="AI reliability">
    [AI agents][ref-ai-context] query your data model through views.
    By curating which members are included and providing descriptive
    metadata via `description` and `meta.ai_context`, you control the
    context AI uses to generate accurate queries. Well-designed views
    with clear naming and descriptions lead to significantly better
    AI results.
  </Accordion>

  <Accordion title="Governance and access control">
    Views give you fine-grained control over what users can see.
    Each view can be scoped with [access policies][ref-access-policies]
    to enforce row-level and member-level security. You can also set
    `public: false` to hide internal views or use
    [COMPILE\_CONTEXT][ref-compile-context] for dynamic visibility
    based on the security context.
  </Accordion>

  <Accordion title="Join path clarity">
    In complex data models, the same pair of cubes might be reachable
    through multiple join paths. Views eliminate this ambiguity by
    specifying the exact `join_path` for each included cube, ensuring
    queries always follow the intended path.
  </Accordion>

  <Accordion title="Embedded analytics">
    Views are a natural fit for [embedded analytics][ref-embedding].
    Different customer tiers can get access to different views,
    allowing you to tailor the analytics experience to your
    monetization strategy without duplicating cubes.
  </Accordion>
</AccordionGroup>

## How views work

Views do **not** define their own members. Instead, they reference cubes by
specific join paths and selectively include measures, dimensions, hierarchies,
and segments from those cubes.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: orders

      cubes:
        - join_path: base_orders
          includes:
            - status
            - created_date
            - total_amount
            - count
            - average_order_value

        - join_path: base_orders.line_items.products
          includes:
            - name: name
              alias: product

        - join_path: base_orders.users
          prefix: true
          includes: "*"
          excludes:
            - company
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`orders`, {
    cubes: [
      {
        join_path: base_orders,
        includes: [
          `status`,
          `created_date`,
          `total_amount`,
          `count`,
          `average_order_value`
        ]
      },
      {
        join_path: base_orders.line_items.products,
        includes: [
          {
            name: `name`,
            alias: `product`
          }
        ]
      },
      {
        join_path: base_orders.users,
        prefix: true,
        includes: `*`,
        excludes: [`company`]
      }
    ]
  })
  ```
</CodeGroup>

In this example, the `orders` view pulls in members from three cubes
along their join paths. End-users see a flat list of fields — `status`,
`created_date`, `product`, `users_city`, etc. — without being exposed to
the underlying cube structure.

## Designing effective views

### Build for your audience

Design views around how your business users think about data, not around
how your database is structured. Group related fields into views that align
with departments or use cases — for example, `sales_overview`,
`customer_360`, or `product_analytics`.

<Tip>
  A single cube can be included in multiple views. For example, a `users`
  cube might appear in both a `customer_360` view and a `sales_overview`
  view, with different fields exposed in each.
</Tip>

### Favor focused views

Smaller, focused views are easier to navigate and lead to better AI
results. Rather than one massive view with hundreds of fields, create
several purpose-built views:

* Views are easier for business users to understand when they're
  scoped to a specific domain
* AI agents perform better with focused context
* Simpler views translate to simpler SQL queries with fewer joins

### Curate with metadata

Help your users understand what a view is for and how to use it:

* Set a clear [`description`][ref-view-description] to explain the
  view's purpose
* Use [`title`][ref-view-title] for user-friendly display names
* Add [`meta.ai_context`][ref-ai-context] to guide AI agents
* Organize fields into [`folders`][ref-view-folders] for logical
  grouping

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: sales_overview
      description: >
        Revenue and order metrics for the sales team.
        Includes order status, product details, and customer segments.
      meta:
        ai_context: >
          Use this view for questions about sales performance,
          revenue trends, and order analysis. The total_revenue
          measure includes only completed orders.

      cubes:
        - join_path: orders
          includes:
            - status
            - total_revenue
            - count
            - created_date

        - join_path: orders.customers
          prefix: true
          includes:
            - segment
            - region

      folders:
        - name: Order Metrics
          includes:
            - total_revenue
            - count
            - status

        - name: Customer Info
          includes:
            - customers_segment
            - customers_region
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`sales_overview`, {
    description: `Revenue and order metrics for the sales team.
      Includes order status, product details, and customer segments.`,
    meta: {
      ai_context: `Use this view for questions about sales performance,
        revenue trends, and order analysis. The total_revenue
        measure includes only completed orders.`
    },

    cubes: [
      {
        join_path: orders,
        includes: [
          `status`,
          `total_revenue`,
          `count`,
          `created_date`
        ]
      },
      {
        join_path: orders.customers,
        prefix: true,
        includes: [
          `segment`,
          `region`
        ]
      }
    ],

    folders: [
      {
        name: `Order Metrics`,
        includes: [
          `total_revenue`,
          `count`,
          `status`
        ]
      },
      {
        name: `Customer Info`,
        includes: [
          `customers_segment`,
          `customers_region`
        ]
      }
    ]
  })
  ```
</CodeGroup>

### Keep shared logic in cubes

Views are a curation layer. All business logic — SQL definitions, measure
calculations, join relationships — should live in cubes. Views should only
control which members are exposed, how they're named, and how they're
organized. This keeps your model [DRY][wiki-dry] and makes maintenance
straightforward.

### Define a metric on a view when it spans cubes

The exception is a metric whose parts live in different cubes. A view can define
its own [measures][ref-view-measures] and [dimensions][ref-view-dimensions] as
long as their `sql` only combines members the view already includes — a member
that reads a column instead is rejected at compile time:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: orders_overview
      # cubes: … includes orders.total_amount and line_items.count

      measures:
        - name: average_line_value
          type: number
          multi_stage: true
          sql: "{CUBE.total_amount} / NULLIF({CUBE.count}, 0)"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`orders_overview`, {
    // cubes: … includes orders.total_amount and line_items.count

    measures: {
      average_line_value: {
        type: `number`,
        multi_stage: true,
        sql: `${CUBE.total_amount} / NULLIF(${CUBE.count}, 0)`
      }
    }
  })
  ```
</CodeGroup>

[`multi_stage`][ref-multi-stage] matters whenever the parts come from different
cubes: it aggregates each of them before combining, instead of evaluating the
expression inside one joined scan where a `one_to_many` join between them would
inflate the numerator. If the cubes don't join to each other at all, see
[multi-fact views][ref-multi-fact-views]. The full example, with the `cubes`
block, is on the [view reference][ref-view-measures].

A cube can also own such a metric, by referencing the other cube's member
directly — that keeps it defined once for every view that includes it, at the
cost of one cube naming another. The [average order value
recipe][ref-recipe-aov] compares the two placements.

### Control visibility

Not every view should be publicly accessible. Use [`public`][ref-view-public]
to hide views that are meant for internal use or are still in development:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: internal_diagnostics
      public: false

      cubes:
        - join_path: system_metrics
          includes: "*"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`internal_diagnostics`, {
    public: false,

    cubes: [
      {
        join_path: system_metrics,
        includes: `*`
      }
    ]
  })
  ```
</CodeGroup>

For dynamic visibility based on user roles, use `COMPILE_CONTEXT`:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: arr
      description: Annual Recurring Revenue
      public: COMPILE_CONTEXT.security_context.is_finance

      cubes:
        - join_path: revenue
          includes:
            - arr
            - date
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`arr`, {
    description: `Annual Recurring Revenue`,
    public: COMPILE_CONTEXT.security_context.is_finance,

    cubes: [
      {
        join_path: revenue,
        includes: [`arr`, `date`]
      }
    ]
  })
  ```
</CodeGroup>

## Organizing members with folders

When a view includes many fields, [folders][ref-view-folders] help organize
them into logical groups. Cube supports both flat and nested folder
structures:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: customers

      cubes:
        - join_path: users
          includes: "*"

        - join_path: users.orders
          prefix: true
          includes:
            - status
            - price
            - count

      folders:
        - name: Personal Details
          includes:
            - name
            - gender
            - created_at

        - name: Order Analytics
          includes:
            - orders_status
            - orders_price
            - orders_count
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`customers`, {
    cubes: [
      {
        join_path: `users`,
        includes: `*`
      },
      {
        join_path: `users.orders`,
        prefix: true,
        includes: [`status`, `price`, `count`]
      }
    ],

    folders: [
      {
        name: `Personal Details`,
        includes: [`name`, `gender`, `created_at`]
      },
      {
        name: `Order Analytics`,
        includes: [
          `orders_status`,
          `orders_price`,
          `orders_count`
        ]
      }
    ]
  })
  ```
</CodeGroup>

Folders are displayed in supported [visualization tools][ref-viz-tools].
Check [APIs & Integrations][ref-apis-support] for details on folder
support. For tools that don't support nested folders, the structure is
automatically flattened.

## Grouping views with view groups

When a data model contains many views, [view groups][ref-view-groups] help
organize them into named collections by domain or purpose — for example,
`sales`, `finance`, or `people`. They're exposed through the
[`/v1/meta`][ref-meta-endpoint] API so downstream tools, AI agents, and
embedded analytics can present a navigable catalog.

See [View groups][ref-view-groups] for the full guide and the
[view group reference][ref-view-group-ref] for the complete list of
parameters.

## Next steps

* See the [view reference][ref-view-reference] for the full list of
  parameters
* Learn about [view groups][ref-view-groups] to organize views into
  named collections
* Learn about [access policies][ref-access-policies] to govern view access
* Explore [AI context][ref-ai-context] to improve AI query accuracy
* Use the [Semantic Model IDE][ref-ide] to develop views interactively

[ref-cubes]: /docs/data-modeling/cubes

[ref-view-reference]: /reference/data-modeling/view

[ref-view-description]: /reference/data-modeling/view#description

[ref-view-title]: /reference/data-modeling/view#title

[ref-view-public]: /reference/data-modeling/view#public

[ref-view-measures]: /reference/data-modeling/view#measures

[ref-view-dimensions]: /reference/data-modeling/view#dimensions

[ref-multi-stage]: /reference/data-modeling/measures#multi_stage

[ref-multi-fact-views]: /docs/data-modeling/multi-fact-views

[ref-recipe-aov]: /recipes/data-modeling/average-order-value#where-to-put-the-measure

[ref-view-folders]: /reference/data-modeling/view#folders

[ref-access-policies]: /reference/data-modeling/data-access-policies

[ref-ai-context]: /docs/data-modeling/ai-context

[ref-compile-context]: /docs/data-modeling/access-control/context

[ref-explore]: /docs/explore-analyze/explore

[ref-workbooks]: /docs/explore-analyze/workbooks

[ref-embedding]: /embedding

[ref-ide]: /docs/data-modeling/data-model-ide

[ref-viz-tools]: /admin/connect-to-data/visualization-tools

[ref-apis-support]: /reference#data-modeling

[ref-view-groups]: /docs/data-modeling/view-groups

[ref-view-group-ref]: /reference/data-modeling/view-group

[ref-meta-endpoint]: /reference/core-data-apis/rest-api/reference

[wiki-dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself


# Visual Modeler
Source: https://docs.cube.dev/docs/data-modeling/visual-modeler

Walks through Cube Cloud’s browser-based Visual Modeler for no-code modeling, including setup, workflow, and known limitations versus the code editor.

Visual Modeler editor provides the visual, no-code experience for building and enhancing
the [data model][ref-data-modeling] of your semantic layer from within your web browser.

Unlike the code-first [data model][ref-data-model] editor, Visual Modeler allows non-technical
users to participate in data modeling without writing code. However, it does not support
some advanced data modeling features listed as known [limitations](#limitations).

<Note>
  Available on [Premium and above plans](https://cube.dev/pricing).
</Note>

<Info>
  Visual Modeler extends and replaces the [Data Graph](https://cube.dev/blog/introducing-data-graph)
  feature.
</Info>

## Prerequisites

Visual Modeler integrates with the [development mode][ref-dev-mode],
[environments][ref-environments], and [continuous deployment][ref-continuous-deployment]
in Cube Cloud.

Once you start editing the data model in Visual Modeler editor, you will automatically
enter the development mode, so you can safely make changes and test them in
[Playground][ref-playground] without affecting your production deployment.

When you are ready to deploy your changes, it is recommended to create a pull request,
which should be reviewed before merging to the production environment.

## Working with cubes

You can see [cubes][ref-cubes] on the **Cubes** tab of Visual Modeler.

Cubes are represented as rectangles on the canvas with [joins][ref-joins] between them as
an [entity-relationship diagram][wiki-erd] (ERD). You can pan and zoom the canvas and
search cubes using the input box.

### Adding cubes

To add a cube from scratch, click the **+ Add Cube** button.

You can also generate the data model for a new cube based on the database schema.
To do so, click the **+ Generate Cube** button. It will bring up the
modal window where you can select a table from your data source:

<Frame>
  <img />
</Frame>

### Editing cubes

To edit a cube, click it on the canvas. Then, in the sidebar, click the **Edit**
button. This will bring up the modal window where you can edit the cube's details:

<Frame>
  <img alt="Edit cube dialog" />
</Frame>

Yu can also click **+ Add → Dimension**, **+ Add → Measure**, or
**+ Add → Access Policy** to quickly add respective members to the cube.

### Working with joins

You can add or edit joins via the **Relationships** tab while you're
[editing a cube](#editing-cubes).

You can also add joins visually by dragging a line on the canvas from the side of one
dimension to another:

<iframe title="YouTube video" />

## Working with views

You can see views on the **Views** tab of Visual Modeler.

Views are represented as rectangles on the canvas. Cubes that are involved in a view
and provide members for it, are shown to the left of the view.

### Adding views

To add a view, click the **+ Add View** button. It will bring up a dialog where you
can choose the base cube, set the view details such as name and title, and add join paths.

<Frame>
  <img alt="Adding a view" />
</Frame>

### Editing views

To edit a views, click it on the canvas. Then, in the sidebar, click the **Edit**
button.

## YAML mode

All modal windows mentioned above provide the option to use the *YAML mode* which can be
entered by clicking the **Edit with YAML** button.

In this mode, you can see and edit the data model represented using the [YAML syntax][ref-yaml-syntax].
That allows you to work around known [limitations](#limitations) and use all data modeling
features while staying in Visual Modeler editor.

<Frame>
  <img alt="YAML mode" />
</Frame>

## Limitations

Visual Modeler does not intend to support all available data modeling features.
You always have options to use the [YAML mode](#yaml-mode) in Visual Modeler or switch the
code-first [data model editor][ref-data-model].

Currently, Visual Modeler does not support the following features in its UI:

* Editing of [meta information][ref-meta] for cubes, views, and their members.
* Editing [segments][ref-segments], [hierarchies][ref-hierarchies], and [refresh keys][ref-refresh-keys] in cubes.
* Editing [folders][ref-folders] in views.
* Adding [subquery dimensions][ref-sub-query] and time dimensions with [custom granularities][ref-granularities] in cubes.
* Adding [drill members][ref-drill-members] and [rolling window][ref-rolling-window] measures in cubes.
* Adding [pre-aggregations][ref-pre-aggregations].
* Removing cubes and views.

Cubes and views using these data modeling features will still be displayed in
Visual Modeler. However, those features can only be edited via the [YAML mode](#yaml-mode)
or in the code-forst data model editor.

Additionally, Visual Modeler only allows editing of cubes and views that are
defined using the [YAML syntax][ref-yaml-syntax] (not JavaScript). Also, it does not
allow editing of [dynamic data models][ref-dynamic-data-models] or models which use
[Jinja][ref-jinja].

[ref-data-modeling]: /docs/data-modeling/overview

[ref-data-model]: /docs/data-modeling/data-model-ide

[ref-meta]: /reference/data-modeling/cube#meta

[ref-segments]: /reference/data-modeling/segments

[ref-hierarchies]: /reference/data-modeling/hierarchies

[ref-folders]: /reference/data-modeling/view#folders

[ref-refresh-keys]: /reference/data-modeling/cube#refresh_key

[ref-pre-aggregations]: /reference/data-modeling/pre-aggregations

[ref-sub-query]: /reference/data-modeling/dimensions#sub_query

[ref-granularities]: /reference/data-modeling/dimensions#granularities

[ref-drill-members]: /reference/data-modeling/measures#drill_members

[ref-rolling-window]: /reference/data-modeling/measures#rolling_window

[ref-dynamic-data-models]: /docs/data-modeling/dynamic

[ref-jinja]: /docs/data-modeling/dynamic/jinja

[ref-continuous-deployment]: /admin/deployment/continuous-deployment

[ref-yaml-syntax]: /docs/data-modeling/concepts/syntax#model-syntax

[ref-dev-mode]: /docs/data-modeling/dev-mode

[ref-environments]: /admin/deployment/environments

[ref-playground]: /docs/explore-analyze/playground

[ref-cubes]: /reference/data-modeling/cube

[ref-joins]: /reference/data-modeling/joins

[wiki-erd]: https://en.wikipedia.org/wiki/Entity–relationship_model


# Analytics Chat
Source: https://docs.cube.dev/docs/explore-analyze/analytics-chat

Conversational analytics interface for asking plain-language questions and getting trusted, AI-powered insights from your semantic layer.

Analytics Chat is Cube's conversational analytics experience — ask questions in plain language and get trusted, AI-powered insights without writing queries or building visualizations.

## How it works

The AI agent interprets your questions, generates queries against your semantic model, and presents findings in natural language. The agent can create multiple queries to answer complex questions and perform ad hoc analysis while maintaining full data governance through your semantic layer.

## Key features

* **Natural language queries** – Ask questions in plain language without knowing SQL
* **Multi-query reasoning** – The AI creates and synthesizes multiple queries for complex questions
* **Python analysis** – For work SQL can't express — forecasting, cohort analysis, statistical tests — the agent can run [Python](/docs/explore-analyze/workbooks/python-analysis) and render the result inline, then save it as a re-runnable workbook report or exploration (in preview)
* **Semantic model integration** – All queries run against your semantic model with proper access control and security, honoring the active [security context](/docs/explore-analyze/workbooks/querying-data#applying-a-security-context)—including an override applied by a developer or admin
* **Queued messages** – Send follow-up messages while the agent is still processing
* **Save your results** – Ask the agent to save a result as a [report](/docs/explore-analyze/workbooks) inside a workbook, or as a standalone [exploration](/docs/explore-analyze/explore#saving-explorations) when you don't want to create a workbook

## Discover available fields

You can ask the AI agent what's available in your semantic model before
diving into analysis. This is useful when you're new to a deployment or
exploring an unfamiliar view.

Try prompts like:

* "What fields are available?"
* "What measures and dimensions can I query in the Orders view?"
* "Describe the fields in the Customers view and what each one means."
* "What does the `lifetime_value` measure represent?"

The agent uses the descriptions and [AI context](/docs/data-modeling/ai-context)
defined on your views, measures, and dimensions to answer. Well-documented
semantic models produce better answers — see
[AI context best practices](/docs/data-modeling/ai-context#best-practices)
for guidance on writing descriptions the agent can use.

## Queued messages

You can send follow-up messages while the AI agent is still processing a
previous request. These messages are queued and processed in order once the
agent completes its current task.

This allows you to:

* **Refine your question** before the agent finishes, if you realize you want
  to adjust the scope or add constraints
* **Queue multiple questions** to ask a series of related questions without
  waiting for each response
* **Provide additional context** to give the agent more information that it
  can incorporate into its next response

## Sharing

Click **Share** in the chat header to grant view access to other members
of your account. You can pick individual users, a user group, or flip
**General access** to **Organization** to make the chat visible to
everyone. Use the **Copy link** button next to **Share** to grab a direct
URL once access is set up. Recipients still need to have access to the
deployment and the data the agent used; otherwise they'll see a "Chat
not available" page.

<Frame>
  <img alt="Analytics Chat share dialog" />
</Frame>

Recipients open the chat at the same URL as the owner and can scroll
through the full conversation, expand the agent's reasoning and tool
calls, and explore the charts and tables it produced — but they can't
send new messages. Only the owner can continue the thread, and the
header shows a "Shared by …" label so viewers always know whose
conversation they're reading.

If the owner asks more questions later, those messages — and the
agent's replies — show up for viewers on the next load.

## Embedding

Analytics Chat can be [embedded](/embedding) into your applications for customer-facing analytics, internal tools, or white-label solutions.

## Learn more

* [Workbooks](/docs/explore-analyze/workbooks) – Build and organize reports with AI assistance
* [Python analysis](/docs/explore-analyze/workbooks/python-analysis) – Save a Python analysis from chat as a re-runnable workbook report or exploration
* [Embedding](/embedding) – Embed analytics in your applications
* [Cube Agentic Analytics announcement](https://cube.dev/blog/cube-agentic-analytics) – Learn about the vision behind agentic analytics


# Apps
Source: https://docs.cube.dev/docs/explore-analyze/apps

Build custom, interactive data experiences backed by governed data from your Cube semantic layer.

<Warning>
  Apps are currently in preview, and their capabilities and authoring experience may
  still change. Reach out to the [Cube support team](/admin/account-billing/support)
  to activate this feature for your account.
</Warning>

Apps let you go beyond a dashboard's grid of widgets. An app is a custom,
interactive interface with its own layout, components, and controls, powered by
live data from reports in a Cube workbook.

Use an app when you need a guided workflow, a custom visual presentation, or an
interactive data tool that does not fit a standard dashboard layout.

## Create an app with the Cube agent

Open a workbook, switch to **Dashboard Builder**, and describe the app you want in
the agent chat. Include the business question, the data you want to show, and how
people should interact with it. For example:

> Build a revenue performance app with headline metrics, a monthly trend chart,
> and a searchable status filter. Use the company's brand colors.

The agent creates the workbook reports, writes the app, and installs reusable
components for common elements such as charts, tables, KPI cards, tabs, and
searchable controls. Continue prompting the agent to adjust the layout, behavior,
or styling.

## Preview and edit the app

Use **Preview** to interact with the running app. Select **Code** to inspect or
edit its files directly. After making code changes, click **Run** to apply them
and refresh the preview.

App components are copied into the app's source, so you can customize their code
and styling for that specific experience.

## Governed data access

An app reads the results of reports in its workbook. Cube runs those reports using
the viewer's existing permissions and passes the results to the app. The app does
not receive credentials for your data source or Cube APIs, and it cannot query
your warehouse directly.

Apps run inside a sandboxed frame, isolated from the Cube interface. The app's
data access remains governed by the semantic model and the permissions already
configured in Cube.

## Preview limitations

During preview:

* Apps are created and viewed from the workbook's Dashboard Builder.
* Publishing, embedding, scheduled refreshes, and deliveries are not yet
  supported for Apps.
* Apps can read workbook report results but cannot write data back to a source.
* Available components and APIs may change as the feature develops.


# Area
Source: https://docs.cube.dev/docs/explore-analyze/charts/chart-types/area

Show volume or part-to-whole trends over time with a filled region beneath the line.

Area charts add a filled region beneath the line. The fill communicates magnitude and cumulative volume, making area charts especially effective for stacked part-to-whole breakdowns over time.

## Variants

### Stacked

Each series is stacked on top of the previous one. The top edge shows the cumulative total; each filled band shows the individual contribution. Use this for part-to-whole breakdowns over time (e.g. revenue by product category over months).

### Percentage stacked (Stack %)

Each series is normalized to 100% at every X-axis value, showing proportional contribution over time. Use when relative share matters more than absolute volume.

### Overlaid

All series share the same baseline. Use only when series are clearly separated in value and you want to compare trajectories rather than totals — with many series, fills will occlude each other.

## Stacking

Set stacking behavior in the **Color & stacking** section of the Style tab. The **Stack**, **Stack %**, and **Overlay** options are the relevant modes for area charts.

See [Color & stacking](/docs/explore-analyze/charts/configuration/color-and-stacking) for palette options and stacked segment sorting.

## Axis behavior

Area charts use a temporal X axis for time dimensions — continuous and time-aware. For non-time fields, the axis is ordinal.


# Bar
Source: https://docs.cube.dev/docs/explore-analyze/charts/chart-types/bar

Compare values across categories with grouped, stacked, percentage, and horizontal variants.

Bar charts compare values across discrete categories. Use them when the magnitude of individual values matters and direct comparison between categories is the goal.

## Variants

### Basic

One dimension on the X axis, one measure on the Y axis. Each category gets a single bar.

<Frame>
  <img />
</Frame>

### Grouped

Each series renders as a separate cluster of bars side-by-side at every X-axis value. Best for comparing absolute values across multiple series at each category.

### Stacked

Series are stacked on top of each other at each X-axis value. Use when you want to show both individual contributions and the total at a glance.

### Percentage stacked (Stack %)

Each stack is normalized to 100%, showing each series as a proportion of the total per X-axis value. Use when relative distribution matters more than absolute values.

### Horizontal

All three vertical variants are also available horizontally. Horizontal bars work well for long category labels, many categories, or when a left-to-right reading direction feels more natural.

### Composite (bar + line)

Assign one series to the right Y axis and set its mark type to **Line** in [series configuration](/docs/explore-analyze/charts/configuration/series-configuration). This creates a dual-axis chart — useful for overlaying a rate on top of volume data (e.g. order count as bars, revenue per order as a line).

## Stacking

Stacking behavior is set in the **Color & stacking** section of the Style tab:

| Option        | Behavior                                                       |
| ------------- | -------------------------------------------------------------- |
| **Automatic** | Cube picks the best option based on your data                  |
| **Stack**     | Series at the same X value are stacked                         |
| **Group**     | Series at the same X value are placed side-by-side             |
| **Overlay**   | Series are drawn on top of each other (rarely useful for bars) |
| **Stack %**   | Series are stacked and normalized to 100%                      |

Stacking can also be set independently per Y-axis series — enabling grouped clusters of stacked sub-groups.

## Data labels

Bar charts support totals labels on stacked charts — showing the aggregate value above each full stack. Enable **Data Labels** in the Fields tab, then configure:

* **Format** — number format applied to the label value
* **Font size** — size of the label text
* **Position** — Outside end, Inside end, Inside center, or Inside base

## Axis behavior

Bar charts use an ordinal X axis — each bar is labeled independently, the axis is not time-aware, and categories not present in the result set are not plotted. With time fields, bars are ordered ascending automatically. For other data types, order follows the results table sort.

Tooltips on stacked bars are scoped to the segment under the cursor, not the full stack total.


# Boxplot
Source: https://docs.cube.dev/docs/explore-analyze/charts/chart-types/boxplot

Display the statistical distribution of a measure across categories using box-and-whisker plots.

Boxplots summarize the distribution of a numeric measure per category, showing the median, interquartile range, and outliers in a single mark. Use them to compare spread and skew across groups rather than just averages.

## Variant

### Box-and-whisker

One dimension on the X axis groups the data into categories. One measure on the Y axis provides the raw values. The chart computes the distribution statistics internally.

## Reading a boxplot

| Element         | Description                                   |
| --------------- | --------------------------------------------- |
| **Box**         | Interquartile range — 25th to 75th percentile |
| **Center line** | Median (50th percentile)                      |
| **Whiskers**    | Extend to min/max within 1.5× the IQR         |
| **Points**      | Values beyond the whiskers (outliers)         |

## Data structure

Boxplots require **raw, row-level data** — each row is one observation. Do not pre-aggregate before using a boxplot; the chart engine computes the distribution itself.

* **X axis** — the grouping dimension (e.g. product category)
* **Y axis** — the measure to distribute (e.g. sale price)


# Funnel
Source: https://docs.cube.dev/docs/explore-analyze/charts/chart-types/funnel

Show how a value narrows from stage to stage, such as signup → activation → purchase.

Funnel charts draw one bar per stage, centered on a shared midline, with a connector between each adjacent pair of stages. Each bar's width is proportional to its stage's value, so the figure narrows wherever values drop. Best for stage-to-stage conversion: how many users, orders, or events survive each step of a process.

## Fields

A funnel needs exactly two fields, picked on the Fields tab:

* **Stage** — a dimension (a time dimension works too, bucketed by its grain). Each distinct value becomes one stage.
* **Value** — a measure. It is rolled up per stage, so a result with extra columns still draws one bar per stage.

Stages keep the order your query returned them in. To reorder stages, adjust the sort in the results table — a stage that grows partway down is real data (re-entry, late-arriving events), so the chart never sorts it away for you.

A stage whose value is zero still draws, as a thin line in its stage color, so a gap in the data reads as a zero rather than as a missing stage.

## Direction

The **Direction** row at the top of the Style tab decides which way the stages progress:

* **Vertical** — stages run top to bottom, each bar spanning the width. The default.
* **Horizontal** — stages run left to right, each bar spanning the height. Useful when stage names are long, or alongside other left-to-right charts.

The taper, the connectors and every label carry over unchanged; only the axes swap.

Direction is greyed out until the chart has both a stage field and a value field.

## Conversion percentages

The connectors between stages carry the funnel's percentages. Two independent toggles in the **Data labels** section of the Style tab control them:

* **First** — each stage as a share of the first stage, drawn as `36% of first`. On by default.
* **Prev** — each stage as a share of the stage before it, drawn as `20% of previous`.

Turning both on stacks the two lines on each connector; turning both off leaves the connectors unlabeled. Whichever you select also appears in the tooltip, alongside the stage and value.

## Data labels

Each bar carries its stage name and value, both on by default and toggled in the **Data labels** section of the Style tab. The value's number format has its own picker, and one font size governs every label the funnel draws — the bar labels and the connector percentages alike.

Labels always sit at the bar's center. When a bar is too narrow to hold its label, the text switches from white to a dark color so it stays readable against the page background.

## Color

Each stage takes its own color from the palette selected in the **Palette** dropdown on the Style tab, in palette order. See [Palettes](/docs/explore-analyze/charts/configuration/color-and-stacking#palettes) for the built-in palettes and how to define a custom one.

## Legend

A funnel draws no legend by default — every bar already carries its stage name, so a legend would repeat it. Turn one on in the [**Legend**](/docs/explore-analyze/charts/configuration/color-and-stacking#legend) section of the Style tab, which also sets its placement. It names each stage in its palette color.


# Heatmap
Source: https://docs.cube.dev/docs/explore-analyze/charts/chart-types/heatmap

Visualize a measure across two categorical dimensions as a color-coded grid.

Heatmaps render data as a grid where each cell's color encodes a measure value at the intersection of two dimensions. Use them to spot patterns, dense clusters, and outliers across two categorical axes at once.

## Variant

### Color-scaled grid

One dimension on the X axis, one on the Y axis, and one measure mapped to the **Color** channel. Each cell's color encodes that measure's value for its row/column pair.

## Color palette

A continuous gradient palette is applied by default — low values map to the lighter end, high values to the darker end. Change or reverse the palette in the **Color** section of the Style tab.

For custom palettes, see [Color & stacking](/docs/explore-analyze/charts/configuration/color-and-stacking).

## Data structure

A heatmap requires exactly:

* One dimension on the **X axis**
* One dimension on the **Y axis**
* One measure on the **Color** channel

Cells with no data in the result set are left blank.


# HTML
Source: https://docs.cube.dev/docs/explore-analyze/charts/chart-types/html

Build fully custom layouts using HTML templates with Handlebars and JavaScript.

HTML charts let you render any layout that Vega-Lite cannot produce — custom scorecards, branded cards, rich tables, or any structure built with HTML, CSS, and JavaScript. Query results are available inside the template via [Handlebars](https://handlebarsjs.com/) expressions.

## Variant

### HTML template

A free-form HTML document with Handlebars expressions. Write any markup and bind query result data directly in the template.

## Template structure

Query results are available in the template context under `result`.

**Access the first row** with `result._first`:

```html theme={"dark"}
<div class="scorecard">
  <h2>{{result._first.order_items.status}}</h2>
  <p>{{result._first.order_items.count}} orders</p>
</div>
```

**Iterate over all rows** with `{{#each result.data}}`:

```html theme={"dark"}
<ul>
  {{#each result.data}}
    <li>{{this.order_items.status}}: {{this.order_items.count}}</li>
  {{/each}}
</ul>
```

## Using JavaScript

Standard `<script>` tags are supported, enabling the use of charting libraries (D3, Chart.js, etc.) or any JavaScript that manipulates the rendered DOM.

```html theme={"dark"}
<canvas id="myChart"></canvas>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
  const labels = [{{#each result.data}}"{{this.order_items.status}}"{{#unless @last}},{{/unless}}{{/each}}];
  const data = [{{#each result.data}}{{this.order_items.count}}{{#unless @last}},{{/unless}}{{/each}}];
  new Chart(document.getElementById('myChart'), {
    type: 'bar',
    data: { labels, datasets: [{ data }] }
  });
</script>
```


# Chart types
Source: https://docs.cube.dev/docs/explore-analyze/charts/chart-types/index

Overview of all built-in chart types available in Cube workbooks.

Cube includes a library of built-in chart types covering the most common visualization patterns. Each type is designed for specific data shapes — choose the one that best fits your query structure and the question you're answering.

* [Bar](/docs/explore-analyze/charts/chart-types/bar)
* [Line](/docs/explore-analyze/charts/chart-types/line)
* [Area](/docs/explore-analyze/charts/chart-types/area)
* [Scatter](/docs/explore-analyze/charts/chart-types/scatter)
* [Pie & donut](/docs/explore-analyze/charts/chart-types/pie)
* [Funnel](/docs/explore-analyze/charts/chart-types/funnel)
* [Sankey](/docs/explore-analyze/charts/chart-types/sankey)
* [Heatmap](/docs/explore-analyze/charts/chart-types/heatmap)
* [Boxplot](/docs/explore-analyze/charts/chart-types/boxplot)
* [Table](/docs/explore-analyze/charts/chart-types/table)
* [KPI](/docs/explore-analyze/charts/chart-types/kpi)
* [Map](/docs/explore-analyze/charts/chart-types/map)
* [HTML](/docs/explore-analyze/charts/chart-types/html)

For configuration options that apply across chart types — axes, color, series settings, tooltips — see [Configure charts](/docs/explore-analyze/charts/configuration).

## Recommended chart type

When your query returns a result, Cube outlines the one chart type that best fits it and labels it
**Recommended**. It is a suggestion: every other available type stays selectable, and the outline
yields as soon as you pick a type in that picker.

Cube never applies a chart type for you. The recommendation is always only outlined, wherever the
picker appears, and choosing a type is always your action.

### What Cube looks at

The recommendation reads the shape of your query and its result: how many measures, dimensions and
time dimensions you selected, how many distinct values each dimension has, and how long the
category labels are. It is computed in your browser and is not saved — the suggestion lasts for the
current session only.

Where a threshold is involved, it comes from
[Draco](https://idl.cs.washington.edu/papers/draco/) (Moritz et al., *Formalizing Visualization
Design Knowledge as Constraints*, IEEE VIS 2018), which encodes established visualization research
as rules: a category axis becomes crowded past 12 values, a color or stacking channel saturates
past 10 series, and no axis reads past 30 values.

One number is Cube's own rather than Draco's: a mean label length past **16 characters** counts as
long.

No threshold is applied to the number of rows. A few rules read the row count directly — a KPI
needs exactly one row, a heatmap needs its grid at least half filled — but none of them treats "too
many rows" as a reason to recommend a different chart, because the row count follows the
granularity you chose rather than the shape of your query.

### The conditions

Cube first checks whether the query disqualifies every chart, and recommends the
[table](/docs/explore-analyze/charts/chart-types/table) if it does:

| Recommendation | When                                                                                                  |
| -------------- | ----------------------------------------------------------------------------------------------------- |
| **Table**      | The query has no measure, two time dimensions, three or more dimensions, or a category past 30 values |

A query meeting any of these has no chart encoding that reads well, so the table is the honest
answer. [Maps](/docs/explore-analyze/charts/chart-types/map) are the exception and are still
recommended over the table — a map has no category axis to crowd, so a large number of plotted
places is normal rather than unreadable.

Otherwise Cube checks these in order and takes the first that matches:

| Recommendation       | When                                                                                                                                                           |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Map**              | The query contains latitude and longitude                                                                                                                      |
| **KPI**              | One measure, no dimensions, and a single row                                                                                                                   |
| **Line**             | A measure over a time dimension, optionally split by one category of up to 10 values                                                                           |
| **Scatter**          | Two or more measures with no time dimension, across one category or several rows — the shape for correlating them                                              |
| **Bar (stacked)**    | One measure split by two categories, the first up to 12 values and the second up to 10                                                                         |
| **Heatmap**          | One measure split by two categories, both past those bounds — the first past 12 values and the second past 10 — whose combinations fill at least half the grid |
| **Bar**              | One measure across up to 12 categories whose labels average 16 characters or fewer                                                                             |
| **Bar (horizontal)** | The same, where the labels are longer or the categories run past 12                                                                                            |

The two [bar](/docs/explore-analyze/charts/chart-types/bar) rows are variants of the same chart
type, not separate ones.

Pie, funnel, sankey, area, boxplot and HTML are never recommended — pick them yourself. Pie's shape,
one measure across a few categories, is the one Bar already answers, and a bar chart compares those
values more accurately. A funnel additionally asserts that its stages are sequential steps of one
process, which the shape of a query does not reveal. All six stay available in the picker like any
other chart type.

### When nothing is recommended

Cube suppresses the recommendation rather than guessing. You will see no outline when:

* no rule matches the query cleanly;
* a measure over time is split into 11 to 30 series — too many for a color channel, too few to give
  up on;
* a value it needs is still unknown, such as the number of distinct values in a dimension;
* the result came back empty, so there is nothing to draw;
* the result was truncated by a row limit, so the counts it would read are incomplete;
* you have picked a type by hand in the picker you are looking at. The outline returns the next
  time you open it — including on the type you applied, since Cube marks the best fit whether or
  not it is already on screen.


# KPI
Source: https://docs.cube.dev/docs/explore-analyze/charts/chart-types/kpi

Highlight key metrics with composable blocks — numbers, comparisons, progress bars, sparklines, text, and HTML.

KPI tiles highlight important metrics and key performance indicators. Rather than a single fixed layout, KPIs are **row-based and composable** — you build the tile by stacking blocks of different types, each configured independently.

## Getting started

The KPI visualization starts with a **Number** block that compares the first and second rows of your result for the first numeric column.

To add a new block, click the **+** button inside the visualization and choose the block type. To edit a block, click it in the visualization — the configuration panel updates to show that block's settings.

Reorder blocks by dragging the handle on the left side of each block. Delete a block with the trash icon in its configuration panel.

## Block types

### Number

Displays a single value from your query result.

| Setting               | Description                                 |
| --------------------- | ------------------------------------------- |
| **Field**             | The measure or dimension to display         |
| **Row**               | Which row of the result to read from        |
| **Format**            | Number formatting (currency, percent, etc.) |
| **Font size / color** | Text appearance                             |
| **Alignment**         | Left, center, or right                      |

### Comparison

Displays a current value alongside a previous value with a calculated difference. Use this to show period-over-period change or target vs. actual.

| Setting                             | Description                                                                                      |
| ----------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Current field / row**             | The primary value                                                                                |
| **Previous field / row**            | The value to compare against — can be a different column or a different row from the same column |
| **Difference format**               | Absolute, percentage, or both                                                                    |
| **Positive color / Negative color** | Colors applied based on whether the change is positive or negative                               |

To compare to a static goal, add a column to your query that always returns the same number (e.g. a calculated field with a constant), then select it as the **Previous** field.

### Progress bar

Shows a value relative to a target as a progress bar or circle. Useful for goal tracking.

| Setting                | Description                           |
| ---------------------- | ------------------------------------- |
| **Value field / row**  | The current progress value            |
| **Target field / row** | The goal or maximum value             |
| **Style**              | Bar or circle                         |
| **Color**              | Fill color for the progress indicator |

<Tip>
  To compare against a static number like a quarterly goal, add a calculated field that always returns that number and use it as the **Target** field.
</Tip>

### Sparkline

Renders a compact trend chart — either a bar or line — within the KPI tile. Use this to show the trend behind the headline number.

| Setting              | Description                                                     |
| -------------------- | --------------------------------------------------------------- |
| **Series measure**   | The measure to plot                                             |
| **Series dimension** | The dimension to use as the X axis (typically a time dimension) |
| **Chart type**       | Bar or line                                                     |
| **Height / Width**   | Dimensions of the sparkline in the tile                         |
| **Max points**       | Limits the number of data points rendered                       |
| **Colors**           | Line/fill colors                                                |

### Text

A Markdown-enabled text field for titles, headings, or descriptions within the tile. Supports standard Markdown formatting.

Use text blocks for short labels and headings inside the KPI. For complex layouts with Markdown, use the [HTML block](#html) or consider the [Custom visualization](/docs/explore-analyze/charts/custom) instead.

### HTML

A free-form HTML block rendered inside the KPI tile. Use this for advanced custom layouts that go beyond what the other block types support.

## Layout controls

KPI tiles have a layout panel that controls how blocks are arranged:

| Setting       | Description                                                     |
| ------------- | --------------------------------------------------------------- |
| **Direction** | Row (blocks side-by-side) or Column (blocks stacked vertically) |
| **Alignment** | How blocks align on the cross axis                              |
| **Justify**   | How blocks are distributed along the main axis                  |
| **Gap**       | Spacing between blocks                                          |
| **Wrap**      | Whether blocks wrap to a new line when the tile is narrow       |

## Converting to raw Markdown

If you need customization beyond what the block builder supports, you can convert the KPI visualization directly to Markdown by clicking on the Markdown visualization option.

<Warning>
  Converting to Markdown is a one-way operation. If you do this accidentally, use the undo button to revert.
</Warning>


# Line
Source: https://docs.cube.dev/docs/explore-analyze/charts/chart-types/line

Track how a measure changes over time or across an ordered dimension.

Line charts connect data points with a continuous line. Use them when the direction and rate of change matter — trends over time, trajectories of multiple series, or any ordered dimension where continuity is meaningful.

## Variants

### Single series

One measure plotted against a time or ordered dimension. The simplest and most common use case.

### Multi-series

Multiple lines plotted on the same axes. Map a second dimension to the **Color** channel to split one measure into one line per dimension value, or add multiple measures to the Y axis to plot them as separate series.

### With reference line

A horizontal reference line marks a target, threshold, or benchmark. Added via the **Axes** section of the Style tab.

## Reference lines

Add a horizontal reference line in the **Y axis** section of the Style tab. Set the value, label, color, and line style (solid, dashed, or dotted). A labelled line also takes horizontal (start / middle / end) and vertical (above / below) placement for its text. Multiple reference lines are supported.

See [Axes](/docs/explore-analyze/charts/configuration/axes) for the full configuration reference.

## Axis behavior

Line charts use a temporal X axis for time dimensions — continuous, time-aware, and not constrained to the result set. For non-time dimensions, the axis is ordinal and follows the result set sort order. Gaps in the line indicate missing data points.

## Combining with bars

To layer a line on top of a bar chart, add a second series to the Y axis, set its mark type to **Line** in [series configuration](/docs/explore-analyze/charts/configuration/series-configuration), and assign it to the right Y axis for a dual-axis layout.


# Map
Source: https://docs.cube.dev/docs/explore-analyze/charts/chart-types/map

Plot geographic data as point maps (latitude/longitude) or region maps (choropleth from GeoJSON polygons).

Map charts visualize geographic data in two modes:

* **Point map** — plot rows at their latitude/longitude coordinates, optionally sized and colored by additional fields.
* **Region map** — paint polygons (countries, US states, or any custom [GeoJSON](https://en.wikipedia.org/wiki/GeoJSON)) as a choropleth driven by a measure.

<Frame>
  <img />
</Frame>

## When to use

* **Point map** — locations with known coordinates (stores, shipments, sign-ups), geographic clusters and outliers.
* **Region map** — measures aggregated by country, state, postcode, sales territory, or any user-defined polygon set.

## Chart type

Pick **Point** or **Region** in the chart settings panel's **Type** row. The default is **Point**.

## Projection

| Projection        | Description                                                         |
| ----------------- | ------------------------------------------------------------------- |
| **Mercator (2D)** | Standard flat map projection — best for most use cases              |
| **Globe (3D)**    | Spherical globe view — useful for data spanning multiple continents |

Both modes support either projection.

## Point map

A point map requires:

* **Latitude** — numeric field containing decimal latitude.
* **Longitude** — numeric field containing decimal longitude.

Optional:

* **Size** — numeric measure that scales point radius proportionally.
* **Color** — dimension or measure that colors points by category or value.

### Point color

When no **Color** field is assigned, all points render in the configurable **Default color**. When a dimension is assigned, each unique value gets a distinct color from the active palette — pick from the built-in palettes or supply a custom one, see [Color and stacking](/docs/explore-analyze/charts/configuration/color-and-stacking).

### Point size

Assign a numeric measure to the **Size** channel to scale point radius by value. The size range (minimum and maximum radius in pixels) is configurable in the settings panel.

### Clustering

Clustering groups nearby points into a single circle that expands on zoom. It is **off by default** and can be enabled in the settings panel.

## Region map

A region map requires:

* **Source** — the GeoJSON to render: `World countries`, `US states`, or `Custom`.
* **Property** — which property in each GeoJSON feature acts as the join key (e.g. `name`, `ISO3166-1-Alpha-2`, `state_code`).
* **Dimension** — which column from your query joins to **Property**.
* **Measure** — the numeric measure that drives the choropleth fill.

Built-in sources expose a fixed list of allowed properties. **Custom** lets you point at any public GeoJSON URL; the property dropdown then enumerates every key present in the feature collection.

When the chart enters Region mode, the join dimension and measure are auto-picked when an unambiguous match exists in your query.

The choropleth gradient comes from the active palette — pick from the built-in palettes or supply a custom one, see [Color and stacking](/docs/explore-analyze/charts/configuration/color-and-stacking).

### Custom GeoJSON

When **Source** is set to **Custom**, paste a URL serving a GeoJSON `FeatureCollection`. Requirements:

* Served over HTTPS with CORS enabled.
* Polygons or multipolygons (not points or lines).
* Each feature must have a `properties` object containing the join key.

The fetched GeoJSON is cached for the session.

### Unmatched regions

Regions in the GeoJSON with no matching data row are hidden by default. Toggle **Fill unmatched** in the settings panel to render them with the **Default color** at reduced opacity instead.

## Tooltip fields

The **Tooltips** section controls which fields appear when a user hovers over a point or region. See [Tooltips](/docs/explore-analyze/charts/configuration/tooltips).

## Map interaction

The map is interactive — users can pan and zoom. Viewport changes persist while you edit other settings; switching the data source or projection re-fits the camera to the new bounds.


# Pie & donut
Source: https://docs.cube.dev/docs/explore-analyze/charts/chart-types/pie

Show how a single measure is distributed across a small number of categories.

Pie charts divide a circle into slices proportional to each category's share of the total. Best for communicating part-to-whole proportions to a broad audience when you have a small number of clearly distinct categories (typically five or fewer).

## Variants

### Pie

Standard filled circle. Each slice's arc length is proportional to its value.

### Donut

A pie with a hollow center. Select **Donut** under **Shape** in the Style tab to switch; select **Pie** to switch back.

## Center total

A donut shows the measure's grand total in its hole by default, using the measure's number format. Use the **Show total** button in the Data labels section of the Style tab to turn it off or on again.

The button appears only for a donut, since a pie has no hollow center to fill.

The total uses the font size set in the Data labels section, the same as the slice labels. If you turn on the **Percentage** label, the total also shows `100%` on a second line, since the whole is the entire circle.

## Color and slice ordering

Slices take their colors from the palette selected in the **Palette** dropdown on the Style tab, in palette order, matched to the sort order of your query results. See [Palettes](/docs/explore-analyze/charts/configuration/color-and-stacking#palettes) for the built-in palettes and how to define a custom one. To change which slice appears first, adjust the sort in the results table.

A pie draws a legend naming each slice. Hide it or move it in the [**Legend**](/docs/explore-analyze/charts/configuration/color-and-stacking#legend) section of the Style tab.


# Sankey
Source: https://docs.cube.dev/docs/explore-analyze/charts/chart-types/sankey

Show flows between nodes, such as order status to year or channel to conversion.

Sankey diagrams draw one node per distinct endpoint and one ribbon per flow, with each ribbon's thickness proportional to its value. Best for showing how a quantity divides and moves between two sets of things: order statuses across years, traffic channels into outcomes, or one step of a user journey into the next.

## Fields

A sankey needs exactly three fields, picked on the Fields tab:

* **Source** — a dimension (a time dimension works too, labelled by its grain). The node a flow leaves.
* **Target** — a dimension. The node a flow enters.
* **Value** — a measure. Each row's value becomes one ribbon's thickness.

Each result row is read as one flow, so a query grouped by two dimensions with one measure draws directly. **Swap** exchanges the source and target, which reverses every ribbon's direction.

Stages come from shared node names rather than from a stage field: rows `A → B` and `B → C` draw as a three-stage diagram, because `B` appears as both a target and a source. Two dimensions that share no values always draw two stages.

A row with a blank endpoint, or a value of zero or less, is not a flow and is left out — a sankey cannot draw a ribbon with no thickness.

A flow that returns to a node it already passed through is a cycle. The returned-to node is split into a numbered copy so the diagram still lays out left-to-right — `A → B → A` draws as `A → B → A (2)`. Every copy of a node shares its color, and hovering one highlights the ribbons of all of them.

A node that flows directly to itself has no valid split, and the chart names the loop and asks you to remove one hop.

## Node grouping

A wide breakdown can return more flows than a diagram can carry, and the small ones become unreadable first. Node grouping folds them into a single **Other** node per side, so the tail stays represented as an aggregate instead of vanishing. It is off until you pick a mode, in the Node grouping section of the Fields tab:

* **Minimal share** — fold every node below a percentage of its side's total. A node sitting exactly on the threshold is kept.
* **Top N nodes** — keep the N largest nodes per side. Tied nodes at the cutoff are kept together, so asking for the top 3 can keep more than 3 when third place is shared.

The two sides fold independently, each against its own total, because a node that is small as a target may be large as a source. The bucket's name is yours to set; leave it blank for **Other**. When both sides fold at once, the two buckets are named apart — **Other (source)** and **Other (target)** — so one is not read as the other.

A single node is never folded on its own — replacing one named node with a same-sized **Other** would say less than leaving it alone. A node whose own value already matches the bucket's name is also left out of the bucket, so a real category called "Other" is never merged into it.

The bucket stands for a set of members rather than one, so it has no query behind it: clicking a ribbon that touches it does not drill down.

## Truncation

Independently of grouping, a sankey draws at most 50 flows, keeping the largest. This is a backstop against a runaway result, not a legibility control — when it removes anything, a warning appears beside the Flows heading on the Fields tab saying how many of the total it is showing, pointing at node grouping, which is the real answer for a diagram too wide to read.

## Data labels

Each node carries its name and, optionally, its value. Both are independent buttons in the Data labels section of the Style tab: **Name** is on by default, **Value** is off. With both on, the value follows the name in parentheses; with only the value on, the node carries a bare number; with both off the diagram draws no labels.

A node's value is the larger of its inflow and its outflow, and takes the value field's own number format.

Labels sit to the right of their node, except in the final stage, where they flip to the left so they stay inside the frame.

## Color

Each node takes its own color from the palette selected in the **Palette** dropdown on the Style tab. The color follows the node's name rather than its position, so filtering or re-sorting the query does not repaint the diagram. See [Palettes](/docs/explore-analyze/charts/configuration/color-and-stacking#palettes) for the built-in palettes and how to define a custom one.

The **Flows** control sets where a ribbon takes its color from:

* **Source** — the color of the node the ribbon leaves. The default.
* **Neutral** — one muted color for every ribbon, leaving the nodes to carry the palette.
* **Target** — the color of the node the ribbon enters.

A sankey draws no legend, and has no setting for one: every node is labeled in the diagram itself.

## Tooltips

Hovering a ribbon shows the result columns named in **Tooltip fields** on the Fields tab, which starts as every column in the query except the three the diagram already draws — source, target and value. Add them back like any other field if you want them repeated. Hovering a node shows its name and value.

See [Tooltips](/docs/explore-analyze/charts/configuration/tooltips) for adding, removing and reordering fields.

## Drill down

Clicking a ribbon drills into the row behind that flow. Ribbons touching a grouped **Other** node are not clickable, since that node covers several members at once.


# Scatter
Source: https://docs.cube.dev/docs/explore-analyze/charts/chart-types/scatter

Plot two measures against each other to find correlations, clusters, and outliers.

Scatter charts plot individual data points using two measures as X and Y coordinates. Use them to explore relationships between measures, identify clusters, and spot outliers across a population of entities.

## Variants

### Basic scatter

Two measures on the X and Y axes. Each row in your result set becomes one point.

### With color grouping

Map a dimension to the **Color** channel to assign each point a color by category. Use this to compare how different groups distribute across the same two measures.

### With size encoding

Map a third numeric measure to the **Size** channel to scale each point's radius by value. Use this to encode a third variable without adding a new axis.

## Size encoding

Assign a measure to the **Size** channel in the Fields tab. Points scale proportionally to the measure value. Configure the minimum and maximum radius in the Style tab.

## Tooltips

All mapped fields appear in the tooltip by default. Add or remove fields in the **Tooltips** section of the Fields tab.

See [Tooltips](/docs/explore-analyze/charts/configuration/tooltips) for details.


# Table
Source: https://docs.cube.dev/docs/explore-analyze/charts/chart-types/table

Display query results as a configurable table with pivots, conditional formatting, and custom styling.

The table visualization presents query results in a structured grid. Unlike the raw results table in the query panel, the table visualization is designed for sharing — it supports pivots, conditional formatting, custom styling, and a per-cell menu for links, copy, and drill-down.

## Showing and hiding columns

Right-click a column header in the table visualization to hide it. Hidden columns can be restored from the **Fields** section of the configuration panel. You can also hide columns from the column options menu (the three-dot menu on each column header).

## Reordering columns

Drag a column header to reorder columns. Dimensions and measures can be interspersed freely when no pivot is active.

## Sorting

Sorting is set on the query, not on the table — use the column header menus or the **Sort** button. See [Sorting](/docs/explore-analyze/workbooks/querying-data#sorting).

Pivot columns are the exception: they can also be sorted from the table itself, as described under [Pivots](#pivots).

## Pivots

Pivoting a dimension turns its unique values into columns, creating a cross-tab view. Pivots are
configured in the **Pivot** section of the **Fields** tab, below the **Fields** section that lists
the columns. The **Pivot** section holds:

* **Rows** — dimensions listed down the left.
* **Columns** — dimensions whose values become column headers. Drag a dimension here to pivot it.
* **Values** — the measures filling the cells.
* A **Measures** placeholder that decides where the measure names go. Drag it to **Columns** to run
  them across the top, or to **Rows** to run them down the side.

Pivot behavior:

* Pivot columns can be sorted by clicking the column header, including the totals column.
* Pivot columns can also be sorted by row values — click a row number to sort by that row, including the totals row.
* Pivoted columns can be hidden, but hiding is indexed to the specific value (e.g. hiding `status: returned`), not position.

### Pivot presets

Open the menu in the corner of the Pivot section to apply a preset — a one-shot arrangement of the three drop zones that you can rearrange further afterwards:

* **Table (default)** — dimensions to **Rows**, measures to **Values**, measure names across the
  top; the standard cross-tab.
* **Vertical records** — the transpose: dimensions to **Columns**, measures to **Values**, and the
  **Measures** placeholder to **Rows**, so the measure names run down the side and a single record
  reads as a list of labelled values. This produces the values-as-rows layout. On a query with no
  measures, **Values** stays empty and the table shows its pivot headers alone.

**Reset**, beside the menu, restores the **Table (default)** arrangement — the two write the same
layout. It is disabled while the pivot already matches it.

## Row grouping

Group rows by their leading dimensions into collapsible headers, so each grouped
dimension's value is shown once for the whole group instead of repeated on every row.

Turn it on with the **Group rows** toggle in the **Values** section of the **Style**
tab. The toggle is disabled — with a tooltip explaining why — unless the table has at
least two row dimensions and no column pivot. You can also ask [Analytics
Chat](/docs/explore-analyze/analytics-chat) to group the table's rows.

With grouping on, every row dimension except the innermost becomes a group level: rows
nest one header per level, kept contiguous by that dimension's first-appearance order,
with the header showing the dimension's value once instead of on every row underneath.

Turning it on also adds a **Row grouping** section to the **Style** tab, with:

* **Expand all groups** / **Collapse all groups** — set every group's expand state at once.
* **Subtotals** (Σ) — show an aggregated value for every measure on each group header row.
  See [Per-group subtotals](#per-group-subtotals).
* Text color, background color, and text formatting for the group header rows.

Each group-level column's card in the **Columns** section gets a **Default state**
control (**Expanded** or **Collapsed**) that sets whether new groups on that level start
open or closed. It only sets the default — a viewer's own expand/collapse of an
individual group isn't affected by changing it afterwards.

### Per-group subtotals

With grouping on, the **Subtotals** (Σ) toggle in the **Row grouping** section adds an
aggregated value for every measure to each group header row, at every nesting level. Not
to be confused with [pivot subtotals](#subtotals), which add a **Total for ‹value›**
column per pivot group rather than a value per group header row.

Each subtotal is queried at its own group's grain rather than summed from the rows below
it. That distinction matters for any measure that doesn't add up: an `avg` shows the true
average over the group instead of an average of averages, and a `count_distinct` counts a
value once even when it appears in several child groups. As a result a subtotal can
legitimately differ from the sum of the rows beneath it — for a distinct count it is
usually smaller.

It also means the value stays correct on a collapsed group, where there are no visible
rows to add up at all.

Measures built on window functions (`RUNNING_TOTAL`, `OFFSET`, or a SQL `OVER` clause)
can't be recomputed at another grain, so their cells stay empty on group rows — the same
exclusion that [row, column, and pivot
totals](/docs/explore-analyze/workbooks/querying-data#subtotals) make. Period-comparison
columns are also left empty. The toggle is disabled unless grouping is active and the
values are placed in columns, since the [values-as-rows layout](#pivot-presets) has no
per-measure column for a subtotal to sit under.

## Column field options

Configure individual columns in the **Columns** section of the **Style** tab (or via the dropdown arrow on a field in the **Fields** section):

| Option                 | Description                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| **Label**              | Override the column header text                                                                  |
| **Alignment**          | Left, center, or right. Defaults to the column's data type — numbers right, everything else left |
| **Vertical alignment** | Top, middle, or bottom — where the value sits when the row is taller than one line               |
| **Word wrap**          | Allow cell content to wrap to multiple lines                                                     |
| **Width**              | **Flex** (a weight) or **Fix** (pixels) — see [Column width](#column-width)                      |
| **Hide**               | Show or hide the column                                                                          |

When a cell's value is too long for its column and word wrap is off, the value is truncated with an ellipsis. Hover over a truncated cell to see its full value in a tooltip.

## Column width

Each column's width is set independently on its card in the **Columns** section of the **Style** tab, using the **Flex** / **Fix** pair and the number next to it. A column is in one of two modes:

* **Flex** (the default) — the column shares the table's available width with the other flexible columns, in proportion to its **weight**, entered next to the mode as `×1`. A column with weight `2` is twice as wide as a column with weight `1`. New columns start at weight `1`, so by default all columns share the width equally and the table stretches to fill its tile.
* **Fix** — the column is locked to an exact pixel width, entered as `px`, and no longer participates in the weight-based distribution. Fixed columns keep their width regardless of the tile size; if the fixed columns don't fill the tile, the remaining space is left blank. Pixel widths start at 10 and step in tens.

You can mix the two: give a label column a fixed width and let the metric columns flex to share the rest.

### Setting widths

* **In the panel** — pick **Flex** or **Fix** for a column and enter its weight or pixel value. Switching to **Fix** reuses the column's last fixed width if it had one, and otherwise starts from the width it's currently drawn at.
* **By dragging** — drag the border between two column headers on the table. The change is saved into the column's current mode (a flexible column keeps flexing at its new relative size; a fixed column updates its pixel width).
* **Fit** — the **Fit** button on a column's card sizes it to its content and switches it to **Fix** at that width.

  <Note>
    Fit measures the rows currently rendered on screen. If a wider value is further down a long, scrolled table, fit again after scrolling to it.
  </Note>

### Bulk controls

At the top of the **Columns** section, three buttons apply a width mode to every column at once:

* **Flex** — converts every column to flexible, deriving each weight from its current width (so the layout doesn't jump). Enabled only when at least one column is fixed.
* **Fix** — freezes every column at its current rendered pixel width. Enabled only when at least one column is flexible.
* **Fit** — sizes every column to its content and fixes it at that width, in a single action. Like the per-column **Fit**, it measures the rows currently rendered on screen.

<Note>
  Under a column pivot, a width set on a measure applies to every column generated for that measure.
</Note>

## Showing columns as links, bars, sparklines, or images

By default, a column displays its value. It can also be drawn as an inline link, an inline bar, a sparkline, or an image — from the column's card in the **Columns** section of the **Style** tab.

Each card has a **Value** toggle, a **Bars** / **Sparkline** pair, and separate **Link**
and **Image** buttons:

* **Value** shows the formatted value in the cell. It **composes** with a bar or a sparkline rather than excluding it — a cell can show a bar and its value together.
* **Bars** and **Sparkline** are mutually exclusive: picking one replaces the other, and clicking the active one again clears it.
* **Link** and **Image** are independent of each other, so a column can be both — an image with a declared link renders as a clickable thumbnail. Switching one off leaves the other alone.
* With nothing active, **Value** is forced on and its toggle disabled — so a plain column always shows its value.
* Each button is offered only where it applies: bars and sparklines on **numeric** columns, **Link** only on a column whose dimension declares links or uses `format: link` (see [Inline links](#inline-links)), and **Image** where the dimension declares `format: imageUrl` or the column's values are image URLs (see [Images](#images)). In link mode the value *is* the link text, so **Value** stays forced on there too; image mode draws the thumbnail instead of the value, so **Value** is forced off and its toggle disabled. With **Link** and **Image** both on, image wins: the thumbnail replaces the link text and becomes the click target. Only bars and sparklines leave the toggle free, because only they draw something the value can sit beside.

### Inline links

A column renders its values as clickable links when the data model says so — links are
declared in the semantic layer, not authored in the chart.

There are two ways to get one:

* **[`links`](/docs/data-modeling/dimensions#links) on the dimension.** The link marked
  `primary` renders inline on the cell value. Every link on the dimension — primary or not
  — stays available from the [cell menu](#cell-menu).
* **[`format: link`](/reference/data-modeling/dimensions#format) on the dimension**, when the
  value already *is* a URL. Use the object form to show a label instead of the raw URL.

For a column whose dimension declares links, selecting the **Link** button reveals a picker for
which of the declared links renders inline (inert when the dimension declares only one).
Clicking the link text opens it; clicking elsewhere in the cell selects it and opens the
cell menu as usual.

### Inline bars

Display a numeric column as a proportional in-cell bar by selecting the **Bars** button on the column's card. Each bar's length reflects the value's magnitude within the column's range.

| Option                   | Description                                                                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Show value**           | The shared **Value** toggle on the column's card. Turn it off for a bar-only cell.                                                                                        |
| **Positive bar color**   | Fill color for non-negative bars                                                                                                                                          |
| **Negative bar color**   | Fill color for negative bars (used when the column contains both positive and negative values)                                                                            |
| **Bar scale**            | **Auto** anchors each bar at zero and scales to the column's largest value, so even the smallest value still shows a bar; **Manual** scales against the bounds you set    |
| **Lower / Higher bound** | The minimum and maximum (in the column's raw units) used when **Bar scale** is **Manual**. Pre-filled to match the Auto range, so switching modes doesn't shift the bars. |

When a column contains both positive and negative values, bars are drawn in both directions from a centered zero baseline — positive values to the right, negative to the left — using the positive and negative bar colors. Values outside the scale are clamped to a full or empty bar, but the displayed number is always the true value.

### Sparklines

Display a numeric column as a **sparkline** — a mini trend chart in each cell that plots the measure across a time dimension. Select the **Sparkline** button on the column's card in the **Columns** section of the **Style** tab.

A sparkline needs a time dimension to use as its horizontal axis. When you switch a column to **Sparkline** and pick its horizontal axis time dimension, that dimension is **removed from the table query** (if it was there): the table shows one row per remaining dimension, correctly aggregated, while the sparkline plots the measure's value across the time dimension. Values are always correct for any measure type, including counts of distinct values, averages, and custom measures.

Removing the dimension is a one-way change — turning the sparkline back off doesn't restore it to the query. Add it again yourself if you want it back.

<Note>
  The time dimensions on offer come from the **semantic view the query is built on**, not from the query itself — so the **Sparkline** button is disabled whenever that view has no time dimension, and equally for a query not built on a view at all, however many time dimensions the query selects.
</Note>

| Option                          | Description                                                                                                                                                                                                                                                                                 |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Horizontal axis**             | The time dimension plotted along the sparkline. Picked for you when the view offers only one; choose it here when there are several.                                                                                                                                                        |
| **Granularity**                 | The time bucket for the horizontal axis. Defaults to the dimension's granularity in the query if present, otherwise month.                                                                                                                                                                  |
| **Type**                        | **Area** (filled line, the default), **Line**, or **Bar** (mini columns).                                                                                                                                                                                                                   |
| **Line color** / **Area color** | Stroke color for line and bar; fill color for area.                                                                                                                                                                                                                                         |
| **Line width**                  | Stroke width in pixels (Line and Area types).                                                                                                                                                                                                                                               |
| **Show value**                  | The shared **Value** toggle on the column's card — shows the measure's value for the row, the same number the cell would show without a sparkline, as a headline next to it. Turn it off for a chart-only cell. Its setting carries over when you switch between inline bars and sparkline. |

A row needs at least two data points to draw a sparkline; cells with fewer fall back to the formatted value.

<Note>
  Choose a reasonable granularity for the data's time span. An overly fine granularity (e.g. by the second over several years) makes the background queries return many rows and can compromise the chart's performance.
</Note>

<Note>
  Internally, sparklines are powered by additional queries grouped by time dimension and granularity: measures sharing the same dimension and granularity are fetched together, so a chart with several sparklines runs at most one extra query per distinct dimension and granularity combination.
</Note>

### Images

A column whose values are image URLs can render them as inline thumbnails.

A dimension declared with
[`format: imageUrl`](/reference/data-modeling/dimensions#format) renders as thumbnails
straight away, with no chart configuration — the data model is enough. Any other string
column offers an **Image** button on the column's card once its values look like image
URLs, so you can render an unmodelled column of URLs without changing the data model.

| Option           | Description                                                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Image shape**  | **Square** or **Circle**.                                                                                                           |
| **Image fit**    | **Fit whole image** shows the whole image inside the box; **Fill and crop** fills the box, cropping the overflow.                   |
| **Image height** | Thumbnail height in pixels, 20 by default and up to 100, in steps of ten. The row grows to fit it and doesn't shift as images load. |

Cells that can't render an image degrade rather than break: an empty value, a total or
subtotal row, and a URL whose scheme isn't `https` or `data:image/*` all render as plain
text, with no request issued. A permitted URL that fails to load leaves a neutral
placeholder of the same size, so the row never reflows.

Copying a cell copies the URL, not the image — the same value that lands in an export.

A thumbnail is clickable only where the dimension also declares
[`links`](/docs/data-modeling/dimensions#links); the `imageUrl` format makes a value an
image source, not a destination. **Image** and **Link** are independent buttons, so a
column that declares both can render a clickable thumbnail — or you can switch either off
on its own.

<Info>
  Images at `https` URLs are fetched directly by the viewer's browser, so they must be
  publicly reachable — Cube does not proxy or cache them. `data:image/*` values are
  rendered inline and need no network access.
</Info>

## Cell menu

Left-clicking a table cell opens a context menu with any [`links` defined on the
dimension](/docs/data-modeling/dimensions#links) — drill into another dashboard
(`dashboard:`) or open an external URL (`url:`) — plus **Copy value** and, where
they apply, **Drill down** options.

**Drill down** works in two ways:

* On a **measure** cell whose data model defines drill members, it opens the
  underlying rows behind that value.
* On a **time-dimension** cell shown at a granularity, it opens a submenu of
  finer granularities. Picking one re-buckets the **same measures** to that
  granularity, scoped to the period you clicked — drilling `2024` to **Quarter**
  shows the four quarters of 2024. You can keep drilling, then close the view to
  return to the original table.

Because a week can straddle two months or quarters, **Week** is never a drill
target from a coarser granularity — a week cell drills only to **Day** and finer.

## Selecting and copying cells

You can copy a single cell or a rectangular block of cells straight out of the
table — copied values paste cleanly into a spreadsheet or text editor.

### Copy a single cell

Click the cell to select it, then press **Cmd/Ctrl+C** or choose **Copy value**
from the [cell menu](#cell-menu). Either way copies that cell's raw
(unformatted) value.

### Select and copy a range

* **Click and drag** across the cells to sweep out a rectangle, or **Shift+click**
  a second cell to extend the selection from the first.
* Press **Cmd/Ctrl+C** to copy the selected cells. When more than one cell is
  selected, the cell menu also offers **Copy values** and **Copy values with headers** — the
  latter prepends a row of column titles.

Copied cells use the raw (unformatted) values. A range is joined by tabs across
columns and newlines across rows, so it lands in a spreadsheet as a matching
grid; a single cell copies as just its value.

The same single-cell and range selection works in the **Results** table on the query
panel, not just the table visualization.

## Style options

The **Style** tab controls the visual appearance of the table. It is organized into sections — **Headers**, **Values**, **Totals**, **Columns**, **Borders**, and **Pagination** — each with its own **Reset** button in the section header that appears once you've changed anything in that section.

### Headers, Values, and Totals formatting

Each of these sections has a compact formatting toolbar that sets, for that part of the table:

* **Colors** — text and background color (the paired color chip).
* **Text format** — **bold**, **italic**, and **underline** toggles.
* **Alignment** — left, center, or right.
* **Vertical alignment** — top, middle, or bottom (**Values** only; headers and totals are always a single line).
* **Overflow** — truncate or wrap long content.

When you don't pick a color, the element uses the theme's default, which adapts to light and dark mode automatically.

Alignment is set independently in each of the three sections, and their defaults differ: headers align left, totals align right, and values follow the column's data type — numbers right, everything else left. A column's own alignment, set in the **Columns** section, overrides all three.

<Note>
  The **Values** alignment control shows left until you set it, even where numeric columns are drawn right-aligned. Choosing left there is still meaningful: it pins numeric columns to the left instead of letting them follow their data type.
</Note>

Vertical alignment is always available, but it only has a visible effect once a row is taller than one line — set **Overflow** to wrap, or turn on **Word wrap** for an individual column, and the shorter cells beside a wrapped value will sit at the top, middle, or bottom as you choose. Values are vertically centred unless you choose otherwise. A per-column setting overrides the table-wide one.

The **Values** section also holds these table-wide row toggles, shown as icon buttons:

* **Row numbers** — show or hide the row number column.
* **Hover row** — highlight the row under the pointer.
* **Row banding** — alternate the row background with a secondary color (its color chip sits next to the toggle).

The **Totals** section holds the **Column totals** and **Row totals** toggles (see [Totals](#totals)).

### Borders

The **Borders** section of the **Style** tab controls which table borders are drawn. Five borders are configurable, each with its own toggle, color, and width (1–10 pixels):

| Border                 | Description                                                           | Default |
| ---------------------- | --------------------------------------------------------------------- | ------- |
| **Horizontal borders** | Lines between value rows                                              | On      |
| **Vertical borders**   | Lines between columns, running through the header, values, and totals | Off     |
| **Header border**      | The line under the header row                                         | On      |
| **Totals border**      | The line above the totals row                                         | On      |
| **Outer border**       | The frame around the whole table                                      | Off     |

Each border is a row in the section: click the **icon button** to toggle the border on or off, and use the **color** swatch and **width** input next to it to style it. Color and width are only available while the border is on. When you don't pick a color, the border uses the theme's default border color, which adapts to light and dark mode automatically.

Next to the first border's width input is a **link** toggle that syncs all widths: while it's on, editing that width applies the same value to every border, so the whole table shares one line weight. It turns on automatically when all borders already share a width, and off as soon as they differ (for example after applying the Accounting preset).

Because every border has its own color and width, styles like a financial report — a thick line under the header, above the totals, and around the table, with thin lines between value rows — are a few clicks away. Or one: see presets below.

#### Border presets

Open the menu in the corner of the Borders section to apply a preset — a one-shot configuration of all five borders that you can tweak further afterwards:

* **Rows (default)** — horizontal row lines with header and totals separators; the standard look.
* **Full grid** — all borders on; a spreadsheet look.
* **Minimal** — dark lines under the header and above the totals, nothing else.
* **Accounting** — thin light row lines with a thick dark header separator, totals separator, and outer frame; a financial-statement look.
* **None** — no borders at all.

Use **Reset** in the section header to clear all border settings.

### Pagination

The **Pagination** section holds a single toggle, off unless you turn it on. With it off, the table renders every row in one scrollable grid; with it on, rows are split into pages of **50**, with page controls below the table. The page size is fixed and can't be changed.

Totals are pinned to the bottom of the table rather than being part of the paged rows, so a totals row stays visible on every page.

## Conditional formatting

The **Formatting** tab applies cell or row styling based on conditions you define. A **rule** picks the field to evaluate, and holds one or more **cases** — each pairing a condition with the styling to apply when it is met. Configure:

1. The field to evaluate
2. The condition of each case — an operator and, for most operators, a value to compare against (see [Conditions](#conditions))
3. The styling that case applies (background color, text color, bold/italic/underline, and an [indicator icon](#indicator-icons))

Use **Add case** to give a rule more than one condition — a three-tier indicator, for example, is three cases in one rule. When several could apply to the same cell, the first matching case in the first matching rule wins.

To make a background transparent, open the color picker and clear the hex value.

### Conditions

The operators offered depend on the evaluated field's data type. **is null** and **is not null** are available for every type and take no value.

**Text**

| Operator                       | Input   |
| ------------------------------ | ------- |
| **is**, **is not**             | A value |
| **contains**, **not contains** | A value |
| **starts with**, **ends with** | A value |
| **is null**, **is not null**   | —       |

**Numbers**

| Operator                                    | Input                      |
| ------------------------------------------- | -------------------------- |
| **is**, **is not**                          | A value                    |
| **greater than**, **greater than or equal** | A value                    |
| **less than**, **less than or equal**       | A value                    |
| **between**                                 | A lower and an upper bound |
| **is null**, **is not null**                | —                          |

**Dates**

| Operator                                                       | Input                   |
| -------------------------------------------------------------- | ----------------------- |
| **is**                                                         | A date                  |
| **before date**, **after date**                                | A date                  |
| **between**                                                    | A start and an end date |
| **in the last N days**                                         | A number of days        |
| **this week**, **this month**, **this quarter**, **this year** | —                       |
| **is null**, **is not null**                                   | —                       |

**Booleans**

| Operator                     | Input |
| ---------------------------- | ----- |
| **is true**, **is false**    | —     |
| **is null**, **is not null** | —     |

### Which cells a rule styles

Each rule's **Format** control sets how far its styling reaches:

* **Source column** — only the column the rule evaluates. The default.
* **Entire row** — every cell in a matching row.
* **Select columns** — a chosen set of columns, picked from a checklist in the same popover.

**Select columns** starts with the rule's own field checked. Clearing every column would leave a rule that styles nothing, so it falls back to **Source column** instead.

Under a column pivot, a row spans several values of the same measure (one per pivot combination), so a row-spanning rule (**Entire row** or **Select columns**) styles each measure cell by its own combination's value. Cells with no single value to test — row headers, row dimensions, and any rule whose source dimension has been pivoted into columns — are left unstyled.

### Rule presets

Picking an entry from the menu next to **Add rule** adds a ready-made rule you can then adjust. It holds three groups:

* **Indicators** — cases that mark values with an [icon](#indicator-icons) instead of recoloring them.
* **Conditional formats** — cases that tint the cell: **Above threshold**, **Below threshold**, **2-tier traffic light** (green at or above the threshold, red on the rest), and **3-tier traffic light** (green above the threshold, amber exactly at it, red on the rest).
* **Color scales** — gradient rules, described under [color scale](#color-scale).

Both indicator and conditional-format presets compare against a single threshold, which starts at `0` — adjust it to the value you're comparing against.

### Indicator icons

A conditional-formatting case can also draw an **icon** beside the cell value — an arrow up, an arrow down, a check mark, a cross, a dash, or a dot. This is how you show a goal comparison: set the condition to the threshold you care about, and the icon marks the cells that meet it.

Each case carries its own icon settings, on the row below its text formatting. Pick a shape from the **Icon** dropdown to turn the icon on; the **No icon** option turns it back off. Once a shape is chosen you can also set:

* **Icon color** — starts from the case's text color and is independent from then on, so changing the text color later leaves the icon as you set it.
* **Icon placement** — **right** of the value (the default) or **left**.

The icon is drawn next to the value, never instead of it. On a column displayed as [inline bars](#inline-bars) or [sparklines](#sparklines), the icon sits beside the bar or the trend line, and it still appears when that column's value is hidden.

Each case draws one icon, so a three-tier indicator — arrow up above target, dash within tolerance, arrow down below — takes three cases. Totals rows are never given an icon.

To add a ready-made indicator rule, open the [preset menu](#rule-presets) and pick from **Indicators**:

* **Achieved or failed** — a green check mark at or above the threshold, a red cross on every other value.
* **Above or below** — a green arrow up at or above the threshold, a red arrow down on every other value.
* **Standout or not** — a dot on the values strictly above the threshold, a muted dash on the rest.

All three are two-case, with their icons already set; add the third case yourself if you want a three-tier indicator.

### Color scale

A **color scale** (heat map) tints each cell of a numeric column with a gradient based on where its value falls in the column's range. It is a rule type in the **Formatting** tab, alongside conditional formatting — switch a rule between **Conditional** and **Scale** with the **Type** selector inside the rule.

To add one quickly, open the [preset menu](#rule-presets) and pick from **Color scales**:

* **Outstanding values** — a two-color scale that highlights the highest values.
* **Divergent values** — a three-color scale that distinguishes low, middle, and high values.
* **Traffic light gradient** — a red–yellow–green three-color scale.

A color scale requires a **numeric source column**. For non-numeric columns (strings, dates, booleans), the **Scale** type is disabled — use conditional formatting instead.

Configure the gradient with three stops, laid out top-to-bottom to mirror the column:

* **Start** (low end) — anchored at the column **Minimum** by default, or a custom **Number** or **Percentile**.
* **Center** (optional middle) — **Disabled** by default, which produces a two-color gradient. Enable it for a three-color gradient anchored at the **Midpoint**, **Average**, **Median**, or a custom **Number** / **Percentile**.
* **End** (high end) — anchored at the column **Maximum** by default, or a custom **Number** or **Percentile**.

Each stop has its own color. The anchor determines *which value* in the column the stop's color is pinned to:

* **Minimum** / **Maximum** — the lowest / highest value in the column.
* **Midpoint** — the halfway point of the range, i.e. `(minimum + maximum) / 2`. Independent of how the values are distributed.
* **Average** — the mean of all values (sensitive to outliers).
* **Median** — the middle value when sorted (robust to outliers).
* **Number** — a fixed value you enter.
* **Percentile** — a value at the given percentile (e.g. `90` = the 90th percentile).

For the computed anchors (Minimum, Maximum, Midpoint, Average, Median), the dropdown previews the resolved value from your data.

Use **Reverse color scale** to swap the Start and End colors. **Treat nulls as zero** is on by default, coloring null/blank cells as zero; turn it off to leave them uncolored.

The scale is normalized **per column** — each targeted column uses its own value range, taken from the column's data cells only. With [totals](#totals) enabled, the row totals and [pivot subtotal](#subtotals) columns are still colored by the scale of the measure they aggregate, but they don't widen its range: a total past the column's highest stop is clamped to that stop's color. Cells in the column totals row are never colored by a scale, since totals rows don't take formatting rules.

## Totals

Enable column totals and row totals from the **Totals** section of the **Style** tab. Totals rows and columns are styled separately from body cells.

### Subtotals

When the table is pivoted by two or more dimensions, you can also enable **subtotals** — a bold **Total for ‹value›** column appended after each pivot group's columns, at every nesting level. Not to be confused with [per-group subtotals](#per-group-subtotals), which add a value to each row group's header row rather than a column per pivot group. Subtotals combine freely with column and row totals, work in workbooks and on dashboards, and — like the other totals — carry over from the results table when you switch the chart type to Table. See [Subtotals](/docs/explore-analyze/workbooks/querying-data#subtotals) for details and limitations.


# Axes
Source: https://docs.cube.dev/docs/explore-analyze/charts/configuration/axes

Configure axis titles, grid lines, label formatting, dual Y-axis, and reference lines.

The **Axes** section in the Style tab controls the appearance and behavior of the X axis and Y axis (or left and right Y axes in dual-axis charts). Most axis settings are available for all Vega-based chart types (bar, line, area, scatter, heatmap).

## X axis

| Setting          | Description                                            |
| ---------------- | ------------------------------------------------------ |
| **Show axis**    | Toggle the X axis on or off                            |
| **Title**        | Custom axis label — leave blank to hide the axis title |
| **Grid lines**   | Toggle grid lines perpendicular to the X axis          |
| **Labels**       | Toggle axis tick labels                                |
| **Label angle**  | Rotate axis labels (useful for long category names)    |
| **Label format** | Number or date format applied to axis labels           |

## Y axis (left)

| Setting          | Description                                                      |
| ---------------- | ---------------------------------------------------------------- |
| **Show axis**    | Toggle the Y axis on or off                                      |
| **Title**        | Custom axis label                                                |
| **Grid lines**   | Toggle horizontal grid lines                                     |
| **Labels**       | Toggle axis tick labels                                          |
| **Label format** | Number format applied to axis labels (e.g. `$,.0f` for currency) |
| **Min / Max**    | Override the axis scale minimum and maximum values               |

## Dual Y axis (right axis)

Add a second Y axis on the right side of the chart to plot a series on a different scale. This is useful for combining measures with different units or magnitudes — for example, showing order count on the left axis and average order value on the right.

To use the right axis:

1. In the **Series configuration** for a specific series, change the **Y axis** assignment from **Left** to **Right**.
2. The right axis settings appear in the Style tab — configure its title, labels, and scale independently from the left axis.

## Reference lines

Add horizontal reference lines to mark a target, threshold, or benchmark value. Reference lines appear at a fixed Y value across the full width of the chart.

To add a reference line:

1. In the **Y axis** section of the Style tab, click **Add reference line**.
2. Set the **Value** — the Y position of the line.
3. Optionally set a **Label** that appears next to the line.
4. Configure **Color** and **Style** (solid, dashed, or dotted).

You can add multiple reference lines to the same axis. Each is configured independently.

### Reference line labels

A reference line with no label renders as a bare rule — the reader has to already know what it
means. Type text into **Label** to name it, for example `Target 18k`.

Once a label is set, two alignment controls appear next to it:

| Control        | Options              | Description                             |
| -------------- | -------------------- | --------------------------------------- |
| **Horizontal** | Start / Middle / End | Where along the line the text sits      |
| **Vertical**   | Above / Below        | Which side of the line the text sits on |

New labels start at **End** and **Above** — the right end of the line, clear of the bars. The label
takes the line's color, so it always reads as part of that line. Clearing the label removes the text
and leaves the line itself untouched.

<Tip>
  A label on a line near the top or bottom edge of the plot flips to the other side of the line
  automatically, so the text stays inside the chart area.
</Tip>

<Note>
  Reference lines are only available on the left Y axis. For right-axis reference lines, use a [custom Vega-Lite spec](/docs/explore-analyze/charts/custom).
</Note>


# Color & stacking
Source: https://docs.cube.dev/docs/explore-analyze/charts/configuration/color-and-stacking

Configure color palettes, stacking behavior, stacked segment sorting, and legend placement for charts.

The **Color** section in the Style tab controls two related things: how series are colored, and how they are stacked or grouped relative to each other. These settings apply to charts that color by a Color channel: bar, line, area, scatter, and heatmap. Chart types that color some other way, such as pie, funnel and sankey, pick their palette from a **Palette** dropdown of their own — but the [palettes](#palettes) below are the same ones they offer.

## Color faceting

Mapping a field to the **Color** channel in the Fields tab creates one series per unique value in that field, each assigned a color from the active palette. How this field is typed affects the available options:

| Data type                  | Palette options                                          |
| -------------------------- | -------------------------------------------------------- |
| **String / nominal**       | Discrete palettes (one color per category value)         |
| **Date / temporal**        | Discrete (nominal) or continuous (temporal gradient)     |
| **Numeric / quantitative** | Discrete (nominal) or continuous (quantitative gradient) |

For strings, only discrete bucketing is available. For dates and numbers, you can choose whether each value gets its own distinct color (discrete) or a gradient is applied across the range (continuous).

If a date or numeric field only offers discrete options, try casting the field to the appropriate type.

## Palettes

### Discrete palettes

For discrete data, colors from the palette are applied in palette order, matching the sort order of the query results. Change the palette order by adjusting the sort in your query.

Enable **Reverse colors** to reverse the order colors are applied.

### Continuous (gradient) palettes

For continuous data, the gradient palette maps to the range of values in your results. Select a different gradient from the palette dropdown to change the color treatment.

### Custom palettes

If none of the provided palettes fit your needs, you can build a custom palette for an individual chart:

1. Open the **Color** section of the Style tab.
2. Select the last option in the palette menu: **Custom palette**.
3. Click **Customize** to open the palette editor.
4. Add, remove, and edit individual hex colors.
5. Use **Open hex code editor** to toggle a bulk editor and paste a comma-separated list of hex values.

To reuse a custom palette across charts, copy the hex codes and paste them into the custom palette editor of another chart.

## Series color controls

When no Color channel is assigned (single measure, no color-by), each series gets an individual color picker in the **Series** section of the Style tab. Click the color swatch next to a series to change its color.

## Stacking options

The stacking behavior controls how multiple series at the same X-axis value are positioned relative to each other. The available modes:

| Option        | Behavior                                                            |
| ------------- | ------------------------------------------------------------------- |
| **Automatic** | Cube selects the best option based on chart type and data           |
| **Stack**     | Series are stacked on top of each other                             |
| **Group**     | Series are placed side-by-side (bar charts only)                    |
| **Overlay**   | Series are drawn on top of each other from the same baseline        |
| **Stack %**   | Series are stacked and normalized to 100% — tooltip shows raw value |

### Per-axis stacking

Stacking can also be set independently per Y-axis series in the Y-axis series configuration. This enables creating grouped clusters of stacked sub-groups — for example, two stacked grouplets placed side-by-side.

## Stacked segment sorting

When stacking is active, control how segments within each stack are ordered using **Sort stack by**:

| Option       | Description                                                                  |
| ------------ | ---------------------------------------------------------------------------- |
| **Label**    | Alphabetical by dimension value (default)                                    |
| **Value**    | By measure value within each individual stack (bar/column only)              |
| **Sum**      | By total sum across all stacks — useful for ordering by overall contribution |
| **Unsorted** | Preserves the original data order from the query results                     |

<Note>
  The **Value** sorting option is only available for bar and column charts. For area and line charts, use **Sum** or **Label**.
</Note>

## Legend

The legend appears when a Color channel is assigned. A chart type without a Color channel decides for itself: a pie carries a legend regardless, a funnel starts without one, and a sankey has none to configure. Where a legend is offered, it uses the same **Legend** section:

| Option       | Description                 |
| ------------ | --------------------------- |
| **Position** | Right, left, top, or bottom |
| **Hidden**   | Remove the legend entirely  |


# Data labels
Source: https://docs.cube.dev/docs/explore-analyze/charts/configuration/data-labels

Display totals directly on stacked bar charts with configurable positioning and formatting.

Data labels show the aggregate total value above each full stack on stacked bar charts. They let users read exact values without cross-referencing the Y axis.

## Enabling data labels

Open the **Fields** tab and enable the **Data Labels** toggle.

## Label settings

| Setting       | Description                                                                               |
| ------------- | ----------------------------------------------------------------------------------------- |
| **Format**    | Number format applied to the label value (e.g. `,.0f` for integers, `$,.2f` for currency) |
| **Font size** | Size of the label text                                                                    |
| **Position**  | Outside end, Inside end, Inside center, or Inside base                                    |


# Configure charts
Source: https://docs.cube.dev/docs/explore-analyze/charts/configuration/index

Reference for chart configuration options — series mapping, color, axes, tooltips, and data labels.

The chart configuration panel has two tabs — **Fields** and **Style** — available for every chart type. Configuration options are divided into per-channel field assignments and per-chart style controls.

| Page                                                                                    | What it covers                                                               |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [Series mapping](/docs/explore-analyze/charts/configuration/series-mapping)             | Assigning query columns to chart channels (X, Y, color, size, tooltip)       |
| [Series configuration](/docs/explore-analyze/charts/configuration/series-configuration) | Per-series mark type, color, and individual display options                  |
| [Color & stacking](/docs/explore-analyze/charts/configuration/color-and-stacking)       | Color palettes, stacking mode, stacked segment sorting, and legend placement |
| [Small multiples](/docs/explore-analyze/charts/configuration/small-multiples)           | Splitting a chart into a grid of panels, one per value of a dimension        |
| [Axes](/docs/explore-analyze/charts/configuration/axes)                                 | Axis titles, grid lines, label formatting, dual Y-axis, and reference lines  |
| [Tooltips](/docs/explore-analyze/charts/configuration/tooltips)                         | Which fields appear on hover and how they are formatted                      |
| [Data labels](/docs/explore-analyze/charts/configuration/data-labels)                   | Labels shown on chart marks — positioning, formatting, and stacked totals    |


# Series configuration
Source: https://docs.cube.dev/docs/explore-analyze/charts/configuration/series-configuration

Configure individual series — mark type, color, and display options — independently from the global chart settings.

Series configuration lets you override chart settings on a per-series basis. Access it from the **Fields** tab by expanding an individual series in the Y-axis section.

## Mark type override

Each series can use a different mark type, independent of the global chart mark. This enables composite charts — for example, plotting one measure as a bar and another as a line on the same chart.

Available mark types per series:

* **Bar**
* **Line**
* **Area**
* **Scatter** (point)

To create a bar + line chart:

1. Add two measures to the Y axis.
2. Expand the second series in the Fields tab.
3. Set its mark type to **Line**.
4. Optionally assign it to the **Right Y axis** in the same panel (see [Axes](/docs/explore-analyze/charts/configuration/axes)).

## Series color

When no **Color** channel is assigned (single-color charts with no color-by dimension), each series has an individual color picker. Click the color swatch to open the picker and set a custom color for that series.

This setting has no effect when a Color channel is active — in that case, colors are managed by the palette in [Color & stacking](/docs/explore-analyze/charts/configuration/color-and-stacking).

## Y axis assignment

For charts with a dual Y axis, assign each series to either the **Left** or **Right** Y axis. This controls which axis scale the series uses.

See [Axes](/docs/explore-analyze/charts/configuration/axes) for configuring the right axis title, labels, and scale.

## Data labels per series

Enable data labels for an individual series without enabling them globally. Configure label position, font, and format independently for each series.

See [Data labels](/docs/explore-analyze/charts/configuration/data-labels) for the full configuration reference.

## Stacking override

On charts with multiple Y-axis series, you can set stacking behavior per-axis rather than globally. This lets you create grouped clusters where each cluster is internally stacked — expand the Y-axis settings for a specific series to access this option.


# Series mapping
Source: https://docs.cube.dev/docs/explore-analyze/charts/configuration/series-mapping

Assign query columns to chart channels — X axis, Y axis, color, size, and tooltips.

Series mapping controls which query columns are assigned to which chart channels. This is done in the **Fields** tab of the chart configuration panel.

## Chart channels

| Channel                          | Description                                                                                                                                      | Applicable chart types                     |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| **X**                            | The horizontal axis dimension or time field                                                                                                      | Bar, line, area, scatter, heatmap, boxplot |
| **Y**                            | The vertical axis measure                                                                                                                        | Bar, line, area, scatter, boxplot          |
| **Color**                        | Creates one series per unique value; controls stacking behavior                                                                                  | All Vega-based types                       |
| **Size**                         | Scales point radius by a numeric measure                                                                                                         | Scatter, map                               |
| **Split by**                     | Repeats the chart once per unique value, as a grid of panels — see [small multiples](/docs/explore-analyze/charts/configuration/small-multiples) | Bar, line, area, scatter                   |
| **Tooltip**                      | Fields shown on hover                                                                                                                            | All types                                  |
| **Theta** (pie)                  | The measure that determines slice size                                                                                                           | Pie                                        |
| **Source** / **Target** (sankey) | The dimensions holding the node each flow leaves and enters                                                                                      | Sankey                                     |
| **Value** (sankey)               | The measure that determines ribbon thickness                                                                                                     | Sankey                                     |

## Assigning fields

Drag a field from the **Available fields** list at the bottom of the Fields tab into the target channel slot. You can also drag an already-assigned field between channels.

Fields can appear in more than one channel simultaneously — drag from **Available fields** to add a field to a second channel without removing it from the first. For example, you can assign the same dimension to both the X axis and the tooltip.

## Multiple measures on Y

To plot multiple measures as separate series, drag additional measures into the **Y** channel. Each measure renders as its own series, with independent color and style settings in [series configuration](/docs/explore-analyze/charts/configuration/series-configuration).

## Removing a field

Drag a field out of its channel slot back to **Available fields**, or click the **×** on the field token to remove it.


# Small multiples
Source: https://docs.cube.dev/docs/explore-analyze/charts/configuration/small-multiples

Split a chart into a grid of panels, one per value of a dimension, for side-by-side comparison across segments.

**Small multiples** repeat one chart once per value of a dimension, laying the copies out in a grid. Instead of a single plot with a dozen overlapping series, you get a dozen small panels that can be read and compared at a glance.

It is a setting on an existing chart, not a chart type of its own: a bar, line, area, or scatter chart stays that chart and simply gets drawn per panel.

## Splitting a chart into panels

The **Small multiples** section appears in the Fields tab for bar, line, area, and scatter charts.

Pick a dimension in **Split by** and the chart is replaced by one panel per value of that dimension. Clearing the picker returns the chart to a single plot.

Only dimensions are offered. Splitting by a measure is not supported — a measure has no discrete values to make panels from.

## Options

These options appear once a **Split by** dimension is chosen.

| Option             | What it does                                                                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Grid**           | Columns × rows, up to 5 × 5. Both are preselected from the number of distinct values in the split dimension, so a four-value dimension opens as a 2 × 2 grid. |
| **Axis scales**    | Whether every panel is drawn against the same scale (**Shared**) or each scales to its own data (**Independent**).                                            |
| **Sort panels by** | Orders the panels by the dimension's own values (**Value**) or by a measure (**Measure**).                                                                    |
| **Sort order**     | **Ascending** or **Descending**.                                                                                                                              |

### Shared vs. independent axis scales

Every panel is labeled with its own X and Y axes either way. What the setting changes is the scale those axes are drawn against.

**Shared** is the default, and it is usually what makes small multiples worth using: every panel is drawn against the same scale, so the panels are directly comparable and a taller bar really does mean a bigger number.

Switch to **Independent** when the question is about the *shape* of each series rather than its magnitude — "what does each warehouse's weekly pattern look like", where one high-volume warehouse would otherwise flatten every other panel to a straight line.

### How many panels are drawn

The grid bounds the render: a chart split into 3 × 2 draws at most six panels, so a high-cardinality dimension can never produce hundreds of unreadable ones. The largest grid is 5 × 5, or twenty-five panels.

When a dimension has more values than the grid has tiles, the chart draws the first ones in the current sort order. The underlying query is unaffected, so no data is lost — a bigger grid simply shows more of it.

Sorting interacts with this: with **Sort panels by** set to a measure and a descending order, the grid keeps the top panels by that measure, which is usually more useful than the first ones alphabetically.

## Interaction with other settings

Chart settings apply to all panels at once — axis titles and formats, colors and palettes, data labels, reference lines, and tooltips are configured once and take effect in every panel. A reference line is drawn once inside each panel, against that panel's own scale when the scales are independent.

Data labels and reference lines have to be switched on *after* the split, not before — see the limitations below.

A legend is shared across the grid rather than repeated per panel. Clicking a legend entry hides that series in every panel.

## Limitations

* **One split dimension.** One dimension fills the grid, panel by panel. Splitting by two dimensions at once — one down the rows and another across the columns — is not supported.
* **Cartesian charts only.** Bar, line, area, and scatter. Pie, sankey, table, KPI, heatmap, boxplot, map, and HTML charts cannot be split.
* **Panel labels are not configurable.** Each panel is labeled with its dimension value; the font, size, and color are fixed.
* **The split is enabled on a single-view chart.** A chart that already carries data labels, a reference line, or a second Y axis series cannot be split — turn the split on first. The order is the only constraint: once a chart is split, data labels and reference lines can be added freely and are drawn in every panel.


# Tooltips
Source: https://docs.cube.dev/docs/explore-analyze/charts/configuration/tooltips

Control which fields appear when a user hovers over a chart mark.

Tooltips appear when a user hovers over a data point in a chart. By default, Cube automatically populates the tooltip with all fields mapped to chart channels. You can customize which fields are shown and in what order.

## Default behavior

When a chart is first created, all fields assigned to the chart (X, Y, color, size) are included in the tooltip automatically. The tooltip is enabled by default on all Vega-based chart types (bar, line, area, scatter, heatmap, boxplot), on map charts, and on sankey charts.

[Sankey](/docs/explore-analyze/charts/chart-types/sankey) is the exception to the first rule: it seeds the tooltip with every column *except* the source, target and value it already draws.

## Configuring tooltip fields

Open the **Fields** tab of the chart configuration panel. The **Tooltip** section shows the list of fields currently included in the tooltip.

| Action             | How                                                          |
| ------------------ | ------------------------------------------------------------ |
| **Add a field**    | Drag a field from **Available fields** into the Tooltip slot |
| **Remove a field** | Click the **×** on a field token in the Tooltip list         |
| **Reorder fields** | Drag field tokens within the Tooltip list                    |

## Disabling tooltips

To turn off tooltips entirely, remove all fields from the Tooltip slot. When the Tooltip slot is empty, no tooltip is shown on hover.

## Tooltip behavior on stacked charts

On stacked bar charts, the tooltip is scoped to the individual stack segment under the cursor — it shows the value for that specific series at that X position, not the total stack value. To display the stack total, use [data labels](/docs/explore-analyze/charts/configuration/data-labels) with the **Simple totals** option.


# Custom visualizations
Source: https://docs.cube.dev/docs/explore-analyze/charts/custom

Edit raw Vega-Lite specs to build visualizations beyond what the chart builder supports.

All standard Cube chart types are built on [Vega-Lite v5](https://vega.github.io/vega-lite/). The visual builder covers the most common patterns, but for anything beyond that — multiple layers with transforms, complex dual-axis rules, custom aggregations, or annotations — you can edit the raw spec directly.

For fully freeform layouts using HTML and CSS, see [HTML charts](/docs/explore-analyze/charts/chart-types/html).

## When the spec editor appears

The chart panel automatically falls back to the **spec editor** when the current Vega-Lite spec has features the visual builder cannot represent:

* Top-level `transform` clauses
* More than two non-text layers
* Certain dual-axis + rule mark combinations

In these cases, the visual builder is replaced by a code editor showing the full Vega-Lite JSON.

## Opening the spec editor manually

Click the **Edit spec** button in the chart panel (visible on Vega-based charts) to open the spec editor. This lets you inspect and modify the generated spec even when the visual builder is active.

Changes take effect immediately in the preview.

## Spec structure

Cube generates standard Vega-Lite v5 specs. The key fields:

```json theme={"dark"}
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "mark": { "type": "bar" },
  "encoding": {
    "x": { "field": "order_items.status", "type": "nominal" },
    "y": { "field": "order_items.count", "type": "quantitative" },
    "color": { "field": "order_items.status", "type": "nominal" }
  }
}
```

Any valid Vega-Lite v5 spec is supported. Refer to the [Vega-Lite documentation](https://vega.github.io/vega-lite/docs/) for the full spec reference.

## AI-generated specs

The AI agent can generate a full Vega-Lite spec from a natural language description. After running a query, prompt the agent — for example: *"Show this as a heatmap of order count by status and month"* — and the agent will write the complete spec.

AI-generated specs produce valid Vega-Lite v5 JSON and can be further refined in the spec editor.


# Charts
Source: https://docs.cube.dev/docs/explore-analyze/charts/index

Visualize query results as charts, tables, KPIs, and maps directly inside Cube workbooks.

Every tab in a Cube workbook has a chart panel. Once your query returns results, switch to the chart panel to pick a visualization type and configure how the data is displayed — from a simple bar chart to a composable KPI tile or a fully custom Vega-Lite spec.

## Chart types

Cube has built-in support for bar, line, area, pie, scatter, heatmap, KPI, map, boxplot, and more. See the [chart types overview](/docs/explore-analyze/charts/chart-types) for a full list and guidance on which type fits which data shape.

### Selecting a chart type

Chart type icons at the top of the chart panel let you quickly switch between common layouts — grouped vs. stacked bars, line vs. area, table vs. chart view — without opening the full configuration panel.

When you run a query on a new tab, Cube shows the chart type picker rather than picking for you. It outlines the type that best fits your query and labels it **Recommended** — see [Recommended chart type](/docs/explore-analyze/charts/chart-types#recommended-chart-type) — but choosing one is always your action. Any manual configuration you apply is preserved when you change query fields.

### Resetting chart settings

Sections of the configuration panel — fields, series, pivot, column widths — each carry their own **Reset** control, which clears that section back to its defaults. Resetting does not change the chart type you picked.

## Generate charts with AI

Describe the visualization you want in plain language — for example, *"show this as a stacked bar grouped by status"* — and the AI agent will build and configure it. You can also let the agent auto-suggest the best chart for your query results. This is a separate mechanism from the **Recommended** outline in the chart type picker: the agent writes a Vega-Lite spec and applies it, while the recommendation only marks a built-in type for you to pick.

Charts generated by the AI are written as [Vega-Lite v5](https://vega.github.io/vega-lite/) specs and can be further edited in the [custom visualization](/docs/explore-analyze/charts/custom) spec editor.

## Configure charts

Adjust the appearance of any chart through the configuration panel:

* **[Color and stacking](/docs/explore-analyze/charts/configuration/color-and-stacking)** — Color palettes, series coloring, and stacking behavior
* **[Series configuration](/docs/explore-analyze/charts/configuration/series-configuration)** — Per-series mark type, color, and display options
* **[Series mapping](/docs/explore-analyze/charts/configuration/series-mapping)** — Assign query fields to chart channels (X, Y, color, size)
* **[Axes](/docs/explore-analyze/charts/configuration/axes)** — Axis titles, grid lines, scale, and reference lines
* **[Tooltips](/docs/explore-analyze/charts/configuration/tooltips)** — Fields shown on hover
* **[Data labels](/docs/explore-analyze/charts/configuration/data-labels)** — Values displayed directly on chart marks

## Custom visualizations

When the built-in chart types don't cover your use case, write a raw [Vega-Lite spec](/docs/explore-analyze/charts/custom) or use an HTML template with Handlebars. Both options give you complete control over the rendered output.


# Dashboard Agent
Source: https://docs.cube.dev/docs/explore-analyze/dashboards/dashboard-agent

Ask questions about a dashboard and its charts — and change its filters and time granularity — using a conversational AI assistant docked alongside the dashboard.

The Dashboard Agent is a conversational assistant docked as a panel on a
[published or embedded dashboard][ref-dashboards]. Ask it questions in plain
language about what's on the dashboard — and it answers using **live queries
against your semantic model**, not just the numbers already rendered on screen.

Because it queries the model directly, the agent can go beyond what a chart
shows. It can drill into a single chart, re-aggregate a metric, break a number
down by a dimension, pull a longer time range than the chart displays, and
summarize trends across the dashboard.

It can also **apply filters and change the time granularity** on the dashboard
you're viewing — just ask in plain language (for example, *"filter to last 30
days"* or *"group by month"*). These changes affect only your own session and
are never saved to the dashboard — see
[Changing filters and time granularity](#changing-filters-and-time-granularity).

<Frame>
  <img alt="Dashboard Agent panel docked alongside a published dashboard" />
</Frame>

<Note>
  There are **two different agent surfaces** with different capabilities:

  * **Dashboard Agent** (this page) — for viewers of a published or embedded
    dashboard: question-and-answer about what's on screen, plus changing your
    own filters and time granularity.
  * **[Workbook Agent][ref-workbook-agent]** — full authoring inside a
    [workbook][ref-workbooks]: creating reports, building and editing
    dashboards, and running analysis.

  The published Dashboard Agent can adjust **your own view** — filters and time
  granularity, for your session only — but intentionally cannot author or change
  the **saved** dashboard.
</Note>

## Opening the agent

Open a published dashboard and toggle the agent panel from the dashboard header
to start a conversation. Use **New Chat** to start a fresh thread.

The panel is docked to the right side of the dashboard and is **resizable** —
drag its edge to give the conversation more or less room. On narrow screens it
switches to a **compact mode** so it stays usable next to the dashboard.

## Focusing on a specific chart

<Note>
  Chart-level follow-ups and attached-chart chips are **rolling out**. If you
  don't see the **Ask a follow up question** action on a chart's menu yet, it
  hasn't reached your deployment.
</Note>

To ask about one chart in particular, open that chart tile's menu (`⋮`) and
choose **Ask a follow up question**. This opens the agent with that chart
**attached as context**, so your question is scoped to that chart's data.

Attached charts appear as **removable chips** in the chat input. To drop a
chart's focus, remove its chip. You can attach more than one chart to ask about
them together.

When a chart is attached, the agent receives a read-only snapshot of it — the
underlying SQL, the data, and the chart spec — along with the dashboard's
**current filter and time-granularity state**. It uses this as context for
answering and never edits the chart's definition. You can still ask it to change
the dashboard's filters or time granularity — see
[Changing filters and time granularity](#changing-filters-and-time-granularity).

## Changing filters and time granularity

Ask the agent, in plain language, to filter the dashboard or change a time
granularity, and it applies the change to the controls in front of you:

* *"Filter this dashboard to orders with status completed."*
* *"Show only the Outerwear category."*
* *"Filter to the last 30 days."*
* *"Group by month."*
* *"Reset the filters."*

How it works and what to expect:

* **Only controls that exist on the dashboard can be changed.** The agent can
  change a filter or time granularity only when the dashboard has a matching
  [filter or time-granularity control widget][ref-controls] for that dimension.
  If there's no control for what you asked about, the agent tells you so instead
  of changing anything. A control whose [visibility][ref-control-visibility] is
  **Disabled** also can't be changed.
* **Time granularity stays within the control's allowed granularities.** If a
  time-granularity control restricts which granularities viewers can pick, the
  agent only chooses from that set.
* **Changes apply to your session only.** They're applied the same way as
  changing a control by hand: reflected in the dashboard's URL — so you can
  share or bookmark the filtered view — but **not** saved to the dashboard. They
  don't affect what other viewers see, and the author's saved defaults are left
  untouched.

This works the same way on both published dashboards and
[embedded][ref-embedding] dashboards.

## Attachments

You can attach uploaded files to the conversation, and the agent can read their
contents — text, PDF, ZIP, and image files are supported.

<Note>
  Pasting an image directly from your clipboard into the chat may also be
  supported. Confirm this in your deployment before relying on it.
</Note>

## What the Dashboard Agent can and can't do

The published Dashboard Agent can answer questions and adjust your own view, but
it never changes the **saved** dashboard.

**It can:**

* Answer questions about what's on the dashboard from the dashboard's own data
* Run **read-only queries** against the semantic model to go deeper — drill
  down, break a metric down by a dimension, or pull a longer time range than a
  chart shows
* Apply filters and change the time granularity on the dashboard you're
  viewing, for dimensions that have a matching
  [control widget][ref-controls] (your session only — see
  [Changing filters and time granularity](#changing-filters-and-time-granularity))
* Explain how a metric or dimension is defined
* Look up the values available for a dimension
* Read the contents of [attachments](#attachments) you add to the chat

**It can't:**

* Save its filter or time-granularity changes to the dashboard — they apply to
  your session only and never change what other viewers see
* Edit the dashboard, or add/remove widgets
* Create reports or workbooks
* Change the data model

If you need any of those, use the [Workbook Agent][ref-workbook-agent] instead.

## Limitations

* **Filter and time-granularity changes need a matching control.** The agent can
  change a filter or time granularity only for dimensions that have a
  corresponding [control widget][ref-controls] on the dashboard, and the change
  applies to your session only — it is never saved to the dashboard. If you ask
  it to change something with no control on the dashboard, it explains the
  current state instead of applying a change.
* **Field switchers aren't driven by the agent.** The agent can read and change
  [filters and time granularities][ref-controls]; a
  [field switcher][ref-field-switcher] is not among the controls it operates, so
  ask it about the data instead and change the field yourself in the control.
* **No authoring on published dashboards.** The published Dashboard Agent
  cannot create reports or build dashboards, edit the saved dashboard, or change
  the data model. Those live in the [Workbook Agent][ref-workbook-agent].
* **Report search covers published reports only.** When the agent searches for
  existing reports, it sees published reports.

[ref-dashboards]: /docs/explore-analyze/dashboards

[ref-workbooks]: /docs/explore-analyze/workbooks

[ref-workbook-agent]: /docs/explore-analyze/workbooks/workbook-agent

[ref-controls]: /docs/explore-analyze/dashboards/widgets/controls

[ref-field-switcher]: /docs/explore-analyze/dashboards/widgets/controls#field-switcher

[ref-control-visibility]: /docs/explore-analyze/dashboards/widgets/controls#visibility

[ref-embedding]: /embedding/iframe/dashboards


# Dashboards as code
Source: https://docs.cube.dev/docs/explore-analyze/dashboards/dashboards-as-code

Manage workbooks, dashboards, and reports as code with idempotent REST endpoints keyed by portable identifiers, so a CI/CD pipeline can apply the same definitions across deployments.

**Dashboards as code** lets you manage the reporting assets in a deployment —
[workbooks][ref-workbooks], their [dashboards][ref-dashboards], and the
[reports][ref-reports] the dashboard widgets render — from source control instead
of only through the UI. You keep each asset's definition in Git and apply it to a
deployment with the [Cube Cloud REST API][ref-api], the same way you might manage
Superset assets with `preset-cli` or infrastructure with Terraform.

Two **idempotent upsert** endpoints make this possible. Instead of tracking the
per-deployment numeric id that a `POST` returns, you address each asset by a
**portable identifier you choose** and re-apply its definition as often as you
like:

| Endpoint                                                                               | Keyed by                         | Upserts                              |
| -------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------ |
| [`PUT /deployments/{deploymentId}/workbooks/by-slug/{slug}`][ref-upsert-workbook]      | a deployment-scoped **slug**     | a workbook (and its dashboard draft) |
| [`PUT /deployments/{deploymentId}/reports/by-public-id/{publicId}`][ref-upsert-report] | an account-unique **`publicId`** | a report                             |

Because the identifier is stable and lives in your repository, applying the same
definition twice is a no-op, and applying it to a second deployment (staging →
production) reproduces the same assets there.

<Note>
  This page covers the REST primitives available today. They are the building
  blocks for an as-code workflow you assemble in your own pipeline — Cube does not
  yet ship a single bundle export/apply command that wraps them.
</Note>

## How the pieces fit

Three assets are involved, each with its own identity:

* A **report** is a saved query plus its visualization. Its portable identity is
  a **`publicId`**: a 12-character alphanumeric (`[0-9A-Za-z]`) id that is unique
  across your account. You mint it when you author the report and keep it fixed
  for the report's lifetime.
* A **workbook** is the container that holds a dashboard. Its portable identity
  is a **slug**: a human-readable, deployment-scoped id (the same slug a data
  model targets with `links: [{ dashboard: <slug> }]` for drill-in).
* A **dashboard** is the layout — which widgets sit where. It is stored on its
  workbook as `meta.dashboardDraft` and is made visible by **publishing** the
  workbook. Each chart widget references a report.

The identifiers you control (`publicId`, `slug`) are what make a definition
portable. The numeric ids that `POST` responses return are per-deployment and are
resolved at apply time — you never store them in Git.

## Authenticating

These are public REST endpoints. Authenticate with a deployment API key exactly
as for the rest of the [REST API][ref-api] — see [Authentication][ref-auth] for
how to create a key and pass it. The examples below assume:

```bash theme={"dark"}
export CUBE_API_URL="https://<your-cube-cloud-host>"
export CUBE_API_TOKEN="<your-api-key>"
export DEPLOYMENT_ID="<your-deployment-id>"
```

## The apply flow

An as-code pipeline applies a dashboard bottom-up: reports first, then the
workbook that lays them out, then publish.

### 1. Author once, then export

The report and dashboard-draft definitions are large and are not meant to be
hand-written. Build the reports and dashboard once in the UI, then read them back
over the API and commit the results:

* [`GET /deployments/{deploymentId}/reports/{reportId}`][ref-get-report] returns a
  report's definition.
* [`GET /deployments/{deploymentId}/workbooks/{workbookId}`][ref-get-workbook]
  returns the workbook, including its `dashboardDraft`.

Assign each report a `publicId` and the workbook a `slug` of your choosing, store
those alongside the exported definitions in your repository, and treat that as the
source of truth.

### 2. Upsert each report

For every report, [upsert it by `publicId`][ref-upsert-report]. If a report with
that `publicId` already exists in the deployment it is updated with the fields you
send (same semantics as [`PUT /reports/{reportId}`][ref-update-report]);
otherwise it is created with that `publicId`.

```bash theme={"dark"}
curl -X PUT \
  "$CUBE_API_URL/api/v1/deployments/$DEPLOYMENT_ID/reports/by-public-id/revqZ1x8Kp0a" \
  -H "Authorization: $CUBE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @report-revenue-by-month.json
```

The path `publicId` is the report's identity; the request body is the report
definition you exported (its query in `sqlQuery` / `jsonQuery`, pivot in
`pivotItems`, and visualization config in `meta`). Keep track of the numeric
`id` each response returns — the dashboard draft references reports by that
per-deployment id.

### 3. Upsert the workbook and its dashboard

[Upsert the workbook by `slug`][ref-upsert-workbook], carrying the dashboard
layout in `meta.dashboardDraft`. Only the fields you send are changed, and `meta`
is **merged** into the existing metadata rather than replacing it. The
`dashboardDraft` is validated the same way the builder validates it.

```bash theme={"dark"}
curl -X PUT \
  "$CUBE_API_URL/api/v1/deployments/$DEPLOYMENT_ID/workbooks/by-slug/revenue-overview" \
  -H "Authorization: $CUBE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Revenue Overview",
    "meta": { "dashboardDraft": { "...": "the exported dashboard config" } }
  }'
```

Because each chart widget inside `dashboardDraft` points at a report by its
per-deployment numeric id, rewrite those references to the ids returned in
step 2 before applying the workbook to a **new** deployment. Re-applying to
the same deployment needs no rewriting — the ids are stable there.

### 4. Publish

Upserting the workbook writes the dashboard **draft**. Publish it to make it
visible to viewers with [`POST /workbooks/{workbookId}/publish`][ref-publish],
using the workbook id returned in step 3. Publishing is itself idempotent per
workbook, so it is safe to run on every apply.

## Idempotency and conflicts

Re-applying an unchanged definition is a no-op — that is the property that makes
these endpoints safe to run on every pipeline execution. When something does go
wrong, both upserts fail with a `409` rather than guessing, and the report upsert
distinguishes three cases by a `code` field in the response body so your pipeline
can react correctly:

| Endpoint          | `code`                  | Meaning                                                                                                                                                      | What to do                                                                                      |
| ----------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| workbook & report | `upsert_branch_changed` | A concurrent writer created or deleted the asset between the access check and the write, so the request would have applied under the wrong permission check. | **Retry.** Transient; happens only under concurrent applies of the same key.                    |
| report            | *(none)*                | The `publicId` already belongs to a report in a **different** deployment. `publicId` is unique across the account.                                           | **Permanent.** Use a different `publicId`.                                                      |
| report            | `ambiguous_legacy_id`   | The id matches more than one legacy report (see below), so it can't identify one.                                                                            | **Permanent.** Give the intended report a `publicId` of your own (see below), then key on that. |

The upserts serialize per key (per slug, per `publicId`), so two pipeline runs
applying the same bundle at once can't create a duplicate — the loser gets a
retryable `upsert_branch_changed` instead.

## Choosing and adopting `publicId`s

A report's `publicId` is **write-once**: you can assign one to a report that
doesn't have one yet, but a report's existing `publicId` can never be changed,
because clients may already have stored it. You can supply a `publicId`:

* **On create** — pass it in the body to [`POST /reports`][ref-create-report], or
  just call the [upsert endpoint][ref-upsert-report] with the id in the path.
* **On an existing report** — assign one with
  [`PUT /reports/{reportId}`][ref-update-report]. This is how you bring a report
  that was authored in the UI under as-code management.

Pick any distinct 12-character `[0-9A-Za-z]` id. The auto-generated placeholder
ids shown for reports that don't have a stable id yet are a reserved, non-unique
shape and are rejected with `400` — you must choose your own.

### Reports created before stable ids

Reports created before `publicId` existed don't store one; the API **synthesizes**
one from the report's internal id so every report has an id on the wire. These
synthesized ids are **not unique** — several reports can share one. The upsert
endpoint resolves a synthesized id only when it is unambiguous, adopting it as the
report's real `publicId` at that point; if it matches more than one report it
returns the `ambiguous_legacy_id` conflict above. For anything you manage as code,
don't rely on a synthesized id — assign a `publicId` you chose and key on that.

## Reference

* [Create or update a workbook by slug][ref-upsert-workbook]
* [Create or update a report by publicId][ref-upsert-report]
* [Create a report][ref-create-report] · [Update a report][ref-update-report]
* [Publish dashboard][ref-publish]
* [Building dashboards in the UI][ref-dashboards]

[ref-dashboards]: /docs/explore-analyze/dashboards

[ref-workbooks]: /docs/explore-analyze/workbooks

[ref-reports]: /docs/explore-analyze/workbooks/querying-data

[ref-api]: /api-reference/introduction

[ref-auth]: /api-reference/authentication

[ref-upsert-workbook]: /api-reference/workbooks/create-or-update-a-workbook-by-slug

[ref-upsert-report]: /api-reference/reports/create-or-update-a-report-by-publicid

[ref-create-report]: /api-reference/reports/create-a-report

[ref-update-report]: /api-reference/reports/update-a-report

[ref-get-report]: /api-reference/reports/get-report

[ref-get-workbook]: /api-reference/workbooks/get-workbook

[ref-publish]: /api-reference/workbooks/publish-dashboard


# Dashboards
Source: https://docs.cube.dev/docs/explore-analyze/dashboards/index

Curate and share polished views of your workbook reports with stakeholders as interactive dashboards.

Dashboards let you select and organize reports from your workbooks into polished, shareable views for your team and stakeholders. Transform your exploratory analysis into production-ready deliverables by choosing which insights to highlight and present.

## Use cases

Dashboards enable you to:

* **Monitor key metrics** – Display critical business indicators that refresh with live data
* **Distribute analysis** – Package your findings into reports for regular distribution
* **Build data tools** – Develop specialized applications powered by your semantic layer
* **Present insights** – Showcase important discoveries in a polished, accessible format

## How it works

In the dashboard builder inside your [workbook][ref-workbooks], select the reports you want to include and arrange them on the canvas alongside other [widgets][ref-widgets] to tell your data story, then publish the dashboard. This gives stakeholders direct access to the insights that matter most, without the complexity of the underlying analysis.

Prefer to manage dashboards from source control? You can also apply dashboards,
workbooks, and reports to a deployment through the REST API and keep their
definitions in Git — see [Dashboards as code](/docs/explore-analyze/dashboards/dashboards-as-code).

## Data freshness

Each widget shows a [freshness](/docs/explore-analyze/workbooks/querying-data#result-freshness-and-provenance) leaf indicating how recently its data was refreshed. The dashboard's own leaf reflects its least-recently-refreshed widget, so you can see at a glance whether everything on the dashboard is up to date.

## Linking between dashboards

Dashboards can link to one another. When a table widget shows a dimension that
has [links][ref-dimension-links] defined in the data model, left-clicking a cell
opens a menu with those links: a **drill-in** link (`dashboard:`) navigates to
another dashboard in the same deployment, filtered by the values in the clicked
row, and an **external** link (`url:`) opens a URL. This is how you build
overview → detail flows — click a row in a summary dashboard to jump straight to
a focused dashboard scoped to that row.

Links are declared once on the dimension in the data model (not configured
per-dashboard), so every table that shows that dimension — in dashboards,
workbooks, embedded dashboards, and Explore — offers the same links. A drill-in
link targets a dashboard by its [slug](#dashboard-slug); see [Dimensions →
Links][ref-dimension-links] to define them.

## Dashboard slug

A dashboard can have a **slug** — a short, stable, human-readable identifier
(e.g. `orders-detail`) used to link to it from the data model. Data-model
[dimension links][ref-dimension-links] with a `dashboard:` value reference a
dashboard by its slug to drill into it.

To set it, open the dashboard in the builder, open the **options sidebar**, and
fill the **Slug** field. Slugs are **unique per deployment** and are resolved
within the current deployment, so the same model works across environments. The
dashboard's own URL is unaffected (it stays `publicId`-based).

<Note>
  **There is no required order between the model and the dashboard.** You can
  reference a slug from a `dashboard:` link in the data model before any dashboard
  uses it, or set a dashboard's slug before any link references it — neither
  breaks. A link whose slug doesn't (yet) resolve is simply skipped in the cell
  menu, and starts working as soon as a dashboard in the deployment claims that
  slug. (If you later clear or change a slug that links still reference, the
  options sidebar warns you to update those links.)
</Note>

## Download as PNG, PDF, or CSV

Open a published dashboard, click the **More actions** (`⋯`) button in the
header, and choose **Download as PNG** or **Download as PDF**. The file is
named after the dashboard's title.

To export a **single chart** instead of the whole dashboard, hover the chart
widget, open its **⋮** menu, and choose **Download as PNG** or **Download as
PDF** — the same menu also offers **Download as CSV** for the chart's
underlying data. The image captures just that chart, named after the chart's
title.

PNG and PDF downloads are server-rendered snapshots — Cube re-opens the
dashboard (or, for a single chart, that chart on its own), waits for rendering
to finish, and captures the result. This can take up to a couple of minutes
for large dashboards. The control selections you currently have applied in your
browser are carried into a download you start yourself — filters, time
granularity switchers and [field switchers][ref-controls] alike. A scheduled
notification has no browser session, so its attachment renders the dashboard's
own defaults, unless that notification carries selections of its own. (CSV is
generated from the data already loaded in the chart and downloads immediately.)

Downloading the whole dashboard requires **Manage** permission on the workbook
that owns it; exporting a single chart requires the **Download data**
permission. Both are hidden entirely when an admin turns off the account-wide
[data download controls][ref-data-download-controls]. The same screenshot
mechanism powers PNG/PDF attachments on [notifications][ref-notifications] sent
after a [scheduled refresh][ref-scheduled-refreshes].

[ref-workbooks]: /docs/explore-analyze/workbooks

[ref-widgets]: /docs/explore-analyze/dashboards/widgets

[ref-controls]: /docs/explore-analyze/dashboards/widgets/controls

[ref-dimension-links]: /docs/data-modeling/dimensions#links

[ref-notifications]: /docs/explore-analyze/notifications

[ref-scheduled-refreshes]: /docs/explore-analyze/scheduled-refreshes

[ref-data-download-controls]: /admin/users-and-permissions/roles-and-permissions#restricting-data-downloads


# Styling
Source: https://docs.cube.dev/docs/explore-analyze/dashboards/styling

Customize the appearance of a dashboard from the Styling panel in the Dashboard Builder.

You can customize the appearance of any dashboard — background, padding, widget cards, borders, titles, and fonts — from the **Styling** panel in the Dashboard Builder.

Styling is **per-dashboard**: settings are saved to the dashboard's configuration and apply equally to the dashboard in Cube and to its [embedded view](/embedding/iframe/dashboards) (both [private](/embedding/iframe/auth/private) and [signed](/embedding/iframe/auth/signed) embedding).

## Open the Styling panel

1. Open your dashboard
2. Click **Dashboard Builder** in the top bar
3. Click the gear icon to open the **Styling** panel

Click **Apply** to preview your changes. Click **Reset** to revert to the defaults. Publish the dashboard for the styling to take effect in embedded views.

## Options

All values accept standard CSS — colors as hex (`#1a1a2e`), `rgb()`, or named colors; lengths as CSS units (e.g., `16px`).

### Background

Settings that apply to the dashboard canvas as a whole.

| Option     | Description                             | Example   |
| ---------- | --------------------------------------- | --------- |
| Background | Dashboard background color              | `#f9f9fb` |
| Padding    | Outer padding around the dashboard grid | `16px`    |

### Widgets

Settings that apply to every widget (chart card) on the dashboard.

| Option     | Description                      | Example   |
| ---------- | -------------------------------- | --------- |
| Background | Widget card background color     | `#ffffff` |
| Padding    | Inner padding within each widget | `12px`    |

### Widgets → Borders

Border styling for widget cards.

| Option | Description                                                  | Example   |
| ------ | ------------------------------------------------------------ | --------- |
| Color  | Border color                                                 | `#E1E2E8` |
| Radius | Corner radius                                                | `8px`     |
| Style  | Border style (`solid`, `dashed`, `dotted`, `double`, `none`) | `solid`   |
| Width  | Border thickness                                             | `1px`     |

### Widgets → Titles

Typography for widget titles.

| Option      | Description       | Example     |
| ----------- | ----------------- | ----------- |
| Color       | Title text color  | `#1a1a2e`   |
| Font Size   | Title font size   | `18px`      |
| Font Weight | Title font weight | `600`       |
| Font Family | Title font family | `system-ui` |


# AI summary
Source: https://docs.cube.dev/docs/explore-analyze/dashboards/widgets/ai-summary

Generate natural-language summaries of dashboard data on demand using an AI agent.

AI summary widgets generate a natural-language summary of the data shown on the dashboard. Write a prompt — for example, *"Summarize the key trends and call out anything unusual"* — and the configured [AI agent][ref-agents] produces a Markdown narrative based on the current dashboard state, including the data behind every chart and the values of any active [controls][ref-controls].

## Adding an AI summary

In the [dashboard builder][ref-workbooks], add an AI summary from the **Add Widgets** menu in the toolbar. The widget opens with a prompt editor — write your prompt and click **Generate Summary** to produce the first response.

## Use cases

* Add an executive summary at the top of a dashboard
* Surface anomalies or notable changes since the last refresh
* Explain numbers to stakeholders who want context without diving into the charts
* Generate a TL;DR for periodic dashboard distributions

## Writing a prompt

Write the prompt as if you were briefing an analyst — describe the audience, the angle you want, and any specific things to call out. The agent has access to the full dashboard context, so you can reference charts and controls by name.

## Caching

Once generated, the summary is **cached** with the widget. Viewers loading the dashboard see the cached response immediately — they don't pay for regeneration on every page load.

## Staleness detection

The widget keeps a checksum of the dashboard state at the time of generation: the queries behind each chart, the active control values, and the chart configuration. When any of those change, the widget marks the cached summary as **stale** and shows a refresh prompt so viewers know the narrative may no longer match the data.

Click the refresh icon (or open the widget menu and choose **Refresh**) to regenerate using the saved prompt against the latest state.

## Choosing the agent

By default, AI summaries use the agent configured at the dashboard level. You can override the agent per widget when you need a particular [agent's][ref-agents] tooling, model, or guardrails for a specific summary.

[ref-workbooks]: /docs/explore-analyze/workbooks

[ref-agents]: /admin/ai

[ref-controls]: /docs/explore-analyze/dashboards/widgets/controls


# Charts
Source: https://docs.cube.dev/docs/explore-analyze/dashboards/widgets/charts

Display reports from your workbook as visualizations on the dashboard.

Chart widgets display a report from the source [workbook][ref-workbooks] as a visualization on the dashboard. Every chart on a dashboard is backed by a tab in the workbook — when you publish a new version of the workbook, the chart updates accordingly.

## Adding a chart

In the [dashboard builder][ref-workbooks], open the **Charts** picker in the toolbar and select one or more reports from the workbook. A chart is added to the canvas for each selected report, inheriting the report's query, configured visualization, and styling.

If the picker is empty, create the report first in a workbook tab — only published reports are available to add to a dashboard.

## Interaction with controls

Charts respect the [controls][ref-controls] placed on the same dashboard — filters, time granularity switchers and field switchers. A single control can drive multiple charts at once: its value is applied to every chart whose query references the targeted dimension.

If some controls are incompatible with a chart's query, the chart skips them and shows a warning icon. See [Incompatible controls][ref-incompatible-controls] for details.

## Updating charts

Charts on a published dashboard reflect the most recent published version of the workbook. To change the query, switch the chart type, or restyle the visualization, edit the underlying report in the workbook and publish a new version of the dashboard.

**Edit in Workbook** in the chart's settings menu opens that report directly, on its own workbook tab.

### Filters carried into the workbook

The dashboard's [filters][ref-controls] come along, so the report opens showing the same slice of data the chart was showing rather than re-running over everything.

They sit in the report's filter bar next to its own filters, tinted violet to set them apart, and read the same way — member, operator, value. Hovering one says **From dashboard**. What is different is that they are not the report's:

* they apply to the results on screen, and are **not** saved to the report. Publishing the workbook again will not pin them onto the chart for everyone.
* their values cannot be changed in the workbook. To explore a different value, add your own filter on the same field, or change the dashboard's control and reopen the chart.
* they can be dropped, but not kept: **Clear filter** on the chip removes it for the rest of the session and the report re-runs without it. Reopening the chart from the dashboard brings the current values back.

To change what a viewer of the dashboard can filter by, edit the [filter control][ref-controls] there — not the report.

When the report already filters the same field, both filters apply — exactly as they do on the dashboard, so the numbers match the chart you came from. A carried filter that says precisely what the report already says is left out rather than shown twice.

Only filters are carried. A [time granularity switcher or field switcher][ref-controls] on the dashboard does not follow into the workbook, so a report opened this way shows its own granularity and its own fields.

## Title

Each chart shows the name of the underlying workbook tab as its title. To rename it, open the tab in the workbook, rename the tab, and republish the dashboard — the new name flows through to every chart backed by that tab.

Use **Hide Title** in the widget's settings menu to suppress the title on the dashboard — useful when the chart's content already makes the subject obvious, or when an adjacent [text widget][ref-text] provides its own heading. Choose **Show Title** in the same menu to bring it back.

[ref-workbooks]: /docs/explore-analyze/workbooks

[ref-controls]: /docs/explore-analyze/dashboards/widgets/controls

[ref-incompatible-controls]: /docs/explore-analyze/dashboards/widgets/controls#incompatible-controls

[ref-text]: /docs/explore-analyze/dashboards/widgets/text


# Controls
Source: https://docs.cube.dev/docs/explore-analyze/dashboards/widgets/controls

Filter, time granularity switcher, field switcher, and parent widgets that let dashboard viewers change what's shown on the dashboard.

Controls are widgets that let dashboard viewers change what's shown without leaving the dashboard. The dashboard builder offers four control types:

* [Filter](#filter) — Narrow the data shown on the dashboard
* [Time granularity switcher](#time-granularity-switcher) — Change the granularity of time-based dimensions
* [Field switcher](#field-switcher) — Swap which dimension or measure the charts are built on
* [Parent](#parent) — Re-point several other controls at once from a single dropdown

The first three each target a member from your semantic model, and apply the viewer's choice to every [chart][ref-charts] on the dashboard whose query references that member. Filters and time granularity switchers change *how a member is queried* — which rows come back, which buckets they fall into. A field switcher goes further and changes *which member is queried at all*. A parent control works one level up: it targets no member of its own and drives *other controls* instead.

## Filter

Filter widgets let viewers narrow down the data shown on the dashboard. In the [dashboard builder][ref-workbooks], open the **Add Controls** menu in the toolbar and choose **Filter**. The new filter is added in an unconfigured state — click **Configure Filter** (or open the widget's settings menu) to pick a semantic view and a dimension.

### Operators by dimension type

The available operators depend on the type of the underlying dimension:

| Dimension type | Operators                                                                                                                                  |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **String**     | `is`, `is not`, `contains`, `not contains`, `starts with`, `not starts with`, `ends with`, `not ends with`, `is null`, `is not null`       |
| **Number**     | `is`, `is not`, `greater than`, `greater than or equal`, `less than`, `less than or equal`, `is null`, `is not null`                       |
| **Time**       | `is`, `is not`, `before date`, `before or on date`, `after date`, `after or on date`, `between`, `relative date`, `is null`, `is not null` |

### Single vs. multiple selection

Filters can allow either a single value or multiple values. Configure this when adding or editing the filter — multi-select is the default for string dimensions, while time and number dimensions default to a single value.

### Default values

You can set a default value that's applied when the dashboard loads. Defaults are useful for scoping the dashboard to "this quarter" or "the user's region" without requiring viewers to interact with the filter first.

There are two ways to set a default:

* **Static default** — pick a value (or values) directly in the filter. Every viewer sees the same default.
* **User attribute default** — resolve the default from the viewer's [user attribute][ref-user-attributes] at load time, so each viewer sees their own personalized default. [Time granularity switchers](#time-granularity-user-attribute-default), [field switchers](#field-switcher-user-attribute-default) and [parent controls](#parent-user-attribute-default) support this too.

Static defaults are configured by interacting with the filter in the dashboard builder — the value you select is saved on the widget and applied to every viewer when the dashboard loads.

#### User attribute default

Use the **User attribute default** toggle in the filter's edit sidebar to pre-fill a filter from the viewer's [user attribute][ref-user-attributes]. When the dashboard loads, Cube looks up the attribute value for the current viewer and applies it as the filter's default.

This is useful for scoping a dashboard to the viewer's own slice of the data — for example, defaulting a **Region** filter to the viewer's `region` attribute, or a **Sales rep** filter to their `email`.

To configure it:

<Steps>
  <Step title="Open the filter's settings">
    In the dashboard builder, click the filter widget's settings menu and choose **Edit Filter**.
  </Step>

  <Step title="Enable User attribute default">
    Scroll to the **User attribute default** switch and turn it on.
  </Step>

  <Step title="Pick the attribute">
    Select the [user attribute][ref-user-attributes] whose value should be used as the default. Only attributes defined in your account appear in the picker.
  </Step>
</Steps>

How the attribute value is matched to the filter:

| Attribute type                     | How it's applied                                                                                                                                      |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **String**, **Number**             | Used as a single value. Works with single-value operators like `is` / `is not`, and is also accepted by multi-select filters as a one-item selection. |
| **String array**, **Number array** | Used as a list of values, one per array entry. Empty values are dropped.                                                                              |

Empty, `null`, or unresolvable attribute values are skipped — the filter falls back to whatever static default it has, or no default if none is set.

The user attribute default only seeds the filter's *initial* value. Viewers can still change the filter unless its [visibility](#visibility) is set to **Disabled**, in which case the resolved attribute value is locked in for that viewer. Values passed via URL parameters also take precedence over user attribute defaults, so deep links continue to work.

### Faceted filters

When multiple filters target dimensions from the same semantic view, you can mark them as **faceted**. Faceted filters scope each other's value lists — selecting a value in one filter narrows the options shown in the others, so viewers only see combinations that exist in the data.

For example, on a sales dashboard with a **Country** filter and a **City** filter, marking both as faceted means selecting `United States` in the Country filter limits the City filter to U.S. cities only.

## Time granularity switcher

Time granularity switchers let viewers change the granularity of time-based dimensions on the dashboard — for example, switching a revenue chart from daily to weekly or monthly. The widget targets a single time dimension and applies the chosen [granularity][ref-granularities] to every chart that groups by that dimension.

In the [dashboard builder][ref-workbooks], open the **Add Controls** menu in the toolbar and choose **Time Granularity**. The new switcher is added in an unconfigured state — open its settings to pick a semantic view and a time dimension.

### Allowed granularities

By default, viewers can choose between **day**, **week**, **month**, **quarter**, and **year**. You can narrow this list in the widget's settings to only expose the granularities that make sense for the dashboard.

For time dimensions backed by a `TIMESTAMP` or `DATETIME` column, sub-day granularities (**second**, **minute**, **hour**) are also available. `DATE`-typed columns don't expose sub-day granularities, since they would bucket the entire day into a single point.

Custom granularities defined in the [data model][ref-granularities] aren't offered in this list yet — the switcher exposes the built-in granularities only.

### Default granularity

You can configure a default granularity that's applied when the dashboard loads. If no default is set, charts use the granularity that was saved on the underlying report — viewers can still switch granularities, but the dashboard opens with each chart at its original granularity.

#### User attribute default

The default above is one granularity for everyone. To give each viewer their own, turn on **User attribute default** in the switcher's settings and pick a [user attribute][ref-user-attributes]. When the dashboard loads, Cube reads that attribute for the current viewer and opens the control on the granularity it names.

This is how one dashboard opens at the interval each audience works in — daily for the operations team, monthly for the executives who read the same charts — from a single published dashboard.

To configure it:

<Steps>
  <Step title="Open the switcher's settings">
    In the dashboard builder, open the widget's settings menu and choose **Edit Control**.
  </Step>

  <Step title="Enable User attribute default">
    Below **Visibility**, turn on the **User attribute default** switch.
  </Step>

  <Step title="Pick the attribute">
    Select the [user attribute][ref-user-attributes] to resolve. Only attributes defined in your account appear in the picker.
  </Step>
</Steps>

The attribute value is matched against the **granularity names** the switcher [allows](#allowed-granularities) — `day`, `week`, `month`, `quarter`, `year`, and `second`, `minute`, `hour` where the dimension exposes them — ignoring case and surrounding spaces, so an attribute reading `Week` resolves to `week`. The names are matched, not the labels the control displays, so one attribute works the same for viewers in every language.

| Attribute type                     | How it's applied                                                                                                |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **String**, **Number**             | Matched against the granularity names as a single value.                                                        |
| **String array**, **Number array** | The first entry that names an allowed granularity wins. The switcher is single-select, so the rest are ignored. |

A value that isn't one of the switcher's [allowed granularities](#allowed-granularities) — or is empty, `null`, or unresolvable — is ignored rather than forced, and the control falls back to the [default granularity](#default-granularity). Attributes are set per user and the allowed list per dashboard, so the two can drift apart without anyone editing either; the safe reading of an unusable value is "no opinion".

<Note>
  The attribute is resolved for the viewer, not baked into the dashboard. Editing the attribute's value changes what that viewer opens on the next time the dashboard loads; it never rewrites the published dashboard, so the default granularity you set in the builder stays intact for everyone else.
</Note>

Viewers can still switch granularities unless the control's [visibility](#visibility) is set to **Disabled**, and their own pick outranks the attribute for the rest of the session. A granularity passed [in the URL](#sharing-the-current-selection) outranks both, so deep links continue to work. If a [parent control](#parent) drives this switcher and the option the viewer is on maps a granularity to it, that mapping decides the granularity — a mapping the author made for that arrangement is more specific than a per-viewer starting point. An option that [leaves the switcher empty](#children) has no opinion, so the attribute still seeds it; one set to **Reset to default** returns the switcher to the granularity it opens on *for that viewer* — the attribute granularity when one resolves, otherwise the saved [default granularity](#default-granularity) — and leaves it untouched when neither resolves.

## Field switcher

A field switcher lets viewers change *which* dimension or measure the charts are built on — swapping a revenue chart's breakdown from **Status** to **City**, or its measure from **Order count** to **Total revenue** — without leaving the dashboard or opening the report.

Where a [filter](#filter) narrows the rows and a [time granularity switcher](#time-granularity-switcher) rebuckets them, a field switcher replaces the member itself in the chart's query. One dashboard can then answer several questions that would otherwise need a chart each.

In the [dashboard builder][ref-workbooks], open the **Add Controls** menu in the toolbar and choose **Field Switcher**, then click **Configure Field Switcher** to set it up.

### Choosing what it switches

A field switcher works on one member kind at a time — set **Field Type** to either **Dimension** or **Measure**. The rest of the settings follow from that choice:

| Setting                                           | What it does                                                                                                                                   |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Field Type**                                    | Whether this control swaps a dimension or a measure. Switching the type resets the settings below it, since the two draw from different pools. |
| **Dimension to Replace** / **Measure to Replace** | The member the charts are currently built on — the one this control stands in for.                                                             |
| **Alternatives**                                  | The members viewers may switch to. The replaced member is always offered as well, so a viewer can get back to the original view.               |

Alternatives come from the control's own semantic view, and must be the same kind as the replaced member — a dimension switcher offers dimensions, a measure switcher offers measures.

### Default option

The member a viewer starts on is set the same way a filter's static default is: by picking it in the control while you're in the dashboard builder. The selection is saved on the widget and applied to every viewer when the dashboard loads. If you never pick one, the dashboard opens on the replaced member.

Removing a member from **Alternatives** after it was serving as the default clears the default, so viewers can't start on a member the control no longer offers.

### Default granularity per option

When a dimension switcher offers **time** dimensions, each of them can carry its own granularity, set under **Default granularity per option**.

This exists because a swap otherwise inherits whatever granularity the chart already had. A viewer moving from **Created at** to a **Completed at** that only makes sense monthly would get the replaced dimension's daily buckets, and the author would have no way to say otherwise.

Each time option is either pinned to a granularity or left at **Inherit from the chart**, which is the default and the behavior of every control configured before this setting existed. Non-time options don't have the setting, and a measure switcher has no granularities to speak of.

If the dashboard also has a [time granularity switcher](#time-granularity-switcher) pointed at the swapped-in dimension, the viewer's own pick wins over the per-option granularity — a granularity a viewer actively chose outranks one the author set as a starting point. A granularity control nobody has touched does not.

### User attribute default

Like [filters](#user-attribute-default), [time granularity switchers](#time-granularity-user-attribute-default) and [parent controls](#parent-user-attribute-default), a field switcher can start each viewer on their own member. Turn on **User attribute default** in the control's settings and pick a [user attribute][ref-user-attributes]; when the dashboard loads, Cube reads that attribute for the current viewer and opens the control on the member it names.

This is how one dashboard opens on the breakdown each audience cares about — a **Breakdown** switcher opening on `region` for one team and `channel` for another, from a single published dashboard.

The attribute seeds the *selection*, exactly as the [default option](#field-switcher-default-option) does, and loses to a pick the viewer has already made. A member passed [in the URL](#sharing-the-current-selection) outranks both, so deep links keep working. If a [parent control](#parent) drives this switcher and the option the viewer is on maps a member to it, that mapping decides the member; an option that [leaves the switcher empty](#children) has no opinion, so the attribute still seeds it, and one set to **Reset to default** returns the switcher to the member it opens on *for that viewer* — the attribute member when the switcher still offers it, otherwise its [default option](#field-switcher-default-option). A value that isn't among the **Alternatives** is ignored rather than forced: the attribute is set per user and the options are set per dashboard, so the two can drift apart without anyone editing either, and the safe reading of an unusable value is "no opinion" — the control falls back to the default option.

### What the swap preserves

The swapped-in member is queried under the replaced member's output name, so everything the chart configured against that column keeps working across a switch — column formatting, sorting, pivots, and conditional formatting rules all survive, rather than resetting each time the viewer picks a different member.

### When a chart can't take the switch

Cube applies the switch in two places: to the SQL that runs, and to the query description the chart formats its results with. It applies the switch only if **both** take it — otherwise the chart would be labelled and formatted as one member while showing another's numbers, which nothing on screen would reveal.

When only one half can take it, the chart keeps rendering the member it was built on and shows a notice reading **"The Field switcher could not be applied to this chart"**. The usual reason is a query Cube can't read back as semantic members — a hand-written one, or one built with a `JOIN` or `UNION`. The rest of the dashboard still switches.

A chart whose query doesn't use the replaced member at all is a different case: it is simply out of the control's scope, exactly as it would be for a filter, and shows no notice.

A chart with a [period comparison][ref-charts] is a narrower case: the comparison can't follow a member switch, so the chart applies the switch and drops the comparison, saying so in its own notice rather than silently showing a comparison that no longer matches the data.

## Parent

A parent control is a dropdown of options you define. Picking one re-points a whole row of other controls at once — so a viewer makes a single choice instead of adjusting three or four filters by hand.

Unlike the other control types, a parent control targets no member and never touches a chart query directly. It applies values to the controls it *drives* — its **children** — and those children then apply themselves to charts exactly as if the viewer had operated each one. Filters, time granularity switchers and [field switchers](#field-switcher) can all be children; a parent control cannot be a child of another parent control.

For example, an **Analysis** parent with the options `Retail`, `Wholesale` and `Promo` can set a **Channel** filter, a **Minimum order value** filter, and a **Date range** filter to a different combination for each option. Viewers see one dropdown; you can [hide](#visibility) the children if the individual values aren't worth showing.

In the [dashboard builder][ref-workbooks], open the **Add Controls** menu in the toolbar and choose **Parent**, then click **Configure Parent** to set it up. The editor has two tabs — **Options** and **Children**.

<Info>
  Add the child controls to the dashboard *before* the parent control. The **Children** tab can only map controls that already exist, so a parent added to an empty dashboard has nothing to drive yet.
</Info>

### Options

On the **Options** tab, type a label and click **Add** for each entry you want in the dropdown. Options appear as chips — remove one with its close button. A parent control can hold up to 50 options.

Renaming an option later doesn't disturb the values you've mapped to it, so you can reword a label without redoing the mapping — but if the control has a [user attribute default](#parent-user-attribute-default), that match is by label, so rename the attribute's values with it.

### Children

On the **Children** tab, pick a control from **Child control**, then give each of the parent's options a value for it. Each row renders *that child's own control* — a time granularity switcher's row shows its granularity picker, limited to the granularities that switcher allows; a filter's row shows that filter's operator and value inputs; a field switcher's row shows its member picker, limited to the members that switcher offers — its **Alternatives**, plus the replaced member. So the values you can offer are exactly the ones a viewer could pick in the child itself.

Repeat for each control you want the parent to drive. Every option/child pair can be in one of three states:

| State                | What happens when the viewer picks that option                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **A value**          | The child is set to that value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **Reset to default** | The child is put back to the value it opens on *for that viewer*. When the child takes its default from a **User attribute default** — a [filter](#user-attribute-default)'s, a [time granularity switcher](#time-granularity-user-attribute-default)'s, or a [field switcher](#field-switcher-user-attribute-default)'s — that's the attribute value; otherwise it's the child's own static default: no filtering on that dimension for a filter, its [default granularity](#default-granularity) for a time granularity switcher, its [default option](#field-switcher-default-option) for a field switcher. Turn on the row's **Reset to default** switch. |
| **Left empty**       | The child is left alone — it keeps whatever value the viewer already had. Use this deliberately when an option shouldn't have an opinion about a particular child.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

While the parent's settings are open, the children it drives are highlighted on the canvas, so you can see the scope of the mapping at a glance.

### One parent per child

A control can be driven by only one parent control at a time. Mapping a child that another parent already drives **moves** it rather than sharing it — the editor warns you before you save, naming the parent that currently owns it.

### Mapping status on child controls

Once a dashboard has at least one parent control, every filter, time granularity switcher and [field switcher](#field-switcher) on it shows a small indicator reporting how it's driven:

| Status            | Meaning                                                                             |
| ----------------- | ----------------------------------------------------------------------------------- |
| **Fully driven**  | Every option of the owning parent sets this control.                                |
| **Partly driven** | Only some of the owning parent's options set this control; the rest leave it alone. |
| **Not driven**    | No parent control maps this one.                                                    |

Click the indicator to jump straight to the **Children** tab of the parent that owns that control, with it already selected. For a control nothing drives yet, the click opens the first parent control on the dashboard — topmost, then leftmost — so you can map it.

### Default option

A parent control's default is set the same way a filter's static default is — by interacting with the control in the dashboard builder. The option you select is saved on the widget and applied to every viewer when the dashboard loads; there's no static default field in the parent's settings.

Picking in the builder also applies that option's values to the children, so their saved defaults line up with the parent's and a published dashboard opens in a consistent state.

If you never pick an option, the parent opens with nothing selected and the children use their own defaults. Deleting the option that was serving as the default clears it, and the parent goes back to opening on nothing.

#### User attribute default

The default above is one arrangement for everyone. To give each viewer their own, turn on **User attribute default** in the parent control's settings and pick a [user attribute][ref-user-attributes]. When the dashboard loads, Cube reads that attribute for the current viewer and opens the control on the option it names — and drives the children with it, exactly as if the viewer had picked that option themselves.

This is how you ship one dashboard that opens differently per audience: a **Reporting period** parent whose options are `Month` and `Quarter`, opening on whichever one the viewer's `reporting_period` attribute says, with every control behind it already set to match.

To configure it:

<Steps>
  <Step title="Open the parent control's settings">
    In the dashboard builder, click **Configure Parent** on the control.
  </Step>

  <Step title="Enable User attribute default">
    Below the **Options** and **Children** tabs — next to **Visibility** — turn on the **User attribute default** switch.
  </Step>

  <Step title="Pick the attribute">
    Select the [user attribute][ref-user-attributes] to resolve. Only attributes defined in your account appear in the picker.
  </Step>
</Steps>

The attribute value is matched against the **option labels**, ignoring case and surrounding spaces — an attribute reading `quarter` selects the option labelled `Quarter`. Give the options the labels your attribute already uses, or adjust the attribute values to match.

<Warning>
  Renaming an option leaves its child mappings intact, but the attribute match is by label — so a rename that moves a label away from the values your attribute holds silently stops it resolving, with no error. The control falls back to the option you picked as the default. Rename labels and attribute values together.
</Warning>

| Attribute type                     | How it's applied                                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **String**, **Number**             | Matched against the option labels as a single value.                                                   |
| **String array**, **Number array** | The first entry that names an option wins. A parent control is single-select, so the rest are ignored. |

If the value matches no option — or is empty, `null`, or unresolvable — the control falls back to the [default option](#default-option) you picked, and the children keep the arrangement that goes with it.

<Note>
  The attribute is resolved for the viewer, not baked into the dashboard. Editing the attribute's value changes what that viewer opens on the next time the dashboard loads; it never rewrites the published dashboard, so the default you picked in the builder stays intact for everyone else.
</Note>

Viewers can still switch to another option unless the control's [visibility](#visibility) is set to **Disabled**, and their own pick outranks the attribute for the rest of the session. Values passed [in the URL](#sharing-the-current-selection) outrank both — but only what the sharer actually picked travels: a parent control has no parameter of its own, and an untouched, attribute-resolved one puts nothing in the link, so the recipient still opens on their own attribute. When the sharer did pick an option, the link carries that option's *children's* values and the recipient opens on those.

## Sharing the current selection

On a published dashboard, the values a viewer picks in the controls are reflected in the URL, so the view they are looking at is bookmarkable and shareable. Copy the address bar, send it on, and the recipient opens the dashboard with the same filters, granularities and member choices applied.

Each control type has its own parameter:

| Control                                                 | Parameter                                                | Example                               |
| ------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------- |
| [Filter](#filter)                                       | `f_<semantic_view>.<dimension>=<JSON>`                   | `f_orders.status={"value":"shipped"}` |
| [Time granularity switcher](#time-granularity-switcher) | `tg_<semantic_view>.<dimension>=<granularity>`           | `tg_orders.created_at=week`           |
| [Field switcher](#field-switcher)                       | `ms_<semantic_view>.<replaced_member>=<selected_member>` | `ms_orders.status=users_city`         |

The semantic view and member are the **internal names** configured on the control — not the display titles you see in the picker. A view shown as `Orders` is usually `orders` in the parameter. The same goes for the member on the right-hand side of `ms_`: it is the internal name of the member to switch to, and it is a measure rather than a dimension when the switcher's **Field Type** is **Measure**. Granularities are lowercase and must be one of the switcher's [allowed granularities](#allowed-granularities) — `day`, `week`, `month`, `quarter`, `year`, plus `second`, `minute`, and `hour` for time dimensions that expose them.

You can also write these parameters by hand to open a dashboard in a particular state — see [Pre-set dashboard filters and granularities via URL][ref-embed-url-filters] for the embedded case, which uses the same format.

What does and doesn't travel in the link:

* **Only what the viewer chose.** Values that came from the control's own configuration — a static default, a [default granularity](#default-granularity) — are not written into the URL. Every viewer already gets those from the dashboard itself, and leaving them out means a link stays correct after the dashboard's defaults change.
* **Never a personalized default.** A value resolved from a [user attribute](#user-attribute-default) stays out of the link — whether it seeded a filter, a [time granularity switcher](#time-granularity-user-attribute-default) or a [field switcher](#field-switcher-user-attribute-default) directly, or reached one through a [parent control](#parent) opening on the viewer's own option. Sharing a dashboard never pins your attribute value onto the recipient; they see it through their own attributes.
* **Every control's pick, together.** Picking in several controls puts them all in the link, including when a [parent control](#parent) sets several children at once — filters, time granularity switchers and [field switchers](#field-switcher) alike. A parent control isn't serialized itself — the link carries the values its children ended up with, so the recipient sees the same data while the parent dropdown opens on whatever default it resolves for them, which may not be the option the sharer picked.
* **Written out on published dashboards only.** Reading these parameters works anywhere, including [embedded][ref-embed-url-filters] dashboards; it's the writing that is published-only. In the dashboard builder the URL is left to the editing session, so changing a control there doesn't rewrite it.

When a dashboard opens with these parameters, they are applied on top of whatever defaults the controls carry. A parameter is ignored when nothing on the dashboard can honor it — there is no matching control for that member, the requested granularity isn't in the switcher's [allowed granularities](#allowed-granularities), or the selected member is one the field switcher doesn't offer — its **Alternatives**, plus the replaced member.

## Visibility

Each control has a **Visibility** setting that determines how it appears on the published dashboard. The setting applies to all four control types.

| Visibility            | Behavior on the published dashboard                                                                                                                                                                                                                                                                                                                            |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Visible** (default) | Shown on the dashboard and viewers can change its value.                                                                                                                                                                                                                                                                                                       |
| **Hidden**            | Not shown to viewers, but the control's value is still applied to the charts it targets. Use this to scope a dashboard with a fixed value — e.g., always filter to the current quarter — without exposing the control. Hiding the *children* of a [parent control](#parent) is the usual way to present one dropdown instead of the row of controls behind it. |
| **Disabled**          | Shown on the dashboard so viewers can see the active value, but they cannot change it.                                                                                                                                                                                                                                                                         |

Set the visibility from the **Visibility** dropdown when editing the control. **Hidden** controls remain visible in the dashboard builder so editors can reconfigure them, but disappear from the published view.

## Interaction with charts

This section applies to filters, time granularity switchers and field switchers. A [parent control](#parent) has no member of its own and never applies to a chart itself, so it doesn't appear in any chart's [Controls mapping](#controls-mapping) — it acts only through the children it drives, and it's those children that show up here.

When a control is added to a dashboard, it's automatically wired up to every [chart][ref-charts] whose query already uses the same member. Charts that don't reference that member are left alone, so a dashboard can mix scoped and unscoped views by default. Filters and time granularity switchers always target a dimension; a [field switcher](#field-switcher) targets a dimension or a measure depending on its **Field Type**, and scopes on whichever it is set to. You can override this default per chart from its [Controls mapping](#controls-mapping) — disable the control for that chart, or remap it onto a different member.

### Incompatible controls

If controls of a certain type are incompatible with a particular chart's query, the chart skips all controls of that type and renders the data without them. Each type is skipped independently — if filters fail but a time granularity switcher works, the chart shows the granularity-adjusted data without filtering, and vice versa. A [field switcher](#field-switcher) that can't be applied says so [on the chart itself](#when-a-chart-cant-take-the-switch) rather than through the icons below.

The chart displays a warning icon to indicate the problem:

| Icon               | Meaning                                              |
| ------------------ | ---------------------------------------------------- |
| Crossed-out filter | Filters were skipped for this chart                  |
| Crossed-out clock  | Time granularity override was skipped for this chart |

Hover over the icon for details. Click it to open the chart's [Controls mapping](#controls-mapping) and fix the issue — remap the control to a compatible dimension or disable it for this chart.

### Controls mapping

Each chart decides which controls apply to it through its **Controls mapping**. The mapping is resolved automatically in most cases and only needs manual attention when a control targets a member the chart doesn't have.

Open **Controls mapping** from a chart's settings menu to inspect or override the mapping for that chart. For each control on the dashboard you can:

* **Toggle the control on or off** for the chart, even when a mapping exists
* **Pick a different member** from the chart's semantic view to remap the control to

Three states show up in the mapping sidebar:

| Status                      | What it means                                                                                                                                   |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Mapped automatically**    | The control's member exists on the chart's semantic view, so it's wired up without configuration.                                               |
| **Manually mapped**         | You (or an AI agent) picked a specific member for this chart. **Reset** restores the automatic mapping.                                         |
| **Can't map automatically** | The control targets a member that doesn't exist on the chart's semantic view. The chart is unaffected by the control until you map it manually. |

Each control's picker offers only the members it can actually be resolved against, so a mapping you can stage is a mapping that will work:

| Control                                                 | What the picker offers                                                                       |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [Filter](#filter)                                       | Dimensions on the chart's semantic view.                                                     |
| [Time granularity switcher](#time-granularity-switcher) | Time-typed dimensions only — other types can't be resolved by the time granularity pipeline. |
| [Field switcher](#field-switcher) set to **Dimension**  | Dimensions.                                                                                  |
| [Field switcher](#field-switcher) set to **Measure**    | Measures, since the control replaces a measure.                                              |

Filter and time granularity mappings are also configurable by AI agents when they build or edit a dashboard, so an agent can wire those controls across charts that use different semantic views without you needing to revisit each chart manually. Field switchers are outside what agents author, so their mappings are yours to set.

[ref-embed-url-filters]: /embedding/iframe/dashboards#pre-set-dashboard-filters-via-url

[ref-workbooks]: /docs/explore-analyze/workbooks

[ref-charts]: /docs/explore-analyze/dashboards/widgets/charts

[ref-granularities]: /docs/data-modeling/dimensions

[ref-user-attributes]: /admin/users-and-permissions/user-attributes


# Widgets
Source: https://docs.cube.dev/docs/explore-analyze/dashboards/widgets/index

Building blocks for dashboards — charts, text, controls, AI summaries, and layout elements that you arrange on the canvas to tell your data story.

Widgets are the building blocks of a dashboard. Each tile placed on the canvas in the [dashboard builder][ref-workbooks] is a widget — a chart, a block of text, a control that viewers interact with, an AI-generated summary, or a layout element such as a spacer, divider, or stack. Combine them to assemble polished, interactive views of your data.

## Widget types

The dashboard builder supports the following widget types:

* [Charts](/docs/explore-analyze/dashboards/widgets/charts) — Visualize reports from your workbook
* [Text](/docs/explore-analyze/dashboards/widgets/text) — Add titles, descriptions, and rich formatting in Markdown
* [Controls](/docs/explore-analyze/dashboards/widgets/controls) — Let viewers filter the data, switch the time granularity, swap which field the charts are built on, or drive several controls at once
* [AI summary](/docs/explore-analyze/dashboards/widgets/ai-summary) — Generate narrative summaries of dashboard data on demand
* [Spacer, Divider & Stack](/docs/explore-analyze/dashboards/widgets/layout) — Non-data layout elements for whitespace, section breaks, and grouping widgets

## Adding widgets

Add widgets from the toolbar at the top of the dashboard builder: pick reports from the **Charts** picker to add charts, use the **Add Widgets** menu for text, AI summaries, and layout elements, or the **Add Controls** menu for **Filter**, **Time Granularity**, **Field Switcher** and **Parent** controls.

Each item — a toolbar button, or an option inside the **Add Widgets** / **Add Controls** menus — can be added in two ways:

* **Click** it to drop the widget into the first open spot on the canvas.
* **Drag** it from the toolbar onto the canvas to place it exactly where you want. As you drag, a full-size placeholder previews the widget's footprint and the surrounding widgets reflow to open a slot; release to drop it there. Dragging is especially handy on dense dashboards, where clicking would otherwise place the new widget far down the page.

Starting a drag from a menu option closes the menu, so it doesn't cover the canvas while you place the widget.

## Arranging widgets

Drag any widget to move it, and use the handle in its bottom-right corner to resize it — the surrounding widgets shift to make room.

To work with several widgets at once, select them first:

* **Click** a widget to select it.
* **Shift-click** to add widgets to, or remove them from, the selection.
* **Drag a marquee** — press on any empty part of the canvas and drag a rectangle over the widgets you want; every widget it touches is selected.

With a selection in place:

* **Move the group** — drag any selected widget and the whole selection moves together, keeping its relative arrangement.
* **Delete the group** — press **Delete** or **Backspace** to remove every selected widget at once.

[ref-workbooks]: /docs/explore-analyze/workbooks


# Spacer, Divider & Stack
Source: https://docs.cube.dev/docs/explore-analyze/dashboards/widgets/layout

Non-data layout elements — a spacer for whitespace, a divider line, and stack containers that group widgets — to help you structure a dashboard.

Spacers, dividers, and stacks are non-data **layout** widgets. They carry no data of their own; you place them on the canvas alongside charts, text, and controls to add whitespace, visual structure, and grouping to a dashboard.

## Spacer

A spacer is an empty, resizable box. Use it to add deliberate whitespace between widgets — for example, to separate a header row from the charts below it, or to push a widget into a particular column.

A spacer is only visible while you are editing in the [dashboard builder][ref-workbooks]. On the published dashboard (including [embedded views](/embedding/iframe/dashboards)) it renders as empty space, so it never draws a card or border for viewers.

## Divider

A divider is a horizontal separator line that breaks up the layout flow — a lightweight way to signal the boundary between sections of a dashboard. Unlike other widgets, a divider is a fixed height and **cannot be resized** vertically.

## Stack

A **horizontal stack** or **vertical stack** is a container that groups several widgets and lays them out evenly — side by side in a horizontal stack, or top to bottom in a vertical stack. Use a stack to keep a set of related widgets aligned and sized together, instead of positioning each one on the grid by hand.

Place a stack on the canvas and resize it to any width and height; its children always share that space evenly:

* In a **horizontal stack**, each child takes the full height and an equal share of the width.
* In a **vertical stack**, each child takes the full width and an equal share of the height.

Add a widget to a stack by dragging it in — from the canvas, the **Add Widgets** menu, or another stack — and remove one by dragging it back out; the remaining children redistribute to fill the space. Stacks can be nested inside one another.

Because a stack owns its children's layout, you work with the **container as a unit**: select, move, resize, or delete the stack itself and it carries its children with it. Individual widgets inside a stack are not separately selectable on the board — a marquee drawn over a stack selects the container, not its children. To rearrange children, drag one to a new position **within** the stack; to take one out, drag it onto the canvas or into another container.

## Adding a layout widget

In the [dashboard builder][ref-workbooks], open the **Add Widgets** menu in the toolbar and choose **Spacer**, **Divider**, **Horizontal Stack**, or **Vertical Stack**. The widget is added to the canvas, where you can drag it into place and resize it (a divider resizes horizontally only).

## Styling

The **spacer** and **divider** follow the dashboard's [widget styling settings](/docs/explore-analyze/dashboards/styling):

* The **divider** draws its line using the widget **border** width, style, and color.
* A **spacer** picks up the same border and background settings while you are editing, so its bounds are easy to see.

A **stack** draws no card of its own — it only groups and sizes its children, each of which keeps its own styling.

[ref-workbooks]: /docs/explore-analyze/workbooks


# Text
Source: https://docs.cube.dev/docs/explore-analyze/dashboards/widgets/text

Add titles, descriptions, and rich formatting to dashboards using Markdown.

Text widgets render Markdown content directly on the dashboard. Use them to add narrative, structure, and context around your charts.

## Adding a text widget

In the [dashboard builder][ref-workbooks], open the **Add Widgets** menu in the toolbar and choose **Text**. A new text widget is added to the canvas with an empty editor.

## Use cases

* Add a dashboard title or section headings to break long dashboards into scannable chunks
* Explain what stakeholders are looking at and how to interpret the numbers
* Link out to related dashboards, runbooks, or documentation
* Embed images, callouts, and formatted lists

## Supported syntax

Text widgets support standard Markdown — see the [Markdown Guide](https://www.markdownguide.org/basic-syntax/) for a full reference of supported syntax.

## Editing

Click the widget's settings menu and choose **Edit** to open the Markdown editor. The widget renders as you type so you can preview formatting before saving. Use **Hide Title** in the same menu to suppress the widget's title bar when the Markdown content already provides its own heading.

[ref-workbooks]: /docs/explore-analyze/workbooks


# Explore
Source: https://docs.cube.dev/docs/explore-analyze/explore

Self-serve data exploration from Analytics Chat, dashboards, or any semantic view — governed by your data model, shareable via URL.

Explore is a quick way to explore data in your semantic layer either by point and click or with an AI agent. Unlike workbooks, Explore doesn't require you to create a workbook—you can start exploring immediately from a dashboard, Analytics Chat, or any semantic view.

Explore leverages your data model definitions, ensuring that all queries use consistent metrics, respect access control policies, and benefit from pre-aggregations for fast performance.

## Using Explore

You can start exploring from three places in Cube:

### Exploring from Analytics Chat

When the AI agent returns a query result in Analytics Chat, click **Explore** to open that result in an exploration. This allows you to further analyze and visualize the data returned by the AI agent.

<video />

### Exploring from a published dashboard

Hover over a chart widget in a published dashboard, and click **Explore**. The exploration will use the same view and data that feeds into the visualization, giving you access to all measures and dimensions available in that view.

<Frame>
  <img />
</Frame>

### Starting a new exploration from scratch

Navigate to the **Explore** page in the sidebar. From here, you can select any semantic view as the data source and start building visualizations from scratch.

## Explore functionality

The functionality in Explore is similar to when working with semantic views in workbooks. You can build visualizations, pivot tables, and tables by selecting measures and dimensions from your semantic views, apply filters, group and aggregate data.

Explore state is also saved in the URL, making it easy to share your exploration with other users by simply copying and sharing the link.

If you have developer or admin access, you can [apply a security context](/docs/explore-analyze/workbooks/querying-data#applying-a-security-context) to an exploration to verify what a specific end user—or an AI agent querying on their behalf—would see.

Explore results carry the same [freshness and pre-aggregation indicators](/docs/explore-analyze/workbooks/querying-data#result-freshness-and-provenance) as workbook reports.

## Saving explorations

You can save an exploration so you can return to it later without
re-building your query. An exploration is the same kind of object as a
workbook [report](/docs/explore-analyze/workbooks) — the only difference is
whether it belongs to a workbook. [Analytics Chat](/docs/explore-analyze/analytics-chat)
and the Cube MCP `createReport` tool save a standalone exploration the same
way: by leaving the workbook unset.

* **Save** — For an unsaved exploration, click **Save** to open the
  **Save Exploration** dialog. Give your exploration a name and click
  **Save**. The exploration is now persisted and appears in your
  workspace.
* **Save (existing)** — After you modify a previously saved exploration,
  click **Save** to update it in place.
* **Save as** — For a saved exploration, open the chevron menu next to
  **Save** and choose **Save as...** to create a copy under a new name.

You can also rename a saved exploration at any time by clicking its title
in the header and typing a new name.

## Converting to a workbook

When you're ready to build a more permanent analysis, you can convert
your exploration to a [workbook](/docs/explore-analyze/workbooks). Click
**Convert to workbook** to create a new workbook with your exploration
as its first tab.

## Copying to clipboard

You can copy an exploration to your clipboard and paste it as a new tab
in any [workbook](/docs/explore-analyze/workbooks). Click the chevron
next to **Convert to workbook** and select **Copy to Clipboard**.

Then navigate to the target workbook and press **Cmd+V** (macOS) or
**Ctrl+V** (Windows/Linux) to paste the exploration as a new tab.


# Notifications
Source: https://docs.cube.dev/docs/explore-analyze/notifications

Notifications are available on Premium and Enterprise plans.

<Info>
  Notifications are available on [Premium and Enterprise plans](https://cube.dev/pricing).
  <br />Users need at least the [Explorer][ref-roles] role and Edit or Manage permission
  on the workbook to set up notifications.
</Info>

Notifications let you send email or Slack messages with a screenshot of a
dashboard after each [scheduled refresh][ref-scheduled-refreshes]. This is useful
for distributing regular updates to stakeholders without requiring them to log in.
They can optionally carry a short [AI-generated summary](#ai-summary) of what
changed since the previous notification.

## Creating a notification

Notifications are configured as part of a [scheduled refresh][ref-scheduled-refreshes].
When creating or editing a schedule, click **Add notification** to expand
the notification configuration card.

<Tip>
  To send the same dashboard to another channel or recipient list, [duplicate an
  existing schedule][ref-duplicate] instead of configuring the notification from
  scratch — the copy carries over the source schedule's notification settings.
</Tip>

### Delivery channel

A schedule delivers to one channel, not both. Pick it with the **Send via**
radio buttons:

* **Email** — sends to the [recipients](#recipients) you choose: individual
  workspace users, [user groups][ref-user-groups], or a mix of both.
* **Slack** — select a Slack channel to post to. Requires connecting your Slack
  workspace first (one-time OAuth flow via **Connect to Slack**). Once
  connected, select a channel from a searchable picker.

### Screenshot attachment

Choose the format for the dashboard screenshot attached to the notification:

* **PNG** (default)
* **PDF**

Select the format using the **Attach screenshot as** option. The same
formats are available for ad-hoc [downloads from the dashboard
header][ref-download].

### AI summary

Turn on **Include AI summary** to add a short "what changed" note to the body of
the email or Slack message, above the screenshot. It is off by default.

The note is written by the configured [AI agent][ref-agents] and is deliberately
short — an opening line naming the most important change, then two to four
bullets, each with a real number and its movement. It is meant to be read in a
few seconds to decide whether to open the dashboard at all:

```text theme={"dark"}
WHAT CHANGED
Order growth accelerated this week, driven mainly by a surge in returns
outpacing overall gains.
- Weekly orders: 416 last full week, up 20% from 346 the week before.
- Returned orders: 42 last week, up 40% week over week (from 30).
- Completed orders: 202 last week, up 13% week over week (from 179).
```

**What it compares against.** Where possible the note describes what changed
since the *previous notification* for that recipient, rather than what changed
inside the data — so a daily notification does not repeat the same sentence
every morning. On the first send, or when there is no earlier note to compare
with, it falls back to comparing recent periods (week over week, month over
month) and says so rather than inventing a comparison.

<Note>
  Each recipient's note is generated under **their own data access**, so it only
  describes rows that recipient is allowed to see. That also means it costs one
  agent run per recipient per send, which is why the option is off by default.
</Note>

If the summary can't be generated — the agent is unavailable, or the run takes
too long — the notification is still delivered, without the note.

<Tip>
  This is not the same as the [AI summary widget][ref-ai-widget], which lives on
  the dashboard, takes a prompt you write, and is cached for everyone who views
  it. The notification summary uses a fixed brief, is generated per recipient, and
  is never shown on the dashboard.
</Tip>

### Removing a notification

To remove a notification from a scheduled refresh, click the X button in the
notification card header before saving.

## Email notifications

Email notifications are sent to the selected recipients after a scheduled
refresh completes. Each recipient receives a message with a link to the
dashboard and the attached screenshot.

<Tip>
  Recipients don't have to be added by an editor. Anyone who can view the dashboard
  can [subscribe themselves][ref-subscribe] to a schedule's email notifications
  from the published dashboard.
</Tip>

### Recipients

Under the **Recipients** heading there are two separate controls:

* **Users** — a searchable picker for individual workspace users.
* **User groups** — a dropdown holding an expandable checklist of
  [user groups][ref-user-groups] and their members. It appears only when your
  workspace has at least one user group.

A group is expanded to its current members each time the notification is sent,
so adding or removing members takes effect on the next run without editing the
schedule. The number beside a group's name counts the members it can currently
email, so a group can show fewer than its full membership — anyone without an
email address is left out of both the count and the list.

A recipient who is selected individually and also belongs to a selected group is
emailed only once.

#### Excluding individual group members

Tick a group to notify everyone in it, then expand it and untick anyone who
should be skipped. Those people are stored as exceptions to that group on this
schedule — the group stays selected and keeps picking up new members, but the
excluded members are left out of every run.

One search box filters both levels at once, so typing a person's name narrows
the list to the groups that would notify them, with that person shown under
each.

Exceptions are saved with the rest of the form, not applied as you click. A few
details worth knowing:

* Unticking a group's **last** remaining member unticks the whole group.
* Exceptions belong to one schedule and one group. Excluding someone from a
  group here does not affect the group anywhere else, or any other schedule.
* An exception is not a block on the person. If they are **also** selected under
  **Users**, or have [subscribed themselves][ref-subscribe], they still get the
  email — a direct recipient row and group membership are independent, and
  either one alone delivers.

## Slack notifications

Slack notifications post a message with the dashboard screenshot to a single
Slack channel per schedule.

### Connecting Slack

Before you can send Slack notifications, connect your Slack workspace:

1. When configuring a notification, select **Slack** as the delivery
   channel.
2. Click **Connect to Slack** to start the OAuth flow.
3. Authorize Cube to post to your Slack workspace.

This is a one-time setup. Once connected, you can select any channel your Slack
workspace has access to.

[ref-download]: /docs/explore-analyze/dashboards#download-as-png-or-pdf

[ref-roles]: /admin/users-and-permissions/roles-and-permissions

[ref-scheduled-refreshes]: /docs/explore-analyze/scheduled-refreshes

[ref-duplicate]: /docs/explore-analyze/scheduled-refreshes#duplicating-a-schedule

[ref-user-groups]: /admin/users-and-permissions/user-groups

[ref-subscribe]: /docs/explore-analyze/scheduled-refreshes#subscribing-to-notifications

[ref-agents]: /admin/ai

[ref-ai-widget]: /docs/explore-analyze/dashboards/widgets/ai-summary


# Scheduled Refreshes
Source: https://docs.cube.dev/docs/explore-analyze/scheduled-refreshes

Scheduled refreshes are available on Premium and Enterprise plans.

<Info>
  Scheduled refreshes are available on [Premium and Enterprise plans](https://cube.dev/pricing).
  <br />Users need at least the [Explorer][ref-roles] role and Edit or Manage permission
  on the workbook to set up scheduled refreshes. Anyone who can view the dashboard
  can open the sidebar to see its schedules and [subscribe to
  notifications](#subscribing-to-notifications).
</Info>

Scheduled refreshes allow you to automatically refresh published dashboards on a
recurring schedule. When a scheduled refresh runs, the dashboard widgets are
queried in the background, refreshing Cube's in-memory cache. This warms up
dashboards so they load instantly when users open them, eliminating wait times.

You can also attach [notifications][ref-notifications] to scheduled refreshes to
send email or Slack messages with a dashboard screenshot after each refresh.

## Accessing scheduled refreshes

From the Dashboard Builder, click the calendar icon in the toolbar to open the
scheduled refreshes sidebar. From this sidebar, you can create new schedules,
modify existing ones, or remove schedules you no longer need.

The same calendar icon is also available on a published dashboard, so you can
reach the sidebar without opening the builder. What you can do there depends on
your permission on the workbook:

* **Edit** or **Manage** — the full sidebar: create, edit, run, and delete
  schedules.
* **View only** — a read-only list of the configured schedules, where you can
  [subscribe or unsubscribe](#subscribing-to-notifications) yourself from each
  schedule's email notifications.

<Warning>
  The dashboard must be published before schedules can be created.
</Warning>

## Creating a schedule

Click **New scheduled refresh** in the sidebar footer. A dialog opens
with the following configuration options.

### Schedule

Pick how often the refresh runs with the **Schedule** select:

| Option  | Description                                                       |
| ------- | ----------------------------------------------------------------- |
| Hourly  | Runs every hour at the specified minute                           |
| Daily   | Runs once a day at the specified time                             |
| Weekly  | Runs on a chosen day of the week at the specified time            |
| Monthly | Runs on a chosen day of the month at the specified time           |
| Custom  | Accepts a cron expression (5-part: minute hour day month weekday) |

Time is specified in 12-hour format with an AM/PM selector. For Hourly
schedules, only the minute field is shown.

### Timezone

Select from common timezones including UTC, US timezones, London, Paris, Berlin,
Tokyo, Shanghai, Singapore, and Sydney. Defaults to your browser's timezone if
it matches a common one, otherwise UTC.

### Notifications

You can optionally attach [notifications][ref-notifications] to a scheduled
refresh. Click **Add notification** to expand the notification
configuration. See the [Notifications][ref-notifications] page for details.

Click **Save** to create or update the schedule.

## Managing schedules

The sidebar lists all existing schedules with the following information:

* **Status indicator** — current state: not run yet, last run succeeded, last
  run failed, or currently running with phase details.
* **Schedule description** — human-readable text like "At 09:00 AM".
* **Enable/disable toggle** — turn schedules on or off without deleting them.
* **Next run time** — shows the next scheduled execution, or "Disabled" if the
  schedule is off.
* **Notification channel** — when a [notification][ref-notifications] is
  configured, the card shows its delivery channel, for example "Notification:
  Email" or "Notification: Slack (#channel)".

### Actions

| Action    | Description                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------ |
| Run now   | Manually trigger the schedule immediately                                                              |
| Edit      | Open the form dialog to modify the schedule                                                            |
| Duplicate | Create a new schedule pre-filled from this one (see [Duplicating a schedule](#duplicating-a-schedule)) |
| Delete    | Remove the schedule permanently                                                                        |

## Duplicating a schedule

To create a new schedule based on an existing one — for example, to send the
same dashboard to another Slack channel or a different set of recipients without
re-entering the **Schedule**, timezone, and notification settings — you can
duplicate it. There are two ways:

* **From the sidebar** — click the duplicate (copy) icon on a schedule card. The
  form dialog opens pre-filled with its **Schedule**, timezone, and
  notification configuration. Adjust anything you need, then click **Save** to
  create the new schedule.
* **From the edit dialog** — while editing a schedule, click **Save as copy** in
  the dialog footer. This creates a new schedule from the current form values,
  including any unsaved changes, instead of updating the original.

Duplicates are independent schedules: the original is left unchanged, and the
copy keeps the source schedule's enabled or disabled state.

## Subscribing to notifications

If a schedule sends [email notifications][ref-notifications], anyone who can view
the dashboard can subscribe to it themselves — an editor does not have to add
them as a recipient. Open the scheduled refreshes sidebar from the published
dashboard and use the toggle on a schedule to subscribe or unsubscribe.

The toggle covers **every** way that schedule could reach you, in one click. If
you were added individually, unsubscribing removes you from its recipients. If
you are reached through a [user group][ref-user-groups] — or several — it also
records you as an exception to each of those groups on this schedule, so the
group keeps notifying everyone else but stops emailing you. Subscribing reverses
both: it clears those exceptions and adds you back as a recipient in your own
right. The change takes effect on the next run.

<Info>
  Unsubscribing affects only this schedule. It does not remove you from the user
  group, and it does not change any other schedule that group receives.
</Info>

The toggle appears only for schedules that send email — those with
notifications enabled and the email delivery channel. A schedule delivers to
either individual inboxes or a Slack channel, not both, so a schedule that posts
to Slack (or that has notifications turned off) has nothing to subscribe to. If an
editor switches a schedule to Slack, its individual subscriptions are cancelled
and any group exceptions it held are cleared; if it is later switched back to
email, everyone starts from the group's full membership again and can subscribe
or unsubscribe afresh.

Every notification email also includes a one-click **Unsubscribe** link in its
footer, so a recipient can stop receiving a schedule's emails without signing in
to Cube. It behaves exactly like the toggle, covering both a direct recipient row
and any [user group][ref-user-groups] delivering to you. This works for any
recipient, including those added directly by an editor and embed users who have
no Cube account of their own.

## Run phases

When a scheduled refresh runs, it progresses through these phases:

1. Initializing
2. Fetching credentials
3. Refreshing dashboard
4. Generating screenshot (if notifications are configured)
5. Generating AI summary (if the notification has [AI summary][ref-ai-summary]
   turned on)
6. Sending notifications (if notifications are configured)

The sidebar shows real-time status updates during execution.

[ref-ai-summary]: /docs/explore-analyze/notifications#ai-summary

[ref-roles]: /admin/users-and-permissions/roles-and-permissions

[ref-notifications]: /docs/explore-analyze/notifications

[ref-user-groups]: /admin/users-and-permissions/user-groups


# Scheduled Tasks
Source: https://docs.cube.dev/docs/explore-analyze/scheduled-tasks

Save a natural-language agent prompt and have Cube run it automatically on a schedule, producing a chat thread for each run.

Scheduled Tasks let you run tasks on a schedule — or whenever you need them.
Save a natural-language prompt for the
[agent](/docs/explore-analyze/analytics-chat) and have Cube run it
automatically on a schedule or on demand. Each run produces a chat thread
you can open later to read the agent's answer. You can also ask the agent to create a
scheduled task for you from any of your chats.

For example, you might schedule a task to *"every weekday at 9am, summarize
yesterday's signups, flag anything anomalous, and email me the results"* and
review the summary each morning.

Scheduled Tasks are **scoped to a deployment** — each task belongs to the
deployment it was created in.

## Where to find it

In the deployment sidebar, open **Scheduled** (the clock icon, below
**Explore**). The page lists the deployment's tasks with their name,
schedule, status, and description, and is searchable.

## Anatomy of a task

A task has:

* **Name** (required) — how the task appears in the list.
* **Description** (optional) — a short summary shown in the list.
* **Instructions** (required) — the natural-language prompt the agent runs on
  each execution.
* **Schedule** — how often the task runs (see below).
* **Enabled** — a toggle to activate or pause a scheduled task.

## Schedule options

Scheduled Tasks use the same schedule editor as
[dashboard scheduled refresh](/docs/explore-analyze/scheduled-refreshes),
offering these frequencies:

* **Manual** — no schedule; the task runs only when you trigger it with
  **Run now**.
* **Hourly**, **Daily**, **Weekly** (with a day of the week), and **Monthly**
  (with a day of the month) — each with a time picker.
* **Custom** — a raw cron expression for full control.

A **timezone** selector (defaulting to your browser's timezone) controls when
the schedule fires; it is stored per task.

## Managing tasks

From the list, you can:

* **Create** a new task. The **New task** button is a dropdown with two
  options:
  * **Create with agent** — opens a new Analytics Chat pre-seeded with a
    message asking the agent to explain scheduled tasks and interview you
    about what the task should do and when it should run. The agent then
    creates the task for you (see
    [Managing tasks from chat](#managing-tasks-from-chat)).
  * **Set up manually** — opens the create dialog where you fill in the
    task's details yourself.
* **Edit** an existing task's instructions, schedule, or details.
* **Enable / Pause** a scheduled task to control whether it runs on schedule.
* **Run now** — trigger a one-off run immediately. This works for both manual
  and scheduled tasks. Triggering a run shows a notification with a **View**
  link straight to the run's chat thread, and the thread appears in the
  Recent Chats sidebar immediately.
* **Delete** a task. Deleting removes its schedule and stops all future runs.

## Task detail page

Clicking a task in the list opens its detail page. The header shows a
breadcrumb back to Scheduled Tasks, the task name, a status tag (**Manual**,
**Active**, or **Paused**), and the description, along with actions to
**Edit** (pencil), **Delete** (trash), and a primary **Run now** button.

The page shows:

* **History** — the task's runs, newest first. Each entry is a timestamped
  link that opens that run's chat thread. Currently-executing runs
  show a **Running** tag, and failed runs a **Failed** tag. The list shows
  the latest 50 runs; a "Showing the latest 50 runs" note appears once the
  cap is hit.
* **Instructions** — the task's prompt.
* **Repeats** — the schedule in plain language.

## Reading the output

Each run creates a chat thread containing the agent's response. Open the
thread in [Analytics Chat](/docs/explore-analyze/analytics-chat) to read the
full answer, ask follow-up questions, or
[save results to a Workbook](/docs/explore-analyze/workbooks).
Scheduled-run threads are marked in the Recent Chats sidebar with a clock
icon (hover over it to see the "Scheduled task" tooltip).

A run shows as **Running** while it executes, then completes or fails. A
failed run's thread shows a failure notice instead of an empty thread.

The task runs headlessly under the security context of the user who created
it, so it sees exactly the data that user can access.

### What the agent can do in a scheduled run

Beyond querying the semantic model, the agent in a scheduled run can:

* **Send email to workspace members** — for example, *"summarize yesterday's
  signups and email the summary to me."* This requires the agent email tool
  to be enabled for the workspace; recipients are restricted to workspace
  members.
* **Use web search**.
* **Create and update reports, workbooks, and dashboards**, using the task
  creator's permissions.

Scheduled runs do not yet have data-model access — editing the semantic
layer is currently available only in interactive chat.

## Managing tasks from chat

You can also create and manage Scheduled Tasks conversationally in
[Analytics Chat](/docs/explore-analyze/analytics-chat) — from any chat, not
just ones started with **Create with agent** (that menu option simply opens
a chat pre-seeded for this flow). Ask the agent to schedule, update, list,
or delete tasks in plain language — for example, *"schedule a daily summary
of yesterday's signups at 9am"* or *"list my scheduled tasks."*

The agent's actions render in the chat as labeled steps with a clock icon —
*"Creating scheduled task…"* / *"Created scheduled task"*, *"Listed
scheduled tasks"*, *"Updated scheduled task"*, and *"Deleted scheduled
task"*.

The agent manages task definitions: when listing tasks, it can report each
task's id, name, description, schedule, timezone, and enabled state. A
task's run history lives on its [detail page](#task-detail-page).


# Agent skills
Source: https://docs.cube.dev/docs/explore-analyze/skills

Run saved agent workflows using skill buttons, the slash menu, or automatic matching.

Skills are reusable, named workflows the agent can run on demand wherever you work with
it — [Analytics Chat](/docs/explore-analyze/analytics-chat), Workbooks, dashboards, and
the IDE. Instead of re-typing the same multi-step request every time, you pick a skill and
the agent follows the workflow your team has already defined — for example, a
**Weekly revenue report** that totals revenue, breaks it down by region, and calls out
week-over-week trends.

Skills are authored by your data team as part of the semantic model. This page covers how
to find and run them. To create skills, see [Skills](/admin/ai/skills) in the agent
configuration docs.

This page covers **Agent Skills in Cube**. These are not
[Cube agent skills](/docs/integrations/agent-skills), which run in a coding agent and
operate Cube through the CLI, or the [Cube connector](/docs/integrations/mcp-server),
which connects Claude and other MCP clients directly to Cube.

<Frame>
  <img alt="The slash menu in Analytics Chat listing available agent skills, each with a title and description" />
</Frame>

## Running a skill

There are three ways to run a skill from the chat input.

<Steps>
  <Step title="Skill buttons">
    When skills are available, they appear as buttons in the chat empty state — one button
    per skill, labeled with the skill's title. Click a button to start the skill.
  </Step>

  <Step title="Slash menu">
    Type `/` in the chat input to open the skill menu. The menu filters as you type and is
    keyboard-navigable. When skills are available, the input placeholder reads
    **"Type / for skills."**
  </Step>

  <Step title="Automatic matching">
    You don't always have to pick a skill explicitly. If a free-text request matches a
    skill's description, the agent recognizes the intent and runs the matching skill on
    its own — asking "can I get the weekly revenue summary?" may trigger a weekly revenue
    report skill.
  </Step>
</Steps>

## Adding context before you run

Picking a skill — whether from a button or the `/` menu — does **not** send the message
immediately. Instead, it inserts a styled `/skill-name` token into the chat input and
keeps your cursor there.

This lets you add specifics before running. Type any extra context after the token, then
send. On send, the message becomes the skill invocation plus whatever you added. For
example:

```text theme={"dark"}
/weekly-revenue-report for EMEA, last 6 weeks
```

runs the weekly revenue report skill, scoped to the EMEA region over the last six weeks.

<Note>
  Running skills is available to anyone with chat access, including **Explorer** and
  **Viewer** [roles](/admin/users-and-permissions/roles-and-permissions). Authoring skills
  requires data-model edit access — see [Skills](/admin/ai/skills) in the agent
  configuration docs.
</Note>


# Calculated fields
Source: https://docs.cube.dev/docs/explore-analyze/workbooks/calculated-fields

Create ad-hoc custom dimensions and measures with Semantic SQL in workbooks, with help from AI or the field picker.

Calculated fields are ad-hoc dimensions and measures you add only to the current
workbook report. They do not change the shared data model.

As described in [Semantic SQL](/docs/introduction#semantic-sql), Cube routes
analysis through the semantic layer instead of sending arbitrary SQL straight to
the warehouse. The runtime validates every request and applies your security
policies. Semantic SQL builds on Postgres-compatible SQL—including the
`MEASURE()` function—so you can express derived logic on top of existing
semantic definitions with both flexibility and governance.

Calculated fields are expressed as Semantic SQL and pushed down to the Cube
backend for evaluation. The semantic layer compiles them with the rest of the
query—rather than applying them only in the browser—so the same validation,
governance, and warehouse execution path apply as for any other Semantic SQL
analysis.

## Using AI to create calculated fields

You can ask the Cube AI agent to create custom calculations in natural language.
The agent can add or refine calculated fields from different parts of the
product—for example while exploring in **Analytics chat** or working in
**Workbooks**—so you are not limited to a single entry point when you want a new
metric or dimension for the analysis in front of you.

## Creating calculated fields in UI

You can also build and edit calculated fields directly in the workbook. New
fields appear in the **Query fields** section of the field picker sidebar.

### Aggregations from existing dimensions

Right-click a dimension column header and choose an aggregation to create a
calculated field automatically. Available aggregations depend on the column type:

| Column type     | Available aggregations                 |
| --------------- | -------------------------------------- |
| Number          | Count Distinct, Sum, Average, Min, Max |
| Time            | Count Distinct, Min, Max               |
| String, Boolean | Count Distinct                         |

### Calculations from existing measures

Open the menu on a measure column header and use the **Calculations** submenu
for derived calculations:

| Calculation            | Description                                             |
| ---------------------- | ------------------------------------------------------- |
| % of total             | Ratio of the measure value to the total across all rows |
| % of previous          | Ratio of the measure value to the previous row's value  |
| % change from previous | Percentage change compared to the previous row          |
| Running total          | Cumulative sum of the measure across rows               |

<Info>
  **% of previous**, **% change from previous**, and **Running total** require at
  least one dimension in the query.
</Info>

Which calculations are offered depends on the measure’s aggregation type:

| Aggregation type        | Available calculations |
| ----------------------- | ---------------------- |
| Count, Sum              | All calculations       |
| Min, Max                | Running total          |
| Average, Count Distinct | None                   |

### Filtered measures

When working with query **Results**, pivot so at least one dimension is on
columns, then open the header menu on a **pivoted measure column** and choose
**Create filtered measure**. Cube adds a calculated measure that applies the
column’s slice—for example, from **Count** broken down by **Status**, you get a
measure that only aggregates rows matching that status (such as completed
orders only).

The option appears only for **native** measures on pivoted columns, not for
calculated fields. The same flow works in **Explore** when results are pivoted
the same way.

### Bins and value groups

You can also bucket an existing dimension without writing SQL. Open its menu in
the field picker sidebar and choose **Create bins…** on a number dimension, or
**Group values…** on a string or boolean one (grouping a boolean dimension is
how you rename its `true`/`false` values). Time dimensions have granularities
instead, and an already derived field cannot be bucketed again.

<Frame>
  <img alt="The Create bins panel on a number dimension, showing typed boundaries, the label styles, a preview of the five buckets, and the generated Semantic SQL" />
</Frame>

**Bins** take their boundaries either as a list (**Custom ranges**) or from a
**Range start** and **Range end** (**Equal intervals**), which are prefilled
from the column's own minimum and maximum. For equal intervals, choose whether
the range is split by **Number of bins** or by a fixed **Bin size**. Each
boundary opens a bucket that includes its lower bound and excludes the upper
one, and two open-ended buckets are added at the edges—so `0, 18, 25` yields
`< 0`, `[0, 18)`, `[18, 25)`, `>= 25`, and no row is dropped. **Label style**
renders a bucket as `[10, 20)`, `>= 10 and < 20`, `10 to 19` (offered only while
every boundary is a whole number), or **Custom**, which lets you type your own
label for each bucket. Turn off **Label empty values separately** to fold rows
where the dimension is `NULL` into the last bucket instead of reporting them
under their own label (`Unknown` by default).

**Value groups** collect the dimension's values into named sets: pick values, name
the group, and choose **Add group**. A value belongs to one group at a time, and
an existing group's picked values can be changed later via **Edit group**. By
default, whatever you did not pick—including empty values—falls under
**Everything else**, which defaults to `Other`; turn off **Group remaining
values** to have those rows return `NULL` instead.

Bucket labels carry their position as a prefix (`1.`, `2.`, zero-padded past nine
buckets) so that sorting the column sorts it by value rather than alphabetically,
which would put `>= 25` before `[0, 18)`. The prefix is visible in results, chart
legends, and axes.

<Frame>
  <img alt="A workbook result grouped by the bucketed field: one row per bucket, with the created field listed under Query fields in the sidebar" />
</Frame>

The panel previews the Semantic SQL it generates as you build:

```sql theme={"dark"}
CASE WHEN orders_view.age IS NULL THEN 'Unknown'
  WHEN orders_view.age < 0 THEN '1. < 0'
  WHEN orders_view.age < 18 THEN '2. [0, 18)'
  ELSE '3. >= 18' END
```

<Info>
  **Equal intervals** ranges are resolved into boundaries when the field is created, not
  recomputed from the data. Values arriving later outside the range join the first
  and last buckets instead of extending them.
</Info>

To change a bucketed field, choose **Edit bins…** or **Edit groups…** from its
menu—either in the sidebar or on its column header in the results. Only fields
this panel generated offer the action; a `CASE` expression written by hand does
not.

### Editing a calculated field

Select a calculated field in the sidebar to open the editor. You can change its
**name** and **SQL expression**, then choose **Update** to apply.


# Workbooks
Source: https://docs.cube.dev/docs/explore-analyze/workbooks/index

Build reports and explore data with AI agents, organize analyses across multiple tabs, and share trusted insights with your team.

Workbooks allow you to build reports and explore data with AI agents, organize the results of your
analysis, and share trusted insights with your team.

A report inside a workbook and a standalone [exploration](/docs/explore-analyze/explore#saving-explorations)
are the same kind of object — the only difference is whether it's filed inside a workbook.

## Tabs

Workbooks can contain one or more tabs, each providing a different way to query and analyze your data. Tabs enable you to organize multiple analyses within a single workbook, making it easy to explore different aspects of your data or combine insights from different sources.

## New tab page

When you open [Explore](/docs/explore-analyze/explore) or add a new tab in a workbook, Cube shows
the **new tab page** — a single launchpad for starting a report. From here you can search across
your data model, browse starting points by type, or jump straight to pasting a query or asking an
AI agent.

### Searching and browsing

A search box sits at the top of the launchpad. Typing filters every category at once; categories
with no matches appear disabled, so you can tell at a glance which ones hold results.

The category selector lets you switch between starting-point types:

* **View groups** — browse [view groups](/docs/data-modeling/view-groups) as folders. Drilling
  into a group reveals its sub-groups and views.
* **Views** — every [view](/docs/data-modeling/views) in the model. Search also matches a view's
  measures and dimensions; when a view matches through a member, the row notes which one.
* **Workbooks** — drill into an existing workbook and pick one of its reports to reuse its query
  as the starting point for the new report. The workbook you are currently in and empty tabs
  (which have no query to reuse) appear disabled.
* **Source tables** — raw tables from your connected
  [data sources](/admin/connect-to-data/data-sources), browsable by data source and schema.

Click through the list to drill down to an individual view, report, or table. Once you reach a
starting point, the data model sidebar activates so you can continue building your query there.

### Starting from a pasted query or an agent

The launchpad also offers shortcuts at the bottom:

* **Paste semantic SQL query** — opens the SQL panel so you can paste a semantic SQL query. The
  dropdown adds **Paste source SQL query** (raw data-source SQL), **Paste JSON query** (a
  [REST API query](/reference/core-data-apis/rest-api/query-format)), and **Paste GraphQL query** (a
  [GraphQL API query](/reference/core-data-apis/graphql-api)) — the JSON and GraphQL queries are
  converted to a semantic query for you.
* **Ask Cube agent** — opens the chat sidebar so you can describe the report you want in natural
  language.

### Configuring the launchpad

Administrators can tailor the launchpad per deployment under **Settings → Configuration**, in the
**Workbooks and Explore** section. Two settings are available.

**Available tabs** — choose which categories appear on the launchpad. **View groups** and **Views**
are always shown and cannot be turned off; **Workbooks** and **Source tables** can each be enabled
or disabled to simplify the starting points your users see.

**Default view group** — set a default view group so the launchpad opens inside a specific
top-level view group instead of listing all of them, useful for steering users toward a curated set
of governed starting points.

<Steps>
  <Step title="Open deployment settings">
    Go to **Settings → Configuration** for your deployment.
  </Step>

  <Step title="Choose the available tabs and default group">
    In the **Workbooks and Explore** section, select the tabs to show and, optionally, enter the
    **name** of the view group the launchpad should open inside. Leave the group empty to show all
    view groups. Save your changes.
  </Step>
</Steps>

When a default view group is set, new Explore and workbook tabs open inside that group. You can
still navigate up to **All view groups** to browse everything. If the configured group no longer
exists, the launchpad falls back to showing all categories.

## Tab types

Workbooks support two types of tabs, each designed for different querying approaches:

### Semantic Query

[Semantic Query tabs](/docs/explore-analyze/workbooks/querying-data) allow you to query your data model through the semantic layer. This ensures all queries use consistent metrics, respect access control policies, and benefit from pre-aggregations for fast performance.

You can query the semantic layer in three ways:

* **Point and click** – Use the intuitive interface to select measures and dimensions, build visualizations, and explore your data interactively
* **AI agent** – Ask the AI agent to build queries and visualizations based on natural language questions
* **Semantic SQL** – Write Semantic SQL queries manually to have full control over your queries while still leveraging the semantic layer

### Source SQL Query

[Source SQL Query tabs](/docs/explore-analyze/workbooks/source-sql-tabs) allow you to query your connected data sources directly, bypassing the semantic layer. This gives you direct access to your raw data and enables deeper exploration beyond what's defined in your data model.

You can query source SQL in two ways:

* **Write SQL manually** – Write standard SQL queries directly against your data source for maximum flexibility
* **Ask AI** – Use the AI agent to help you research your data source, build SQL queries, and refine results in real-time

## Copying and pasting tabs

You can copy a tab from one workbook and paste it into another workbook
using the clipboard.

### Copying a tab

Open the tab options menu (the chevron on the tab in the footer) and
select **Copy to Clipboard**. The tab's query, chart configuration, and
settings are serialized and written to your system clipboard.

### Pasting a tab

Navigate to the target workbook and press **Cmd+V** (macOS) or
**Ctrl+V** (Windows/Linux) while the workbook is focused. A new tab will
be created with the query and configuration from the clipboard.

<Info>
  Paste only works via the keyboard shortcut. Make sure the focus is not
  inside a text input—otherwise the browser's default paste behavior will
  take precedence.
</Info>

You can also copy an exploration from [Explore](/docs/explore-analyze/explore)
and paste it as a new tab in any workbook using the same workflow.

## Duplicating workbooks

You can duplicate a workbook by selecting **Duplicate** from the row
actions menu on the workspace page, from the workbook menu while the
workbook is open, or from a published dashboard's options menu. This
creates a full copy of the workbook, including all its tabs, reports, and
any published dashboard.

A duplicate does not carry the original's sharing over by default. The
copy is visible only to you, plus anyone with access to the folder it is
created in.

If the original is shared — with people, with groups, with your whole
organization, or through signed embedding — the duplicate dialog offers
**Copy sharing and embedding settings**. Selecting it gives the copy the
same audience. The option appears only if you have **Full access** to the
original, since copying its sharing means granting that access again. See
[Duplicates][ref-sharing-duplicates] for what does and doesn't carry over.

## Workbook versions

When you [publish a dashboard][ref-dashboards] from a workbook, Cube
automatically creates a version snapshot. Each time you publish, a new
version is recorded so you can track changes to your dashboard over time.

### Restoring a version

You can restore the state of your workbook from any previously published
dashboard version. Restoring a version rebuilds the workbook with the
charts and configuration from that published snapshot.

<Warning>
  Restoring a version replaces **all existing tabs** in the workbook with
  the tabs from the selected version. Any current work in the workbook that
  has not been published will be lost.
</Warning>

[ref-dashboards]: /docs/explore-analyze/dashboards

[ref-sharing-duplicates]: /docs/organize-content/sharing#duplicates


# Python analysis
Source: https://docs.cube.dev/docs/explore-analyze/workbooks/python-analysis

Attach a Python script to a workbook report or exploration to run forecasting, regression, cohort, and other analysis that SQL can't express.

<Warning>
  Python analysis is currently in preview, and the user experience and the script
  contract may still change. Reach out to the [Cube support
  team](/admin/account-billing/support) to activate this feature for your account.
</Warning>

A workbook report or exploration can carry an attached **Python script** that
transforms its SQL result. Its chart then renders the script's **output** instead
of the raw SQL rows. This turns an analysis that would otherwise scroll away in a
chat transcript into a saved, re-runnable, shareable analysis.

Use it for work SQL can't express — forecasting, regression, cohort analysis,
statistical tests, clustering, and anomaly detection.

<Frame>
  <img alt="A workbook report with the Python code panel open, showing a Prophet forecast script above a chart plotting actual monthly orders alongside the forecast and its confidence interval" />
</Frame>

## Adding Python to a workbook report or exploration

### From Analytics Chat

Ask for the analysis in natural language — "forecast next quarter's revenue",
"find anomalies in signups" — and the agent runs Python for you, rendering the
result inline in the [chat thread](/docs/explore-analyze/analytics-chat). This
result is ephemeral by default.

Ask to **save it** — to a workbook, or as a standalone
[exploration](/docs/explore-analyze/explore#saving-explorations) — and Cube persists
both the code and the run result. Opening the saved copy renders that output without
re-running; saving re-executes the analysis.

<Info>
  The agent reaches for Python **only** when the answer genuinely needs a statistics
  or machine-learning library. Ordinary aggregations, top-N, ratios, running totals,
  period-over-period comparisons, and time series all stay in SQL, because a Python
  run costs a re-query plus a sandbox start. If you expected Python and got a plain
  SQL query, that is usually correct behavior.
</Info>

### From the toolbar

Workbooks and [Explore](/docs/explore-analyze/explore) share the same flow.

Click **Python** in the toolbar to open the Python panel, then **Add script** to
attach one. Cube seeds a starter script and opens it on the **Script** tab.
Opening the panel does not attach anything by itself — only **Add script** does.

**Remove**, in the panel header, detaches the script, after which the analysis is
SQL-backed again.

Attaching Python clears any existing SQL result: a Python-backed analysis renders
its last Python run, and a freshly attached script has none until you press **Run**.

Attaching Python in Explore is only available on a **saved** exploration. On an
unsaved one the **Python** button is disabled with the tooltip *"Save the
exploration to add Python"* — **Run** executes server-persisted code, so the
analysis needs a saved exploration to live on.

## Writing the script

The script runs in a sandbox against a fixed contract:

* Input data arrives as `data.csv` in the working directory.
* Write results to `output.json` as a **flat JSON array of row objects**, for
  example `[{"month": "2026-01", "value": 1.5}, ...]`.

A top-level dict or object is rejected — flatten any nested structure into one
array of uniform rows.

## Python environment

Every run gets a fresh, isolated sandbox running **Python 3.11**. It is created for
the run and destroyed when the run finishes — nothing carries over between runs.

These packages are pre-installed, along with their dependencies:

| Package                           | Use                                                       |
| --------------------------------- | --------------------------------------------------------- |
| `pandas`, `numpy`                 | Dataframes and numerical computing                        |
| `scipy`                           | Statistical tests, optimization, interpolation            |
| `scikit-learn`                    | Regression, classification, clustering, anomaly detection |
| `statsmodels`                     | ARIMA, exponential smoothing, econometric models          |
| `prophet`                         | Time series forecasting with seasonality and holidays     |
| `matplotlib`, `seaborn`, `plotly` | Plotting                                                  |

Figures are not a supported output. The chart is built from `output.json`, and
anything a script writes to disk is discarded with the sandbox — so the plotting
libraries are importable, but a saved figure has nowhere to go.

<Info>
  Installing your own packages is not supported yet. Because the sandbox is recreated
  for every run, anything a script installs is discarded when the run ends. Support for
  adding packages to the environment is coming.
</Info>

## Running and refreshing

The panel's **Script** tab is editable in place, with line numbers. **Reset**
restores the starter template.

* **Edits do not run anything.** They save with the analysis, and the rendered result
  keeps showing the previous run.
* When the code or its input SQL has changed since the last run, the result is
  marked **Outdated**, with the tooltip *"The Python code or its input SQL changed
  after the last run. Run to refresh the saved result."*
* **Run** executes the stored script in the sandbox and persists the refreshed
  result.
* The **Output** tab shows what the last run printed — the script's stdout and
  stderr, so `print()` is how you inspect intermediate values. Both are captured up
  to the cap in [Limits](#limits), so a chatty script gets truncated.
* The **input SQL panel is read-only** on a Python-backed analysis: that SQL is the
  sandbox's input, not what gets charted. It still offers the **Semantic SQL** and
  **Generated SQL** tabs, both derived from that input query.
* **A failed run keeps the previous chart.** The error surfaces alongside the last
  successful result, which stays rendered.

**Run is the only way the saved result changes.** Opening the workbook report or
exploration, reloading the page, or viewing a dashboard never re-runs anything on
its own.

## On dashboards

Python-backed workbook reports render their **saved output** on dashboards.
Nothing re-runs on dashboard load, so a dashboard full of Python reports costs
no compute to open — each widget shows whatever the last **Run** produced.

A python widget can be opened in [Explore](/docs/explore-analyze/explore) from a
dashboard and run from there.

## Who the analysis runs as

<Warning>
  Python runs with the **security context of the person who pressed Run** — or of the
  chat user who saved the analysis. The result is then persisted with the workbook
  report or exploration, and **anyone who can view that item can see the result**.

  Row-level security is applied at **run time**, not at view time. A user with broad
  access can Run, and the stored output is then readable by people whose own access
  is narrower.
</Warning>

Take this into account when deciding who can run Python analyses or publish Python
reports, the same way you would for any other shared saved result.

## Limits

| Limit                         | Value  |
| ----------------------------- | ------ |
| SQL query timeout             | 120s   |
| Python execution timeout      | 120s   |
| Maximum output rows persisted | 10,000 |
| Maximum output size           | 2 MB   |
| stdout/stderr captured        | 16 KB  |

Exceeding the output caps means the analysis still returns in chat but **cannot be
saved to a workbook report or exploration**. Aggregate or summarize inside the
script so the output stays within the caps — analysis results such as forecasts,
cohorts, and test statistics are small by nature.

## Learn more

* [Analytics Chat](/docs/explore-analyze/analytics-chat) — the standalone
  conversational analytics experience
* [Workbook Agent](/docs/explore-analyze/workbooks/workbook-agent) — the authoring
  assistant inside a workbook
* [Source SQL tabs](/docs/explore-analyze/workbooks/source-sql-tabs) — query
  connected data sources directly


# Querying data
Source: https://docs.cube.dev/docs/explore-analyze/workbooks/querying-data

In the Semantic Query tab, you can query the semantic layer. On the left, there is a selector for the semantic view that you want to query.

<Frame>
  <img />
</Frame>

On the left side, you can select a semantic view you would like to query. Inside the semantic view, you can see the measures and dimensions grouped either by cubes or folders. You can search within your semantic view to find the relevant member.

## Running queries

As you build a query — adding members, changing filters, adjusting sorting —
the workbook runs it automatically and refreshes the results. You can turn
this off with the auto-run toggle in the query controls: with auto-run
disabled, the results are marked as outdated while you edit the query, and
the query only runs when you click **Run query**. The toggle applies to the
current tab only.

A data model author can change the default for a semantic view with the
[`meta.auto_run`][ref-auto-run] parameter — selecting a view with
`auto_run: false` starts the tab with auto-run disabled. This is useful for
views that are expensive to query. You can still toggle auto-run back on at
any time.

An admin can also turn auto-run off by default for every tab in the
deployment, from **Model Configuration**. Per-view and per-tab settings still
take precedence over this deployment-wide default. See
[Auto-run][ref-configuration-auto-run] in the Model Configuration reference.

When a cell's value is too long for its column, it is truncated with an
ellipsis. Hover over a truncated cell to see its full value in a tooltip.

## Filtering

Dimensions and measures can be added as filters to focus on specific rows of
data. Pick **Filter** in a member's menu in the left pane, or in a result
column's menu, to add the first one. The filter bar then appears above the
results, with a **Filter** button for adding more — you can filter on any member
of the semantic view, whether or not the query selects it.

Every filter is a chip showing its member, operator and value. Click the chip
to edit it, or use its options menu to remove it. A filter added without a
value yet is highlighted and left out of the query; the query runs as soon as
the value is complete.

Filtering a dimension keeps or drops rows before aggregation, as a SQL `WHERE`
condition. Filtering a measure applies after aggregation, as a `HAVING`
condition — so `revenue greater than 1000` keeps groups whose total exceeds
1000, not individual orders.

### Operators

The operators offered depend on the member's data type, for measures as much as
for dimensions:

| Data type | Operators                                                                                                                                                                             |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| String    | is, is not, contains, not contains, starts with, not starts with, ends with, not ends with, is null, is not null, is empty, is not empty                                              |
| Number    | is, is not, greater than, greater than or equal, less than, less than or equal, between, is null, is not null                                                                         |
| Time      | is, is not, after, after or on, before, before or on, between, in the month, not in the month, in the quarter, not in the quarter, in the year, not in the year, is null, is not null |
| Boolean   | is, is not, is null, is not null                                                                                                                                                      |

On a number member the comparisons appear on the chip as `=`, `≠`, `>`, `≥`,
`<` and `≤`.

### Values

* **is** and **is not** accept several values, matching any of them. On a string
  member the value picker lists the member's own values and searches them
  server-side, so you select from what the data actually contains.
* The **contains**, **starts with** and **ends with** family matches a
  substring, prefix or suffix, ignoring case.
* **between** includes both bounds.
* **is null**, **is not null**, **is empty** and **is not empty** take no value.
  Empty means the empty string, which is not the same as null.
* The period operators take any date inside the period — **in the year** with
  `2026-03-14` matches all of 2026.
* A date value can be fixed or relative. The date editor's **Relative** tab
  takes values like `today`, `7 days ago`, `this month` or `2 weeks from now`,
  and resolves them every time the query runs, so the window rolls forward on
  its own. The full list is under
  [`default_ui_filters`][ref-default-ui-filters].

### Combining filters

Filters in the bar are combined with AND: every one of them must hold. For OR,
and for anything nested, use **Add advanced filter** in the filter picker's
footer. It creates a group, shown as its own chip, whose operator sits as a
toggle between the filters inside it — click it to switch the whole group
between AND and OR. Groups can contain groups, which is how an expression like
`status is completed AND (country is US OR city contains San)` is built.

A group holds either dimension filters or measure filters, never both, because
the two apply at different stages of the query. Its **Filter** button therefore
offers only the kind of member the group already contains.

### Custom SQL filters

**Add custom SQL**, also in the filter picker's footer, takes a SQL condition
and passes it into the query as written. Use it for a condition the operators
above cannot express.

### Default filters

A data model author can define default workbook filters on a semantic view with
the [`meta.default_ui_filters`][ref-default-ui-filters] parameter. The same
defaults are also seeded when a query on that view is started in the Google
Sheets / Excel add-in.

```yaml theme={"dark"}
views:
  - name: orders_view

    cubes:
      - join_path: orders
        includes: "*"

    meta:
      default_ui_filters:
        - member: created_at
          operator: between
          values: ["7 days ago", "today"]
        - member: status
          operator: is
          values: ["completed"]
```

When you select such a view in a new tab, those filters are added to the query
automatically. They behave exactly like filters you add yourself: you can
change their values, switch operators, or remove them.

Date range filters can use relative bounds like `7 days ago` or `this month`.
A relative range resolves each time the query runs, so the window rolls
forward day over day, and the filter's date editor opens on the **Relative**
tab showing its bounds. See
[`default_ui_filters`][ref-default-ui-filters] for the full list of accepted
operators and values.

Resetting the tab or going back to the view list clears default filters
along with the rest of the query; they are seeded again the next time you
select a view.

## Pivoting

You can add dimensions to the pivot by right-clicking on the left pane or in the results header.

Note that chart tables are different from results tables. You can configure pivots in chart tables separately.

## Totals

The totals menu (the **Σ** button) in the results toolbar adds summary rows
and columns to the results table: **Column Totals** (a pinned row at the
bottom with a total for each measure column), **Row Totals** (a total for
each row across the pivoted columns), and **Subtotals** (see below). All
three can be enabled at once; each setting is saved with the report and
carries over when you switch the chart type to [Table][ref-table-chart].

### Subtotals

When the table is [pivoted](#pivoting) by two or more dimensions,
**Subtotals** appends a bold **Total for ‹value›** column after each pivot
group's columns, at every nesting level — for example, pivoting by year and
then status adds a **Total for 2024** column after 2024's status columns.
With fewer than two pivot dimensions the menu item is disabled, and if the
query changes so the pivot no longer qualifies, subtotals switch off
automatically.

<Frame>
  <img alt="Pivoted results table with subtotal columns" />
</Frame>

Subtotal values are computed by the database — one extra query per pivot
level — rather than by summing the visible cells, so they are correct for
non-additive measures such as counts of distinct values and averages, and
when the [row limit](#limiting) truncates the table. With **Column Totals**
also enabled, the pinned totals row shows a grand total for each pivot group.

<Note>
  * The toggle adds subtotals for all pivot levels at once; there is no
    per-group control.
  * Subtotals are not available for flat (non-pivoted) tables or in the
    [values-as-rows table layout](/docs/explore-analyze/charts/chart-types/table#pivot-presets).
  * [Calculations][ref-calculated-fields] based on window functions, such as
    **Running total**, are excluded — same as for row and column totals.
</Note>

## Limiting

Every query in a workbook returns at most a fixed number of rows. By
default, queries are limited to **5,000 rows**, and you can adjust the
limit up to **50,000 rows** from the query controls.

The default and maximum values available in the workbook are governed by
the deployment's [Model Configuration][ref-configuration]:

* **Default row limit** is applied when a query doesn't specify one
  explicitly.
* **Maximum row limit** is the upper bound — any value you pick in the
  workbook is capped at this number.

Updating those settings at the deployment level changes what every
workbook in the deployment can request.

<Warning>
  Large result sets can slow down chart rendering and may hit browser
  memory limits, especially for tables. When possible, aggregate in the
  semantic layer instead of pulling raw rows into the workbook.
</Warning>

## Sorting

You can sort query results using drop-down menus on column headers in the results table or the
dedicated sorting control.

### Column headers

Hover over a column header in the results table and expand the context menu to sort ascending, sort descending, or clear sorting.
If a column has sorting applied, a chevron icon on the header indicates the current sorting direction.

### Sorting control

The sorting control, available via the **Sort** button, lists all query members and their current state:
unsorted, sorted ascending, or sorted descending. Use it to apply or
change the sort order for any member. Drag and drop members within the sorting control to change their priority in the sort order.

<Frame>
  <img />
</Frame>

When a [pivot](#pivoting) is applied, an additional section with pivot dimensions appears.

## Filling in missing rows

A time-series query only returns rows for date buckets that actually contain
data. If no orders were created in a given month, that month is simply absent
from the result — which reads as a misleading gap in tables and charts. Fill
in missing rows densifies the result so every date bucket in the range is
present.

To apply it, hover over the header of a time dimension column in the results
table, expand the context menu, and select **Fill in missing rows**. To turn
it off, select **Stop filling missing rows** from the same menu. While the
fill is active, an icon on the column header indicates it.

<Frame>
  <img alt="Results table column menu with the Fill in missing rows action" />
</Frame>

The fill works on time dimensions with a year, quarter, month, week, or day
granularity. The date range comes from the date filters on that dimension, or
from the earliest and latest dates in the data. In added rows, additive
measures such as counts and sums are set to `0`; other measures are left
empty.

The fill doesn't change the query or the generated SQL — the missing rows are
added when the report is rendered. It is saved with the report and applies
everywhere it appears, including [dashboards][ref-dashboards].

<Info>
  The fill is skipped when it would produce more than 10,000 rows. When that
  happens, the column header indicator warns you.
</Info>

## Period-over-period comparison

You can compare any measure against a prior period — for example, month over
month or year over year. Hover over the header of a measure column in the
results table, expand the context menu, and pick a comparison under
**Compare periods**. The same menu on a time dimension column header applies
the comparison to all measures at once.

<Frame>
  <img alt="Results table with period comparison columns" />
</Frame>

The menu is available when the query includes a time dimension with a year,
quarter, month, week, or day granularity. The presets depend on that
granularity — a month grain offers **Previous period**, **Same period
previous quarter**, and **Same period previous year** — so the comparison
period always aligns exactly with the current buckets. A measure can have
several comparisons active at once, such as month over month and year over
year side by side.

Each comparison adds derived columns next to the measure. Choose which ones
to show under **Comparison columns** in the same menu:

* **Previous value** (on by default) — the measure's value in the comparison
  period
* **Difference** — the absolute change from the comparison period
* **% change** — the relative change from the comparison period

To remove a single derived column, use **Remove Column** in its header menu;
removing the last one turns the comparison off. You can also untoggle the
preset under **Compare periods**.

Comparisons are saved with the report and apply everywhere it appears —
charts, totals, and [dashboards][ref-dashboards]. Cube fetches the
comparison values with a companion query whose date filters are shifted back
by the comparison offset; you can [inspect it](#inspecting-queries) to check
the math.

## Inspecting queries

Every query in the Semantic Query tab can be inspected as code. Open the SQL panel via the **SQL** button in the toolbar, next to the Results and Chart tabs, to see the query that the workbook generates, switch between representations, and copy it for use elsewhere.

<Frame>
  <img />
</Frame>

The panel exposes two top-level tabs:

* **Semantic SQL** — the query expressed against the Semantic Model (semantic views, measures, dimensions, and `MEASURE()` calls). This is the source of truth for the query and what the workbook stores.
* **Generated SQL** — the SQL that Cube compiles from the Semantic SQL and sends to your data warehouse. Use it to understand exactly what runs against your database, debug performance, or share with a database administrator.

The **Semantic SQL** tab also has a dropdown for viewing the same query in the formats accepted by Cube's [Core Data APIs][ref-core-data-apis]:

* **Semantic JSON** — the [REST (JSON) API][ref-rest-api] query format
* **Semantic GraphQL** — the [GraphQL API][ref-graphql-api] query format

These views are convenient when you want to take a query you've built interactively in a workbook and reuse it directly through one of the Core Data APIs from your own application.

## Result freshness and provenance

Two indicators next to each result describe the data behind it.

* **Freshness** — a leaf icon shows how recently the underlying data was refreshed. Hover over it to see the last refresh time (for example, "Refreshed 5 minutes ago"); its color shifts as the data ages, so you can tell fresh from stale results at a glance. If the refresh time can't be determined, the leaf turns gray with a "Data age unknown" label. When you have access to [Query History](/admin/monitoring/query-history), clicking the leaf opens the underlying request for that result.
* **Pre-aggregation** — for those same users, a lightning-bolt icon appears next to the leaf with a "Served from a pre-aggregation" label whenever the result was served from a [pre-aggregation](/docs/pre-aggregations). If no icon is shown, the query ran directly against your data source.

## Editing Semantic SQL by hand

You can edit the Semantic SQL directly in the editor to refine a query — for example, to add a `WHERE` clause, change `GROUP BY` order, or apply a different sort. After making changes, click **Save and Run** to apply them to the query and refresh the results, or **Discard** to revert.

<Frame>
  <img />
</Frame>

When you save a hand-edited query, the workbook keeps the Semantic SQL as the source of truth, and the visual controls (members panel, sort, pivot) stay in sync with what's expressible in the UI. Anything that goes beyond the interactive controls — see [Advanced semantic queries](#advanced-semantic-queries) below — disables the affected UI controls but keeps the rest of the workbook fully functional.

## Advanced semantic queries

Advanced semantic queries typically can contain CTEs (Common Table Expressions) and unions, and can contain multiple semantic views. In many cases for advanced semantic queries, the interactive components of the UI would be disabled—not the whole UI—as these complex queries require manual SQL editing.

<Frame>
  <img />
</Frame>

<Info>
  Currently, advanced semantic queries can be placed on dashboards, but dashboard filters cannot be applied to advanced semantic queries.
</Info>

## Applying a security context

When you run a query—in a workbook, on a dashboard, or in [Explore][ref-explore]—Cube
generates a token to execute it against the semantic layer. If you have developer or
admin access, you can attach a [security context][ref-security-context] to that token
directly from the page you're working on. The values you provide are used when the
token is generated, overriding the claims that would otherwise come from your session.

The security context you set is also respected by [AI agents][ref-analytics-chat]:
any query an agent runs on your behalf—whether in the workbook or in the IDE—executes
under the same context. This lets you confirm an agent sees exactly the data a given
end user would.

### What you can override

* **Groups** — choose **Inherit** to keep the Cube Cloud groups resolved from your
  session, **Custom** to query as a specific set of groups, or **None** to query with
  no groups at all.
* **User attributes** — keep the attributes resolved from your session, or override
  them with your own values.

<Note>
  Setting a security context requires developer or admin access (deployment edit
  access). Overriding the Cube Cloud **groups** and **user attributes** specifically
  requires the admin role. Users without edit access always query with the security
  context derived from their own session.
</Note>

<Warning>
  You can't use a security context to impersonate another user. The `email` claim is
  never overridable—it's always taken from your own session—so you can't run queries on
  behalf of someone else.
</Warning>

This is primarily a testing tool. It lets you reproduce what a specific end user would
see and verify [access control][ref-access-control] and multitenancy behavior without
leaving Cube Cloud. It's especially useful when a query fails or returns no data
because the data model expects security context values that aren't present in your
session—you can supply them here and confirm the model (and any agent that queries it)
behaves as intended.

<video />

<video />

[ref-core-data-apis]: /reference/core-data-apis

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-graphql-api]: /reference/core-data-apis/graphql-api

[ref-configuration]: /docs/data-modeling/configuration

[ref-security-context]: /docs/data-modeling/access-control/context

[ref-access-control]: /docs/data-modeling/access-control

[ref-dashboards]: /docs/explore-analyze/dashboards

[ref-explore]: /docs/explore-analyze/explore

[ref-analytics-chat]: /docs/explore-analyze/analytics-chat

[ref-default-ui-filters]: /reference/data-modeling/view#default_ui_filters

[ref-table-chart]: /docs/explore-analyze/charts/chart-types/table

[ref-calculated-fields]: /docs/explore-analyze/workbooks/calculated-fields

[ref-auto-run]: /reference/data-modeling/view#auto_run

[ref-configuration-auto-run]: /docs/data-modeling/configuration#auto-run


# Source SQL Tabs
Source: https://docs.cube.dev/docs/explore-analyze/workbooks/source-sql-tabs

Run warehouse-native SQL inside Workbooks—by hand or with AI help—to explore raw tables before promoting logic into the semantic model.

Source SQL Query tabs allow you to query your connected data sources directly, bypassing the semantic layer. Source SQL Query tabs can be used for prototyping your calculations before they would go into the semantic layer.

<Frame>
  <img />
</Frame>

## Data sources

The data sources sidebar lists every source declared on the deployment —
both the default source and any named sources added under
[**Settings → Data Sources**](/admin/connect-to-data/multiple-data-sources).
Newly added sources show up immediately; you don't have to wire them into
a cube first.

## Querying methods

You can query source SQL in two ways:

* **Write SQL manually** – Write standard SQL queries directly against your data source for maximum flexibility
* **Ask AI** – Use the AI agent to help you research your data source, build SQL queries, and refine results in real-time


# Workbook Agent
Source: https://docs.cube.dev/docs/explore-analyze/workbooks/workbook-agent

Use the AI agent inside a workbook to build reports, create and edit dashboards, and run analysis with natural language.

Inside a [workbook][ref-workbooks], the AI agent is a full **authoring**
assistant. Where the read-only [Dashboard Agent][ref-dashboard-agent] only
answers questions about a published dashboard, the workbook agent can act on
your behalf — it builds reports, and assembles and edits dashboards, all from
plain-language requests.

<Note>
  **Workbook Agent vs. [Analytics Chat][ref-analytics-chat].** Analytics Chat is
  a standalone, chat-first analytics experience for asking questions and saving
  results into a workbook. The Workbook Agent lives **inside a workbook** and is
  oriented around authoring the workbook's own reports and dashboards. Both run
  read-only queries against your semantic model; the Workbook Agent additionally
  creates and edits workbook content.
</Note>

## What the Workbook Agent can do

In addition to everything the read-only [Dashboard Agent][ref-dashboard-agent]
can do (answer questions, run read-only semantic-layer queries, explain metric
and dimension definitions), the Workbook Agent can:

* **Create and save reports** in the workbook from a natural-language request
* **Search existing reports** to find and reuse work already in the workbook
* **Build and edit dashboards** — add and configure chart, KPI, filter,
  time-grain, and text widgets
* **Publish dashboards**

## How charts get added to a dashboard

When the agent adds a chart to a dashboard, the chart widget references a
**report in the workbook**, not a one-off query. So to put a new chart on a
dashboard, the agent first saves the query as a report in the workbook, then
adds a widget that points at that report. This keeps every dashboard chart
backed by a reusable, governed report.

## Getting help with Cube

While working in a workbook, you can also ask the agent questions about Cube
itself — it can answer using the Cube documentation, which is handy for
"how do I…" questions without leaving your analysis.

## Limitations

* **Report search covers published reports only.** When the agent searches for
  existing reports to reuse, it sees published reports.

## Learn more

* [Dashboard Agent][ref-dashboard-agent] — the read-only Q\&A assistant on
  published and embedded dashboards
* [Querying data in workbooks][ref-querying-data] — point-and-click, AI agent,
  and Semantic SQL
* [Analytics Chat][ref-analytics-chat] — the standalone conversational
  analytics experience

[ref-workbooks]: /docs/explore-analyze/workbooks

[ref-dashboard-agent]: /docs/explore-analyze/dashboards/dashboard-agent

[ref-analytics-chat]: /docs/explore-analyze/analytics-chat

[ref-querying-data]: /docs/explore-analyze/workbooks/querying-data


# Connect your data
Source: https://docs.cube.dev/docs/getting-started/connect-your-data

If you don't have a data source to connect to, you can create a demo deployment to test all Cube features with demo data.

<Info>
  If you don't have a data source to connect to, you can create a demo deployment to test all Cube features with demo data.
</Info>

Cube supports multiple warehouses and databases.

<Frame>
  <img />
</Frame>

Once you select your data source, follow the instructions on the connection page.

<Frame>
  <img alt="Cube Cloud Snowflake Configuration Screen" />
</Frame>

## AI builds initial semantic model

Select what tables you'd like to use in your initial semantic model and let AI build it.


# Create workbooks and dashboards
Source: https://docs.cube.dev/docs/getting-started/create-workbooks-and-dashboards

Workbooks are places to curate and organize your analysis. You can create multiple reports using tabs, each focusing on different aspects of your data.

## Create a new workbook

You can create a new workbook in two ways:

* Click the **New Workbook** button on the home page or on the workbooks page
* Open **Explore** from Analytics Chat, then convert that exploration into a workbook

## Organize analysis with tabs

Use tabs within a workbook to create different reports. Each tab can contain its own analysis, allowing you to explore various aspects of your data and organize multiple insights in one place. The AI agent can help you build analysis in workbook tabs, creating queries and visualizations based on your questions.

<Frame>
  <img />
</Frame>

## Share with dashboards

Once you're ready to share your work, you can turn workbooks into [dashboards][ref-dashboards] to organize reports into shareable artifacts. Dashboards let you select and organize reports from your workbooks into polished views for your team and stakeholders. The AI agent can help you create dashboards, manage layout, add filters, and more.

Dashboards can be published to make them accessible to your team. Published dashboards provide stakeholders with direct access to the insights that matter most.

[ref-dashboards]: /docs/explore-analyze/dashboards


# Develop in IDE
Source: https://docs.cube.dev/docs/getting-started/develop-in-ide

Use Cube Cloud IDE branch environments, commits, merges, and AI assistance to iterate on your data model without destabilizing production.

The IDE is a place to develop your data model. Cube supports multiple environments based on Git branches, helping you follow software engineering best practices while developing your data model.

## Branch-based development

Cube uses Git branches to create separate environments for development and production. This allows you to safely make changes to your data model without affecting your production environment. When you need to make a change, you can enter development mode or work on a separate branch to test and refine your changes. This isolation ensures that your production data model remains stable while you experiment and iterate.

<Frame>
  <img />
</Frame>

## Commit and push to production

When your changes are ready, you can commit and push them to your production branch. The IDE helps manage this entire process without requiring you to know how Git and version control work in detail. You can save changes, commit them, and merge into production—all from within the IDE interface.

## AI-assisted development

The IDE includes an AI agent that helps you create data models from scratch and make changes to existing data models. Simply describe what you want to build or modify, and the AI agent will assist you in implementing the changes.


# Embed analytics
Source: https://docs.cube.dev/docs/getting-started/embed-analytics

Ship agentic embedded analytics in your product — choose among iframe embeds, the conversational Chat API, or headless core APIs for full control.

Cube offers rich options for embedded analytics. You can embed [dashboards][ref-dashboards] and [analytics chat][ref-analytics-chat] as iframes, use the [Chat API][ref-chat-api] directly to create your own conversational analytics experience, or use [Core Data APIs][ref-core-apis] directly to build custom visualization, reporting, and dashboarding experiences.

## Embed with iframes

The simplest way to embed Cube content is using iframes. You can embed both dashboards and analytics chat directly into your applications. Cube supports two authentication methods for iframe embedding: [private embedding][ref-private-embedding] for internal use cases and [signed embedding][ref-signed-embedding] for customer-facing applications.

## Use the Chat API

For more control over the conversational analytics experience, you can use the [Analytics Chat API][ref-chat-api] directly. This API-first approach lets you programmatically integrate AI-powered conversations with your data into your applications, giving you full control over the user experience.

## Build custom experiences

If you want complete control over visualizations and user interfaces, you can use [Cube's core APIs][ref-core-apis]—including REST (JSON), GraphQL, and SQL APIs—directly. This headless approach enables you to build fully custom visualization, reporting, and dashboarding experiences tailored to your specific needs.

[ref-dashboards]: /docs/explore-analyze/dashboards

[ref-analytics-chat]: /docs/explore-analyze/analytics-chat

[ref-chat-api]: /reference/embed-apis/chat-api

[ref-core-apis]: /reference/core-data-apis

[ref-private-embedding]: /embedding/iframe/auth/private

[ref-signed-embedding]: /embedding/iframe/auth/signed


# Import a Bitbucket repository
Source: https://docs.cube.dev/docs/getting-started/migrate-from-core/import-bitbucket-repository-via-ssh

Onboard an existing Cube project by linking a Bitbucket repository over SSH in Cube Cloud and completing database connectivity.

This guide walks you through setting up Cube Cloud, importing a
[Bitbucket][bitbucket] repository with an existing Cube project via SSH, and
connecting to your database.

## Step 1: Create an account

Navigate to [cubecloud.dev](https://cubecloud.dev/), and create a new Cube Cloud
account.

## Step 2: Create a new Deployment

Click **Create Deployment**. This is the first step in the deployment
creation. Give it a name and select the cloud provider and region of your
choice.

<div>
  <img alt="Cube Cloud Create Deployment Screen" />
</div>

<Info>
  Microsoft Azure is available on [Enterprise plan](https://cube.dev/pricing).
  [Contact us](https://cube.dev/contact) for details.
</Info>

## Step 3: Import Git repository

Next up, the second step in creating a Cube App from scratch in Cube Cloud is to
click **Import Git repository via SSH**.

<div>
  <img alt="Cube Cloud Upload Project Screen" />
</div>

Now go to your Bitbucket repository and on the **Clone** dialog, switch
to **SSH** and copy the URL:

<div>
  <img alt="Getting the repository's SSH URL from Bitbucket" />
</div>

Back in Cube Cloud, paste the URL and click **Generate SSH key**:

<div>
  <img alt="Getting SSH key from Cube Cloud" />
</div>

Now copy the SSH key and go back to Bitbucket and into the repository's
settings. Click **Access keys** from the navigation, then click  **Add
key** button. Give the key a label (`Cube Cloud`, for example) and paste the
SSH key in the relevant field:

<div>
  <img alt="Add Cube Cloud deploy key to Bitbucket" />
</div>

Click **Add SSH key** to save, then go back to Cube Cloud and
click **Connect**. After a connection is successfully established, you
should see the next screen:

<div>
  <img alt="Getting webhook URL from Cube Cloud" />
</div>

Copy the **Cube Cloud Git Webhook URL**, go to your Bitbucket
repository's settings, and click **Webhooks** from the navigation.
Click **Add webhook**, then add a title (`Cube Cloud`, for example).
Paste the URL into the correct field, ensure the **Repository > Push**
trigger is checked and click **Save**.

<div>
  <img alt="Add Cube Cloud webhook to Bitbucket" />
</div>

Back in Cube Cloud, click **Connect** to test the webhook.

## Step 4: Connect your Database

Enter your credentials to connect to your database. Check the [connecting to
databases][link-connecting-to-databases] guide for more details.

<Info>
  Want to use a sample database instead? We also have a sample database where you
  can try out Cube Cloud:

  <br />

  | Field    | Value              |
  | -------- | ------------------ |
  | Host     | `demo-db.cube.dev` |
  | Port     | `5432`             |
  | Database | `ecom`             |
  | Username | `cube`             |
  | Password | `12345`            |
</Info>

<div>
  <img alt="Cube Cloud Setup Database Screen" />
</div>

In the UI it'll look exactly like the image below.

<div>
  <img alt="Cube Cloud Setup Database Screen" />
</div>

If you run into issues here, make sure to allow the Cube Cloud IPs to access
your database. This means you need to enable these IPs in your firewall. If you
are using AWS, this would mean adding a security group with allowed IPs.

## Step 5: Generate the Data Model

Step five in this case consists of generating data models. Start by selecting
the database tables to generate the data models from, then
hit **Generate**.

<div>
  <img alt="Cube Cloud Setup Database Screen" />
</div>

Cube Cloud will generate the data models and spin up your Cube deployment. With
this, you're done. You've created a Cube deployment, configured a database
connection, and generated data models!

<div>
  <img alt="Cube Cloud Setup Database Screen" />
</div>

You're ready for the last step, running queries in the Playground.

## Step 6: Try out Cube Cloud

Now you can navigate to Playground to try out your queries or connect your
application to the Cube Cloud API.

<div>
  <img alt="Cube Cloud Playground" />
</div>

[bitbucket]: https://bitbucket.org/

[link-connecting-to-databases]: /admin/connect-to-data/data-sources


# Import a Git repository
Source: https://docs.cube.dev/docs/getting-started/migrate-from-core/import-git-repository-via-ssh

This guide walks you through setting up Cube Cloud, importing a generic Git repository with an existing Cube project via SSH, and connecting to your database.

## Step 1: Create an account

Navigate to [cubecloud.dev](https://cubecloud.dev/), and create a new Cube Cloud
account.

## Step 2: Create a new Deployment

Click **Create Deployment** button. This is the first step in the
deployment creation. Give it a name and select the cloud provider and region of
your choice.

<div>
  <img alt="Cube Cloud Create Deployment Screen" />
</div>

<Info>
  Microsoft Azure is available on [Enterprise plan](https://cube.dev/pricing).
  [Contact us](https://cube.dev/contact) for details.
</Info>

## Step 3: Import Git repository

Next up, the second step in creating a Cube App from scratch in Cube Cloud is to
click **Import Git repository via SSH** button.

<div>
  <img alt="Cube Cloud Upload Project Screen" />
</div>

Enter the SSH URL of your Git repository, and click **Generate SSH key**:

<div>
  <img alt="Getting SSH key from Cube Cloud" />
</div>

Copy the SSH key and add it to your hosted Git repository. Back in Cube Cloud,
click **Connect**. After a connection is successfully established, you
should see the next screen:

<div>
  <img alt="Getting webhook URL from Cube Cloud" />
</div>

Copy the **Cube Cloud Git Webhook URL** and add it your hosted Git
repository's webhooks. Ensure that the Git repository can push events which
should trigger a build on Cube Cloud. Back in Cube Cloud,
click **Connect** to test the webhook.

### Webhook format

Cube recognizes push webhooks in the formats sent by GitLab, Bitbucket, and
Azure DevOps out of the box, so you can usually point your repository's native
webhook integration at the webhook URL without any extra configuration.

If your Git host does not send one of these formats (for example, AWS
CodeCommit), or you want to trigger a sync from a CI/CD pipeline or manually,
send a `POST` request to the webhook URL with the `x-git-event: push` header:

```bash theme={"dark"}
curl -X POST "<CUBE-GIT-WEBHOOK-URL>" \
  -H "x-git-event: push" \
  -H "Content-Type: application/json" \
  --data '{"ref": "refs/heads/main"}'
```

* Use the full webhook URL exactly as shown in the UI — it includes the
  `token` query parameter that authenticates the request.
* The `x-git-event: push` header is required. Requests that do not carry a
  recognized Git event are ignored: Cube responds with `204`, does not pull
  the repository, and the request is not shown under recent webhook requests.
* `ref` is optional and names the branch to sync (in the `refs/heads/<branch>`
  form). If omitted, the production branch configured for the deployment is
  used.

Response status codes:

| Status | Meaning                                                                                    |
| ------ | ------------------------------------------------------------------------------------------ |
| `201`  | The event was accepted and a build was triggered                                           |
| `204`  | The event was ignored — no recognized Git event in the request, or nothing new to build    |
| `403`  | The `token` query parameter is missing or invalid                                          |
| `429`  | Rate limited — there is a short per-branch cooldown between webhook calls; retry in \~30 s |

## Step 4: Connect your Database

Enter your credentials to connect to your database. Check the [connecting to
databases][link-connecting-to-databases] guide for more details.

<Info>
  Want to use a sample database instead? We also have a sample database where you
  can try out Cube Cloud:

  <br />

  | Field    | Value              |
  | -------- | ------------------ |
  | Host     | `demo-db.cube.dev` |
  | Port     | `5432`             |
  | Database | `ecom`             |
  | Username | `cube`             |
  | Password | `12345`            |
</Info>

<div>
  <img alt="Cube Cloud Setup Database Screen" />
</div>

In the UI it'll look exactly like the image below.

<div>
  <img alt="Cube Cloud Setup Database Screen" />
</div>

If you run into issues here, make sure to allow the Cube Cloud IPs to access
your database. This means you need to enable these IPs in your firewall. If you
are using AWS, this would mean adding a security group with allowed IPs.

## Step 5: Generate the Data Model

Step five in this case consists of generating data models. Start by selecting
the database tables to generate the data models from, then
hit **Generate**.

<div>
  <img alt="Cube Cloud Setup Database Screen" />
</div>

Cube Cloud will generate the data models and spin up your Cube deployment. With
this, you're done. You've created a Cube deployment, configured a database
connection, and generated data models!

<div>
  <img alt="Cube Cloud Setup Database Screen" />
</div>

You're ready for the last step, running queries in the Playground.

## Step 6: Try out Cube Cloud

Now you can navigate to Playground to try out your queries or connect your
application to the Cube Cloud API.

<div>
  <img alt="Cube Cloud Playground" />
</div>

[link-connecting-to-databases]: /admin/connect-to-data/data-sources


# Import a GitHub repository
Source: https://docs.cube.dev/docs/getting-started/migrate-from-core/import-github-repository

This guide walks you through setting up Cube Cloud, importing a GitHub repository with an existing Cube project, and connecting to your database.

## Step 1: Create an account

Navigate to [cubecloud.dev](https://cubecloud.dev/), and create a new Cube Cloud
account.

## Step 2: Create a new Deployment

Click **Create Deployment**. This is the first step in the deployment
creation. Give it a name and select the cloud provider and region of your
choice.

<div>
  <img alt="Cube Cloud Create Deployment Screen" />
</div>

<Info>
  Microsoft Azure is available on [Enterprise plan](https://cube.dev/pricing).
  [Contact us](https://cube.dev/contact) for details.
</Info>

## Step 3: Import repository from GitHub

Next up, click **Import from a GitHub repository**. This will pop open a
GitHub app authorization dialog where you must first install the Cube Cloud
GitHub app to the desired organization. After authorizing Cube Cloud to access
your GitHub repository, you should see the following screen in Cube Cloud:

<div>
  <img alt="Cube Cloud Import from GitHub screen" />
</div>

Select your repository and the desired branch to use as the default. If the
repository is a monorepo, you should also provide the path to the Cube project
within it. Deployments connected to a Git monorepo will trigger a rebuild
**only** when committed files begin with the provided path.

## Step 4: Connect your Database

Enter your credentials to connect to your database. Check the [connecting to
databases][link-connecting-to-databases] guide for more details.

<Info>
  Want to use a sample database instead? We also have a sample database where you
  can try out Cube Cloud:

  <br />

  | Field    | Value              |
  | -------- | ------------------ |
  | Host     | `demo-db.cube.dev` |
  | Port     | `5432`             |
  | Database | `ecom`             |
  | Username | `cube`             |
  | Password | `12345`            |
</Info>

<div>
  <img alt="Cube Cloud Setup Database Screen" />
</div>

In the UI it'll look exactly like the image below.

<div>
  <img alt="Cube Cloud Setup Database Screen" />
</div>

If you run into issues here, make sure to allow the Cube Cloud IPs to access
your database. This means you need to enable these IPs in your firewall. If you
are using AWS, this would mean adding a security group with allowed IPs.

## Step 5: Generate the Data Model

Step four in this case consists of generating data models. Start by selecting
the database tables to generate the data models from, then
hit **Generate**.

<div>
  <img alt="Cube Cloud Setup Database Screen" />
</div>

Cube Cloud will generate the data models and spin up your Cube deployment. With
this, you're done. You've created a Cube deployment, configured a database
connection, and generated data models!

<div>
  <img alt="Cube Cloud Setup Database Screen" />
</div>

You're ready for the last step, running queries in the Playground.

## Step 6: Try out Cube Cloud

Now you can navigate to Playground to try out your queries or connect your
application to Cube Cloud API.

<div>
  <img alt="Cube Cloud Playground" />
</div>

[github]: https://github.com

[link-connecting-to-databases]: /admin/connect-to-data/data-sources


# Import a GitLab repository
Source: https://docs.cube.dev/docs/getting-started/migrate-from-core/import-gitlab-repository-via-ssh

Onboard an existing Cube project by linking a GitLab repository over SSH in Cube Cloud and completing database connectivity.

This guide walks you through setting up Cube Cloud, importing a [GitLab][gitlab]
repository with an existing Cube project via SSH, and connecting to your
database.

## Step 1: Create an account

Navigate to [cubecloud.dev](https://cubecloud.dev/), and create a new Cube Cloud
account.

## Step 2: Create a new Deployment

Click **Create Deployment**. This is the first step in the deployment
creation. Give it a name and select the cloud provider and region of your
choice.

<div>
  <img alt="Cube Cloud Create Deployment Screen" />
</div>

<Info>
  Microsoft Azure is available on [Enterprise plan](https://cube.dev/pricing).
  [Contact us](https://cube.dev/contact) for details.
</Info>

## Step 3: Import Git repository

Next up, the second step in creating a Cube App from scratch in Cube Cloud is to
click **Import Git repository via SSH**.

<div>
  <img alt="Cube Cloud Upload Project Screen" />
</div>

Now go to your GitLab repository and from the **Clone** dropdown menu,
copy the **Clone with SSH** URL:

<div>
  <img alt="Getting the repository's SSH URL from GitLab" />
</div>

Back in Cube Cloud, paste the URL and click **Generate SSH key**:

<div>
  <img alt="Getting SSH key from Cube Cloud" />
</div>

Now copy the SSH key and go back to GitLab and paste it into the repository's
settings. Find the **Deploy keys** section and click **Expand**.
Give the key a title (`Cube Cloud`, for example) and paste the SSH key in the
relevant field:

<div>
  <img alt="Add Cube Cloud deploy key to GitLab" />
</div>

Ensure **Grant write permissions to this key** is checked, then
click **Add key**. Go back to Cube Cloud and click **Connect**.
After a connection is successfully established, you should see the next screen:

<div>
  <img alt="Getting webhook URL from Cube Cloud" />
</div>

Copy the **Cube Cloud Git Webhook URL** and go to your GitLab
project's **Webhooks** settings. Paste the URL into the correct field,
ensure the **Push events** trigger is checked and click **Add
webhook**.

<div>
  <img alt="Add Cube Cloud webhook to GitLab" />
</div>

Back in Cube Cloud, click **Connect** to test the webhook.

## Step 4: Connect your Database

Enter your credentials to connect to your database. Check the [connecting to
databases][link-connecting-to-databases] guide for more details.

<Info>
  Want to use a sample database instead? We also have a sample database where you
  can try out Cube Cloud:

  <br />

  | Field    | Value              |
  | -------- | ------------------ |
  | Host     | `demo-db.cube.dev` |
  | Port     | `5432`             |
  | Database | `ecom`             |
  | Username | `cube`             |
  | Password | `12345`            |
</Info>

<div>
  <img alt="Cube Cloud Setup Database Screen" />
</div>

In the UI it'll look exactly like the image below.

<div>
  <img alt="Cube Cloud Setup Database Screen" />
</div>

If you run into issues here, make sure to allow the Cube Cloud IPs to access
your database. This means you need to enable these IPs in your firewall. If you
are using AWS, this would mean adding a security group with allowed IPs.

## Step 5: Generate the Data Model

Step five in this case consists of generating data models. Start by selecting
the database tables to generate the data models from, then
hit **Generate**.

<div>
  <img alt="Generating data models for a new Cube Cloud deployment" />
</div>

Cube Cloud will generate the data models and spin up your Cube deployment. With
this, you're done. You've created a Cube deployment, configured a database
connection, and generated data models!

<div>
  <img alt="Cube Cloud Playground" />
</div>

You're ready for the last step, running queries in the Playground.

## Step 6: Try out Cube Cloud

Now you can navigate to Playground to try out your queries or connect your
application to the Cube Cloud API.

<div>
  <img alt="Cube Cloud Playground" />
</div>

[gitlab]: https://gitlab.com/

[link-connecting-to-databases]: /admin/connect-to-data/data-sources


# Import a local project to Cube Cloud with CLI
Source: https://docs.cube.dev/docs/getting-started/migrate-from-core/upload-with-cli

This guide walks you through setting up Cube Cloud, importing an existing Cube project from a local machine via SSH, and connecting to your database.

<iframe title="Loom video" />

## Step 1: Create Deployment

Click **Create Deployment**. Then give it a name and select the cloud
provider and region of your choice.

<div>
  <img alt="Cube Cloud Create Deployment Screen" />
</div>

<Info>
  Microsoft Azure is available on [Enterprise plan](https://cube.dev/pricing).
  [Contact us](https://cube.dev/contact) for details.
</Info>

## Step 2: Upload your Cube project

The next step is to upload your existing Cube project to the Cube Cloud.

You can do it by running the following command from terminal in your Cube
project directory.

```bash theme={"dark"}
npx cubejs-cli deploy --token <TOKEN>
```

<div>
  <img alt="Cube Cloud Upload Project Screen" />
</div>

## Step 3: Connect your Database

Enter your credentials to connect to your database. Check the [connecting to
databases][ref-cloud-connecting-to-databases] guide for more details.

<Info>
  Want to use a sample database instead? We also have a sample database where you
  can try out Cube Cloud:

  <br />

  | Field    | Value              |
  | -------- | ------------------ |
  | Host     | `demo-db.cube.dev` |
  | Port     | `5432`             |
  | Database | `ecom`             |
  | Username | `cube`             |
  | Password | `12345`            |
</Info>

<div>
  <img alt="Cube Cloud Setup Database Screen" />
</div>

## Step 4: Try out Cube Cloud

Now you can navigate to [the Playground][ref-cloud-playground] to try out your
queries or connect your application to Cube Cloud API.

<div>
  <img alt="Cube Cloud Playground" />
</div>

[ref-cloud-connecting-to-databases]: /admin/connect-to-data/data-sources

[ref-cloud-playground]: /docs/explore-analyze/playground


# Use analytics chat
Source: https://docs.cube.dev/docs/getting-started/use-analytics-chat

Once your initial semantic model is ready, you can start using Cube features: analytics chat, workbooks, dashboards, IDE and more.

## Ask analytics questions in chat

On the home page, you can ask AI questions about your data and receive answers as results tables and charts.

<Frame>
  <img />
</Frame>

## Explore more

When the AI agent returns a query result in Analytics Chat, click Explore to open that result in an exploration. This allows you to further analyze and visualize the data returned by the AI agent.

## Make changes to data model

The AI agent can create ad-hoc calculations using [Semantic SQL][ref-semantic-sql] directly in the analytics chat. These calculations leverage the full power of SQL to build derived metrics on top of your existing semantic model measures and dimensions. When you need to persist these calculations, simply ask the AI agent to save them to your data model, and it will add them as new measures or dimensions.

[ref-semantic-sql]: /docs/introduction#semantic-sql


# Cube agent skills
Source: https://docs.cube.dev/docs/integrations/agent-skills

Install official Cube skills in your coding agent to operate Cube through the CLI.

[Cube agent skills](https://github.com/cube-js/cube-agent-skills) are instruction
packages that teach coding agents how to use the [Cube CLI](/reference/cli). They can
explore and change the semantic model, manage saved content and access, run queries,
configure embedded analytics, and operate deployments.

> Cube agent skills run in your coding agent and operate Cube through the CLI. They are not Agent Skills in Cube, which your data team authors in the semantic model and runs from Analytics Chat.

They are also separate from the [Cube connector](/docs/integrations/mcp-server), which
connects Claude directly to Cube for natural-language analytics.

## Choose the right Cube integration

| Thing                                                    | What it is                                                   | Where it runs                          |
| -------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------- |
| [**Cube connector**](/docs/integrations/mcp-server)      | Ask Cube questions in natural language                       | Claude — desktop, web, Code            |
| **Cube agent skills**                                    | Operate Cube — model, content, access, deployments           | Your coding agent, over the `cube` CLI |
| [**Agent Skills in Cube**](/docs/explore-analyze/skills) | Saved workflows your data team authors in the semantic model | Analytics Chat, via the `/` menu       |

You can install the Cube connector and Cube agent skills together. The connector gives
Claude a direct path to governed analytics; the skills give your coding agent repeatable
operational workflows over the CLI.

## Prerequisites

Install the Cube CLI. On Linux or macOS, run:

```bash theme={"dark"}
curl -fsSL https://raw.githubusercontent.com/cube-js/cube/master/install-cli.sh | sh
```

For Windows installation and other options, see [Cube CLI installation](/reference/cli#installation).

Then authenticate with a browser:

```bash theme={"dark"}
cube login --url https://TENANT.cubecloud.dev
```

For a headless environment, set `CUBE_API_URL` and `CUBE_API_KEY` instead. See
[Cube CLI authentication](/reference/cli#authentication) for both methods.

Every skill checks that the CLI is installed, verifies authentication, and lists the
available Cube contexts before it acts, so you can confirm the target tenant.

## Install

### Claude Code

Run these commands inside Claude Code:

```text theme={"dark"}
/plugin marketplace add cube-js/cube-agent-skills
/plugin install cube@cube
```

### Codex, GitHub Copilot, Gemini CLI, and other compatible agents

Install the skills from [skills.sh](https://skills.sh):

```bash theme={"dark"}
npx skills add cube-js/cube-agent-skills
```

The source is public under Apache 2.0 at
[`cube-js/cube-agent-skills`](https://github.com/cube-js/cube-agent-skills).

## Available skills

| Skill                  | What it does                                                                                                     |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `cube-explore-model`   | Searches and inspects cubes, views, measures, dimensions, joins, and model files.                                |
| `cube-build-model`     | Authors cubes and views on a dev-mode branch, validates them, and prepares them to deploy.                       |
| `cube-explore-content` | Browses workbooks, workbook reports, explorations, dashboards, folders, and scheduled notifications.             |
| `cube-build-content`   | Creates and updates workbooks, workbook reports, explorations, dashboards, folders, and scheduled notifications. |
| `cube-run-query`       | Runs semantic-layer queries and interprets the results.                                                          |
| `cube-configure-agent` | Inspects and tunes the in-product Cube agent, including rules, certified queries, and Agent Skills in Cube.      |
| `cube-admin`           | Manages users, groups, attributes, access policies, tenant settings, SCIM, and OIDC.                             |
| `cube-embed`           | Configures embed sessions, tokens, embeddable dashboards, and embed tenants.                                     |
| `cube-deploy`          | Manages deployments, environments, environment variables, builds, and logs.                                      |

## Use the skills

Skills activate automatically when a request matches their description. You can also name
a skill explicitly:

```text theme={"dark"}
Use cube-build-model to add a churn measure.
```

The skills distinguish between inspection and state-changing work. Exploration skills are
read-only. Skills that write first inspect the current state, confirm the Cube context, and
use the platform's normal safety boundaries, such as dev-mode branches for data model edits.

### Connector or `cube-run-query`?

Use the [Cube connector](/docs/integrations/mcp-server) when you want Claude to answer a
natural-language data question directly in a conversation. Use `cube-run-query` when the
query is part of a broader coding-agent task—for example, validating a measure you just
changed, checking exact query output before saving a report, or combining query results
with repository work.

Both paths apply the authenticated user's Cube permissions and security context. They are
complementary, so a Claude Code setup can use both.

## Troubleshooting

* **The agent says the Cube CLI is missing:** Install it from the
  [Cube CLI reference](/reference/cli#installation), then start a new agent session.
* **Authentication fails:** Run `cube whoami`. If needed, sign in again with
  `cube login --url https://TENANT.cubecloud.dev`.
* **The request targets the wrong tenant:** Run `cube context list` and tell the agent
  which context to use.
* **A skill does not activate automatically:** Name it in the request, for example,
  `Use cube-explore-model to find the revenue measure.`


# dbt Integration
Source: https://docs.cube.dev/docs/integrations/dbt

Pull dbt models into Cube and convert them into cubes automatically — manually, from your CI/CD pipeline, or on every push to your dbt repository.

<Note>
  Available on [Premium and above plans](https://cube.dev/pricing).
</Note>

If your team already models data in [dbt](https://www.getdbt.com/), you can import
those models into Cube as cubes instead of redefining them by hand. **dbt pull**
connects to your dbt project's Git repository, parses the project, converts each dbt
model into a cube — including dimensions, measures, descriptions, and joins — and
commits the generated files to a branch where you review them before they reach
production.

Pulls can run manually, from your CI/CD pipeline, automatically on every push to your
dbt repository, or from [Analytics Chat](#trigger-from-analytics-chat) — so your
semantic layer stays in sync with dbt as it evolves.

<Info>
  **dbt pull** runs in one direction — **dbt → Cube**. dbt stays the source of truth for how
  tables are transformed; Cube serves those models to BI tools, APIs, and AI agents. The
  reverse direction — promoting a cube back into your dbt project as a pull request — is
  available via [dbt push](#push-cubes-to-dbt), currently in preview.
</Info>

## How it works

When a pull runs — whether triggered manually, from CI, or by a repository push —
Cube spins up a short-lived, isolated sandbox and:

1. **Clones your dbt repository** (a shallow clone of the branch you selected).
2. **Installs your project's dependencies** (`dbt deps`).
3. **Parses the project** (`dbt parse`) to produce dbt's `manifest.json` — the
   structured description of every model, column, test, and constraint.
4. **Converts each dbt model into a cube definition** (one `.yml` file per model).
5. **Commits the generated files** to a branch for review, then tears the sandbox
   down.

**By default, no connection to your data warehouse is made during a pull.** Cube uses
`dbt parse`, not `dbt run` or `dbt compile`, so it reads your project's structure
without ever querying your warehouse. dbt pull generates cube definitions; it assumes
the underlying tables were already built by your own production `dbt run`. The one
exception is [Infer column types from dbt catalog](#infer-column-types-from-dbt-catalog),
an opt-in option that reads real column types from your warehouse.

## Prerequisites

* **A supported data warehouse.** dbt pull supports **Snowflake**,
  **Amazon Redshift**, **PostgreSQL**, **Google BigQuery**, **Databricks**,
  **Amazon Athena**, and **ClickHouse**. If your deployment uses any other database
  type, the pull dialog will tell you it's unsupported.
* **A Git repository** containing your dbt project, reachable over **HTTPS** or
  **SSH**. GitHub, GitLab, Bitbucket, Azure DevOps, and self-hosted Git servers all
  work.
* **Read access to that repository** — either a personal access token (PAT) for
  HTTPS, or the ability to register a read-only deploy key for SSH.
* For the generated cubes to return data, the dbt models must already be **built into
  your warehouse** by your normal production `dbt run`. dbt pull generates cube
  definitions that point at each model's relation; it does not create the underlying
  tables. Models may live in **several schemas** — the schema is resolved per model
  from your dbt project, not taken from a single setting (see
  [Models in several schemas](#models-in-several-schemas)).

## Connect your dbt repository

The dbt connection is configured on your deployment's **default data source**.

<Steps>
  <Step title="Open the data source settings">
    Go to **Settings → Data Sources** and **edit** the default data source.
    Expand the **dbt project** section.
  </Step>

  <Step title="Fill in the connection fields">
    | Field                 | Description                                                                                                                                                                                                                                                                                                                                                                           |
    | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Repository URL**    | The clone URL of the repo that contains your dbt project, e.g. `https://github.com/your-org/your-repo.git` or `git@github.com:your-org/your-repo.git`.                                                                                                                                                                                                                                |
    | **Project path**      | The path to the dbt project inside the repository (the folder containing `dbt_project.yml`). Use `.` if the project is at the repository root.                                                                                                                                                                                                                                        |
    | **Branch**            | The branch of the dbt repository to sync. Defaults to the repository's default branch.                                                                                                                                                                                                                                                                                                |
    | **dbt target schema** | Your dbt **target schema** — the default for models that don't declare a schema of their own. Models that set a custom schema in dbt resolve to that schema instead; see [Models in several schemas](#models-in-several-schemas).                                                                                                                                                     |
    | **dbt target**        | *Optional.* The dbt target name the pull runs as. Defaults to `dev`. It doesn't have to match anything in your repository — Cube generates its own `profiles.yml` for the pull — but it is what your project's `generate_schema_name` macro sees as `target.name`. Set it if your project picks schemas per environment; see [Models in several schemas](#models-in-several-schemas). |
  </Step>

  <Step title="Choose an authentication method">
    Two authentication methods are supported:

    * **HTTPS + personal access token** — paste a PAT with read access to the
      repository. Leave it unchanged on later edits to reuse the existing token.
    * **SSH deploy key** — Cube generates a key pair for you and shows you the
      **public** key to register as a read-only deploy key on your Git host. The
      private key is generated and stored server-side and never leaves Cube.

    Whichever method you use, the secret is stored encrypted and resolved server-side
    at pull time — your Git credentials never reach the browser.

    <Frame>
      <img alt="dbt project settings card with the SSH authentication method selected and the generated public deploy key" />
    </Frame>
  </Step>

  <Step title="Test the connection">
    Click **Test connection**. Cube checks that the repository is reachable with your
    URL and credentials and reports the result:

    * **"Repository is reachable"** — you're good to save.
    * An error message identifying the problem (invalid/expired token, repository not
      found, host unreachable, not a Git URL, etc.).
  </Step>

  <Step title="Save">
    Click **Save dbt settings**.
  </Step>
</Steps>

Saving these settings does not restart your deployment.

## Models in several schemas

Generated cubes take their schema **per model**, from what dbt resolved for that
model — so a project that builds into `analytics`, `reports` and `intermediate`
produces cubes pointing at all three. **dbt target schema** is not applied to every
model; it is the default for models that don't declare a schema of their own.

dbt decides each model's schema at parse time by calling its `generate_schema_name`
macro, so what you get depends on which macro your project uses:

| Your dbt project                                                             | A model with `+schema: analytics` resolves to                                       |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| dbt's **default** `generate_schema_name`                                     | `<target schema>_analytics` — the custom name is **appended** to your target schema |
| A `generate_schema_name` override that returns the custom name in production | `analytics`                                                                         |

The first row is dbt's documented default and is often not what people expect;
the second is the common override
([dbt: custom schemas](https://docs.getdbt.com/docs/build/custom-schemas)).

<Warning>
  If your project overrides `generate_schema_name` and keys it on the environment —
  the widespread `{% if target.name == 'prod' %}` pattern — you **must** set **dbt
  target** to that production target name. Otherwise the macro takes its fallback
  branch and every model collapses onto the **dbt target schema** value, so every
  generated cube points at one schema.
</Warning>

To see what a pull actually resolved, open any generated `.yml` and read its
`sql_table` — the schema in it is the one dbt picked for that model. If every cube
carries the same schema and your project expects several, that's the misconfigured
target described in the warning above. (Cube support can also see a per-model
declared-vs-resolved breakdown in the sync logs for a given pull.)

## Configure pull settings

Pull options are saved on the integration itself, so every pull — manual or
automated — uses the same configuration:

| Option                                                   | Default            | Description                                                                                                                                                                                  |
| -------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Output path**                                          | `/model/cubes/dbt` | Directory in the repository where the generated cube files are written. This folder is replaced on each pull.                                                                                |
| **Name prefix**                                          | `dbt_`             | Prefix added to each generated cube's name.                                                                                                                                                  |
| **Title prefix**                                         | `(dbt) `           | Prefix added to each generated cube's display title.                                                                                                                                         |
| **Model selector**                                       | *(empty)*          | Optional dbt selector using `dbt ls --select` syntax to limit which models are pulled, e.g. `tag:cube` or `marts.*`. Leave empty to pull all models.                                         |
| **Only pull marts**                                      | Off                | When enabled, only pulls models whose path starts with the **Marts folder** value (e.g. `marts`).                                                                                            |
| **Auto-detect primary keys from column names**           | On                 | Falls back to a column-name guess when dbt declares no key. See [Primary key detection](#primary-key-detection).                                                                             |
| **Primary key column suffixes**                          | `_id`              | Comma-separated suffixes treated as key columns, e.g. `_sk, _key`. The default `_id` also matches a column named `id`. Only shown when **Auto-detect primary keys from column names** is on. |
| **Detect primary keys from `unique` + `not_null` tests** | On                 | Treats a column carrying both dbt tests as the cube's primary key. Outranks the column-name guess.                                                                                           |
| **Add default measures**                                 | On                 | Adds a `count` measure to every cube, and `sum` measures for additive numeric columns.                                                                                                       |
| **Include descriptions**                                 | On                 | Carries dbt model and column descriptions into cubes and dimensions.                                                                                                                         |
| **Generate joins**                                       | On                 | Infers joins between cubes from dbt `relationships` tests and foreign-key constraints.                                                                                                       |
| **Also generate reverse joins**                          | Off                | Adds a `one_to_many` join back to the referencing cube, so a query can start from either side. Only shown when **Generate joins** is on.                                                     |
| **Infer column types from dbt catalog**                  | Off                | Reads real warehouse column types from dbt's `catalog.json` instead of guessing from column names. See [below](#infer-column-types-from-dbt-catalog).                                        |

### Primary key detection

A cube's `primary_key` states the model's grain, and Cube relies on it to aggregate
correctly across joins. The pull looks for it in three tiers and uses the first one that
yields a key:

1. **dbt `primary_key` constraints** — both column-level and model-level (composite)
   constraint blocks. Always honored, even when both detection options are off.
2. **Strict `unique` + `not_null` tests** on the same column. Only tests that actually
   guarantee uniqueness count — a test with `where:`, `severity: warn`, or a relaxed
   `error_if` is ignored.
3. **Column-name suffixes**, `_id` by default.

Only tier 1 can produce a **composite** key, because it's the only place where your dbt
project states the grain. Tiers 2 and 3 mark exactly one column: two independently unique
columns are two candidate keys, not a composite key. When several columns qualify, the
pull prefers the one named after the model — `stg_customers` → `customer_id`, with layer
prefixes (`stg_`, `dim_`, `fct_`, …) stripped and plurals reduced — and deprioritizes
columns dbt declares as foreign keys, unless that would leave no candidate at all (on a
1:1 satellite table, the foreign key *is* the table's own key).

Separately from the tiers, a column that another cube joins to is marked as a key on the
**referenced** cube — Cube can't resolve the join otherwise. This is additive: it applies
whether or not the tiers already found a key, so a cube can end up with a declared key
*plus* a joined-to column. The cube on the other side — the one that owns the foreign
key — gets no key from this, which is the usual reason a cube in a join ends up without
one.

To key a cube on something the pull wouldn't guess — a composite key, or a column your
suffixes don't cover — declare it in dbt. Constraints require an
[enforced model contract](https://docs.getdbt.com/reference/resource-configs/contract),
which in turn requires a `data_type` on every column of the model:

```yaml theme={"dark"}
models:
  - name: dim_accounts
    config:
      contract:
        enforced: true
    constraints:
      - type: primary_key
        columns: [account_sk, valid_from]
    columns:
      - name: account_sk
        data_type: varchar
      - name: valid_from
        data_type: timestamp
      # …every other column of the model needs a data_type too
```

Your warehouse doesn't have to enforce primary keys for this to work — most don't. The
pull only runs `dbt parse`, and reads the declaration out of `manifest.json`.

If your project doesn't use contracts, tier 2 is the way to declare a single-column key:
add `unique` and `not_null` tests to it.

A declared key is never overridden or widened by the guessing tiers — only a joined-to
column can add to it. If a cube that participates in a join ends up with no key at all,
the pull still writes the file, and what happens next depends on the cube's measures:

* **With a `count`, `sum`, `avg`, or `number` measure** — including the `count` that
  **Add default measures** adds to every cube — the data model fails to compile with
  `primary key for '<cube>' is required when join is defined in order to make aggregates
  work properly`.
* **Without one**, there's no compile error, but the join is dropped: a query that touches
  both cubes then fails with `Can't find join path to join '<cube>', '<cube>'`.

Either way, the generated `.yml` is where to check what the pull decided — every key it
detected is a dimension with `primary_key: true`.

### Infer column types from dbt catalog

<Warning>
  This option is currently in preview, and its behavior may still change. Reach out to the
  [Cube support team](/admin/account-billing/support) if you run into issues.
</Warning>

Without it, a dimension's type comes from a `data_type` declared in your dbt YAML, and —
when none is declared — from a column-name heuristic (`*_id` → `number`, `created_at` →
`time`, …). Enable this option and the pull additionally runs `dbt docs generate` to
produce dbt's `catalog.json`, which carries the **actual warehouse column types**.

Type precedence becomes: **declared `data_type` → catalog type → column-name heuristic**.
An explicit `data_type` in your dbt YAML still wins; the catalog only fills the gaps.

* **This step connects to your warehouse** (`dbt docs generate` queries the warehouse
  metadata), unlike the rest of the pull. The models must already be built.
* **Supported on Snowflake, Amazon Redshift, PostgreSQL, and ClickHouse.** It's skipped
  on Google BigQuery, Databricks, and Amazon Athena, whose sandbox profiles can't open a
  connection.
* **Best-effort.** If catalog generation or the catalog read fails — no connectivity,
  unbuilt models, unreadable file — it's logged and skipped, and the pull completes on
  declared and name-based types exactly as it would with the option off.

## Pass environment variables to dbt

Some dbt projects read environment variables while the sandbox runs — most
commonly a token used to install a **private dbt package**. For example, a
`packages.yml` that pulls a package from a private Git repository:

```yaml theme={"dark"}
packages:
  - git: "https://x-access-token:{{ env_var('DBT_PACKAGES_TOKEN') }}@github.com/your-org/private-package.git"
    revision: v1.0.1
```

Here `dbt deps` fails inside the sandbox unless `DBT_PACKAGES_TOKEN` is available
to it. Data
source connection variables (`CUBEJS_DB_*`) reach the sandbox automatically; any
other variable does **not**, unless you select it.

In the **dbt project** settings card, the **Environment variables** picker lets
you choose which of the deployment's environment variables to pass into the
sandbox. You select variables **by name** — their values stay in the deployment
env, are resolved server-side at sync time, and never reach the browser.

<Steps>
  <Step title="Define the variable on the deployment">
    In **Settings → Configuration**, add the environment variable (e.g.
    `DBT_PACKAGES_TOKEN`) with its value, if it isn't set already.
  </Step>

  <Step title="Select it in the dbt settings">
    Edit the default data source, expand the **dbt project** section, and under
    **Environment variables** select the variable(s) to pass — then **Save dbt
    settings**.
  </Step>

  <Step title="Reference it in dbt">
    Use the variable in your dbt project via `env_var('DBT_PACKAGES_TOKEN')`, as in the
    `packages.yml` example above. It's now available to `dbt deps`, `dbt parse`, and
    the rest of the pull.
  </Step>
</Steps>

<Note>
  `CUBEJS_DB_*` connection variables, and a few names reserved by the sync itself
  (schema, dbt profile, and Git internals), can't be selected. If a selected
  variable is later removed from the deployment env, it's skipped on the next sync
  and the settings card flags it.
</Note>

## Run a pull manually

<Steps>
  <Step title="Enter development mode">
    Open the deployment's **data model** page (the IDE) and enter **development mode**.
    The dbt integration is disabled outside dev mode — a manual pull lands on your dev
    branch, never directly on production.
  </Step>

  <Step title="Open the pull dialog">
    Open the **Integrations** menu → **dbt** → **Pull**. The dialog shows what will be
    pulled using your saved settings.

    <Warning>
      If the output path already contains files, the dialog shows a warning with the file
      count: a pull **overwrites** generated cube files and **deletes** files in that folder
      that no longer correspond to a dbt model. See
      [Re-running a pull](#re-running-a-pull).
    </Warning>
  </Step>

  <Step title="Start the pull">
    Click **Start Pull**. A progress toast tracks the pull and ends with
    **"dbt pull completed (N cubes)"**. The generated files appear in your file tree
    under the output path, on your development branch.
  </Step>
</Steps>

Review the generated cubes in the **Changes** view, then commit and merge the branch
through your normal workflow.

## Keep Cube in sync automatically

Automated syncs run the same pipeline as a manual pull, but instead of committing to
your working branch they **create a fresh review branch** — so a person can approve
the update before it reaches the live data model.

### Trigger from your CI/CD pipeline

Cube exposes a REST endpoint you can call at the end of your dbt deployment pipeline,
right after `dbt run`. As soon as your warehouse tables are rebuilt, your pipeline
tells Cube to regenerate the matching cubes. The exact endpoint URL for your
deployment is shown in the dbt settings card, ready to drop into a CI step.

<Frame>
  <img alt="API trigger section of the dbt settings card showing the sync endpoint URL" />
</Frame>

The [Cube CLI](/reference/cli#dbt-sync) wraps the same endpoint and can **wait** for
the sync to finish, which is what turns it into a test gate: sync the ref under
review, compile it, and fail the job before anything reaches production.

```bash theme={"dark"}
cube dbt sync DEPLOYMENT_ID --ref "$GITHUB_HEAD_REF" --wait
```

`--wait` exits non-zero if the sync fails, and `--ref` syncs the branch being
reviewed rather than the one saved on the integration. See [dbt sync as a CI test
gate](/reference/cli#dbt-sync-as-a-ci-test-gate) for the full pipeline, including
the compile and query steps.

### Trigger on every push

Register a webhook on your dbt repository so Cube syncs automatically whenever the
tracked branch is updated. In the settings card, generate a signing secret and copy
the callback URL into your Git host's webhook settings. Pushes are verified by
signature, de-duplicated (redeliveries and no-op ref changes are ignored), and scoped
to the branch you're syncing.

<Frame>
  <img alt="Webhook section of the dbt settings card with the signing secret and callback URL" />
</Frame>

### Trigger from Analytics Chat

Ask [the agent](/docs/explore-analyze/analytics-chat) to check for and pull dbt updates —
for example, "check for dbt updates and pull them." The agent starts a sync, follows its
progress, opens the review branch it produces, and summarizes the generated cubes. Ask
"what happened with my recent dbt syncs?" to have it answer from sync history instead.

### Review notifications

When an automated sync produces a branch that's ready to review, Cube emails the
recipients you configure — a comma-separated list in the settings card — with a link
straight to the review. No one has to poll the UI to notice that dbt changed. Recipients
who can edit the data model land on the branch in [development
mode](/docs/data-modeling/dev-mode), ready to make changes; recipients without edit access
see a read-only diff instead.

## What gets generated

dbt pull converts **models, their columns, and their relationships**. dbt
**metrics and semantic models are not imported.**

For each dbt model in your project:

* **One cube** is created (one `.yml` file per model), named
  `<name prefix><model name>` with title `<title prefix><model alias or name>`.

* **`sql_table`** is set to the model's fully-qualified relation,
  `database.schema.model` (empty parts are dropped, so e.g. Postgres and Athena
  yield `schema.model`). The **`schema` is taken per model** from what dbt resolved
  for it, so a project whose models build into several schemas produces cubes
  pointing at several schemas — see [Models in several schemas](#models-in-several-schemas).
  On Databricks, the first segment is the catalog: the
  value of the deployment's `CUBEJS_DB_DATABRICKS_CATALOG` environment variable,
  or `hive_metastore` if it isn't set. On ClickHouse, cubes also yield
  `schema.model`: on ClickHouse a schema *is* a database, so `CUBEJS_DB_NAME`
  doesn't affect the generated `sql_table` (it still sets the connection's default
  database).

* **Each column becomes a dimension.** The dimension type is inferred from the
  column's `data_type` where available, then — if
  [Infer column types from dbt catalog](#infer-column-types-from-dbt-catalog) is
  enabled — from the warehouse type in `catalog.json`, and otherwise from the column
  name:

  | Column type                                                                                       | Cube dimension type |
  | ------------------------------------------------------------------------------------------------- | ------------------- |
  | `varchar`, `text`, `string`, `char`, and non-scalar types (`json`, `variant`, `array`, …)         | `string`            |
  | `integer`, `int`, `bigint`, `smallint`, `decimal`, `numeric`, `number`, `float`, `double`, `real` | `number`            |
  | `date`, `datetime`, `timestamp`, `timestamptz`, `time`                                            | `time`              |
  | `boolean`, `bool`                                                                                 | `boolean`           |

  Vendor spellings and parameters are normalized, so `NUMBER(38,0)`,
  `character varying(256)`, `TIMESTAMP_NTZ(9)`, `INT64`, and `double precision` all map
  as expected.

* **Model and column descriptions** from your dbt project are carried over to the
  cubes and dimensions.

* **A `count` measure** is added to every cube.

* **`total_<column>` sum measures** are added for numeric columns whose names suggest
  an additive metric (names containing `amount`, `price`, `cost`, `total`, or `value`).

* **Primary keys** are detected from dbt `primary_key` constraints, then `unique` +
  `not_null` tests, then column-name suffixes — see
  [Primary key detection](#primary-key-detection).

* **Joins between cubes** are generated from dbt `relationships` tests and
  foreign-key constraints — so the generated data model is queryable across cubes out of
  the box. The foreign-key column is on the "many" side, so every generated join is
  `many_to_one` from the cube that owns it. A dbt relationship describes the reference
  from the referencing side only, so nothing points back — enable **Also generate reverse
  joins** to emit a `one_to_many` join back to the referencing cube too.

Models named `metricflow_time_spine` and any non-model resources (sources, seeds,
snapshots, etc.) are skipped.

Each generated file begins with a header noting that it's auto-generated and
recommending you don't edit it by hand — see
[Build on top of the generated cubes](#build-on-top-of-the-generated-cubes) for
how to customize them instead.

## Build on top of the generated cubes

Think of the resulting data model as **layered**. The generated cubes are the base
layer, not the finished semantic layer:

* **The base layer** — the cubes in the output path — is owned by the integration.
  It mirrors your dbt project and is regenerated on every pull, so treat it as
  read-only: any manual edits to these files are lost on the next sync.
* **The customization layer** is everything you build on top: hand-written cubes
  that [`extends`](/reference/data-modeling/cube#extends) the generated ones, and
  [views](/reference/data-modeling/view) that shape what's exposed to consumers.
  This layer lives outside the output path and survives every pull.

Because `extends` merges your definitions into the generated cube, you can add
measures, joins, segments, pre-aggregations, or access control without touching
the generated files:

```yaml theme={"dark"}
cubes:
  - name: orders
    extends: dbt_orders

    measures:
      - name: average_order_value
        sql: amount
        type: avg
```

When your dbt project changes — a column is added, a description is updated — the
next pull refreshes the base layer, and your customizations automatically apply on
top of the updated cubes. dbt stays the source of truth for the physical model,
while the semantics you add in Cube accumulate in a layer the sync never touches.

## Re-running a pull

Pulling again refreshes the cubes to match your current dbt project:

* Files for models that **still exist** in dbt are **overwritten** with freshly
  generated definitions.
* Files in the output path whose models are **no longer in the dbt project** are
  **deleted**.
* Files in the output path that correspond to a model **still present** in dbt are
  preserved — so a scoped pull (using a model selector or "Only pull marts") will
  **not** delete the cubes for models outside that scope.

<Warning>
  Because generated files are overwritten, manual edits to them are lost on the next
  pull. Keep customizations in a separate cube that `extends` the generated one — see
  [Build on top of the generated cubes](#build-on-top-of-the-generated-cubes).
</Warning>

## Push cubes to dbt

<Warning>
  dbt push is currently in preview, and its behavior may still change. If you run into
  issues, reach out to the [Cube support team](/admin/account-billing/support).
</Warning>

**dbt push** is the reverse direction: it promotes a cube back into your dbt project as a
reviewed pull request. A cube you built in Cube on an inline `sql:` becomes a dbt model —
a `<model>.sql` plus a per-model `<model>.yml` properties file — validated by a real
`dbt parse` in Cube's sandbox **before** the PR is opened, so the change arrives green.

This closes the modeling loop: prototype fast in Cube, then harden the logic in dbt where
it's materialized, tested, and owned by analytics engineering. Once the pull request
merges, your existing [pull](#keep-cube-in-sync-automatically) picks the new model back up.

### Before you push

* **Write access to the dbt repository.** Pull only needs read access; push needs a PAT
  with write scope, or an SSH deploy key registered with write access. Cube verifies this
  without pushing anything (see below).
* Push is **off by default** and enabled per deployment.

### Enable push

<Steps>
  <Step title="Open the dbt settings">
    Edit the **default data source** under **Settings → Data Sources**, expand the
    **dbt project** section, and find **Push to dbt**.
  </Step>

  <Step title="Turn push on and verify write access">
    Enable **push**, then click **Verify write access**. Cube checks that the stored
    credential can write to the repository — a `git-receive-pack` probe for a PAT, a
    `push --dry-run` for SSH — without creating any branch or commit.
  </Step>

  <Step title="Choose where models land and how they're delivered">
    | Setting           | Description                                                                                                                                                                              |
    | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Models path**   | Directory in the dbt project where generated model files are written. Defaults to `models/marts/cube/`.                                                                                  |
    | **Delivery mode** | **Open a pull request** (default) pushes to a `cube/dbt-push/*` branch and opens a PR/MR. **Commit directly to a branch** commits straight to a branch you name — validation still runs. |

    Then **Save dbt settings**.
  </Step>
</Steps>

### Push a cube

<Steps>
  <Step title="Enter development mode">
    Open the deployment's **data model** page and enter **development mode** — push runs from a
    dev branch, like a manual pull.
  </Step>

  <Step title="Open the push dialog">
    Open the **Integrations** menu → **dbt** → **Push**, pick the cube to promote, and give the
    dbt model a name. Only cubes defined in YAML with an inline `sql:` are eligible; a cube
    backed only by `sql_table` (nothing to materialize) or defined in JavaScript/Python is
    reported as ineligible.
  </Step>

  <Step title="Review the preview">
    Cube shows the generated `<model>.sql` and `<model>.yml` in an editable preview, along with
    any conversion warnings. **What you see is what ships** — edit either file here if you need
    to.
  </Step>

  <Step title="Push">
    Confirm. Cube clones the repo, writes the files (**create-only** — it never overwrites an
    existing model and never force-pushes), and runs `dbt deps` + `dbt parse`. If parse fails,
    the push stops with dbt's own output and **no pull request is opened**. On success, a
    progress toast ends with a link to the pull request — or, for SSH or non-GitHub/GitLab
    hosts, a prefilled compare link to open it yourself.
  </Step>
</Steps>

### What gets pushed

Each push creates exactly two new files:

* **`<model>.sql`** — the cube's `sql:` wrapped in a CTE that projects one column per
  dimension, so every column the properties file documents exists by construction. Table
  references that match a [pulled](#what-gets-generated) dbt model are rewritten to
  `{{ ref('<model>') }}`, making the generated model a first-class node in your dbt DAG.
* **`<model>.yml`** — a per-model properties file: model and column descriptions,
  `unique` + `not_null` tests on primary-key dimensions, `relationships` tests synthesized
  from the cube's joins (only to targets that originated in dbt), and the cube's measures
  preserved under `meta.cube.measures` for context.

## Limitations

* **Supported warehouses:** Snowflake, Amazon Redshift, PostgreSQL, Google
  BigQuery, Databricks, Amazon Athena, and ClickHouse.
* **Imports models, columns, and relationships only** — not dbt metrics, semantic
  models, or exposures. Data tests aren't converted into anything either; `unique`,
  `not_null`, and `relationships` tests are only read as evidence for
  [primary keys](#primary-key-detection) and joins.
* **Pull is one-directional** — dbt pull never writes back to your dbt repository.
  Promoting cubes into dbt is the [dbt push](#push-cubes-to-dbt) direction (in preview).
* **No warehouse connection** — a pull doesn't trigger a `dbt run`; it assumes your
  tables are already built. The only exception is the opt-in
  [Infer column types from dbt catalog](#infer-column-types-from-dbt-catalog) option
  (in preview), which runs `dbt docs generate` on Snowflake, Amazon Redshift,
  PostgreSQL, and ClickHouse.
* **One dbt project per deployment.**

## Troubleshooting

<AccordionGroup>
  <Accordion title="The dbt menu item is greyed out">
    You're not in development mode. Enter dev mode on the data model page — a manual
    pull only runs against a dev branch.
  </Accordion>

  <Accordion title="The pull dialog says the database type is unsupported">
    Your deployment uses a database other than Snowflake, Amazon Redshift, PostgreSQL,
    Google BigQuery, Databricks, Amazon Athena, or ClickHouse. dbt pull isn't available
    for it.
  </Accordion>

  <Accordion title="The pull dialog says dbt isn't configured">
    The dbt connection settings are missing or incomplete on the default data source. An
    account administrator can add them under **Settings → Data Sources** (see
    [Connect your dbt repository](#connect-your-dbt-repository)). If you're not an
    administrator, ask someone who manages the deployment to set it up.
  </Accordion>

  <Accordion title="Test connection fails">
    The message identifies the cause:

    * *Authentication failed* — the token is invalid, expired, or lacks read access to
      the repository (for HTTPS), or the deploy key isn't registered on the repository
      (for SSH). Generate a new read-scoped token, or register the public deploy key
      shown in the settings card.
    * *Repository not found* — check the URL; for private repos this can also mean the
      credential can't see the repo.
    * *Unsupported protocol* — use the repository's HTTPS or SSH clone URL.
    * *Host unreachable / could not resolve host* — check the URL; the host must be
      reachable over the public internet.
  </Accordion>

  <Accordion title="A pull fails partway through">
    The error message describes what failed. Common causes:

    * The dbt project doesn't exist at the configured **Project path** (no
      `dbt_project.yml` there).
    * A failure in the dbt project itself — the same failure you'd see running dbt
      locally.

    Transient failures are retried automatically; persistent errors fail with a message
    describing the problem.
  </Accordion>

  <Accordion title="The pull reports &#x22;no dbt models matched&#x22;">
    Your **Model selector** and/or **Only pull marts** filters excluded every model. The
    pull fails (rather than generating nothing and deleting files) and names the active
    filters. Adjust the selector/marts folder and try again. Confirm the selector with
    `dbt ls --select <your selector>` locally.
  </Accordion>

  <Accordion title="A webhook push doesn't trigger a sync">
    Check that:

    * The webhook is registered on the **dbt repository** with the callback URL and
      signing secret from the settings card.
    * The push targets the **branch** configured in the dbt settings — pushes to other
      branches are ignored.
    * The delivery isn't a redelivery or a no-op ref change — those are de-duplicated
      and skipped.
  </Accordion>

  <Accordion title="The pull succeeded but Playground returns no data">
    dbt pull generates cube definitions that point at each model's relation, but it
    doesn't build the tables. Make sure your production `dbt run` has materialized the
    models, and that the schema each generated cube names is where they actually landed.
    Open a generated `.yml` and compare its `sql_table` against your warehouse — if the
    schema is wrong, see *A generated cube points at the wrong table or schema* below.
  </Accordion>

  <Accordion title="A generated cube has no primary key, or the wrong one">
    * **No key at all** — the model has no `primary_key` constraint, no strict `unique` +
      `not_null` pair, and no column matching the configured suffixes. Either declare the key
      in dbt, or set **Primary key column suffixes** to your project's convention (e.g. `_sk`).
    * **A declared key was ignored** — a `primary_key` constraint is applied all-or-nothing.
      If it names a column the model's `columns:` block doesn't document, the whole
      declaration is skipped (rather than emitting a narrower, wrong grain) and the pull falls
      back to the guessing tiers. Check that every column the constraint lists is also
      documented under `columns:`.
    * **Wrong column** — declare the key in dbt and the pull will use it verbatim.

    Open the generated `.yml` to see what the pull decided: the key is whichever dimensions
    carry `primary_key: true`. See [Primary key detection](#primary-key-detection).
  </Accordion>

  <Accordion title="A query can't join two cubes in one direction">
    Joins generated from dbt follow the direction dbt declares them, and Cube's join graph is
    directed — so a query rooted at the referenced cube can't reach the cube that references
    it. Enable **Also generate reverse joins** in the pull settings and re-run the pull.
  </Accordion>

  <Accordion title="A generated cube points at the wrong table or schema">
    The `sql_table` is whatever dbt resolved for that model, so start by asking which
    schema dbt picked rather than which one you typed.

    **Every cube points at the same schema, and it's the value you put in dbt target
    schema.** Your project almost certainly overrides `generate_schema_name` and keys it
    on the environment (`{% if target.name == 'prod' %}`), while the pull ran under the
    default `dev` target — so every model took the macro's fallback branch. Set **dbt
    target** to your production target name and re-run the pull. See
    [Models in several schemas](#models-in-several-schemas).

    **Every cube points at `<dbt target schema>_<something>`.** That's dbt's *default*
    `generate_schema_name`, which appends a model's custom schema to the target schema.
    It's working as dbt documents. If you want the bare custom names, override the macro
    in your dbt project — Cube uses whatever your project resolves.

    **One cube is wrong, the rest are fine.** Check that model's own `+schema` /
    `+database` config in dbt.

    On Databricks, the catalog segment comes from the deployment's
    `CUBEJS_DB_DATABRICKS_CATALOG` environment variable and defaults to
    `hive_metastore`. If your models live in a Unity Catalog catalog, set
    `CUBEJS_DB_DATABRICKS_CATALOG` to that catalog so generated cubes point at it.
  </Accordion>
</AccordionGroup>


# Cube for Sheets
Source: https://docs.cube.dev/docs/integrations/google-sheets

Cube for Sheets is the native Google Sheets add-on for Cube.

<Note>
  Available on [Premium and above plans](https://cube.dev/pricing).
</Note>

After [configuring](#configuration), [installing](#installation), and
[authenticating](#authentication) this add-on, you will be able to [create
explorations via pivot table](#create-explorations-via-pivot-table) and work with
[explorations](#work-with-explorations).

<iframe title="YouTube video" />

## Configuration

Cube for Sheets uses the SQL API internally. So, the SQL API has to be
[enabled][ref-sql-api-enabled] in the Cube deployment settings.

## Installation

You have to install Cube for Sheets into your Google Workspace organization.
To do so, navigate to its [page in the Google Workspace
Marketplace][link-marketplace-listing] and click **Install**:

<Frame>
  <img />
</Frame>

To verify that the add-on is successfully installed, go to any Google Sheets
document, open the **Extensions** menu, and check that there is the
**Cube Cloud for Sheets** menu item:

<Frame>
  <img />
</Frame>

## Authentication

You need to authenticate Cube for Sheets to retrieve data from Cube.
To do so, open the sidebar by going to the **Extensions** menu and choosing
**Cube Cloud for Sheets → Show Sidebar**. Then, click **Log in to Cube**.

A modal window with an authentication prompt will appear. Choose the deployments
that you want to work with in Google Sheets and click **Authorize**.
Once you see the `Access Granted` message, the window will close automatically.

<Warning>
  Google Apps Script authenticates the add-on as whichever Google account you
  signed in to first in the browser, not necessarily one with access to the
  open spreadsheet. If they differ, the add-on can't reach the spreadsheet and
  the cursor status reads **Cannot read your selection**. Sign in to only one
  Google account per browser profile (or use a private/incognito window) to
  avoid this — or sign out of every Google account and sign back in with an
  account that has access to the file first.
</Warning>

If you want to revoke the authentication, open the add-on menu and click
**Sign out**.

## Create explorations via pivot table

To create an exploration, open the add-on and click **Create exploration**.
Then, select a Cube deployment from the drop-down. Finally,
you can start building a query by selecting a view and its members in the UI that
looks and feels like [Playground][ref-playground].

<Info>
  Cube for Sheets works only with [views][ref-views], not cubes.
</Info>

If the view defines [`default_ui_filters`][ref-default-ui-filters], those
filters are pre-populated as soon as you select the view — the same way they
are in workbooks. They are a starting point, not enforcement: you can change
their values, switch operators, or remove them.

Click on members to add them to **Rows** and **Measures**, or drag a member from
the list straight onto **Rows**, **Columns**, **Measures**, or **Filters**. You
can also drag members between zones to rearrange them, or click the funnel
buttons to add members to **Filters**. A member dropped onto **Filters** has no
value yet, so it appears greyed until you set one in the **Filters** pane.
Click on **×** to remove members from a query.

<Frame>
  <img />
</Frame>

Use **Order** and **Filters** panes below to sort and filter the
data in the exploration.

Above the query editor, a **cursor row** (`● Sheet1 · A1` next to **+ New**)
shows the cell you last selected in the sheet. It can briefly lag your click;
press the target button in that row to re-read your selection. It only
refreshes the readout — it doesn't move or write anything.

If you'd like to move the exploration to a new location, click on the desired
top-left cell and then confirm with the target button under
**Result location**. Unlike the cursor row's button, this one moves the
exploration.

<Frame>
  <img />
</Frame>

With every change to your query, Cube for Sheets will update the exploration on
the sheet after a slight delay. If you'd like to minimize it, consider
implementing [pre-aggregations][ref-pre-aggs].

Writing a large result to the sheet can take a few seconds. When it does, a
progress bar appears above the run controls, tracking the write itself rather
than the query.

### Measure position and order

By default, measures nest under each value of the dimension they're paired
with — every measure for the first column value, then every measure for the
next. Open the **Display** tab to change **Measure position** to **Before
columns** to get the opposite layout: each measure spans every column value,
with all values of one measure together before moving to the next.

For example, with `Forecast Sales Units` and `Forecast Net Sales` on Measures
and a `season` dimension on Columns:

* **After columns** (default): `Q1: [Sales Units, Net Sales] | Q2: [Sales
  Units, Net Sales]`
* **Before columns**: `Sales Units: [Q1, Q2] | Net Sales: [Q1, Q2]`

The same choice applies when measures are placed on **Rows** instead (set
with **Measures on**, in the same tab) — there it's labeled **After rows** /
**Before rows**.

To change the order measures appear in within their group, drag them within
the **Measures** pane on the **Pivot** tab. Position and order are saved with
the exploration and survive **Refresh**.

When your exploration is ready, click **Save** to add it to your workspace. You
can then [work with the exploration](#work-with-explorations) from the add-on.
To discard an unsaved exploration instead, choose **Delete exploration** from
the editor's **⋮** menu.

## Work with explorations

Opening the add-on shows the current spreadsheet's home: every exploration
placed in this spreadsheet, grouped by sheet — a sheet isn't limited to one
placement — with each placement's range and how long ago it last refreshed.
A placement shows **Out of date** when its source exploration has been
edited since that copy was written to the sheet. Running an exploration
keeps its progress even if you close the pane before saving: it's listed
under its sheet with a **Not saved** label; if it has no sheet or anchor
yet, it appears under a top-level **Unsaved** heading instead. Reopening it
resumes exactly where you left off. The pane can also hold more than one
exploration open at once, switchable from a picker at the top.

Click **Browse all explorations** to search by name across your whole
deployment, not just the current folder — results are grouped by type and
show each item's folder location, and selecting one navigates you straight to
it.

An exploration can be placed more than once — on different sheets or at
different anchors in the same spreadsheet, and in more than one document at
once (a Google Sheets spreadsheet and an Excel workbook simultaneously).
Hovering a row in this list shows every placement it has in the **current**
document under **Location** / **Locations**. Click **Refresh** to update all
of that exploration's placements in the current document at once; click its
title to open it and change the query, which applies to every placement.

**Refresh all**, at the top of the spreadsheet home, refreshes every
placement in the document as a tracked run: a footer at the bottom of the
pane tracks overall progress (**N of M refreshed**) with a **Stop** button,
while each row shows **Queued**, **Refreshing…**, or **Not refreshed** with a
reason if it failed. The run keeps going if you navigate away and back;
refreshes are written one sheet at a time, so a spreadsheet with many
sheets refreshes noticeably slower than a single placement.

If you've edited a placement's cells by hand since it last refreshed, a
banner names the affected rows and warns that the next **Refresh** will
overwrite them — its **Locate** button jumps straight to them.

A placement survives renaming the sheet it's on or the spreadsheet it's in —
it's tracked by the sheet's and spreadsheet's own stable ids, not by name. A
placement's anchor is a fixed cell reference, though, so it does **not**
survive rows or columns inserted above it: the visible data shifts down with
the insert, but the stored anchor doesn't move with it, so the next refresh
targets the wrong cell.

<Frame>
  <img />
</Frame>

If an exploration has filters applied, an admin can turn on **Show applied filters
in reports** (Settings → Spreadsheet Add-ins) to make the filter state
visible on the sheet itself. When enabled, a summary of active filters is
added above the table, and filtered columns are marked "(filtered)" in
their header, both when the exploration is inserted and after **Refresh**.

Saved explorations also appear in the Cube workspace. See
[Saving explorations][ref-explorations] for details.

[link-google-sheets]: https://workspace.google.com/products/sheets/

[link-marketplace-listing]: https://workspace.google.com/u/0/marketplace/app/cube_cloud_for_sheets/641460343379

[ref-playground]: /docs/explore-analyze/playground

[ref-views]: /docs/data-modeling/views

[ref-pre-aggs]: /docs/pre-aggregations/using-pre-aggregations

[ref-default-ui-filters]: /reference/data-modeling/view#default_ui_filters

[ref-sql-api-enabled]: /reference/core-data-apis/sql-api#cube-cloud

[ref-explorations]: /docs/explore-analyze/explore#saving-explorations


# MCP server
Source: https://docs.cube.dev/docs/integrations/mcp-server

Connect MCP-aware assistants to Cube through a hosted HTTPS endpoint with OAuth and admin-managed defaults.

Cube MCP (Model Context Protocol) lets MCP-compatible AI clients connect to Cube over HTTPS using OAuth.

This page covers the **Cube connector**, which gives an AI assistant direct access to Cube
through MCP. It is not [Cube agent skills](/docs/integrations/agent-skills), which run in a
coding agent and operate Cube through the CLI, or
[Agent Skills in Cube](/docs/explore-analyze/skills), which are saved workflows your data
team authors for Analytics Chat.

<Note>
  The MCP server is available on [Premium and Enterprise plans](https://cube.dev/pricing). <br />Users need the [Viewer][ref-roles] role or higher to interact with the MCP server. Which tools a
  user sees depends on their role — see [Available actions](#available-actions).
</Note>

## What is MCP?

Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. The Cube MCP server acts as a bridge between your AI assistant and Cube's analytics platform, allowing you to ask data questions directly from your coding environment.

## Overview

Cube hosts an MCP server endpoint. MCP clients connect over HTTPS and authenticate via OAuth.

* **Endpoint:** `https://cubecloud.dev/mcp`
* **OAuth flow:** Authorization Code + PKCE, `client_id` = `cube-mcp-client`, scope = `mcp-agent-access`. Clients discover it automatically from the endpoint — there is nothing to configure by hand.
* **Account selection:** You sign in to Cube as part of the OAuth flow and, if you belong to more than one account, choose which one to connect.
* **Deployment selection:** On connect, the client lands on the tenant **default deployment** set by your admin (or the first deployment you can access). Clients can also target a specific deployment and agent per request — see [Select a deployment and agent](#select-a-deployment-and-agent).

### One endpoint for everyone

`https://cubecloud.dev/mcp` is the same URL for every account, deployment and region. Cube
identifies your account from the OAuth token and routes each request to whichever
deployment serves it, so there is no per-tenant host to look up before you can connect.

<Note>
  If Cube runs in your own cloud account or on your own domain, use that console domain
  instead — `https://<your-console-domain>/mcp`.
</Note>

Each deployment also keeps a **region-specific endpoint**, shown under
**Admin → MCP Server**. Both work. Prefer the single endpoint above unless you need a
client to reach a deployment's region directly without passing through the control plane.

## Admin setup

### Prerequisites

Before enabling MCP, make sure you have:

* **Admin privileges** in your Cube instance
* An active Cube tenant

### 1) Check the MCP page

Go to **Admin → MCP Server**. The page shows the endpoint to hand to clients along with
ready-made setup snippets for each supported client. If it reads “MCP configuration is
unavailable,” the MCP server host isn’t configured for the account yet.

### 2) Configure deployment access

Go to **Admin → MCP Server** and use the **Deployment Access** section to control which
deployments MCP clients can reach and where they connect by default:

* **Default deployment** — the deployment MCP clients connect to unless they explicitly
  request another one. Choose **Automatic (first available)** to land each user on the
  first deployment they can access.
* **Limit available deployments** — when off (the default), MCP clients can access **all**
  deployments the user is permitted to see. Turn it on to restrict MCP to a chosen subset.
* **Available deployments** — when the limit is on, pick the deployments MCP clients may
  access. Selecting none disables MCP access for the account.

<Note>
  Deployment access is always intersected with the user's
  [role-based permissions][ref-roles] — clients can only reach deployments the
  authenticated user is allowed to see.
</Note>

<Frame>
  <img alt="Admin MCP Server page showing the Deployment Access section with the default deployment dropdown, the Limit available deployments switch, and the available deployments picker" />
</Frame>

## Connect to Claude

Cube is available in the
[Claude Connectors Directory](https://claude.ai/customize/connectors). Connect it once
and use it in Claude on the web, desktop, or Claude Code—there is no endpoint to paste or
local server to configure.

1. In Claude on the web or desktop, open **Customize → Connectors**.
2. Click **+**, choose **Browse connectors**, and search for **Cube**.
3. Select Cube and click **Connect**.
4. Complete the Cube OAuth flow and choose your tenant.

On a Team or Enterprise plan, an owner may need to enable Cube first under
**Admin Settings → Connectors**.

To use Cube in a chat, open the tools menu and enable the Cube connector, then ask a data
question. In Claude Code, run `/mcp` to confirm the connector is available and authenticate
if prompted.

<Frame>
  <img />
</Frame>

## Connect to Cursor

Add the MCP endpoint under Tools & MCP Settings, then complete the OAuth flow.

```json theme={"dark"}
{
  "mcpServers": {
    "cube-mcp-server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "--transport", "http", "https://cubecloud.dev/mcp"]
    }
  }
}
```

## Connect to Codex

Preferred (CLI):

```bash theme={"dark"}
codex mcp add cube-mcp-server --url https://cubecloud.dev/mcp
```

If this is your first time using MCP in Codex, enable the feature in `~/.codex/config.toml`:

```editorconfig theme={"dark"}
[features]
rmcp_client = true
```

Manual setup:

```editorconfig theme={"dark"}
[features]
rmcp_client = true

[mcp_servers."cube-mcp-server"]
url = "https://cubecloud.dev/mcp"
```

Then run `codex mcp login cube-mcp-server` to authenticate.

## Connect to other MCP clients

For any MCP-compatible client:

1. Add a new server with the **MCP endpoint**.
2. The client will auto-discover OAuth and prompt for authentication.
3. Complete the OAuth flow to grant access to your Cube deployment.

## Select a deployment and agent

An MCP client is not locked to a single deployment for the whole session. After
connecting, it can discover the deployments and agents you can access and target a
specific one on each request.

Three tools work together:

* **`listDeployments`** — discovery. Returns every deployment you can access via MCP
  (already filtered by the admin's deployment-access settings and your permissions) and
  each deployment's agents. Use it to find valid `deploymentId` and `agentId` values
  before calling `chat`. Every deployment offers an **Auto** agent (`agentId: null`) in
  addition to any configured agents.
* **`chat`** — accepts two optional selection parameters:
  * **`deploymentId`** — the deployment to use for this request. When omitted, the chat
    uses the deployment from the current session (the default resolved at connect time).
  * **`agentId`** — the agent to use for this request. When omitted or `null`, the
    deployment's **Auto** agent is used. Pass a specific `agentId` to route to a
    configured agent.
* **`loadQueryResults`** — paginates through the results of a previous query on the same
  deployment context.

A typical client workflow:

<Steps>
  <Step title="Connect">
    Complete the OAuth flow. The session is scoped to the tenant default deployment (or
    the first one you can access).
  </Step>

  <Step title="Discover">
    Call `listDeployments` to see the available `deploymentId` / `agentId` values.
  </Step>

  <Step title="Chat">
    Call `chat` with your `input`, optionally passing `deploymentId` and/or `agentId` to
    target a specific deployment or agent. Omit both to use the session default deployment
    with its Auto agent.
  </Step>
</Steps>

Requests are always validated against the admin's deployment-access settings. A deployment
that is outside the allow-list — or that you don't have permission to see — is rejected
with a **403 Forbidden** (`Deployment <id> is not available via MCP for this account`), so
neither `listDeployments` nor the `chat` selection can reach an excluded deployment.

## Available actions

The MCP server exposes 23 tools, grouped below.

Every tool runs as the authenticated user. Queries respect the same
[permissions][ref-roles] as the rest of Cube, including row-level security — MCP is a new
way to reach your data, not a new access surface.

### Read and write tools

Each tool is annotated as read-only or destructive. MCP clients that honor these
annotations — including Claude — run read-only tools automatically and **always ask for
confirmation** before any of the six destructive ones: `updateReport`, `deleteReport`,
`updateDashboard`, `publishDashboard`, `writeDataModelFile`, and `deleteDataModelFile`.
Nothing that changes a workbook report, an exploration, a dashboard, or your data model
happens without an explicit approval.

### Deployments and chat

| Tool               | Description                                                                            |
| ------------------ | -------------------------------------------------------------------------------------- |
| `listDeployments`  | Lists the deployments and agents you can reach over MCP.                               |
| `chat`             | Asks a question of a Cube agent, optionally targeting a specific deployment and agent. |
| `loadQueryResults` | Paginates through the results of a previous query.                                     |

See [Select a deployment and agent](#select-a-deployment-and-agent) for how these three
work together.

### Query and discovery

| Tool              | Description                                                                                                                                                                                                                                                                       | Access    |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `searchDataModel` | Searches the semantic model by similarity — views and their measures and dimensions — to discover what is queryable. Returns compact records (name, title, description, type) to reference in `runQuery`.                                                                         | Read-only |
| `runQuery`        | Runs a Cube SQL query (PostgreSQL dialect) against the [SQL API][ref-sql-api]. Returns a schema, a page of rows, and `hasMore` / `totalRows` for pagination via `offset`. Pass the dev `branchName` from `startDataModelEdit` to query that branch instead of the deployed model. | Read-only |

Call `searchDataModel` before `runQuery` to find exact view and member names rather than
guessing them.

Omitting `branchName` queries the deployed model, exactly as before this parameter existed.
Passing a `branchName` that isn't an active dev branch — for example the deploy branch's own
name, or a feature branch with no dev worker running — fails with an error rather than
silently answering from the deployed model, so a query aimed at the wrong branch never
looks like a query that just returned no rows.

### Dashboard authoring

These tools build [workbooks][ref-workbooks] and [dashboards][ref-dashboards]
programmatically. Creating and editing workbooks requires the Explorer role or higher.

| Tool               | Description                                                                                                                                                                                                                                                     | Access                |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `readWorkbook`     | Reads a workbook — its name and its current dashboard draft and published configs.                                                                                                                                                                              | Read-only             |
| `createWorkbook`   | Creates a new empty workbook, the container that holds reports and a dashboard.                                                                                                                                                                                 | Write                 |
| `createReport`     | Saves a query plus its visualization. Pass `workbookId` to create a report inside a workbook and get the `reportId` a chart widget references; omit `workbookId` to save a standalone [exploration](/docs/explore-analyze/explore#saving-explorations) instead. | Write                 |
| `readReport`       | Reads one workbook report or standalone exploration by id — its title, SQL, chart spec, placement, and a shareable URL.                                                                                                                                         | Read-only             |
| `updateReport`     | Edits an existing workbook report or exploration in place, keeping its `reportId`. Send only the fields you want to change.                                                                                                                                     | Destructive — prompts |
| `deleteReport`     | Deletes a workbook report or exploration.                                                                                                                                                                                                                       | Destructive — prompts |
| `updateDashboard`  | Saves the dashboard layout to the workbook **draft**. Replaces the full widget set and does not go live.                                                                                                                                                        | Destructive — prompts |
| `publishDashboard` | Publishes the current draft to make it live. Idempotent — republishing an unchanged draft is a no-op.                                                                                                                                                           | Destructive — prompts |

Drafts are the safety net here: `updateDashboard` only ever writes to the draft, so a
published dashboard keeps serving its previous version until you approve
`publishDashboard`. See [Build a dashboard](#build-a-dashboard) for the full sequence.

**To change an existing report, use `updateReport` — never recreate it.** A dashboard's
chart widget points at a specific `reportId`, so replacing a report with a new one orphans
every widget referencing it. The same caution applies to moving a report between workbooks:
a widget resolves its report from its *own* workbook's report list, so changing a report's
`workbookId` empties the tiles on the old workbook's dashboard. Call `readWorkbook` and
re-point those widgets with `updateDashboard` first.

### Data model editing

These tools read and edit the semantic model **source** files. They are registered only
for users whose role grants permission to edit the semantic model — Admin and Developer by
default. Users without it never see them.

| Tool                  | Description                                                                                                                                                                     | Access                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `listDataModelFiles`  | Lists the semantic model source files (raw YAML, JavaScript, or Python).                                                                                                        | Read-only             |
| `readDataModelFile`   | Reads one file's raw source.                                                                                                                                                    | Read-only             |
| `startDataModelEdit`  | Enters [development mode][ref-dev-mode], starts a dev worker, and returns the dev `branchName` that every write tool requires.                                                  | Write                 |
| `writeDataModelFile`  | Creates or overwrites a model source file on the dev branch (whole-file replacement). Recompiles the model and reports `valid` plus any `validationError`.                      | Destructive — prompts |
| `deleteDataModelFile` | Deletes a model source file on the dev branch.                                                                                                                                  | Destructive — prompts |
| `getDataModelChanges` | Shows the diff of the dev branch against its parent — the pending changes, for review before committing.                                                                        | Read-only             |
| `getBranchDiff`       | Shows what **any** branch changed against the deploy branch: the changed-file list with per-file line counts, plus the unified diff.                                            | Read-only             |
| `getDeploymentEnv`    | Lists the deployment's environment variables, with every secret-looking value redacted to `[ENCRYPTED]`. Useful for confirming configuration is present and shaped as expected. | Read-only             |

`getDataModelChanges` answers "what have I changed?" for your own dev branch against its
immediate parent. `getBranchDiff` answers "what did this branch change?" for any branch,
including feature branches — reach for it when a change edits existing cubes, where the
file list looks identical on both branches and `listDataModelFiles` reveals nothing.

<Note>
  `getDeploymentEnv` never returns secret values. Anything that looks like a credential is
  replaced with `[ENCRYPTED]` before it leaves Cube, so an AI client can verify that a
  variable is set without ever seeing what it is set to.
</Note>

#### How model edits stay safe

Letting an AI client edit your semantic model is safe because of four constraints built
into the MCP server:

* **Edits never touch production.** Every write goes to a personal dev branch named
  `dev-<user>-<hash>`. The write tools reject any branch that isn't a dev branch, so
  the deploy branch is never writable over MCP.
* **`startDataModelEdit` is the only entry point.** It returns the dev `branchName`, and
  `writeDataModelFile` and `deleteDataModelFile` require it. There is no way to write
  without going through it first.
* **Promotion is manual and human.** To publish model changes you commit the dev branch
  from the Cube UI, as described in [Development mode][ref-dev-mode]. The MCP server
  deliberately exposes no commit tool — an AI client can prepare changes, but only a
  person can ship them.
* **Registration is permission-gated.** Every tool in the two sections above — the six
  model-editing tools, `getBranchDiff`, `getDeploymentEnv`, and both pre-aggregation
  tools — is offered only to users whose role allows editing the semantic model. A Viewer
  never sees them at all.
* **Verification happens on the branch, before a merge, not after.** Pass the dev
  `branchName` to `runQuery` to check that an edit returns the right data — `valid: true`
  from `writeDataModelFile` only means the model compiles, not that it's correct.

Review pending work with `getDataModelChanges` before you commit.

### Pre-aggregations

These tools inspect and trigger [pre-aggregation][ref-pre-aggregations] builds. They are
registered under the same semantic-model permission as the data model tools above.

| Tool                      | Description                                                                                                                                                                                        | Access    |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `getPreAggregationStatus` | Lists the data model's pre-aggregations with their definitions and, for each, how many partitions exist, how many were built, when the newest build landed, and the exact error if a build failed. | Read-only |
| `buildPreAggregation`     | Queues an on-demand build of one pre-aggregation and returns once it is accepted. The build runs asynchronously.                                                                                   | Write     |

Together these close the loop on pre-aggregation work: a query alone cannot prove a rollup
was used, and external pre-aggregations fail in configuration-specific ways — a missing
export bucket, denied bucket permissions — that only an actual build surfaces. Call
`buildPreAggregation`, then poll `getPreAggregationStatus` to see whether the partitions
built or to read the failure.

<Note>
  `buildPreAggregation` runs real queries against your data warehouse and, for external
  pre-aggregations, writes through the export bucket. It consumes warehouse resources, so
  expect a cost per build.
</Note>

## Example workflows

### Ask a data question

Ask a question in natural language and let the agent do the planning: `chat` returns the
answer along with the SQL it generated, and `loadQueryResults` pages through large result
sets. Use this for summaries, trends, and ad-hoc analysis.

To drive the query yourself instead, call `searchDataModel` to find the right view and
members, then run your own SQL with `runQuery`.

<Frame>
  <img />
</Frame>

### Build a dashboard

Four of the dashboard tools build a new dashboard, and they are designed to be used in
order. The rest — `readWorkbook`, `readReport`, `updateReport`, `deleteReport` — are for
inspecting and changing one that already exists.

<Steps>
  <Step title="Create the workbook">
    Call `createWorkbook` with a name. It returns the `workbookId` every later step needs.
    If you were given an existing workbook to build into, call `readWorkbook` instead and
    skip to the next step.
  </Step>

  <Step title="Create a report per chart">
    Call `createReport` once per chart, KPI tile, or table, passing the `workbookId` and
    the SQL query that powers it. Each call returns a `reportId`.
  </Step>

  <Step title="Lay out the dashboard">
    Call `updateDashboard` with the complete widget set, referencing each `reportId` from
    the previous step. This replaces the draft layout and saves to the workbook draft —
    the live dashboard is unchanged. Your client will ask you to confirm.
  </Step>

  <Step title="Publish">
    Review the draft, then call `publishDashboard` to make it live. This also prompts for
    confirmation. It returns the dashboard URL.
  </Step>
</Steps>

To change a dashboard later, call `readWorkbook` first and edit on top of the current
draft rather than overwriting it. To change one chart rather than the layout, call
`readReport` on the widget's `reportId` and edit it with `updateReport` — that keeps the
id, so every widget pointing at it keeps rendering.

### Edit the data model

Call `startDataModelEdit` to enter development mode and get a dev `branchName`. Explore
the current source with `listDataModelFiles` and `readDataModelFile`, then apply changes
with `writeDataModelFile` or `deleteDataModelFile`, passing that `branchName`. Each write
recompiles the model and reports validation errors, so you can iterate until it compiles.
Before committing, verify the change returns the right data: call `runQuery` with the same
`branchName` and check the numbers, since a compiling model can still return wrong results.
Review the result with `getDataModelChanges`, then commit the branch from the Cube UI to
publish it.

To review a branch you didn't author — a colleague's feature branch, say — call
`getBranchDiff` with its name instead. It compares against the deploy branch and returns
the full changed-file list even when the patch itself is trimmed.

### Verify a pre-aggregation

After adding or changing a pre-aggregation, call `getPreAggregationStatus` to see whether
its partitions exist and when they were last built. If nothing has been built yet — or you
want to confirm an external pre-aggregation's export bucket actually works — call
`buildPreAggregation`, then poll `getPreAggregationStatus` again. A failed build reports
the exact error, which is usually a configuration problem rather than a modeling one;
`getDeploymentEnv` will tell you whether the expected variables (`CUBEJS_DB_EXPORT_BUCKET`
and friends) are set.

## Troubleshooting

* **MCP configuration is unavailable**: Configure the MCP server URL.
* **MCP OAuth integration is not configured**: Enable MCP in **Admin → Team & Security → OAuth Integrations**.
* **No deployments available / MCP access is disabled**: In **Admin → MCP Server → Deployment Access**, make sure **Limit available deployments** is off, or that at least one deployment is selected and the user has permission to access it.
* **`Deployment <id> is not available via MCP for this account` (403)**: The requested deployment is excluded by the deployment-access allow-list or by the user's permissions. Call `listDeployments` to see which deployments are reachable, or adjust the allow-list in **Admin → MCP Server → Deployment Access**.

[ref-roles]: /admin/users-and-permissions/roles-and-permissions

[ref-pre-aggregations]: /docs/pre-aggregations/using-pre-aggregations

[ref-sql-api]: /reference/core-data-apis/sql-api

[ref-workbooks]: /docs/explore-analyze/workbooks

[ref-dashboards]: /docs/explore-analyze/dashboards

[ref-dev-mode]: /docs/data-modeling/dev-mode


# Cube for Excel
Source: https://docs.cube.dev/docs/integrations/microsoft-excel

Cube for Excel is the native Microsoft Excel add-in for Cube.

it works with Excel on all operating systems,
including macOS, and all platforms, including web and mobile. It doesn't integrate
with the native [PivotTable][link-pivottable] in Excel but provides a custom
[pivot table](#create-explorations-via-pivot-table) UI.

<Note>
  Available on [Enterprise plan](https://cube.dev/pricing).
</Note>

After [configuring](#configuration), [installing](#installation), and
[authenticating](#authentication) this add-in, you will be able to [create
explorations via pivot table](#create-explorations-via-pivot-table) and work with
[explorations](#work-with-explorations).

<iframe title="YouTube video" />

## Configuration

Cube for Excel uses the SQL API internally. So, the SQL API has to be
[enabled][ref-sql-api-enabled] in the Cube deployment settings.

## Installation

You have to install Cube for Excel into your Microsoft 365 organization.
To do so, navigate to its [page in the Microsoft AppSource][link-ms-appsource]
and click **Get it now**:

<Frame>
  <img />
</Frame>

You can also add this add-in to your Excel application via the **Add-ins**
button. Where this button is located depends on the [Excel version][link-excel-addins].
For example, in Excel for the web, it's located on the rightmost side of the
**Home** ribbon.

Search for `Cube for Excel (add-in)` and click **Add**:

<Frame>
  <img />
</Frame>

## Authentication

You need to authenticate Cube for Excel to retrieve data from Cube.
To do so, open the sidebar by clicking on the **Cube** button in
the **Home** ribbon. Then, click **Log in to Cube**.

A modal window with an authentication prompt will appear. Choose the deployments
that you want to work with in Microsoft Excel and click **Authorize**.
Once you see the `Access Granted` message, close the modal window.

If you want to revoke the authentication, open the add-in menu and click
**Sign out**.

## Create explorations via pivot table

To create an exploration, open the add-in and click **Create exploration**.
Then, select a Cube deployment from the drop-down. Finally,
you can start building a query by selecting a view and its members in the UI that
looks and feels like [Playground][ref-playground].

<Info>
  Cube for Excel works only with [views][ref-views], not cubes.
</Info>

If the view defines [`default_ui_filters`][ref-default-ui-filters], those
filters are pre-populated as soon as you select the view — the same way they
are in workbooks. They are a starting point, not enforcement: you can change
their values, switch operators, or remove them.

Click on members to add them to **Rows** and **Measures**, or drag a member from
the list straight onto **Rows**, **Columns**, **Measures**, or **Filters**. You
can also drag members between zones to rearrange them, or click the funnel
buttons to add members to **Filters**. A member dropped onto **Filters** has no
value yet, so it appears greyed until you set one in the **Filters** pane.
Click on **×** to remove members from a query.

<Frame>
  <img />
</Frame>

Use **Order** and **Filters** panes below to sort and filter the
data in the exploration.

If you'd like to move the exploration to a new location, click on the desired top-left
cell and then confirm with the target button under **Result location**.

<Frame>
  <img />
</Frame>

With every change to your query, Cube for Excel will update the exploration on
the sheet after a slight delay. If you'd like to minimize it, consider
implementing [pre-aggregations][ref-pre-aggs].

Writing a large result to the sheet can take a few seconds. When it does, a
progress bar appears above the run controls, tracking the write itself rather
than the query.

### Measure position and order

By default, measures nest under each value of the dimension they're paired
with — every measure for the first column value, then every measure for the
next. Open the **Display** tab to change **Measure position** to **Before
columns** to get the opposite layout: each measure spans every column value,
with all values of one measure together before moving to the next.

For example, with `Forecast Sales Units` and `Forecast Net Sales` on Measures
and a `season` dimension on Columns:

* **After columns** (default): `Q1: [Sales Units, Net Sales] | Q2: [Sales
  Units, Net Sales]`
* **Before columns**: `Sales Units: [Q1, Q2] | Net Sales: [Q1, Q2]`

The same choice applies when measures are placed on **Rows** instead (set
with **Measures on**, in the same tab) — there it's labeled **After rows** /
**Before rows**.

To change the order measures appear in within their group, drag them within
the **Measures** pane on the **Pivot** tab. Position and order are saved with
the exploration and survive **Refresh**.

When your exploration is ready, click **Save** to add it to your workspace. You
can then [work with the exploration](#work-with-explorations) from the add-in.
To discard an unsaved exploration instead, choose **Delete exploration** from
the editor's **⋮** menu.

## Work with explorations

Opening the add-in shows the current workbook's home: every exploration
placed in this workbook, grouped by sheet — a sheet isn't limited to one
placement — with each placement's range and how long ago it last refreshed.
A placement shows **Out of date** when its source exploration has been
edited since that copy was written to the sheet. Running an exploration
keeps its progress even if you close the pane before saving: it's listed
under its sheet with a **Not saved** label; if it has no sheet or anchor
yet, it appears under a top-level **Unsaved** heading instead. Reopening it
resumes exactly where you left off. The pane can also hold more than one
exploration open at once, switchable from a picker at the top.

Click **Browse all explorations** to search by name across your whole
deployment, not just the current folder — results are grouped by type and
show each item's folder location, and selecting one navigates you straight to
it.

An exploration can be placed more than once — on different sheets or at
different anchors in the same workbook, and in more than one document at
once (a Google Sheets spreadsheet and an Excel workbook simultaneously).
Hovering a row in this list shows every placement it has in the **current**
document under **Location** / **Locations**. Click **Refresh** to update all
of that exploration's placements in the current document at once; click its
title to open it and change the query, which applies to every placement.

**Refresh all**, at the top of the workbook home, refreshes every placement
in the document as a tracked run: a footer at the bottom of the pane tracks
overall progress (**N of M refreshed**) with a **Stop** button, while each
row shows **Queued**, **Refreshing…**, or **Not refreshed** with a reason if
it failed. The run keeps going if you navigate away and back; refreshes are
written one sheet at a time, so a workbook with many sheets refreshes
noticeably slower than a single placement.

If you've edited a placement's cells by hand since it last refreshed, a
banner names the affected rows and warns that the next **Refresh** will
overwrite them — its **Locate** button jumps straight to them.

A placement survives renaming the sheet it's on or the workbook it's in —
it's tracked by the sheet's and workbook's own stable ids, not by name. A
placement's anchor is a fixed cell reference, though, so it does **not**
survive rows or columns inserted above it: the visible data shifts down with
the insert, but the stored anchor doesn't move with it, so the next refresh
targets the wrong cell.

<Frame>
  <img />
</Frame>

If an exploration has filters applied, an admin can turn on **Show applied filters
in reports** (Settings → Spreadsheet Add-ins) to make the filter state
visible on the sheet itself. When enabled, a summary of active filters is
added above the table, and filtered columns are marked "(filtered)" in
their header, both when the exploration is inserted and after **Refresh**.

Saved explorations also appear in the Cube workspace. See
[Saving explorations][ref-explorations] for details.

[ref-excel]: /admin/connect-to-data/visualization-tools/excel

[link-pivottable]: https://support.microsoft.com/en-us/office/create-a-pivottable-to-analyze-worksheet-data-a9a84538-bfe9-40a9-a8e9-f99134456576

[ref-playground]: /docs/explore-analyze/playground

[ref-views]: /docs/data-modeling/views

[ref-pre-aggs]: /docs/pre-aggregations/using-pre-aggregations

[ref-default-ui-filters]: /reference/data-modeling/view#default_ui_filters

[ref-sql-api-enabled]: /reference/core-data-apis/sql-api#cube-cloud

[link-excel-addins]: https://support.microsoft.com/en-us/office/add-or-remove-add-ins-in-excel-0af570c4-5cf3-4fa9-9b88-403625a0b460

[link-ms-appsource]: https://appsource.microsoft.com/en-us/product/office/WA200008486

[ref-explorations]: /docs/explore-analyze/explore#saving-explorations


# Slack
Source: https://docs.cube.dev/docs/integrations/slack

Connect Cube to Slack for notifications and AI-powered analytics chat.

<Note>
  Available on [Premium and above plans](https://cube.dev/pricing).
</Note>

Cube's Slack integration enables two capabilities:

* **[Notifications](#notifications)** — Deliver scheduled dashboard screenshots
  to Slack channels.
* **[Slack Agent](#slack-agent)** — Let your team ask data questions directly in
  Slack and get AI-powered answers from the
  [Analytics Chat][ref-analytics-chat] agent.

## Setup

A workspace admin connects Slack from the **Settings → Integrations → Slack**
page. The setup flow authorizes Cube to interact with your Slack workspace via
OAuth.

Once connected, the admin selects:

* A **deployment** that the Slack integration will use.
* An **agent** that will respond to questions in Slack.

<Frame>
  <img />
</Frame>

## Notifications

Slack notifications post a dashboard screenshot to a Slack channel after each
[scheduled refresh][ref-scheduled-refreshes]. See [Notifications][ref-notifications]
for details on creating and configuring notification schedules.

## Slack Agent

The Slack Agent brings [Analytics Chat][ref-analytics-chat] into Slack.
Anyone in your Slack workspace can send a direct message to the Cube app and
get AI-powered answers grounded in your semantic layer — without leaving Slack.

### How it works

1. A user sends a direct message to the Cube Slack app.
2. Cube matches the user by **email address** — the email in Slack must match
   an existing Cube user.
3. An [Analytics Chat][ref-analytics-chat] session is created, and the agent
   responds in a **Slack thread**.

<Frame>
  <img />
</Frame>

Follow-up questions can be asked by replying in the same Slack thread, keeping
the conversation contextual.

### Customizing responses with rules

The agent is aware when it's responding in Slack, so you can use [rules][ref-rules]
to tailor its behavior on this surface. For example, to suppress charts in Slack
unless the user explicitly asks for one, add an `always` rule:

```markdown theme={"dark"}
<!-- agents/rules/slack-no-charts.md -->
---
type: always
---
When responding in Slack, do not include charts in the response unless the user
has explicitly asked for them.
```

### User matching

Cube identifies Slack users by their email address. For the integration to work,
a user with the **same email** must exist in both Cube and the connected Slack
workspace. Every Slack user who wants to use the agent must have a Cube account
(a Viewer role is sufficient). If no matching Cube user is found, the agent will
not respond.

### Limitations

<Warning>
  Slack Agent is in active development. The following limitations apply:

  * **DMs only** — The Slack Agent currently works only in direct messages with
    the Cube app. Channel mentions are not supported.
  * **One agent** — Only one agent can be active at a time. Admins can change the
    selected agent in the Slack integration settings.
  * **One-way message sync** — Chats initiated from Slack are visible in the Cube
    UI, and you can post messages from the Cube UI, but those messages will not
    appear in the corresponding Slack thread.
  * **Email matching required** — Users must have the same email address in both
    Cube and Slack.
</Warning>

[ref-analytics-chat]: /docs/explore-analyze/analytics-chat

[ref-notifications]: /docs/explore-analyze/notifications

[ref-scheduled-refreshes]: /docs/explore-analyze/scheduled-refreshes

[ref-rules]: /admin/ai/rules


# Snowflake Semantic Views Integration
Source: https://docs.cube.dev/docs/integrations/snowflake-semantic-views

Snowflake Semantic Views integration is available in Cube on the Enterprise plan.

<Info>
  Snowflake Semantic Views integration is available in Cube on the [Enterprise plan](https://cube.dev/pricing).
</Info>

Cube supports bi-directional integration with Snowflake Semantic Views. This integration enables you to author views in Cube and use them in Snowflake, or work with Snowflake semantic views directly in Cube. This ensures consistency between your Cube definitions and Snowflake's semantic layer, allowing teams to work in their preferred environment.

## Overview

The Snowflake Semantic Views integration provides two-way synchronization between Cube and Snowflake:

* **Pull integration**: Pull semantic views from Snowflake and turn them into cubes and views in Cube
* **Push integration**: Push Cube views into Snowflake as native semantic views

This bi-directional approach ensures that your semantic layer definitions remain consistent across both platforms, regardless of where they are authored.

## Pull Integration

From the IDE, users can pull semantic views from Snowflake and turn them into cubes and views in Cube. The pull integration generates code files with cube and view definitions in your Cube repository, making it easy to work with existing Snowflake semantic views.

### How it works

1. Connect to your Snowflake account from the Cube IDE
2. Browse available semantic views in Snowflake
3. Select the semantic views you want to import
4. Cube generates the corresponding cube and view definitions
5. The generated code files are added to your Cube repository

This allows you to leverage existing Snowflake semantic views in Cube without manual conversion, ensuring consistency between your Snowflake and Cube definitions.

## Push Integration

Alternatively, you can push Cube views into Snowflake as native semantic views. The push integration creates DDL from Cube's definitions and executes it in Snowflake, creating Snowflake Semantic Views that match your Cube schema.

### How it works

1. Select Cube views you want to push to Snowflake
2. Cube generates DDL statements from your Cube view definitions
3. The DDL is executed in your Snowflake account
4. Native Snowflake Semantic Views are created matching your Cube schema

This enables you to use Cube-authored views directly in Snowflake, maintaining consistency across both platforms.

### Cubes defined with `sql`

When a cube uses the `sql` property with a plain SQL string, Cube creates a helper
Snowflake view named `CUBE_SV_SRC_<CUBENAME>` in a configurable schema (defaults to
`PUBLIC`) and uses that view as the source for the semantic view. For example:
`sql: "SELECT id, status FROM raw.orders"`.

Note that if you're simply referencing a table, use `sql_table` instead, as it's the
recommended approach for straightforward table access (e.g., `sql_table: MY_SCHEMA.MY_TABLE`).

### Prerequisites

The push integration uses the SQL Runner to execute DDL statements in Snowflake. To
successfully create semantic views, ensure the following:

* **Enable DDL operations** for your Cube deployment. In the Cube UI, go to
  **Deployment Settings** → **Configuration** and turn on **Enable DDL operations**.
  Without this setting, the SQL Runner will reject the DDL statements that the push
  integration generates.
* The Snowflake role configured for your Cube data source (via [`CUBEJS_DB_SNOWFLAKE_ROLE`](/reference/configuration/environment-variables#cubejs_db_snowflake_role))
  has privileges to create semantic views in the target database and schema
  (`CREATE SEMANTIC VIEW` on the schema, plus `USAGE` on the parent database and schema).
  If any cube uses a plain SQL string in its `sql` property, the role also needs
  `CREATE VIEW` privileges on the schema where helper views are created (which defaults to `PUBLIC`).
* The role has `USAGE` on the warehouse specified by [`CUBEJS_DB_SNOWFLAKE_WAREHOUSE`](/reference/configuration/environment-variables#cubejs_db_snowflake_warehouse)
  and `SELECT` on the underlying tables referenced by the view.
* [`CUBEJS_DB_SNOWFLAKE_QUOTED_IDENTIFIERS_IGNORE_CASE`](/reference/configuration/environment-variables#cubejs_db_snowflake_quoted_identifiers_ignore_case)
  is set consistently with how identifiers are defined in your Cube data model. The
  default value is `false`.

If a push fails with a permissions error, verify that **Enable DDL operations** is
turned on in your deployment configuration and that the configured role has the
required privileges listed above. See [Snowflake data source configuration](/admin/connect-to-data/data-sources/snowflake)
for the full list of relevant environment variables.

### Limitations

Cube's data modeling layer is broader than what can be expressed natively in
Snowflake Semantic Views today, so not every Cube view can be pushed as-is. Views
that rely on the features below will continue to work in Cube, and the push
wizard will flag them during validation so you can adjust them or keep them in
Cube only.

When pushing a Cube view to Snowflake, the following are currently not supported:

* **Cubes with templated `sql`.** If a cube's `sql` property uses template
  expressions (e.g., Jinja or dbt `{{ source(...) }}` syntax), it can't be
  pushed. See [Cubes defined with `sql`](#cubes-defined-with-sql) for details on
  what SQL patterns are supported.
* **Cubes without a single-column primary key.** Every cube needs a
  `primary_key` dimension that resolves to a single physical column. Composite
  primary keys and primary keys defined as SQL expressions aren't supported.
* **Non-equi joins and expression-based joins.** Joins must be simple equality
  joins between columns. Function calls (e.g., `LOWER({CUBE}.user_id) = {users.id}`),
  inequality operators, `OR` conditions, and other expression-based join
  conditions can't be translated.
* **Joins that don't reference a primary key.** The referenced side of every
  join must be the primary key of the target cube. Snowflake Semantic Views
  requires referenced columns to be a primary or unique key.
* **Measure types beyond the basic aggregates.** Snowflake Semantic Views
  natively supports `count`, `count_distinct`, `sum`, `avg`, `min`, and `max`.
  Cube measures that combine other measures, apply per-measure filters, or use
  rolling windows don't have a direct equivalent and can't be pushed.
* **Advanced Cube features without a Snowflake equivalent.** Segments, access
  policies, hierarchies, time-dimension granularities, view-level filters, and
  pre-aggregations are skipped during the push.

We're working closely with Snowflake to expand coverage as Snowflake Semantic
Views evolves.

## Benefits

The Snowflake Semantic Views integration provides several advantages:

* **Consistency**: Keep your semantic layer definitions synchronized between Cube and Snowflake
* **Flexibility**: Work in your preferred environment—author in Cube or Snowflake
* **Efficiency**: Automatically generate definitions without manual conversion
* **Collaboration**: Enable teams to work in their preferred tools while maintaining consistency


# Introduction
Source: https://docs.cube.dev/docs/introduction

Cube is the agentic analytics platform for business intelligence and embedded analytics, built on an open-source semantic layer.

Cube is the agentic analytics platform built on a semantic layer. One product, two primary use cases: internal business intelligence and embedded analytics.

<iframe title="Cube: The Agentic Analytics Platform. Full Demo" />

For internal BI, data teams and business users explore data with workbooks, dashboards, and Analytics Chat — natural-language analysis grounded in a governed data model. For embedded analytics, software companies ship the same surfaces, and the underlying APIs, inside their own products to deliver customer-facing experiences.

Cube is built for both humans and AI agents:

* **Data engineers** build and maintain semantic models in code, with AI assistance.
* **Data analysts** explore deeply and get trusted answers without writing ad-hoc SQL.
* **Business users** ask questions in natural language and get answers grounded in the same data model the data team owns.
* **AI agents** like Claude, ChatGPT, or your own connect through the MCP server or Chat API to get analytics answers grounded in the same governed data model.

## How is Cube different?

At the foundation of Cube is an [open-source semantic layer](https://github.com/cube-js/cube) — **Cube Core** — that provides the shared context every consumer works from. It centralizes metric definitions, joins, access rules, and caching upstream of every BI tool, application, and AI agent that queries the data. The same Cube Core that powers Cube is what we maintain as open-source; data models port unchanged between the two.

The semantic layer is what makes AI useful. Without one, agents writing SQL against a warehouse end up with inconsistent metrics and ungoverned access — numbers that don't match how your business defines them. With one, agents get a stable, governed surface to reason over.

### Semantic SQL

Cube AI agents don't query the warehouse directly. They query the semantic layer using Semantic SQL — a Postgres-compatible interface that extends SQL with the `MEASURE` function. Every query passes through the semantic layer runtime, where it's validated against the data model and has access policies applied deterministically before reaching the warehouse.

Semantic SQL gives agents the full expressiveness of SQL to build ad-hoc derived calculations on top of governed metrics — flexibility on a stable foundation, instead of one or the other.

<Frame>
  <img />
</Frame>

### Semantic layer architecture

The semantic layer is built on four pillars: data modeling, access control, caching, and APIs.

#### Code-first

Everything in Cube — data models, configurations, access control policies — is managed as code. That brings version control, code review, CI, and isolated environments to the semantic layer, the same way modern software teams already manage application code.

Code-first also makes AI assistance practical: agents can read, propose, and edit the model through normal git workflows. Humans review the change before it lands.

#### Data modeling

The data model is the knowledge graph the platform — and any AI agent — uses to understand your business. It defines metrics, entities, joins, and how they relate, upstream of any consumer.

Cube's model is **dataset-centric**, expanding on dimensional modeling. You work with two object types:

* **Cubes** represent business entities — customers, orders, line items. They define measures, dimensions, and joins between entities.
* **Views** sit on top of cubes and present curated, query-ready datasets. Views are what data consumers — humans and agents — interact with.

Models are written in YAML or JavaScript and managed in version control.

#### Access control

Access control runs at the semantic layer, so the same policies apply to every consumer: AI agents, BI tools, embedded applications. Define the rule once; it's enforced everywhere.

Policies are code (Python or JavaScript) and range from row-level rules to fully tenant-aware models backed by different data sources.

#### Caching

Cube's caching is built on **pre-aggregations** — rollup tables declared in the data model and refreshed in the background, stored in Cube Store (Cube's distributed caching engine).

When a query comes in, Cube's aggregate awareness engine routes it to a matching pre-aggregation when one exists. This is what keeps interactive workflows fast and warehouse costs predictable.

#### APIs

The semantic layer exposes standard APIs so any consumer can plug in:

* **SQL** — Postgres-compatible, with `MEASURE` and related extensions. Any tool that talks to Postgres or Redshift can talk to Cube.
* **REST (JSON)** and **GraphQL** — for custom applications and programmatic access.
* **Meta API** — model introspection. Lets AI agents discover what's queryable, and lets BI tools auto-map to the data model.


# Folders
Source: https://docs.cube.dev/docs/organize-content/folders

Organize workbooks, dashboards, and explorations into a hierarchical folder structure for easy navigation and access control.

As your team creates workbooks, dashboards, and explorations, folders help you
keep content organized and easy to find. Folders provide a hierarchical
structure that mirrors how your team thinks about its data — by team,
project, domain, or any other grouping that makes sense.

## Creating folders

To create a folder:

1. Navigate to the **Workspace** page.
2. Click **New folder**.
3. Enter a name for the folder (up to 255 characters).
4. Click **Create**.

You can also create folders inside existing folders to build a nested
hierarchy. Open the parent folder first, then follow the same steps.

<Info>
  Folder names must be unique within the same parent folder.
</Info>

## Nesting folders

Folders support up to **10 levels** of nesting, allowing you to build
detailed hierarchies. For example:

```text theme={"dark"}
Workspace (root)
└── Marketing
    └── Campaigns
        └── Q1 2025
            └── Email Performance
```

Each level provides further categorization while keeping content accessible
through the folder tree.

## What can go in a folder

Folders can contain the following content types:

* **Workbooks** — multi-tab analyses built with the semantic layer or
  source SQL
* **Dashboards** — published views of workbook reports
* **Explorations** — saved explorations from Analytics Chat or the Explore
  page

Content that is not placed in a folder appears at the root level of your
workspace.

## Searching your workspace

Use the search box in the Workspace page toolbar to quickly find a workbook,
dashboard, or exploration by name, no matter how deeply it's nested. Results
are grouped by content type and show each item's folder location, so you can
jump straight to it without browsing the folder tree. Selecting a result
navigates you directly to that item.

## Moving content into folders

To move a workbook, dashboard, or exploration into a folder, open the
item's action menu and select **Move**. Choose the target folder from the
folder picker and confirm. You can also move items to the root level by
selecting the workspace root as the destination.

## Renaming folders

To rename a folder:

1. Open the folder's action menu.
2. Select **Rename**.
3. Enter the new name.
4. Click **Save**.

<Info>
  The new name must be unique within the same parent folder.
</Info>

## Moving folders

You can rearrange your folder hierarchy by moving folders to a different
parent:

1. Open the folder's action menu.
2. Select **Move**.
3. Choose the new parent folder (or the workspace root).
4. Confirm the move.

<Warning>
  A folder cannot be moved into one of its own subfolders.
</Warning>

## Deleting folders

To delete a folder:

1. Open the folder's action menu.
2. Select **Delete**.
3. Confirm the deletion.

<Warning>
  Deleting a folder deletes everything inside it — subfolders, workbooks,
  dashboards, and explorations — along with it; this cannot be undone.
</Warning>

If anything inside the folder has its own permissions and you don't have Full
access there too, deletion is blocked entirely and nothing is deleted.

## Folder permissions

Folder access is controlled through three permission levels:

| Level           | Allows                                                                                 |
| --------------- | -------------------------------------------------------------------------------------- |
| **Can view**    | View the folder and its contents                                                       |
| **Can edit**    | Rename the folder, move content into it, and create subfolders                         |
| **Full access** | Full control including moving and deleting the folder, and managing folder permissions |

The creator of a folder automatically receives **Full access**.

To learn how to share folders with users, groups, or your entire
organization — and how permissions are inherited by content inside
folders — see [Share content][ref-sharing].

[ref-workbooks]: /docs/explore-analyze/workbooks

[ref-dashboards]: /docs/explore-analyze/dashboards

[ref-sharing]: /docs/organize-content/sharing

[ref-roles]: /admin/users-and-permissions/roles-and-permissions


# Share content
Source: https://docs.cube.dev/docs/organize-content/sharing

Share workbooks, dashboards, and explorations with specific users, groups, or your entire organization.

Sharing content with your team keeps everyone aligned on key metrics,
reduces duplicated work, and ensures stakeholders have access to the
insights they need. Cube lets you control exactly who can see and edit
each piece of content — from individual users to your entire organization.

## What can be shared

You can share the following content types:

* **Workbooks** — share the full workbook including all tabs and reports
* **Dashboards** — share published dashboard views with stakeholders
* **Explorations** — share saved explorations from Analytics Chat, the
  Explore page, or dashboards

<Info>
  Shared explorations are also available to users through the
  [Google Sheets][ref-google-sheets] and [Microsoft Excel][ref-excel]
  integrations, allowing them to pull exploration results directly into
  their spreadsheets.
</Info>

## Access levels

Sharing permissions are organized into three levels:

| Level           | Description                                                    |
| --------------- | -------------------------------------------------------------- |
| **Can view**    | View the content and its data                                  |
| **Can edit**    | View and modify the content                                    |
| **Full access** | Full control including managing who the content is shared with |

The creator of a piece of content automatically receives **Full access**.

<Info>
  When sharing is set at the [folder level][ref-folders], content inside
  the folder inherits those permissions. See
  [Permission inheritance](#permission-inheritance) for details.
</Info>

## Sharing with users and groups

To share content with specific people or groups:

1. Open the workbook, dashboard, or exploration you want to share.
2. Click the **Share** button.
3. In the **Share** dialog, type a name or email in the search field to
   find users or [user groups][ref-groups].
4. Select the desired [access level](#access-levels) from the dropdown
   next to the user or group.
5. Click **Invite**.

Invited users and groups appear in the **People with access** list. You
can change their access level or remove their access at any time from the
same dialog.

### Changing access for existing collaborators

To update a collaborator's access level:

1. Open the **Share** dialog for the content.
2. Find the user or group in the **People with access** list.
3. Select a new access level from the dropdown next to their name.

To remove access entirely, select **Remove** from the dropdown.

## Sharing with your organization

You can make content available to everyone in your Cube Cloud account:

1. Open the **Share** dialog for the content.
2. In the **General access** section, change the setting from **Only
   people invited** to **Organization**.
3. Select the access level that all organization members should receive.

When organization-wide access is set, individual users and groups can
still be granted higher access levels. For example, the organization
might have **Can view** access while a specific team has **Can edit**.

## Permission inheritance

Permissions flow down through the [folder hierarchy][ref-folders]. When
you share a folder, all content inside it — including workbooks,
dashboards, explorations, and subfolders — inherits the folder's
permissions.

```text theme={"dark"}
Marketing (Full access for Marketing team)
├── Q1 Campaign Dashboard    ← inherits Full access
├── Revenue Workbook         ← inherits Full access
└── Weekly Reports           ← inherits Full access
    └── Week 1 Exploration   ← inherits Full access
```

### How inheritance works

* **Direct permissions override inherited ones.** If a workbook has an
  explicit permission set, that takes priority over the folder permission.
* **Closest folder wins.** When multiple ancestor folders have
  permissions for the same user, the nearest folder in the hierarchy
  determines the effective access level.
* **Inherited permissions are visible in the Share dialog.** Users and
  groups with inherited access appear in the collaborator list with an
  indication of which folder the permission comes from.

### Folder visibility

Users can see a folder if any of the following apply:

* They have been granted direct access to the folder
* They have access to a parent or child folder (ancestor folders are
  visible for navigation)
* They have access to content inside the folder

This ensures users can always navigate to content they have permission to
view, even if they don't have explicit access to every folder along the
path.

### Duplicates

Duplicating a workbook or dashboard does not carry its sharing over by
default — the copy starts visible only to you, plus anyone with access to
the folder it is created in.

When the original is shared, the duplicate dialog offers **Copy sharing
and embedding settings**. Selecting it re-grants the original's users,
groups, and organization-wide access on the copy, and carries over
[signed embedding][ref-signed-embedding] if it was enabled. Access that
the original inherits from a folder is not copied — the duplicate derives
it from the folder it is created in, like any other new content there.

The option requires **Full access** to the original, since copying its
sharing means granting that access again. With **Can edit** or
**Can view**, duplicating still works and the copy starts unshared.

## Sharing folders

Sharing a folder is the most efficient way to manage access for a
collection of related content:

1. Navigate to the folder in the **Workspace** page.
2. Open the folder's action menu and select **Share** (or open the folder
   and click the **Share** button).
3. Add users, groups, or set organization-wide access as described above.

All current and future content added to the folder will inherit its
permissions. This makes folders ideal for organizing content by team or
project, where everyone on the team needs the same level of access.

## Sharing explorations for spreadsheet integrations

When you share an exploration with a user, that exploration becomes
available in the [Google Sheets][ref-google-sheets] and
[Microsoft Excel][ref-excel] add-ins. Users can browse their shared
explorations directly from the add-in and pull the results into their
spreadsheets.

This lets analysts share governed, pre-built queries with spreadsheet
users who can refresh the data on demand without needing to use the Cube
interface.

[ref-folders]: /docs/organize-content/folders

[ref-groups]: /admin/users-and-permissions/user-groups

[ref-roles]: /admin/users-and-permissions/roles-and-permissions

[ref-google-sheets]: /docs/integrations/google-sheets

[ref-excel]: /docs/integrations/microsoft-excel

[ref-signed-embedding]: /embedding/iframe/auth/signed


# Cube Store architecture
Source: https://docs.cube.dev/docs/pre-aggregations/cube-store-architecture

How Cube Store, the distributed OLAP engine behind pre-aggregations, stores data and executes queries with sub-second latency at high concurrency.

Cube Store is the purpose-built storage and query engine that serves
[pre-aggregations](/docs/pre-aggregations). It ingests pre-aggregation data
built from your data sources, stores it in a columnar format optimized for
analytical queries, and answers queries with sub-second latency at high
concurrency.

Cube Store also plays a second role: it hosts Cube's
[cache and queue store](#cache-and-queue-store) — the in-memory cache used
for query result caching and refresh keys, and the query queue that
coordinates work across API instances and refresh workers. Both roles were
historically served by Redis; Cube Store replaced it, so a Cube deployment
needs no external cache or queue infrastructure.

This page explains how Cube Store works under the hood: the design decisions
behind it, how data is stored and partitioned, how queries are executed
across a cluster, and how the cache and queue store works.

## Why Cube Store exists

Cloud data warehouses are excellent at storing and transforming large volumes
of data at low maintenance cost, but they are not designed to serve
user-facing analytics directly. They typically fall short on:

* **Sub-second query latency** — warehouse queries take seconds to minutes.
* **High query concurrency** — most warehouses throttle at dozens of
  concurrent queries, while user-facing applications need 1000+ queries per
  second.
* **Low ingestion latency** — freshly loaded data is not immediately
  queryable at interactive speed.

Cube Store closes this gap. It sits between your data sources and your
applications, turning warehouse output into a query-optimized store that
delivers the latency and concurrency of a dedicated OLAP database while
preserving the warehouse's ease of use.

It was designed against the following requirements:

* Billions of rows as input
* Sub-second response time
* High query concurrency
* Input data always has a unique primary key
* Sources are both batch and real-time streaming
* Joins between data sources

**Technology stack:** Rust, Apache Arrow, DataFusion, Parquet, RocksDB.

## High-level architecture

```text theme={"dark"}
                        ┌──────────────┐
                        │   Cube API   │
                        └──────┬───────┘
                               │ queries
                               ▼
                        ┌──────────────┐
                        │    Router    │
                        │  (metastore) │
                        └──┬───┬───┬──┘
                           │   │   │
                    ┌──────┘   │   └──────┐
                    ▼          ▼          ▼
              ┌──────────┐┌──────────┐┌──────────┐
              │ Worker 1 ││ Worker 2 ││ Worker N │
              └────┬─────┘└────┬─────┘└────┬─────┘
                   │           │           │
                   └─────┬─────┴─────┬─────┘
                         ▼           ▼
                  ┌────────────────────────┐
                  │   Cloud object store   │
                  │   (S3 / GCS / MinIO)   │
                  └────────────────────────┘
```

A Cube Store cluster consists of a **router** and one or more **workers**:

* The **router** owns the metastore and plans queries. It also hosts the
  [cache and queue store](#cache-and-queue-store) used by Cube for query
  result caching and query queue coordination. Result merging is not done
  on the router: for each query, it delegates execution to one of the
  workers acting as the query's coordinator.
* **Workers** execute partial queries on the partitions they own and return
  results to the per-query coordinator worker.
* All persistent data lives in a **cloud object store**. Compute nodes are
  disposable and interchangeable — any worker can download the partitions it
  needs and start serving queries.

In a single-process deployment (the default in development), one process
plays all roles. See
[Running in production](/docs/pre-aggregations/running-in-production) for
cluster deployment.

## Design decisions

Cube Store's architecture follows from seven key design decisions, each
serving one or more of the requirements above:

1. **High-throughput metastore** — metadata is the most accessed data in the
   system and gets its own optimized store.
2. **Indexes are sorted copies** — sorting is the most efficient way to
   compress and filter columnar data.
3. **Auto-partitioning** — partitions split automatically to stay uniformly
   sized.
4. **Parquet as the storage format** — the industry-standard columnar format
   with min-max statistics for filter pushdown.
5. **Distributed file system as the storage layer** — storage-compute
   separation makes compute nodes disposable.
6. **Shared-nothing architecture** — workers never talk to each other, which
   removes coordination overhead and scales concurrency.
7. **Real-time in-memory chunks** — streaming rows are buffered in memory
   instead of being written to Parquet one at a time.

The following sections describe each decision.

## High-throughput metastore

The metastore holds all metadata: schemas, tables, indexes, partitions,
chunks, and background jobs. It is the most frequently accessed component in
Cube Store — small relative to the data it describes, but still reaching
tens of millions of rows, with strong read-after-write consistency
requirements and heavy read traffic alongside significant write concurrency.

RocksDB backs the metastore. Metadata entities form a hierarchy:

```text theme={"dark"}
Schema
  └─ Table
       └─ Index (one or more per table)
            └─ Partition (a sorted range of the index)
                 └─ Chunk (a fragment of a partition:
                           a Parquet file or an in-memory buffer)
```

All metadata mutations go through the router to maintain consistency.
Workers reach the metastore over the network and cache metadata locally.

## Indexes are sorted copies

Every index in Cube Store is a **sorted copy** of the table data. Sorting is
the most efficient way to compress columnar data, and it is optimal for
filtering — range predicates can skip entire blocks of data using min-max
statistics.

### How sorting affects columnar compression

In a columnar format, values of one column are stored next to each other,
and encoders exploit *local redundancy*: repeated or slowly changing
neighboring values encode into far fewer bits. Sorting is what creates that
redundancy. Consider a column of product categories in arrival order versus
sorted order:

```text theme={"dark"}
Unsorted:  books, toys, books, garden, toys, books, garden, toys, ...
Sorted:    books, books, books, garden, garden, toys, toys, toys, ...
```

The unsorted column has to be stored more or less value by value. The
sorted column collapses into a handful of runs — effectively
`books×3, garden×2, toys×3` — regardless of how many million rows it spans.
Concretely, sorting feeds each of the standard columnar encodings:

* **Run-length encoding (RLE).** Sorted low-cardinality columns become a
  short list of `(value, count)` pairs. A column with 20 distinct values
  across a billion rows compresses to almost nothing.
* **Dictionary encoding.** Values are replaced by small integer codes into
  a dictionary. Sorting makes the code sequence itself highly repetitive,
  so the RLE applied on top of the codes compresses further.
* **Delta encoding.** A sorted numeric or timestamp column is
  monotonically non-decreasing, so storing differences between neighbors
  yields tiny, similar numbers that pack into a few bits each.

The effect cascades down the sort key: the first key column is perfectly
sorted, and within each of its runs the second column is sorted too, and so
on. Columns *not* in the sort key still benefit whenever they correlate
with key columns (for example, `city` correlating with `country`).

Smaller files are not just a storage win — they are a latency win. Scan
speed is bounded by bytes read, and general-purpose compression applied on
top works better on already-regular data. The same property also tightens
min-max statistics: in sorted data, each block covers a narrow, mostly
disjoint slice of the key space, so pruning can rule blocks out with
precision instead of finding every block's range overlapping every query.

Because all data is sorted, every operation in the engine can be
merge-based: merge sort, merge join, and merge aggregation all work
naturally on pre-sorted inputs without expensive hash tables or shuffles.

Cube Store deliberately pays **write amplification** (maintaining several
sorted copies of the same data) to buy read speed. Indexes are selected
based on query filters: the planner examines the `WHERE` clause and picks
the index whose sort key best matches the filtered columns. This is why
[defining indexes](/docs/pre-aggregations/using-pre-aggregations) that match
your query patterns is the single most effective pre-aggregation
optimization.

### Aggregating indexes

Cube Store supports two index types: **regular** and **aggregating**.

A regular index is a sorted copy of every row in the table. An
[aggregating index](/docs/pre-aggregations/using-pre-aggregations#aggregating-indexes)
goes further: it stores only the dimensions listed in its definition plus
pre-aggregated measures, rolling the data up over every dimension that is
*not* in the index. It is effectively a rollup of the rollup, maintained
incrementally by the storage engine itself.

Each measure column in an aggregating index carries an aggregate function
that defines how rows with the same sort key combine:

| Function      | Used for                                       |
| ------------- | ---------------------------------------------- |
| `SUM`         | Additive measures (`sum`, `count`)             |
| `MIN` / `MAX` | Minimum / maximum measures                     |
| `MERGE`       | HyperLogLog sketches (`count_distinct_approx`) |

The rollup does not happen at query time. Whenever chunks are merged
during compaction, Cube Store runs the merged, sorted stream through a
group-by on the index's sort key and applies the aggregate functions —
rows with equal dimension values collapse into one. Because the data is
already sorted by the grouping columns, this aggregation is a cheap,
streaming merge rather than a hash aggregation.

The result: a query that matches an aggregating index reads a table that is
often orders of magnitude smaller than the parent pre-aggregation, and the
aggregation work has already been paid for at ingestion time.

Note that this is also why aggregating indexes only support additive
aggregate functions — a non-additive measure (such as an exact distinct
count) cannot be combined incrementally from partial rollups.

## Auto-partitioning

### Partition key space and ranges

An index's sort key defines a totally ordered **key space**, and each
partition owns a contiguous range of it. A partition's range is described
by two bounds, where an absent bound means "unbounded":

```text theme={"dark"}
Key space of an index sorted by (created_at, user_id):

  ├────────────────┼────────────────┼────────────────┤
  Partition 1       Partition 2      Partition 3
  (−∞ .. K₁)        [K₁ .. K₂)       [K₂ .. +∞)
```

Two properties of ranges matter in practice:

* **Range bounds vs. data bounds.** Alongside its range (the keys it *may*
  contain), each partition tracks the actual minimum and maximum key
  present in its data. Pruning uses the tighter of the two, so a partition
  with a wide range but sparse data is still skipped effectively.
* **The partition split key.** Ranges are defined over a *prefix* of the
  sort key, called the split key. Rows that share the same split key value
  are guaranteed to land in the same partition — they are never spread
  across two partitions. This keeps range boundaries clean and lets the
  engine reason about a partition as a self-contained unit of work.

A freshly created table starts with a single partition covering the entire
key space (both bounds unbounded). Partitions never split on ingestion —
splitting is deferred to compaction, when the data is being rewritten
anyway.

### Partition splits

During compaction, Cube Store checks whether the partition has outgrown its
split threshold and, if so, writes the merged output into several new
partitions instead of one:

```text theme={"dark"}
Before compaction:                    After split at compaction:

  Partition [K₁ .. K₂)                Partition [K₁ .. S₁)
  ┌───────────────────────┐           Partition [S₁ .. S₂)
  │ main file + N chunks  │    ──►    Partition [S₂ .. K₂)
  └───────────────────────┘
```

The number of child partitions is computed from both row count and file
size:

* **By rows:** total pending rows divided by the split threshold
  (`CUBESTORE_PARTITION_SPLIT_THRESHOLD`, default 2,097,152 rows; can also
  be set per pre-aggregation).
* **By size:** the partition's file size divided by the size threshold
  (`CUBESTORE_PARTITION_SIZE_SPLIT_THRESHOLD`, default 100 MiB).

The larger of the two wins, capped at 16 children per compaction pass to
bound write amplification. Because the merged output is sorted, the split
points fall out naturally: the writer streams rows into the first file
until it reaches its row budget, closes it at the next split-key boundary,
and moves on. Each child's range bounds are derived from the actual first
and last keys written to it.

Uniform partition sizes keep query work evenly distributed across workers
and make partition pruning predictable.

## Parquet as the storage format

All persistent data is stored as Parquet files. Parquet implements the PAX
(Partition Attributes Across) layout: rows are grouped into row groups, and
values within a row group are stored column by column. This gives columnar
compression and scan speed while preserving efficient row reconstruction.

Cube Store leans on Parquet's **min-max statistics**: every row group
records the minimum and maximum value of each column. Combined with sorted
data, this lets the query planner skip partitions — and row groups within
partitions — whose ranges cannot match the query's filters, often
eliminating most of the data before reading a single byte.

## Distributed file system as the storage layer

Cube Store separates storage from compute. All Parquet files live in a
cloud object store (S3, GCS, MinIO, or a local directory in development),
and workers keep local copies only as a cache.

This has several consequences:

* **Workers are disposable.** A worker that dies is replaced by a new one
  that downloads the same partitions and continues serving.
* **Replication is simple.** The object store is the single source of truth.
* **Scaling is elastic.** Adding workers redistributes partitions without
  moving the underlying data.

To avoid download latency on the query path, Cube Store performs a
**partition warmup**: before a table comes online, every worker downloads
the partitions assigned to it. Queries never wait for a cold download.

## Shared-nothing architecture

Worker nodes never communicate with each other. Each worker owns a set of
partitions, assigned deterministically by consistent hashing over the
partition's range and index. Every node computes the same assignment
independently — no coordination service is needed.

A query executes as follows:

```text theme={"dark"}
                    Router
                      │  distribute plan
          ┌───────────┼───────────┐
          ▼           ▼           ▼
       Worker 1    Worker 2    Worker N
       ┌───────┐   ┌───────┐   ┌───────┐
       │Parquet│   │Parquet│   │Parquet│   ← persisted data
       ├───────┤   ├───────┤   ├───────┤
       │Memory │   │Memory │   │Memory │   ← real-time data
       │chunks │   │chunks │   │chunks │
       └───┬───┘   └───┬───┘   └───┬───┘
           │  partial   │  partial │
           │  results   │  results │
           └──────┬─────┴─────┬────┘
                  ▼           ▼
             ┌──────────────────────┐
             │ Coordinator: merge   │
             │ sorted streams,      │
             │ finalize aggregation,│
             │ LIMIT                │
             └──────────────────────┘
```

Workers do as much as possible locally: they prune partitions with min-max
statistics, scan Parquet and in-memory chunks, and compute **partial
aggregations**. The coordinator receives already-aggregated partial
results and only needs to merge them — merging sorted streams is cheap, so
coordination never becomes a data-processing bottleneck.

The coordinator here is itself one of the workers, chosen per query — not
the router node that hosts the metastore, which only plans queries and
relays results (see
[One plan, two physical plans](#one-plan-two-physical-plans)).

This is also how [lambda pre-aggregations](/docs/pre-aggregations/lambda-pre-aggregations)
work: a single query transparently combines persisted Parquet data with
fresh streaming data held in memory on the same workers.

## Real-time in-memory chunks

Streaming sources (such as Kafka) deliver rows continuously, but writing
single rows to Parquet would be prohibitively expensive. Instead, incoming
rows are routed to the worker that owns the target partition and buffered
there as **in-memory chunks** — columnar Arrow buffers that are immediately
queryable.

```text theme={"dark"}
Streaming source ──► Router ──► partition owner worker
                                      │  in-memory chunks
                                      │  (queryable immediately)
                                      ▼  compacted at ~1-minute intervals
                                 Parquet partition in object store
```

In-memory chunks are compacted into persisted Parquet partitions at roughly
one-minute intervals, or sooner when count or size thresholds are exceeded.
During compaction, Cube Store sorts the data, deduplicates rows by unique
key, and evaluates aggregate columns — so unique-key semantics hold across
batch and streaming data alike. See
[Compaction in detail](#compaction-in-detail) for the full process.

## Real-time deduplication by unique key

One of Cube Store's founding requirements is that input data always has a
unique primary key. Streaming sources exploit this: an update to a row
arrives simply as a *new version* of the same key. Cube Store never updates
data in place — chunks and partitions are immutable — so upsert semantics
are implemented as **last row by unique key**: among all stored versions of
a key, the newest one wins. Deduplication happens twice: logically on every
read, and physically at compaction.

### Version ordering with the sequence column

Tables with a unique key carry a hidden, monotonically increasing sequence
column, `__seq`. For streaming tables it is derived from the source's own
ordering (such as Kafka offsets), so "newest" reflects the order in which
the source emitted the versions.

Two structural guarantees make deduplication cheap:

* **Every index sort key ends with the unique key and `__seq`.** When an
  index is created on a unique-key table, any unique key columns missing
  from its definition are appended to the sort key, followed by `__seq` as
  the final sort column. All versions of a key are therefore physically
  adjacent in every sorted file, with the newest version last.
* **`__seq` is excluded from the partition split key.** Partitions may
  split on the unique key, but never *between* versions of the same key —
  all versions of a key always live in the same partition, and therefore
  on the same worker. Deduplication never requires cross-worker
  coordination, preserving the shared-nothing model.

### How it is read

A query against a unique-key table dedupes on the fly, seeing streamed
updates the moment they arrive:

1. **The scan projection is widened.** Even if the query only asks for a
   measure, the scan also reads the unique key columns and `__seq` — they
   are needed to decide which version of each row survives.
2. **Only dedup-safe filters are pushed below deduplication.** A predicate
   that references unique key columns exclusively can be applied early to
   each stream: it eliminates a key with *all* of its versions. A
   predicate on any other column cannot — filtering on a measure value
   before deduplication could drop the newest version and resurrect an
   overwritten one. Non-key predicates are applied after deduplication.
3. **All sources merge into one sorted stream.** The partition's main
   Parquet file, its persisted chunks, and its in-memory chunks are each
   already sorted; a k-way merge combines them, ordered by the sort key
   with `__seq` last. Versions of the same key from different sources —
   an old version in Parquet, a fresh update in memory — end up adjacent,
   newest last.
4. **A streaming last-row filter drops stale versions.** The operator
   walks the merged stream and keeps a row only if the next row has a
   different key (comparing across batch boundaries as well). Since
   versions are adjacent and the newest sorts last, this keeps exactly the
   latest version of every key, in a single pass with no hash table.

The plan then re-projects to the columns the query actually asked for.
The extra cost over a plain scan is modest: the merge was needed anyway,
and the last-row filter is a linear scan over already-sorted data.

### How it is compacted

Compaction runs the very same merge-plus-last-row pipeline (see
[Compaction in detail](#compaction-in-detail)): chunks and the main file
are merged in sort order, the last-row filter keeps only the newest
version of each key, and the result is written out. The difference is
what happens to the output — it *replaces* the inputs, so superseded
versions are physically deleted.

This division of labor keeps read-time deduplication bounded. At any
moment, a key has at most one version in the compacted main file plus
however many updates arrived since the last compaction — and compaction
continuously folds those in. Read-time dedup only ever pays for the
recent, not-yet-compacted tail, while storage converges toward exactly
one row per key.

Note that unique-key deduplication and
[aggregating indexes](#aggregating-indexes) are mutually exclusive ways of
merging rows: a regular index on a unique-key table keeps the last version
per key, while an aggregating index combines rows with aggregate
functions.

## Query planning

Cube Store builds on [DataFusion](https://datafusion.apache.org), the
Arrow-native query engine, and extends it with distribution-aware planning.
All planning happens on the router; the outcome is a plan split into a
router part and a worker part at an explicit cluster boundary.

### From SQL to a logical plan

The SQL text is parsed into an abstract syntax tree and converted into a
DataFusion logical plan — a tree of relational operators (scan, filter,
project, aggregate, sort, limit). At this stage, table scans are
placeholders: no index has been chosen and no partitions are attached yet.
DataFusion's standard logical optimizations run here, most importantly
pushing filters and projections down toward the scans, which sets up the
constraint collection that follows.

### Index selection

The planner walks the optimized plan and collects, for every scanned
table, the constraints relevant to choosing an index:

* filter predicates that reached the scan,
* the set of projected columns,
* the aggregates being computed,
* sort requirements imposed by joins or `GROUP BY`.

It then fetches all candidate indexes for all referenced tables from the
metastore in a single round trip and picks the winner per table:

1. **Eligibility.** For joins, an index qualifies only if the join columns
   form a prefix of its sort key — that is what makes a merge join
   possible. An [aggregating index](#aggregating-indexes) qualifies only
   if it covers every projected column, every filtered column, and every
   requested aggregate; otherwise it cannot answer the query at all.
2. **Scoring.** Among eligible indexes, an aggregating index always beats
   a regular one (it is strictly smaller). Ties are broken by how early
   the query's filter columns appear in the index sort key, then by how
   early the projected columns appear. Earlier is better: a filter on the
   leading sort key column narrows the scan to a contiguous range, while
   the same filter on a trailing column cannot skip anything.
3. **Joins.** Every joined table must have an index sorted by the join
   key. If no suitable index exists for a join, planning fails with an
   error that includes the exact `CREATE INDEX` statement to fix it —
   distributed joins without a matching index would require a data
   shuffle or a query-time sort, which Cube Store deliberately does not
   do. See [Distributed joins](#distributed-joins) for the full
   mechanics.

With indexes chosen, the planner attaches the concrete partition list to
each scan, applying partition pruning as it goes, and inserts a
**cluster send** node into the plan above the scans. That node marks the
boundary: everything below it will run on workers, everything above it on
the router.

### Partition pruning

Partition pruning happens on the router at planning time, before any work
is distributed. The goal is to touch only the partitions whose key ranges
can possibly satisfy the query.

The planner converts the query's `WHERE` clause into a set of **min-max
conditions** over the index's sort key columns. Each condition is a pair of
per-column lower and upper bounds; the whole filter is a union of such
conditions (an OR across them). The extraction understands:

* Comparison operators: `=`, `<`, `<=`, `>`, `>=`
* `IN` lists (each value becomes its own condition)
* `AND` / `OR` combinations of the above
* Boolean columns used directly in predicates

Anything the extractor cannot represent as a range over sort key columns —
functions on columns, predicates on non-key columns, and so on — is simply
left out. That is always safe: pruning may only ever *over*-include
partitions, never skip one that holds matching rows. The remaining
predicates are still applied during the scan.

Each partition's `[min, max]` key interval is then checked against the
conditions with a lexicographic comparison, mirroring how the data is
sorted. If no condition can intersect the partition's interval, the
partition is dropped from the plan — its worker never sees it, and its
files are never opened.

Pruning applies at three successively finer levels:

1. **Partitions** are pruned on the router at planning time, using
   metastore-tracked min/max keys.
2. **Chunks** within a surviving partition are pruned the same way, using
   per-chunk min/max keys.
3. **Row groups** within a Parquet file are pruned at scan time on the
   worker, using Parquet's per-row-group min-max statistics.

Combined with sorted data — which makes ranges tight and non-overlapping —
this typically eliminates the vast majority of data for selective queries
before a single byte is read.

### Distribution-aware rewrites

Before the plan is finalized, Cube Store rewrites it so that as much work
as possible lands below the cluster boundary:

* **Aggregate pushdown.** An aggregation above the boundary is split into
  a *partial* aggregation on the workers and a *final* aggregation on the
  router. Workers send compact partial states (for example, per-group sums
  and counts) instead of raw rows.
* **Top-k pushdown.** The `GROUP BY … ORDER BY … LIMIT n` pattern is
  rewritten into a distributed top-k: each worker computes its local
  candidates and the coordinator merges them, instead of materializing the
  full grouped result.
* **Limit pushdown.** Plain limits propagate to workers so they stop
  producing rows early.
* **Sorted (streaming) aggregation.** Where the chosen index's sort order
  matches the grouping columns, hash aggregation is replaced with a
  streaming merge aggregation that emits groups as it goes and needs no
  hash table.

### One plan, two physical plans

The rewritten logical plan — along with the chosen index snapshots and
partition lists — is serialized once and shipped to every participating
worker. Each side then builds its own physical plan from it:

* The **router plan** is the part above the cluster boundary: receiving
  worker streams, merging them (sort-preserving where order matters),
  final aggregation, and the final limit.
* A **worker plan** is the part below the boundary for one worker's subset
  of partitions: scanning local Parquet files and in-memory chunks,
  applying remaining filters, and computing partial aggregates.

Workers are assigned their partition subsets by the same consistent
hashing that governs data placement, so the plan always executes where the
data already lives. Execution streams Arrow record batches from the
workers to the node executing the router plan, which merges and returns
the result.

Importantly, "router plan" names a *role* in the plan, not the router
node. In a multi-node cluster, the actual router node — the one hosting
the metastore — does not execute the router plan itself. For each query,
it picks one of the workers at random and delegates the router plan to
it: that worker becomes the query's coordinator, fanning the worker plans
out to its peers (including possibly itself), merging their streams, and
running the final aggregation and limit. The true router only plans the
query and passes the finished result through.

This has two effects. The metastore node — a shared dependency of the
whole cluster — is kept free of heavy data processing, so a large merge
never degrades metadata operations for everyone else. And because the
coordinator is re-picked per query, the merge workload itself is load
balanced across the cluster rather than concentrating on a single node.

### Planning walkthrough

Putting it all together for a typical query:

```sql theme={"dark"}
SELECT product_category, SUM(order_total)
FROM orders_rollup
WHERE created_at >= '2026-01-01'
GROUP BY 1
ORDER BY 2 DESC
LIMIT 10
```

1. Parse and build the logical plan; push the `created_at` filter down to
   the scan.
2. Collect constraints and pick the best index — say, an aggregating index
   sorted by `(created_at, product_category)`.
3. Prune partitions to those whose key ranges intersect
   `created_at >= '2026-01-01'`.
4. Insert the cluster boundary; rewrite the aggregation + sort + limit
   into a distributed top-k.
5. Ship the serialized plan; each worker scans its surviving partitions,
   aggregates partially, and returns its top candidates.
6. The coordinating worker merges the candidates, finalizes the
   aggregation, applies `LIMIT 10`, and returns the result.

The resulting distributed physical plan looks like this (with the top-k
rewrite left out for clarity — shown as a plain distributed aggregation
over six surviving partitions and three workers):

```text theme={"dark"}
        Router node (metastore)
        plans the query, picks Worker 2 as coordinator
                           │
                           ▼
        Worker 2 — executes the router plan
        ┌─────────────────────────────────────┐
        │ Projection                          │
        │  └─ InlineAggregate (Final)         │
        │      └─ SortPreservingMerge         │
        │          └─ ClusterSend             │
        └────────┬──────────┬──────────┬──────┘
                 │          │          │  worker plans
                 ▼          ▼          ▼
        ┌────────────┐ ┌────────────┐ ┌────────────┐
        │  Worker 1  │ │  Worker 2  │ │  Worker 3  │
        │            │ │            │ │            │
        │ InlineAgg  │ │ InlineAgg  │ │ InlineAgg  │
        │  (Partial) │ │  (Partial) │ │  (Partial) │
        │ └─ Filter  │ │ └─ Filter  │ │ └─ Filter  │
        │  └─ Merge  │ │  └─ Merge  │ │  └─ Merge  │
        │   ├─ P1    │ │   ├─ P2    │ │   ├─ P3    │
        │   ├─ P4    │ │   ├─ P5    │ │   ├─ P6    │
        │   └─ mem   │ │   └─ mem   │ │   └─ mem   │
        │     chunks │ │     chunks │ │     chunks │
        └────────────┘ └────────────┘ └────────────┘
          P1..P6 — pruned-in partitions, assigned to
          workers by consistent hashing
```

Reading it bottom-up: each worker merges its partitions' sorted streams —
Parquet files and in-memory chunks together (the lambda architecture
query) — filters them, and computes a partial streaming aggregation. The
coordinating worker (Worker 2 here, which also processes its own share of
partitions) merges the three sorted partial streams, finalizes the
aggregation, and returns the result through the router.

## Distributed joins

Cube Store supports joins between tables, with two properties that follow
directly from its merge-based, shared-nothing design: every joined table
must have an index on the join key, and the join is distributed so that
workers execute it locally.

### Joins require an index on the join key

Cube Store executes joins exclusively as **merge joins** — hash joins are
disabled. A merge join consumes two streams that are both sorted by the
join key and zips them together in a single linear pass, with no hash
table to build and no memory proportional to the input size. This is the
same principle that runs through the whole engine: every operation is
merge-based over sorted data.

The sorted inputs have to come from somewhere, and re-sorting billions of
rows at query time would defeat the purpose. So the planner requires each
side of a join to be scanned through an index whose **sort key starts with
the join columns** — the join columns must form a prefix of the index sort
key, in order. Such a scan produces join-key-ordered output for free, and
the merge join can start streaming immediately.

If no such index exists on one of the joined tables, planning fails
immediately with an error that spells out the fix, including the exact
`CREATE INDEX` statement to run. This is deliberate: the alternative —
silently falling back to a sort or shuffle — would turn a sub-second query
into a multi-second one, and Cube Store treats that as an error rather
than a degradation.

### How the join is distributed

The join itself runs entirely on the workers, below the cluster boundary.
When both sides of a join resolve to worker-bound scans, the planner
places the join *under* a single cluster-send node — so each worker joins
its own data locally and the coordinator merely merges already-joined
results.

Since the joined tables are partitioned independently, their partition
boundaries don't line up, so work is batched by the left-most (root)
table: the root table's partitions are split across batches, and **every
right-side table is included in full in every batch**. Including the right
side whole is required for correctness — batching a right table would make
a `LEFT JOIN` produce spurious `NULL`s and duplicates — but it means the
right side is effectively replicated into each batch. This works well when
the right side is small (dimension tables joined to a large fact table)
and poorly when both sides are large. A configurable guard
(`CUBESTORE_MAX_JOINED_PARTITIONS`, default 5 partitions per batch) fails
the query fast when the right side is too fragmented, rather than letting
it fan out into an expensive execution.

Each worker then executes the same plan: scan its batch's partitions
through the join-key indexes (each stream already sorted), merge-join
them, apply whatever partial aggregation was pushed down, and stream
results to the coordinator.

## Compaction in detail

Ingestion optimizes for write latency: every batch or streaming buffer
becomes a new **chunk** — a small, independently sorted file (or in-memory
buffer) attached to a partition. Queries, however, want few large sorted
files. Compaction is the background process that continuously converts the
former into the latter. It runs at two levels.

### In-memory chunk compaction

Streaming ingestion produces many tiny in-memory chunks. A scheduled job
checks each partition and compacts its in-memory chunks when either:

* the number of in-memory chunks exceeds a count threshold, or
* the oldest buffered row exceeds a lifetime threshold
  (`CUBESTORE_IN_MEMORY_CHUNKS_MAX_LIFETIME_THRESHOLD`, default 60
  seconds).

Chunks that are still small and young are merged into a single larger
in-memory chunk (staying queryable in RAM); chunks that have grown past the
size limit or aged past the lifetime threshold are merged and written out
as persistent Parquet chunks. This is the \~1-minute cadence at which
streaming data flows from memory into durable storage.

### Persistent chunk compaction

A per-partition compaction job merges accumulated Parquet chunks into the
partition's main file:

1. **Select chunks.** Pending chunks are taken smallest-first, up to a
   total row budget (`CUBESTORE_CHUNKS_TOTAL_SIZE_THRESHOLD`, default
   2,097,152 rows) and an on-disk byte budget. Taking the smallest chunks
   first maximizes the reduction in file count per unit of work.
2. **Merge as sorted streams.** The partition's main file and every
   selected chunk are each already sorted, so they are merged with a
   streaming k-way merge — no re-sorting, no materializing the inputs in
   memory. Compaction cost is proportional to bytes streamed.
3. **Deduplicate or aggregate.** On the merged stream:
   * For tables with a unique key, only the **last row per unique key** is
     kept — this is how upserts and streaming updates resolve, with later
     ingestion winning (see
     [Real-time deduplication by unique key](#real-time-deduplication-by-unique-key)).
   * For aggregating indexes, rows are grouped by the sort key and the
     aggregate functions (`SUM`, `MIN`, `MAX`, `MERGE`) combine matching
     rows — this is where the incremental rollup happens.
4. **Split if needed.** If the partition has outgrown its thresholds, the
   output is written into several child partitions
   (see [Partition splits](#partition-splits)); otherwise into a single
   rewritten main file. Writers cut files only at split-key boundaries.
5. **Upload and swap atomically.** New files are uploaded to the object
   store, then a single metastore transaction deactivates the parent
   partition and consumed chunks and activates the children with their
   computed key ranges. Any query planned before the swap still sees the
   old files; any query planned after sees the new ones. There is no
   window of inconsistency, and old files are garbage-collected later.

If data arrives faster than one compaction pass can absorb, the cycle
simply repeats: each pass halves the file count or splits the partition
further, converging toward a small number of large, sorted,
uniformly-sized files per partition.

## Cache and queue store

Beyond storing pre-aggregations, Cube Store hosts a second, independent
subsystem: the **cache and queue store**. It is the engine behind Cube's
in-memory cache (query result caching, refresh keys) and the **query
queue** that coordinates query execution across Cube nodes. Historically
these roles were played by Redis; Cube Store replaced it, removing an
entire moving part from the deployment.

The cache and queue store lives on the router node and is backed by its own
RocksDB instance, fully separate from the metastore. Hot entries are served
from memory (RocksDB memtables and block cache), while the disk backing
means the cache and any in-flight queue state survive a router restart.
Cube talks to it over the same SQL interface as everything else, using
dedicated `CACHE` and `QUEUE` command families.

### Cache

The cache is a Redis-style key-value store. Each entry has:

* a path of the form `prefix:key`, so related entries (for example, all
  refresh keys of one deployment) can be listed and truncated by prefix,
* a string value,
* an optional TTL, after which the entry expires.

Because unbounded caches eventually eat their host, a background eviction
manager enforces two budgets: a total size limit
(`CUBESTORE_CACHE_MAX_SIZE`, default 4 GiB) and a key count limit
(`CUBESTORE_CACHE_MAX_KEYS`, default 100,000). When a budget is exceeded,
it evicts entries according to a configurable policy
(`CUBESTORE_CACHE_POLICY`):

| Policy                                        | Keeps                                          |
| --------------------------------------------- | ---------------------------------------------- |
| `allkeys-lru` (default)                       | Most recently used entries                     |
| `allkeys-lfu`                                 | Most frequently used entries                   |
| `allkeys-ttl`                                 | Entries with the most remaining time-to-live   |
| `sampled-lru` / `sampled-lfu` / `sampled-ttl` | Same criteria, evaluated on a sample for speed |

To support this, every entry tracks a last-access timestamp and an access
frequency counter. Expired entries are also collected proactively in the
background rather than only on access.

### Query queue

The query queue is how Cube serializes and prioritizes expensive work —
data source queries and pre-aggregation builds — across any number of API
instances and refresh workers. Centralizing the queue in Cube Store is what
makes those nodes stateless and horizontally scalable: any node can add
work, process work, or pick up results, because the queue state lives in
one place.

There is not one global queue but one queue per workload, separated by key
prefix: each data source gets its own query queue, and pre-aggregation
builds run through their own queue. Each queue has its own concurrency
budget and its own ordering.

Every queue item carries a key, a payload (the serialized query), a
priority, and a status that moves through a simple lifecycle:

```text theme={"dark"}
  Pending ──► Active ──► Finished
     (added)    (claimed by a          (acknowledged with
                 processing node)       a result)
```

Pending items are picked by priority (from `-10000` to `10000`, higher
first), with older items winning ties — a priority queue with FIFO
fairness.

#### Idempotency

A queue item's key is a deterministic hash of the query itself — the SQL,
its parameters, and the security context that shapes it. Identical queries
always hash to the same key, and adding to the queue is an atomic
*insert-if-absent* on that key: the first request creates the item, and
every subsequent identical request — from the same API instance or any
other — matches the existing item instead. Cube Store reports back whether
the item was actually created, so the orchestrator knows whether it is the
originator or just another waiter.

The result path is deduplicated the same way. Before adding to the queue at
all, an API instance checks whether a result for that key is already
available from a just-finished execution. After adding, all waiters —
however many instances they are spread across — block on the same key and
wake on the same result.

The net effect: a dashboard fanning the same expensive query out through a
dozen concurrent requests costs exactly one data source execution.

#### How API instances coordinate scheduling

There is no dedicated scheduler node. Every API instance and refresh worker
runs the same **reconciliation loop** against the shared queue — after
adding an item, when a blocked wait times out, and on a background
interval. Reconciliation does two things:

1. **Cancel dead work** — query stalled and orphaned items (see below) and
   cancel them.
2. **Start new work** — read the queue's active and pending lists, compute
   how many more items may run (the concurrency budget minus currently
   active items), and attempt to claim that many pending items, in
   priority order.

Because many instances reconcile the same queue concurrently, several of
them may attempt to claim the same pending item at once. The claim itself —
`QUEUE RETRIEVE` — is an atomic compare-and-act inside Cube Store: it
re-checks the concurrency budget and flips the item from `Pending` to
`Active` in a single serialized write. Exactly one instance wins the race
and receives the payload; the others get a "not enough concurrency" or
"already taken" response and simply move on. Coordination requires no
locks, no leader election, and no scheduler — the queue itself is the
synchronization point.

When a queue is already saturated (active count at the concurrency limit),
reconciling instances limit themselves to a single claim attempt rather
than trying to grab a full budget's worth — this keeps a large cluster from
stampeding the queue with doomed claim attempts.

#### What the concurrency number actually means

The `concurrency` you configure for a data source is a **cluster-wide cap
on simultaneously executing queries for that queue** — not a per-node
setting. If concurrency is 4 and you scale from one API instance to ten,
at most 4 queries run against the data source at any moment; the ten
instances merely compete to be among the claimants. The cap is enforced
atomically at claim time inside Cube Store — an item is only flipped to
`Active` if the queue's active count is below the cap — so it cannot be
overshot by racing nodes.

This is exactly the semantics you want for protecting a data source with
a connection or workload limit: scaling out the Cube tier never multiplies
the pressure on the warehouse behind it.

#### Execution, heartbeats, and results

The instance that wins a claim executes the query — dispatching it to the
data source or running the pre-aggregation build. While the query runs,
the processor **heartbeats** the queue item on a fixed interval (30 seconds
by default), continuously proving that the work is still alive.

On completion, the processor **acknowledges** the item with its serialized
result. The acknowledgment atomically stores the result, finishes the
item, and fires an event. Waiters use a blocking read (`QUEUE
RESULT_BLOCKING`) that subscribes to that event: they wake the moment the
result lands, with no polling interval to pay for.

A blocking wait does not hold an API request open forever. If the result
does not arrive within the continue-wait window (10 seconds by default),
the API responds with `Continue wait` and the client re-requests; the
re-request finds the queue item already present (idempotency again) and
resumes waiting. Long-running queries thus survive any number of HTTP
request cycles without ever being re-executed. Delivered results are
garbage-collected after a configurable expiry.

#### Stalled and orphaned queries

Two failure modes are handled by reconciliation, both detected from
timestamps Cube Store keeps on each item:

* **Stalled queries** are `Active` items whose heartbeat has gone quiet
  for longer than the heartbeat timeout (4× the heartbeat interval — two
  minutes by default). This means the node that claimed the query died
  mid-execution: a crashed process, a killed pod, a network partition.
* **Orphaned queries** are `Pending` items that outlived their orphaned
  deadline (set when the item is added; 120 seconds by default). This
  typically means everyone who cared about the result has gone away —
  clients disconnected and stopped re-requesting — so executing the query
  would be wasted work.

Any reconciling instance can collect both kinds via a single queue call,
remove them, and invoke the registered cancel handlers — which, for a
stalled data source query, also issues the kill/cancel against the
warehouse so a dead node's query does not keep burning warehouse compute.

Because detection is timestamp-based and cancellation is idempotent, it
does not matter which instance notices first: recovery works even if the
failed node never comes back.

### Message size limits

Cube talks to the cache and queue store over a WebSocket connection, and
every cache entry, queue payload, and query result crosses it as one
message. That transport has a hard ceiling:

| Limit                  | Environment variable                   | Default | Allowed range                        |
| ---------------------- | -------------------------------------- | ------- | ------------------------------------ |
| Transport message size | `CUBESTORE_TRANSPORT_MAX_MESSAGE_SIZE` | 64 MiB  | 16 MiB — 256 MiB                     |
| Transport frame size   | `CUBESTORE_TRANSPORT_MAX_FRAME_SIZE`   | 64 MiB  | 4 MiB — 256 MiB                      |
| Single cache entry     | `CUBESTORE_CACHE_MAX_ENTRY_SIZE`       | 63 MiB  | up to transport message size − 1 MiB |

Query results are the usual reason these limits are reached. A result is
handed to the queue store so that every API instance waiting on that query
can pick it up, and it is written to the cache under its cache key — so a
result set larger than the transport limit cannot be delivered at all,
however fast the query that produced it was.

A cache entry at or above `CUBESTORE_CACHE_MAX_ENTRY_SIZE` is rejected explicitly,
with `Unable to SET cache with '<key>' key, exceeds maximum allowed size for
payload: <size>, max allowed: <limit>`.

A message above the *transport* limit is answered with an error naming the
size and the limit, and the connection stays up for the other queries
multiplexed over it:

```
Request of 70000000 bytes exceeds the maximum message size of 67108864 bytes.
Reduce the size of the query, e.g. by sending fewer or smaller inline tables,
or raise CUBESTORE_TRANSPORT_MAX_MESSAGE_SIZE.
```

That holds up to twice whichever of the two transport limits above is lower.
A message beyond it is refused before it can be attributed to a query, so the
connection is closed instead and the other queries multiplexed over it are
re-sent on a new one. The close names the limit that refused it, so it says
which of the two to raise.

A result too large for Cube's own limit is reported the same way, as
`Cube Store response size exceeds the maximum message size of 100 MB`. That
limit is [`CUBEJS_CUBESTORE_MAX_MESSAGE_SIZE`](/reference/configuration/environment-variables#cubejs_cubestore_max_message_size),
which is independent of the Cube Store side and defaults to 100 MB.

If a query hits this limit, reduce the size of its result set — add filters
or a lower `limit`, drop dimensions, or split it into several queries.
Self-hosted deployments can raise the ceiling instead, but
`CUBESTORE_TRANSPORT_MAX_MESSAGE_SIZE` and `CUBESTORE_TRANSPORT_MAX_FRAME_SIZE`
have to go up together, since a message is sent as a single frame.

### Why it lives in Cube Store

Folding the cache and queue into Cube Store is itself a design decision in
the spirit of the rest of the system: one storage engine, one deployment
unit, one consistency model. The queue benefits directly from RocksDB's
write durability (in-flight queue state survives restarts), and the
event-driven blocking reads give lower-latency result delivery than the
polling patterns typical of external queue stores.


# Getting started with pre-aggregations
Source: https://docs.cube.dev/docs/pre-aggregations/getting-started-pre-aggregations

Conceptual introduction to pre-aggregations as Cube Store–backed rollups that tame warehouse latency as analytical data volume grows.

Often at the beginning of an analytical application's lifecycle - when there is
a smaller dataset that queries execute over - the application works well and
delivers responses within acceptable thresholds. However, as the size of the
dataset grows, the time-to-response from a user's perspective can often suffer
quite heavily. This is true of both application and purpose-built data
warehousing solutions.

This leaves us with a chicken-and-egg problem; application databases can deliver
low-latency responses with small-to-large datasets, but struggle with massive
analytical datasets; data warehousing solutions *usually* make no guarantees
except to deliver a response, which means latency can vary wildly on a
query-to-query basis.

| Database Type                  | Low Latency? | Massive Datasets? |
| ------------------------------ | ------------ | ----------------- |
| Application (Postgres/MySQL)   | ✅            | ❌                 |
| Analytical (BigQuery/Redshift) | ❌            | ✅                 |

Cube provides a solution to this problem: pre-aggregations. In layman's terms, a
pre-aggregation is a condensed version of the source data. It specifies
attributes from the source, which Cube uses to condense (or crunch) the data.
This simple yet powerful optimization can reduce the size of the dataset by
several orders of magnitude, and ensures subsequent queries can be served by the
same condensed dataset if any matching attributes are found.

[Pre-aggregations are defined within each cube's data
model][ref-schema-preaggs], and cubes can have as many pre-aggregations as they
require. The pre-aggregated data is stored in [Cube Store, a dedicated pre-aggregation storage
layer][ref-caching-preaggs-cubestore].

## Pre-Aggregations without Time Dimension

To illustrate pre-aggregations with an example, let's use a sample e-commerce
database. We have a data model representing all our `orders`:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      measures:
        - name: count
          type: count

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: status
          sql: status
          type: string

        - name: completed_at
          sql: completed_at
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    measures: {
      count: {
        type: `count`
      }
    },

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      },

      status: {
        sql: `status`,
        type: `string`
      },

      completed_at: {
        sql: `completed_at`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

Some sample data from this table might look like:

| **id** | **status** | **completed\_at**       |
| ------ | ---------- | ----------------------- |
| 1      | completed  | 2021-02-15T12:21:11.290 |
| 2      | completed  | 2021-02-25T18:15:12.369 |
| 3      | shipped    | 2021-03-15T20:40:57.404 |
| 4      | processing | 2021-03-13T10:30:21.360 |
| 5      | completed  | 2021-03-10T18:25:32.109 |

Our first requirement is to populate a dropdown in our front-end application
which shows all possible statuses. The Cube query to retrieve this information
might look something like:

```json theme={"dark"}
{
  "dimensions": ["orders.status"]
}
```

In that case, we can add the following pre-aggregation to the `orders` cube:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: order_statuses
          dimensions:
            - status
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    pre_aggregations: {
      order_statuses: {
        dimensions: [status]
      }
    }
  })
  ```
</CodeGroup>

## Pre-Aggregations with Time Dimension

Using the same data model as before, we are now finding that users frequently
query for the number of orders completed per day, and that this query is
performing poorly. This query might look something like:

```json theme={"dark"}
{
  "measures": ["orders.count"],
  "timeDimensions": ["orders.completed_at"]
}
```

In order to improve the performance of this query, we can add another
pre-aggregation definition to the `orders` cube:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: orders_by_completed_at
          measures:
            - count
          time_dimension: completed_at
          granularity: month
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    pre_aggregations: {
      orders_by_completed_at: {
        measures: [count],
        time_dimension: completed_at,
        granularity: `month`
      }
    }
  })
  ```
</CodeGroup>

Note that we have added a `granularity` property with a value of `month` to this
definition. This allows Cube to aggregate the dataset to a single entry for each
month.

The next time the API receives the same JSON query, Cube will build (if it
doesn't already exist) the pre-aggregated dataset, store it in the source
database server and use that dataset for any subsequent queries. A sample of the
data in this pre-aggregated dataset might look like:

| **completed\_at**       | **count** |
| ----------------------- | --------- |
| 2021-02-01T00:00:00.000 | 2         |
| 2021-03-01T00:00:00.000 | 3         |

## Keeping pre-aggregations up-to-date

Pre-aggregations can become out-of-date or out-of-sync if the original dataset
changes. [Cube uses a refresh key to check the freshness of the
data][ref-caching-preaggs-refresh]; if a change in the refresh key is detected,
the pre-aggregations are rebuilt. These refreshes are performed in the
background as a scheduled process, unless configured otherwise.

[ref-caching-preaggs-cubestore]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregations-storage

[ref-caching-preaggs-refresh]: /docs/pre-aggregations/using-pre-aggregations#refresh-strategy

[ref-schema-preaggs]: /reference/data-modeling/pre-aggregations


# Overview
Source: https://docs.cube.dev/docs/pre-aggregations/index

Understand Cube's two-level caching with in-memory query results and configurable pre-aggregations.

Caching Overview

<div>
  <img alt="Request vs Cube caching layers" />
</div>

Cube provides a two-level caching system. The first level is **in-memory** cache
and is active by default.

Cube's [in-memory cache](#in-memory-cache) acts as a buffer for your database
when there's a burst of requests hitting the same data from multiple concurrent
users. [Pre-aggregations](#pre-aggregations) are designed to provide the
right balance between time to insight and querying performance.

To reset the **in-memory** cache in [development mode][ref-development-mode], just
restart the server.

The second level of caching is called **pre-aggregations**, and requires
explicit configuration to activate.

We do not recommend changing the default **in-memory** caching configuration
unless it is necessary. To speed up query performance, consider using
**pre-aggregations**.

## Pre-aggregations

Pre-aggregations is a layer of the aggregated data built and refreshed by Cube.
It can dramatically improve the query performance and provide a higher
concurrency.

<Info>
  To start building pre-aggregations, depending on your data source, Cube may
  require write access to the [pre-aggregations schema][ref-config-preagg-schema]
  in the source database. In this case, Cube first builds pre-aggregations as
  tables in the source database and then exports them into the pre-aggregations
  storage. Please refer to the documentation for your specific driver to learn
  more about read-only support and pre-aggregation build strategies.
</Info>

Pre-aggregations are defined in the data model. You can learn more about
defining pre-aggregations in [data modeling reference][ref-schema-ref-preaggs].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      measures:
        - name: total_amount
          sql: amount
          type: sum

      dimensions:
        - name: created_at
          sql: created_at
          type: time

      pre_aggregations:
        - name: amount_by_created
          measures:
            - total_amount
          time_dimension: created_at
          granularity: month
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    measures: {
      total_amount: {
        sql: `amount`,
        type: `sum`
      }
    },

    dimensions: {
      created_at: {
        sql: `created_at`,
        type: `time`
      }
    },

    pre_aggregations: {
      amount_by_created: {
        measures: [total_amount],
        time_dimension: created_at,
        granularity: `month`
      }
    }
  })
  ```
</CodeGroup>

## In-memory cache

Cube caches the results of executed queries using in-memory cache. The cache key
is a generated SQL statement with any existing query-dependent pre-aggregations.

Upon receiving an incoming request, Cube first checks the cache using this key.
If nothing is found in the cache, the query is executed in the database and the
result set is returned as well as updating the cache.

If an existing value is present in the cache and the `refresh_key` value for the
query hasn't changed, the cached value will be returned. Otherwise, an SQL query
will be executed against either the pre-aggregations storage or the source
database to populate the cache with the results and return them.

### Refresh Keys

Cube takes great care to prevent unnecessary queries from hitting your database.
The first stage caching system caches query results, but Cube needs a way to
know if the data powering that query result has changed. If the underlying data
isn't any different, the cached result is valid and can be returned skipping an
expensive query, but if there is a difference, the query needs to be re-run and
its result cached.

To aid with this, Cube defines a `refresh_key` for each cube. [Refresh
keys][ref-schema-ref-cube-refresh-key] are evaluated by Cube to assess if the
data needs to be refreshed.

The following `refresh_key` tells Cube to refresh data every 5 minutes:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      refresh_key:
        every: 5 minute
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    refresh_key: {
      every: `5 minute`
    }
  })
  ```
</CodeGroup>

With the following `refresh_key`, Cube will only refresh the data if the value
of `MAX(created_at)` changes. By default, Cube will check this `refresh_key`
every 10 seconds:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      refresh_key:
        sql: SELECT MAX(created_at) FROM orders
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    refresh_key: {
      sql: `SELECT MAX(created_at) FROM orders`
    }
  })
  ```
</CodeGroup>

By default, Cube will check and invalidate the cache in the background when in
[development mode][ref-development-mode]. In production environments, we
recommend [running a Refresh Worker as a separate
instance][ref-production-checklist-refresh].

We recommend enabling background cache invalidation in a separate Cube worker
for production deployments. Please consult the [Production
Checklist][ref-production-checklist] for more information.

If background refresh is disabled, Cube will refresh the cache during query
execution. Since this could lead to delays in responding to end-users, we
recommend always enabling background refresh.

### Default Refresh Keys

The default values for `refresh_key` are:

* `every: 2 minute` for Athena, BigQuery, Databricks, Firebolt, Presto, and Snowflake.
* `every: 10 second` for all other databases.

You can use a custom SQL query to check if a refresh is required by changing the
[`refresh_key`][ref-schema-ref-cube-refresh-key] property in a cube. Often, a
`MAX(updated_at_timestamp)` for OLTP data is a viable option, or examining a
metadata table for whatever system is managing the data to see when it last ran.

### Disabling the cache

There's no straightforward way to disable caching in Cube. The reason is that
Cube not only stores cached values but also uses the cache as a point of
synchronization and coordination between nodes in a cluster. For the sake of
design simplicity, Cube doesn't distinguish client invocations, and all calls to
the data load API are idempotent. This provides excellent reliability and
scalability but has some drawbacks. One of those load data calls can't be traced
to specific clients, and as a consequence, there's no guaranteed way for a
client to initiate a new data loading query or know if the current invocation
wasn't initiated earlier by another client. Only Refresh Key freshness
guarantees are provided in this case.

The `refresh_key` parameter can be used to control cache validity.
For closer-to-real-time use cases, [`refresh_key.every`][ref-schema-ref-cube-refresh-key]
can be set to a low value, such as `1 minute`, which is the lowest recommended option.

For truly real-time use cases, consider using [streaming pre-aggregations][ref-streaming-preaggs].

## Inspecting Queries

To inspect whether the query hits in-memory cache, pre-aggregation, or the
underlying data source, you can use the Playground or [Cube
Cloud][link-cube-cloud].

[Developer Playground][ref-dev-playground] can be used to inspect a single
query. To do that, click the "cache" button after executing the query. It will
show you the information about the `refresh_key` for the query and whether the
query uses any pre-aggregations. To inspect multiple queries or list existing
pre-aggregations, you can use [Cube Cloud][link-cube-cloud].

To inspect queries in the Cube Cloud, navigate to the "History" page. You can
filter queries by multiple parameters on this page, including whether they hit
the cache, pre-aggregations, or raw data. Additionally, you can click on the
query to see its details, such as time spent in the database, the database
queue's size at the point of query execution, generated SQL, query timeline, and
more. It will also show you the optimal pre-aggregations that could be used for
this query.

To see existing pre-aggregations, navigate to the "Pre-Aggregations" page in the
Cube Cloud. The table shows all the pre-aggregations, the last refresh
timestamp, and the time spent to build the pre-aggregation. You can also inspect
every pre-aggregation's details: the list of queries it serves and all its
versions.

### Cache type

Any query that is fulfilled by Cube will use one of the following cache types:

* **[Pre-aggregations](#pre-aggregations) in Cube Store.** This cache type
  indicates that the query utilized existing pre-aggregations in Cube Store,
  so it did not need to go to the database for processing.
* **Pre-aggregations in Cube Store with a suboptimal query plan.** This cache
  type indicates that the query ultilized pre-aggregations in Cube Store,
  but that it's possible to get a performance boost by [using indexes][ref-indexes].
* **Pre-aggregations in the data source.** This cache type indicates that
  the query utilized pre-aggregations from in the upstream data source.
  These queries could gain a performance boost by using Cube Store as [pre-aggregation
  storage][ref-storage].
* **[In-memory cache.](#in-memory-cache)** This cache type indicates that the
  results were retrieved from Cube's in-memory cache. All query results
  are stored in Cube's in-memory cache, and if the same query is
  run within a certain time frame, the results will be retrieved from in-memory
  cache instead of being processed on the database or in Cube Store. This is the
  fastest query retrieval method, but it requires that the exact same query was
  run very recently.
* **No cache.** This cache type indicates that the query was processed in the upstream
  data source and was not accelerated using pre-aggregations. These queries could have
  a significant performance boost if pre-aggregations and Cube Store were utilized.

In [Query History][ref-query-history] and throughout Cube Cloud, colored bolt
icons are used to indicate the cache type. Also, [Performance
Insights][ref-perf-insights] provide an overview of API requests by specific
cache types.

<Frame>
  <img />
</Frame>

[link-cube-cloud]: https://cube.dev/cloud

[ref-config-preagg-schema]: /reference/configuration/config#preaggregationsschema

[ref-dev-playground]: /docs/explore-analyze/playground

[ref-development-mode]: /reference/configuration/environment-variables#cubejs_dev_mode

[ref-production-checklist]: /cube-core/running-in-production

[ref-production-checklist-refresh]: /cube-core/running-in-production#set-up-refresh-worker

[ref-schema-ref-cube-refresh-key]: /reference/data-modeling/cube#refresh_key

[ref-schema-ref-preaggs]: /reference/data-modeling/pre-aggregations

[ref-streaming-preaggs]: /docs/pre-aggregations/lambda-pre-aggregations#batch-and-streaming-data

[ref-query-history]: /admin/monitoring/query-history#inspecting-api-queries

[ref-perf-insights]: /admin/monitoring/performance#cache-type

[ref-indexes]: /docs/pre-aggregations/using-pre-aggregations#using-indexes

[ref-storage]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregations-storage


# Lambda pre-aggregations
Source: https://docs.cube.dev/docs/pre-aggregations/lambda-pre-aggregations

Lambda-style pre-aggregations that merge historical rollups with fresher source or streaming layers for near-real-time serving on Cube Store.

Lambda pre-aggregations follow the
[Lambda architecture](https://en.wikipedia.org/wiki/Lambda_architecture) design
to union real-time and batch data. Cube acts as a serving layer and uses
pre-aggregations as a batch layer and source data or other pre-aggregations,
usually [streaming][streaming-pre-agg], as a speed layer. Due to this design,
lambda pre-aggregations **only** work with data that is newer than the existing
batched pre-aggregations.

<Warning>
  Lambda pre-aggregations only work with Cube Store.
</Warning>

## Use cases

Below we are looking at the most common examples of using lambda
pre-aggregations.

### Batch and source data

Batch data is coming from pre-aggregation and real-time data is coming from the
data source.

<div>
  <img alt="Lambda pre-aggregation batch and source diagram" />
</div>

First, you need to create pre-aggregations that will contain your batch data. In
the following example, we call it `batch`. Please note, it must have a
`time_dimension` and `partition_granularity` specified. Cube will use these
properties to union batch data with freshly-retrieved source data.

You may also control the batch part of your data with the `build_range_start`
and `build_range_end` properties of a pre-aggregation to determine a specific
window for your batched data.

Next, you need to create a lambda pre-aggregation. To do that, create
pre-aggregation with type `rollup_lambda`, specify rollups you would like to use
with `rollups` property, and finally set `union_with_source_data: true` to use
source data as a real-time layer.

Please make sure that the lambda pre-aggregation definition comes first when
defining your pre-aggregations.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      # ...

      pre_aggregations:
        - name: lambda
          type: rollup_lambda
          union_with_source_data: true
          rollups:
            - CUBE.batch

        - name: batch
          measures:
            - users.count
          dimensions:
            - users.name
          time_dimension: users.created_at
          granularity: day
          partition_granularity: day
          build_range_start:
            sql: SELECT '2020-01-01'
          build_range_end:
            sql: SELECT '2022-05-30'
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("users", {
    // ...

    pre_aggregations: {
      lambda: {
        type: `rollup_lambda`,
        union_with_source_data: true,
        rollups: [CUBE.batch]
      },

      batch: {
        measures: [users.count],
        dimensions: [users.name],
        time_dimension: users.created_at,
        granularity: `day`,
        partition_granularity: `day`,
        build_range_start: {
          sql: `SELECT '2020-01-01'`
        },
        build_range_end: {
          sql: `SELECT '2022-05-30'`
        }
      }
    }
  })
  ```
</CodeGroup>

### Batch and streaming data

In this scenario, batch data is comes from one pre-aggregation and real-time
data comes from a [streaming pre-aggregation][streaming-pre-agg].

<div>
  <img alt="Lambda pre-aggregation batch and streaming diagram" />
</div>

You can use lambda pre-aggregations to combine data from multiple
pre-aggregations, where one pre-aggregation can have batch data and another
streaming.
Please note that build ranges of all rollups referenced by lambda rollup should have enough intersection between each other that anticipates partition build times for those rollups.
Cube will maximize the coverage of the requested date range by partitions from different rollups.
The first rollup in a list of referenced rollups that has a fully built partition for a particular date range will be used to serve this date range.
The last rollup in a list will be used to cover the remaining uncovered part of a date range.
Partitions of the last rollup will be used even if not completely built.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: streaming_users
      # This cube uses a streaming SQL data source such as ksqlDB
      # ...

      pre_aggregations:
        - name: streaming
          type: rollup
          measures:
            - CUBE.count
          dimensions:
            - CUBE.name
          time_dimension: CUBE.created_at
        granularity: day,
        partition_granularity: day

    - name: users
      # This cube uses a data source such as ClickHouse or BigQuery
      # ...

      pre_aggregations:
        - name: batch_streaming_lambda
          type: rollup_lambda
          rollups:
            - users.batch
            - streaming_users.streaming

        - name: batch
          type: rollup
          measures:
            - users.count
          dimensions:
            - users.name
          time_dimension: users.created_at
          granularity: day
          partition_granularity: day
          build_range_start:
            sql: SELECT '2020-01-01'
          build_range_end:
            sql: SELECT '2022-05-30'
  ```

  ```javascript title="JavaScript" theme={"dark"}
  // This cube uses a streaming SQL data source such as ksqlDB
  cube("streaming_users", {
    // ...

    pre_aggregations: {
      streaming: {
        type: `rollup`,
        measures: [CUBE.count],
        dimensions: [CUBE.name],
        time_dimension: CUBE.created_at,
        granularity: `day`,
        partition_granularity: `day`
      }
    }
  })

  // This cube uses a data source such as ClickHouse or BigQuery
  cube("users", {
    // ...

    pre_aggregations: {
      batch_streaming_lambda: {
        type: `rollup_lambda`,
        rollups: [users.batch, streaming_users.streaming]
      },

      batch: {
        type: `rollup`,
        measures: [users.count],
        dimensions: [users.name],
        time_dimension: users.created_at,
        granularity: `day`,
        partition_granularity: `day`,
        build_range_start: {
          sql: `SELECT '2020-01-01'`
        },
        build_range_end: {
          sql: `SELECT '2022-05-30'`
        }
      }
    }
  })
  ```
</CodeGroup>

[streaming-pre-agg]: /docs/pre-aggregations/using-pre-aggregations#streaming-pre-aggregations


# Matching queries with pre-aggregations
Source: https://docs.cube.dev/docs/pre-aggregations/matching-pre-aggregations

When executing a query, Cube will try to match and fulfill it with the best available pre-aggregation.

Since pre-aggregations contain a *condensed representation* of the data from
the upstream data source (rather than a copy of that data), Cube needs to ensure
that fulfilling a query with a pre-aggregation is possible and doing so will
produce correct results.

If there's no matching pre-aggregation, Cube will fall back to querying
the upstream data source, unless the [rollup-only mode][ref-rollup-only-mode]
is enabled.

<Info>
  If you don't know why a query doesn't match a pre-aggregation, check
  [common pitfalls](#common-pitfalls) first.
</Info>

## Eligible pre-aggregations

Cube goes through the following steps to determine if there are any pre-aggregations
matching a query:

* **Members (e.g., dimensions, measures, etc.) are extracted from the query.**
  If the query contains members of a [view][ref-views], they are substituted by
  respective members of cubes where they are defined. It means that pre-aggregations
  defined for cube members would also match queries with view members. There's no need
  to define additional pre-aggregations for views.
* Cube looks for pre-aggregations in all cubes that define members in the query.
* Pre-aggregations are tested in the order they are defined in the data model
  file. However, `rollup` pre-aggregations are tested before `original_sql`
  pre-aggregations.
* The first pre-aggregation that [matches](#matching-algorithm) a query is used.

## Matching algorithm

Cube goes through the following steps to determine whether a query matches a
particular eligible pre-aggregation:

<Frame>
  <img />
</Frame>

See the details for each step:

* **Is query leaf-measure additive?** Cube checks that all [leaf
  measures][ref-leaf-measures] in the query are [additive][ref-measure-additivity].
  If the query contains [calculated measures][ref-calculated-measures] (e.g.,
  measures defined as `{sum} / {count}`), then referenced leaf measures will be
  checked for additivity.
* **Does every member of the query exist in the pre-aggregation?** Cube checks
  that the pre-aggregation contains all dimensions, filter dimensions, and leaf
  measures from the query. [`switch` dimensions](#matching-switch-dimensions) are
  an exception: they don't have to be included in the pre-aggregation.
* **Are any query measures multiplied in the cube's data model?** Cube checks
  if any measures are multiplied via a [`one_to_many`
  relationship][ref-schema-joins-rel] between cubes in the query.
* **Does the query specify granularity for its time dimension?** Cube checks
  that the time dimension granularity is set in the query.
* **Are query filter dimensions included in its own dimensions?** Cube checks
  that all filter dimensions are also included as dimensions in the query.

### Matching time dimensions

There are extra considerations that apply to matching time dimensions.

* **Time dimension and granularity in the query together act as a dimension.**
  If the date range isn't aligned with granularity, a common granularity is used.
  This common granularity is selected using the [greatest common divisor][wiki-gcd]
  across both the query and pre-aggregation. For example, the common granularity
  between `hour` and `day` is `hour` because both `hour` and `day` can be divided
  by `hour`.
* **The query's granularity's date range must match the start date and end date
  from time dimensions.** For example, when using a granularity of `month`,
  the values should be the start and end days of the month, i.e.,
  `['2020-01-01T00:00:00.000', '2020-01-31T23:59:59.999']`; when the granularity
  is `day`, the values should be the start and end hours of the day, i.e.,
  `['2020-01-01T00:00:00.000', '2020-01-01T23:59:59.999']`. Date ranges are
  inclusive, and the minimum granularity is `second`. By default, this is ensured
  via the [`allow_non_strict_date_range_match`][ref-non-strict-date-range-match]
  parameter of pre-aggregations: it allows to match *non-strict date ranges* and is
  set to `true` by default.
* **The time zone in the query must match the time zone of a pre-aggregation.**
  You can configure a list of time zones that pre-aggregations will be built for
  using the [`scheduled_refresh_time_zones`][ref-conf-scheduled-refresh-time-zones]
  configuration option.

If a query specifies a [custom granularity][ref-custom-granularity] for its time
dimension, then a matching pre-aggregation with the same custom granularity will
be used even if there is also an matching pre-aggregation with a default
granularity (e.g., `day` or `month`).

<Note>
  Provide the date range via [`timeDimensions`][ref-time-dimensions-format] rather
  than an [`inDateRange` filter][ref-in-date-range]. A date range expressed as a
  filter is applied as a generic dimension filter, so it matches only when that
  time dimension is also listed in the pre-aggregation's `dimensions` — the
  granularity matching rules above don't apply to it.
</Note>

### Matching ungrouped queries

There are extra considerations that apply to matching [ungrouped
queries][ref-ungrouped-queries]:

* The pre-aggregation should include [primary keys][ref-primary-key] of all
  cubes involved in the query.
* If multiple cubes are referenced in the query, the pre-aggregation should
  include only members of these cubes.

### Matching switch dimensions

A [`switch` dimension][ref-switch] holds a predefined set of values rather than
data from the upstream data source, and [`case` measures][ref-case] dispatch on
the selected value. Because its values are known from the data model, a
pre-aggregation **does not need to include a `switch` dimension** to match a
query that uses one: the selected value is applied over the pre-aggregation scan.

Leaving the `switch` dimension out keeps the pre-aggregation small — including
it multiplies the rows by every value in the set:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: sales
      # ...

      pre_aggregations:
        - name: rolling
          measures:
            - total
            - r3_amount
            - ytd_amount
          dimensions:
            - account
            - product
          time_dimension: date
          granularity: month
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`sales`, {
    // ...

    pre_aggregations: {
      rolling: {
        measures: [total, r3_amount, ytd_amount],
        dimensions: [account, product],
        time_dimension: date,
        granularity: `month`
      }
    }
  });
  ```
</CodeGroup>

Pre-aggregations that *do* include the `switch` dimension keep matching as well,
so existing definitions are unaffected.

Matching is unaffected by how the `switch` dimension is modeled across cubes. If
a query returns more rows than expected, that's a modeling concern — see
[`case` measures][ref-case] — and pre-aggregations accelerate that result rather
than preventing it.

<Warning>
  `switch` dimensions and `case` measures are powered by Tesseract, the
  [next-generation data modeling engine][link-tesseract]. In versions before
  v1.7.0, it was not enabled by default.
</Warning>

## Matching multi-fact and multi-stage queries

A query can decompose into multiple subqueries — for example, a query over a
[multi-fact view][ref-multi-fact-views] runs a subquery per fact, and a query
with [multi-stage measures][ref-multi-stage] runs a subquery per stage. Cube
matches a pre-aggregation to each subquery independently, so a single query can
be served by several pre-aggregations at once — one per subquery — rather than
requiring a single pre-aggregation that covers the whole query.

Matching is all-or-nothing across the query, though: if any subquery can't be
served, the pre-aggregations matched for the others are dropped too and the whole
query runs against the upstream data source. A common cause is a pre-aggregation
keyed on its own cube's time dimension while the query groups by another cube's —
the two are equal by the join condition, but matching only considers members the
pre-aggregation stores. Key every pre-aggregation on the time dimension the query
groups by. Results stay correct either way; only the acceleration is lost.

<Warning>
  Matching separate pre-aggregations to multi-fact and multi-stage subqueries is
  powered by Tesseract, the [next-generation data modeling engine][link-tesseract]. In versions before v1.7.0, it was not enabled by default.
</Warning>

## Troubleshooting

If you're not sure why a query does not match a pre-aggregation, try to identify
the part of the query that prevents it from matching. You can do that by
removing measures, dimensions, filters, etc. from your query until it matches.
Then, refer to the [matching algorithm](#matching-algorithm) and [common
pitfalls](#common-pitfalls) to understand why that part was an issue.

### Common pitfalls

* Most commonly, a query would not match a pre-aggregation because they contain
  [non-additive measures][ref-measure-additivity].

  <Note>
    See [this recipe][ref-non-additive-recipe] for workarounds.
  </Note>

* If a query uses any time zone other than `UTC`, please check the section on
  [matching time dimensions](#matching-time-dimensions) and the
  [`scheduled_refresh_time_zones`][ref-conf-scheduled-refresh-time-zones]
  configuration option.

[ref-rollup-only-mode]: /docs/pre-aggregations/using-pre-aggregations#rollup-only-mode

[ref-schema-joins-rel]: /reference/data-modeling/joins#relationship

[wiki-gcd]: https://en.wikipedia.org/wiki/Greatest_common_divisor

[ref-measure-additivity]: /reference/data-modeling/measures#type

[ref-leaf-measures]: /reference/data-modeling/measures#type

[ref-calculated-measures]: /docs/data-modeling/overview#4-using-calculated-measures

[ref-non-strict-date-range-match]: /reference/data-modeling/pre-aggregations#allow_non_strict_date_range_match

[ref-non-additive-recipe]: /recipes/pre-aggregations/non-additivity

[ref-conf-scheduled-refresh-time-zones]: /reference/configuration/config#scheduled_refresh_time_zones

[ref-ungrouped-queries]: /reference/core-data-apis/queries#ungrouped-query

[ref-primary-key]: /reference/data-modeling/dimensions#primary_key

[ref-custom-granularity]: /reference/data-modeling/dimensions#granularities

[ref-views]: /docs/data-modeling/views

[ref-multi-fact-views]: /docs/data-modeling/multi-fact-views

[ref-multi-stage]: /docs/data-modeling/measures#multi_stage

[ref-switch]: /reference/data-modeling/dimensions#type

[ref-case]: /reference/data-modeling/measures#case

[ref-time-dimensions-format]: /reference/core-data-apis/rest-api/query-format#time-dimensions-format

[ref-in-date-range]: /reference/core-data-apis/rest-api/query-format#indaterange

[link-tesseract]: https://cube.dev/blog/introducing-tesseract


# Refreshing pre-aggregations
Source: https://docs.cube.dev/docs/pre-aggregations/refreshing-pre-aggregations

Refresh worker responsibilities, key environment variables for scheduled builds, and troubleshooting when refresh intervals fall behind.

*Pre-aggregation refresh* is the process of building pre-aggregations and updating
them with new data. Pre-aggregation refresh is the responsibility of the *refresh
worker*.

## Configuration

You can use the following environment variables to configure the refresh worker
behavior:

* [`CUBEJS_REFRESH_WORKER`](/reference/configuration/environment-variables#cubejs_refresh_worker) (see also [`CUBEJS_PRE_AGGREGATIONS_BUILDER`](/reference/configuration/environment-variables#cubejs_pre_aggregations_builder))
* [`CUBEJS_PRE_AGGREGATIONS_SCHEMA`](/reference/configuration/environment-variables#cubejs_pre_aggregations_schema)
* [`CUBEJS_SCHEDULED_REFRESH_TIMEZONES`](/reference/configuration/environment-variables#cubejs_scheduled_refresh_timezones)
* [`CUBEJS_DB_QUERY_TIMEOUT`](/reference/configuration/environment-variables#cubejs_db_query_timeout)
* [`CUBEJS_REFRESH_WORKER_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_refresh_worker_concurrency) (see also [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency))
* [`CUBEJS_SCHEDULED_REFRESH_QUERIES_PER_APP_ID`](/reference/configuration/environment-variables#cubejs_scheduled_refresh_queries_per_app_id)
* [`CUBEJS_DROP_PRE_AGG_WITHOUT_TOUCH`](/reference/configuration/environment-variables#cubejs_drop_pre_agg_without_touch)
* [`CUBEJS_PRE_AGGREGATIONS_BACKOFF_MAX_TIME`](/reference/configuration/environment-variables#cubejs_pre_aggregations_backoff_max_time)

## Pre-aggregation data source

By default, each data source builds and stores its pre-aggregations using its own
connection. You can instead point a data source's pre-aggregations at a dedicated
connection by adding a `PRE_AGGREGATIONS` segment to its environment variables. When
set, that source's pre-aggregations are built on and read from the dedicated
connection rather than the source's own.

Use the `CUBEJS_PRE_AGGREGATIONS_DB_*` variables for the default data source, and the
`CUBEJS_DS_<NAME>_PRE_AGGREGATIONS_DB_*` variables for a [named data
source][ref-multiple-data-sources]:

```dotenv theme={"dark"}
# Default data source
CUBEJS_DB_TYPE=postgres
CUBEJS_DB_HOST=localhost

# Dedicated pre-aggregation data source for the default data source
CUBEJS_PRE_AGGREGATIONS_DB_HOST=preagg-host
CUBEJS_PRE_AGGREGATIONS_DB_USER=preagg-user
CUBEJS_PRE_AGGREGATIONS_DB_PASS=preagg-pass

# A named data source and its dedicated pre-aggregation data source
CUBEJS_DATASOURCES=default,analytics
CUBEJS_DS_ANALYTICS_DB_TYPE=postgres
CUBEJS_DS_ANALYTICS_DB_HOST=remotehost
CUBEJS_DS_ANALYTICS_PRE_AGGREGATIONS_DB_HOST=analytics-preagg-host
CUBEJS_DS_ANALYTICS_PRE_AGGREGATIONS_DB_USER=analytics-preagg-user
CUBEJS_DS_ANALYTICS_PRE_AGGREGATIONS_DB_PASS=analytics-preagg-pass
```

The `PRE_AGGREGATIONS` variant supports the same connection variables as the regular
`CUBEJS_DB_*` / `CUBEJS_DS_<NAME>_DB_*` data source variables (for example `_DB_HOST`,
`_DB_PORT`, `_DB_USER`, `_DB_PASS`, and `_DB_SSL`).

Driver-specific variables take the same segment, so the dedicated connection is not
limited to the `_DB_*` family — for example `CUBEJS_PRE_AGGREGATIONS_JDBC_URL` or
`CUBEJS_PRE_AGGREGATIONS_AWS_REGION`. In the decorated form for a named data source, the
`DB_`, `JDBC_`, `AWS_`, `DATABASE`, and `FIREBOLT_` families are supported.

Setting any one of these variables switches the data source's pre-aggregations onto the
dedicated connection; there is no separate flag to enable it. Activation is prefix-based
rather than name-based, so a misspelled variable such as
`CUBEJS_PRE_AGGREGATIONS_DB_HSOT` still switches it on — combined with the rule below,
that leaves every setting at its driver default.

<Warning>
  Each variable is read independently, and an unset one does **not** fall back to its
  `CUBEJS_DB_*` counterpart — it falls back to the driver's own default. Configure the
  dedicated connection in full: if you set only `CUBEJS_PRE_AGGREGATIONS_DB_HOST`, the build
  connects to that host with the driver's default user and password rather than the ones
  from `CUBEJS_DB_USER` and `CUBEJS_DB_PASS`.

  The one exception is the driver type: `CUBEJS_PRE_AGGREGATIONS_DB_TYPE` is ignored, since
  the dedicated connection always uses the same driver as the data source it belongs to.
</Warning>

<Info>
  [`CUBEJS_PRE_AGGREGATIONS_SCHEMA`](/reference/configuration/environment-variables#cubejs_pre_aggregations_schema),
  [`CUBEJS_PRE_AGGREGATIONS_BUILDER`](/reference/configuration/environment-variables#cubejs_pre_aggregations_builder),
  [`CUBEJS_PRE_AGGREGATIONS_BACKOFF_MAX_TIME`](/reference/configuration/environment-variables#cubejs_pre_aggregations_backoff_max_time),
  and [`CUBEJS_PRE_AGGREGATIONS_ALLOW_NON_STRICT_DATE_RANGE_MATCH`](/reference/configuration/environment-variables#cubejs_pre_aggregations_allow_non_strict_date_range_match)
  share the prefix but configure pre-aggregation behavior rather than a connection, so they
  do not switch the data source's pre-aggregations onto a dedicated connection.
</Info>

A custom [`driver_factory`][ref-config-driver-factory] takes precedence over these
variables: if both are configured, the `driver_factory` connection is used for
pre-aggregations as well and a `Pre-aggregation driver conflict` warning is logged.

## Troubleshooting

### `Refresh scheduler interval error`

Sometimes, you might come across the following error:

```json theme={"dark"}
{
  "message": "Refresh Scheduler Interval Error",
  "error": "Previous interval #2 was not finished with 60000 interval"
}
```

It indicates that your refresh worker is overloaded. You probably have a lot of
[tenants][ref-multitenancy], a lot of [pre-aggregations][ref-preaggs] to refresh,
or both.

If you're using [multitenancy][ref-multitenancy], you'd need to deploy several Cube
clusters (each one per a reduced set of tenants) so there will be multiple refresh
workers which will work only on a subset of your tenants.

If you're using Cube Cloud, you can use a [Multi-cluster deployment][ref-production-multi-cluster]
that would automatically do this for you.

[ref-multitenancy]: /embedding/multitenancy

[ref-preaggs]: /docs/pre-aggregations/using-pre-aggregations

[ref-production-multi-cluster]: /admin/deployment/deployment-types#multi-cluster

[ref-multiple-data-sources]: /admin/connect-to-data/multiple-data-sources

[ref-config-driver-factory]: /reference/configuration/config#driver_factory


# Using pre-aggregations
Source: https://docs.cube.dev/docs/pre-aggregations/using-pre-aggregations

Operational guide to aggregate awareness—how Cube picks rollups, partitions data, enforces rollup-only mode, and tunes pre-aggregation behavior.

Pre-aggregations is an implementation of aggregate awareness in Cube.
Pre-aggregation tables are materialized query results.
Cube can analyze queries against a defined set of pre-aggregation rules to
choose the optimal one that will be used to serve a given Cube query instead of going to the data source.

If Cube finds a suitable pre-aggregation rule, database querying becomes a
multi-stage process:

1. Cube checks if an up-to-date copy of the pre-aggregation exists.

2. Cube will execute a query against the pre-aggregated tables instead of the
   raw data.

Pre-aggregations is a powerful way to speed up your Cube queries. There are many
configuration options to consider. Please make sure to check the
[configuration reference][ref-schema-ref-preaggs].

## Matching queries

When executing a query, Cube will try to [match and fulfill it with a
pre-aggregation][ref-matching-preaggs] in the first place.

If there's no matching pre-aggregation, Cube will query the upstream data
source instead, unless the [rollup-only mode](#rollup-only-mode) is enabled.

## Rollup-only mode

In the rollup-only mode, Cube will **only** fulfill queries using
pre-aggregations. To enable the rollup-only mode, use the
[`CUBEJS_ROLLUP_ONLY`](/reference/configuration/environment-variables#cubejs_rollup_only) environment variable.

It can be useful to prevent queries from your end users from ever hitting the
upstream data source, e.g., if you prefer to use your data warehouse only to
build and refresh pre-aggregations and keep it suspended the rest of the time.

<Warning>
  When the rollup-only mode is used with a single-node deployment (where the API
  instance also serves as a [refresh worker][ref-deploy-refresh-wrkr]), queries
  that can't be fulfilled with pre-aggregations will result in an error.
  Scheduled refreshes will continue to work in the background.
</Warning>

## Refresh strategy

Refresh strategy can be customized by setting the
[`refresh_key`][ref-schema-ref-preaggs-refresh-key] property for the
pre-aggregation.

The default value of [`refresh_key`][ref-schema-ref-preaggs-refresh-key] is
`every: 1 hour`, if neither of the cubes overrides it's `refreshKey` parameter.
It can be redefined either by overriding the default value of
the [`every` property][ref-schema-ref-preaggs-refresh-key-every]:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: amount_by_created
          type: rollup
          measures:
            - amount
          time_dimension: created_at
          granularity: month
          refresh_key:
            every: 12 hour
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    pre_aggregations: {
      amount_by_created: {
        type: `rollup`,
        measures: [amount],
        time_dimension: created_at,
        granularity: `month`,
        refresh_key: {
          every: `12 hour`
        }
      }
    }
  })
  ```
</CodeGroup>

Or by providing a [`sql` property][ref-schema-ref-preaggs-refresh-key-sql]
instead, and leaving `every` unchanged from its default value:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: amount_by_created
          measures:
            - amount
          time_dimension: created_at
          granularity: month
          refresh_key:
            # every will default to `10 seconds` here
            sql: SELECT MAX(created_at) FROM orders
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    pre_aggregations: {
      amount_by_created: {
        measures: [amount],
        time_dimension: created_at,
        granularity: `month`,
        refresh_key: {
          // every will default to `10 seconds` here
          sql: `SELECT MAX(created_at) FROM orders`
        }
      }
    }
  })
  ```
</CodeGroup>

Or both `every` and `sql` can be defined together:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: amount_by_created
          measures:
            - amount
          time_dimension: created_at
          granularity: month
          refresh_key:
            every: 12 hour
            sql: SELECT MAX(created_at) FROM orders
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    pre_aggregations: {
      amount_by_created: {
        measures: [amount],
        time_dimension: created_at,
        granularity: `month`,
        refresh_key: {
          every: `12 hour`,
          sql: `SELECT MAX(created_at) FROM orders`
        }
      }
    }
  })
  ```
</CodeGroup>

When `every` and `sql` are used together, Cube will run the query from the `sql`
property on an interval defined by the `every` property. If the query returns
new results, then the pre-aggregation will be refreshed.

## Partitioning

[Partitioning][wiki-partitioning] is an extremely effective optimization for
accelerating pre-aggregations build and refresh time. It effectively "shards"
the data between multiple tables, splitting them by a defined attribute.

Cube can be configured to incrementally refresh only the last set of partitions
through the `updateWindow` property. This leads to faster refresh times due to
unnecessary data not being reloaded, and even reduced cost for some databases
like [BigQuery](/admin/connect-to-data/data-sources/google-bigquery) or
[AWS Athena](/admin/connect-to-data/data-sources/aws-athena).

<Note>
  See [this recipe][ref-incremental-refresh-recipe] for an example of optimized
  incremental refresh.
</Note>

Any `rollup` pre-aggregation can be partitioned by time using the
`partition_granularity` property in [a pre-aggregation
definition][ref-schema-ref-preaggs]. In the example below, the
`partition_granularity` is set to `month`, which means Cube will generate
separate tables for each month's worth of data. Once built, it will continue to
refresh on a daily basis the last 3 months of data.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: category_and_date
          measures:
            - count
            - revenue
          dimensions:
            - category
          time_dimension: created_at
          granularity: day
          partition_granularity: month
          refresh_key:
            every: 1 day
            incremental: true
            update_window: 3 months
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    preAggregations: {
      category_and_date: {
        measures: [count, revenue],
        dimensions: [category],
        time_dimension: created_at,
        granularity: `day`,
        partition_granularity: `month`,
        refresh_key: {
          every: `1 day`,
          incremental: true,
          update_window: `3 months`
        }
      }
    }
  })
  ```
</CodeGroup>

### Partitioning by non-time dimension

Cube Store uses an auto-partitioning technique to split Cube logical partitions into multiple physical ones.
The partitioning key is the same as the sorting key of an index.
Every physical partition is stored as a separate parquet file.
Split is performed based on underlying parquet file sizes and rows inside those files.
So simplest way to ensure proper partitioning is to introduce an index.
For bigger pre-aggregations first columns of an index will determine the partitioning scheme.
An interesting consequence of having time dimension partitioning enabled with an index is data partitioned by time and then by sorting the key of an index.
It leads to that even in case of optimal index in place querying time is proportional to count of involved time partitions.
This issue can be addressed by lambda pre-aggregations.

Alternatively, if you want to explicitly introduce key partitioning, you can use multi-tenancy to introduce multiple orchestrator IDs.
Each orchestrator ID can use a different pre-aggregation schema, so you may define those based on the partitioning key you want to introduce.
This technique, together with multi-router Cube Store approach, allows you to achieve linear scaling on the partitioning key of your choice.

### Best practices

In general, it's better to lean towards less partitions, as long as you are satisfied with query speed.

For optimal *querying performance*, partitions should be small enough so that a Cube Store worker can read (scan) a partition in less than 100 milliseconds.
The best way to optimize this is to start from a relatively large partition (e.g., yearly or no partition at all if data permits),
check what the [flame graph][ref-flame-graph] in Query History shows, then iterate as needed.

For optimal pre-aggregation *build performance*, you would optimize partition size together with pre-aggregation build concurrency and build time. Smaller
partitions with high concurrency would incur significant overhead. For optimal build performance, having 1 Cube Store worker per partition is ideal.
However, Cube Store workers can handle up to 4 partitions per worker conucrrently. Since Cube Store workers often max out at 16, this means you should avoid having more than 64 partitions.
Any additional partitions would be queued. Keep in mind that indexes essentially multiply the number of partitions that are created,
so for example, if you have two indexes, you would want to avoid having more than 32 partitions to avoid queueing.
The best way to optimize this is to make refresh keys as infrequent as possible
and then use the [Build History][ref-build-history] tab to check build times, along with the [Performance Insights][ref-perf-insights] page to
monitor Cube Store workers load, and iterate as needed.

## Using indexes

[Indexes][ref-ref-indexes] are sorted copies of pre-aggregation data.

**When you define a pre-aggregation without any explicit indexes, the default
index is created.** In this index, dimensions come first, time dimensions come
second.

When you define additional indexes, you don't incur any additional costs on
the data warehouse side. However, the pre-aggregation build time for a
particular pre-aggregation increases with each index because all indexes for pre-aggregation are built during ingestion time.

### When to use indexes?

At query time, if the default index can't be selected for a merge sort scan,
then a less performant hash aggregation would be used. It usually means that
the full table needs to be scanned to get query results.

It usually doesn't make much difference if the pre-aggregation table is only
several MBs in size. However, for larger pre-aggregations, indexes are usually
required to achieve optimal performance, especially if not all dimensions from
a pre-aggregation are used in a particular query.

### Best practices

Most pre-aggregations represent [additive][ref-additivity] rollups. For such
rollups, **the rule of thumb is that, for most queries, there should be
at least one index that makes a particular query scan very little amount of
data,** which makes it very fast. (There are exceptions to this rule like
top-k queries or queries with only low selectivity range filters. Optimization
for these use cases usually involves remodeling data and queries.)

To maximize performance, you can introduce an index per each query type so
that the set of dimensions used in a query overlaps as much as possible with
the set of dimensions in the index. Measures are usually only used in indexes
if you plan to filter on a measure value and the cardinality of the possible
values of the measure is low.

The order in which dimensions are specified in the index is **very** important;
suboptimal ordering can lead to diminished performance. To improve the
performance of an index the main thing to consider is its order of dimensions.
The rule of thumb for dimension order is as follows:

* Dimensions used in high selectivity, single-value filters come first.
* Dimensions used in `GROUP BY` come second.
* Everything else used in the query comes in the end, including dimensions
  used in low selectivity, multiple-value filters.

It might sound counter-intuitive to have dimensions used in `GROUP BY` before
dimensions used in multiple-value filters. However, Cube Store always performs
scans on sorted data, and if `GROUP BY` matches index ordering, merge
sort-based algorithms are used for querying, which are usually much faster
than hash-based `GROUP BY` in case index ordering doesn't match the query.

If in doubt, always
[use `EXPLAIN` and `EXPLAIN ANALYZE`][ref-cubestore-sql-commands] to figure out
the final query plan.

#### Example

Suppose you have a pre-aggregation that has millions of rows and the following
structure:

| timestamp           | product\_name | product\_category | zip\_code | order\_total |
| ------------------- | ------------- | ----------------- | --------- | ------------ |
| 2023-01-01 10:00:00 | Keyboard      | Electronics       | 88523     | 1000         |
| 2023-01-01 10:00:00 | Mouse         | Electronics       | 88523     | 800          |
| 2023-01-01 10:00:00 | Plastic Chair | Furniture         | 88523     | 2000         |
| 2023-01-01 11:00:00 | Keyboard      | Electronics       | 88524     | 2000         |
| 2023-01-01 11:00:00 | Plastic Chair | Furniture         | 88524     | 3000         |

The pre-aggregation definition looks as follows:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: main
          measures:
            - order_total
          dimensions:
            - product_name
            - product_category
            - zip_code
          time_dimension: timestamp
          granularity: hour
          partition_granularity: day
          allow_non_strict_date_range_match: true
          refresh_key:
            every: 1 hour
            incremental: true
            update_window: 1 day
          build_range_start:
            sql: SELECT DATE_SUB(NOW(), 365)
          build_range_end:
            sql: SELECT NOW()
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("orders", {
    // ...

    pre_aggregations: {
      main: {
        measures: [order_total],
        dimensions: [product_name, product_category, zip_code],
        time_dimension: timestamp,
        granularity: `hour`,
        partition_granularity: `day`,
        allow_non_strict_date_range_match: true,
        refresh_key: {
          every: `1 hour`,
          incremental: true,
          update_window: `1 day`
        },
        build_range_start: {
          sql: `SELECT DATE_SUB(NOW(), 365)`
        },
        build_range_end: {
          sql: `SELECT NOW()`
        }
      }
    }
  })
  ```
</CodeGroup>

You run the following query on a regular basis, with the only difference
between queries being the filter values:

```json theme={"dark"}
{
  "measures": [
    "orders.order_total"
  ],
  "timeDimensions": [
    {
      "dimension": "orders.timestamp",
      "granularity": "hour",
      "dateRange": [
        "2022-12-14T06:00:00.000",
        "2023-01-13T06:00:00.000"
      ]
    }
  ],
  "order": {
    "orders.timestamp": "asc"
  },
  "filters": [
    {
      "member": "orders.product_category",
      "operator": "equals",
      "values": [
        "Electronics"
      ]
    },
    {
      "member": "orders.product_name",
      "operator": "equals",
      "values": [
        "Keyboard",
        "Mouse"
      ]
    }
  ],
  "dimensions": [
    "orders.zip_code"
  ],
  "limit": 10000
}
```

After running this query on a dataset with millions of records you find that
it's taking too long to run, so you decide to add an index to target this
specific query. Taking into account the best practices, you should define an
index as follows:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: main
          # ...

          indexes:
            - name: category_productname_zipcode_index
              columns:
                - product_category
                - zip_code
                - product_name
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    pre_aggregations: {
      main: {
        // ...

        indexes: {
          category_productname_zipcode_index: {
            columns: [
              product_category,
              zip_code,
              product_name
            ]
          }
        }
      }
    }
  })
  ```
</CodeGroup>

Here's why:

* The `product_category` dimension comes first as it's used in a single-value
  filter.
* Then, the `zip_code` dimension comes second as it's used in `GROUP BY`.
* The `product_name` dimension comes last as it's used in a multiple-value
  filter.

The data within `category_productname_zipcode_index` would look as follows:

| product\_category | zip\_code | product\_name | timestamp           | order\_total |
| ----------------- | --------- | ------------- | ------------------- | ------------ |
| Electronics       | 88523     | Mouse         | 2023-01-01 10:00:00 | 800          |
| Electronics       | 88523     | Plastic Chair | 2023-01-01 10:00:00 | 2000         |
| Furniture         | 88523     | Keyboard      | 2023-01-01 10:00:00 | 1000         |
| Electronics       | 88524     | Keyboard      | 2023-01-01 11:00:00 | 2000         |
| Furniture         | 88524     | Plastic Chair | 2023-01-01 11:00:00 | 3000         |

### Aggregating indexes

A regular index (the kind described above) is a *sorted copy* of the full
pre-aggregation: it contains the same rows at the same granularity, just ordered
differently so that a particular query can be served with a fast merge scan. An
**aggregating index** goes one step further. It stores **only** the dimensions
listed in its definition, together with the pre-aggregated measures, and rolls the
data up over every dimension that is *not* in the index.

**In other words, an aggregating index is a rollup of the data that already lives
inside a rollup table.** Cube Store aggregates over the missing dimensions once,
when the index is built. At query time that work is already done, so a query that
matches the index reads far fewer rows and skips the aggregation step entirely.

Take the `main` pre-aggregation [from above](#example). A regular index keeps
every `timestamp` / `product_name` / `product_category` / `zip_code` combination.
An aggregating index on `zip_code` alone collapses all of that into one row per
ZIP code:

| zip\_code | order\_total |
| --------- | ------------ |
| 88523     | 3800         |
| 88524     | 5000         |

#### When to use an aggregating index

Reach for an aggregating index when you have a **wide** pre-aggregation (many
dimensions) that is frequently queried on a **small, fixed subset** of those
dimensions. The classic example is a rollup with 50 dimensions where a recurring
dashboard tile only ever groups by 5 of them. The aggregating index materializes
exactly that narrow shape, so the tile reads a tiny pre-rolled table instead of
scanning and re-aggregating the full pre-aggregation.

The decision is usually between an aggregating index and a *second
pre-aggregation* for the same narrow shape. The economics favor the index:

* Each pre-aggregation is built by querying your data source independently, so
  *N* pre-aggregations means *N* expensive warehouse reads.
* A single pre-aggregation with *N* aggregating indexes is built from **one**
  warehouse read — Cube Store derives every index locally during ingestion.

You get roughly the same Cube Store query performance at a fraction of the
warehouse cost. The cost is paid in pre-aggregation *build* time, which grows with
each index.

The following table summarizes how the two index types differ:

|                    | Regular index                                                   | Aggregating index                                        |
| ------------------ | --------------------------------------------------------------- | -------------------------------------------------------- |
| `type`             | `regular` (default; can be omitted)                             | `aggregate`                                              |
| What it stores     | All pre-aggregation rows, re-sorted                             | Only the index dimensions + rolled-up measures           |
| Granularity        | Same as the pre-aggregation                                     | Rolled up to the index dimensions                        |
| Size               | Same row count as the pre-aggregation                           | Typically much smaller                                   |
| Supported measures | Any                                                             | [Additive][ref-additivity] only                          |
| Query dimensions   | Any (affects only sort efficiency)                              | **All** must be columns of the index                     |
| Filters            | Any dimension                                                   | Only on dimensions that are columns of the index         |
| Best for           | Tuning sort order for known shapes; flexible and ad-hoc queries | A wide pre-aggregation queried on a narrow, fixed subset |

#### How regular and aggregating indexes work together

You don't have to choose one *or* the other. You can define both kinds on the same
pre-aggregation, and Cube Store selects the best index for each query
automatically:

* When a query **qualifies** for an aggregating index, Cube Store **prefers it**
  over regular indexes, because it is smaller and already rolled up. When several
  aggregating indexes qualify, the one with the smallest key wins.
* Any query that does **not** qualify falls back to a regular index (or the
  default index), so those queries are still optimized.

This is why the recommended pattern for a wide pre-aggregation is a couple of
regular indexes covering your general and ad-hoc query shapes, *plus* one
aggregating index per hot narrow query shape.

A query qualifies for an aggregating index only when **all** of the following
hold:

* Every measure used in the query is [additive][ref-additivity] — for example,
  measures built on `sum`, `count`, `min`, `max`, or `countDistinctApprox`.
  Non-additive measures (such as `avg` or exact `countDistinct`) can never use an
  aggregating index, because they cannot be re-derived from a partially rolled-up
  result.
* **Every** dimension used in the query is one of the index's columns.
* **Every** filter is on a dimension that is one of the index's columns. You
  cannot filter on a dimension that was rolled away when the index was built.

#### Defining aggregating indexes

Aggregating indexes are defined by adding the [`type` option][ref-ref-index-type]
to an index definition. Define them alongside your regular indexes so that Cube
Store can route each query to the most efficient one:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: main
          # ...

          indexes:
            # ...

            - name: zip_code_index
              columns:
                - zip_code
              type: aggregate
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("orders", {
    // ...

    pre_aggregations: {
      main: {
        // ...

        indexes: {
          // ...

          zip_code_index: {
            columns: [zip_code],
            type: `aggregate`
          }
        }
      }
    }
  })
  ```
</CodeGroup>

The data for `zip_code_index` would look as follows:

| zip\_code | order\_total |
| --------- | ------------ |
| 88523     | 3800         |
| 88524     | 5000         |

#### Putting it together

The two index types are most useful in combination. Building on the `main`
pre-aggregation from above, define both the regular index that targets your
filtered, multi-dimension query and the aggregating index that targets the narrow
ZIP-code rollup:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: main
          measures:
            - order_total
          dimensions:
            - product_name
            - product_category
            - zip_code
          time_dimension: timestamp
          granularity: hour
          # ...

          indexes:
            # Regular index: full-grain, re-sorted for the filtered query
            - name: category_productname_zipcode_index
              columns:
                - product_category
                - zip_code
                - product_name

            # Aggregating index: pre-rolled to a single dimension
            - name: zip_code_index
              columns:
                - zip_code
              type: aggregate
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("orders", {
    // ...

    pre_aggregations: {
      main: {
        measures: [order_total],
        dimensions: [product_name, product_category, zip_code],
        time_dimension: timestamp,
        granularity: `hour`,
        // ...

        indexes: {
          // Regular index: full-grain, re-sorted for the filtered query
          category_productname_zipcode_index: {
            columns: [product_category, zip_code, product_name]
          },

          // Aggregating index: pre-rolled to a single dimension
          zip_code_index: {
            columns: [zip_code],
            type: `aggregate`
          }
        }
      }
    }
  })
  ```
</CodeGroup>

Now consider two queries against this pre-aggregation.

**Query A — totals per ZIP code.** It groups by a single dimension that is a
column of the aggregating index, uses only an additive measure, and applies no
disqualifying filters:

```json theme={"dark"}
{
  "measures": ["orders.order_total"],
  "dimensions": ["orders.zip_code"]
}
```

This query **qualifies for `zip_code_index`**, so Cube Store serves it from the
two-row aggregating index rather than scanning the full pre-aggregation — even
though the regular index also contains `zip_code`, the smaller aggregating index
is preferred.

**Query B — filtered breakdown by product.** It filters on `product_category` and
groups by `product_name`:

```json theme={"dark"}
{
  "measures": ["orders.order_total"],
  "dimensions": ["orders.product_name"],
  "filters": [
    {
      "member": "orders.product_category",
      "operator": "equals",
      "values": ["Electronics"]
    }
  ]
}
```

This query **cannot** use `zip_code_index`: it groups by and filters on dimensions
that were rolled away. Cube Store automatically **falls back to the regular
`category_productname_zipcode_index`**, whose column order (`product_category`
first for the single-value filter, then the rest) lets it serve the query with a
fast merge scan.

With both indexes defined, each query is routed to the most efficient one without
any change to the query itself. Use [`EXPLAIN`][ref-cubestore-sql-commands] to
confirm which index a given query selects.

### Compaction

Whenever a newer version of pre-aggregation is just built and becomes available its performance would be suboptimal as it's pending compaction.
Most of the essential compaction process usually takes several seconds to several minutes for bigger partitions after pre-aggregation creation, depending on the size of the partition and the Cube Store workers' processing power available.
This compaction process is usually unnoticeable for queries that are optimal in terms of index usage, so it's always best practice to make sure all of your queries match an index.

## Inspecting pre-aggregations

Cube Store partially supports the MySQL protocol. This allows you to execute
simple queries using a familiar SQL syntax. You can connect using the MySQL CLI
client, for example:

```bash theme={"dark"}
mysql -h <CUBESTORE_IP> --user=cubestore -pcubestore --protocol=TCP
```

<Warning>
  Only Linux and Mac OS versions of MySQL client are supported as of right now.
  You can install one on ubuntu using `apt-get install default-mysql-client`
  command or `brew install mysql-client` on Mac OS. Windows versions of the MySQL
  client aren't supported.
</Warning>

To check which pre-aggregations are managed by Cube Store, you could run the
following query:

```sql theme={"dark"}
SELECT * FROM information_schema.tables;
+----------------------+-----------------------------------------------+
| table_schema         | table_name                                    |
+----------------------+-----------------------------------------------+
| dev_pre_aggregations | orders_main20190101_23jnqarg_uiyfxd0f_1gifflf |
| dev_pre_aggregations | orders_main20190301_24ph0a1c_utzntnv_1gifflf  |
| dev_pre_aggregations | orders_main20190201_zhrh5kj1_rkmsrffi_1gifflf |
| dev_pre_aggregations | orders_main20191001_mdw2hxku_waxajvwc_1gifflf |
| dev_pre_aggregations | orders_main20190701_izc2tl0h_bxsf1zlb_1gifflf |
+----------------------+-----------------------------------------------+
5 rows in set (0.01 sec)
```

These pre-aggregations are stored as Parquet files under the `.cubestore/`
folder in the project root during development.

### `EXPLAIN` queries

Cube Store's MySQL protocol also supports `EXPLAIN`, `EXPLAIN ANALYZE`, and
`EXPLAIN ANALYZE DETAILED`, all of which are useful for determining how much
processing a query will require, and for seeing where time is spent within it.

See [Cube Store SQL commands][ref-cubestore-sql-commands] for their syntax and
output, guidance on reading a query plan, and the rest of Cube Store's command
surface.

## Pre-aggregations storage

Cube uses its own purpose-built pre-aggregations engine: [Cube Store][ref-cube-store].

When using Cube Store, pre-aggregation data will be ingested and stored as Parquet files
on a [blob storage][ref-cube-store-storage]. Then, Cube Store would load that data to
execute queries using pre-aggregations.

However, [`original_sql`][ref-original-sql] pre-aggregations are stored in the data source
by default. It is not recommended to store `original_sql` pre-aggregations in Cube Store.

## Joins between pre-aggregations

When making a query that joins data from two different cubes, Cube can use
pre-aggregations instead of running the base SQL queries. To get started, first
ensure both cubes have valid pre-aggregations:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: orders_rollup
          measures:
            - CUBE.count
          dimensions:
            - CUBE.user_id
            - CUBE.status
          time_dimension: CUBE.created_at
          granularity: day

      joins:
        - name: users
          sql: "{CUBE.user_id} = ${users.id}"
          relationship: many_to_one

    - name: users
      # ...

      pre_aggregations:
        - name: users_rollup
          dimensions:
            - CUBE.id
            - CUBE.name
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    pre_aggregations: {
      orders_rollup: {
        measures: [CUBE.count],
        dimensions: [CUBE.user_id, CUBE.status],
        time_dimension: CUBE.created_at,
        granularity: `day`
      }
    },

    joins: {
      users: {
        sql: `${CUBE.user_id} = ${users.id}`,
        relationship: `many_to_one`
      }
    }
  })

  cube(`users`, {
    // ...

    pre_aggregations: {
      users_rollup: {
        dimensions: [CUBE.id, CUBE.name]
      }
    }
  })
  ```
</CodeGroup>

Before we continue, let's add an index to the `orders_rollup` pre-aggregation so
that the `rollup_join` pre-aggregation can work correctly:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: orders_rollup
          # ...

          indexes:
            - name: user_index
              columns:
                - CUBE.user_id
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    pre_aggregations: {
      orders_rollup: {
        // ...

        indexes: {
          user_index: {
            columns: [CUBE.user_id]
          }
        }
      }
    }
  })
  ```
</CodeGroup>

Now we can add a new pre-aggregation of type `rollup_join` to the `orders` cube:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        # ...

        - name: orders_with_users_rollup
          type: rollup_join
          measures:
            - CUBE.count
          dimensions:
            - users.name
          time_dimension: CUBE.created_at
          granularity: day
          rollups:
            - users.users_rollup
            - CUBE.orders_rollup
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    pre_aggregations: {
      // ...

      orders_with_users_rollup: {
        type: `rollup_join`,
        measures: [CUBE.count],
        dimensions: [users.name],
        time_dimension: CUBE.created_at,
        granularity: `day`,
        rollups: [users.users_rollup, CUBE.orders_rollup]
      }
    }
  })
  ```
</CodeGroup>

With all of the above set up, making a query such as the following will now use
`orders.orders_rollup` and `users.users_rollup`, avoiding a database request:

```json theme={"dark"}
{
  "dimensions": ["users.name"],
  "timeDimensions": [
    {
      "dimension": "orders.created_at",
      "dateRange": "This month"
    }
  ],
  "order": {
    "orders.count": "desc"
  },
  "measures": ["orders.count"]
}
```

### Indexing the joined rollup for partition pruning

A `rollup_join` can only be planned if each side of the join can be scanned in
join-key order — either from the rollup's default index, where dimensions come
first, or from an explicit index whose leading columns cover the join key, like
`user_index` above. However, an index that *starts* with the join key gives you
no partition pruning: Cube Store partitions are ranged by index order, so a
filter only prunes partitions when it constrains the index's leading column. A
filter on the second column of an index prunes nothing unless a partition
happens to cover a single value of the first column.

**When queries filter the joined rollup by a highly selective, single-value
dimension, define an index that puts that dimension before the join key.**
Suppose `users` has such a dimension, `alt_key`, and queries commonly filter on
it. Add it to `users_rollup` and index it ahead of the join key:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      # ...

      pre_aggregations:
        - name: users_rollup
          dimensions:
            - CUBE.id
            - CUBE.name
            - CUBE.alt_key

          indexes:
            - name: alt_key_index
              columns:
                - CUBE.alt_key
                - CUBE.id
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    // ...

    pre_aggregations: {
      users_rollup: {
        dimensions: [CUBE.id, CUBE.name, CUBE.alt_key],

        indexes: {
          alt_key_index: {
            columns: [CUBE.alt_key, CUBE.id]
          }
        }
      }
    }
  })
  ```
</CodeGroup>

Cube Store will pick `alt_key_index` for the joined side of such a query — the
join key is still covered by the index's leading columns, it just doesn't come
first — and prune every partition whose range excludes the filtered value.

This pays off twice over, because the joined rollup's partitions are never split
up: only the left-most rollup is divided into batches, and every batch carries
all partitions of the joined one. Those partitions also consume the per-batch
join budget that bounds how large the right side of a rollup join can be, so
pruning them can be what keeps a query planning at all.

A few things to keep in mind:

* Only single-value (equality) filters let the filtered dimension sit ahead of
  the join key. A range filter, including a time dimension filter, won't make
  such an index eligible for the join — though a range filter on an index's
  leading column does prune partitions normally.
* The join key must still be part of the index's leading columns, together with
  the filtered dimension. Listing the filtered dimension alone, without the join
  key, makes the index unusable for the join.
* Queries that hit the rollup join without the equality filter are planned on a
  join-key-leading scan instead, so keep one available — the default index
  serves that as long as the join key is the rollup's first dimension.
* The other side of the join — typically the large rollup carrying the time
  dimension — still needs to be scanned in join-key order, and its time
  dimension filter will not prune partitions there.
* Each extra index adds build time and storage, so add one when the filter is
  both common and selective.

As always,
[use `EXPLAIN` and `EXPLAIN ANALYZE`][ref-cubestore-sql-commands] to confirm
which index was picked and how many partitions were scanned.

## Pre-Aggregation build strategies

<Info>
  For ideal performance, pre-aggregations should be built using a dedicated
  Refresh Worker. [See here for more details][ref-prod-list-refresh].
</Info>

Cube supports three different strategies for building pre-aggregations. To see
which strategies your database supports, please refer to its individual page
from [Connecting to the Database][ref-config-db].

### Simple

When using the simple strategy, Cube will use the source database as a temporary
staging area for writing pre-aggregations to determine column types. The data is
loaded back into memory before writing them to Cube Store (or an external
database).

<Info>
  For larger datasets, we strongly recommend using the [Batching][self-batching]
  or [Export Bucket][self-export-bucket] strategies instead.
</Info>

<div>
  <img alt="Internal vs External vs External with Cube Store diagram" />
</div>

### Batching

Batching is a more performant strategy where Cube sends compressed CSVs for Cube
Store to ingest.

<div>
  <img alt="Internal vs External vs External with Cube Store diagram" />
</div>

The performance scales to the amount of memory available on the Cube instance.
Batching is automatically enabled for any databases that can support it.

### Export bucket

<Warning>
  The export bucket strategy requires permission to execute `CREATE TABLE`
  statements in the data source as part of the pre-aggregation build process.
</Warning>

<Warning>
  Do not confuse the export bucket with the Cube Store storage bucket. Those are
  two separate storages and should never be mixed.
</Warning>

When dealing with larger pre-aggregations (more than 100k rows), performance can
be significantly improved by using an export bucket. This allows the source
database to temporarily materialize the data locally, which is then loaded into
Cube Store in parallel:

<div>
  <img alt="Internal vs External vs External with Cube Store diagram" />
</div>

Enabling the export bucket functionality requires extra configuration and is
not available for all data sources. Please
refer to the [database-specific documentation][ref-config-db] for more details.
Data sources that support export buckets will have an "Export Bucket" section with more information.

When using cloud storage, it is important to correctly configure any data
retention policies to clean up the data in the export bucket as Cube does not
currently manage this. For most use-cases, 1 day is sufficient.

## Streaming pre-aggregations

Streaming pre-aggregations are different from traditional pre-aggregations in
the way they are being updated. Traditional pre-aggregations follow the “pull”
model — Cube **pulls updates** from the data source based on some cadence and/or
condition. Streaming pre-aggregations follow the “push” model — Cube
**subscribes to the updates** from the data source and always keeps
pre-aggregation up to date.

You don’t need to define `refresh_key` for streaming pre-aggregations. Whether
pre-aggregation is streaming or not is defined by the data source.

Currently, Cube supports only one streaming data source -
[ksqlDB](/admin/connect-to-data/data-sources/ksqldb). All pre-aggregations where
data source is ksqlDB are streaming.

We are working on supporting more data sources for streaming pre-aggregations,
please [let us know](https://cube.dev/contact) if you are interested in early
access to any of these drivers or would like Cube to support any other SQL
streaming engine.

## Troubleshooting

### Unused pre-aggregations

You might find that a pre-aggregation is ignored by Cube. Possible reasons:

* A pre-aggregation does not reference any dimensions or measures from a cube
  where this pre-aggreation is [defined][ref-schema-ref-preaggs]. To resolve,
  move it to another cube.
* A pre-aggregation is defined similarly to another pre-aggregation that has
  more granular [partitions](#partitioning). To resolve, remove one of these
  pre-aggregations.

### Members with unknown types

When building pre-aggregations, you might get an error similar to the this one:

```text theme={"dark"}
Error during create table: CREATE TABLE <REDACTED>:
Custom type 'fixed' is not supported
```

It means that a member of a pre-aggregation has a type in the upstream data
source that Cube Store can not recognize (e.g., `fixed` in this case).

To resolve, please add a cast to a known type in the [`sql` parameter][ref-member-sql]
of this member. For numeric types, it will most likely be an integer, a float,
or a decimal type, depending on the nature of your data.

[ref-config-db]: /admin/connect-to-data/data-sources

[ref-schema-ref-preaggs]: /reference/data-modeling/pre-aggregations

[ref-schema-ref-preaggs-refresh-key]: /reference/data-modeling/pre-aggregations#refresh_key

[ref-schema-ref-preaggs-refresh-key-every]: /reference/data-modeling/pre-aggregations#every

[ref-schema-ref-preaggs-refresh-key-sql]: /reference/data-modeling/pre-aggregations#sql

[ref-deploy-refresh-wrkr]: /cube-core/architecture#refresh-worker

[ref-prod-list-refresh]: /cube-core/running-in-production#set-up-refresh-worker

[ref-original-sql]: /reference/data-modeling/pre-aggregations#original_sql

[self-batching]: #batching

[self-export-bucket]: #export-bucket

[wiki-partitioning]: https://en.wikipedia.org/wiki/Partition_\(database\)

[ref-ref-indexes]: /reference/data-modeling/pre-aggregations#indexes

[ref-additivity]: /docs/pre-aggregations/matching-pre-aggregations

[ref-ref-index-type]: /reference/data-modeling/pre-aggregations#type-1

[ref-flame-graph]: /admin/monitoring/query-history#flame-graph

[ref-perf-insights]: /admin/monitoring/performance

[ref-build-history]: /admin/monitoring/pre-aggregations#build-history

[ref-matching-preaggs]: /docs/pre-aggregations/matching-pre-aggregations

[ref-cube-store]: /docs/pre-aggregations/running-in-production#architecture

[ref-cubestore-sql-commands]: /reference/cubestore/sql-commands

[ref-cube-store-storage]: /docs/pre-aggregations/running-in-production#storage

[ref-member-sql]: /reference/data-modeling/dimensions#sql

[ref-incremental-refresh-recipe]: /recipes/pre-aggregations/incrementally-building-pre-aggregations-for-a-date-range


# Preferences
Source: https://docs.cube.dev/docs/preferences

Customize your personal Cube experience — theme, language, and other per-user settings.

Each user can customize their Cube experience from the **Preferences** page
(`/preferences`), accessible from the user menu. These settings are saved to your own
account, apply across all devices, and don't affect other users in the account.

| Preference             | Description                                                                    | Default            |
| ---------------------- | ------------------------------------------------------------------------------ | ------------------ |
| Theme                  | Choose between System, Light, or Dark visual theme                             | System             |
| Language               | Choose the language for the Cube interface                                     | English (US)       |
| Time zone              | Run your queries in this time zone, so dates like "today" match your local day | Deployment default |
| Sidebar drawer         | Show only icons and expand the sidebar on hover                                | Off                |
| Pointer cursors        | Use pointer cursors on interactive elements                                    | On                 |
| Code editor            | Switch to the new CodeMirror-based code editor for data models                 | Off                |
| New message scrolling  | Automatically scroll to new messages in chat                                   | On                 |
| Alternating row colors | Highlight alternating rows in data tables                                      | Off                |
| Default deployment     | Open this deployment when you go to Cube without one in the URL                | Account default    |

## Language

The Cube interface is available in 10 languages across 12 locales (Spanish and
Portuguese each have two regional variants). Set your language from the
**Language** picker in the **Appearance** section of the **Preferences** page. The
setting is per-user — it's stored on your profile and follows you across browsers and
devices. It also determines the language of transactional emails you receive from Cube,
such as budget alerts.

| Language                | Locale code |
| ----------------------- | ----------- |
| English (US)            | `en-US`     |
| Deutsch (Deutschland)   | `de-DE`     |
| Español (España)        | `es-ES`     |
| Español (Latinoamérica) | `es-MX`     |
| Français (France)       | `fr-FR`     |
| Italiano (Italia)       | `it-IT`     |
| 日本語 (日本)                | `ja-JP`     |
| Norsk bokmål (Norge)    | `nb-NO`     |
| Português (Brasil)      | `pt-BR`     |
| Português (Portugal)    | `pt-PT`     |
| Svenska (Sverige)       | `sv-SE`     |
| Tiếng Việt (Việt Nam)   | `vi-VN`     |

English (`en-US`) is the default and the fallback when no language is configured.

<Info>
  To set the language of **embedded** Cube surfaces (dashboards, Analytics Chat, and
  Creator Mode) instead, see [embedding localization](/embedding/iframe/localization).
</Info>

## Time zone

By default your queries run in the deployment's
[default time zone](/docs/data-modeling/configuration#default-time-zone). If your admin has
enabled **user time zones** and left personal time zones allowed, you can pick your own
under **Time zone** on the **Preferences** page — so time dimensions bucket into your
local day and `today` means your today.

Only a zone you pick is applied; Cube never silently switches you to your browser's zone.
If your device is somewhere else, Cube offers the detected zone as a dismissible
suggestion rather than applying it.

Leaving it as **Deployment default** follows the account-wide zone your admin set, or the
deployment's default time zone when there isn't one. The control is hidden when your admin
has not enabled the feature, or has turned off personal time zones — in that case
everyone queries in the account-wide zone.

See [Time zones](/admin/time-zones) for what a zone changes and how dashboards carry their
own.

## Default deployment

On an account with more than one deployment, **Default deployment** on the **Preferences**
page picks which one you land on when you open Cube without a deployment specified in the
URL. Leaving it as **Account default** falls back, in order, to the deployment you last
switched to, then the account-wide default an admin can set from the
[deployments list](/admin/deployment#list-of-deployments), then your most recently created
deployment. The control is hidden on accounts with only one reachable deployment.


# Authenticate requests to Cube with Auth0
Source: https://docs.cube.dev/embedding/authentication/auth0

Step-by-step Auth0 application and API setup, rules for enriching JWTs with claims, and Cube configuration for Auth0-issued tokens.

## Introduction

In this guide, you'll learn how to integrate Auth0 authentication with a Cube
deployment. If you already have a pre-existing application on Auth0 that you'd
like to re-use, please skip ahead to [Configure Cube][ref-config-auth0].

We'll be creating an Auth0 [application][link-auth0-docs-app] and
[API][link-auth0-docs-api], configuring a [rule on Auth0][link-auth0-docs-rules]
to add custom claims to vended JWTs, and finally configuring Cube to use Auth0.

## Create an application

First, go to the [Auth0 dashboard][link-auth0-app], and click on the
Applications menu option on the left and then click the Create Application
button.

<div>
  <img />
</div>

In the popup, set the name of your application and select Single Page Web
Applications.

<div>
  <img />
</div>

Next, go to the application's settings and add the appropriate callback URLs for
your application (`http://localhost:4000` for the Developer Playground).

### Custom claims

You can also configure custom claims for your JWT token. Auth0 has two SDKs
available; [Auth0.js][link-auth0-js] and the [Auth0 SPA
SDK][link-auth0-spa-sdk]. We recommend using the SPA SDK wherever possible, [as
per Auth0's own developer advice][gh-auth0-spa-sdk-issue34]. If you're using
`@auth0/auth0-angular` or `@auth0/auth0-react`, then the SPA SDK is
automatically included.

Open the Auth0 dashboard, click on 'Rules' and add a rule to add any custom
claims to the JWT.

#### Auth0 SPA SDK

<Info>
  Take note of the value of `namespace` here, you will need it later to [configure
  Cube][ref-config-auth0].
</Info>

```javascript theme={"dark"}
function (user, context, callback) {
  const namespace = "http://localhost:4000/"
  context.accessToken[namespace] =
  {
    'company_id': 'company1',
    'user_id': user.user_id,
    'roles': ['user']
  }
  callback(null, user, context)
}
```

## Create an API

If you're using the Auth0 SPA SDK, you'll also need to [create an
API][link-auth0-api]. First, go to the [Auth0 dashboard][link-auth0-app] and
click on the APIs menu option from the left sidebar, then click the Create API
button.

<div>
  <img />
</div>

In the 'New API' popup, set a name for this API and an identifier (e.g.
`cube-app`), then click the Create button.

<div>
  <img />
</div>

<Info>
  Take note of the Identifier here, as it is used to [set the JWT Audience option
  in Cube][ref-config-auth0].
</Info>

In your application code, configure your API identifier as the audience when
initializing Auth0. If you're using the `@auth0/auth-react` package for your
application front-end, this might look something like this:

```tsx theme={"dark"}
<Auth0Provider
  domain={process.env.AUTH_DOMAIN}
  client_id={process.env.AUTH_CLIENT_ID}
  redirect_uri={window.location.origin}
  onRedirectCallback={() => {}}
  audience="cube"
>
```

Refer to Auth0's documentation for instructions on configuring
[Angular][link-auth0-angular] or [Vue][link-auth0-vue] applications.

## Configure Cube

Now we're ready to configure Cube to use Auth0. Go to your Cube project and open
the `.env` file and add the following, replacing the values wrapped in `<>`.

```dotenv theme={"dark"}
CUBEJS_JWK_URL=https://<AUTH0-SUBDOMAIN>.auth0.com/.well-known/jwks.json
CUBEJS_JWT_AUDIENCE=<APPLICATION_URL>
CUBEJS_JWT_ISSUER=https://<AUTH0-SUBDOMAIN>.auth0.com/
CUBEJS_JWT_ALGS=RS256
CUBEJS_JWT_CLAIMS_NAMESPACE=<CLAIMS_NAMESPACE>
```

## Testing with the Developer Playground

### Retrieving a JWT

Go to the [OpenID Playground from Auth0][link-openid-playground] to and click
Configuration.

<div>
  <img />
</div>

Enter the following values:

* **Auth0 domain**: `<AUTH0-SUBDOMAIN>.auth0.com`
* **OIDC Client ID**: Retrieve from Auth0 Application settings page
* **OIDC Client Secret**: Retrieve from Auth0 Application settings page
* **Audience**: Retrieve from Auth0 API settings

Click 'Use Auth0 Discovery Document' to auto-fill the remaining values, then
click Save.

<div>
  <img />
</div>

<Warning>
  If you haven't already, go back to the Auth0 application's settings and add
  `https://openidconnect.net/callback` to the list of allowed callback URLs.
</Warning>

Now click Start; if the login is successful, you should see the code, as well as
a button called 'Exchange'. Click on it to exchange the code for your tokens:

<div>
  <img />
</div>

Copy the `access_token` from the response, and use the [JWT.IO
Debugger][link-jwt-io-debug] to decode the token and verify any custom claims
were successfully added.

### Set JWT in Developer Playground

Now open the Developer Playground (at `http://localhost:4000`) and on the Build
page, click Add Security Context.

<div>
  <img />
</div>

Click the Token tab, paste the JWT from OpenID Playground and click the Save
button.

<div>
  <img />
</div>

Close the popup and use the Developer Playground to make a request. Any data
models using the [Security Context][ref-sec-ctx] should now work as expected.

## Example

To help you get up and running, we have [an example project which is configured
to use Auth0][gh-cube-auth0-example]. You can use it as a starting point for
your own Cube application.

[link-auth0-angular]: https://auth0.com/docs/quickstart/spa/angular/01-login

[link-auth0-vue]: https://auth0.com/docs/quickstart/spa/vuejs/01-login

[link-auth0-docs-app]: https://auth0.com/docs/applications

[link-auth0-docs-api]: https://auth0.com/docs/get-started/set-up-apis

[link-auth0-docs-rules]: https://auth0.com/docs/rules

[gh-auth0-spa-sdk-issue34]: https://github.com/auth0/auth0-spa-js/issues/34#issuecomment-505420895

[link-auth0-app]: https://manage.auth0.com/

[link-auth0-js]: https://auth0.com/docs/libraries/auth0js

[link-auth0-spa-sdk]: https://auth0.com/docs/libraries/auth0-spa-js

[link-auth0-api]: https://auth0.com/docs/tokens/access-tokens#json-web-token-access-tokens

[link-jwt-io-debug]: https://jwt.io/#debugger-io

[link-openid-playground]: https://openidconnect.net/

[ref-config-auth0]: #configure-cube

[ref-sec-ctx]: /docs/data-modeling/access-control/context

[gh-cube-auth0-example]: https://github.com/cube-js/examples/tree/master/auth0


# Authenticate requests to Cube with AWS Cognito
Source: https://docs.cube.dev/embedding/authentication/aws-cognito

Step-by-step wiring of AWS Cognito User Pools and Hosted UI to Cube, including optional Lambda hooks for custom JWT claims.

## Introduction

In this guide, you'll learn how to integrate AWS Cognito authentication with a
Cube deployment. If you already have a pre-existing Cognito User Pool in AWS
that you'd like to re-use, please skip ahead to
[Configure Cube](#configure-cube).

## Create and configure a User Pool

If you haven't already created a User Pool, please follow [the instructions in
the AWS Cognito documentation][link-aws-cognito-hosted-ui] to create one, along
with enabling the Hosted UI.

### Custom claims

To add custom claims to the JWT, you will need to associate [a Lambda
function][link-aws-lambda] to the [Pre Token Generation event
trigger][link-aws-cognito-pre-token] available on your User Pool.

First, go to the AWS Lambda Console and create new a Lambda function:

<div>
  <img />
</div>

Add the following code to the Lambda function:

```javascript theme={"dark"}
exports.handler = (event, context, callback) => {
  event.response = {
    claimsOverrideDetails: {
      claimsToAddOrOverride: {
        "http://localhost:4000/": JSON.stringify({
          company_id: "company1",
          user_id: event.request.userAttributes.sub,
          roles: ["user"]
        })
      }
    }
  }
  
  callback(null, event)
}
```

Then navigate to the Amazon Cognito User Pools Console, select Triggers from the
left sidebar and associate the Lambda function you created previously:

<div>
  <img />
</div>

You can find more examples of [modifying claims in JWTs
here][link-aws-cognito-pretoken-example].

## Configure Cube

Now we're ready to configure Cube to use AWS Cognito. Go to your Cube project
and open the `.env` file and add the following, replacing the values wrapped in
`<>`.

```dotenv theme={"dark"}
CUBEJS_JWK_URL=https://cognito-idp.<AWS_REGION>.amazonaws.com/<USER_POOL_ID>/.well-known/jwks.json
CUBEJS_JWT_AUDIENCE=<APPLICATION_URL>
CUBEJS_JWT_ISSUER=https://cognito-idp.<AWS_REGION>.amazonaws.com/<USER_POOL_ID>
CUBEJS_JWT_ALGS=RS256
CUBEJS_JWT_CLAIMS_NAMESPACE=<CLAIMS_NAMESPACE>
```

## Testing with the Developer Playground

### Retrieving a JWT

Go to the [OpenID Playground from Auth0][link-openid-playground] to and click
Configuration.

<div>
  <img />
</div>

Change the Server Template to Custom, and enter the following values:

<div>
  <img />
</div>

* **Discovery Document URL**:
  `https://cognito-idp.<AWS_REGION>.amazonaws.com/<USER_POOL_ID>/.well-known/openid-configuration`
* **OIDC Client ID**: Retrieve from App Client settings page in AWS Cognito User
  Pool Console
* **OIDC Client Secret**: Retrieve from App Client settings page in AWS Cognito
  User Pool Console

Click 'Use Discovery Document' to auto-fill the remaining values, then click
Save.

<Warning>
  If you haven't already, go back to the AWS Cognito App Client's settings and add
  `https://openidconnect.net/callback` to the list of allowed callback URLs.
</Warning>

Now click Start; and in a separate tab, go to the App Client's settings page and
click the Launch Hosted UI button.

<div>
  <img />
</div>

If the login is successful, you should be redirected to the OpenID Connect
Playground. Click on the Exchange button to exchange the code for your tokens:

<div>
  <img />
</div>

Click Next, and continue on to the next section and click the Verify button to
verify the JWT signature as well as decode the identity token:

<div>
  <img />
</div>

### Set JWT in Developer Playground

Now open the Developer Playground (at `http://localhost:4000`) and on the Build
page, click Add Security Context.

<div>
  <img />
</div>

Click the Token tab, paste the `id_token` from OpenID Playground and click the
Save button.

<div>
  <img />
</div>

Close the popup and use the Developer Playground to make a request. Any data
models using the [Security Context][ref-sec-ctx] should now work as expected.

[link-aws-cognito-hosted-ui]: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-app-integration.html#cognito-user-pools-create-an-app-integration

[link-aws-cognito-pre-token]: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html

[link-aws-cognito-pretoken-example]: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html#aws-lambda-triggers-pre-token-generation-example-1

[link-aws-lambda]: https://docs.aws.amazon.com/lambda/latest/dg/welcome.html

[link-openid-playground]: https://openidconnect.net/

[ref-sec-ctx]: /docs/data-modeling/access-control/context


# JSON Web Token authentication
Source: https://docs.cube.dev/embedding/authentication/jwt

Walks through validating JWTs from clients or identity providers, the relevant Cube settings and environment variables, and custom check_auth implementations.

Some visualization tools (e.g., custom front-end applications) can pass access tokens based
on the [JSON Web Token][wiki-jwt] (JWT) standard to Cube. These tokens can be either generated
by these applications or obtained from an identity provider. Cube then validates these tokens.

The diagram below shows how it works during the request processing in Cube:

<div>
  <img />
</div>

## Configuration

Relevant configuration options: [`check_auth`][ref-config-check-auth] and [`jwt`][ref-config-jwt].

Relevant environment variables: [`CUBEJS_API_SECRET`](/reference/configuration/environment-variables#cubejs_api_secret), [`CUBEJS_JWT_KEY`](/reference/configuration/environment-variables#cubejs_jwt_key), [`CUBEJS_JWK_URL`](/reference/configuration/environment-variables#cubejs_jwk_url),
[`CUBEJS_JWT_AUDIENCE`](/reference/configuration/environment-variables#cubejs_jwt_audience), [`CUBEJS_JWT_ISSUER`](/reference/configuration/environment-variables#cubejs_jwt_issuer), [`CUBEJS_JWT_SUBJECT`](/reference/configuration/environment-variables#cubejs_jwt_subject), [`CUBEJS_JWT_CLAIMS_NAMESPACE`](/reference/configuration/environment-variables#cubejs_jwt_claims_namespace).

## Custom authentication

Cube allows you to provide your own JWT verification logic. You can use the
[`check_auth`][ref-config-check-auth] configuration option to verify a JWT and set the security context.

A typical use case would be:

1. A web server serves a page which needs to communicate with the Cube API.
2. The web server generates a JWT. The
   server includes the token in the page or provides the token to
   the frontend via an XHR request. The token is then stored in the local storage or
   a cookie.
3. The token is used for calls to the Cube API.
4. The token is received by Cube, and verified using any available JWKS (if configured)
5. Once decoded, the token claims are injected into the [security
   context][ref-sec-ctx].

<Warning>
  **In development mode, the token is not required for authorization.** JWT
  verification on this API is enabled by `NODE_ENV=production`, so it is off whenever
  `NODE_ENV` is anything else. Under the `cubejs` CLI and the official Docker images,
  setting
  [`CUBEJS_DEV_MODE=true`](/reference/configuration/environment-variables#cubejs_dev_mode)
  also forces `NODE_ENV=development`, which switches verification off even where it was
  otherwise on. A custom [`check_auth`](/reference/configuration/config#check_auth) that
  rejects unauthenticated requests enforces it whatever `NODE_ENV` is.

  `cubejs server` and the official Docker images set `NODE_ENV=production`, so
  verification is on there unless you enable development mode. Development mode also
  exposes Playground's unauthenticated endpoints, which hand out and mint valid tokens
  carrying any security context, signed with your API secret. This is
  intentional — development mode is designed for local development machines only. Never
  use it in production, and using it in the Cube cloud platform is highly discouraged
  because it bypasses the platform's security model.

  You can still pass a token in development mode to [set a security
  context][ref-sec-ctx].
</Warning>

## Generating JSON Web Tokens

Authentication tokens are generated based on your API secret. Cube CLI generates
an API Secret when a project is scaffolded and saves this value in the `.env`
file as [`CUBEJS_API_SECRET`](/reference/configuration/environment-variables#cubejs_api_secret).

You can generate two types of tokens:

* Without security context, which will mean that all users will have the same
  data access permissions.
* With security context, which will allow you to implement role-based security
  models where users will have different levels of access to data.

<Info>
  It is considered best practice to use an `exp` expiration claim to limit the
  lifetime of your public tokens. [Learn more in the JWT docs][link-jwt-docs].
</Info>

You can find a library to generate JWTs for your programming language
[here][link-jwt-libs].

In Node.js, the following code shows how to generate a token which will expire
in 30 days. We recommend using the `jsonwebtoken` package for this.

```javascript theme={"dark"}
const jwt = require("jsonwebtoken")
const CUBE_API_SECRET = "secret"

const cubeToken = jwt.sign({}, CUBE_API_SECRET, { expiresIn: "30d" })
```

Then, in a web server or cloud function, create a route which generates and
returns a token. In general, you will want to protect the URL that generates
your token using your own user authentication and authorization:

```javascript theme={"dark"}
app.use((req, res, next) => {
  if (!req.user) {
    res.redirect("/login")
    return
  }

  next()
})

app.get("/auth/cubejs-token", (req, res) => {
  res.json({
    // Take note: Cube expects the JWT payload to contain an object!
    token: jwt.sign(req.user, process.env.CUBEJS_API_SECRET, {
      expiresIn: "1d"
    })
  })
})
```

Then, on the client side, (assuming the user is signed in), fetch a token from
the web server:

```javascript theme={"dark"}
let apiTokenPromise

const cubeApi = cube(
  () => {
    if (!apiTokenPromise) {
      apiTokenPromise = fetch(`${API_URL}/auth/cubejs-token`)
        .then((res) => res.json())
        .then((r) => r.token)
    }
    
    return apiTokenPromise
  },
  {
    apiUrl: `${API_URL}/cubejs-api/v1`
  }
)
```

You can optionally store this token in local storage or in a cookie, so that you
can then use it to query the Cube API.

## Using JSON Web Key Sets

<Info>
  Looking for a guide on how to connect a specific identity provider? Check out
  our recipes for using [Auth0][ref-recipe-auth0] or [AWS
  Cognito][ref-recipe-cognito] with Cube.
</Info>

As mentioned previously, Cube supports verifying JWTs using industry-standard
JWKS. The JWKS can be provided either from a URL, or as a JSON object conforming
to [JWK specification RFC 7517 Section 4][link-jwk-ref], encoded as a string.

### Using a key as a JSON string

Add the following to your `cube.js` configuration file:

```javascript theme={"dark"}
module.exports = {
  jwt: {
    key: "<JWK_AS_STRING>"
  }
}
```

Or configure the same using environment variables:

```dotenv theme={"dark"}
CUBEJS_JWT_KEY='<JWK_AS_STRING>'
```

### Using a key from a URL

<Info>
  When using a URL to fetch the JWKS, Cube will automatically cache the response,
  re-use it and update if a key rotation has occurred.
</Info>

Add the following to your `cube.js` configuration file:

```javascript theme={"dark"}
module.exports = {
  jwt: {
    jwkUrl: "<URL_TO_JWKS_JSON>"
  }
}
```

Or configure the same using environment variables:

```dotenv theme={"dark"}
CUBEJS_JWK_URL='<URL_TO_JWKS_JSON>'
```

### Verifying claims

Cube can also verify the audience, subject and issuer claims in JWTs. Similarly
to JWK configuration, these can also be configured in the `cube.js`
configuration file:

```javascript theme={"dark"}
module.exports = {
  jwt: {
    audience: "<AUDIENCE_FROM_IDENTITY_PROVIDER>",
    issuer: ["<ISSUER_FROM_IDENTITY_PROVIDER>"],
    subject: "<SUBJECT_FROM_IDENTITY_PROVIDER>"
  }
}
```

Using environment variables:

```dotenv theme={"dark"}
CUBEJS_JWT_AUDIENCE='<AUDIENCE_FROM_IDENTITY_PROVIDER>'
CUBEJS_JWT_ISSUER='<ISSUER_FROM_IDENTITY_PROVIDER>'
CUBEJS_JWT_SUBJECT='<SUBJECT_FROM_IDENTITY_PROVIDER>'
```

### Custom claims namespace

Cube can also extract claims defined in custom namespaces. Simply specify the
namespace in your `cube.js` configuration file:

```javascript theme={"dark"}
module.exports = {
  jwt: {
    claimsNamespace: "my-custom-namespace"
  }
}
```

[wiki-jwt]: https://en.wikipedia.org/wiki/JSON_Web_Token

[link-jwt-docs]: https://github.com/auth0/node-jsonwebtoken#token-expiration-exp-claim

[link-jwt-libs]: https://jwt.io/#libraries-io

[link-jwk-ref]: https://tools.ietf.org/html/rfc7517#section-4

[ref-config-check-auth]: /reference/configuration/config#check_auth

[ref-config-jwt]: /reference/configuration/config#jwt

[ref-recipe-auth0]: /embedding/authentication/auth0

[ref-recipe-cognito]: /embedding/authentication/aws-cognito

[ref-sec-ctx]: /docs/data-modeling/access-control/context


# Security context
Source: https://docs.cube.dev/embedding/authentication/security-context

Explains how verified JWT claims become the security context Cube uses for access control, query rewrite, and multi-tenant configuration.

Your authentication server issues JWTs to your client application, which, when
sent as part of the request, are verified and decoded by Cube to get security
context claims to evaluate access control rules. Inbound JWTs are decoded and
verified using industry-standard [JSON Web Key Sets (JWKS)][link-auth0-jwks].

For access control or authorization, Cube allows you to define granular access
control rules for every cube in your data model. Cube uses both the request and
security context claims in the JWT token to generate a SQL query, which includes
row-level constraints from the access control rules.

JWTs sent to Cube should be passed in the `Authorization: <JWT>` header to
authenticate requests.

JWTs can also be used to pass additional information about the user, known as a
**security context**. A security context is a verified set of claims about the
current user that the Cube server can use to ensure that users only have access
to the data that they are authorized to access.

It will be accessible as the [`securityContext`][ref-config-sec-ctx] property
inside:

* The [`query_rewrite`][ref-config-queryrewrite] configuration option in your
  Cube configuration  file.
* the [`COMPILE_CONTEXT`][ref-cubes-compile-ctx] global, which is used to
  support [multi-tenant deployments][link-multitenancy].

## Contents

By convention, the contents of the security context should be an object (dictionary)
with nested structure:

```json theme={"dark"}
{
  "sub": "1234567890",
  "iat": 1516239022,
  "user_name": "John Doe",
  "user_id": 42,
  "location": {
    "city": "San Francisco",
    "state": "CA"
  }
}
```

### Reserved elements

Some features of Cube Cloud (e.g., [authentication integration][ref-auth-integration])
use the `cubeCloud` element in the security context.
This element is reserved and should not be used for other purposes.

## Using query\_rewrite

You can use [`query_rewrite`][ref-config-queryrewrite] to amend incoming queries
with filters. For example, let's take the following query:

```json theme={"dark"}
{
  "measures": [
    "orders_view.count"
  ],
  "dimensions": [
    "orders_view.status"
  ]
}
```

We'll also use the following as a JWT payload; `user_id`, `sub` and `iat` will
be injected into the security context:

```json theme={"dark"}
{
  "sub": "1234567890",
  "iat": 1516239022,
  "user_id": 42
}
```

<Warning>
  Cube expects the context to be an object. If you don't provide an object as the
  JWT payload, you will receive the following error:

  ```bash theme={"dark"}
  Cannot create proxy with a non-object as target or handler
  ```
</Warning>

To ensure that users making this query only receive their own orders, define
`query_rewrite` in the configuration file:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('query_rewrite')
  def query_rewrite(query: dict, ctx: dict) -> dict:
    if 'user_id' in ctx['securityContext']:
      query['filters'].append({
        'member': 'orders_view.users_id',
        'operator': 'equals',
        'values': [ctx['securityContext']['user_id']]
      })
    return query
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    queryRewrite: (query, { securityContext }) => {
      
      if (securityContext.user_id) {
        query.filters.push({
          member: "orders_view.users_id",
          operator: "equals",
          values: [securityContext.user_id]
        })
      }

      return query
    }
  }
  ```
</CodeGroup>

To test this, we can generate an API token as follows:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  # Install the PyJWT with pip install PyJWT
  import jwt
  import datetime

  # Secret key to sign the token
  CUBE_API_SECRET = 'secret'

  # Create the token
  token_payload = {
    'user_id': 42
  }

  # Generate the JWT token
  token = jwt.encode(token_payload, CUBE_API_SECRET, algorithm='HS256')
  ```

  ```javascript title="JavaScript" theme={"dark"}
  const jwt = require("jsonwebtoken")
  const CUBE_API_SECRET = "secret"

  const cubeToken = jwt.sign({ user_id: 42 }, CUBE_API_SECRET, {
    expiresIn: "30d"
  })
  ```
</CodeGroup>

Using this token, we authorize our request to the Cube API by passing it in the
Authorization HTTP header.

```bash theme={"dark"}
curl \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1Ijp7ImlkIjo0Mn0sImlhdCI6MTU1NjAyNTM1MiwiZXhwIjoxNTU4NjE3MzUyfQ._8QBL6nip6SkIrFzZzGq2nSF8URhl5BSSSGZYp7IJZ4" \
  -G \
  --data-urlencode 'query={"measures":["orders.count"]}' \
  http://localhost:4000/cubejs-api/v1/load
```

And Cube will generate the following SQL:

```sql theme={"dark"}
SELECT
  "orders".STATUS "orders_view__status",
  count("orders".ID) "orders_view__count"
FROM
  ECOM.ORDERS AS "orders"
  LEFT JOIN ECOM.USERS AS "users" ON "orders".USER_ID = "users".ID
WHERE
  ("users".ID = 42)
GROUP BY
  1
ORDER BY
  2 DESC
LIMIT
  5000
```

## Using COMPILE\_CONTEXT

`COMPILE_CONTEXT` can be used to create fully dynamic data models. It enables you to create multiple versions of data model based on the incoming security context.
The first thing you need to do is to define the mapping rule from a security context to the id of the compiled data model.
It is done with `context_to_app_id` configuration option.

```python theme={"dark"}
from cube import config
 
@config('context_to_app_id')
def context_to_app_id(ctx: dict) -> str:
  return ctx['securityContext']['team']
```

It is common to use some field from the incoming security context as an id for your data model.
In our example, as illustrated below, we are using `team` property of the security context as a data model id.

<Frame>
  <img alt="COMPILE_CONTEXT mapping" />
</Frame>

Once you have this mapping, you can use `COMPILE_CONTEXT` inside your data model.
In the example below we are passing it as a variable into `masked` helper function.

```yaml theme={"dark"}
cubes:
  - name: users
    sql_table: ECOM.USERS
    public: false

    dimensions:
      - name: last_name
        sql: {{ masked('LAST_NAME', COMPILE_CONTEXT.securityContext) }}
        type: string
```

This `masked` helper function is defined in `model/globals.py` as follows: it checks if the current `team` is inside the list of trusted teams.
If that's the case, it will render the SQL to get the value of the dimension; if not, it will return just the masked string.

```python theme={"dark"}
from cube import TemplateContext
 
template = TemplateContext()

@template.function('masked')
def masked(sql, security_context):
  trusted_teams = ['cx', 'exec' ]
  is_trusted_team = security_context.setdefault('team') in trusted_teams
  if is_trusted_team:
    return sql
  else:
    return "'--- masked ---'"
```

### Usage with pre-aggregations

To generate pre-aggregations that rely on `COMPILE_CONTEXT`, [configure
`scheduledRefreshContexts` in your `cube.js` configuration
file][ref-config-sched-refresh].

### Usage for member-level security

You can also use `COMPILE_CONTEXT` to control whether a data model entity should be
public or private [dynamically][ref-dynamic-data-modeling].

In the example below, the `customers` view would only be visible to a subset
of [tenants][ref-multitenancy] that have the `team` property set to `marketing`
in the security context:

```ymltitle="model/views/customers.yml" theme={"dark"}
views:
  - name: customers
    public: "{{ is_accessible_by_team('marketing', COMPILE_CONTEXT) }}"
```

```pythontitle="model/globals.py" theme={"dark"}
from cube import TemplateContext

template = TemplateContext()

@template.function('is_accessible_by_team')
def is_accessible_by_team(team: str, ctx: dict) -> bool:
  return team == ctx['securityContext'].setdefault('team', 'default')
```

If you'd like to keep a data model entity public but prevent access to it
anyway, you can use the \[`query_rewrite` configuration option]\[ref-query-rewrite] for that.

## Testing during development

During development, it is often useful to be able to edit the security context
to test access control rules. The [Developer
Playground][ref-devtools-playground] allows you to set your own JWTs, or you can
build one from a JSON object.

## Enriching the security context

Sometimes it is convenient to enrich the security context with additional attributes
before it is used to evaluate access control rules.

### Extending the security context

You can use the [`extend_context`][ref-extend-context] configuration option to
enrich the security context with additional attributes.

### Authentication integration

When using Cube Cloud, you can enrich the security context with information about
an authenticated user, obtained during their authentication.

You can enable the authentication integration by navigating to the **Settings → Configuration**
of your Cube Cloud deployment and using the **Enable Cloud Auth Integration** toggle.

## Common patterns

### Enforcing mandatory filters

You can use `query_rewrite` to enforce mandatory filters that apply to all queries. This is useful when you need to ensure certain conditions are always met, such as filtering data by date range or restricting access to specific data subsets.

For example, if you want to only show orders created after a specific date across all queries, you can add a mandatory filter:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('query_rewrite')
  def query_rewrite(query: dict, ctx: dict) -> dict:
    query['filters'].append({
      'member': 'orders.created_at',
      'operator': 'afterDate',
      'values': ['2019-12-30']
    })
    return query
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    queryRewrite: (query) => {
      query.filters.push({
        member: `orders.created_at`,
        operator: "afterDate",
        values: ["2019-12-30"]
      })

      return query
    }
  }
  ```
</CodeGroup>

This filter will be automatically applied to all queries, ensuring that only orders created after December 30th, 2019 are returned, regardless of any other filters specified in the query.

### Enforcing role-based access

You can use `query_rewrite` to enforce role-based access control by filtering data based on the user's role from the security context.

For example, to restrict access so that users with the `operator` role can only view processing orders, while users with the `manager` role can only view shipped and completed orders:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('query_rewrite')
  def query_rewrite(query: dict, ctx: dict) -> dict:
    if not ctx['securityContext'].get('role'):
      raise ValueError("No role found in Security Context!")

    role = ctx['securityContext']['role']
    
    if role == "manager":
      query['filters'].append({
        'member': 'orders.status',
        'operator': 'equals',
        'values': ['shipped', 'completed']
      })
    elif role == "operator":
      query['filters'].append({
        'member': 'orders.status',
        'operator': 'equals',
        'values': ['processing']
      })

    return query
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    queryRewrite: (query, { securityContext }) => {
      if (!securityContext.role) {
        throw new Error("No role found in Security Context!")
      }

      if (securityContext.role == "manager") {
        query.filters.push({
          member: "orders.status",
          operator: "equals",
          values: ["shipped", "completed"]
        })
      }

      if (securityContext.role == "operator") {
        query.filters.push({
          member: "orders.status",
          operator: "equals",
          values: ["processing"]
        })
      }

      return query
    }
  }
  ```
</CodeGroup>

### Enforcing column-based access

You can use `query_rewrite` to enforce column-based access control by filtering data based on relationships and user attributes from the security context.

For example, to restrict suppliers to only see their own products based on their email:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('query_rewrite')
  def query_rewrite(query: dict, ctx: dict) -> dict:
    cube_names = [
      *(query.get('dimensions', [])),
      *(query.get('measures', []))
    ]
    cube_names = [e.split(".")[0] for e in cube_names]

    if "products" in cube_names:
      email = ctx['securityContext'].get('email')
      if not email:
        raise ValueError("No email found in Security Context!")

      query['filters'].append({
        'member': 'suppliers.email',
        'operator': 'equals',
        'values': [email]
      })

    return query
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    queryRewrite: (query, { securityContext }) => {
      const cubeNames = [
        ...(query.dimensions || []),
        ...(query.measures || [])
      ].map((e) => e.split(".")[0])

      if (cubeNames.includes("products")) {
        if (!securityContext.email) {
          throw new Error("No email found in Security Context!")
        }

        query.filters.push({
          member: `suppliers.email`,
          operator: "equals",
          values: [securityContext.email]
        })
      }

      return query
    }
  }
  ```
</CodeGroup>

### Controlling access to cubes and views

You can use `extend_context` and `COMPILE_CONTEXT` to control access to cubes and views based on user properties from the security context.

For example, to make a view accessible only to users with a `department` claim set to `finance`:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('extend_context')
  def extend_context(ctx: dict) -> dict:
    return {
      'securityContext': {
        **ctx['securityContext'],
        'isFinance': ctx['securityContext'].get('department') == 'finance'
      }
    }
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    extendContext: ({ securityContext }) => {
      return {
        securityContext: {
          ...securityContext,
          isFinance: securityContext.department === "finance"
        }
      }
    }
  }
  ```
</CodeGroup>

Then in your data model, use `COMPILE_CONTEXT` to control visibility:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: total_revenue_per_customer
      public: {{ COMPILE_CONTEXT['securityContext']['isFinance'] }}
      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`total_revenue_per_customer`, {
    public: COMPILE_CONTEXT.securityContext.isFinance,
    // ...
  })
  ```
</CodeGroup>

[link-auth0-jwks]: https://auth0.com/docs/tokens/json-web-tokens/json-web-key-sets

[link-multitenancy]: /embedding/multitenancy

[ref-config-queryrewrite]: /reference/configuration/config#query_rewrite

[ref-config-sched-refresh]: /reference/configuration/config#scheduledrefreshcontexts

[ref-config-sec-ctx]: /reference/configuration/config#securitycontext

[ref-cubes-compile-ctx]: /reference/data-modeling/context-variables#compile_context

[ref-devtools-playground]: /docs/explore-analyze/playground#editing-the-security-context

[ref-auth-integration]: /docs/data-modeling/access-control#authentication-integration

[ref-extend-context]: /reference/configuration/config#extend_context

[ref-dynamic-data-modeling]: /docs/data-modeling/dynamic

[ref-multitenancy]: /embedding/multitenancy


# Analytics Chat
Source: https://docs.cube.dev/embedding/iframe/analytics-chat

Embed Cube Analytics Chat into your applications via iframe.

<Info>
  Iframe embedding is available on [Premium and Enterprise plans](https://cube.dev/pricing).
</Info>

Embed [Analytics Chat](/docs/explore-analyze/analytics-chat) into your application using an iframe. Let your users ask questions in plain language and get trusted answers powered by your semantic layer — without leaving your product.

Analytics Chat can be embedded with either authentication mode:

* **[Private embedding](/embedding/iframe/auth/private)** — for internal users with Cube accounts
* **[Signed embedding](/embedding/iframe/auth/signed)** — for external/customer-facing applications using server-generated sessions

## Embed with private embedding

The embed URL for Analytics Chat is always the same:

```html theme={"dark"}
<iframe
  title="Analytics Chat"
  src="https://your-account.cubecloud.dev/embed/chat"
  width="100%"
  height="800"
></iframe>
```

Users will be prompted to sign in with their Cube credentials when accessing the embedded chat. See [Private embedding](/embedding/iframe/auth/private) for details on the auth model.

## Embed with signed embedding

To embed Analytics Chat for external/customer-facing applications, generate a session on your backend and pass the session ID into the iframe:

```html theme={"dark"}
<iframe
  title="Analytics Chat"
  src="https://your-tenant.cubecloud.dev/embed/chat?sessionId=YOUR_SESSION_ID"
  width="100%"
  height="800"
></iframe>
```

See [Signed embedding](/embedding/iframe/auth/signed) for the full session generation flow, API key setup, and a complete working example.

## Personalize chat with user attributes

When using signed embedding, you can pass [user attributes](/embedding/iframe/auth/signed#user-attributes) during session generation to personalize chat responses for each user — for example, scoping answers to a specific region, department, or tenant.

## Customize the chat

Add these query parameters to the embed URL to hide parts of the chat UI:

| Parameter         | Effect                                               |
| ----------------- | ---------------------------------------------------- |
| `hideNewChat=1`   | Hides the **New chat** button.                       |
| `hideChatInput=1` | Hides the message input, for a read-only transcript. |
| `hideHistory=1`   | Hides the **Chat History** button.                   |

By default, the chat header shows a **Chat History** button that lists the
user's past conversations (matched by `externalId` under signed embedding) so
they can resume one instead of always starting fresh.

To deep-link directly into a specific past conversation, pass its ID as
`chatId` alongside `sessionId` on the short embed URL:

```text theme={"dark"}
https://your-tenant.cubecloud.dev/embed/chat?sessionId=YOUR_SESSION_ID&chatId=YOUR_CHAT_ID
```


# Private embedding
Source: https://docs.cube.dev/embedding/iframe/auth/private

Authenticate iframe-embedded Cube content with users' existing Cube accounts.

<Info>
  Private embedding is available on [Premium and Enterprise plans](https://cube.dev/pricing).
</Info>

Private embedding is designed for **internal use cases** where team members already have Cube accounts. Simply drop an iframe into your internal tools — no API keys or session generation required. Users authenticate with their existing Cube credentials when accessing embedded content.

Use private embedding to embed:

* [Dashboards](/embedding/iframe/dashboards)
* [Analytics Chat](/embedding/iframe/analytics-chat)

<Note>
  Private embedding does not support [Creator Mode](/embedding/iframe/creator-mode) — use [Signed embedding](/embedding/iframe/auth/signed) instead.
</Note>

## How it works

To embed Cube content with private embedding, paste an `<iframe>` tag into your application or tool. Get the embed code from Cube and paste it wherever you want the content to appear.

When users open the page containing the iframe, they'll be prompted to sign in with their Cube credentials if they're not already authenticated. Access is then governed by their normal Cube [roles and permissions](/admin/users-and-permissions/roles-and-permissions).

## Common applications

### Embedding in Notion

To embed a Cube dashboard in Notion:

1. In Cube, open your dashboard and click **Share** → **Embed**
2. Copy the embed URL (just the URL, not the iframe code):
   ```
   https://your-account.cubecloud.dev/embed/dashboard/OwVQpbdaZmBT
   ```
3. In Notion, type `/embed` and select **Embed**
4. Paste the URL when prompted

When team members open the Notion page, they'll be prompted to sign in with their Cube credentials if not already authenticated.

### Embedding in Salesforce

To embed Cube analytics in Salesforce:

1. Navigate to the Salesforce page where you want to add the dashboard
2. Add a **Visualforce Page** component
3. Use an iframe to embed your Cube dashboard:

```html theme={"dark"}
<apex:page>
  <iframe
    src="https://your-account.cubecloud.dev/embed/dashboard/OwVQpbdaZmBT"
    width="100%"
    height="800"
    frameborder="0"
  ></iframe>
</apex:page>
```

## Security

Private embedding uses Cube's built-in authentication. Users must:

* Have an active Cube account
* Be signed in to Cube (or will be prompted to sign in)
* Have appropriate permissions to view the embedded content

Access control is managed through your existing Cube [roles and permissions](/admin/users-and-permissions/roles-and-permissions) settings.


# Signed embedding
Source: https://docs.cube.dev/embedding/iframe/auth/signed

Authenticate iframe-embedded Cube content with secure, server-generated sessions.

<Info>
  Signed embedding is available on [Premium and Enterprise plans](https://cube.dev/pricing).
</Info>

Signed embedding is designed for **external, customer-facing analytics**. It uses secure, server-generated sessions for authentication, making it ideal for:

* Embedding analytics in your SaaS application for customers
* White-label analytics solutions
* Multi-tenant applications where each customer sees their own data
* Public-facing dashboards with controlled access

Users authenticate through your application without needing Cube accounts, providing a seamless experience. The session tokens are cryptographically signed to ensure secure access with user-specific permissions.

Use signed embedding to embed:

* [Dashboards](/embedding/iframe/dashboards)
* [Analytics Chat](/embedding/iframe/analytics-chat)
* [Creator Mode](/embedding/iframe/creator-mode) (signed embedding is required)

## How it works

Signed embedding works through a two-step authentication flow:

1. **Generate a session** – Your backend generates a temporary session using the Cube API
2. **Exchange for a token** – The iframe automatically exchanges the session for a long-lived access token

**Session lifecycle:**

* **Sessions** are valid for **5 minutes** and must be exchanged within this window
* **Tokens** are usable for about **23 hours** after exchange — they're minted with a 24-hour expiry, but the iframe stops trusting one an hour early so an in-flight request can't lapse mid-call
* Sessions are single-use and expire after being exchanged
* A long-lived tab can renew its token **in place**, without reloading the iframe — see [Events & actions → Keeping a signed session alive](/embedding/iframe/events#keeping-a-signed-session-alive)

This ensures secure authentication while maintaining a smooth user experience.

## Getting started

### Get your API key

To use signed embedding, you need an [API key][ref-api-keys]:

* Go to **Access → API Keys** in your Cube admin panel
* Generate or copy your existing API key
* You'll use this key to authenticate API calls for generating embed sessions

### Generate an embed session

Use the [Generate Session API][ref-generate-session] to create a session for your user. This endpoint will automatically create (insert) or update the external user based on the `externalId` provided.

<Warning>
  Accounts are limited to 10,000 external users. To increase this limit, please
  contact support.
</Warning>

#### Example (JavaScript)

```javascript theme={"dark"}
const API_KEY = "YOUR_API_KEY";
const DEPLOYMENT_ID = 32;

const session = await fetch(
  "https://your-account.cubecloud.dev/api/v1/embed/generate-session",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Api-Key ${API_KEY}",
    },
    body: JSON.stringify({
      deploymentId: DEPLOYMENT_ID,
      externalId: "user@example.com",
      userAttributes: [
        // optional - enables row-level security
        {
          name: "city",
          value: "San Francisco",
        },
        {
          name: "department",
          value: "Sales",
        },
      ],
    }),
  },
);

const data = await session.json();
const sessionId = data.sessionId;
```

### Embed via iframe

Use the session ID to embed the dashboard or chat UI in your application. See [Dashboards](/embedding/iframe/dashboards) and [Analytics Chat](/embedding/iframe/analytics-chat) for the full iframe snippets.

#### Complete example

Here's a complete HTML example that demonstrates the full flow for embedding a dashboard:

```html theme={"dark"}
<html>
  <head>
    <script>
      (async () => {
        const API_BASE_URL = "https://your-tenant.cubecloud.dev";
        const API_KEY = "YOUR_API_KEY";
        const DEPLOYMENT_ID = 32;
        const externalId = "user@example.com";

        const sessionResponse = await fetch(
          `${API_BASE_URL}/api/v1/embed/generate-session`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              Authorization: `Api-Key ${API_KEY}`,
            },
            body: JSON.stringify({
              deploymentId: DEPLOYMENT_ID,
              externalId: externalId,
            }),
          },
        );

        const sessionData = await sessionResponse.json();

        const iframe = document.getElementById("dashboard-iframe");
        const baseUrl =
          "https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID";
        iframe.src = `${baseUrl}?session=${sessionData.sessionId}`;
      })();
    </script>
  </head>

  <body>
    <iframe
      id="dashboard-iframe"
      src=""
      width="100%"
      height="800"
      frameborder="0"
      allowtransparency="true"
      allowfullscreen="true"
    ></iframe>
  </body>
</html>
```

## User attributes

User attributes enable row-level security and personalized chat responses by filtering data based on user permissions. The attributes you pass during session generation automatically filter data queries and responses.

<Info>
  User attributes must first be configured in your Cube admin panel. See the
  [User Attributes documentation](/admin/users-and-permissions/user-attributes) for
  setup instructions.
</Info>

**How it works:**

1. **Configure attributes** in your admin panel (e.g., `city`, `department`)
2. **Pass attributes** during session generation
3. **Data is automatically filtered** based on user permissions through access policies
4. **AI responses are personalized** to the user's context

**Example use cases:**

* Sales reps only see data for their assigned territory
* Regional managers see data filtered by their city
* Department heads see only their department's metrics

## Example application

For a complete working example of signed embedding, check out the [cube-embedding-demo](https://github.com/cubedevinc/cube-embedding-demo) repository. This demo application provides:

* A full working example of iframe embedding
* Implementation of signed iframe embedding with session generation
* A React-based UI for testing embedding functionality
* Backend server that securely handles API key authentication

You can clone the repository, configure it with your Cube credentials, and run it locally to test embedding functionality or use it as a reference implementation for your own application.

[ref-api-keys]: /admin/account-billing/api-keys

[ref-generate-session]: /reference/embed-apis/generate-session


# Creator Mode
Source: https://docs.cube.dev/embedding/iframe/creator-mode

Embed the full Cube application so users can build and modify their own dashboards.

<Info>
  Creator Mode is available on the [Enterprise plan](https://cube.dev/pricing).
</Info>

Creator Mode embeds the full Cube application instead of an individual dashboard or chat. Users can create and modify workbooks, dashboards, and reports inside the iframe.

To enable it, pass `creatorMode: true` to the [Generate Session API][ref-generate-session].

<Note>
  Creator Mode requires [Signed embedding](/embedding/iframe/auth/signed). Private embedding is not supported.
</Note>

## Dashboard header controls

When a user opens a dashboard inside Creator Mode, its header renders the
same as in a standalone dashboard embed. To hide any of its controls (title,
back button, Edit, Duplicate) for your embed, see
[Show or hide header controls](/embedding/iframe/dashboards#show-or-hide-header-controls).

## Embed tenant scoping

In Creator Mode, content (workbooks, dashboards) and the groups/user attributes referenced by the session are scoped to an **embed tenant**. Pass `embedTenantName` to isolate content per customer; omit it to use the current tenant.

`embedTenantName` must be lowercase, 5–36 chars, start with a letter, end with a letter or digit, and contain only `a-z`, `0-9`, or `-`.

## Provisioning groups and user attributes

In Creator Mode, `groups` and `userAttributes` resolve against the embed tenant's scoped catalog (separate from the tenant-wide one used by read-only embedding). To define those entries from your backend in the same call, pass `groupDefinitions` and `userAttributeDefinitions` — they are idempotent and validated before memberships and values are applied.

See [Generate Session → Creator mode bootstrap][ref-bootstrap] for the input shape, value types, and the immutable-`type` rule on attribute definitions.

## Default dashboards

You can pre-populate every embed user's workspace with ready-made content so they see useful dashboards the first time they open the embedded app, instead of an empty workspace. This is a good way to ship templates or starter explorations that your users can open.

Default dashboards are shared from your **main workspace** with the **All embed users** (`all_embed_users`) group — a system group that Cube creates automatically once Creator Mode is enabled. Sharing is read-only: embed users can open and explore the shared content but can't edit it.

To set up default dashboards:

1. Build the workbooks, dashboards, folders, and explorations you want everyone to see in your main workspace.
2. Open the share dialog for a workbook, exploration, or folder and share it with **All embed users**. The only available access level is **Can view**.
3. Embed users in Creator Mode now see the shared items at the root of their workspace as soon as they open the app.

<Note>
  **All embed users** is a system group: it can't be renamed or deleted, and it can only be granted read-only (**Can view**) access. It appears automatically in **Admin → User Groups** and in the share dialog once Creator Mode is enabled for your workspace.
</Note>

Keep the following behavior in mind:

* **Sharing a folder** shares everything inside it — all nested folders, workbooks, and explorations become available to embed users.
* **Sharing a single workbook or exploration** exposes that item plus the folders above it (so users can navigate to it), but not the other contents of those folders.
* All embed users see the **same** default dashboards, regardless of their [groups](/admin/users-and-permissions/user-groups) or user attributes. The shared set applies across every embed tenant that belongs to your account.
* Embed users can't edit content shared from the main workspace. Opening a shared workbook shows its published dashboard, so a workbook must have a published dashboard for users to open it.
* Removing the share from the **All embed users** group removes those items from embed users' workspaces immediately.

## Sharing workbooks, explorations, dashboards, and folders

Embed users in Creator Mode can share the workbooks, explorations, dashboards, and folders they build with other users, the same way they would in the full Cube app. Sharing a folder shares everything inside it, and follows the same access levels — **Full access**, **Can edit**, **Can view** — as sharing a workbook.

<Note>
  Sharing is scoped to the [embed tenant](#embed-tenant-scoping): users can only share with others in the same tenant, never across tenants.
</Note>

## Folders and workbook actions

Embed users in Creator Mode can create, rename, and delete folders in their own workspace — gated by the same permissions as the full Cube app, and disabled inside a folder shared in from the main workspace. Opening a workbook's actions menu from its header (click the workbook name, or its chevron) offers **Rename**, **Duplicate**, and **Delete**, permission-gated the same way as the full app, plus **View all** and **New workbook** for navigating between workbooks.

## Example

```javascript theme={"dark"}
const session = await fetch(
  "https://your-account.cubecloud.dev/api/v1/embed/generate-session",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Api-Key ${API_KEY}`,
    },
    body: JSON.stringify({
      deploymentId: 32,
      externalId: "user@example.com",
      embedTenantName: "acme-corp",
      creatorMode: true,
    }),
  },
);

const { sessionId } = await session.json();
```

Embed the app with the returned session ID:

```html theme={"dark"}
<iframe
  title="Cube App"
  src="https://your-tenant.cubecloud.dev/embed/d/{deploymentId}/app?session={sessionId}"
  width="100%"
  height="800"
></iframe>
```

For a complete working example, see the [cube-embedding-demo](https://github.com/cubedevinc/cube-embedding-demo) repository.

[ref-generate-session]: /reference/embed-apis/generate-session

[ref-bootstrap]: /reference/embed-apis/generate-session#creator-mode-bootstrapping-groups-and-user-attributes


# Customization
Source: https://docs.cube.dev/embedding/iframe/customization

Customize the appearance of embedded dashboards and the embedded Cube app.

You can customize the appearance of iframe-embedded Cube content in two ways:

* **[Dashboard customization](#dashboard-customization)** — style an individual [dashboard](/embedding/iframe/dashboards) using the Styling panel in the Dashboard Builder
* **[App customization](#app-customization)** — pass theme parameters to the [Generate Session API](/reference/embed-apis/generate-session) when embedding the full Cube app in [Creator Mode](/embedding/iframe/creator-mode)

<Note>
  Customization options will expand over time. This page documents what is supported today.
</Note>

<Tip>
  To set the language of embedded surfaces — account-wide, per embed, or at runtime — see [Localization](/embedding/iframe/localization).
</Tip>

<Tip>
  To brand the whole embedded experience — accent color, background, text, logo, and fonts — at the account level, configure the [app theme](/admin/customization/app-theme). It applies to all embedded surfaces automatically (and, optionally, to the entire Cube Cloud console).
</Tip>

## Dashboard customization

Style an individual dashboard from the **Styling** panel in the Dashboard Builder. Settings are saved per-dashboard and apply equally to the dashboard in Cube and to its embedded view.

See [Dashboards → Styling](/docs/explore-analyze/dashboards/styling) for the full list of options.

## App customization

When embedding the full Cube app in [Creator Mode](/embedding/iframe/creator-mode), pass an `embedTheme` object to the [Generate Session API](/reference/embed-apis/generate-session) to customize the appearance of the embedded experience.

The `embedTheme` is scoped to the embed session — it is applied while the user is viewing the embedded app and reset on the next session generation.

### Example

```javascript theme={"dark"}
const session = await fetch(
  "https://your-account.cubecloud.dev/api/v1/embed/generate-session",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Api-Key ${API_KEY}`,
    },
    body: JSON.stringify({
      deploymentId: DEPLOYMENT_ID,
      externalId: "user@example.com",
      creatorMode: true,
      tenantId: "tenant-123",
      tenantName: "Acme Corporation",
      embedTheme: {
        analyticsChat: {
          backgroundColor: "#f4f4f5",
          chatInput: {
            backgroundColor: "#ffffff",
            borderColor: "#e4e4e7",
          },
        },
      },
    }),
  },
);
```

### Parameters

The following `embedTheme` parameters are currently supported:

| Parameter                                 | Type     | Description                                   | Example     |
| ----------------------------------------- | -------- | --------------------------------------------- | ----------- |
| `analyticsChat.backgroundColor`           | `string` | Background color of the Analytics Chat panel. | `"#f4f4f5"` |
| `analyticsChat.chatInput.backgroundColor` | `string` | Background color of the chat input field.     | `"#ffffff"` |
| `analyticsChat.chatInput.borderColor`     | `string` | Border color of the chat input field.         | `"#e4e4e7"` |

All values accept standard CSS color formats (hex, `rgb()`, named colors).


# Dashboards
Source: https://docs.cube.dev/embedding/iframe/dashboards

Embed Cube dashboards into your applications via iframe.

<Info>
  Iframe embedding is available on [Premium and Enterprise plans](https://cube.dev/pricing).
</Info>

Embed any [dashboard](/docs/explore-analyze/dashboards) into your application using an iframe. Dashboards can be embedded with either authentication mode:

* **[Private embedding](/embedding/iframe/auth/private)** — for internal users with Cube accounts (e.g., embedding in Notion, Salesforce, internal tools)
* **[Signed embedding](/embedding/iframe/auth/signed)** — for external/customer-facing applications using server-generated sessions

## Embed with private embedding

To embed a dashboard for internal users:

1. Open your dashboard in Cube
2. Click **Share** → **Embed**
3. Copy the generated iframe code

<img alt="Share embed dialog" />

Then paste the iframe code into your application:

```html theme={"dark"}
<iframe
  title="Dashboard"
  src="https://your-account.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID"
  width="100%"
  height="800"
></iframe>
```

Users will be prompted to sign in with their Cube credentials when accessing the embedded dashboard. See [Private embedding](/embedding/iframe/auth/private) for details on the auth model and integration examples (Notion, Salesforce).

## Embed with signed embedding

Signed embedding must be allowed on the dashboard first: open the dashboard,
click **Share** → **Embed**, and turn on **Allow signed embedding**. You can
also toggle it without opening the UI using the [Cube CLI](/reference/cli):

```bash theme={"dark"}
cube embed enable-dashboard YOUR_DASHBOARD_PUBLIC_ID
cube embed disable-dashboard YOUR_DASHBOARD_PUBLIC_ID
```

To embed a dashboard for external/customer-facing applications, generate a session on your backend and pass the session ID into the iframe:

```html theme={"dark"}
<iframe
  title="Dashboard"
  src="https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID?session=YOUR_SESSION_ID"
  width="100%"
  height="800"
></iframe>
```

See [Signed embedding](/embedding/iframe/auth/signed) for the full session generation flow, API key setup, and a complete working example.

## Pre-set dashboard filters and granularities via URL

You can pre-set the values of a dashboard's [controls](/docs/explore-analyze/dashboards/widgets/controls) by adding
URL parameters:

| Control                   | Parameter                                                | Example                                               |
| ------------------------- | -------------------------------------------------------- | ----------------------------------------------------- |
| Filter                    | `f_<semantic_view>.<dimension>=<JSON>`                   | `f_orders_transactions.users_country={"value":"USA"}` |
| Time granularity switcher | `tg_<semantic_view>.<dimension>=<granularity>`           | `tg_orders_transactions.created_at=week`              |
| Field switcher            | `ms_<semantic_view>.<replaced_member>=<selected_member>` | `ms_orders_transactions.status=users_city`            |

The semantic view and member must match the internal names (not display titles)
configured on the widget — as must the member on the right-hand side of `ms_`,
which is a measure rather than a dimension when the field switcher's **Field
Type** is **Measure**. For filters, an omitted filter type defaults to `equals`.
Granularities are lowercase and must be one of the switcher's [allowed
granularities](/docs/explore-analyze/dashboards/widgets/controls#allowed-granularities) —
`day`, `week`, `month`, `quarter`, `year`, plus `second`, `minute`, and `hour`
for time dimensions that expose them.

Example:

```text theme={"dark"}
https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID?session=YOUR_SESSION_ID&f_orders_transactions.users_country={"value":"USA"}&tg_orders_transactions.created_at=week
```

The filter's JSON value is shown unencoded for readability. Percent-encode it
before the URL goes anywhere real — pasted as-is into the `src="…"` of the iframe
snippet above, its raw `"` closes the attribute and truncates the URL.

This works on both regular and published (embedded) dashboards. A parameter is
applied only if a matching control for that member already exists on the
dashboard; a granularity outside the switcher's allowed list is ignored, as is a
member the field switcher doesn't offer — its
[**Alternatives**](/docs/explore-analyze/dashboards/widgets/controls#field-switcher),
plus the member it replaces.

The reverse direction works on published dashboards: when a viewer changes a
control there, the new value is written back into the dashboard's own URL, so the
state a link carries and the state a viewer reaches by clicking are the same
format. Reading the parameters works anywhere; it's the writing that is
published-only. See [Controls → Sharing the current
selection](/docs/explore-analyze/dashboards/widgets/controls#sharing-the-current-selection).

## Allow chart export

By default, embedded dashboards do not expose a download action on individual
widgets. To let viewers download a chart widget as a **CSV**, **PNG**, or
**PDF** file, add the `allowExport=true` query parameter to the embed URL:

```text theme={"dark"}
https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID?session=YOUR_SESSION_ID&allowExport=true
```

When enabled, each chart widget's ⋮ menu shows **Download as CSV**, **Download
as PNG**, and **Download as PDF** actions. `allowExport` is the single switch
for all three formats — there is no way to allow one format while blocking
another. Only the exact literal string `true` opts in: `allowExport=1`,
`allowExport=TRUE`, a bare `?allowExport`, and omitting the parameter (the
default) all leave every download action hidden.

The CSV is generated client-side from the data already loaded into the
widget, so no additional query is issued. Inside an embed, `allowExport` —
not the viewer's own Cube role — is the authority on whether the download
actions appear.

## Show or hide the AI chat

Embedded dashboards show an AI chat (the agent panel and its launcher bubble) by
default. You can control it in two ways:

* **Globally, in the UI.** Toggle **Show dashboard chat** under
  **Embed → Settings** in the Cube Cloud console. This switch is
  account-wide — it turns the AI chat on or off for the entire embedded surface,
  i.e. every embedded dashboard.
* **Per session, via the API.** Pass `settings.showDashboardChat` when you
  [generate the session](/reference/embed-apis/generate-session#session-settings). A per-session
  value takes precedence over the global toggle — `false` hides the chat for that
  session even when it is enabled account-wide, and `true` shows it even when it
  is disabled:

```javascript theme={"dark"}
body: JSON.stringify({
  deploymentId: DEPLOYMENT_ID,
  externalId: "user@example.com",
  settings: {
    // Hide the AI chat for this viewer only
    showDashboardChat: false,
  },
}),
```

This applies to embedded published dashboards; it does not affect the standalone
[Analytics Chat](/embedding/iframe/analytics-chat) surface, where embedding the
chat is itself the opt-in.

## Show or hide header controls

By default, an embedded dashboard's header shows its title, back button, and
— when the viewer has permission — the Edit and Duplicate actions. Hide any
of them individually with URL parameters on the embed iframe `src`:

| Parameter                            | Hides                 |
| ------------------------------------ | --------------------- |
| `showDashboardHeader=false`          | The entire header bar |
| `showDashboardBackButton=false`      | The back button       |
| `showDashboardTitle=false`           | The dashboard title   |
| `showDashboardEditButton=false`      | The Edit action       |
| `showDashboardDuplicateButton=false` | The Duplicate action  |

```text theme={"dark"}
https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID?session=YOUR_SESSION_ID&showDashboardBackButton=false&showDashboardTitle=false
```

Every one of these defaults to shown. Only the exact literal string `false`
hides a control — `=0`, `=False`, `=FALSE`, and a bare `?showDashboardTitle`
(no value) all leave it visible. Note this is the inverse of `allowExport`
above, where only the literal string `true` opts in.

<Note>
  These parameters are URL-only — they aren't accepted in the [Generate
  Session](/reference/embed-apis/generate-session#session-settings) `settings`
  object, unlike `showDashboardChat`, and they have no account-wide default
  under **Embed → Settings**.
</Note>

These parameters apply to the dashboard header only — the workbook header
(which carries Publish and Share) is unaffected.

Setting `showDashboardHeader=false` overrides the other four: the whole bar
disappears regardless of their values. `showDashboardEditButton` can only
hide the Edit action; it can never show one to a viewer who lacks edit
permission.

These parameters are read from the URL the host loaded the iframe with and
stay pinned for the life of the embed, so they survive in-app navigation
(for example, from the home-page dashboard card, or after publishing a
draft).

## Set the language

Embedded dashboards render their UI in the account's default language, which you can
override per embed by adding the `?locale=` query parameter:

```text theme={"dark"}
https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID?session=YOUR_SESSION_ID&locale=es-MX
```

See [Localization](/embedding/iframe/localization) for the list of supported languages
and the other ways to set the language.

## Customize appearance

You can style an embedded dashboard — background, padding, widget borders, titles, and fonts — from the **Styling** panel in the Dashboard Builder. See [Dashboards → Styling](/docs/explore-analyze/dashboards/styling) for the full list of options.


# Events & actions
Source: https://docs.cube.dev/embedding/iframe/events

Listen to user-interaction events from an embedded Cube iframe and send actions back into it, over the browser postMessage API.

<Note>
  Available on [Premium and above plans](https://cube.dev/pricing).
</Note>

Embedded Cube surfaces communicate with your host page over the browser
[`postMessage`](https://developer.mozilla.org/docs/Web/API/Window/postMessage)
API, in both directions:

* **Events** (`cube:event:*`) travel **embed → host**. Subscribe to them to learn
  how a viewer interacts with the embed — when it loads, what they view,
  download, drill into, search for with AI, and any errors they hit. Feed them
  into your own analytics / event bus.
* **Actions** (`cube:action:*`) travel **host → embed**. Send them to drive the
  embed from your app — switch the color scheme, set a filter, navigate, or
  refresh the data.

No SDK is required — it's plain `window.postMessage` and a `message` listener.

## Message envelope

Every message — in either direction — is a single object with the same shape:

```ts theme={"dark"}
{
  source: "cube-embed",              // discriminator — always this string
  direction: "event" | "action",     // "event" = embed→host, "action" = host→embed
  type: string,                      // e.g. "cube:event:download" / "cube:action:set-filter"
  payload: object,                   // shape depends on `type` (see catalogs below)
  timestamp: number,                 // epoch milliseconds
  surface?: "dashboard" | "app" | "chat" // always on events; never on actions
}
```

| Field       | Description                                                                                                                                                           |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`    | Always `"cube-embed"`. Check this first to tell Cube messages apart from other `postMessage` traffic on the page (browser extensions, other libraries, your own app). |
| `direction` | `"event"` for messages emitted by the embed, `"action"` for messages you send into it.                                                                                |
| `type`      | The event or action name (see the catalogs below).                                                                                                                    |
| `payload`   | Event/action-specific data.                                                                                                                                           |
| `timestamp` | When the message was created, in epoch milliseconds.                                                                                                                  |
| `surface`   | Which embedded surface the message relates to. **Always present on events**; never sent on actions — so event listeners never need to handle a missing `surface`.     |

## Listening to events

Attach a single `message` listener to `window`. Always validate `event.origin`
against your tenant's origin and check `data.source === "cube-embed"` before
trusting a message.

```js theme={"dark"}
const CUBE_ORIGIN = "https://your-tenant.cubecloud.dev";

window.addEventListener("message", (event) => {
  // 1. Only trust messages from your Cube tenant.
  if (event.origin !== CUBE_ORIGIN) return;

  const data = event.data;

  // 2. Only handle Cube embed events.
  if (!data || data.source !== "cube-embed" || data.direction !== "event") return;

  // 3. Dispatch on the event type.
  switch (data.type) {
    case "cube:event:ready":
      console.log("Embed ready", data.payload.embedTenant, data.payload.deploymentId);
      break;
    case "cube:event:download":
      myAnalytics.track("embed_download", data.payload);
      break;
    case "cube:event:ai-query":
      myAnalytics.track("embed_ai_query", { query: data.payload.query });
      break;
    case "cube:event:error":
      console.error("Embed error", data.payload.message);
      break;
    default:
      // ready, view, navigate, dashboard-loaded, drilldown, …
      myAnalytics.track(data.type, { surface: data.surface, ...data.payload });
  }
});
```

### Event catalog

| Event                                                         | Fires when                                                   | Surfaces  |
| ------------------------------------------------------------- | ------------------------------------------------------------ | --------- |
| [`cube:event:ready`](#cube-event-ready)                       | The embed has authenticated and mounted (the handshake)      | all       |
| [`cube:event:view`](#cube-event-view)                         | A surface is viewed, on load and on each in-embed navigation | all       |
| [`cube:event:navigate`](#cube-event-navigate)                 | The viewer navigates within the embed                        | all       |
| [`cube:event:dashboard-loaded`](#cube-event-dashboard-loaded) | All widgets on a dashboard have rendered                     | dashboard |
| [`cube:event:download`](#cube-event-download)                 | The viewer exports data or an image                          | dashboard |
| [`cube:event:drilldown`](#cube-event-drilldown)               | The viewer drills into a measure                             | dashboard |
| [`cube:event:ai-query`](#cube-event-ai-query)                 | The viewer runs an AI / natural-language query               | all       |
| [`cube:event:session-expiring`](#cube-event-session-expiring) | A signed session is close to expiring (\~30 min out)         | all       |
| [`cube:event:session-expired`](#cube-event-session-expired)   | A signed session has expired                                 | all       |
| [`cube:event:error`](#cube-event-error)                       | The embed surfaces an error                                  | all       |

<Note>
  Every event payload is also delivered with the envelope's `surface` field, so
  you can always tell which surface (`dashboard`, `app`, or `chat`) it came from
  — including AI queries, which report `app` when run inside the embedded app and
  `chat` on the standalone chat surface.
</Note>

#### `cube:event:ready`

Emitted once per session, as soon as the embed authenticates and mounts. The
handshake — the first event you receive, and the moment to record an
"embed opened".

| Field          | Type                             | Description                                           |
| -------------- | -------------------------------- | ----------------------------------------------------- |
| `embedTenant`  | `string \| null`                 | The embed tenant the iframe resolved to, when known.  |
| `deploymentId` | `number \| null`                 | The deployment the embed is bound to, when known.     |
| `mode`         | `"signed" \| "private"`          | How the viewer was authenticated.                     |
| `surface`      | `"dashboard" \| "app" \| "chat"` | The surface that mounted.                             |
| `publicId`     | `string` *(optional)*            | The dashboard's public id, for the dashboard surface. |

```json theme={"dark"}
{
  "embedTenant": "acme",
  "deploymentId": 42,
  "mode": "signed",
  "surface": "dashboard",
  "publicId": "a1b2c3d4"
}
```

#### `cube:event:view`

Emitted when a surface is viewed — on the initial load and again whenever the
viewer navigates within the embed.

| Field      | Type                             | Description                                          |
| ---------- | -------------------------------- | ---------------------------------------------------- |
| `surface`  | `"dashboard" \| "app" \| "chat"` | The surface viewed.                                  |
| `path`     | `string`                         | The in-embed route path that was viewed.             |
| `publicId` | `string` *(optional)*            | The dashboard's public id, when applicable.          |
| `title`    | `string` *(optional)*            | Human-readable title of the surface, when available. |

```json theme={"dark"}
{
  "surface": "app",
  "path": "/embed/d/42/app/workbook/130"
}
```

#### `cube:event:navigate`

Emitted when the viewer navigates within the embed (a route change). Use it to
mirror the embed's location in your own router or analytics.

| Field          | Type                  | Description                   |
| -------------- | --------------------- | ----------------------------- |
| `path`         | `string`              | The new path.                 |
| `previousPath` | `string` *(optional)* | The path navigated away from. |

```json theme={"dark"}
{
  "path": "/embed/d/42/app/workbook/130",
  "previousPath": "/embed/d/42/app"
}
```

#### `cube:event:dashboard-loaded`

Emitted when a dashboard has finished rendering all of its widgets — the "fully
painted" signal (distinct from `ready`, which fires at mount, before data loads).

| Field            | Type                  | Description                                                     |
| ---------------- | --------------------- | --------------------------------------------------------------- |
| `publicId`       | `string` *(optional)* | The dashboard's public id.                                      |
| `widgetCount`    | `number` *(optional)* | Number of widgets on the dashboard.                             |
| `loadDurationMs` | `number` *(optional)* | Milliseconds from mount to all widgets loaded, when measurable. |

```json theme={"dark"}
{
  "publicId": "a1b2c3d4",
  "widgetCount": 6
}
```

#### `cube:event:download`

Emitted when a viewer exports something — a widget's data as CSV, or a widget
as a PNG or PDF image. Reports *that* an export happened and its shape — never
the exported rows themselves.

| Field      | Type                                | Description                                                  |
| ---------- | ----------------------------------- | ------------------------------------------------------------ |
| `format`   | `"csv" \| "xlsx" \| "png" \| "pdf"` | The file format produced.                                    |
| `target`   | `"widget" \| "dashboard"`           | Whether a single widget or the whole dashboard was exported. |
| `widgetId` | `string` *(optional)*               | Id of the source widget, when `target` is `"widget"`.        |
| `title`    | `string` *(optional)*               | Title of the exported widget / dashboard.                    |
| `rowCount` | `number` *(optional)*               | Rows exported, for data exports (`csv` / `xlsx`).            |

```json theme={"dark"}
{
  "format": "csv",
  "target": "widget",
  "widgetId": "37",
  "title": "Revenue by month",
  "rowCount": 128
}
```

<Note>
  A dashboard widget's download actions (CSV, PNG, PDF) only appear when the
  embed URL includes `allowExport=true` (see [Dashboards → Allow chart
  export](/embedding/iframe/dashboards#allow-csv-export)). The event fires when a
  viewer uses one of them.
</Note>

#### `cube:event:drilldown`

Emitted when a viewer drills into a measure (clicks a chart mark or table cell to
see its detail rows).

| Field      | Type                   | Description                                        |
| ---------- | ---------------------- | -------------------------------------------------- |
| `member`   | `string`               | The fully-qualified measure that was drilled into. |
| `value`    | `unknown` *(optional)* | The clicked value, when the click carried one.     |
| `widgetId` | `string` *(optional)*  | Id of the originating widget.                      |

```json theme={"dark"}
{
  "member": "orders.count",
  "value": "completed",
  "widgetId": "37"
}
```

#### `cube:event:ai-query`

Emitted around an AI / natural-language query — capturing *what* the viewer asked
and the lifecycle stage. Fires wherever AI chat is used: the standalone chat
surface, the dashboard agent, and the embedded app.

| Field     | Type                                    | Description                                      |
| --------- | --------------------------------------- | ------------------------------------------------ |
| `query`   | `string`                                | The natural-language query the viewer submitted. |
| `status`  | `"submitted" \| "completed" \| "error"` | Lifecycle stage of the query.                    |
| `chatId`  | `string` *(optional)*                   | The chat/session id, when applicable.            |
| `agentId` | `string` *(optional)*                   | The agent that answered, when applicable.        |

```json theme={"dark"}
{
  "query": "top 10 customers by revenue this quarter",
  "status": "submitted",
  "agentId": "1"
}
```

#### `cube:event:session-expiring`

Emitted once per [signed embedding](/embedding/iframe/auth/signed) session, \~30
minutes before it stops working. This is the moment to mint a replacement
session and push it in with `cube:action:set-session` — see [Keeping a signed
session alive](#keeping-a-signed-session-alive) below.

| Field         | Type     | Description                                                                                                                                                              |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `expiresAt`   | `number` | Epoch ms when the session actually stops working — earlier than the token's nominal 24-hour expiry, see [Session lifecycle](/embedding/iframe/auth/signed#how-it-works). |
| `expiresInMs` | `number` | Milliseconds from this event to `expiresAt`. `0` if already past it.                                                                                                     |

```json theme={"dark"}
{
  "expiresAt": 1735689600000,
  "expiresInMs": 1800000
}
```

<Note>
  Only fires for signed embedding sessions — a private-embedding iframe has no
  expiring session to renew. It's a best-effort timer inside the iframe: a
  hidden or suspended tab can throttle it, so it may arrive late (immediately
  on wake) or after `cube:event:session-expired`.
</Note>

#### `cube:event:session-expired`

Emitted when a signed session has actually lapsed. The embed can't recover on
its own — there's no refresh token or re-exchange endpoint — so nothing happens
until you push a fresh session in with `cube:action:set-session`.

| Field       | Type     | Description                                            |
| ----------- | -------- | ------------------------------------------------------ |
| `expiredAt` | `number` | Epoch ms when the session was observed to have lapsed. |

```json theme={"dark"}
{
  "expiredAt": 1735689600000
}
```

#### `cube:event:error`

Emitted when the embed surfaces an error (a render error, a query failure, an
auth/session problem). `fatal` distinguishes an error that took the whole surface
down from a recoverable one.

| Field     | Type                   | Description                                                      |
| --------- | ---------------------- | ---------------------------------------------------------------- |
| `message` | `string`               | Human-readable message.                                          |
| `name`    | `string` *(optional)*  | Error name/class, e.g. `"TypeError"`.                            |
| `context` | `string` *(optional)*  | Where it originated, e.g. `"embed-render"`, `"session-renewal"`. |
| `fatal`   | `boolean` *(optional)* | `true` when the error took down the whole surface.               |

```json theme={"dark"}
{
  "message": "Failed to load data",
  "context": "embed-render",
  "fatal": true
}
```

## Sending actions

Send actions into the embed by posting a message to the iframe's
`contentWindow`. Always target your tenant's origin (not `"*"`) so the message
can't leak to another document if the iframe navigates away.

```js theme={"dark"}
const iframe = document.querySelector("iframe#cube");
const CUBE_ORIGIN = "https://your-tenant.cubecloud.dev";

function sendAction(type, payload = {}) {
  iframe.contentWindow.postMessage(
    {
      source: "cube-embed",
      direction: "action",
      type,
      payload,
      timestamp: Date.now(),
    },
    CUBE_ORIGIN
  );
}

// Examples
sendAction("cube:action:set-color-scheme", { scheme: "dark" });
sendAction("cube:action:set-filter", {
  filterUrlParameter: 'f_orders.status={"value":"completed"}',
});
sendAction("cube:action:refresh");
```

### Action catalog

| Action                                                          | Effect                                                      | Payload                  |
| --------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------ |
| [`cube:action:set-color-scheme`](#cube-action-set-color-scheme) | Switch light / dark / auto                                  | `{ scheme }`             |
| [`cube:action:set-theme`](#cube-action-set-theme)               | Apply a brand theme (colors, fonts)                         | `embedTheme` object      |
| [`cube:action:set-locale`](#cube-action-set-locale)             | Switch the UI language                                      | `{ locale }`             |
| [`cube:action:set-timezone`](#cube-action-set-timezone)         | Switch the query time zone                                  | `{ timezone }`           |
| [`cube:action:set-filter`](#cube-action-set-filter)             | Push a filter into a dashboard                              | `{ filterUrlParameter }` |
| [`cube:action:navigate`](#cube-action-navigate)                 | Navigate the embed to a path                                | `{ path }`               |
| [`cube:action:refresh`](#cube-action-refresh)                   | Re-run the embed's queries                                  | *none*                   |
| [`cube:action:set-session`](#cube-action-set-session)           | Swap in a fresh signed session, in place (no iframe reload) | `{ sessionId }`          |

#### `cube:action:set-color-scheme`

Switch the embed's color scheme at runtime.

| Field    | Type                          | Description                                  |
| -------- | ----------------------------- | -------------------------------------------- |
| `scheme` | `"light" \| "dark" \| "auto"` | `"auto"` follows the viewer's OS preference. |

```js theme={"dark"}
sendAction("cube:action:set-color-scheme", { scheme: "dark" });
```

#### `cube:action:set-theme`

Apply a brand theme (colors, fonts) to the embed at runtime. The payload is an
`embedTheme` object — the same shape the [Generate Session API](/reference/embed-apis/generate-session)
accepts. Common fields are `primaryColor`, `borderRadius`, and `font`; see
[App customization](/embedding/iframe/customization#app-customization) for the
full list.

```js theme={"dark"}
sendAction("cube:action:set-theme", {
  primaryColor: "#7c5cff",
  borderRadius: 8,
});
```

#### `cube:action:set-locale`

Switch the embed's UI language. Accepts a full code (`es-ES`), a short code
(`es`), or a regional variant. See [Localization](/embedding/iframe/localization)
for the list of supported languages and the other ways to set the language.

| Field    | Type     | Description              |
| -------- | -------- | ------------------------ |
| `locale` | `string` | The locale to switch to. |

```js theme={"dark"}
sendAction("cube:action:set-locale", { locale: "es" });
```

#### `cube:action:set-timezone`

Switch the time zone the embed's queries run in — which day a row falls into, and what
`today` means. Takes precedence over the `?timezone=` URL parameter and the account
default. See [Time zones](/embedding/iframe/time-zones) for the other ways to set it.

| Field      | Type     | Description                                                                                                          |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `timezone` | `string` | An [IANA time zone name](/admin/time-zones#valid-time-zone-values), e.g. `Asia/Tokyo`. Bare UTC offsets are ignored. |

```js theme={"dark"}
sendAction("cube:action:set-timezone", { timezone: "Asia/Tokyo" });
```

#### `cube:action:set-filter`

Push a filter into a dashboard. The `filterUrlParameter` is the same
`f_<semantic_view>.<dimension>=<JSON>` form used to
[pre-set filters via URL](/embedding/iframe/dashboards#pre-set-dashboard-filters-via-url),
so you can capture a viewer's filters and restore them later.

| Field                | Type     | Description                                                                |
| -------------------- | -------- | -------------------------------------------------------------------------- |
| `filterUrlParameter` | `string` | Filter(s) in URL-query form, e.g. `f_orders.status={"value":"completed"}`. |

```js theme={"dark"}
sendAction("cube:action:set-filter", {
  filterUrlParameter: 'f_orders.status={"value":"completed"}',
});
```

#### `cube:action:navigate`

Navigate the embed to an in-embed path.

| Field  | Type     | Description                       |
| ------ | -------- | --------------------------------- |
| `path` | `string` | The in-embed path to navigate to. |

```js theme={"dark"}
sendAction("cube:action:navigate", { path: "/embed/d/42/app/workbook/130" });
```

#### `cube:action:refresh`

Re-run the embed's queries and refresh its data. No payload.

```js theme={"dark"}
sendAction("cube:action:refresh");
```

#### `cube:action:set-session`

Hand the embed a fresh [signed embedding](/embedding/iframe/auth/signed)
session id, replacing the one it's running on **without reloading the
iframe**. Sent before the current session lapses, the swap is invisible —
nothing unmounts, so the viewer keeps their place, filters, and any unsaved
editing state. Sent after it has already lapsed, it still recovers the embed
without a reload, but the surface has been torn down by then and transient
state is gone.

| Field       | Type     | Description                                                                                                                                                                                           |
| ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sessionId` | `string` | A single-use session id from the [Generate Session API](/reference/embed-apis/generate-session). Expires 5 minutes after it's minted, so mint it at the moment you send it rather than ahead of time. |

```js theme={"dark"}
sendAction("cube:action:set-session", { sessionId: newSessionId });
```

A rejected id (unknown, already redeemed, or expired) doesn't tear down a
working embed. It's reported via `cube:event:error` with `context:
"session-renewal"` and `name: "EmbedSessionExchangeError"`, so you can filter
for it and retry.

## Keeping a signed session alive

A signed embed's token is usable for about 23 hours (see [Session
lifecycle](/embedding/iframe/auth/signed#how-it-works)) and can't refresh
itself — left alone, a tab open that long drops to a "Session expired"
message. Renew it in place instead.

If you're using `@cube-dev/embed-sdk`, call `autoRenewSession` on the
connection instead of hand-rolling the listener below — it drives renewal
from all three triggers (both events plus the tab returning to the
foreground, which catches a renewal that timers missed while the tab was
hidden), and collapses concurrent triggers into one in-flight renewal:

```js theme={"dark"}
import { connectCubeEmbed } from "@cube-dev/embed-sdk";

const cube = connectCubeEmbed(iframe);

cube.autoRenewSession({
  // must resolve to the new session id
  mintSession: () =>
    fetch("/api/cube-embed-session", { method: "POST" })
      .then((r) => r.json())
      .then(({ sessionId }) => sessionId),
});
```

`mintSession` is your own backend endpoint, calling [Generate
Session](/reference/embed-apis/generate-session) — an API key that must never
reach the browser. Each id is single-use and expires 5 minutes after minting,
so mint a fresh one on every call rather than caching one ahead of time.

Without the SDK, drive the same renewal by hand from the raw events and action:

```js theme={"dark"}
let renewing = false;

window.addEventListener("message", (event) => {
  if (event.origin !== CUBE_ORIGIN) return;
  const data = event.data;
  if (!data || data.source !== "cube-embed" || data.direction !== "event") return;

  if (data.type === "cube:event:session-expiring" || data.type === "cube:event:session-expired") {
    // Both events can fire for one session — renew only once.
    if (renewing) return;
    renewing = true;

    fetch("/api/cube-embed-session", { method: "POST" }) // your backend, calling Generate Session
      .then((r) => r.json())
      .then(({ sessionId }) => sendAction("cube:action:set-session", { sessionId }))
      .catch((error) => console.error("Session renewal failed", error))
      .finally(() => {
        renewing = false;
      });
  }
});
```

## Surfaces

Events come from one of three customer-facing surfaces, reported in the envelope's
`surface` field:

* `dashboard` — a [published dashboard](/embedding/iframe/dashboards).
* `app` — the [Creator-mode app](/embedding/iframe/creator-mode) (workbooks,
  folders, in-app dashboards). AI chat run *inside* the app reports `app`.
* `chat` — the standalone [analytics chat](/embedding/iframe/analytics-chat).

## Security

* **Always validate `event.origin`** against your tenant's origin in your
  `message` listener, and check `data.source === "cube-embed"`. Never act on a
  message that fails either check.
* **Target your tenant's origin when sending actions** (`iframe.contentWindow.postMessage(msg, CUBE_ORIGIN)`),
  not `"*"`, so an action can't be delivered to an unexpected document.

## Complete example

A minimal host page that loads a signed dashboard embed, logs every event, and
exposes buttons to drive it. Generate the `session` on your backend with the
[Generate Session API](/reference/embed-apis/generate-session) — see
[Signed embedding](/embedding/iframe/auth/signed) for the full flow.

```html theme={"dark"}
<!doctype html>
<html>
  <body>
    <button id="dark">Dark mode</button>
    <button id="refresh">Refresh</button>

    <iframe
      id="cube"
      title="Dashboard"
      src="https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID?session=YOUR_SESSION_ID"
      width="100%"
      height="800"
    ></iframe>

    <script>
      const CUBE_ORIGIN = "https://your-tenant.cubecloud.dev";
      const iframe = document.getElementById("cube");

      // Receive events (embed → host)
      window.addEventListener("message", (event) => {
        if (event.origin !== CUBE_ORIGIN) return;
        const data = event.data;
        if (!data || data.source !== "cube-embed" || data.direction !== "event") return;

        console.log(`[${data.surface}] ${data.type}`, data.payload);
        // → forward to your own analytics / event bus here
      });

      // Send actions (host → embed)
      function sendAction(type, payload = {}) {
        iframe.contentWindow.postMessage(
          { source: "cube-embed", direction: "action", type, payload, timestamp: Date.now() },
          CUBE_ORIGIN
        );
      }

      document.getElementById("dark").onclick = () =>
        sendAction("cube:action:set-color-scheme", { scheme: "dark" });
      document.getElementById("refresh").onclick = () =>
        sendAction("cube:action:refresh");
    </script>
  </body>
</html>
```


# Localization
Source: https://docs.cube.dev/embedding/iframe/localization

Set the language for embedded Cube surfaces — account-wide, per embed via URL, or at runtime.

Embedded Cube surfaces — dashboards, [Analytics Chat](/embedding/iframe/analytics-chat),
and the full app in [Creator Mode](/embedding/iframe/creator-mode) — can render their
UI in any of the supported languages. You can set a default language for the whole
account, override it per embed with a URL parameter, or switch it at runtime from the
host page.

<Note>
  Available on [Premium and Enterprise plans](https://cube.dev/pricing).
</Note>

<Info>
  This page covers **embedded** surfaces. To set the language of the main Cube
  interface for your own account, see [Preferences](/docs/preferences#language).
</Info>

## Supported languages

| Language                | Locale code |
| ----------------------- | ----------- |
| English (US)            | `en-US`     |
| Deutsch (Deutschland)   | `de-DE`     |
| Español (España)        | `es-ES`     |
| Español (Latinoamérica) | `es-MX`     |
| Français (France)       | `fr-FR`     |
| Italiano (Italia)       | `it-IT`     |
| 日本語 (日本)                | `ja-JP`     |
| Norsk bokmål (Norge)    | `nb-NO`     |
| Português (Brasil)      | `pt-BR`     |
| Português (Portugal)    | `pt-PT`     |
| Svenska (Sverige)       | `sv-SE`     |
| Tiếng Việt (Việt Nam)   | `vi-VN`     |

English (`en-US`) is the default and the fallback when no language is configured.

A locale value can be a full code (`es-ES`), a short language code (`es`), or a regional
variant that isn't shipped (`es-AR`). Short codes and unsupported regional variants
resolve to the first supported locale for that language — for example, both `es` and
`es-AR` resolve to `es-ES`. A value that doesn't match any supported language is ignored.

## How the language is resolved

The language of an embedded surface is resolved from the following sources, highest
priority first:

1. **Runtime override** — a [`cube:action:set-locale`](/embedding/iframe/events#cube-action-set-locale)
   message sent from the host page (see [At runtime](#at-runtime)).
2. **URL parameter** — the `?locale=` query parameter on the embed URL (see
   [Per embed via URL](#per-embed-via-url)).
3. **Account default** — the language configured in **Embed → Settings** (see
   [Account-wide default](#account-wide-default)).
4. **Fallback** — `en-US`.

## Account-wide default

Set a default language for all embedded surfaces from the Cube interface:

1. Go to **Embed → Settings**.
2. In the **Language** card, pick a language from the dropdown.

The selected language applies to every embedded surface across the account, unless a
specific embed overrides it with a `?locale=` URL parameter or a runtime
`cube:action:set-locale` message.

Clearing the setting removes the stored default, and embeds fall back to `en-US` (or to
whatever a per-embed override specifies).

## Per embed via URL

Override the account default for an individual embed by adding the `?locale=` query
parameter to the embed URL:

```text theme={"dark"}
https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID?session=YOUR_SESSION_ID&locale=es-MX
```

The parameter is read once when the embed loads and pinned for the session, so in-app
navigation won't drop it.

## At runtime

Switch the language after the embed has loaded by sending a
[`cube:action:set-locale`](/embedding/iframe/events#cube-action-set-locale) message from
the host page. This takes precedence over both the URL parameter and the account default:

```js theme={"dark"}
sendAction("cube:action:set-locale", { locale: "es" });
```

See [Events and actions](/embedding/iframe/events) for the full host ↔ embed messaging
contract.


# Time zones
Source: https://docs.cube.dev/embedding/iframe/time-zones

Set the time zone for embedded Cube surfaces — account-wide, per embed via URL, or at runtime.

Embedded Cube surfaces — dashboards, [Analytics Chat](/embedding/iframe/analytics-chat),
and the full app in [Creator Mode](/embedding/iframe/creator-mode) — bucket time in a
zone you control. You can set a default for the whole account, override it per embed with
a URL parameter, or switch it at runtime from the host page.

This matters most when your end users are not in your deployment's zone: without it,
"today" in an embedded dashboard means today in the deployment's
[default time zone](/docs/data-modeling/configuration#default-time-zone), not in your
customer's.

<Note>
  Available on [Premium and above plans](https://cube.dev/pricing).
</Note>

<Info>
  Embedded time zones require **user time zones** to be enabled for the account. See
  [Time zones](/admin/time-zones) for the account-wide policy, what a zone changes, and
  the console-side behavior.
</Info>

## How the zone is resolved

The time zone of an embedded surface is resolved from the following sources, highest
priority first:

1. **Runtime override** — a [`cube:action:set-timezone`](/embedding/iframe/events#cube-action-set-timezone)
   message sent from the host page (see [At runtime](#at-runtime)).
2. **URL parameter** — the `?timezone=` query parameter on the embed URL (see
   [Per embed via URL](#per-embed-via-url)).
3. **Dashboard's own zone** — a dashboard pinned to a named zone, or set to resolve per
   viewer (see [dashboard time zone](/admin/time-zones#dashboard-time-zone)). In
   [signed embedding](/embedding/iframe/auth/signed) the viewer has no Cube account and
   therefore no personal zone, so a viewer-resolved dashboard falls through to the next
   step — supply `?timezone=` if you want each end user's own zone.
4. **Account default** — the zone configured in **Embed → Settings** (see
   [Account-wide default](#account-wide-default)).
5. **Account-wide zone**, then the deployment's default time zone.

A host override outranks a dashboard's pinned zone by design: the integrator is speaking
for the whole frame, and you know your user's zone better than the dashboard's author
does.

<Note>
  If the account policy is disabled, none of this applies — Cube sends no zone and the
  deployment's default time zone is used, exactly as before.
</Note>

## Account-wide default

Set a default time zone for all embedded surfaces:

1. Go to **Embed → Settings**.
2. In the **Time Zone** card, pick a zone from the dropdown.

The selected zone applies to every embedded surface across the account, unless a specific
embed overrides it. Re-selecting the account-wide zone clears the embed-specific value, so
embeds follow the account-wide zone again.

The picker is inert while user time zones are off for the account — a zone stored there
would be one nothing applies.

## Per embed via URL

Override the account default for an individual embed by adding the `?timezone=` query
parameter to the embed URL:

```text theme={"dark"}
https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID?session=YOUR_SESSION_ID&timezone=America/New_York
```

The parameter is read once when the embed loads and pinned for the session, so in-app
navigation won't drop it.

Values must be [IANA time zone names](/admin/time-zones#valid-time-zone-values). An
unusable value — including a bare UTC offset like `+05:30` — is ignored, and the embed
falls back to the account default rather than quietly shifting every number.

## At runtime

Switch the zone after the embed has loaded by sending a
[`cube:action:set-timezone`](/embedding/iframe/events#cube-action-set-timezone) message
from the host page. This takes precedence over both the URL parameter and the account
default — use it when your own user changes their zone:

```js theme={"dark"}
sendAction("cube:action:set-timezone", { timezone: "Asia/Tokyo" });
```

See [Events and actions](/embedding/iframe/events) for the full host ↔ embed messaging
contract.


# Overview
Source: https://docs.cube.dev/embedding/index

Embed AI-powered analytics into your applications using iframes, the React Embed SDK, or a headless approach.

Cube provides multiple approaches for embedding AI-powered analytics into your applications — from iframe embeds to fully custom embedded analytics experiences built on Cube's APIs.

## Iframe embedding

<Note>
  Available on [Premium and Enterprise plans](https://cube.dev/pricing).
</Note>

Embed Cube content using iframes for the fastest integration with minimal code. This approach works with any frontend framework and requires no additional dependencies.

Iframe embedding supports [dashboards](/embedding/iframe/dashboards), [Analytics Chat](/embedding/iframe/analytics-chat), and the full Cube application in [Creator Mode](/embedding/iframe/creator-mode).

**Authentication options:**

* **[Private embedding](/embedding/iframe/auth/private)** – For internal use cases where users authenticate with their Cube accounts
* **[Signed embedding](/embedding/iframe/auth/signed)** – For customer-facing applications using secure, server-generated sessions for authentication

## SDK embedding

<Note>
  Available on [Premium and Enterprise plans](https://cube.dev/pricing).
</Note>

Embed Cube using the [React Embed SDK](/embedding/react-embed-sdk) for tighter integration with your React applications. Components provide more control over styling, theming, and user interactions.

## Headless embedding

Build fully custom embedded analytics experiences using Cube APIs directly. This headless approach gives you complete control over data fetching, visualization, and user interface.

### Chat API

Use the [Chat API](/reference/embed-apis/chat-api) to build custom conversational analytics experiences. Let your users ask questions in plain language and get trusted answers powered by your semantic layer — without building your own AI infrastructure.

### Core Data APIs

Use the [Core Data APIs](/reference/core-data-apis) to build fully custom visualization, reporting, and dashboarding experiences.


# Multitenancy
Source: https://docs.cube.dev/embedding/multitenancy

Reference for tenant-aware Cube configuration—per-tenant drivers, schemas, repositories, refresh, and query rewrite driven by security context.

Cube supports multitenancy out of the box, both on database and data model
levels. Multiple drivers are also supported, meaning that you can have one
customer’s data in MongoDB and others in Postgres with one Cube instance.

There are several [configuration options][ref-config-opts] you can leverage for
your multitenancy setup. You can use all of them or just a couple, depending on
your specific case. The options are:

* `context_to_app_id`
* `schema_version`
* `repository_factory`
* `driver_factory`
* `context_to_orchestrator_id`
* `pre_aggregations_schema`
* `query_rewrite`
* `scheduled_refresh_contexts`
* `scheduled_refresh_time_zones`

All of the above options are functions, which you provide in the
[configuration file][ref-config]. The functions accept one argument:
a context object, which has a [`securityContext`][ref-config-security-ctx]
property where you can provide all the necessary data to identify a user e.g.,
organization, app, etc. By default, the
[`securityContext`][ref-config-security-ctx] is defined by [Cube API
Token][ref-security].

There are several multitenancy setup scenarios that can be achieved by using
combinations of these configuration options.

<Note>
  See the following recipes:

  * If you'd like to provide a [custom data source][ref-per-tenant-data-source-recipe] for each tenant.
  * If you'd like to provide a [custom data model][ref-per-tenant-data-model-recipe] for each tenant.
</Note>

## Multitenancy vs Multiple Data Sources

In cases where your Cube data model is spread across multiple different data
sources, consider using the [`data_source` cube property][ref-cube-datasource]
instead of multitenancy. Multitenancy is designed for cases where you need to
serve different datasets for multiple users, or tenants which aren't related to
each other.

On the other hand, multitenancy can be used for scenarios where users need to
access the same data but from different databases. The multitenancy and multiple
data sources features aren't mutually exclusive and can be used together.

<Warning>
  A `default` data source **must** exist and be configured. It is used to resolve
  target query data source for now. This behavior **will** be changed in future
  releases.
</Warning>

A simple configuration with two data sources might look like:

**cube.js:**

```javascript theme={"dark"}
module.exports = {
  driverFactory: ({ dataSource } = {}) => {
    if (dataSource === "db1") {
      return {
        type: "postgres",
        database: process.env.DB1_NAME,
        host: process.env.DB1_HOST,
        user: process.env.DB1_USER,
        password: process.env.DB1_PASS,
        port: process.env.DB1_PORT
      }
    } else {
      return {
        type: "postgres",
        database: process.env.DB2_NAME,
        host: process.env.DB2_HOST,
        user: process.env.DB2_USER,
        password: process.env.DB2_PASS,
        port: process.env.DB2_PORT
      }
    }
  }
}
```

A more advanced example that uses multiple [data sources][ref-config-db] could
look like:

**cube.js:**

```javascript theme={"dark"}
module.exports = {
  driverFactory: ({ dataSource } = {}) => {
    if (dataSource === "web") {
      return {
        type: "athena",
        database: dataSource,

        // ...
      }
    } else if (dataSource === "googleAnalytics") {
      return {
        type: "bigquery",

        // ...
      }
    } else if (dataSource === "financials") {
      return {
        type: "postgres",
        database: "financials",
        host: "financials-db.acme.com",
        user: process.env.FINANCIALS_DB_USER,
        password: process.env.FINANCIALS_DB_PASS
      }
    } else {
      return {
        type: "postgres",

        // ...
      }
    }
  }
}
```

More information can be found on the [Multiple Data Sources
page][ref-config-multi-data-src].

### queryRewrite vs Multitenant Compile Context

As a rule of thumb, the [`queryRewrite`][ref-config-query-rewrite] should be
used in scenarios when you want to define row-level security within the same
database for different users of such database. For example, to separate access
of two e-commerce administrators who work on different product categories within
the same e-commerce store, you could configure your project as follows.

Use the following `cube.js` configuration file:

```javascript theme={"dark"}
module.exports = {
  queryRewrite: (query, { securityContext }) => {
    if (securityContext.categoryId) {
      query.filters.push({
        member: "products.category_id",
        operator: "equals",
        values: [securityContext.categoryId]
      })
    }
    return query
  }
}
```

Also, you can use a data model like this:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products
      sql_table: products
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`products`, {
    sql_table: `products`
  })
  ```
</CodeGroup>

On the other hand, multi-tenant [`COMPILE_CONTEXT`][ref-cube-security-ctx]
should be used when users need access to different databases. For example, if
you provide SaaS ecommerce hosting and each of your customers have a separate
database, then each e-commerce store should be modeled as a separate tenant.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products
      sql_table: "{COMPILE_CONTEXT.security_context.userId}.products"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`products`, {
    sql_table: `${COMPILE_CONTEXT.security_context.userId}.products`
  })
  ```
</CodeGroup>

### Running in Production

Each unique id generated by `contextToAppId` will generate a dedicated data model
compile cache and SQL compile cache, and each unique id generated by
`contextToOrchestratorId` will generate a dedicated query orchestrator with its
own database connections, query queues, and in-memory result cache. Depending on your
data model complexity and usage patterns, those resources can have a pretty
sizable memory footprint ranging from single-digit MBs on the lower end and
dozens of MBs on the higher end. So you should make sure Node VM has enough
memory reserved for that.

There're multiple strategies in terms of memory resource utilization here. The
first one is to bucket your actual tenants into variable-size buckets with
assigned `contextToAppId` or `contextToOrchestratorId` by some bucketing rule.
For example, you can bucket your biggest tenants in separate buckets and all the
smaller ones into a single bucket. This way, you'll end up with a very small
count of buckets that will easily fit a single node.

Another strategy is to split all your tenants between different Cube nodes and
route traffic between them so that each Cube API node serves only its own set of
tenants and never serves traffic for another node. In that case, memory usage is
limited by the number of tenants served by each node. Cube Cloud utilizes
precisely this approach for scaling. Please note that in this case, you should
also split refresh workers and assign appropriate `scheduledRefreshContexts` to
them.

## Same DB Instance with per Tenant Row Level Security

Per tenant row-level security can be achieved by configuring
[`queryRewrite`][ref-config-query-rewrite], which adds a tenant identifier
filter to the original query. It uses the
[`securityContext`][ref-config-security-ctx] to determine which tenant is
requesting data. This way, every tenant starts to see their own data. However,
resources such as query queue and pre-aggregations are shared between all
tenants.

**cube.js:**

```javascript theme={"dark"}
module.exports = {
  queryRewrite: (query, { securityContext }) => {
    const user = securityContext
    if (user.id) {
      query.filters.push({
        member: "users.id",
        operator: "equals",
        values: [user.id]
      })
    }
    return query
  }
}
```

## Same DB Instance with per Tenant Data Model

If [`context_to_app_id`][ref-config-ctx-to-appid] is the only option you define,
Cube compiles and caches a separate data model for each app id it returns. This
is what enables [`COMPILE_CONTEXT`][ref-cube-security-ctx] and per-tenant
[`repository_factory`][ref-config-repofactory], so each tenant can get a
different data model built from the same or different data model files.

**cube.js:**

```javascript theme={"dark"}
module.exports = {
  contextToAppId: ({ securityContext }) =>
    `CUBE_APP_${securityContext.tenantId}`
}
```

<Warning>
  `context_to_app_id` scopes multitenancy to data model compilation only.
  Everything below the data model remains shared across all tenants: database
  connections, query queues, the in-memory query results cache, and
  pre-aggregations, including their tables in the pre-aggregations schema. So
  tenants whose data models generate the same SQL will share queue entries, cached
  results, and pre-aggregation tables.

  To isolate those resources per tenant as well, add
  [`pre_aggregations_schema`][ref-config-preagg-schema] for per-tenant
  pre-aggregation tables and [`context_to_orchestrator_id`][ref-config-ctx-to-orch-id]
  for per-tenant connections, queues, and results cache, as shown in the sections
  below.
</Warning>

## Multiple DB Instances with Same Data Model

Let's consider an example where we store data for different users in different
databases, but on the same Postgres host. The database name format is
`my_app_<APP_ID>_<USER_ID>`, so `my_app_1_2` is a valid database name.

To make it work with Cube, first we need to pass the `appId` and `userId` as
context to every query. We should first ensure our JWTs contain those properties
so we can access them through the [security context][ref-config-security-ctx].

```javascript theme={"dark"}
const jwt = require("jsonwebtoken")
const CUBE_API_SECRET = "secret"

const cubeToken = jwt.sign({ appId: "1", userId: "2" }, CUBE_API_SECRET, {
  expiresIn: "30d"
})
```

Now, we can access them through the [`securityContext`][ref-config-security-ctx]
property inside the context object. Let's use
[`contextToAppId`][ref-config-ctx-to-appid] and
[`contextToOrchestratorId`][ref-config-ctx-to-orch-id] to create a dynamic Cube
App ID and Orchestrator ID for every combination of `appId` and `userId`, as
well as defining [`driverFactory`][ref-config-driverfactory] to dynamically
select the database, based on the `appId` and `userId`:

<Warning>
  The App ID (the result of [`contextToAppId`][ref-config-ctx-to-appid]) is used
  as a caching key for the compiled data model and other data model-related
  in-memory structures. The Orchestrator ID (the result of
  [`contextToOrchestratorId`][ref-config-ctx-to-orch-id]) is used as a caching key
  for the query orchestrator, which holds database connections and their pools,
  execution queues, query results cache, and pre-aggregation table caches. Not
  declaring these properties will result in unexpected caching issues such as the
  data model or data of one tenant being used for another.
</Warning>

**cube.js:**

```javascript theme={"dark"}
module.exports = {
  contextToAppId: ({ securityContext }) =>
    `CUBE_APP_${securityContext.appId}_${securityContext.userId}`,
  contextToOrchestratorId: ({ securityContext }) =>
    `CUBE_APP_${securityContext.appId}_${securityContext.userId}`,
  driverFactory: ({ securityContext }) => ({
    type: "postgres",
    database: `my_app_${securityContext.appId}_${securityContext.userId}`
  })
}
```

## Same DB Instance with per Tenant Pre-Aggregations

To support per-tenant pre-aggregation of data within the same database instance,
you should configure the [`preAggregationsSchema`][ref-config-preagg-schema]
option in your `cube.js` configuration file. You should use also
[`securityContext`][ref-config-security-ctx] to determine which tenant is
requesting data.

**cube.js:**

```javascript theme={"dark"}
module.exports = {
  contextToAppId: ({ securityContext }) =>
    `CUBE_APP_${securityContext.userId}`,
  preAggregationsSchema: ({ securityContext }) =>
    `pre_aggregations_${securityContext.userId}`
}
```

## Multiple Data Models and Drivers

What if for application with ID 3, the data is stored not in Postgres, but in
MongoDB?

We can instruct Cube to connect to MongoDB in that case, instead of Postgres. To
do this, we'll use the [`driverFactory`][ref-config-driverfactory] option to
dynamically set database type. We will also need to modify our
[`securityContext`][ref-config-security-ctx] to determine which tenant is
requesting data. Finally, we want to have separate data models for every
application. We can use the [`repositoryFactory`][ref-config-repofactory] option
to dynamically set a repository with data model files depending on the `appId`:

**cube.js:**

```javascript theme={"dark"}
const { FileRepository } = require("@cubejs-backend/server-core")

module.exports = {
  contextToAppId: ({ securityContext }) =>
    `CUBE_APP_${securityContext.appId}_${securityContext.userId}`,
  contextToOrchestratorId: ({ securityContext }) =>
    `CUBE_APP_${securityContext.appId}_${securityContext.userId}`,
  driverFactory: ({ securityContext }) => {
    if (securityContext.appId === 3) {
      return {
        type: "mongobi",
        database: `my_app_${securityContext.appId}_${securityContext.userId}`,
        port: 3307
      }
    } else {
      return {
        type: "postgres",
        database: `my_app_${securityContext.appId}_${securityContext.userId}`
      }
    }
  },
  repositoryFactory: ({ securityContext }) =>
    new FileRepository(`model/${securityContext.appId}`)
}
```

## Scheduled Refreshes for Pre-Aggregations

If you need scheduled refreshes for your pre-aggregations in a multi-tenant
deployment, ensure you have configured
[`scheduled_refresh_contexts`][ref-config-refresh-ctx] correctly. You may also
need to configure [`scheduled_refresh_time_zones`][ref-config-refresh-tz].

<Warning>
  Leaving [`scheduled_refresh_contexts`][ref-config-refresh-ctx] unconfigured will
  lead to issues where the security context will be `undefined`. This is because
  there is no way for Cube to know how to generate a context without the required
  input.
</Warning>

[ref-config]: /admin/connect-to-data#configuration-options

[ref-config-opts]: /reference/configuration/config

[ref-config-db]: /admin/connect-to-data/data-sources

[ref-config-driverfactory]: /reference/configuration/config#driver_factory

[ref-config-repofactory]: /reference/configuration/config#repository_factory

[ref-config-preagg-schema]: /reference/configuration/config#pre_aggregations_schema

[ref-config-ctx-to-appid]: /reference/configuration/config#context_to_app_id

[ref-config-ctx-to-orch-id]: /reference/configuration/config#context_to_orchestrator_id

[ref-config-multi-data-src]: /admin/connect-to-data/multiple-data-sources

[ref-config-query-rewrite]: /reference/configuration/config#query_rewrite

[ref-config-refresh-ctx]: /reference/configuration/config#scheduled_refresh_contexts

[ref-config-refresh-tz]: /reference/configuration/config#scheduled_refresh_timezones

[ref-config-security-ctx]: /docs/data-modeling/access-control/context

[ref-security]: /docs/data-modeling/access-control

[ref-cube-datasource]: /reference/data-modeling/cube#data_source

[ref-cube-security-ctx]: /reference/data-modeling/context-variables#compile_context

[ref-per-tenant-data-source-recipe]: /recipes/configuration/multiple-sources-same-schema

[ref-per-tenant-data-model-recipe]: /recipes/configuration/custom-data-model-per-tenant


# React Embed SDK
Source: https://docs.cube.dev/embedding/react-embed-sdk

React Embed SDK is currently in public preview. The API may change in future releases.

<Info>
  React Embed SDK is currently in **public preview**. The API may change in future releases.
</Info>

The React Embed SDK provides React components for embedding Cube analytics directly into your React applications. It offers tighter integration with React's component model, giving you more control over styling, theming, and user interactions compared to iframe embedding.

## Installation

```bash theme={"dark"}
npm install @cube-dev/embed-sdk
# or
yarn add @cube-dev/embed-sdk
```

## Quick Start

The SDK requires [TanStack Query](https://tanstack.com/query) as a peer dependency. Wrap your application with `QueryClientProvider`, then add `CubeEmbedProvider` inside it:

```jsx theme={"dark"}
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { CubeEmbedProvider } from "@cube-dev/embed-sdk";

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <CubeEmbedProvider
        apiUrl="https://your-account.cubecloud.dev"
        sessionId="YOUR_SESSION_ID"
      >
        {/* Your embedded analytics components go here */}
      </CubeEmbedProvider>
    </QueryClientProvider>
  );
}
```

## Authentication

The React Embed SDK uses the same session-based authentication as [signed embedding](/embedding/iframe/auth/signed). Generate a session using the [Generate Session API](/reference/embed-apis/generate-session) and pass the `sessionId` to the provider.

A session expires after about 23 hours. SDK embedding talks to Cube's APIs directly rather than through an iframe, so the `postMessage` renewal contract in [Keeping a signed session alive](/embedding/iframe/events#keeping-a-signed-session-alive) — including the `autoRenewSession` helper — applies to iframe embedding only. With the React Embed SDK, mint a new `sessionId` before the current one expires and re-render the provider with it.

## Example

For a complete working implementation, see the [antd-cube-embed-sdk example](https://github.com/cubedevinc/cube-agent-examples/tree/main/examples/antd-cube-embed-sdk) on GitHub.


# Agent-to-agent: using the Chat API as a tool
Source: https://docs.cube.dev/recipes/ai/agent-to-agent

In this recipe, you will learn how to wrap the Cube Chat API as a tool for an external AI agent, enabling agent-to-agent analytics workflows.

In this recipe, you will learn how to wrap the Cube [Chat API][ref-chat-api]
as a tool for an external AI agent, enabling agent-to-agent analytics
workflows.

## Use case

When building AI-powered applications, you often have an orchestrating agent
(built with frameworks like LangChain, LlamaIndex, or CrewAI) that handles
user conversations and coordinates multiple capabilities. One of these
capabilities might be answering data questions — revenue trends, customer
metrics, pipeline analysis, and so on.

Rather than building a custom data retrieval pipeline, you can give your
agent a tool that calls the Cube Chat API. This way, the Cube AI agent
handles the hard parts — understanding the data model, writing correct
queries, and summarizing results — while your orchestrating agent decides
*when* to ask data questions and how to fold the answers into its broader
workflow.

## Architecture

The following diagram shows how the orchestrating agent delegates data
questions to the Cube AI agent via the Chat API:

```mermaid theme={"dark"}
sequenceDiagram
    participant User
    participant Agent as Your Agent<br/>(LangChain, etc.)
    participant Tool as Cube Chat API Tool
    participant Cube as Cube AI Agent

    User->>Agent: "Prepare a board report<br/>with last quarter financials"
    activate Agent
    Note over Agent: Decides it needs<br/>financial data
    Agent->>Tool: ask_cube("What was total revenue<br/>last quarter, broken down<br/>by product line?")
    activate Tool
    Tool->>Cube: POST /chat/stream-chat-state
    activate Cube
    Note over Cube: Queries data model,<br/>runs SQL, summarizes
    Cube-->>Tool: Streamed NDJSON response
    deactivate Cube
    Tool-->>Agent: "Total revenue was $4.2M…"
    deactivate Tool
    Note over Agent: Incorporates data<br/>into the report
    Agent-->>User: Board report with<br/>financial analysis
    deactivate Agent
```

**Key benefits of this approach:**

* **Separation of concerns.** Your agent handles conversation flow and
  business logic; Cube handles data access, governance, and query
  optimization.
* **Built-in security.** Row-level security, data access policies, and
  user attributes are enforced by the Cube layer — your agent does not
  need to implement them.
* **Multi-turn context.** By reusing a `chatId`, the Cube agent retains
  conversational context, so follow-up questions like "now break that
  down by region" work automatically.

## Prerequisites

Before you begin, make sure you have:

* A Cube Cloud deployment on a [Premium or Enterprise plan](https://cube.dev/pricing)
* An AI agent configured in **Admin -> Agents**
* An [API key][ref-api-keys] with access to the agent
* The **Chat API URL** copied from your agent settings

## Implementation

### Wrapping the Chat API as a tool

The core idea is to write a function that sends a question to the Cube
Chat API, collects the streamed response, and returns the final answer
as a plain string. You then register this function as a tool that your
agent can invoke.

Here is a helper that calls the Chat API and extracts the final answer:

```python theme={"dark"}
import requests
import json

CUBE_CHAT_API_URL = "YOUR_CHAT_API_URL"
CUBE_API_KEY = "YOUR_API_KEY"


def query_cube_agent(question: str, chat_id: str | None = None) -> str:
    """Send a question to the Cube AI agent and return its final answer."""

    payload = {
        "input": question,
        "sessionSettings": {
            "externalId": "orchestrating-agent",
        },
    }
    if chat_id:
        payload["chatId"] = chat_id

    response = requests.post(
        CUBE_CHAT_API_URL,
        headers={
            "Content-Type": "application/json",
            "Authorization": f"Api-Key {CUBE_API_KEY}",
        },
        json=payload,
        stream=True,
    )
    response.raise_for_status()

    messages = []
    for line in response.iter_lines():
        if line:
            messages.append(json.loads(line.decode("utf-8")))

    # Extract the final answer from the stream
    final_messages = [
        msg
        for msg in messages
        if msg.get("role") == "assistant"
        and isinstance(msg.get("graphPath"), list)
        and len(msg["graphPath"]) > 0
        and msg["graphPath"][0] == "final"
        and len(msg["graphPath"]) <= 2
    ]

    if final_messages:
        return final_messages[-1].get("content", "")

    # Fallback: return the last assistant message with content
    for msg in reversed(messages):
        if msg.get("role") == "assistant" and msg.get("content"):
            return msg["content"]

    return "No answer received from the Cube agent."
```

<Info>
  The function filters streamed messages for those where
  `graphPath[0] === "final"` to get the consolidated answer. See the
  [Chat API reference][ref-chat-api] for details on the response format.
</Info>

### LangChain integration

Below is a complete example of a LangChain agent that has access to the
Cube Chat API as a tool. When the agent decides it needs data to answer
a question, it calls the `ask_cube` tool automatically.

```python theme={"dark"}
import os
import requests
import json
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

CUBE_CHAT_API_URL = os.environ["CUBE_CHAT_API_URL"]
CUBE_API_KEY = os.environ["CUBE_API_KEY"]


def query_cube_agent(question: str) -> str:
    """Send a question to the Cube AI agent and return its final answer."""

    response = requests.post(
        CUBE_CHAT_API_URL,
        headers={
            "Content-Type": "application/json",
            "Authorization": f"Api-Key {CUBE_API_KEY}",
        },
        json={
            "input": question,
            "sessionSettings": {
                "externalId": "orchestrating-agent",
            },
        },
        stream=True,
    )
    response.raise_for_status()

    messages = []
    for line in response.iter_lines():
        if line:
            messages.append(json.loads(line.decode("utf-8")))

    final_messages = [
        msg
        for msg in messages
        if msg.get("role") == "assistant"
        and isinstance(msg.get("graphPath"), list)
        and len(msg["graphPath"]) > 0
        and msg["graphPath"][0] == "final"
        and len(msg["graphPath"]) <= 2
    ]

    if final_messages:
        return final_messages[-1].get("content", "")

    for msg in reversed(messages):
        if msg.get("role") == "assistant" and msg.get("content"):
            return msg["content"]

    return "No answer received from the Cube agent."


@tool
def ask_cube(question: str) -> str:
    """Ask a data analytics question. Use this tool whenever you need
    business metrics, KPIs, trends, or any data from the company's
    databases. Pass a clear, self-contained question."""

    return query_cube_agent(question)


llm = ChatOpenAI(model="gpt-4o")
agent = create_react_agent(llm, [ask_cube])

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": (
                    "Prepare a brief executive summary of last quarter's "
                    "performance. Include revenue, top products, and "
                    "month-over-month trends."
                ),
            }
        ]
    }
)

print(result["messages"][-1].content)
```

When you run this, the LangChain agent will:

1. Read the user's request and decide it needs data.
2. Call `ask_cube` with a focused data question (e.g., *"What was total
   revenue last quarter?"*).
3. Receive the Cube agent's answer with queried data and analysis.
4. Optionally call `ask_cube` again for additional data points.
5. Compose the final executive summary using all collected data.

### Passing user context

If your application has per-user data access policies, pass the
current user's identity and attributes through `sessionSettings` so that
the Cube agent enforces row-level security:

```python theme={"dark"}
def query_cube_agent_for_user(
    question: str,
    user_id: str,
    user_email: str | None = None,
    user_attributes: list[dict] | None = None,
) -> str:
    """Query the Cube agent with user-scoped permissions."""

    session_settings = {"externalId": user_id}
    if user_email:
        session_settings["email"] = user_email
    if user_attributes:
        session_settings["userAttributes"] = user_attributes

    response = requests.post(
        CUBE_CHAT_API_URL,
        headers={
            "Content-Type": "application/json",
            "Authorization": f"Api-Key {CUBE_API_KEY}",
        },
        json={
            "input": question,
            "sessionSettings": session_settings,
        },
        stream=True,
    )
    response.raise_for_status()

    # ... same response parsing as above ...
```

This way, a sales manager asking about revenue will only see data for
their territory, while a VP will see the full picture — without any
changes to your agent code.

### Multi-turn conversations

To maintain context across multiple questions in a single workflow, reuse
the `chatId` returned by the Cube Chat API:

```python theme={"dark"}
def query_cube_with_followup(questions: list[str]) -> list[str]:
    """Send a sequence of related questions, maintaining conversation context."""

    chat_id = None
    answers = []

    for question in questions:
        payload = {
            "input": question,
            "sessionSettings": {
                "externalId": "orchestrating-agent",
            },
        }
        if chat_id:
            payload["chatId"] = chat_id

        response = requests.post(
            CUBE_CHAT_API_URL,
            headers={
                "Content-Type": "application/json",
                "Authorization": f"Api-Key {CUBE_API_KEY}",
            },
            json=payload,
            stream=True,
        )
        response.raise_for_status()

        messages = []
        for line in response.iter_lines():
            if line:
                messages.append(json.loads(line.decode("utf-8")))

        # Capture the chatId for follow-up questions
        for msg in messages:
            if msg.get("id") == "__cutoff__" and msg.get("state", {}).get("chatId"):
                chat_id = msg["state"]["chatId"]

        final_messages = [
            msg
            for msg in messages
            if msg.get("role") == "assistant"
            and isinstance(msg.get("graphPath"), list)
            and len(msg["graphPath"]) > 0
            and msg["graphPath"][0] == "final"
            and len(msg["graphPath"]) <= 2
        ]

        if final_messages:
            answers.append(final_messages[-1].get("content", ""))
        else:
            answers.append("")

    return answers


# Example: ask a question and then a follow-up
answers = query_cube_with_followup([
    "What was total revenue last quarter?",
    "Now break that down by product line.",
])
```

With this approach, the second question — *"Now break that down by
product line"* — is understood in the context of the first, just like a
human conversation.

### Orchestrating multiple Cube agents

If your deployment uses [multi-agent][ref-multi-agent] — with specialized
Cube agents like a Sales Assistant and a Marketing Analyst living in the
same deployment — your orchestrating agent can choose the right Cube
agent for each question and route to it.

The [Chat API URL](#wrapping-the-chat-api-as-a-tool) embeds an `agentId`, so every agent in
your deployment has its own Chat API URL. Copy each one from **Admin →
Agents** for the corresponding agent. Switching between Cube agents
from your code is then just a matter of POSTing to a different URL —
the request shape is identical.

How your orchestrating agent learns which Cube agents exist is up to
you. Two common patterns:

* **List them in the system prompt.** Hardcode the agents (name,
  description, the domain each one covers) in your orchestrator's
  system prompt. Simple, and works well when the set of agents rarely
  changes.
* **Expose a discovery tool.** Add a `list_cube_agents` tool that
  returns the available agents at runtime. Useful when agents come and
  go, or when you want the orchestrator to pick them up without a code
  change.

The example below combines both: a `list_cube_agents` tool for
discovery and a single `ask_cube_agent` tool that takes an agent name
plus the question and routes the request to the matching Chat API URL.
It builds on the `query_cube_agent` helper from above, extended to
accept a `chat_api_url` argument instead of using a single hardcoded
URL.

```python theme={"dark"}
import json
import os
from langchain_core.tools import tool


CUBE_AGENTS = {
    "sales-assistant": {
        "url": os.environ["CUBE_SALES_AGENT_URL"],
        "description": (
            "Sales pipeline, deals, reps, quotas, and revenue by territory."
        ),
    },
    "marketing-analyst": {
        "url": os.environ["CUBE_MARKETING_AGENT_URL"],
        "description": (
            "Campaigns, channel attribution, traffic sources, and funnel "
            "conversion."
        ),
    },
}


@tool
def list_cube_agents() -> str:
    """List the available Cube agents and the domain each one covers.
    Call this first when you need data, then pick the most relevant
    agent for the user's question."""

    return json.dumps(
        {name: agent["description"] for name, agent in CUBE_AGENTS.items()}
    )


@tool
def ask_cube_agent(agent_name: str, question: str) -> str:
    """Ask a data analytics question to a specific Cube agent.

    Call `list_cube_agents` first to see which agents are available and
    which domain each one covers, then pass the chosen `agent_name`
    along with a focused, self-contained question."""

    agent = CUBE_AGENTS.get(agent_name)
    if agent is None:
        available = ", ".join(CUBE_AGENTS.keys())
        return (
            f"Unknown Cube agent '{agent_name}'. "
            f"Available agents: {available}."
        )

    return query_cube_agent(question, chat_api_url=agent["url"])
```

<Info>
  Alternatively, skip the discovery tool entirely and inline the list of
  agents and their domains in your orchestrator's system prompt. The
  orchestrator will then pass an `agent_name` directly to `ask_cube_agent`
  without an extra round trip.
</Info>

This pattern gives your orchestrating agent a clean routing layer: it
picks the right Cube agent for each question, and each Cube agent
answers using the rules, certified queries, and accessible views
configured for its [space][ref-spaces]. A sales question is routed to
the Sales Assistant and answered against the sales views; a marketing
question is routed to the Marketing Analyst and answered against the
marketing views — without your orchestrator needing to know any of
those details.

[ref-chat-api]: /reference/embed-apis/chat-api

[ref-api-keys]: /admin/account-billing/api-keys

[ref-multi-agent]: /admin/ai/multi-agent

[ref-spaces]: /admin/ai/multi-agent#spaces


# Providing a custom data model for each tenant
Source: https://docs.cube.dev/recipes/configuration/custom-data-model-per-tenant

We have multiple users and we would like them to have different data models. These data models can be completely different or have something in common.

## Use case

We have multiple users and we would like them to have different data models.
These data models can be completely different or have something in common.

## Configuration

Let's assume that we have two users: `Alice` and `Bob`. We'll refer to them as
*tenants*. We're going to provide custom data models for these tenants by
implementing [multitenancy][ref-multitenancy].

### Multitenancy

First of all, we need to define the following configuration options so that Cube
knows how to distinguish between your tenants:

* [`context_to_app_id`][ref-context-to-app-id] to derive tenant identifiers
  from security contexts.
* [`scheduled_refresh_contexts`][ref-scheduled-refresh-contexts] to provide
  a list of security contexts.

<Note>
  `context_to_app_id` makes the data model per-tenant, which is all this recipe
  needs. Querying and caching (database connections, query queues, and
  pre-aggregations) stay shared between tenants unless you also configure
  [`context_to_orchestrator_id`][ref-context-to-orchestrator-id] and
  [`pre_aggregations_schema`][ref-pre-aggregations-schema].
</Note>

Put the following code into your `cube.py` or `cube.js` [configuration
file][ref-config-files]:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('scheduled_refresh_contexts')
  def scheduled_refresh_contexts() -> list[object]:
    return [
      {
        'securityContext': { 'tenant_id': 'Alice' }
      },
      {
        'securityContext': { 'tenant_id': 'Bob' }
      }
    ]

  @config('context_to_app_id')
  def context_to_app_id(ctx: dict) -> str:
    return ctx['securityContext']['tenant_id']
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    scheduledRefreshContexts: () => {
      return [
        {
          securityContext: { tenant_id: 'Alice' }
        },
        {
          securityContext: { tenant_id: 'Bob' }
        }
      ]
    },

    contextToAppId: ({ securityContext }) => {
      return securityContext.tenant_id
    }
  }
  ```
</CodeGroup>

## Data modeling

### Customizing member-level access

The simplest way to customize the data models is by changing the [member-level access][ref-mls]
to data model entities. It works great for use cases when tenants share parts of
their data models.

By setting the `public` parameter of [cubes][ref-cubes-public], [views][ref-views-public],
[measures][ref-measures-public], [dimensions][ref-dimensions-public], and
[segments][ref-segments-public], you can ensure that each tenant has its unique
*perspective* of the whole data model.

With the following data model, `Alice` will only have access to `cube_a`,
`Bob` will only have access to `cube_b`, and they both will have access to
select members of `cube_x`:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  {% set tenant_id = COMPILE_CONTEXT['securityContext']['tenant_id'] %}

  cubes:
    - name: cube_a
      sql_table: table_a
      public: {{ tenant_id == 'Alice' }}
    
      measures:
        - name: count
          type: count

    - name: cube_b
      sql_table: table_b
      public: {{ tenant_id == 'Bob' }}
    
      measures:
        - name: count
          type: count

    - name: cube_x
      sql_table: table_x
   
      measures:
        - name: count
          type: count

        - name: count_a
          type: count
          public: {{ tenant_id == 'Alice' }}

        - name: count_b
          type: count
          public: {{ tenant_id == 'Bob' }}
  ```

  ```javascript title="JavaScript" theme={"dark"}
  const { tenant_id } = COMPILE_CONTEXT.securityContext

  cube(`cube_a`, {
    sql_table: `table_a`,
    public: tenant_id == 'Alice',
    
    measures: {
      count: {
        type: `count`
      }
    }
  })

  cube(`cube_b`, {
    sql_table: `table_b`,
    public: tenant_id == 'Bob',
    
    measures: {
      count: {
        type: `count`
      }
    }
  })

  cube(`cube_x`, {
    sql_table: `table_x`,
    
    measures: {
      count: {
        type: `count`
      },

      count_a: {
        type: `count`,
        public: tenant_id == 'Alice'
      },

      count_b: {
        type: `count`,
        public: tenant_id == 'Bob'
      }
    }
  })
  ```
</CodeGroup>

For your convenience, [Playground][ref-playground] ignores member-level access configration
and marks data model entities that are not accessible for querying through
[APIs][ref-apis] with the lock icon.

Here's what `Alice` *sees*:

<Frame>
  <img />
</Frame>

And here's the *perspective* of `Bob`:

<Frame>
  <img />
</Frame>

### Customizing other parameters

Similarly to [customizing member-level access](#customizing-member-level-access),
you can set other parameters of data model entities for each tenant individually:

* By setting `sql` or [`sql_table` parameters][ref-cube-sql-table] of cubes, you
  can ensure that each tenant accesses data from its own tables or database schemas.
* By setting the [`data_source` parameter][ref-cube-data-source], you can point
  each tenant to its own [data source][ref-data-sources], allowing to switch between
  database names or even database servers.
* By setting the [`extends` parameter][ref-cube-extends], you can ensure that
  cubes of some tenants are enriched with custom measures, dimensions, or joins.

With the following data model, `cube_x` will read data from the `Alice` database
schema for `Alice` and from `Bob` database schema for `Bob`:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  {% set tenant_id = COMPILE_CONTEXT['securityContext']['tenant_id'] %}

  cubes:
    - name: cube_x
      sql_table: {{ tenant_id | safe }}.table_x
   
      measures:
        - name: count
          type: count
  ```

  ```javascript title="JavaScript" theme={"dark"}
  const { tenant_id } = COMPILE_CONTEXT.securityContext

  cube(`cube_x`, {
    sql_table: `${tenant_id}.table_x`,
    
    measures: {
      count: {
        type: `count`
      }
    }
  })
  ```
</CodeGroup>

Here's the generated SQL for `Alice`:

<Frame>
  <img />
</Frame>

And here's the generated SQL for `Bob`:

<Frame>
  <img />
</Frame>

### Dynamic data modeling

A more advanced way to customize the data models is by using [dynamic data
models][ref-dynamic-data-modeling]. It allows to create fully customized data
models for each tenant programmatically.

With the following data model, `cube_x` will have the `count_a` measure for
`Alice` and the `count_b` measure for `Bob`:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  {% set tenant_id = COMPILE_CONTEXT['securityContext']['tenant_id'] %}

  cubes:
    - name: cube_x
      sql_table: table_x
   
      measures:
        - name: count
          type: count

        {% if tenant_id == 'Alice' %}
          - name: count_a
            sql: column_a
            type: count
        {% endif %}

        {% if tenant_id == 'Bob' %}
          - name: count_b
            sql: column_b
            type: count
        {% endif %}
  ```

  ```javascript title="JavaScript" theme={"dark"}
  const { tenant_id } = COMPILE_CONTEXT.securityContext

  const measures = {
    count: {
      type: `count`
    }
  }

  if (tenant_id == 'Alice') {
    measures['count_a'] = {
      sql: () => `column_a`,
      type: `count`
    }
  }

  if (tenant_id == 'Bob') {
    measures['count_b'] = {
      sql: () => `column_b`,
      type: `count`
    }
  }

  cube(`cube_x`, {
    sql_table: `table_x`,

    measures
  })
  ```
</CodeGroup>

Here's the data model and the generated SQL for `Alice`:

<Frame>
  <img />
</Frame>

And here's the data model and the generated SQL for `Bob`:

<Frame>
  <img />
</Frame>

### Loading from disk

You can also maintain independent data models for each tenant that you would load
from separate locations on disk. It allows to create fully customized data
models for each tenant that are maintained mostly as static files.

By using the [`repository_factory` option][ref-repository-factory] with the
`file_repository` utility, you can load data model files for each tenant from
a custom path.

With the following configuration, `Alice` will load the data model files from
`model/Alice` while `Bob` will load the data model files from `model/Bob`:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config, file_repository
   
  @config('repository_factory')
  def repository_factory(ctx: dict) -> list[dict]:
    return file_repository(f"model/{ctx['securityContext']['tenant_id']}")

  # Other configuration options, e.g., for multitenancy, etc.
  ```

  ```javascript title="JavaScript" theme={"dark"}
  const { FileRepository } = require("@cubejs-backend/server-core")
   
  module.exports = {
    repositoryFactory: ({ securityContext }) => {
      return new FileRepository(`model/${securityContext.tenant_id}`)
    }

    // Other configuration options, e.g., for multitenancy, etc.
  }
  ```
</CodeGroup>

#### Example

Here's an example of how to use this approach. Let's say we have a folder structure
as follows:

```tree theme={"dark"}
model/
├── avocado/
│   └── cubes
│       └── Products.js
└── mango/
    └── cubes
        └── Products.js
```

Let's configure Cube to use a specific data model path for each tenant using the
`repositoryFactory` function along with `contextToAppId` and `scheduledRefreshContexts`:

```javascript theme={"dark"}
const { FileRepository } = require("@cubejs-backend/server-core")

module.exports = {
  contextToAppId: ({ securityContext }) =>
    `CUBE_APP_${securityContext.tenant}`,

  repositoryFactory: ({ securityContext }) =>
    new FileRepository(`model/${securityContext.tenant}`),

  scheduledRefreshContexts: () => [
    { securityContext: { tenant: "avocado" } },
    { securityContext: { tenant: "mango" } }
  ]
}
```

In this example, we'll filter products differently for each tenant. For the `avocado`
tenant, we'll show products with odd `id` values, and for the `mango` tenant, we'll show
products with even `id` values.

This is the `products` cube for the `avocado` tenant:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products
      sql: |
        SELECT * FROM public.Products WHERE MOD (id, 2) = 1
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`products`, {
    sql: `SELECT *
      FROM public.Products
      WHERE MOD (id, 2) = 1`,

    // ...
  })
  ```
</CodeGroup>

This is the `products` cube for the `mango` tenant:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products
      sql: |
        SELECT * FROM public.Products WHERE MOD (id, 2) = 0
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`products`, {
    sql: `SELECT *
      FROM public.Products
      WHERE MOD (id, 2) = 0`,

    // ...
  })
  ```
</CodeGroup>

To fetch the products for different tenants, we send the same query but with different
JWTs:

```json theme={"dark"}
{
  "sub": "1234567890",
  "tenant": "Avocado",
  "iat": 1000000000,
  "exp": 5000000000
}
```

```json5 theme={"dark"}
{
  sub: "1234567890",
  tenant: "Mango",
  iat: 1000000000,
  exp: 5000000000,
}
```

This approach produces different results for each tenant as expected:

```json5 theme={"dark"}
// Avocado products
[
  {
    "products.id": 1,
    "products.name": "Generic Fresh Keyboard",
  },
  {
    "products.id": 3,
    "products.name": "Practical Wooden Keyboard",
  },
  {
    "products.id": 5,
    "products.name": "Handcrafted Rubber Chicken",
  },
]
```

```json5 theme={"dark"}
// Mango products:
[
  {
    "products.id": 2,
    "products.name": "Gorgeous Cotton Sausages",
  },
  {
    "products.id": 4,
    "products.name": "Handmade Wooden Soap",
  },
  {
    "products.id": 6,
    "products.name": "Handcrafted Plastic Chair",
  },
]
```

You can find a working example of this approach on [GitHub](https://github.com/cube-js/cube/tree/master/examples/recipes/using-different-schemas-for-tenants).
Run it with the `docker-compose up` command to see the results in your console.

### Loading externally

Finally, you can maintain independent data models for each tenant that you would
load from an external location rather from a folder on disk. Good examples of
such  locations are an S3 bucket, a database, or an external API. It allows to
provide fully customized data models for each tenant that you have full control of.

It can be achieved by using the same [`repository_factory` option][ref-repository-factory].
Instead of using the `file_repository` utility, you would have to write your own
code that fetches data model files for each tenant.

[ref-multitenancy]: /embedding/multitenancy

[ref-scheduled-refresh-contexts]: /reference/configuration/config#scheduled_refresh_contexts

[ref-context-to-app-id]: /reference/configuration/config#context_to_app_id

[ref-context-to-orchestrator-id]: /reference/configuration/config#context_to_orchestrator_id

[ref-pre-aggregations-schema]: /reference/configuration/config#pre_aggregations_schema

[ref-config-files]: /admin/connect-to-data#cubepy-and-cubejs-files

[ref-mls]: /docs/data-modeling/access-control/member-level-security

[ref-cubes-public]: /reference/data-modeling/cube#public

[ref-views-public]: /reference/data-modeling/view#public

[ref-measures-public]: /reference/data-modeling/measures#public

[ref-dimensions-public]: /reference/data-modeling/dimensions#public

[ref-segments-public]: /reference/data-modeling/segments#public

[ref-playground]: /docs/explore-analyze/playground

[ref-apis]: /reference

[ref-cube-sql-table]: /reference/data-modeling/cube#sql_table

[ref-cube-data-source]: /reference/data-modeling/cube#data_source

[ref-data-sources]: /admin/connect-to-data/multiple-data-sources

[ref-cube-extends]: /reference/data-modeling/cube#extends

[ref-dynamic-data-modeling]: /docs/data-modeling/dynamic

[ref-repository-factory]: /reference/configuration/config#repository_factory


# Optimizing data source usage
Source: https://docs.cube.dev/recipes/configuration/data-store-cost-saving-guide

Shrink warehouse spend by shaping how Cube hits upstream stores through pre-aggregations, refresh strategy, and workload-aware settings.

As a semantic layer, Cube supports various [data
sources][ref-config-data-sources], including cloud-based data warehouses and
regular databases, and various [use cases][ref-intro] such as embedded analytics
and business intelligence.

Depending on the upstream data source and the use case, Cube can be configured
in a way that provides the best economic effect and maximizes cost savings.

## Reducing data store usage

Cloud-based data stores commonly use two pricing models: *on-demand*, when you
get charged for the storage and compute resources used to process each query, or
*flat-rate*, when queries consume an pre-agreed resource quota.

Regardless of the pricing model, it's usually a good idea to implement measures
that reduce usage:

* In case of the on-demand model, reduced usage will directly lead to a reduced
  bill.
* In case of the flat-rate model, reduced usage will reduce resource contention
  and leave more spare resources to other consumers (e.g., for ad-hoc
  exploration) or allow to reduce the allocated quota, leading to a reduced
  bill.

Often, reducing data store usage allows cloud-based [data
warehouses][snowflake-auto-suspend] and [regular databases][neon-auto-suspend]
to more frequently auto-suspend their compute resources or scale them down to
zero.

### Using pre-aggregations

Cube queries upstream data sources for the following purposes:

* Serving interactive queries, incoming to any of [supported
  APIs][ref-config-apis], and populating the first, in-memory, layer of caching.
* Populating pre-aggregations, the second layer of [caching][ref-caching].
* Ensuring and checking the freshness of data in both layers of caching.

[Pre-aggregations][ref-caching-using-pre-aggs] are one of Cube's core tenets.
They contain condensed subsets of source data, optimized for serving queries
more effectively than a data store is able to. Using pre-aggregations is the
most effective way to reduce data store usage and costs.

<Info>
  When defining your data model or generally operating the semantic layer,
  consider [inspecting your queries][ref-query-history] and [configuring necessary
  pre-aggregations][ref-caching-using-pre-aggs] on a periodic basis.
</Info>

### Preventing non-cached queries

In some use cases, it's possible to configure pre-aggregations in a way that
they match all necessary queries and always serve them from cache. However, a
new or malformed query would still be able to hit the data store. Preventing
non-cached queries ensures that accidental spend can't happen.

Cube supports the [rollup-only mode][ref-caching-rollup-only-mode] which
prevents queries from hitting the data store. Only queries served from
pre-aggregations are allowed; other queries are rejected.

<Info>
  Consider using the rollup-only mode if all your queries are matched by
  pre-aggregations and served from cache. Use [Query History][ref-query-history]
  to check the status of any query.
</Info>

### Refreshing data timely

Pre-aggregations are populated by Cube on [schedule][ref-pre-agg-refresh-key], a
[condition][ref-pre-agg-refresh-key], or an external trigger. Adjusting the
timing and frequency of pre-aggregation refresh in accordance with your use case
can substantially reduce the data store usage and costs. For example, if you
know that data is loaded and transformed in a data warehouse daily, it makes
sense to refresh pre-aggregations with the same cadence.

<Info>
  Consider configuring the [refresh keys][ref-pre-agg-refresh-key] of
  pre-aggregations according to your use case.
</Info>

In real-time use cases, when queries should return fresh data, it is still
possible to leverage pre-aggregations. Cube supports [lambda
pre-aggregations][ref-caching-lambda-pre-aggs] which transparently combine
cached data and recent data from the data store. Lambda pre-aggregations can
reduce data store usage in cases when queries span both historical and recent
data.

<Info>
  Cosider using [lambda pre-aggregations][ref-caching-lambda-pre-aggs] in
  real-time use cases.
</Info>

### Refreshing data incrementally

Often, [fact tables][wiki-fact-table] contain [time-series][wiki-time-series]
data that change in time by appending new rows, not updating the existing ones.
In that case, data can be partitioned by a time dimension and only metrics
calculated from the last partition would need to be updated when new data
arrives. For example, the volume of sales at Acme Corporation in year 2022
doesn't change when new orders are made in 2023; however, the volume of sales in
year 2023 will be changing as new orders are made during that year. Caching
metrics for historical data and refreshing time-series data incrementally can
help drastically reduce data source usage.

Cube supports [partitioned and incrementally
refreshed][ref-caching-partitioning-pre-aggs] pre-aggregations that, on update,
retrieve only the last partition of data from the data store.

<Info>
  Consider configuring [partitions][ref-caching-partitioning-pre-aggs] and using
  incremental refresh for time-series data. Use the
  [Pre-aggregations][ref-workspace-pre-aggs] view to check the status of every
  partition.
</Info>

Moreover, Cube supports customizable update windows that may span more than one
partition, supporting use cases when relatively fresh historical data is indeed
being updated. For example, financial transactions are often [settled in two or
three business days][wiki-settlement-cycle]; however, certain facts about
transactions can change between their creation and settlement—but never after a
transaction was settled. In this case, it makes sense to use an update window
that spans from creation to settlement.

<Info>
  Consider configuring wider [update windows][ref-caching-partitioning-pre-aggs]
  when data outside the last partition can be updated.
</Info>

[ref-config-data-sources]: /admin/connect-to-data/data-sources

[ref-intro]: /docs/introduction

[ref-caching]: /docs/pre-aggregations

[ref-pre-agg-refresh-key]: /reference/data-modeling/pre-aggregations#refresh_key

[ref-config-apis]: /admin/connect-to-data/visualization-tools#ap-is-references

[ref-caching-using-pre-aggs]: /docs/pre-aggregations/getting-started-pre-aggregations

[ref-query-history]: /admin/monitoring/query-history

[ref-caching-using-pre-aggs]: /docs/pre-aggregations/using-pre-aggregations

[ref-caching-rollup-only-mode]: /docs/pre-aggregations/using-pre-aggregations#rollup-only-mode

[ref-caching-lambda-pre-aggs]: /docs/pre-aggregations/lambda-pre-aggregations

[wiki-fact-table]: https://en.wikipedia.org/wiki/Fact_table

[wiki-time-series]: https://en.wikipedia.org/wiki/Time_series

[ref-caching-partitioning-pre-aggs]: /docs/pre-aggregations/using-pre-aggregations#partitioning

[wiki-settlement-cycle]: https://en.wikipedia.org/wiki/T%2B2

[ref-workspace-pre-aggs]: http://localhost:8000/cloud/inspecting-pre-aggregations

[snowflake-auto-suspend]: https://docs.snowflake.com/en/user-guide/warehouses-overview#auto-suspension-and-auto-resumption

[neon-auto-suspend]: https://neon.tech/docs/introduction/autoscaling


# Referencing environment variables
Source: https://docs.cube.dev/recipes/configuration/environment-variables

Read deployment secrets and tunables from environment variables inside Python config, JavaScript config, and data model code.

## Use case

We want to move important or frequently changing configuration values (e.g.,
passwords and other secrets) to environment variables and then reference them in
the [data model code][ref-data-model-syntax] and [configuration files][ref-config-files].

It would prevent these values from being stored in a source code repository and
being exposed to more people than needed. It would also allow to update the
deployment configuration without changing the source code.

## Configuration

In Cube Core, you can put environment variables into [`docker-compose.yml`][ref-docker-compose-config].
In Cube Cloud, you can manage environment variables via the **Settings**
page of your deployment.

### `cube.py` file

In the `cube.py` configuration file, you can access environment variables either
via the `getenv` function or the `environ` dictionary from the `os` package.
`getenv` returns `None` if the variable is not set and allows to provide a default
value. `environ` raises a `KeyError` if the variable is not set.

```pythontitle="cube.py" theme={"dark"}
import os

value_or_none = os.getenv('MY_ENV_VAR')
print(value_or_none)

value_or_default = os.getenv('MY_OTHER_ENV_VAR', 'my_default_value')
print(value_or_default)

value_or_error = os.environ['MY_OTHER_ENV_VAR']
print(value_or_error)
```

### `cube.js` file

In the `cube.js` configuration file, you can access environment variables via the
global `process.env` object. It returns `undefined` if the variable is not set.
You can use the `||` operator to provide a default value.

```javascripttitle="cube.js" theme={"dark"}
value_or_undefined = process.env.MY_ENV_VAR
console.log(value_or_undefined)

value_or_default = process.env.MY_OTHER_ENV_VAR || 'my_default_value'
console.log(value_or_default)
```

## Data modeling

### YAML files

In YAML data model files, you can access environment variables via the built-in
`env_var` Jinja function. It raises an error if the variable is not set and allows
to provide a default value.

```yamltitle="model/cubes/my_cube.yml" theme={"dark"}
cubes:
  - name: my_cube
    description: "{{ env_var('MY_ENV_VAR') | safe }}"
    sql_table: "{{ env_var('MY_OTHER_ENV_VAR', 'my_default_value') | safe }}.table"
 
    measures:
      - name: count
        type: count
```

### `globals.py` file

In the [`globals.py` file][ref-python-globals], similarly to the [`cube.py`
file](#cube-py-file), you can access environment variables either via the `getenv`
function or the `environ` dictionary from the `os` package.

Consider the following file structure:

```tree theme={"dark"}
.
└── model
    └── globals.py
    └── cubes
        └── my_cube.yml
```

You can access environment variables in the `globals.py` file and potentially
[expose them to Jinja templates][ref-template-context] via `TemplateContext`:

```pythontitle="model/globals.py" theme={"dark"}
from cube import TemplateContext
import os

template = TemplateContext()

value_or_none = os.getenv('MY_ENV_VAR')
template.add_variable('value_or_none', value_or_none)

value_or_default = os.getenv('MY_OTHER_ENV_VAR', 'my_default_value')
template.add_variable('value_or_default', value_or_default)
```

```yamltitle="model/cubes/my_cube.yml" theme={"dark"}
cubes:
  - name: my_cube
    description: "{{ value_or_none | safe }}"
    sql_table: "{{ value_or_default | safe }}.table"
 
    measures:
      - name: count
        type: count
```

### JavaScript files

In JavaScript data model files, the global `process.env` object is [not
available][ref-nodejs-globals]. However, you can use that object in JavaScript
files *outside of the data model directory* and import from those files.

Consider the following file structure:

```tree theme={"dark"}
.
├── env.js
└── model
    └── cubes
        └── my_cube.js
```

You can't access `process.env` in the `my_cube.js` file but you can do that in
the `env.js` file since it's outside of the `model` directory:

```javascripttitle="env.js" theme={"dark"}
module.exports = {
  value_or_undefined: process.env.MY_ENV_VAR,
  value_or_default: process.env.MY_OTHER_ENV_VAR || 'my_default_value'
}
```

```javascripttitle="model/cubes/my_cube.js" theme={"dark"}
import { value_or_undefined, value_or_default } from '../env'

cube(`my_cube`, {
  description: `${value_or_undefined}`,
  sql_table: `${value_or_default}.table`,
  
  measures: {
    count: {
      type: `count`
    }
  }
})
```

[ref-data-model-syntax]: /docs/data-modeling/concepts/syntax

[ref-config-files]: /admin/connect-to-data#cubepy-and-cubejs-files

[ref-docker-compose-config]: /admin/deployment/core#configuration

[ref-python-globals]: /docs/data-modeling/dynamic/jinja#python

[ref-template-context]: /reference/data-modeling/cube-package#templatecontext-class

[ref-nodejs-globals]: /docs/data-modeling/dynamic/schema-execution-environment#nodejs-globals-processenv-consolelog-and-others


# Providing a custom data source for each tenant
Source: https://docs.cube.dev/recipes/configuration/multiple-sources-same-schema

Route each tenant to its own physical database while reusing one data model by combining context IDs with a dynamic driver factory.

## Use case

We need to access the data from different data sources for different tenants.
For example, we are the platform for the online website builder, and each client
can only view their data. The same data model is used for all clients.

## Configuration

Each client has its own database. In this recipe, the `Mango Inc` tenant keeps
its data in the remote `ecom` database while the `Avocado Inc` tenant works with
the local database (bootstrapped in the `docker-compose.yml` file) which has the
same data model.

To enable multitenancy, use the
[`contextToAppId`](/reference/configuration/config#context_to_app_id) function to
provide distinct identifiers for each tenant's data model and the
[`contextToOrchestratorId`](/reference/configuration/config#context_to_orchestrator_id)
function to give each tenant its own database connections and query queues.
Without the latter, all tenants would share a single connection to whichever
data source was resolved first. Also, implement the
[`driverFactory`](/reference/configuration/config#driver_factory) function where
you can select a data source based on the tenant name.
[JSON Web Token](/docs/data-modeling/access-control) includes information about the tenant name in
the `tenant` property of the `securityContext`.

```javascript theme={"dark"}
module.exports = {
  // Provides a distinct identifier for each tenant's compiled data model
  contextToAppId: ({ securityContext }) =>
    `CUBE_APP_${securityContext.tenant}`,

  // Provides a distinct identifier for each tenant's query orchestrator, so
  // that every tenant gets its own database connections and query queues
  contextToOrchestratorId: ({ securityContext }) =>
    `CUBE_APP_${securityContext.tenant}`,

  // Selects the database connection configuration based on the tenant name
  driverFactory: ({ securityContext }) => {
    if (!securityContext.tenant) {
      throw new Error("No tenant found in Security Context!")
    }

    if (securityContext.tenant === "Avocado Inc") {
      return {
        type: "postgres",
        database: "localDB",
        host: "postgres",
        user: "postgres",
        password: "example",
        port: "5432"
      }
    }

    if (securityContext.tenant === "Mango Inc") {
      return {
        type: "postgres",
        database: "ecom",
        host: "demo-db.cube.dev",
        user: "cube",
        password: "12345",
        port: "5432"
      }
    }

    throw new Error("Unknown tenant in Security Context")
  }
}
```

## Query

To get users for different tenants, we will send two identical requests with
different JWTs. Also, we send a query with unknown tenant to show that he cannot
access to the data model of other tenants.

```json5 theme={"dark"}
// JWT payload for "Avocado Inc"
{
  sub: "1234567890",
  tenant: "Avocado Inc",
  iat: 1000000000,
  exp: 5000000000,
}
```

```json5 theme={"dark"}
// JWT payload for "Mango Inc"
{
  sub: "1234567890",
  tenant: "Mango Inc",
  iat: 1000000000,
  exp: 5000000000,
}
```

```json5 theme={"dark"}
// JWT payload for "Peach Inc"
{
  sub: "1234567890",
  tenant: "Peach Inc",
  iat: 1000000000,
  exp: 5000000000,
}
```

## Result

We have received different data from different data sources depending on the
tenant's name:

```json5 theme={"dark"}
// Avocado Inc last users:
[
  {
    "Users.id": 700,
    "Users.name": "Freddy Gulgowski",
  },
  {
    "Users.id": 699,
    "Users.name": "Julie Crooks",
  },
  {
    "Users.id": 698,
    "Users.name": "Macie Ryan",
  },
]
```

```json5 theme={"dark"}
// Mango Inc last users:
[
  {
    "Users.id": 705,
    "Users.name": "Zora Vallery",
  },
  {
    "Users.id": 704,
    "Users.name": "Fawn Danell",
  },
  {
    "Users.id": 703,
    "Users.name": "Moyra Denney",
  },
];
```

```json5 theme={"dark"}
// Peach Inc error:
{ error: "Error: Unknown tenant in Security Context" }
```

## Source code

Please feel free to check out the
[full source code](https://github.com/cube-js/cube/tree/master/examples/recipes/multiple-data-sources)
or run it with the `docker-compose up` command. You'll see the result, including
queried data, in the console.


# Using SSL connections to a data source
Source: https://docs.cube.dev/recipes/configuration/using-ssl-connections-to-data-source

Enable TLS to upstream databases from Cube and, when required, inject custom CA bundles, client certificates, and private keys.

## Use case

Cube supports SSL-encrypted connections to various data sources. Please check
the documentation for a particular [data source][ref-config-db] for specific
instructions.

## Configuration

Generally, you can enable SSL via the [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) environment variable.

### Cube Core

To enable SSL, set the [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl) environment variable to `true`. Cube can
also be configured to use custom connection settings. For example, to use a
custom certificate authority and certificates, you could do the following:

```dotenv theme={"dark"}
CUBEJS_DB_SSL_CA=/path/to/ssl/ca.pem
CUBEJS_DB_SSL_CERT=/path/to/ssl/cert.pem
CUBEJS_DB_SSL_KEY=/path/to/ssl/key.pem
```

You can also set the above environment variables to the contents of the PEM
files; for example:

```dotenv theme={"dark"}
CUBEJS_DB_SSL_CA="-----BEGIN CERTIFICATE-----
MIIDDjCCAfYCCQCN/HhSZ3ofTDANBgkqhkiG9w0BAQsFADBJMQswCQYDVQQGEwJV
SzEMMAoGA1UECgwDSUJNMQ0wCwYDVQQLDARBSU9TMR0wGwYDVQQDDBRhaW9zLW9y
Y2gtZGV2LWVudi1DQTAeFw0yMTAyMTUyMzIyMTZaFw0yMzEyMDYyMzIyMTZaMEkx
CzAJBgNVBAYTAlVLMQwwCgYDVQQKDANJQk0xDTALBgNVBAsMBEFJT1MxHTAbBgNV
BAMMFGFpb3Mtb3JjaC1kZXYtZW52LUNBMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A
MIIBCgKCAQEAyhYY9+4TduTsNRh/6MaRtE59j8HkAkoQYvNYZN7D1j1oV6yhzitn
oN4bD+HiQWe4J3mwAaJOAAJRCkIVyUXxwZUCPxGN/KVha/pcB8hN6LHfI6vInixp
U9kHNYWWBn428nMeMqts7yqly/HwG1/qO+j4178c8lZNS7Uwh76y+lAEaIkeBipq
i4WuCOiChFc/sIV7g4DcLKKbqzDWtRDjbsg7JRfsALO5gM360GrNYkhV4C5lm8Eh
ozNuaPhS65zO93PMj/3UTyuctXKa7WpaHJHoKZRXAuOwSamvqvFgIQ0SSnW+qcud
fL3GAPJn7d065gh7JvgcT86v7WWBiUNs0QIDAQABMA0GCSqGSIb3DQEBCwUAA4IB
AQCzw00d8e0e5AYZtzIk9hjczta7JHy2/cwTMv0opzBk6C26G6YZww+9brHW2w5U
mY/HKBnGnMadjMWOZmm9Vu0B0kalYY0lJdE8alO1aiv5B9Ms/XIt7FzzGtfv9gYJ
cw5/nzGBBMJNICC1kVLnzzlllLferhCIrczDyPcu16o1Flc7q1p8AbwQpC+A2I/L
8nWlFeHZ+watLtQ1lF3qDzzCumPHrJqAGmlp0265owCM8Q5zv8AL5DStIZvtexrI
JqbwLdbA8smyOFRwCckOWcWjnrEDjO2e3NLWINbB7Z4ZRviZSEH5UZlDLVu+ahGV
KmZIuh7+XpXzJ1MN0SBZXgXH
-----END CERTIFICATE-----"
```

### Cube Cloud

When setting up a new deployment, select the SSL checkbox when entering database
credentials:

<Frame>
  <img alt="Cube Cloud Database Connection Screen for Postgres" />
</Frame>

To use custom SSL certificates between Cube Cloud and your database server, go
to the **Configuration** tab in the **Settings** screen:

<Frame>
  <img alt="Cube Cloud Database Connection Screen" />
</Frame>

Add the following environment variables:

| Environment Variable                                                                      | Description                                                                                                                                                                                                 | Example                                  |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| [`CUBEJS_DB_SSL`](/reference/configuration/environment-variables#cubejs_db_ssl)           | If `true`, enables SSL encryption for database connections from Cube                                                                                                                                        | `true`, `false`                          |
| [`CUBEJS_DB_SSL_CA`](/reference/configuration/environment-variables#cubejs_db_ssl_ca)     | The contents of a CA bundle in PEM format, or a path to one. For more information, check the `options.ca` property for TLS Secure Contexts [in the Node.js documentation][nodejs-docs-tls-options]          | A valid CA bundle or a path to one       |
| [`CUBEJS_DB_SSL_CERT`](/reference/configuration/environment-variables#cubejs_db_ssl_cert) | The contents of an SSL certificate in PEM format, or a path to one. For more information, check the `options.cert` property for TLS Secure Contexts [in the Node.js documentation][nodejs-docs-tls-options] | A valid SSL certificate or a path to one |
| [`CUBEJS_DB_SSL_KEY`](/reference/configuration/environment-variables#cubejs_db_ssl_key)   | The contents of a private key in PEM format, or a path to one. For more information, check the `options.key` property for TLS Secure Contexts [in the Node.js documentation][nodejs-docs-tls-options]       | A valid SSL private key or a path to one |

[nodejs-docs-tls-options]: https://nodejs.org/docs/latest/api/tls.html#tls_tls_createsecurecontext_options

[ref-config-db]: /admin/connect-to-data/data-sources


# Retrieving numeric values on the front-end
Source: https://docs.cube.dev/recipes/core-data-api/cast-numerics

Recipe for coercing REST (JSON) numeric strings into JavaScript numbers on the client, including precision pitfalls and when casting is unsafe.

## Use case

The REST (JSON) API returns numeric measure and dimension values as strings.
However, we'd like to receive them as JavaScript `Number` type.
In the recipe below, we explore a way to have numeric values automatically
converted to `Number`. This is a potentially unsafe operation, so we also
explore when it's safe to do so.

## Data modeling

Let's assume we have the following cube with a numeric dimension and a
numeric measure:

```yaml theme={"dark"}
cubes:
  - name: cube_with_big_numbers
    sql: |
      SELECT              123::BIGINT AS number UNION ALL
      SELECT 9007199254740991::BIGINT AS number UNION ALL
      SELECT 9999999999999999::BIGINT AS number

    dimensions:
      - name: number
        sql: number
        type: number

    measures:
      - name: sum
        sql: number
        type: sum
```

## Query via the REST (JSON) API

Let's send the following query via the REST (JSON) API:

```json theme={"dark"}
{
  "dimensions": [
    "cube_with_big_numbers.number"
  ],
  "measures": [
    "cube_with_big_numbers.sum"
  ]
}
```

Unsurprisingly, we'll get the following result set in respose:

```json theme={"dark"}
[
  {
    "cube_with_big_numbers.number": "9999999999999999",
    "cube_with_big_numbers.sum": "9999999999999999"
  },
  {
    "cube_with_big_numbers.number": "9007199254740991",
    "cube_with_big_numbers.sum": "9007199254740991"
  },
  {
    "cube_with_big_numbers.number": "123",
    "cube_with_big_numbers.sum": "123"
  }
]
```

You can see that the REST (JSON) API returns numeric measure and dimension values
as strings. While it might counter-intuitive, this is actually by design.

[JavaScript numbers][link-js-numbers] are always stored as double precision
floating point numbers, following the international IEEE 754 standard.
They can only safely represent integers between `–9007199254740991`
and `9007199254740991`, also known as `Number.MIN_SAFE_INTEGER` and
[`Number.MAX_SAFE_INTEGER`][link-mdn-max-safe-integer]. It's also true with
regards to JSON numbers since they are handled by the JavaScript runtime.

That is why the REST (JSON) API returns numeric measure and dimension values as
strings by default. Depending on the nature of your data and domain, you
can decide that numbers are "safe integers" and parse them as instances of
the `Number` type; alternatively, you can parse them as instances of the
`BigInt` type.

JavaScript SDK provides convenient facilities for the case when all numbers
are considered "safe integers". See how to use them below.

## Query via the JavaScript SDK

Let's use [JavaScript SDK][ref-cube-core] to send the same query and print
the result set to the browser console:

```js theme={"dark"}
import cube from "@cubejs-client/core";

const apiUrl = "...";
const apiToken = "...";
const cubeApi = cube(apiToken, { apiUrl });

const query = {
  dimensions: ["cube_with_big_numbers.number"],
  measures: ["cube_with_big_numbers.sum"]
};

// 1. Default format
cubeApi.load(query).then((resultSet) => {
  console.log(resultSet.tablePivot());
});

// 2. Format with castNumerics
cubeApi.load(query, { castNumerics: true }).then((resultSet) => {
  console.log(resultSet.tablePivot());
});
```

In the first case, numeric measure and dimension values will be rendered
as strings:

```js theme={"dark"}
(3) [Object, Object, Object]
  0: Object
    cube_with_big_numbers.number: "9999999999999999"
    cube_with_big_numbers.sum: "9999999999999999"
  1: Object
    cube_with_big_numbers.number: "9007199254740991"
    cube_with_big_numbers.sum: "9007199254740991"
  2: Object
    cube_with_big_numbers.number: "123"
    cube_with_big_numbers.sum: "123"
```

In the second case, when the [`castNumerics`][ref-cube-core-cast-numerics]
flag is set to `true`, numeric values are automatically cast to `number`.
As the result, some numbers consequently loose precision:

```js theme={"dark"}
(3) [Object, Object, Object]
  0: Object
    cube_with_big_numbers.number: 10000000000000000
    cube_with_big_numbers.sum: 10000000000000000
  1: Object
    cube_with_big_numbers.number: 9007199254740991
    cube_with_big_numbers.sum: 9007199254740991
  2: Object
    cube_with_big_numbers.number: 123
    cube_with_big_numbers.sum: 123
```

It is advised to use `castNumerics` only in cases when you're sure that
you work with "safe integers".

[link-js-numbers]: https://www.w3schools.com/js/js_numbers.asp

[link-mdn-max-safe-integer]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER

[ref-cube-core]: /reference/javascript-sdk/reference/cubejs-client-core

[ref-cube-core-cast-numerics]: /reference/javascript-sdk/reference/cubejs-client-core#loadmethodoptions


# Using cloud groups and user attributes with Core Data APIs
Source: https://docs.cube.dev/recipes/core-data-api/cloud-groups-and-user-attributes

Pass Cube Cloud groups and user attributes via JWT when querying Core Data APIs directly, so data access policies work seamlessly.

## Use case

You have [groups][ref-groups] and [user attributes][ref-user-attributes]
configured in Cube Cloud. Now you want to query
[Core Data APIs][ref-core-data-apis] directly (e.g., the SQL API) while
still having your [data access policies][ref-dap] enforced based on those
groups and attributes.

By wrapping groups and user attributes inside the `cubeCloud` property of
your JWT payload, the API request is treated the same as a request from an
authenticated Cube Cloud user.

## Configuration

### JWT payload

Include a `cubeCloud` object in the JWT payload with `groups` and, optionally,
`userAttributes`:

```json theme={"dark"}
{
  "cubeCloud": {
    "groups": ["marketing"],
    "userAttributes": {
      "country": "United States"
    }
  }
}
```

* `groups` is an array of group names the user belongs to.
* `userAttributes` is an object whose keys match the attribute names you
  defined in Cube Cloud.

### Data access policy

In your data model, reference `groups` and `userAttributes` as usual.
Because the `cubeCloud` wrapper maps them automatically, the same policy
works for both Cube Cloud UI users and direct API callers.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders_transactions
      # ...

      access_policy:
        - group: marketing
          row_level:
            filters:
              - member: users_country
                operator: equals
                values: ["{ userAttributes.country }"]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders_transactions`, {
    // ...

    access_policy: [
      {
        group: `marketing`,
        row_level: {
          filters: [
            {
              member: `users_country`,
              operator: `equals`,
              values: [`{ userAttributes.country }`]
            }
          ]
        }
      }
    ]
  })
  ```
</CodeGroup>

## Example

The following Node.js script signs a JWT with `cubeCloud` groups and user
attributes, then queries the SQL API:

```javascript theme={"dark"}
import jwt from "jsonwebtoken";

// ── Configuration ──────────────────────────────────────────────
const CUBE_API_URL = "YOUR_SQL_API_URL";
const CUBE_SECRET = "YOUR_CUBE_API_SECRET";

const JWT_PAYLOAD = {
  cubeCloud: {
    groups: ["marketing"],
    userAttributes: {
      country: "United States"
    }
  }
};

const JWT_OPTIONS = {
  expiresIn: "1d"
};

// ── SQL query ──────────────────────────────────────────────────
const sql = `SELECT DISTINCT
  orders_transactions.users_country
FROM
  orders_transactions
LIMIT 5000`;

// ── Execute ────────────────────────────────────────────────────
const token = jwt.sign(JWT_PAYLOAD, CUBE_SECRET, JWT_OPTIONS);

const res = await fetch(CUBE_API_URL, {
  method: "POST",
  headers: {
    Authorization: token,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ query: sql })
});

if (!res.ok) {
  console.error(`HTTP ${res.status}: ${res.statusText}`);
  console.error(await res.text());
  process.exit(1);
}

const text = await res.text();
const lines = text.trim().split("\n").filter(Boolean);
for (const line of lines) {
  console.log(JSON.stringify(JSON.parse(line), null, 2));
}
```

## Result

Because the JWT contains `cubeCloud.groups: ["marketing"]` and
`cubeCloud.userAttributes.country: "United States"`, the query is filtered
by the `marketing` group's access policy. Only rows matching the user
attribute filter are returned:

```json theme={"dark"}
{
  "data": [
    ["United States"]
  ]
}
```

[ref-groups]: /admin/users-and-permissions/user-groups

[ref-user-attributes]: /admin/users-and-permissions/user-attributes

[ref-core-data-apis]: /reference/core-data-apis

[ref-dap]: /docs/data-modeling/data-access-policies


# Drilldowns
Source: https://docs.cube.dev/recipes/core-data-api/drilldowns

Configure measure drill members in the data model and invoke `ResultSet.drillDown()` to fetch detail rows behind an aggregate.

Drilldowns are a powerful feature to facilitate data exploration. It allows
building an interface to let users dive deeper into visualizations and data
tables. See [`ResultSet.drillDown()`][ref-cube-client-ref-resultset-drilldown]
on how to use this feature on the client side.

A drilldown is defined on the [measure][ref-schema-ref-measures] level in your
data model. It’s defined as a list of dimensions called **drill members**. Once
defined, these drill members will always be used to show underlying data when
drilling into that measure.

Let’s consider the following example of our imaginary e-commerce store. We have
the `orders` cube, which describes orders in our store. It’s connected to
`users` and `products`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      joins:
        - name: users
          relationship: many_to_one
          sql: "{CUBE}.user_id = {users.id}"

        - name: products
          relationship: many_to_one
          sql: "{CUBE}.product_id = {products.id}"

      measures:
        - name: count
          type: count
          # Here we define all possible properties we might want
          # to "drill down" on from our front-end
          drill_members:
            - id
            - status
            - products.name
            - users.city

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true
          public: true

        - name: status
          sql: status
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    joins: {
      users: {
        relationship: `many_to_one`,
        sql: `${CUBE}.user_id = ${users.id}`
      },

      products: {
        relationship: `many_to_one`,
        sql: `${CUBE}.product_id = ${products.id}`
      }
    },

    measures: {
      count: {
        type: `count`,
        // Here we define all possible properties we might want
        // to "drill down" on from our front-end
        drill_members: [id, status, products.name, users.city]
      }
    },

    dimensions: {
      id: {
        type: `number`,
        sql: `id`,
        primary_key: true,
        public: true
      },

      status: {
        type: `string`,
        sql: `status`
      }
    }
  })
  ```
</CodeGroup>

You can follow [this tutorial][blog-drilldown-api] to learn more about building
a UI for drilldowns.

[ref-cube-client-ref-resultset-drilldown]: /reference/javascript-sdk/reference/cubejs-client-core#drilldown

[blog-drilldown-api]: https://cube.dev/blog/introducing-a-drill-down-table-api-in-cubejs/

[ref-schema-ref-measures]: /reference/data-modeling/measures


# Getting unique values for a field
Source: https://docs.cube.dev/recipes/core-data-api/getting-unique-values-for-a-field

Recipe for powering filter dropdowns by querying distinct dimension values from Cube’s data APIs on a users-by-city example.

## Use case

We have a dashboard with information about the users, and we'd like to filter
them by city. To do so, we need to display all unique values for cities in the
dropdown. In the recipe below, we'll learn how to get unique values for
[dimensions](/reference/data-modeling/dimensions).

## Data modeling

To filter users by city, we need to define the appropriate dimension:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      dimensions:
        - name: city
          sql: city
          type: string

        - name: state
          sql: state
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    dimensions: {
      city: {
        sql: `city`,
        type: `string`
      },

      state: {
        sql: `state`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

## Query

It is enough to include only a dimension in the query to get all unique values
of that dimension:

```json theme={"dark"}
{
  "dimensions": ["users.city"]
}
```

## Result

We got the unique values of the `city` dimension, and now we can use them in the
dropdown on the dashboard:

```json theme={"dark"}
[
  {
    "users.city": "Austin"
  },
  {
    "users.city": "Chicago"
  },
  {
    "users.city": "Los Angeles"
  },
  {
    "users.city": "Mountain View"
  }
]
```

## Choosing dimensions

In case we need to choose a dimension or render dropdowns for all dimensions, we
can fetch the list of dimensions for all cubes from the
[`/meta` endpoint](/reference/core-data-apis/rest-api/reference#base_path/v1/meta):

```bash theme={"dark"}
curl http://localhost:4000/cubejs-api/v1/meta
```

```json theme={"dark"}
{
  "cubes": [
    {
      "name": "users",
      "title": "Users",
      "measures": [],
      "dimensions": [
        {
          "name": "users.city",
          "title": "Users City",
          "type": "string",
          "shortTitle": "City",
          "suggestFilterValues": true
        },
        {
          "name": "users.state",
          "title": "Users State",
          "type": "string",
          "shortTitle": "State",
          "suggestFilterValues": true
        }
      ],
      "segments": []
    }
  ]
}
```

Then, we can iterate through dimension names and use any of them in a
[query](#query).

## Source code

Please feel free to check out the
[full source code](https://github.com/cube-js/cube/tree/master/examples/recipes/getting-unique-values-for-a-field)
or run it with the `docker-compose up` command. You'll see the result, including
queried data, in the console.


# Implementing pagination
Source: https://docs.cube.dev/recipes/core-data-api/pagination

Recipe for paged tables over Cube queries using `limit`, `offset`, and deterministic ordering on a sample orders model.

## Use case

We want to display a table of data with hundreds of rows. To make the table
easier to digest and to improve the performance of the query, we'll use
pagination. With the recipe below, we'll get the orders list sorted by the order
number. Every page will have 5 orders.

## Data modeling

We have the following data model:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      measures:
        - name: count
          type: count

      dimensions:
        - name: number
          sql: number
          type: number

        - name: created_at
          sql: created_at
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    measures: {
      count: {
        type: `count`
      }
    },

    dimensions: {
      number: {
        sql: `number`,
        type: `number`
      },

      created_at: {
        sql: `created_at`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

## Query

To select orders that belong to a particular page, we can use the `limit` and
`offset` query properties. First, let's get the number of all orders that we
have.

```json theme={"dark"}
{
  "measures": ["orders.count"]
}
```

Then, let's retrieve first batch (page) of five orders:

```json theme={"dark"}
{
  "dimensions": ["orders.number"],
  "order": {
    "orders.number": "asc"
  },
  "limit": 5
}
```

Now, let's retrieve the second batch (page) of five orders:

```json theme={"dark"}
{
  "dimensions": ["orders.number"],
  "order": {
    "orders.number": "asc"
  },
  "limit": 5,
  "offset": 5
}
```

## Result

We have received five orders per query and can use them as we want.

```javascript theme={"dark"}
// Orders count:

[
  {
    "orders.count": "10000"
  }
]
```

```javascript theme={"dark"}
// The first five orders:

[
  {
    "orders.number": 1
  },
  {
    "orders.number": 2
  },
  {
    "orders.number": 3
  },
  {
    "orders.number": 4
  },
  {
    "orders.number": 5
  }
]
```

```javascript theme={"dark"}
// The next five orders:

[
  {
    "orders.number": 6
  },
  {
    "orders.number": 7
  },
  {
    "orders.number": 8
  },
  {
    "orders.number": 9
  },
  {
    "orders.number": 10
  }
]
```

## Source code

Please feel free to check out the
[full source code](https://github.com/cube-js/cube/tree/master/examples/recipes/pagination)
or run it with the `docker-compose up` command. You'll see the result, including
queried data, in the console.


# Real-Time data fetch in the REST (JSON) API
Source: https://docs.cube.dev/recipes/core-data-api/real-time-data-fetch

Recipe for live-updating dashboards using the REST (JSON) API with WebSocket transport and `@cubejs-client` subscriptions.

## Use case

When building an embedded analytics application, you'd like to provide a real-time
experience to the users. On some page, you'd like to display a chart that updates
as soon as the data changes in the database.

## Configuration

When using the [REST (JSON) API][ref-rest-api], you can use the [WebSocket
transport][ref-websocket-transport] to receive real-time updates. Using this
transport enables subscriptions to real-time updates.

### Client code

JavaScript example:

```javascript theme={"dark"}
import cube from "@cubejs-client/core";
import WebSocketTransport from "@cubejs-client/ws-transport";

const cubeApi = cube({
  transport: new WebSocketTransport({
    authorization: CUBE_TOKEN,
    apiUrl: "ws://localhost:4000/",
  }),
});

// Create a subscription
const subscription = cubeApi.subscribe(
  {
    measures: ["logs.count"],
    timeDimensions: [
      {
        dimension: "logs.time",
        granularity: "hour",
        dateRange: "last 1440 minutes",
      },
    ],
  },
  options,
  (error, resultSet) => {
    if (!error) {
      // handle the update
    }
  }
);

// Later on, unsubscribe from subscription
subscription.unsubscribe();
```

React example:

```javascript theme={"dark"}
import { useCubeQuery } from "@cubejs-client/react";

const Chart = ({ query }) => {
  const { resultSet, error, isLoading } = useCubeQuery(query, {
    // The component will automatically unsubscribe when unmounted
    subscribe: true,
  });

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (error) {
    return <pre>{error.toString()}</pre>;
  }

  if (!resultSet) {
    return null;
  }

  return <LineChart resultSet={resultSet} />;
};
```

### Refresh rate

Real-time data fetch obeys the [`refresh_key`][ref-refresh-key].
In order to provide a desired refresh rate, `refresh_key` should reflect the rate of
change of the underlying data set; the querying time should also be much less than the
desired refresh rate. Please use the [`every`][ref-every] parameter to adjust the
refresh interval.

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-websocket-transport]: /reference/core-data-apis/rest-api#websocket-transport

[ref-refresh-key]: /docs/pre-aggregations#refresh-keys

[ref-every]: /reference/data-modeling/cube#refresh_key


# Implementing custom sorting
Source: https://docs.cube.dev/recipes/core-data-api/sorting

In this recipe, you will learn how to sort the result set of a query by your custom criteria.

## Use case

While [data APIs][ref-data-apis] provide built-in ways to sort the result set by
dimensions and measures in ascending or descending order, sometimes you may need
more flexibility.

For example, if a measure or a dimension contains `NULL` values, they will always
appear last last when sorting in the ascending order. This recipe shows how to
work around this behavior for all data APIs.

<Note>
  Currently, the SQL API does not support `ORDER BY ... NULLS FIRST/LAST`.
  Please [track this issue](https://github.com/cube-js/cube/issues/8464).
</Note>

## Data modeling

Consider the following data model:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: sort_nulls
      sql: |
        SELECT 1234 AS value UNION ALL
        SELECT 5678 AS value UNION ALL
        SELECT NULL AS value

      dimensions:
        - name: value
          sql: value
          type: number

        - name: value_for_sorting
          sql: "COALESCE({value}, 0)"
          type: number
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`sort_nulls`, {
    sql: `
      SELECT 1234 AS value UNION ALL
      SELECT 5678 AS value UNION ALL
      SELECT NULL AS value
    `,

    dimensions: {
      value: {
        sql: `value`,
        type: `number`
      },

      value_for_sorting: {
        sql: `COALESCE(${value}, 0)`,
        type: `number`
      }
    }
  })
  ```
</CodeGroup>

You can see that the `value` dimension contains `NULL` values while the
`value_for_sorting` dimension never has `NULL` values. It means that sorting by
the latter dimension will always strictly follow the ascending or descending
order.

Moreover, note that this additional dimension that acts as a *sorting key* may
reference more than one other dimension, allowing to move your complex sorting
logic from the querying layer to your data model.

## Query

Let's query the `value` dimension and sort the result set by that dimension in
the ascending order:

<CodeGroup>
  ```sql title="SQL" theme={"dark"}
  SELECT value
  FROM sort_nulls
  GROUP BY 1
  ORDER BY 1 ASC;
  ```

  ```json title="JSON" theme={"dark"}
  {
    "dimensions": [
      "sort_nulls.value"
    ],
    "order": {
      "sort_nulls.value": "asc"
    }
  }
  ```
</CodeGroup>

We'll get the following result set:

| value  |
| ------ |
| 1234   |
| 5678   |
| `NULL` |

Now, let's query the `value` dimension but sort the result set by the
`value_for_sorting` dimension in the ascending order:

<CodeGroup>
  ```sql title="SQL" theme={"dark"}
  SELECT value, value_for_sorting
  FROM sort_nulls
  GROUP BY 1, 2
  ORDER BY 2 ASC;
  ```

  ```json title="JSON" theme={"dark"}
  {
    "dimensions": [
      "sort_nulls.value",
      "sort_nulls.value_for_sorting"
    ],
    "order": {
      "sort_nulls.value_for_sorting": "asc"
    }
  }
  ```
</CodeGroup>

We'll get the following result set:

| value  | value\_for\_sorting |
| ------ | ------------------- |
| `NULL` | 0                   |
| 1234   | 1234                |
| 5678   | 5678                |

As you can see, now `NULL` values of the `value` dimension appear first in the
result set.

[ref-queries]: /reference/core-data-apis/queries

[ref-data-apis]: /reference#data-apis


# Daily, Weekly, Monthly Active Users (DAU, WAU, MAU)
Source: https://docs.cube.dev/recipes/data-modeling/active-users

We want to know the customer engagement of our store. To do this, we need to use an Active Users metric.

## Use case

We want to know the customer engagement of our store. To do this, we need to use
an [Active Users metric](https://en.wikipedia.org/wiki/Active_users).

<Note>
  This recipe defines a separate measure for each fixed window (daily, weekly, monthly).
  To let a data consumer choose the window at query time instead, see [Configurable rolling
  windows](/recipes/data-modeling/dynamic-rolling-windows).
</Note>

## Data modeling

Daily, weekly, and monthly active users are commonly referred to as DAU, WAU,
MAU. To get these metrics, we need to use a rolling time frame to calculate a
daily count of how many users interacted with the product or website in the
prior day, 7 days, or 30 days. Also, we can build other metrics on top of these
basic metrics. For example, the WAU to MAU ratio, which we can add by using
already defined `weekly_active_users` and `monthly_active_users`.

To calculate daily, weekly, or monthly active users we’re going to use the
[`rolling_window`](/reference/data-modeling/measures#rolling_window)
measure parameter.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: active_users
      sql: |
        SELECT user_id, created_at FROM public.orders

      measures:
        - name: monthly_active_users
          type: count_distinct
          sql: user_id
          rolling_window:
            trailing: 30 day
            offset: start

        - name: weekly_active_users
          type: count_distinct
          sql: user_id
          rolling_window:
            trailing: 7 day
            offset: start

        - name: daily_active_users
          type: count_distinct
          sql: user_id
          rolling_window:
            trailing: 1 day
            offset: start

        - name: wau_to_mau
          title: WAU to MAU
          type: number
          sql:
            "1.0 * {weekly_active_users} / NULLIF({monthly_active_users}, 0)"
          format: percent

      dimensions:
        - name: created_at
          type: time
          sql: created_at
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`active_users`, {
    sql: `SELECT user_id, created_at
      FROM public.orders`,

    measures: {
      monthly_active_users: {
        sql: `user_id`,
        type: `count_distinct`,
        rolling_window: {
          trailing: `30 day`,
          offset: `start`
        }
      },

      weekly_active_users: {
        sql: `user_id`,
        type: `count_distinct`,
        rolling_window: {
          trailing: `7 day`,
          offset: `start`
        }
      },

      daily_active_users: {
        sql: `user_id`,
        type: `count_distinct`,
        rolling_window: {
          trailing: `1 day`,
          offset: `start`
        }
      },

      wau_to_mau: {
        title: `WAU to MAU`,
        sql: `1.0 * ${weekly_active_users} / NULLIF(${monthly_active_users}, 0)`,
        type: `number`,
        format: `percent`
      }
    },

    dimensions: {
      created_at: {
        sql: `created_at`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

## Result

Query all four measures with a `timeDimensions` date range to get the active
user counts for any given day. For example, for a single day in 2020:

| MAU | WAU | DAU | WAU/MAU |
| --: | --: | --: | ------: |
|  22 |   4 |   0 |  18.18% |


# Calculating average order value
Source: https://docs.cube.dev/recipes/data-modeling/average-order-value

Define AOV as a single measure when its numerator and denominator live in the same cube, or in two fact tables at different grains.

## Use case

Average order value (AOV) — sometimes called basket size — is revenue divided by
the number of orders. It looks like a one-line calculation, but where the two
parts live decides how it is modeled:

* **[Same cube](#same-cube)** — both parts are measures of one fact table.
* **[Two fact tables](#across-two-fact-tables)** — revenue is aggregated at one
  grain (say, day/item/location) and orders are counted at another (transaction
  lines). This is the common shape in retail models.

In both cases AOV is a ratio of two aggregates, so it must be computed *after*
its parts are aggregated — never as a row-level `amount / orders` expression.

## Same cube

When both parts are measures of the same cube, define AOV as a calculated
measure that divides them:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

      measures:
        - name: revenue
          sql: amount
          type: sum
          format: currency

        - name: count
          type: count

        - name: average_order_value
          sql: "{revenue} / NULLIF({count}, 0)"
          type: number
          format: currency
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    dimensions: {
      id: { sql: `id`, type: `number`, primary_key: true }
    },

    measures: {
      revenue: { sql: `amount`, type: `sum`, format: `currency` },
      count: { type: `count` },

      average_order_value: {
        sql: `${revenue} / NULLIF(${count}, 0)`,
        type: `number`,
        format: `currency`
      }
    }
  })
  ```
</CodeGroup>

`NULLIF` guards the division so a group with no orders returns `NULL` rather
than failing.

## Across two fact tables

Retail models usually split the two parts. Sales dollars come from a
pre-aggregated daily table (`item_location_sales`, one row per day, item and
location), while the transaction count comes from the line-item table
(`sales_line_item`, one row per transaction line). The two never join to each
other — they meet through shared `items`, `locations` and `dates` cubes, which
makes this a [multi-fact query][ref-multi-fact-views].

<Warning>
  Multi-fact views and multi-stage measures are powered by Tesseract, the
  [next-generation data modeling engine][link-tesseract]. In versions before
  v1.7.0, it was not enabled by default.
</Warning>

### 1. Define each part on the cube that owns it

The denominator counts distinct transactions and excludes exchanges and
non-store channels. Write that logic once, as measure
[`filters`][ref-measure-filters] on the line-item cube, so every consumer picks
it up by including the measure — never restate it per view:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: sales_line_item
      sql_table: sales_line_item

      joins:
        - name: items
          sql: "{CUBE}.item_id = {items.id}"
          relationship: many_to_one
        - name: locations
          sql: "{CUBE}.location_id = {locations.id}"
          relationship: many_to_one
        - name: dates
          sql: "DATE_TRUNC('day', {CUBE}.sold_at) = {dates.date}"
          relationship: many_to_one

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

      measures:
        - name: transactions_without_returns
          sql: transaction_id
          type: count_distinct
          filters:
            - sql: "{CUBE}.transaction_type <> 'EXCHANGE'"
            - sql: "{CUBE}.fulfillment_channel_group IN ('IN_STORE', 'SHIP_FROM_STORE')"

    - name: item_location_sales
      sql_table: item_location_sales

      joins:
        - name: items
          sql: "{CUBE}.item_id = {items.id}"
          relationship: many_to_one
        - name: locations
          sql: "{CUBE}.location_id = {locations.id}"
          relationship: many_to_one
        - name: dates
          sql: "DATE_TRUNC('day', {CUBE}.date) = {dates.date}"
          relationship: many_to_one

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

      measures:
        - name: sales_amount
          sql: sales_amount
          type: sum
          format: currency
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`sales_line_item`, {
    sql_table: `sales_line_item`,

    joins: {
      items: {
        sql: `${CUBE}.item_id = ${items.id}`,
        relationship: `many_to_one`
      },
      locations: {
        sql: `${CUBE}.location_id = ${locations.id}`,
        relationship: `many_to_one`
      },
      dates: {
        sql: `DATE_TRUNC('day', ${CUBE}.sold_at) = ${dates.date}`,
        relationship: `many_to_one`
      }
    },

    dimensions: {
      id: { sql: `id`, type: `number`, primary_key: true }
    },

    measures: {
      transactions_without_returns: {
        sql: `transaction_id`,
        type: `count_distinct`,
        filters: [
          { sql: `${CUBE}.transaction_type <> 'EXCHANGE'` },
          { sql: `${CUBE}.fulfillment_channel_group IN ('IN_STORE', 'SHIP_FROM_STORE')` }
        ]
      }
    }
  })

  cube(`item_location_sales`, {
    sql_table: `item_location_sales`,

    joins: {
      items: {
        sql: `${CUBE}.item_id = ${items.id}`,
        relationship: `many_to_one`
      },
      locations: {
        sql: `${CUBE}.location_id = ${locations.id}`,
        relationship: `many_to_one`
      },
      dates: {
        sql: `DATE_TRUNC('day', ${CUBE}.date) = ${dates.date}`,
        relationship: `many_to_one`
      }
    },

    dimensions: {
      id: { sql: `id`, type: `number`, primary_key: true }
    },

    measures: {
      sales_amount: { sql: `sales_amount`, type: `sum`, format: `currency` }
    }
  })
  ```
</CodeGroup>

Both facts join to the same `items`, `locations` and `dates` cubes. The `dates`
spine matters: without it the two facts have no common time member to group by,
since one is keyed by day and the other by timestamp.

### 2. Define AOV on the view

AOV can live on the view or on either cube — see [where to put
it](#where-to-put-the-measure) below. On the view it is a [measure of the
view][ref-view-measures], marked [`multi_stage`][ref-multi-stage]:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: retail_analysis
      cubes:
        - join_path: item_location_sales
          includes:
            - sales_amount
        - join_path: sales_line_item
          includes:
            - transactions_without_returns
        - join_path: dates
          includes:
            - date
        - join_path: items
          includes:
            - department
        - join_path: locations
          includes:
            - region

      measures:
        - name: aov_basket
          type: number
          format: currency
          multi_stage: true
          sql: "{CUBE.sales_amount} / NULLIF({CUBE.transactions_without_returns}, 0)"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`retail_analysis`, {
    cubes: [
      {
        join_path: item_location_sales,
        includes: [`sales_amount`]
      },
      {
        join_path: sales_line_item,
        includes: [`transactions_without_returns`]
      },
      {
        join_path: dates,
        includes: [`date`]
      },
      {
        join_path: items,
        includes: [`department`]
      },
      {
        join_path: locations,
        includes: [`region`]
      }
    ],

    measures: {
      aov_basket: {
        type: `number`,
        format: `currency`,
        multi_stage: true,
        sql: `${CUBE.sales_amount} / NULLIF(${CUBE.transactions_without_returns}, 0)`
      }
    }
  })
  ```
</CodeGroup>

The shared dimension cubes sit at root-level join paths, so `date`, `department`
and `region` are common to both facts and can be grouped by.

### 3. Query it

Querying `aov_basket` by `region` aggregates each fact on its own, stitches the
two results on the shared dimension, and takes the division over the joined rows:

```sql theme={"dark"}
-- one aggregating subquery per fact, at the query's grain
SUM(item_location_sales.sales_amount)                GROUP BY region
COUNT(DISTINCT CASE WHEN … THEN transaction_id END)  GROUP BY region
-- final stage, once the two are joined on region
sales_amount / NULLIF(transactions_without_returns, 0)
```

The measure filters travel into the line-item subquery, so the exchange and
channel rules are applied exactly where they were defined.

<Note>
  `multi_stage: true` is what defers the division until both facts have been
  aggregated. Without it, Cube plans the expression as an ordinary calculated
  measure, looks for a single join tree covering both fact cubes, and fails with
  `Can't find join path to join 'locations', 'item_location_sales',
    'sales_line_item'`.
</Note>

## Where to put the measure

A metric spanning two facts does not have to live on a view. A cube measure may
reference another cube's measure, which makes it derived rather than owned by
its cube — the same property a view measure has — so AOV can sit on either fact
cube instead:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: sales_line_item
      # …

      measures:
        - name: transactions_without_returns
          sql: transaction_id
          type: count_distinct
          filters:
            - sql: "{CUBE}.transaction_type <> 'EXCHANGE'"
            - sql: "{CUBE}.fulfillment_channel_group IN ('IN_STORE', 'SHIP_FROM_STORE')"

        - name: aov_basket
          type: number
          format: currency
          multi_stage: true
          sql: "{item_location_sales.sales_amount} / NULLIF({CUBE.transactions_without_returns}, 0)"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`sales_line_item`, {
    // …

    measures: {
      transactions_without_returns: {
        sql: `transaction_id`,
        type: `count_distinct`,
        filters: [
          { sql: `${CUBE}.transaction_type <> 'EXCHANGE'` },
          { sql: `${CUBE}.fulfillment_channel_group IN ('IN_STORE', 'SHIP_FROM_STORE')` }
        ]
      },

      aov_basket: {
        type: `number`,
        format: `currency`,
        multi_stage: true,
        sql: `${item_location_sales.sales_amount} / NULLIF(${CUBE.transactions_without_returns}, 0)`
      }
    }
  })
  ```
</CodeGroup>

Both placements plan identically — the same per-fact subqueries, stitched the
same way, divided in the same final stage — and `multi_stage` is required either
way. What differs is reuse and coupling:

|            | On a cube                                     | On a view                            |
| ---------- | --------------------------------------------- | ------------------------------------ |
| Reuse      | Defined once; every view including it gets it | Redefined in each view that needs it |
| Coupling   | The cube names the other cube's measure       | The cubes stay unaware of each other |
| Query path | Available as `sales_line_item.aov_basket` too | Only through the view                |

Prefer the cube when the metric is part of the model that several views expose —
it keeps [shared logic in cubes][ref-views-shared-logic]. Prefer the view when
the pairing is a presentation choice for one audience, or when the cubes belong
to different domains and you would rather not have one reference the other.

A cube-owned measure reaches the other fact whether or not the view naming it
also includes that fact, so a view can expose AOV without exposing
`sales_amount`.

[ref-multi-fact-views]: /docs/data-modeling/multi-fact-views

[ref-multi-stage]: /reference/data-modeling/measures#multi_stage

[ref-measure-filters]: /reference/data-modeling/measures#filters

[ref-view-measures]: /reference/data-modeling/view#measures

[ref-views-shared-logic]: /docs/data-modeling/views#keep-shared-logic-in-cubes

[link-tesseract]: https://cube.dev/blog/introducing-tesseract


# Implementing retention analysis & cohorts
Source: https://docs.cube.dev/recipes/data-modeling/cohort-retention

This is an advanced topic that assumes good, pre-existing knowledge of SQL and Cube.

Whether you’re selling groceries, financial services, or gym memberships,
successful recruitment of new customers is only truly successful if they return
to buy from you again. The metric that reflects this is called **retention**,
and the approach we use is **customer retention analysis**. Retention analysis
is typically done using **cohort analysis**.

Cohort analysis is a technique to see how variables change over in different
groups with different starting conditions. Retention is a simplified one, where
the **starting condition is usually the time of signup and the variable is
simply activity**.

It’s usually visualized as a cohort grid or retention curves.

<div>
  <img />
</div>

Cohort retention analysis is pretty hard to do in SQL. **We need to have the
user-date combination**, which tells us about a user’s activity on that date,
including dates with no activity. To do this, we need to make a tricky join,
which gives us a dates list. Once we have it, we can “fill it” with users’
activities.

The example below shows monthly cohort retention. The same technique can be used
for daily or weekly retention.

<Info>
  The SQL code in this guide is Postgres-compliant. The final SQL code may be
  different depending on your database. Also, this technique requires at least 1
  user to be active during the month, otherwise this month will not be included in
  the months' list.
</Info>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: monthly_retention
      sql: |
        SELECT
          users.id as user_id,
          date_trunc('month', users.created_at) as signup_month,
          months_list.activity_month as activity_month,
          data.monthly_pageviews
        FROM users LEFT JOIN (
          SELECT
            DISTINCT (date_trunc('month', pages.original_timestamp)) as
        activity_month
          FROM pages
        ) as months_list ON months_list.activity_month >= date_trunc('month',
        users.created_at) LEFT JOIN (
          SELECT
            p.user_id,
            date_trunc('month', p.original_timestamp) as activity_month,
            COUNT(DISTINCT p.id) as monthly_pageviews
          FROM pages p
          GROUP BY 1,2
        ) as data ON data.activity_month = months_list.activity_month AND
        data.user_id = users.id
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`monthly_retention`, {
    sql: `SELECT
      users.id as user_id,
      date_trunc('month', users.created_at) as signup_month,
      months_list.activity_month as activity_month,
      data.monthly_pageviews
    FROM users
    LEFT JOIN
      (
        SELECT
          DISTINCT (date_trunc('month', pages.original_timestamp)) as activity_month
        FROM pages
      ) as months_list
    ON months_list.activity_month >= date_trunc('month', users.created_at)
    LEFT JOIN
      (
        SELECT
          p.user_id,
          date_trunc('month', p.original_timestamp) as activity_month,
          COUNT(DISTINCT p.id) as monthly_pageviews
        FROM pages p
        GROUP BY 1,2
      ) as data
    ON data.activity_month = months_list.activity_month
    AND data.user_id = users.id`
  })
  ```
</CodeGroup>

The SQL above provides the base table for our retention cube. It would show
signup months and activity months with pageviews:

| user\_id | signup\_month | activity\_month | monthly\_pageviews |
| -------- | ------------- | --------------- | ------------------ |
| 1        | 1/18          | 1/18            | 10                 |
| 1        | 1/18          | 2/18            | 5                  |
| 1        | 1/18          | 3/18            | 0                  |
| 2        | 2/18          | 2/18            | 12                 |
| 2        | 2/18          | 3/18            | 0                  |
| 3        | 3/18          | 3/18            | 5                  |

Now we can calculate a total count of users and the total count of active users,
who has more than 0 page views, for every month. Based on these two measures we
can calculate monthly `percentage_of_active`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: monthly_retention
      # ...
      measures:
        - name: total_count
          sql: user_id
          type: count_distinct
          public: false

        - name: total_active_count
          sql: user_id
          type: count_distinct
          filters:
            - sql: monthly_pageviews > 0
          drill_members:
            - users.id
            - users.email

        - name: percentage_of_active
          sql: "1.0 * {total_active_count} / NULLIF({total_count}, 0)"
          type: number
          format: percent
          drill_members:
            - users.email
            - bots.team
            - bots.last_seen
            - percentage_of_active
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`monthly_retention`, {
    // ...

    measures: {
      total_count: {
        sql: `user_id`,
        type: `count_distinct`,
        public: false
      },

      total_active_count: {
        sql: `user_id`,
        type: `count_distinct`,
        filters: [{ sql: `${CUBE}.monthly_pageviews > 0` }],
        drill_members: [users.id, users.email]
      },

      percentage_of_active: {
        sql: `1.0 * ${total_active_count} / NULLIF(${total_count}, 0)`,
        type: `number`,
        format: `percent`,
        drill_members: [
          users.email,
          bots.team,
          bots.last_seen,
          percentage_of_active
        ]
      }
    }
  })
  ```
</CodeGroup>

To be able to build cohorts, we need to group by two dimensions: **signup
date**, which will define our cohorts, and **months since signup**, which will
show how the percentage of active users is changing.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: monthly_retention
      # ...
      dimensions:
        - name: months_since_signup
          sql: "DATEDIFF('month', signup_month, activity_month)"
          type: number

        - name: signup_date
          sql: "(signup_month AT TIME ZONE 'America/Los_Angeles')"
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`monthly_retention`, {
    // ...

    dimensions: {
      months_since_signup: {
        sql: `DATEDIFF('month', ${CUBE}.signup_month, ${CUBE}.activity_month)`,
        type: `number`
      },

      signup_date: {
        sql: `(signup_month AT TIME ZONE 'America/Los_Angeles')`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

<Info>
  Note, we are explicitly setting the `signup_month` timezone. `date_trunc`
  returns UTC dates and not setting a correct timezone would lead to wrong results
  due to time shift.
</Info>


# Querying across data sources
Source: https://docs.cube.dev/recipes/data-modeling/cross-data-source-queries

Append rows from cubes that live in different databases into one result set with a UNION ALL query through the SQL API.

## Use case

Some datasets are spread across more than one database. Product events, for
example, are often split by age: the last few months stay in a fast analytical
database that serves live dashboards, while everything older is moved to
cheaper storage. Both tables describe the same events and carry the same
columns.

The goal is to report on them together — one result set with the rows of both
databases appended, plus a dimension that says which database each row came
from.

This is a *union*: it adds rows. It is a different problem from a
[`rollup_join`](/reference/data-modeling/pre-aggregations#rollup_join), which
adds columns by relating entities that live in different databases. It is also
different from [data blending](/docs/data-modeling/concepts/data-blending),
which unions cubes inside a single database.

The [SQL API](/reference/core-data-apis/sql-api) can do this at query time,
against live data and without pre-aggregations. Each cube is queried on its own
data source, and Cube appends the results.

## Configuration

Define the two connections as [multiple data
sources](/admin/connect-to-data/multiple-data-sources). The default source needs
no name; every other source gets one, and the full list goes in
`CUBEJS_DATASOURCES`:

```dotenv theme={"dark"}
CUBEJS_DATASOURCES=default,recent

CUBEJS_DB_TYPE=postgres
CUBEJS_DB_HOST=archive.example.com
CUBEJS_DB_NAME=analytics
# ...

CUBEJS_DS_RECENT_DB_TYPE=clickhouse
CUBEJS_DS_RECENT_DB_HOST=clickhouse.example.com
CUBEJS_DS_RECENT_DB_NAME=analytics
# ...
```

## Data modeling

Model each table as its own cube, and point one of them at the named data source
with [`data_source`](/reference/data-modeling/cube#data_source). The cube without
a `data_source` uses the default one.

Give both cubes a matching set of members, and add a constant dimension that
identifies the origin of each row. That dimension is what makes the two halves
of the union distinguishable once they sit in the same result set:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: archived_events
      sql_table: events

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: created_at
          sql: created_at
          type: time

        - name: tier
          sql: tier
          type: string

        - name: storage
          sql: "'archive'"
          type: string

      measures:
        - name: event_count
          type: count

    - name: recent_events
      sql_table: events
      data_source: recent

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: created_at
          sql: created_at
          type: time

        - name: tier
          sql: tier
          type: string

        - name: storage
          sql: "'recent'"
          type: string

      measures:
        - name: event_count
          type: count
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`archived_events`, {
    sql_table: `events`,

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      },

      created_at: {
        sql: `created_at`,
        type: `time`
      },

      tier: {
        sql: `tier`,
        type: `string`
      },

      storage: {
        sql: `'archive'`,
        type: `string`
      }
    },

    measures: {
      event_count: {
        type: `count`
      }
    }
  })

  cube(`recent_events`, {
    sql_table: `events`,
    data_source: `recent`,

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      },

      created_at: {
        sql: `created_at`,
        type: `time`
      },

      tier: {
        sql: `tier`,
        type: `string`
      },

      storage: {
        sql: `'recent'`,
        type: `string`
      }
    },

    measures: {
      event_count: {
        type: `count`
      }
    }
  })
  ```
</CodeGroup>

## Querying

Connect to the [SQL API](/reference/core-data-apis/sql-api) and append the two
cubes with `UNION ALL`:

```sql theme={"dark"}
SELECT storage, tier, MEASURE(event_count) AS events
FROM archived_events
GROUP BY 1, 2
UNION ALL
SELECT storage, tier, MEASURE(event_count) AS events
FROM recent_events
GROUP BY 1, 2
```

```
 storage |    tier    | events
---------+------------+--------
 archive | free       | 412508
 archive | enterprise |  95012
 recent  | free       |  38471
 recent  | enterprise |   9930
```

Each half of the union is evaluated against its own database, in that database's
own dialect, and Cube appends the two results. Filters reach the databases
rather than being applied afterwards, so a `WHERE` clause on either side limits
what that database scans:

```sql theme={"dark"}
SELECT storage, tier, MEASURE(event_count) AS events
FROM archived_events
WHERE tier = 'enterprise'
GROUP BY 1, 2
UNION ALL
SELECT storage, tier, MEASURE(event_count) AS events
FROM recent_events
WHERE tier = 'enterprise'
GROUP BY 1, 2
```

Add a time dimension to both halves to line the databases up on a common grain:

```sql theme={"dark"}
SELECT storage, tier, DATE_TRUNC('day', created_at) AS date, MEASURE(event_count) AS events
FROM archived_events
GROUP BY 1, 2, 3
UNION ALL
SELECT storage, tier, DATE_TRUNC('day', created_at) AS date, MEASURE(event_count) AS events
FROM recent_events
GROUP BY 1, 2, 3
ORDER BY 3, 1
```

<Note>
  A cube whose name starts with `pg_` cannot be referenced by that name alone. The
  SQL API routes such a name to `pg_catalog`, where no cube is ever found, and the
  query fails with `Table or CTE with name 'pg_...' not found`. Qualify it with the
  schema that holds cubes, as in `FROM public.pg_costs`, or avoid the prefix.
</Note>

### Aggregating across the union

Wrap the union in a CTE to aggregate over both databases at once. Here the
per-tier totals combine events from both databases:

```sql theme={"dark"}
WITH blended AS (
  SELECT storage, tier, MEASURE(event_count) AS events
  FROM archived_events
  GROUP BY 1, 2
  UNION ALL
  SELECT storage, tier, MEASURE(event_count) AS events
  FROM recent_events
  GROUP BY 1, 2
)
SELECT tier, SUM(events) AS total, COUNT(DISTINCT storage) AS databases
FROM blended
GROUP BY 1
ORDER BY 2 DESC
```

```
    tier    | total  | databases
------------+--------+-----------
 free       | 450979 |         2
 enterprise | 104942 |         2
```

`UNION` also works where duplicate rows should collapse, as do an outer
`ORDER BY` and `LIMIT` over the union.

<Warning>
  Aggregating over the union like this is only correct for additive measures such
  as `count` and `sum`. Non-additive measures — `count_distinct`, `avg`,
  percentiles — cannot be combined from per-source results: summing distinct
  counts double-counts anything present in both databases, and averaging averages
  ignores how many rows each database contributed. No error is raised, so report
  these measures per data source instead.
</Warning>

### Inspecting how a query is split

Run `EXPLAIN` on any of these queries to see the plan. It puts a `Union` over one
`CubeScan` per cube, and each scan carries its own filter — the `WHERE` clause is
part of the request sent for that cube, not a step applied after the results are
appended:

```sql theme={"dark"}
EXPLAIN SELECT storage, tier, MEASURE(event_count) AS events
FROM archived_events
WHERE tier = 'enterprise'
GROUP BY 1, 2
UNION ALL
SELECT storage, tier, MEASURE(event_count) AS events
FROM recent_events
WHERE tier = 'enterprise'
GROUP BY 1, 2
```

```
Union
  CubeScan: request={
  "measures": [
    "archived_events.event_count"
  ],
  "dimensions": [
    "archived_events.storage",
    "archived_events.tier"
  ],
  "segments": [],
  "order": [],
  "filters": [
    {
      "member": "archived_events.tier",
      "operator": "equals",
      "values": [
        "enterprise"
      ]
    }
  ]
}
  CubeScan: request={
  "measures": [
    "recent_events.event_count"
  ],
  "dimensions": [
    "recent_events.storage",
    "recent_events.tier"
  ],
  "segments": [],
  "order": [],
  "filters": [
    {
      "member": "recent_events.tier",
      "operator": "equals",
      "values": [
        "enterprise"
      ]
    }
  ]
}
```

The plan identifies each scan by cube, not by data source, so read it together
with the `data_source` of each cube to see which database serves which half.

## Limitations

Unions combine rows across data sources; joins do not. A query that joins two
cubes on different data sources is rejected, and relating entities across
databases needs a
[`rollup_join`](/reference/data-modeling/pre-aggregations#rollup_join) instead.

Each half of the union is subject to the [maximum row
limit](/docs/data-modeling/configuration#maximum-row-limit) on its own, and the
cap applies before the results are appended. Aggregate inside each half of the
union, as in the examples above, rather than unioning raw rows and aggregating
afterwards.


# Implementing custom calendars
Source: https://docs.cube.dev/recipes/data-modeling/custom-calendar

Map fact tables to irregular retail or fiscal calendars—illustrated with the 4-5-4 pattern—using dedicated calendar cubes and proxy dimensions.

This recipe explains the implementation of the [4-5-4 calendar][link-454], a common
retail calendar used in the US and Canada. However, the same approach can be used
to implement other custom calendars.

Unlike [custom time dimension granularities][ref-custom-granularities], custom
calendars provide more flexibility and can be used when time units have variable
lengths, such as the months and quarters in the 4-5-4 calendar. See the [custom
granularities recipe][ref-custom-granularities-recipe] for more information.

## Use case

The 4-5-4 calendar ensures sales comparability between years by dividing the year
into months based on a 4 weeks – 5 weeks – 4 weeks format. The layout of the calendar
lines up holidays and ensures the same number of Saturdays and Sundays in comparable
months. Hence, like days are compared to like days for sales reporting purposes.

## Data modeling

The data modeling includes the following steps:

* Create a calendar cube, e.g., `calendar_454`.
* Extend it a number of times, so there's one calendar cube for every time dimension
  in cubes with facts that needs translation to a custom calendar.
* Define joins from your cubes with facts to those calendar cubes, e.g., `base_orders`,
  and bring relevant calendar attributes as [proxy dimensions][ref-proxy-dimensions].

The last two steps require a few lines of code but it can totally be optimized with
a [Jinja macro][ref-jinja-macro] if needed.

### Calendar table

Consider the following calendar cube. It was generated using a large language model
(LLM) and then tested against the [official calendar][link-454-official-calendar].
In this example, it's generated on the fly, however, in production, it should be
materialized as a table using a data transformation tool:

```yaml theme={"dark"}
cubes:
  - name: calendar_454
    public: false
    sql: |
      WITH RECURSIVE fiscal_weeks AS (
          -- Step 1: Define the start of the fiscal years (Sunday closest to Feb 1st)
          SELECT 
              year AS fiscal_year, 
              CASE 
                  WHEN strftime('%w', date_trunc('week', make_date(year, 2, 1)))::INTEGER <= 3 
                  THEN date_trunc('week', make_date(year, 2, 1)) + INTERVAL 6 DAY 
                  ELSE date_trunc('week', make_date(year, 2, 1) + INTERVAL 7 DAY) + INTERVAL 7 DAY
              END AS week_start,
              1 AS week_number,
              1 AS month_number,
              1 AS month_week_count
          FROM range(2015, 2031) t(year)
          
          UNION ALL
          
          -- Step 2: Generate weeks recursively following the 4-5-4 pattern
          SELECT 
              fiscal_year,
              week_start + INTERVAL 7 DAY AS week_start,
              week_number + 1,
              CASE 
                  WHEN month_number = 12 AND ((month_week_count = 4 AND month_number % 3 = 1) OR 
                                              (month_week_count = 5 AND month_number % 3 = 2) OR 
                                              (month_week_count = 4 AND month_number % 3 = 0)) 
                  THEN 1 
                  WHEN month_week_count = 4 AND (month_number % 3 = 1) THEN month_number + 1
                  WHEN month_week_count = 5 AND (month_number % 3 = 2) THEN month_number + 1
                  WHEN month_week_count = 4 AND (month_number % 3 = 0) THEN month_number + 1
                  ELSE month_number
              END AS month_number,
              CASE 
                  WHEN month_week_count = 4 AND (month_number % 3 = 1) THEN 1
                  WHEN month_week_count = 5 AND (month_number % 3 = 2) THEN 1
                  WHEN month_week_count = 4 AND (month_number % 3 = 0) THEN 1
                  ELSE month_week_count + 1
              END AS month_week_count
          FROM fiscal_weeks
          WHERE week_number < 52 OR (week_number = 52 AND (fiscal_year % 5 = 2)) -- Account for 53rd week
      )

      SELECT 
          fiscal_year,
          week_number,
          month_number,
          make_timestamp(fiscal_year, month_number, 1, 0, 0, 0) AS fiscal_month_date,
          week_start AS week_start_date,
          make_timestamp(year(week_start + INTERVAL 6 DAY), 
              month(week_start + INTERVAL 6 DAY), 
              day(week_start + INTERVAL 6 DAY), 
              23, 59, 59.999) AS week_end_date
      FROM fiscal_weeks
      ORDER BY fiscal_year, week_number

    dimensions:
      - name: retail_year
        sql: fiscal_year
        type: number

      - name: week_number
        sql: week_number
        type: number

      - name: month_number
        sql: month_number
        type: number

      - name: retail_month_date
        sql: fiscal_month_date
        type: time

      - name: week_start_date
        sql: week_start_date
        type: time

      - name: week_end_date
        sql: week_end_date
        type: time
```

As you can see, this cube defines `week_start_date` and `week_end_date` time dimensions
as the start and end dates of the retail week. They can be used to join this cube to
cubes with facts.

### Auxiliary calendar cubes

We will also extend the `calendar_454` cube to create auxiliary calendar cubes for
three time dimensions that we'd like to translate to the 4-5-4 calendar:

```yaml theme={"dark"}
cubes:
  - name: calendar_454__base_orders__created_at
    extends: calendar_454

  - name: calendar_454__base_orders__completed_at
    extends: calendar_454
```

### Cubes with facts

Finally, we define joins from the `base_orders` cube to the auxiliary calendar cubes.
We also bring the `week_number` and `month_number` attributes as proxy dimensions:

```yaml theme={"dark"}
cubes:
  - name: base_orders
    sql: SELECT * FROM 's3://cube-tutorial/orders.csv'

    joins:
      # BEGIN — Joins to calendar tables
      - name: calendar_454__base_orders__created_at
        sql: "{CUBE.created_at} BETWEEN {calendar_454__base_orders__created_at.week_start_date} AND {calendar_454__base_orders__created_at.week_end_date}"
        relationship: many_to_one

      - name: calendar_454__base_orders__completed_at
        sql: "{CUBE.completed_at} BETWEEN {calendar_454__base_orders__completed_at.week_start_date} AND {calendar_454__base_orders__completed_at.week_end_date}"
        relationship: many_to_one
      # END — Joins to calendar tables

    dimensions:
      - name: id
        sql: id
        type: number
        primary_key: true

      - name: status
        sql: status
        type: string

      # BEGIN — Regular time dimension + ones derived from calendar table
      - name: created_at
        sql: "{CUBE}.created_at::TIMESTAMP"
        type: time

      - name: created_at_retail_month
        sql: "{calendar_454__base_orders__created_at.retail_month_date}"
        type: time

      - name: created_at_retail_week
        sql: "{calendar_454__base_orders__created_at.week_number}"
        type: number

      - name: completed_at
        sql: "{CUBE}.completed_at::TIMESTAMP"
        type: time

      - name: completed_at_retail_month
        sql: "{calendar_454__base_orders__completed_at.retail_month_date}"
        type: time

      - name: completed_at_retail_week
        sql: "{calendar_454__base_orders__completed_at.week_number}"
        type: number
      # END — Regular time dimension + ones derived from calendar table

    measures:
      - name: count
        type: count

      - name: completed_count
        type: count
        filters:
          - sql: "{CUBE}.status = 'completed'"
```

[link-454]: https://nrf.com/resources/4-5-4-calendar

[link-454-official-calendar]: https://2fb5c46100c1b71985e2-011e70369171d43105aff38e48482379.ssl.cf1.rackcdn.com/4-5-4%20calendar/3-Year-Calendar-5-27.pdf

[ref-custom-granularities]: /reference/data-modeling/dimensions#granularities

[ref-custom-granularities-recipe]: /recipes/data-modeling/custom-granularity

[ref-proxy-dimensions]: /docs/data-modeling/dimensions#proxy-dimensions

[ref-jinja-macro]: /docs/data-modeling/dynamic/jinja#macros


# Implementing custom time dimension granularities
Source: https://docs.cube.dev/recipes/data-modeling/custom-granularity

This recipe shows examples of commonly used custom granularities.

## Use case

Sometimes, you might need to group the result set by units of time that are
different from [default granularities][ref-default-granularities] such as `week`
(starting on Monday) or `year` (starting on January 1).

Below, we explore the following examples of custom granularities:

* *Week starting on Sunday*, commonly used in the US and some other countries. A
  *fiscal week* that starts on any other day is defined the same way.
* *[Fiscal year][wiki-fiscal-year]* and *fiscal quarter*, commonly used in
  accounting and financial reporting.

## Data modeling

Consider the following data model. `interval` and `offset` parameters are used to
configure each custom granularity in `granularities`.

`interval` is the only way to define a granularity under a name of your own, and it
places the granularity in the `day` → `week` → `month` → `quarter` → `year` hierarchy,
so Cube derives it arithmetically and rolls it up with the units around it. In exchange,
the period has to be a fixed length. A period that varies in length, such as a month of
a 4-5-4 retail calendar, is read from a pre-calculated column instead — see [overriding
granularities][ref-calendar-cubes] and the [custom calendar
recipe][ref-recipe-custom-calendar].

Note that each custom granularity is also exposed via a [proxy
dimension][ref-proxy-granularity]. This is not just a convenience: while the
[REST API][ref-rest-api] can query custom granularities by name, the [SQL
API][ref-sql-api] and the [GraphQL API][ref-graphql-api] can only address the
default granularities, so a proxy dimension is the way to query a custom
granularity from those APIs or from a BI tool. Proxy dimensions can also be used
in further calculations, like rendering `fiscal_quarter_label` below.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: custom_granularities
      sql: |
        SELECT '2024-01-15'::TIMESTAMP AS timestamp UNION ALL
        SELECT '2024-02-15'::TIMESTAMP AS timestamp UNION ALL
        SELECT '2024-03-15'::TIMESTAMP AS timestamp UNION ALL
        SELECT '2024-04-15'::TIMESTAMP AS timestamp UNION ALL
        SELECT '2024-05-15'::TIMESTAMP AS timestamp UNION ALL
        SELECT '2024-06-15'::TIMESTAMP AS timestamp UNION ALL
        SELECT '2024-07-15'::TIMESTAMP AS timestamp UNION ALL
        SELECT '2024-08-15'::TIMESTAMP AS timestamp UNION ALL
        SELECT '2024-09-15'::TIMESTAMP AS timestamp UNION ALL
        SELECT '2024-10-15'::TIMESTAMP AS timestamp UNION ALL
        SELECT '2024-11-15'::TIMESTAMP AS timestamp UNION ALL
        SELECT '2024-12-15'::TIMESTAMP AS timestamp

      dimensions:
        - name: timestamp
          sql: timestamp
          type: time

          granularities:
            - name: sunday_week
              interval: 1 week
              offset: -1 day

            - name: fiscal_year
              title: Federal fiscal year in the United States
              interval: 1 year
              offset: -3 months

            - name: fiscal_quarter
              title: Federal fiscal quarter in the United States
              interval: 1 quarter
              offset: -3 months
        
        - name: sunday_week
          sql: "{timestamp.sunday_week}"
          type: time
        
        - name: fiscal_year
          sql: "{timestamp.fiscal_year}"
          type: time
        
        - name: fiscal_quarter
          sql: "{timestamp.fiscal_quarter}"
          type: time

        - name: fiscal_quarter_label
          sql: |
            'FY' || (EXTRACT(YEAR FROM {timestamp.fiscal_year}) + 1) ||
            '-Q' || EXTRACT(QUARTER FROM {timestamp.fiscal_quarter} + INTERVAL '3 MONTHS')
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`custom_granularities`, {
    sql: `
      SELECT '2024-01-15'::TIMESTAMP AS timestamp UNION ALL
      SELECT '2024-02-15'::TIMESTAMP AS timestamp UNION ALL
      SELECT '2024-03-15'::TIMESTAMP AS timestamp UNION ALL
      SELECT '2024-04-15'::TIMESTAMP AS timestamp UNION ALL
      SELECT '2024-05-15'::TIMESTAMP AS timestamp UNION ALL
      SELECT '2024-06-15'::TIMESTAMP AS timestamp UNION ALL
      SELECT '2024-07-15'::TIMESTAMP AS timestamp UNION ALL
      SELECT '2024-08-15'::TIMESTAMP AS timestamp UNION ALL
      SELECT '2024-09-15'::TIMESTAMP AS timestamp UNION ALL
      SELECT '2024-10-15'::TIMESTAMP AS timestamp UNION ALL
      SELECT '2024-11-15'::TIMESTAMP AS timestamp UNION ALL
      SELECT '2024-12-15'::TIMESTAMP AS timestamp
    `,

    dimensions: {
      timestamp: {
        sql: `timestamp`,
        type: `time`,

        granularities: {
          sunday_week: {
            interval: `1 week`,
            offset: `-1 day`
          },

          fiscal_year: {
            title: `Federal fiscal year in the United States`,
            interval: `1 year`,
            offset: `-3 months`
          },

          fiscal_quarter: {
            title: `Federal fiscal quarter in the United States`,
            interval: `1 quarter`,
            offset: `-3 months`
          }
        }
      },
      
      sunday_week: {
        sql: `${timestamp.sunday_week}`,
        type: `time`
      },

      fiscal_year: {
        sql: `${timestamp.fiscal_year}`,
        type: `time`
      },
        
      fiscal_quarter: {
        sql: `${timestamp.fiscal_quarter}`,
        type: `time`
      },

      fiscal_quarter_label: {
        sql: `
            'FY' || (EXTRACT(YEAR FROM {timestamp.fiscal_year}) + 1) ||
            '-Q' || EXTRACT(QUARTER FROM {timestamp.fiscal_quarter} + INTERVAL '3 MONTHS')
        `,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

## Result

Querying this data modal would yield the following result:

<Frame>
  <img />
</Frame>

[ref-custom-granularities]: /reference/data-modeling/dimensions#granularities

[ref-default-granularities]: /docs/data-modeling/dimensions#time-dimensions

[wiki-fiscal-year]: https://en.wikipedia.org/wiki/Fiscal_year

[ref-sql-api]: /reference/core-data-apis/sql-api

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-graphql-api]: /reference/core-data-apis/graphql-api

[ref-proxy-granularity]: /docs/data-modeling/dimensions#time-dimension-granularity-references

[ref-calendar-cubes]: /docs/data-modeling/concepts/calendar-cubes#overriding-granularities

[ref-recipe-custom-calendar]: /recipes/data-modeling/custom-calendar


# Custom ordering for categorical values
Source: https://docs.cube.dev/recipes/data-modeling/custom-order

This recipe shows how to define a custom sort order for dimension values that don't follow alphabetical or numeric ordering.

## Use case

When working with categorical dimensions like pipeline stages, priority levels,
or status values, you often need to sort them in a specific business-meaningful
order rather than alphabetically. For example, a sales pipeline might have
stages like *Pipeline*, *Best Case*, *Most Likely*, *Commit*, and *Closed*
that should always appear in that funnel order.

Sometimes stages are prefixed with numbers (e.g., *1. Pipeline*, *2. Best
Case*) which makes alphabetical sorting work. But when they don't have
numbers, alphabetical order produces results that don't match the business
logic.

There are two ways to solve this:

* **At query time** — write a `CASE` expression directly in a [semantic
  SQL][ref-sql-api] query. This is the fastest way to get results and works
  great when you're exploring data in a [workbook][ref-workbooks] or asking AI
  to build a query for you.
* **In the data model** — add a permanent dimension with the ordering logic.
  This is the right choice when the same sort order is reused across many
  queries, dashboards, or consumers.

## Query-level approach

You can define a custom ordering dimension directly in a semantic SQL query
without changing the data model. This is especially useful when working in
workbooks — you can ask AI to sort results in a specific order and it will
generate the appropriate `CASE` expression for you.

```sql theme={"dark"}
SELECT
  deals.forecast_category,
  CASE
    WHEN deals.forecast_category = 'Pipeline' THEN 1
    WHEN deals.forecast_category = 'Best Case' THEN 2
    WHEN deals.forecast_category = 'Most Likely' THEN 3
    WHEN deals.forecast_category = 'Commit' THEN 4
    WHEN deals.forecast_category = 'Closed' THEN 5
    ELSE 6
  END AS funnel_order,
  MEASURE(total_amount) AS total_amount
FROM
  deals
GROUP BY
  1, 2
ORDER BY
  2 ASC
```

The `CASE` expression creates an inline `funnel_order` column that maps each
category to its position. The query then sorts by that column instead of by
the category name.

This approach requires no changes to the data model and is ideal for ad-hoc
analysis. In a workbook, you can simply ask the AI assistant something like
*"sort forecast categories in pipeline order: Pipeline, Best Case, Most
Likely, Commit, Closed"* and it will generate a query like the one above.

## Data model approach

When the same custom order is needed across multiple queries, dashboards, or
BI tools, it's better to encode it as a dimension in the data model. This
way any consumer can sort by it without re-implementing the `CASE` logic.

Consider the following data model with a `forecast_category` dimension that
has no inherent sort order:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: deals
      sql_table: deals

      dimensions:
        - name: forecast_category
          sql: forecast_category
          type: string

        - name: forecast_category_order
          sql: |
            CASE
              WHEN {forecast_category} = 'Pipeline' THEN 1
              WHEN {forecast_category} = 'Best Case' THEN 2
              WHEN {forecast_category} = 'Most Likely' THEN 3
              WHEN {forecast_category} = 'Commit' THEN 4
              WHEN {forecast_category} = 'Closed' THEN 5
              ELSE 6
            END
          type: number

      measures:
        - name: total_amount
          sql: amount
          type: sum
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`deals`, {
    sql_table: `deals`,

    dimensions: {
      forecast_category: {
        sql: `forecast_category`,
        type: `string`
      },

      forecast_category_order: {
        sql: `
          CASE
            WHEN ${forecast_category} = 'Pipeline' THEN 1
            WHEN ${forecast_category} = 'Best Case' THEN 2
            WHEN ${forecast_category} = 'Most Likely' THEN 3
            WHEN ${forecast_category} = 'Commit' THEN 4
            WHEN ${forecast_category} = 'Closed' THEN 5
            ELSE 6
          END
        `,
        type: `number`
      }
    },

    measures: {
      total_amount: {
        sql: `amount`,
        type: `sum`
      }
    }
  })
  ```
</CodeGroup>

The `forecast_category_order` dimension uses a `CASE` expression to assign a
numeric position to each category value. This dimension references the
`forecast_category` dimension so that the mapping stays consistent.

The `ELSE 6` clause handles any unexpected values, placing them at the end
of the sort order.

Once the dimension is in the data model, queries become straightforward:

```sql theme={"dark"}
SELECT
  forecast_category,
  forecast_category_order,
  MEASURE(total_amount)
FROM
  deals
GROUP BY
  1, 2
ORDER BY
  2 ASC
```

## Result

Both approaches produce the same result — a business-meaningful funnel order
instead of alphabetical sorting:

| Forecast Category | funnel\_order |   Total Amount |
| ----------------- | ------------: | -------------: |
| Pipeline          |             1 |   \$17,830,500 |
| Best Case         |             2 |    \$6,786,250 |
| Most Likely       |             3 |   \$537,499.70 |
| Commit            |             4 |      \$688,000 |
| Closed            |             5 | \$9,232,800.46 |

This pattern works for any set of categorical values that need a custom order:
support ticket priorities, project phases, approval workflows, and so on.

Use the **query-level approach** when you need a quick, one-off sort order
while exploring data. Use the **data model approach** when the ordering is a
stable business rule that should be available to all consumers.

[ref-data-apis]: /reference#data-apis

[ref-sql-api]: /reference/core-data-apis/sql-api

[ref-custom-sorting]: /recipes/core-data-api/sorting

[ref-workbooks]: /docs/explore-analyze/workbooks


# Using Cube with dbt
Source: https://docs.cube.dev/recipes/data-modeling/dbt

Layer Cube cubes and views on dbt-built warehouse models, aligning documentation patterns with dimensions, measures, joins, and downstream APIs.

[dbt][link-dbt-docs] is a popular data integration tool used by many Cube
users to transform the data in the data warehouse before bringing it to the
semantic layer.

<Frame>
  <img />
</Frame>

Usually, dbt projects are [focused][link-dbt-docs-structure] on creating
staging and intermediate models and finally using them to define normalized
[data marts][link-dbt-docs-structure-marts] for the semantic layer. Often,
these marts would be described in `.yml` files as
[models][link-dbt-docs-models] with [columns][link-dbt-docs-columns] and
other properties.

Cube projects usually define [cubes][ref-ref-cubes] on top of dbt models,
materialized as tables or views in your data warehouse, bring columns as
[dimensions][ref-ref-dimensions], enrich them with
[measures][ref-ref-measures], [joins][ref-ref-joins], and
[pre-aggregations][ref-ref-pre-aggs]. Finally, the facade of the data model
is created with [views][ref-ref-views] and exposed to downstream tools via
a rich [set of APIs][ref-apis].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
    - sql_table: my_dbt_schema.my_dbt_orders_model

      dimensions: []
      measures: []
      joins: []
      pre_aggregations: []
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `my_dbt_schema.my_dbt_orders_model`,

    dimensions: {},
    measures: {},
    joins: {},
    pre_aggregations: {}
  })
  ```
</CodeGroup>

Cube provides a convenient `cube_dbt` package to simplify [data model
integration][self-integration].

## Data transformation

### Data types

Cube provides a single [`time` type][ref-time-type] to model time
dimensions. However, raw data can contain temporal columns in various
formats, e.g., as `TIMESTAMP`, `DATETIME`, `DATE`, etc. It's a best practice
to convert all temporal columns in dbt models into the `TIMESTAMP` format.

### Refresh keys

It's convenient to have an `updated_at` column in every dbt model so that
the [refresh keys][ref-refresh-keys] of cubes would be defined as follows:

```sql theme={"dark"}
SELECT MAX(updated_at)
FROM orders
```

When the source data doesn't have a column that can be used to track updates
reliably and dbt [snapshots](https://docs.getdbt.com/docs/build/snapshots) are used,
`dbt_valid_from` and `dbt_valid_to` columns can be used to define refresh keys, e.g.:

```sql theme={"dark"}
SELECT CONCAT(COUNT(*), MAX(dbt_valid_from), MIN(dbt_valid_to))
FROM orders_snapshot
```

### Pre-aggregations

When [pre-aggregations][ref-pre-aggs] are implemented, they would be
refreshed using their own [refresh keys][ref-pre-aggs-refresh-keys].

If applicable, consider configuring a data orchestration tool like Airflow,
Dagster, or Prefect so that it triggers pre-aggregation refresh when dbt
models are updated via the [Orchestration API][ref-orchestration-api].

## Data model integration

[`cube_dbt` package][ref-cube-dbt] simplifies defining the data model on
top of dbt models. It provides convenient tools for loading the metadata
of a dbt project, inspecting dbt models, and rendering them as cubes with
dimensions. It's designed to work with [dynamic data models][dynamic-models]
built with YAML, Jinja, and Python.

Usually, the integration would include the following steps:

* Load the metadata of your dbt project.
* Select relevant dbt models.
* Render dbt models as cubes with dimensions.
* Enrich these cubes with measures, joins, pre-aggregations, etc.

### Installation

Add the `cube_dbt` package to the `requirements.txt` file in the root
directory of your Cube project. See the [`cube_dbt` package][ref-cube-dbt]
documentation for details.

### Loading dbt projects

`cube_dbt` package loads the metadata of dbt projects from the
[`manifest.json` file][dbt-manifest]. Any dbt command that parses the dbt
project would produce this file, including `dbt build` and `dbt run`.

<Info>
  Loading metadata from dbt Cloud might be implemented in further releases of
  the `cube_dbt` package.
</Info>

In the most basic scenario, you can commit the `manifest.json` file to the
source code of your Cube project and load it as a local file. Here's an
example source code of the `globals.py` file in your data model folder:

```python theme={"dark"}
from cube_dbt import Dbt

dbt = Dbt.from_file('./manifest.json')
```

In a less basic scenario, you can put the `manifest.json` file to a remote
storage and load it by its URL:

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://cube-dbt-integration.s3.amazonaws.com/manifest.json'
dbt = Dbt.from_url(manifest_url)
```

Actually, you can obtain the contents of the `manifest.json` file in any way
that works for you. parse the JSON into a dictionary, and load it directly.
This is particularly useful when loading `manifest.json` from non-public
remote storage using packages like [`smart-open`][link-smart-open] or
[`boto3`][link-boto3].

```python theme={"dark"}
from cube_dbt import Dbt
from smart_open import open
import json

manifest_url = 'https://cube-dbt-integration.s3.amazonaws.com/manifest.json'
manifest = None

with open(manifest_url) as file:
  manifest_json = file.read()
  manifest = json.loads(manifest_json)

dbt = Dbt(manifest)
```

### Selecting dbt models

By default, `cube_dbt` would load all dbt models, excluding
[ephemeral][link-dbt-materializations] ones. You can also cherry-pick dbt
models and load only some of them.

For example, you can load only models under a directory or directories.
This is particularly useful if you keep your data marts under
`models/marts/` as [advised by dbt][link-dbt-docs-structure-marts].

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://cube-dbt-integration.s3.amazonaws.com/manifest.json'
dbt = Dbt.from_url(manifest_url).filter(paths=['marts/'])
```

You can also load only models with certain tags. This is useful if you'd
like to have more granular controls over dbt models exposed to the semantic
layer:

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://cube-dbt-integration.s3.amazonaws.com/manifest.json'
dbt = Dbt.from_url(manifest_url).filter(tags=['cube'])
```

Finally, you can load only select models by their names:

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://cube-dbt-integration.s3.amazonaws.com/manifest.json'
dbt = Dbt.from_url(manifest_url).filter(names=['orders', 'customers'])
```

### Rendering dbt models

`cube_dbt` provides convenient tools to render dbt models in YAML files
with Jinja. For that, dbt models should be made
[accessible][ref-template-context] from Jinja templates. Here, they are
exposed via `dbt_models` and `dbt_model` functions:

```python theme={"dark"}
from cube import TemplateContext
from cube_dbt import Dbt

manifest_url = 'https://cube-dbt-integration.s3.amazonaws.com/manifest.json'
dbt = Dbt.from_url(manifest_url).filter(paths=['marts/'])

template = TemplateContext()

@template.function('dbt_models')
def dbt_models():
  return dbt.models

@template.function('dbt_model')
def dbt_model(name):
  return dbt.model(name)
```

You can use the `dbt_models` function in a Jinja template to iterate over
all models and output them as YAML. Note the convenient
[`as_cube`][ref-cube-dbt-as-cube] and
[`as_dimensions`][ref-cube-dbt-as-dimensions] methods that would render
each model with correct `name` and `sql_table` and also render each column
as a dimension.

```yaml theme={"dark"}
cubes:
  {% for model in dbt_models() %}
  - {{ model.as_cube() }}

    dimensions:
      {{ model.as_dimensions(skip=['very_private_column']) }}

    measures:
      - name: count
        type: count
  {% endfor %}
```

`cube_dbt` does its best to [translate `data_type`][ref-cube-dbt-data-type]
properties of columns to correct [dimension types][ref-dimension-types].
Also, if a column is tagged as `primary_key` in its properties, it would
automatically become a [primary key][ref-primary-key] dimension. You can
also prevent select columns from being rendered as dimensions with `skip`.

You can even iterate over columns on your own and render them as you wish:

```yaml theme={"dark"}
cubes:
  {% for model in dbt_models() %}
  - {{ model.as_cube() }}

    dimensions:
      {% for column in model.columns %}
      - name: "{{ column.name }}"
        sql: "{{ column.sql }}"
        type: "{{ column.type }}"
        description: "{{ column.description }}"
        meta:
          source: dbt
      {% endfor %}

    measures:
      - name: count
        type: count
  {% endfor %}
```

However, in a real-world scenario, iterating over all dbt models and
rendering them in a single YAML file is inconvenient since it would be
difficult to enrich each rendered cube with its own measures, joins, etc.

### Enriching the data model

It's best practice to render each dbt model (or data mart) as cube in its
own file. It simplifies Jinja templates and improves the maintainability
of the data model. Consider the following cube:

```yml theme={"dark"}
{% set model = dbt_model('orders') %}

cubes:
  - {{ model.as_cube() }}

    dimensions:
      {{ model.as_dimensions() }}

    # Model-specific measures
    measures:
      - name: count
        type: count

      - name: statuses
        sql: "STRING_AGG({status}, ',')"
        type: string

    # Model-specific joins
    joins:
      - name: users
        sql: "{CUBE.user_id} = {users.id}"
        relationship: many_to_one

    # Model-specific pre-aggregations
    pre_aggregations:
      - name: count_by_users
        measures:
          - CUBE.count
        dimensions:
          - users.full_name
```

You can easily customize measures, joins, and pre-aggregation that apply
to this very cube, mapped to the `orders` dbt model, and have it
side-by-side with other cubes, even of they don't come from dbt.

To inspect rendered cubes, you can use [Visual Modeler][ref-visual-model],
[Playground][ref-playground], or the [`meta` endpoint][ref-rest-api-meta]
of the REST (JSON) API.

[dynamic-models]: /docs/data-modeling/dynamic/jinja

[dbt-manifest]: https://docs.getdbt.com/reference/artifacts/manifest-json

[self-integration]: /recipes/data-modeling/dbt#data-model-integration

[ref-ref-cubes]: /reference/data-modeling/cube

[ref-ref-dimensions]: /reference/data-modeling/dimensions

[ref-ref-measures]: /reference/data-modeling/measures

[ref-ref-joins]: /reference/data-modeling/joins

[ref-ref-pre-aggs]: /reference/data-modeling/pre-aggregations

[ref-ref-views]: /reference/data-modeling/view

[ref-apis]: /reference

[ref-time-type]: /reference/data-modeling/dimensions#type

[ref-refresh-keys]: /reference/data-modeling/cube#refresh_key

[ref-pre-aggs]: /docs/pre-aggregations/using-pre-aggregations

[ref-pre-aggs-refresh-keys]: /docs/pre-aggregations/using-pre-aggregations#refresh-strategy

[ref-orchestration-api]: /reference/orchestration-api

[ref-cube-dbt]: /reference/data-modeling/cube_dbt

[ref-cube-dbt-as-cube]: /reference/data-modeling/cube_dbt#modelas_cube

[ref-cube-dbt-as-dimensions]: /reference/data-modeling/cube_dbt#modelas_dimensions

[ref-cube-dbt-data-type]: /reference/data-modeling/cube_dbt#columntype

[ref-template-context]: /reference/data-modeling/cube-package#templatecontext-class

[ref-primary-key]: /reference/data-modeling/dimensions#primary_key

[ref-dimension-types]: /reference/data-modeling/dimensions#type

[ref-visual-model]: /docs/data-modeling/visual-modeler

[ref-playground]: /docs/explore-analyze/playground

[ref-rest-api-meta]: /reference/core-data-apis/rest-api/reference#base_path/v1/meta

[link-dbt-docs]: https://docs.getdbt.com/docs/build/projects

[link-dbt-docs-structure]: https://docs.getdbt.com/guides/best-practices/how-we-structure/1-guide-overview#guide-structure-overview

[link-dbt-docs-structure-marts]: https://docs.getdbt.com/guides/best-practices/how-we-structure/5-semantic-layer-marts

[link-dbt-docs-models]: https://docs.getdbt.com/reference/model-properties

[link-dbt-docs-columns]: https://docs.getdbt.com/reference/resource-properties/columns

[link-dbt-materializations]: https://docs.getdbt.com/docs/build/materializations

[link-smart-open]: https://pypi.org/project/smart-open/

[link-boto3]: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/s3-examples.html


# Configurable rolling windows and time shifts
Source: https://docs.cube.dev/recipes/data-modeling/dynamic-rolling-windows

Let data consumers choose a measure's rolling-window and time-shift interval at query time, without defining a separate measure for every window.

## Use case

Sometimes you want a measure to behave *dynamically*: its rolling window — and the
prior-period shift you compare it against — should be chosen by the data consumer at
query time rather than fixed in the data model. A common example is an embedded
dashboard with a "window" dropdown (R3 / R6 / R9 / R12) where picking a value should
change the query, not the data model.

The window and the shift can't be passed as query parameters. Both
[`rolling_window`][ref-rolling-window] and [`time_shift`][ref-time-shift] are
properties of a measure *definition*, resolved when the model compiles — and a member
must mean the same thing in every query, otherwise caching, pre-aggregation matching,
and governance break.

The trick is to move the *choice* into the query instead. A [`switch`
dimension][ref-switch] holds the set of allowed windows and acts as the query-time
parameter, and [`case` measures][ref-case] dispatch to the matching rolling logic based
on the selected value. Consumers only ever touch a small, fixed set of members, so
those members stay well-defined and cacheable.

## Data modeling

Say you have monthly `gross_sales` and want trailing 3-, 6-, 9-, and 12-month totals,
each compared to the immediately preceding window of the same length.

The model has four parts:

* A `growth_window` [`switch` dimension][ref-switch] whose `values` are the selectable
  windows. This is the query-time parameter.
* A [`rolling_window`][ref-rolling-window] measure per window (the *current period*).
* A [`time_shift`][ref-time-shift] measure per window that shifts the current-period
  measure back by the window's length (the *prior period*).
* Four [`case` measures][ref-case] — `gross_sales_current`, `gross_sales_prior`,
  `gross_sales_change`, and `gross_sales_growth_percentage` — that dispatch on
  `growth_window`. Consumers query only these four, regardless of the selected window.

The per-window measures are near-identical, so [Jinja][ref-jinja] generates them from a
single list. Adding a window (say, R18) is a one-token change to `windows`, not a new
measure by hand.

<Warning>
  `switch` dimensions and `case` measures are powered by Tesseract, the
  [next-generation data modeling engine][link-tesseract]. In versions before v1.7.0, it
  was not enabled by default.
</Warning>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  {%- set windows = [3, 6, 9, 12] -%}

  cubes:
    - name: gross_sales
      sql: |
        SELECT '2023-01-01'::TIMESTAMP AS month, 100 AS amount UNION ALL
        SELECT '2023-02-01'::TIMESTAMP AS month, 110 AS amount UNION ALL
        SELECT '2023-03-01'::TIMESTAMP AS month, 120 AS amount UNION ALL
        SELECT '2023-04-01'::TIMESTAMP AS month, 130 AS amount UNION ALL
        SELECT '2023-05-01'::TIMESTAMP AS month, 140 AS amount UNION ALL
        SELECT '2023-06-01'::TIMESTAMP AS month, 150 AS amount UNION ALL
        SELECT '2023-07-01'::TIMESTAMP AS month, 160 AS amount UNION ALL
        SELECT '2023-08-01'::TIMESTAMP AS month, 170 AS amount UNION ALL
        SELECT '2023-09-01'::TIMESTAMP AS month, 180 AS amount UNION ALL
        SELECT '2023-10-01'::TIMESTAMP AS month, 190 AS amount UNION ALL
        SELECT '2023-11-01'::TIMESTAMP AS month, 200 AS amount UNION ALL
        SELECT '2023-12-01'::TIMESTAMP AS month, 210 AS amount UNION ALL
        SELECT '2024-01-01'::TIMESTAMP AS month, 220 AS amount UNION ALL
        SELECT '2024-02-01'::TIMESTAMP AS month, 230 AS amount UNION ALL
        SELECT '2024-03-01'::TIMESTAMP AS month, 240 AS amount UNION ALL
        SELECT '2024-04-01'::TIMESTAMP AS month, 250 AS amount UNION ALL
        SELECT '2024-05-01'::TIMESTAMP AS month, 260 AS amount UNION ALL
        SELECT '2024-06-01'::TIMESTAMP AS month, 270 AS amount UNION ALL
        SELECT '2024-07-01'::TIMESTAMP AS month, 280 AS amount UNION ALL
        SELECT '2024-08-01'::TIMESTAMP AS month, 290 AS amount UNION ALL
        SELECT '2024-09-01'::TIMESTAMP AS month, 300 AS amount UNION ALL
        SELECT '2024-10-01'::TIMESTAMP AS month, 310 AS amount UNION ALL
        SELECT '2024-11-01'::TIMESTAMP AS month, 320 AS amount UNION ALL
        SELECT '2024-12-01'::TIMESTAMP AS month, 330 AS amount

      dimensions:
        - name: month
          sql: month
          type: time
          primary_key: true

        # The query-time parameter: the selected value chooses the window.
        - name: growth_window
          type: switch
          values:
          {%- for months in windows %}
            - {{ months }}m
          {%- endfor %}

      measures:
        - name: gross_sales
          sql: amount
          type: sum

        # Trailing (current-period) totals, one per window.
        {%- for months in windows %}
        - name: r{{ months }}_gross_sales
          sql: amount
          type: sum
          rolling_window:
            trailing: {{ months }} month
        {% endfor %}

        # Prior-period counterparts, each shifted back by the window's length.
        {%- for months in windows %}
        - name: prev_r{{ months }}_gross_sales
          multi_stage: true
          sql: "{r{{ months }}_gross_sales}"
          type: number
          time_shift:
            - interval: {{ months }} month
              type: prior
        {% endfor %}

        # The members consumers query, dispatching on growth_window.
        - name: gross_sales_current
          multi_stage: true
          case:
            switch: "{CUBE.growth_window}"
            when:
            {%- for months in windows %}
              - value: {{ months }}m
                sql: "{CUBE.r{{ months }}_gross_sales}"
            {%- endfor %}
            else:
              sql: "{CUBE.r{{ windows[0] }}_gross_sales}"
          type: number

        - name: gross_sales_prior
          multi_stage: true
          case:
            switch: "{CUBE.growth_window}"
            when:
            {%- for months in windows %}
              - value: {{ months }}m
                sql: "{CUBE.prev_r{{ months }}_gross_sales}"
            {%- endfor %}
            else:
              sql: "{CUBE.prev_r{{ windows[0] }}_gross_sales}"
          type: number

        - name: gross_sales_change
          multi_stage: true
          sql: "{gross_sales_current} - {gross_sales_prior}"
          type: number

        - name: gross_sales_growth_percentage
          multi_stage: true
          sql: "100.0 * ({gross_sales_current} - {gross_sales_prior}) / NULLIF({gross_sales_prior}, 0)"
          type: number
  ```

  ```javascript title="JavaScript" theme={"dark"}
  const windows = [3, 6, 9, 12];

  cube(`gross_sales`, {
    sql: `
      SELECT '2023-01-01'::TIMESTAMP AS month, 100 AS amount UNION ALL
      SELECT '2023-02-01'::TIMESTAMP AS month, 110 AS amount UNION ALL
      SELECT '2023-03-01'::TIMESTAMP AS month, 120 AS amount UNION ALL
      SELECT '2023-04-01'::TIMESTAMP AS month, 130 AS amount UNION ALL
      SELECT '2023-05-01'::TIMESTAMP AS month, 140 AS amount UNION ALL
      SELECT '2023-06-01'::TIMESTAMP AS month, 150 AS amount UNION ALL
      SELECT '2023-07-01'::TIMESTAMP AS month, 160 AS amount UNION ALL
      SELECT '2023-08-01'::TIMESTAMP AS month, 170 AS amount UNION ALL
      SELECT '2023-09-01'::TIMESTAMP AS month, 180 AS amount UNION ALL
      SELECT '2023-10-01'::TIMESTAMP AS month, 190 AS amount UNION ALL
      SELECT '2023-11-01'::TIMESTAMP AS month, 200 AS amount UNION ALL
      SELECT '2023-12-01'::TIMESTAMP AS month, 210 AS amount UNION ALL
      SELECT '2024-01-01'::TIMESTAMP AS month, 220 AS amount UNION ALL
      SELECT '2024-02-01'::TIMESTAMP AS month, 230 AS amount UNION ALL
      SELECT '2024-03-01'::TIMESTAMP AS month, 240 AS amount UNION ALL
      SELECT '2024-04-01'::TIMESTAMP AS month, 250 AS amount UNION ALL
      SELECT '2024-05-01'::TIMESTAMP AS month, 260 AS amount UNION ALL
      SELECT '2024-06-01'::TIMESTAMP AS month, 270 AS amount UNION ALL
      SELECT '2024-07-01'::TIMESTAMP AS month, 280 AS amount UNION ALL
      SELECT '2024-08-01'::TIMESTAMP AS month, 290 AS amount UNION ALL
      SELECT '2024-09-01'::TIMESTAMP AS month, 300 AS amount UNION ALL
      SELECT '2024-10-01'::TIMESTAMP AS month, 310 AS amount UNION ALL
      SELECT '2024-11-01'::TIMESTAMP AS month, 320 AS amount UNION ALL
      SELECT '2024-12-01'::TIMESTAMP AS month, 330 AS amount
    `,

    dimensions: {
      month: {
        sql: `month`,
        type: `time`,
        primary_key: true
      },

      // The query-time parameter: the selected value chooses the window.
      growth_window: {
        type: `switch`,
        values: windows.map(months => `${months}m`)
      }
    },

    measures: {
      gross_sales: {
        sql: `amount`,
        type: `sum`
      },

      // Trailing (current-period) totals and their prior-period counterparts,
      // one pair per window.
      ...windows.reduce((members, months) => {
        const current = `r${months}_gross_sales`;
        const prior = `prev_r${months}_gross_sales`;
        return {
          ...members,

          [current]: {
            sql: `amount`,
            type: `sum`,
            rolling_window: {
              trailing: `${months} month`
            }
          },

          [prior]: {
            multi_stage: true,
            sql: `${CUBE[current]}`,
            type: `number`,
            time_shift: [{
              interval: `${months} month`,
              type: `prior`
            }]
          }
        };
      }, {}),

      // The members consumers query, dispatching on growth_window.
      gross_sales_current: {
        multi_stage: true,
        case: {
          switch: `${CUBE.growth_window}`,
          when: windows.map(months => {
            const current = `r${months}_gross_sales`;
            return { value: `${months}m`, sql: `${CUBE[current]}` };
          }),
          else: {
            sql: `${CUBE[`r${windows[0]}_gross_sales`]}`
          }
        },
        type: `number`
      },

      gross_sales_prior: {
        multi_stage: true,
        case: {
          switch: `${CUBE.growth_window}`,
          when: windows.map(months => {
            const prior = `prev_r${months}_gross_sales`;
            return { value: `${months}m`, sql: `${CUBE[prior]}` };
          }),
          else: {
            sql: `${CUBE[`prev_r${windows[0]}_gross_sales`]}`
          }
        },
        type: `number`
      },

      gross_sales_change: {
        multi_stage: true,
        sql: `${gross_sales_current} - ${gross_sales_prior}`,
        type: `number`
      },

      gross_sales_growth_percentage: {
        multi_stage: true,
        sql: `100.0 * (${gross_sales_current} - ${gross_sales_prior}) / NULLIF(${gross_sales_prior}, 0)`,
        type: `number`
      }
    }
  });
  ```
</CodeGroup>

<Note>
  Two requirements make `case` measures work:

  * **Every `case` measure needs an `else` branch.** It provides the value when the
    selected `switch` value matches no `when` clause.
  * **Always include the `switch` dimension (`growth_window`) in the query.** The `case`
    measures — and the calculated measures built on top of them — need it to dispatch. To
    pin a single window, add a filter on it (see below); don't rely on the filter alone.
</Note>

To give consumers a sensible default window, expose the cube through a [view][ref-view]
with a [`default_filters`][ref-default-filters] entry on `growth_window`. The `unless`
clause releases the default as soon as the consumer filters on `growth_window`
explicitly, so a query with no window filter gets the default, and a query that picks a
window gets that one:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: gross_sales_view
      cubes:
        - join_path: gross_sales
          includes: "*"

      default_filters:
        - member: gross_sales.growth_window
          operator: equals
          values:
            - 3m
          unless:
            - gross_sales.growth_window
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`gross_sales_view`, {
    cubes: [{
      join_path: gross_sales,
      includes: `*`
    }],

    defaultFilters: [{
      member: `gross_sales.growth_window`,
      operator: `equals`,
      values: [`3m`],
      unless: [`gross_sales.growth_window`]
    }]
  });
  ```
</CodeGroup>

## Result

Query the view through the [SQL API][ref-sql-api], selecting `growth_window` and the four
consumer measures. Wrap measures in `MEASURE()` and provide a date range for the rolling
windows.

With no filter on `growth_window`, the `default_filters` entry applies the default
window (`3m`):

```sql theme={"dark"}
SELECT
  growth_window,
  MEASURE(gross_sales_current),
  MEASURE(gross_sales_prior),
  MEASURE(gross_sales_change),
  MEASURE(gross_sales_growth_percentage)
FROM gross_sales_view
WHERE month >= '2024-12-01' AND month < '2025-01-01'
GROUP BY 1;
```

| growth\_window | gross\_sales\_current | gross\_sales\_prior | gross\_sales\_change | gross\_sales\_growth\_percentage |
| -------------- | --------------------: | ------------------: | -------------------: | -------------------------------: |
| 3m             |                   960 |                 870 |                   90 |                            10.34 |

Filtering on `growth_window` — what a "window" dropdown does — selects that window:

```sql theme={"dark"}
SELECT
  growth_window,
  MEASURE(gross_sales_current),
  MEASURE(gross_sales_prior),
  MEASURE(gross_sales_change),
  MEASURE(gross_sales_growth_percentage)
FROM gross_sales_view
WHERE month >= '2024-12-01' AND month < '2025-01-01'
  AND growth_window = '9m'
GROUP BY 1;
```

| growth\_window | gross\_sales\_current | gross\_sales\_prior | gross\_sales\_change | gross\_sales\_growth\_percentage |
| -------------- | --------------------: | ------------------: | -------------------: | -------------------------------: |
| 9m             |                  2610 |                1800 |                  810 |                               45 |

Filtering on all values returns every window side by side, e.g. to render a comparison:

```sql theme={"dark"}
SELECT
  growth_window,
  MEASURE(gross_sales_current),
  MEASURE(gross_sales_change)
FROM gross_sales_view
WHERE month >= '2024-12-01' AND month < '2025-01-01'
  AND growth_window IN ('3m', '6m', '9m', '12m')
GROUP BY 1
ORDER BY 1;
```

| growth\_window | gross\_sales\_current | gross\_sales\_change |
| -------------- | --------------------: | -------------------: |
| 3m             |                   960 |                   90 |
| 6m             |                  1830 |                  360 |
| 9m             |                  2610 |                  810 |
| 12m            |                  3300 |                 1440 |

## Pre-aggregations

Add a [`rollup`][ref-rollup] over the per-window measures to accelerate these
queries. `growth_window` is a [`switch` dimension][ref-switch], so it does not
have to be included: [pre-aggregation matching][ref-matching-switch-dimensions]
applies the selected value over the rollup scan. Leaving it out also keeps the
rollup small — including it would multiply the rows by every window in the set.

List the per-window measures, not the four `case` measures: the `case` measures
are [multi-stage][ref-multi-stage] and dispatch to the per-window ones, and it's
those that the rollup has to name to be matched.

In the JavaScript model, reference them through `CUBE[...]` rather than by name
as strings. Cube resolves member references by recording them as they're
accessed, so a string never registers as one — the rollup compiles with an empty
measure list and silently matches nothing.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  {%- set windows = [3, 6, 9, 12] -%}

  cubes:
    - name: gross_sales
      # ...

      pre_aggregations:
        - name: rolling
          measures:
            {%- for months in windows %}
            - r{{ months }}_gross_sales
            {%- endfor %}
          time_dimension: month
          granularity: month
  ```

  ```javascript title="JavaScript" theme={"dark"}
  const windows = [3, 6, 9, 12];

  cube(`gross_sales`, {
    // ...

    pre_aggregations: {
      rolling: {
        measures: windows.map(months => CUBE[`r${months}_gross_sales`]),
        time_dimension: month,
        granularity: `month`
      }
    }
  });
  ```
</CodeGroup>

Query the view exactly as above. When querying through the REST (JSON) API,
provide the date range via [`timeDimensions`][ref-time-dimensions-format] rather
than an [`inDateRange` filter][ref-in-date-range] — a filter is matched as a
generic dimension filter, which requires the time dimension to be listed in the
rollup's `dimensions`.

## Related recipes

* If you need a single fixed window rather than a consumer-selectable one, see
  [Active users (DAU, WAU, MAU)][ref-active-users] (fixed `rolling_window` measures) and
  [Period-over-period changes][ref-period-over-period] (a fixed `time_shift` comparison).
  This recipe generalizes both, making the window and shift selectable at query time.
* [Passing dynamic parameters in a query][ref-dynamic-params] also lets a consumer choose
  something at query time, but the choice there is a **data value** (e.g. a city) injected
  into a calculation — not a **measure behavior** (the window length) as it is here.
* [Generating the data model dynamically][ref-dynamic-measures] generates a family of
  members from a list at model-build time; the consumer then picks by choosing which
  member to query, rather than passing a query-time value.

[ref-switch]: /reference/data-modeling/dimensions#type

[ref-case]: /reference/data-modeling/measures#case

[ref-rollup]: /reference/data-modeling/pre-aggregations#rollup

[ref-multi-stage]: /reference/data-modeling/measures#multi_stage

[ref-matching-switch-dimensions]: /docs/pre-aggregations/matching-pre-aggregations#matching-switch-dimensions

[ref-time-dimensions-format]: /reference/core-data-apis/rest-api/query-format#time-dimensions-format

[ref-in-date-range]: /reference/core-data-apis/rest-api/query-format#indaterange

[ref-rolling-window]: /reference/data-modeling/measures#rolling_window

[ref-time-shift]: /reference/data-modeling/measures#time_shift

[ref-view]: /reference/data-modeling/view

[ref-default-filters]: /reference/data-modeling/view#default_filters

[ref-jinja]: /docs/data-modeling/dynamic/jinja

[ref-sql-api]: /reference/core-data-apis/sql-api

[ref-active-users]: /recipes/data-modeling/active-users

[ref-period-over-period]: /recipes/data-modeling/period-over-period

[ref-dynamic-params]: /recipes/data-modeling/passing-dynamic-parameters-in-a-query

[ref-dynamic-measures]: /recipes/data-modeling/using-dynamic-measures

[link-tesseract]: https://cube.dev/blog/introducing-next-generation-data-modeling-engine


# Using dynamic union tables
Source: https://docs.cube.dev/recipes/data-modeling/dynamic-union-tables

Sometimes, you may have a lot of tables in a database, which actually relate to the same entity.

## Use case

Sometimes, you may have a lot of tables in a database, which actually relate
to the same entity.

For example, you can have “per client” tables with the same data, but related to
different customers: `elon_musk_table`, `john_doe_table`, `steve_jobs_table`,
etc. In this case, it would make sense to create a *single* [cube][ref-cubes]
for customers, which should be backed by a union table from all customers tables.

## Data modeling

You can use the [`sql` parameter][ref-cube-sql] to define a cube over an
arbitrary SQL query, e.g., a query that includes `UNION` or `UNION ALL`
operators:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: customers
      sql: |
        SELECT *, 'Einstein' AS name FROM einstein_data UNION ALL
        SELECT *, 'Pascal'   AS name FROM pascal_data   UNION ALL
        SELECT *, 'Newton'   AS name FROM newton_data
    
      measures:
        - name: count
          type: count
    
      dimensions:
        - name: name
          sql: name
          type: string





  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`customers`, {
    sql: `
      SELECT *, 'Einstein' AS name FROM einstein_data UNION ALL
      SELECT *, 'Pascal'   AS name FROM pascal_data   UNION ALL
      SELECT *, 'Newton'   AS name FROM newton_data
    `,
   
    measures: {
      count: {
        type: `count`
      }
    },
   
    dimensions: {
      name: {
        sql: `name`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

However, it can be quite annoying to write the SQL to union all tables manually.
Luckily, you can use [dynamic data modeling][ref-dynamic-data-modeling] to
generate necessary SQL based on a list of tables:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  {%- set customer_tables = {
    "einstein_data": "Einstein",
    "pascal_data": "Pascal",
    "newton_data": "Newton"
  } -%}
   
  cubes:
    - name: customers
      sql: |
        {%- for table, name in customer_tables | items %}
        SELECT *, '{{ name | safe }}' AS name FROM {{ table | safe }}
        {% if not loop.last %}UNION ALL{% endif %}
        {% endfor %}
    
      measures:
        - name: count
          type: count
    
      dimensions:
        - name: name
          sql: name
          type: string
   
   
   
   
   
  ```

  ```javascript title="JavaScript" theme={"dark"}
  const customer_tables = [
    { table: "einstein_data", name: "Einstein" },
    { table: "pascal_data", name: "Pascal" },
    { table: "newton_data", name: "Newton" }
  ]

  cube(`customers`, {
    sql: customer_tables
      .map(entry => `SELECT *, '${entry.name}' AS name FROM ${entry.table}`)
      .join(` UNION ALL `),
   
    measures: {
      count: {
        type: `count`
      }
    },
   
    dimensions: {
      name: {
        sql: `name`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

## Result

Querying `count` and `name` members of the dynamically defined `customers` cube
would result in the following generated SQL:

```sql theme={"dark"}
SELECT
  "customers".name "customers__name",
  count(*) "customers__count"
FROM
  (
    SELECT
      *,
      'Einstein' AS name
    FROM
      einstein_data
    UNION ALL
    SELECT
      *,
      'Pascal' AS name
    FROM
      pascal_data
    UNION ALL
    SELECT
      *,
      'Newton' AS name
    FROM
      newton_data
  ) AS "customers"
GROUP BY
  1
ORDER BY
  2 DESC
```

[ref-cubes]: /reference/data-modeling/cube

[ref-cube-sql]: /reference/data-modeling/cube#sql

[ref-dynamic-data-modeling]: /docs/data-modeling/dynamic


# Implementing Entity-Attribute-Value Model (EAV)
Source: https://docs.cube.dev/recipes/data-modeling/entity-attribute-value

Shape sparse entity-attribute-value warehouse tables into queryable dimensions and joins while preserving flexibility across entities.

## Use case

We want to create a cube for a dataset which uses the
[Entity-Attribute-Value](https://en.wikipedia.org/wiki/Entity–attribute–value_model)
model (EAV). It stores entities in a table that can be joined to another table
with numerous attribute-value pairs. Each entity is not guaranteed to have the
same set of associated attributes, thus making the entity-attribute-value
relation a sparse matrix. In the cube, we'd like every attribute to be modeled
as a dimension.

## Data modeling

Let's explore the `users` cube that contains the entities:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      joins:
        - name: orders
          relationship: one_to_many
          sql: "{CUBE}.id = {orders.user_id}"

      dimensions:
        - name: name
          sql: "first_name || ' ' || last_name"
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    joins: {
      orders: {
        relationship: "one_to_many",
        sql: `${CUBE}.id = ${orders.user_id}`
      }
    },

    dimensions: {
      name: {
        sql: `first_name || ' ' || last_name`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

The `users` cube is joined with the `orders` cube to reflect that there might be
many orders associated with a single user. The orders remain in various
statuses, as reflected by the `status` dimension, and their creation dates are
available via the `created_at` dimension:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      dimensions:
        - name: user_id
          sql: user_id
          type: string

        - name: status
          sql: status
          type: string

        - name: created_at
          sql: created_at
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    dimensions: {
      user_id: {
        sql: `user_id`,
        type: `string`
      },

      status: {
        sql: `status`,
        type: `string`
      },

      created_at: {
        sql: `created_at`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

Currently, the dataset contains orders in the following statuses:

| status     |
| ---------- |
| completed  |
| processing |
| shipped    |

Let's say that we'd like to know, for each user, the earliest creation date for
their orders in any of these statuses. In terms of the EAV model:

* the users serve as *entities* and they should be modeled with a *cube*
* order statuses serve as *attributes* and they should be modeled as
  *dimensions*
* the earliest creation dates for each status serve as attribute *values* and
  they will be modeled as *dimension values*

Let's explore some possible ways to model that.

### Static attributes

We already know that the following statuses are present in the dataset:
`completed`, `processing`, and `shipped`. Let's assume this set of statuses is
not going to change often.

Then, modeling the cube is as simple as defining a few joins (one join per
attribute):

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users_statuses_joins
      sql: |
        SELECT
          users.first_name,
          users.last_name,
          MIN(cOrders.created_at) AS cCreatedAt,
          MIN(pOrders.created_at) AS pCreatedAt,
          MIN(sOrders.created_at) AS sCreatedAt
        FROM public.users AS users
        LEFT JOIN public.orders AS cOrders
          ON users.id = cOrders.user_id AND cOrders.status = 'completed'
        LEFT JOIN public.orders AS pOrders
          ON users.id = pOrders.user_id AND pOrders.status = 'processing'
        LEFT JOIN public.orders AS sOrders
          ON users.id = sOrders.user_id AND sOrders.status = 'shipped'
        GROUP BY 1, 2

      dimensions:
        - name: name
          sql: "first_name || ' ' || last_name"
          type: string

        - name: completed_created_at
          sql: cCreatedAt
          type: time

        - name: processing_created_at
          sql: pCreatedAt
          type: time

        - name: shipped_created_at
          sql: sCreatedAt
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users_statuses_joins`, {
    sql: `
      SELECT
        users.first_name,
        users.last_name,
        MIN(cOrders.created_at) AS cCreatedAt,
        MIN(pOrders.created_at) AS pCreatedAt,
        MIN(sOrders.created_at) AS sCreatedAt
      FROM public.users AS users
      LEFT JOIN public.orders AS cOrders
        ON users.id = cOrders.user_id AND cOrders.status = 'completed'
      LEFT JOIN public.orders AS pOrders
        ON users.id = pOrders.user_id AND pOrders.status = 'processing'
      LEFT JOIN public.orders AS sOrders
        ON users.id = sOrders.user_id AND sOrders.status = 'shipped'
      GROUP BY 1, 2
    `,

    dimensions: {
      name: {
        sql: `first_name || ' ' || last_name`,
        type: `string`
      },

      completed_created_at: {
        sql: `cCreatedAt`,
        type: `time`
      },

      processing_created_at: {
        sql: `pCreatedAt`,
        type: `time`
      },

      shipped_created_at: {
        sql: `sCreatedAt`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

Querying the cube would yield data like this. As we can see, every user has
attributes that show the earliest creation date for their orders in all three
statuses. However, some attributes don't have values (meaning that a user
doesn't have orders in this status).

| name              | completed\_created\_at | processing\_created\_at | shipped\_created\_at |
| ----------------- | ---------------------: | ----------------------: | -------------------: |
| Ally Blanda       |             2019-03-05 |                       — |           2019-04-06 |
| Cayla Mayert      |             2019-06-14 |              2021-05-20 |                    — |
| Concepcion Maggio |                      — |              2020-07-14 |           2019-07-19 |

The drawback is that when the set of statuses changes, we'll need to amend the
cube definition in several places: update selected values and joins in SQL as
well as update the dimensions. Let's see how to work around that.

### Static attributes, DRY version

<Note>
  This approach uses JavaScript-specific features — programmatic code generation
  with helper functions and `Object.assign`. It is not available in YAML data
  models.
</Note>

We can embrace the
[Don't Repeat Yourself](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)
principle and eliminate the repetition by generating the cube definition
dynamically based on the list of statuses. Let's create a new JavaScript model
so we can move all repeated code patterns into handy functions and iterate over
statuses in relevant parts of the cube's code.

```javascript theme={"dark"}
const statuses = ["completed", "processing", "shipped"]

const createValue = (status, index) =>
  `MIN(orders_${index}.created_at) AS created_at_${index}`

const createJoin = (status, index) =>
  `LEFT JOIN public.orders AS orders_${index}
    ON users.id = orders_${index}.user_id
    AND orders_${index}.status = '${status}'`;

const createDimension = (status, index) => ({
  [`${status}_created_at`]: {
    sql: (CUBE) => `created_at_${index}`,
    type: `time`
  }
})

cube(`users_statuses_DRY`, {
  sql: `
    SELECT
      users.first_name,
      users.last_name,
      ${statuses.map(createValue).join(",")}
    FROM public.users AS users
    ${statuses.map(createJoin).join("")}
    GROUP BY 1, 2
  `,

  dimensions: Object.assign(
    {
      name: {
        sql: `first_name || ' ' || last_name`,
        type: `string`
      }
    },
    statuses.reduce(
      (all, status, index) => ({
        ...all,
        ...createDimension(status, index)
      }),
      {}
    )
  )
})
```

The new `users_statuses_DRY` cube is functionally identical to the
`users_statuses_joins` cube above. Querying this new cube would yield the same
data. However, there's still a static list of statuses present in the cube's
source code. Let's work around that next.

### Dynamic attributes

<Note>
  This approach uses JavaScript-specific features — `asyncModule`, `require`, and
  the Node.js `pg` package. It is not available in YAML data models.
</Note>

We can eliminate the list of statuses from the cube's code by loading this list
from an external source, e.g., the data source. Here's the code from the
`fetch.js` file that defines the `fetchStatuses` function that would load the
statuses from the database. Note that it uses the `pg` package (Node.js client
for Postgres) and reuses the credentials from Cube.

```javascript theme={"dark"}
const { Pool } = require("pg")

const pool = new Pool({
  host: process.env.CUBEJS_DB_HOST,
  port: process.env.CUBEJS_DB_PORT,
  user: process.env.CUBEJS_DB_USER,
  password: process.env.CUBEJS_DB_PASS,
  database: process.env.CUBEJS_DB_NAME
})

const statusesQuery = `
  SELECT DISTINCT status
  FROM public.orders
`;

exports.fetchStatuses = async () => {
  const client = await pool.connect()
  const result = await client.query(statusesQuery)
  client.release()

  return result.rows.map((row) => row.status)
}
```

In the cube file, we will use the `fetchStatuses` function to load the list of
statuses. We will also wrap the cube definition with the `asyncModule` built-in
function that allows the data model to be created
[dynamically](/docs/data-modeling/dynamic).

```javascript theme={"dark"}
const fetchStatuses = require("../fetch").fetchStatuses

asyncModule(async () => {
  const statuses = await fetchStatuses()

  const createValue = (status, index) =>
    `MIN(orders_${index}.created_at) AS created_at_${index}`

  const createJoin = (status, index) =>
    `LEFT JOIN public.orders AS orders_${index}
      ON users.id = orders_${index}.user_id
      AND orders_${index}.status = '${status}'`;

  const createDimension = (status, index) => ({
    [`${status}_created_at`]: {
      sql: (CUBE) => `created_at_${index}`,
      type: `time`
    }
  })

  cube(`users_statuses_dynamic`, {
    sql: `
      SELECT
        users.first_name,
        users.last_name,
        ${statuses.map(createValue).join(",")}
      FROM public.users AS users
      ${statuses.map(createJoin).join("")}
      GROUP BY 1, 2
    `,

    dimensions: Object.assign(
      {
        name: {
          sql: `first_name || ' ' || last_name`,
          type: `string`
        }
      },
      statuses.reduce(
        (all, status, index) => ({
          ...all,
          ...createDimension(status, index)
        }),
        {}
      )
    )
  })
})
```

Again, the new `users_statuses_dynamic` cube is functionally identical to the
previously created cubes. So, querying this new cube would yield the same data
too.


# Implementing event analytics
Source: https://docs.cube.dev/recipes/data-modeling/event-analytics

Turn raw clickstream events into session definitions and metrics you control, using SQL-based patterns that work across common event pipelines.

This tutorial walks through how to transform raw event data into sessions. Many
“out-of-box” web analytics solutions come already prepackaged with sessions, but
they work as a “black box.” It doesn’t give the user either insight into or
control how these sessions defined and work.

With Cube SQL-based sessions data model, you’ll have full control over how these
metrics are defined. It will give you great flexibility when designing sessions
and events to your unique business use case.

A few question we’ll answer with our sessions data model:

* How do we measure session duration?
* What is our bounce rate?
* What areas of the app are most used?
* Where are users spending most of their time?
* How do we filter sessions where a user performs a specific action?

We’ll explore the subject using the data from
[Segment.com](https://segment.com)’s analytics.js library. The same concept
could be applied for different data collection tools, such as
[Snowplow](https://snowplowanalytics.com).

## What is a session?

A session is defined as a group of interactions one user takes within a given
time frame on your app. Usually that time frame defaults to 30 minutes, meaning
that whatever a user does on your app (e.g. browses pages, downloads resources,
purchases products) before they leave equals one session.

<div>
  <img />
</div>

## Unify events and page views into single cube

Segment stores page view data as a `pages` table and events data as a `tracks`
table. For sessions we want to rely not only on page views data, but on events
as well. Imagine you have a highly interactive app, a user loads a page and can
stay on this page interacting with the website for while. Hence, you want to
count events as part of the session as well.

To do that we need to combine page view data and event data into a single cube.
We’ll call the cube just events and assign a page views event type to
`pageview`. Also, we’re going to assign a unique event\_id to every event to use
as primary key.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: events
      sql: |
        SELECT
          t.id || '-e' as event_id
          , t.anonymous_id as anonymous_id
          , t.timestamp
          , t.event
          , t.context_page_path as page_path
          , NULL as referrer
        from javascript.tracks as t

        UNION ALL

        SELECT
          p.id as event_id
          , p.anonymous_id
          , p.timestamp
          , 'pageview' as event
          , p.context_page_path as page_path
          , p.referrer as referrer
        FROM javascript.pages as p
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`events`, {
    sql: `
       SELECT
        t.id || '-e' as event_id
        , t.anonymous_id as anonymous_id
        , t.timestamp
        , t.event
        , t.context_page_path as page_path
        , NULL as referrer
      from javascript.tracks as t

      UNION ALL

      SELECT
        p.id as event_id
        , p.anonymous_id
        , p.timestamp
        , 'pageview' as event
        , p.context_page_path as page_path
        , p.referrer as referrer
      FROM javascript.pages as p
      `
  })
  ```
</CodeGroup>

The above SQL creates base table for our events cube. Now we can add some
measures to calculate the number of events and number of page views only, using
a filter on `event` column.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: events
      # ...

      measures:
        - name: count
          sql: event_id
          type: count

        - name: page_views_count
          sql: event_id
          type: count
          filters: [{ sql: "{CUBE}.event = 'pageview'" }]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("events", {
    // ...,

    measures: {
      count: {
        sql: `event_id`,
        type: `count`
      },

      page_views_count: {
        sql: `event_id`,
        type: `count`,
        filters: [{ sql: `${CUBE}.event = 'pageview'` }]
      }
    }
  })
  ```
</CodeGroup>

Having this in place, we will already be able to calculate the total number of
events and pageviews. Next, we’re going to add dimensions to be able to filter
events in a specific time range and for specific types.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: events
      # ...

      dimensions:
        - name: anonymous_id
          sql: anonymous_id
          type: number
          primary_key: true

        - name: event_id
          sql: event_id
          type: number
          primary_key: true

        - name: timestamp
          sql: timestamp
          type: time

        - name: event
          sql: event
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("events", {
    // ...,

    dimensions: {
      anonymous_id: {
        sql: `anonymous_id`,
        type: `number`,
        primary_key: true
      },

      event_id: {
        sql: `event_id`,
        type: `number`,
        primary_key: true
      },

      timestamp: {
        sql: `timestamp`,
        type: `time`
      },

      event: {
        sql: `event`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

Now we have everything for Events cube and can move forward to grouping these
events into sessions.

## Creating Sessions

As a recap, a session is defined as a group of interactions one user takes
within a given time frame on your app. Usually that time frame defaults to 30
minutes. First, we’re going to use
[`LAG()` function](https://docs.aws.amazon.com/redshift/latest/dg/r_WF_LAG.html)
in Redshift to determine an inactivity\_time between events.

```sql theme={"dark"}
select
  e.event_id AS event_id
  , e.anonymous_id AS anonymous_id
  , e.timestamp AS timestamp
  , DATEDIFF(minutes, LAG(e.timestamp) OVER(PARTITION BY e.anonymous_id ORDER BY e.timestamp), e.timestamp) AS inactivity_time
FROM events AS e
```

`inactivity_time` is the time in minutes between the current event and the
previous. We’re going to use `inactivity_time` to terminate a session based on
30 minutes of inactivity. This window could be changed to any value, based on
how users interact with your app. Now we’re ready to introduce our Sessions
cube.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: sessions
      sql: |
        SELECT
          ROW_NUMBER() OVER(PARTITION BY event.anonymous_id ORDER BY event.timestamp) || ' - '|| event.anonymous_id AS session_id
          , event.anonymous_id
          , event.timestamp AS session_start_at
          , ROW_NUMBER() OVER(PARTITION BY event.anonymous_id ORDER BY event.timestamp) AS session_sequence
          , LEAD(timestamp) OVER(PARTITION BY event.anonymous_id ORDER BY event.timestamp) AS next_session_start_at
        FROM (
          SELECT e.anonymous_id
            , e.timestamp
            , DATEDIFF(minutes
            , LAG(e.timestamp) OVER(PARTITION BY e.anonymous_id ORDER BY e.timestamp)
            , e.timestamp) AS inactivity_time
          FROM {events.sql()} AS e
        ) AS event
        WHERE (event.inactivity_time > 30 OR event.inactivity_time IS NULL)
  ```

  ```javascript title="JavaScript" theme={"dark"}
  // Create new cube for sessions with the following content
  cube(`sessions`, {
    sql: `
      SELECT
        ROW_NUMBER() OVER(PARTITION BY event.anonymous_id ORDER BY event.timestamp) || ' - '|| event.anonymous_id AS session_id
        , event.anonymous_id
        , event.timestamp AS session_start_at
        , ROW_NUMBER() OVER(PARTITION BY event.anonymous_id ORDER BY event.timestamp) AS session_sequence
        , LEAD(timestamp) OVER(PARTITION BY event.anonymous_id ORDER BY event.timestamp) AS next_session_start_at
      FROM (
        SELECT
          e.anonymous_id
          , e.timestamp
          , DATEDIFF(minutes, LAG(e.timestamp) OVER(PARTITION BY e.anonymous_id ORDER BY e.timestamp), e.timestamp) AS inactivity_time
        FROM ${events.sql()} AS e
      ) AS event
      WHERE (event.inactivity_time > 30 OR event.inactivity_time IS NULL)
      `
  })
  ```
</CodeGroup>

As a primary key, we’re going to use `session_id`, which is the combination of
the `anonymous_id` and the session sequence, since it’s guaranteed to be unique
for each session. Having this in place, we can already count sessions and plot a
time series chart of sessions.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: sessions
      # ...

      measures:
        - name: count
          sql: session_id
          type: count

      dimensions:
        - name: anonymous_id
          sql: anonymous_id
          type: number
          primary_key: true

        - name: session_id
          sql: session_id
          type: number
          primary_key: true

        - name: start_at
          sql: session_start_at
          type: time

        - name: next_start_at
          sql: next_session_start_at
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("sessions", {
    // ...,

    measures: {
      count: {
        sql: `session_id`,
        type: `count`
      }
    },

    dimensions: {
      anonymous_id: {
        sql: `anonymous_id`,
        type: `number`,
        primary_key: true
      },

      session_id: {
        sql: `session_id`,
        type: `number`,
        primary_key: true
      },

      start_at: {
        sql: `session_start_at`,
        type: `time`
      },

      next_start_at: {
        sql: `next_session_start_at`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

## Connecting Events to Sessions

The next step is to identify the events contained within the session and the
events ending the session. It’s required to get metrics such as session duration
and events per session, or to identify sessions where specific events occurred
(we’re going to use that for funnel analysis later on). We’re going to
[declare a join](/reference/data-modeling/joins) such that the `events`
cube has a `many_to_one` relation to the `sessions` cube, and specify a
condition, such as all users' events from session start (inclusive) till the
start of the next session (exclusive) belong to that session.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: events
      # ...

      joins:
        - name: sessions
          relationship: many_to_one
          sql: |
            {events.anonymous_id} = {sessions.anonymous_id}
            AND {events.timestamp} >= {sessions.start_at}
            AND ({events.timestamp} < {sessions.next_start_at} or {sessions.next_start_at} is null)
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("events", {
    // ...,

    joins: {
      sessions: {
        relationship: `many_to_one`,
        sql: `
          ${events.anonymous_id} = ${sessions.anonymous_id}
          AND ${events.timestamp} >= ${sessions.start_at}
          AND (${events.timestamp} < ${sessions.next_start_at} or ${sessions.next_start_at} is null)
        `
      }
    }
  })
  ```
</CodeGroup>

To determine the end of the session, we’re going to use a [subquery
dimension](/docs/data-modeling/dimensions#subquery-dimensions).

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: events
      # ...

      measures:
        - name: last_event_timestamp
          sql: timestamp
          type: max
          public: false

    - name: sessions
      # ...

      dimensions:
        - name: end_raw
          sql: "{events.last_event_timestamp}"
          type: time
          sub_query: true
          public: false

        - name: end_at
          sql: |
            CASE WHEN {end_raw} + INTERVAL '1 minutes' > {CUBE}.next_session_start_at
              THEN {CUBE}.next_session_start_at
              ELSE {end_raw} + INTERVAL '30 minutes'
            END

        - name: duration_minutes
          sql: "datediff(minutes, {CUBE}.session_start_at, {end_at})"
          type: number
          
      measures:
        - name: average_duration_minutes
          sql: "{duration_minutes}"
          type: avg
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("events", {
    // ...,

    measures: {
      last_event_timestamp: {
        sql: `timestamp`,
        type: `max`,
        public: false
      }
    }
  })

  cube("sessions", {
    // ...,

    dimensions: {
      end_raw: {
        sql: `${events.last_event_timestamp}`,
        type: `time`,
        sub_query: true,
        public: false
      },

      end_at: {
        sql: `CASE WHEN ${end_raw} + INTERVAL '1 minutes' > ${CUBE}.next_session_start_at
           THEN ${CUBE}.next_session_start_at
           ELSE ${end_raw} + INTERVAL '30 minutes'
           END`,
        type: `time`
      },

      duration_minutes: {
        sql: `datediff(minutes, ${CUBE}.session_start_at, ${end_at})`,
        type: `number`
      }
    },

    measures: {
      average_duration_minutes: {
        type: `avg`,
        sql: `${duration_minutes}`
      }
    }
  })
  ```
</CodeGroup>

## Mapping Sessions to Users

Right now all our sessions are anonymous, so the final step in our modeling
would be to map sessions to users in case, they have signed up and have been
assigned a `user_id`. Segment keeps track of such assignments in a table called
identifies. Every time you identify a user with segment it will connect the
current `anonymous_id` to the identified user id.

We’re going to create an `identifies` cube, which will not contain any visible
measures and dimensions for users to use in Insights, but instead will provide
us with a `user_id` to use in the **Sessions** cube. Also, `identifies` could be
used later on to join `sessions` to your `users` cube, which could be a cube
built based on your internal database data for users.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  # Create a new file for the `identifies` cube with following content
  cubes:
    - name: identifies
      sql: "SELECT distinct user_id, anonymous_id FROM javascript.identifies"

      dimensions:
        - name: id
          sql: "user_id || '-' || anonymous_id"
          type: string
          primary_key: true

        - name: anonymous_id
          sql: anonymous_id
          type: number

        - name: user_id
          sql: user_id
          type: number
          format: id
  ```

  ```javascript title="JavaScript" theme={"dark"}
  // Create a new file for the `identifies` cube with following content
  cube(`identifies`, {
    sql: `SELECT distinct user_id, anonymous_id FROM javascript.identifies`,

    dimensions: {
      id: {
        sql: `user_id || '-' || anonymous_id`,
        type: `string`,
        primary_key: true
      },

      anonymous_id: {
        sql: `anonymous_id`,
        type: `number`
      },

      user_id: {
        sql: `user_id`,
        type: `number`,
        format: `id`
      }
    }
  })
  ```
</CodeGroup>

We need to declare a relationship between `identifies` and `sessions`, where
session has a `many_to_one` relationship with identity.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: sessions
      # ...

      joins:
        - name: identifies
          relationship: many_to_one
          sql: "{identifies.anonymous_id} = {sessions.anonymous_id}"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("sessions", {
    // ...,

    joins: {
      identifies: {
        relationship: `many_to_one`,
        sql: `${identifies.anonymous_id} = ${sessions.anonymous_id}`
      }
    }
  })
  ```
</CodeGroup>

Once we have it, we can create a dimension `user_id`, which will be either a
`user_id` from the identifies table or an `anonymous_id` in case we don’t have
the identity of a visitor, which means that this visitor never signed in.

<CodeGroup>
  ```javascript title="JavaScript" theme={"dark"}
  cube("sessions", {
    // ...,

    dimensions: {
      user_id: {
        sql: `coalesce(${identifies.user_id}, ${CUBE}.anonymous_id)`,
        type: `string`
      }
    }
  })
  ```

  ````yaml title="YAML" theme={"dark"}
  cubes:
    - name: sessions
      # ...

      dimensions:
        - name: user_id
          sql: "coalesce({identifies.user_id}, {CUBE}.anonymous_id)"
          type: string

  </CodeGroup>

  Based on the just-created dimension, we can add two new metrics: the count of
  users and the average sessions per user.

  <CodeGroup>

  ```yaml title="YAML"
  cubes:
    - name: sessions
      # ... 

      measures:
        - name: users_count
          sql: "{user_id}"
          type: count_distinct

        - name: average_sessions_per_user
          sql: "{count}::NUMERIC / NULLIF({users_count}, 0)"
          type: number
  ````

  ```javascript title="JavaScript" theme={"dark"}
  cube("sessions", {
    // ...,

    measures: {
      users_count: {
        sql: `${user_id}`,
        type: `count_distinct`
      },

      average_sessions_per_user: {
        sql: `${count}::NUMERIC / NULLIF(${users_count}, 0)`,
        type: `number`
      }
    }
  })
  ```
</CodeGroup>

That was our final step in building a foundation for a sessions data model.
Congratulations on making it here! Now we’re ready to add some advanced metrics
on top of it.

## More metrics for Sessions

### Number of Events per Session

This one is super easy to add with a subquery dimension. We just calculate the
number of events, which we already have as a measure in the `events` cube, as a
dimension in the `sessions` cube.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: sessions
      # ...

      dimensions:
        - name: number_events
          sql: "{events.count}"
          type: number
          sub_query: true
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("sessions", {
    // ...,

    dimensions: {
      number_events: {
        sql: `${events.count}`,
        type: `number`,
        sub_query: true
      }
    }
  })
  ```
</CodeGroup>

### Bounce Rate

we’ve just defined the number of events per session, we can easily add a
dimension `is_bounced` to identify bounced sessions to the Sessions cube. Using
this dimension, we can add two measures to the Sessions cube as well - a count
of bounced sessions and a bounce rate.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: sessions
      # ...

      dimensions:
        - name: is_bounced
          type: string
          case:
            when: [{ sql: "{number_events} = 1", label: "True" }]
            else: { label: "False" }

      measures:
        - name: bounced_count
          sql: session_id
          type: count
          filters:
            - - sql: "{is_bounced} = 'True'

        - name: bounce_rate
          sql: "1.0 * {bounced_count} / NULLIF({count}, 0)"
          type: number
          format: percent
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("sessions", {
    // ...,

    dimensions: {
      is_bounced: {
        type: `string`,
        case: {
          when: [{ sql: `${number_events} = 1`, label: `True` }],
          else: { label: `False` }
        }
      }
    },

    measures: {
      bounced_count: {
        sql: `session_id`,
        type: `count`,
        filters: [
          {
            sql: `${is_bounced} = 'True'`
          }
        ]
      },

      bounce_rate: {
        sql: `1.0 * ${bounced_count} / NULLIF(${count}, 0)`,
        type: `number`,
        format: `percent`
      }
    }
  })
  ```
</CodeGroup>

### First Referrer

We already have this column in place in our base table. We’re just going to
define a dimension on top of this.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: sessions
      # ...

      measures:
        - name: first_referrer
          type: string
          sql: first_referrer
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("sessions", {
    // ...,

    measures: {
      first_referrer: {
        type: `string`,
        sql: `first_referrer`
      }
    }
  })
  ```
</CodeGroup>

### Sessions New vs Returning

Same as for the first referrer. We already have a `session_sequence` field in
the base table, which we can use for the `is_first` dimension. If
`session_sequence` is 1 - then it belongs to the first session, otherwise - to a
repeated session.

<CodeGroup>
  ```javascript title="JavaScript" theme={"dark"}
  cube("sessions", {
    // ...,

    dimensions: {
      is_first: {
        type: `string`,
        case: {
          when: [{ sql: `${CUBE}.session_sequence = 1`, label: `First` }],
          else: { label: `Repeat` }
        }
      }
    },

    measures: {
      repeat_count: {
        description: `Repeat Sessions Count`,
        sql: `session_id`,
        type: `count`,
        filters: [{ sql: `${is_first} = 'Repeat'` }]
      },

      repeat_percent: {
        description: `Percent of Repeat Sessions`,
        sql: `1.0 * ${repeat_count} / NULLIF(${count}, 0)`,
        type: `number`,
        format: `percent`
      }
    }
  })
  ```

  ````yaml title="YAML" theme={"dark"}
  cubes:
    - name: sessions
      # ...

      dimensions: 
        - name: is_first
          type: string
          case:
            when: [{ sql: "{CUBE}.session_sequence = 1", label: "First" }]
            else: { label: "Repeat" }

      measures:
        - name: repeat_count
          description: Repeat Sessions Count
          sql: session_id
          type: count
          filters: [{ sql: "{is_first} = 'Repeat'" }]

        - name: repeat_percent
          description: Percent of Repeat Sessions
          sql: "1.0 * {repeat_count} / NULLIF({count}, 0)"
          type: number
          format: percent

  </CodeGroup>

  ### Filter Sessions, where user performs specific event

  Often, you want to select specific sessions where a user performed some
  important action. In the example below, we’ll filter out sessions where the
  `form_submitted` event happened. To do that, we need to follow 3 steps:

  Define a measure on the Events cube to count only `form_submitted` events.

  <CodeGroup>

  ```yaml title="YAML"
  cubes:
    - name: events
      # ...

      # Add this measure to the `events` cube
      measures:
        - name: form_submitted_count
          sql: event_id
          type: count
          filters: [{ sql: "{CUBE}.event = 'form_submitted'" }]
  ````

  ```javascript title="JavaScript" theme={"dark"}
  cube("events", {
    // ...,

    // Add this measure to the `events` cube
    measures: {
      form_submitted_count: {
        sql: `event_id`,
        type: `count`,
        filters: [{ sql: `${CUBE}.event = 'form_submitted'` }]
      }
    }
  })
  ```
</CodeGroup>

Define a dimension `form_submitted_count` on the Sessions using `sub_query`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: sessions
      # ...

      # Add this dimension to the `sessions` cube
      dimensions:
        - name: form_submitted_count
          sql: "{events.form_submitted_count}"
          type: number
          sub_query: true
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("sessions", {
    // ...,

    // Add this dimension to the `sessions` cube
    dimensions: {
      form_submitted_count: {
        sql: `${events.form_submitted_count}`,
        type: `number`,
        sub_query: true
      }
    }
  })
  ```
</CodeGroup>

Create a measure to count only sessions where `form_submitted_count` is greater
than 0.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: sessions
      # ...

      # Add this measure to the `sessions` cube
      measures:
        - name: with_form_submitted_count
          sql: session_id
          type: count
          filters: [{ sql: "{form_submitted_count} > 0" }]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("sessions", {
    // ...,

    // Add this measure to the `sessions` cube
    measures: {
      with_form_submitted_count: {
        type: `count`,
        sql: `session_id`,
        filters: [{ sql: `${form_submitted_count} > 0` }]
      }
    }
  })
  ```
</CodeGroup>

Now we can use the `with_form_submitted_count` measure to get only sessions when
the `form_submitted` event occurred.


# Calculating filtered aggregates
Source: https://docs.cube.dev/recipes/data-modeling/filtered-aggregates

Model cross-cube filters so measures aggregate facts in one entity while respecting dimensions and time bounds from related cubes.

## Use case

Sometimes, there's a need to calculate an aggregation over facts in a joined cube that
is filtered by a dimension from another cube. For example, you might want to calculate
the total sales for a retailer. Each retailer has multiple stores, and each store does
its own sales.

If you set sales goals at the retailer level and are only interested in
the sales that happened after a certain date, you would need to calculate the total sales
in a way that only includes sales that happened after that date.

## Data modeling

We can model this scenario by creating a cube for each entity: `retailer`, `store`,
and `sales`. The `retailer` cube has a one-to-many relationship with the `store` cube,
and the `store` cube has a one-to-many relationship with the `sales` cube:

```yml theme={"dark"}
cubes:
  - name: retailer
    sql: |
      SELECT 101 AS id, 'Retailer 1' AS name, 10 AS sales_goal, '2025-02-01Z'::TIMESTAMP AS goal_start UNION ALL
      SELECT 102 AS id, 'Retailer 2' AS name, 10 AS sales_goal, '2025-02-01Z'::TIMESTAMP AS goal_start UNION ALL
      SELECT 103 AS id, 'Retailer 3' AS name, 10 AS sales_goal, '2025-02-01Z'::TIMESTAMP AS goal_start

    joins:
      - name: store
        sql: '{CUBE.id} = {store.retailer_id}'
        relationship: one_to_many

    dimensions:
      - name: id
        sql: "{CUBE}.id"
        type: number
        primary_key: true
      
      - name: name
        sql: "{CUBE}.name"
        type: string
      
      - name: goal_start
        sql: "{CUBE}.goal_start"
        type: time

      - name: sales
        sql: "{store.total_sales}"
        type: number
        sub_query: true

      - name: sales_for_goal
        sql: "{store.total_sales_for_goal}"
        type: number
        sub_query: true
    
    measures:
      - name: sales_goal
        sql: "{CUBE}.sales_goal"
        type: sum

      - name: sales_goal_achieved
        type: number
        sql: "({CUBE.sales_for_goal} / NULLIF({CUBE.sales_goal}, 0))"

  - name: store
    sql: |
      SELECT 201 AS id, 'Store 1' AS name, 101 AS retailer_id UNION ALL
      SELECT 202 AS id, 'Store 2' AS name, 101 AS retailer_id UNION ALL
      SELECT 203 AS id, 'Store 3' AS name, 101 AS retailer_id UNION ALL
      SELECT 204 AS id, 'Store 4' AS name, 102 AS retailer_id UNION ALL
      SELECT 205 AS id, 'Store 5' AS name, 102 AS retailer_id UNION ALL
      SELECT 206 AS id, 'Store 6' AS name, 102 AS retailer_id UNION ALL
      SELECT 207 AS id, 'Store 7' AS name, 103 AS retailer_id UNION ALL
      SELECT 208 AS id, 'Store 8' AS name, 103 AS retailer_id UNION ALL
      SELECT 209 AS id, 'Store 9' AS name, 103 AS retailer_id

    joins:
      - name: sales
        sql: '{CUBE.id} = {sales.store_id}'
        relationship: one_to_many

    dimensions:
      - name: id
        sql: "{CUBE}.id"
        type: number
        primary_key: true
      
      - name: name
        sql: "{CUBE}.name"
        type: string
      
      - name: retailer_id
        sql: "{CUBE}.retailer_id"
        type: number

      - name: goal_start
        sql: "{retailer.goal_start}"
        type: time

      - name: sales
        sql: "{sales.total_sales}"
        type: number
        sub_query: true

      - name: sales_for_goal
        sql: "{sales.total_sales_for_goal}"
        type: number
        sub_query: true

    measures:
      - name: total_sales
        sql: "{CUBE.sales}"
        type: sum

      - name: total_sales_for_goal
        sql: "{CUBE.sales_for_goal}"
        type: sum

  - name: sales
    sql: |
      SELECT 301 AS id, 201 AS store_id, '2025-01-01Z'::TIMESTAMP AS order_date, 1 AS sales UNION ALL
      SELECT 302 AS id, 202 AS store_id, '2025-01-01Z'::TIMESTAMP AS order_date, 1 AS sales UNION ALL
      SELECT 303 AS id, 203 AS store_id, '2025-01-01Z'::TIMESTAMP AS order_date, 1 AS sales UNION ALL
      SELECT 304 AS id, 204 AS store_id, '2025-01-01Z'::TIMESTAMP AS order_date, 3 AS sales UNION ALL
      SELECT 305 AS id, 205 AS store_id, '2025-01-01Z'::TIMESTAMP AS order_date, 3 AS sales UNION ALL
      SELECT 306 AS id, 206 AS store_id, '2025-01-01Z'::TIMESTAMP AS order_date, 3 AS sales UNION ALL
      SELECT 307 AS id, 207 AS store_id, '2025-01-01Z'::TIMESTAMP AS order_date, 5 AS sales UNION ALL
      SELECT 308 AS id, 208 AS store_id, '2025-01-01Z'::TIMESTAMP AS order_date, 5 AS sales UNION ALL
      SELECT 309 AS id, 209 AS store_id, '2025-01-01Z'::TIMESTAMP AS order_date, 5 AS sales UNION ALL
      SELECT 310 AS id, 201 AS store_id, '2025-02-01Z'::TIMESTAMP AS order_date, 1 AS sales UNION ALL
      SELECT 311 AS id, 202 AS store_id, '2025-02-01Z'::TIMESTAMP AS order_date, 1 AS sales UNION ALL
      SELECT 312 AS id, 203 AS store_id, '2025-02-01Z'::TIMESTAMP AS order_date, 1 AS sales UNION ALL
      SELECT 313 AS id, 204 AS store_id, '2025-02-01Z'::TIMESTAMP AS order_date, 3 AS sales UNION ALL
      SELECT 314 AS id, 205 AS store_id, '2025-02-01Z'::TIMESTAMP AS order_date, 3 AS sales UNION ALL
      SELECT 315 AS id, 206 AS store_id, '2025-02-01Z'::TIMESTAMP AS order_date, 3 AS sales UNION ALL
      SELECT 316 AS id, 207 AS store_id, '2025-02-01Z'::TIMESTAMP AS order_date, 5 AS sales UNION ALL
      SELECT 317 AS id, 208 AS store_id, '2025-02-01Z'::TIMESTAMP AS order_date, 5 AS sales UNION ALL
      SELECT 318 AS id, 209 AS store_id, '2025-02-01Z'::TIMESTAMP AS order_date, 5 AS sales

    dimensions:
      - name: id
        sql: "{CUBE}.id"
        type: number
        primary_key: true 

      - name: store_id
        sql: "{CUBE}.store_id"
        type: number
      
      - name: order_date
        sql: "{CUBE}.order_date"
        type: time

      - name: goal_start
        sql: "{store.goal_start}"
        type: time
      
      - name: sales
        sql: "{CUBE}.sales"
        type: number
      
    measures:
      - name: total_sales
        sql: "{CUBE.sales}"
        type: sum

      - name: total_sales_for_goal
        sql: "{CUBE.sales}"
        type: sum
        filters:
          - sql: "{CUBE.order_date} >= {CUBE.goal_start}"
```

The total sales for a store and total sales for a retailer are calculated via [subquery
dimensions][ref-subquery-dimension]. If you look at the join path (`retailer.store.sales`),
you would see the *upstream flow* of data: the aggregation over sales is passed from the
`sales` cube to the `store` cube and then to the `retailer` cube.

At the same time, the `goal_start` date is passed from the `retailer` cube to the `store`
cube and then to the `sales` cube, creating the *downstream flow* of data. This way, the
`total_sales_for_goal` measure in the `sales` cube can be filtered by the `goal_start` date.

This pattern of passing measures (aggregates) *upstream* by the join path and passing
dimensions *downstream* is an effective way to solve many data modeling tasks, including
calculating filtered aggregates.

## Result

Querying the `retailer` cube will return the total sales for each retailer and the total
sales for each retailer after the `goal_start` date. The `sales_goal_achieved` measure
will show the ratio of the sales goal that has been achieved:

<Frame>
  <img />
</Frame>

[ref-subquery-dimension]: /docs/data-modeling/dimensions#subquery-dimensions


# Calculating nested aggregates
Source: https://docs.cube.dev/recipes/data-modeling/nested-aggregates

Express aggregates-of-aggregates—such as a median of per-group sums—by splitting inner and outer rollups across joined cubes and subquery dimensions.

## Use case

Sometimes, there's a need to calculate a double aggregation over a fact
table. For example, if you have a `line_items` table that has `store_id`,
`order_id`, and `sales` columns, you might wonder what is the median of
*sales per product* for each store.

With an ad-hoc SQL query, this double aggregation would probably
be expressed as follows:

```sql theme={"dark"}
WITH sales_per_store_product AS (
  SELECT store_id, product_id, SUM(sales) AS sales
  FROM line_items
  GROUP BY 1, 2
)

SELECT store_id, PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY sales) AS sales_median
FROM sales_per_store_product
GROUP BY 1
```

## Data modeling

In Cube, [measures][ref-measures] are used to define aggregates. However,
a single measure can only contain a single aggregation, e.g., `SUM`,
`APPROX_COUNT_DISTINCT`, or `PERCENTILE_CONT`.

If you'd like to define a double aggregation, e.g., a median of a sum of
values, the *outer* aggregation would need to be defined in a separate
[cube][ref-cube] and the *inner* aggregation (measure) would need to be
brought to that cube as a [subquery dimension][ref-subquery-dimension].
Also, these cubes would need to have a join definition between them.

Consider the following data model:

```yaml theme={"dark"}
cubes:
  - name: nested_agg_sales
    sql: |
      SELECT 1 AS id, 1 AS store_id, 1 AS product_id, 10 AS sales UNION ALL
      SELECT 2 AS id, 1 AS store_id, 1 AS product_id, 20 AS sales UNION ALL
      SELECT 3 AS id, 1 AS store_id, 2 AS product_id, 30 AS sales UNION ALL
      SELECT 4 AS id, 1 AS store_id, 2 AS product_id, 40 AS sales UNION ALL
      SELECT 5 AS id, 2 AS store_id, 1 AS product_id, 50 AS sales UNION ALL
      SELECT 6 AS id, 2 AS store_id, 1 AS product_id, 60 AS sales UNION ALL
      SELECT 7 AS id, 2 AS store_id, 2 AS product_id, 70 AS sales UNION ALL
      SELECT 8 AS id, 2 AS store_id, 2 AS product_id, 80 AS sales

    dimensions:
      - name: id
        sql: id
        type: number
        primary_key: true

      - name: store_id
        sql: store_id
        type: number

      - name: product_id
        sql: product_id
        type: number

      - name: store_product_id
        sql: "CONCAT({store_id}, '-', {product_id})"
        type: string

    measures:
      - name: sales
        sql: sales
        type: sum

  - name: nested_agg_stores_orders
    sql: |
      SELECT store_id, product_id
      FROM (
        SELECT 1 AS id, 1 AS store_id, 1 AS product_id, 10 AS sales UNION ALL
        SELECT 2 AS id, 1 AS store_id, 1 AS product_id, 20 AS sales UNION ALL
        SELECT 3 AS id, 1 AS store_id, 2 AS product_id, 30 AS sales UNION ALL
        SELECT 4 AS id, 1 AS store_id, 2 AS product_id, 40 AS sales UNION ALL
        SELECT 5 AS id, 2 AS store_id, 1 AS product_id, 50 AS sales UNION ALL
        SELECT 6 AS id, 2 AS store_id, 1 AS product_id, 60 AS sales UNION ALL
        SELECT 7 AS id, 2 AS store_id, 2 AS product_id, 70 AS sales UNION ALL
        SELECT 8 AS id, 2 AS store_id, 2 AS product_id, 80 AS sales
      ) AS raw
      GROUP BY 1, 2

    joins:
      - name: nested_agg_sales
        sql: "{nested_agg_stores_orders.store_product_id} = {nested_agg_sales.store_product_id}"
        relationship: one_to_many

    dimensions:
      - name: store_id
        sql: store_id
        type: number

      - name: product_id
        sql: product_id
        type: number

      - name: store_product_id
        sql: "CONCAT({store_id}, '-', {product_id})"
        type: string
        primary_key: true

      - name: sales_sum
        sql: "{nested_agg_sales.sales}"
        type: number
        sub_query: true

    measures:
      - name: median_sales
        sql: "PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY {sales_sum})"
        type: number
```

As you can see, the sum of sales for per store and per product is defined
in the `nested_agg_sales` cube as the `sales` measure. Then, it is brought
to the `nested_agg_stores_orders` cube as `sales_sum` that is defined as
a subquery dimension. Also, a join is defined between both cubes.

Then, the median of sales is defined as the `median_sales` measure in the
`nested_agg_stores_orders` cube. It’s OK to reference `sales_sum` in this
measure because now it's a dimension; referencing a measure from another
cube here would not work.

## Result

Querying the `median_sales` measure would give the expected result:

<Frame>
  <img />
</Frame>

We can verify that it's correct by adding one more dimension to the query:

<Frame>
  <img />
</Frame>

[ref-measures]: /reference/data-modeling/measures

[ref-cube]: /reference/data-modeling/cube

[ref-subquery-dimension]: /docs/data-modeling/dimensions#subquery-dimensions


# Passing dynamic parameters in a query
Source: https://docs.cube.dev/recipes/data-modeling/passing-dynamic-parameters-in-a-query

In some cases we may want to let a user select a filter value and be able to use that value in calculations without filtering the entire query.

## Use case

In some cases we may want to let a user select a filter value and be able to
use that value in calculations without filtering the entire query.

In this example, we want to know the ratio between the number of people in a particular city and
the total number of women in the country. The user can specify the city for the
filter. The trick is to get the value of the city from the user and use it in
the calculation. In the recipe below, we can learn how to join the data table
with itself and reshape the dataset!

<Warning>
  This pattern only allows users to choose from values that already exist in the data set. Rather than injecting arbitrary user input into the query, this method involves filtering the data based on the user's input and utilizing a single value result in a calculation.
</Warning>

## Data modeling

Essentially what we will be doing is allowing the user to select a specific city value, then cross joining that value with the rows in the data table.
This will maintain the orginal number of rows in the dataset while adding a new column that has the value that the user chose.
This will allow us to use that value in our calculations.
In this case, we will use that value to filter a single metric so that we can compare that metric with the whole population.

Let's explore the `users` cube data that contains various information about
users, including city and gender:

| id  | city     | gender | name            |
| --- | -------- | ------ | --------------- |
| 1   | Seattle  | female | Wendell Hamill  |
| 2   | Chicago  | male   | Rahsaan Collins |
| 3   | New York | female | Megane O'Kon    |
| ... | ...      | ...    | ...             |

To calculate the ratio between the number of women in a particular city and the
total number of people in the country, we need to define three measures, one of
which uses the city value that the user chose.

In order to prevent filtering the whole dataset with the user-selected value,
we will need to define a new dimension that, when filtered on, only filters a specific part of the query.
We will use this new filter field along with the [`FILTER_PARAMS`][ref-filter-params]
parameter in the sql of the cube. This will allow us to apply to the filter to a subquery
rather than the whole query so that it doesn't affect other calculations.
In this use case, we can join the data table with itself to create a new city\_filter
column with a single value that the user chose so that we can use it in other calculations.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql: |
        WITH data AS (
          SELECT
            users.id AS id,
            users.city AS city,
            users.gender AS gender
          FROM public.users
        ),
        cities AS (
          SELECT city
          FROM data
          WHERE {FILTER_PARAMS.users.city.filter('city')}
        ),
        grouped AS (
          SELECT
            cities.city AS city_filter,
            data.id AS id,
            data.city AS city,
            data.gender AS gender
          FROM cities, data
          GROUP BY 1, 2, 3, 4
        )
        SELECT *
        FROM grouped

      measures:
        - name: total_number_of_women
          sql: id
          type: count
          filters:
            - sql: "gender = 'female'"

        - name: number_of_people_of_any_gender_in_the_city:
          sql: id
          type: count
          filters:
            - sql: "city = city_filter"

        - name: ratio
          title: Ratio Women in the City to Total Number of People
          sql: |
            1.0 * {number_of_people_of_any_gender_in_the_city} /
            {total_number_of_women}
          type: number

      dimensions:
        - name: city_filter
          sql: city_filter
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql: `
      WITH data AS (
        SELECT
          users.id AS id,
          users.city AS city,
          users.gender AS gender
        FROM public.users
      ),

      cities AS (
        SELECT city
        FROM data
        WHERE ${FILTER_PARAMS.users.city.filter('city')}
      ),

      grouped AS (
        SELECT
          cities.city AS city_filter,
          data.id AS id,
          data.city AS city,
          data.gender AS gender
        FROM cities, data
        GROUP BY 1, 2, 3, 4
      )

      SELECT *
      FROM grouped
    `,

    measures: {
      total_number_of_women: {
        sql: "id",
        type: "count",
        filters: [{ sql: `${CUBE}.gender = 'female'` }]
      },

      number_of_people_of_any_gender_in_the_city: {
        sql: "id",
        type: "count",
        filters: [{ sql: `${CUBE}.city = ${CUBE}.city_filter` }]
      },

      ratio: {
        title: "Ratio Women in the City to Total Number of People",
        sql: `
          1.0 * ${CUBE.number_of_people_of_any_gender_in_the_city} /
          ${CUBE.total_number_of_women}`,
        type: `number`
      }
    },

    dimensions: {
      city_filter: {
        sql: `city_filter`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

The above code shows very clearly what is happening, but it is even simplier to define the sql parameter in the following way:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql: |
        WITH 
        city AS (
          SELECT DISTINCT city AS city_filter
          FROM public.users
          WHERE {FILTER_PARAMS.users.city.filter('city')}
          )
        SELECT city.city_filter, users.*
        FROM city, public.users
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql: `
      WITH 
      city AS (
        SELECT DISTINCT city AS city_filter
        FROM public.users
        WHERE {FILTER_PARAMS.users.city.filter('city')}
        )
      SELECT city.city_filter, users.*
      FROM city, public.users
    `,
  ```
</CodeGroup>

## Result

By joining the data table with itself and filtering on `city_filter`, we get the
ratio for the chosen city without affecting the total denominator. For example,
when filtering for Seattle:

| total\_number\_of\_women | number\_of\_people\_in\_city |  ratio |
| -----------------------: | ---------------------------: | -----: |
|                      259 |                           99 | 38.22% |

[ref-filter-params]: /reference/data-modeling/context-variables#filter_params


# Calculating averages and percentiles
Source: https://docs.cube.dev/recipes/data-modeling/percentiles

Learn how to model and query percentile-based metrics alongside averages so skewed numeric distributions are represented accurately in Cube.

## Use case

We want to understand the distribution of values for a certain numeric property
within a dataset. We're used to average values and intuitively understand how to
calculate them. However, we also know that average values can be misleading for
[skewed](https://en.wikipedia.org/wiki/Skewness) distributions which are common
in the real world: for example, 2.5 is the average value for both `(1, 2, 3, 4)`
and `(0, 0, 0, 10)`.

So, it's usually better to use
[percentiles](https://en.wikipedia.org/wiki/Percentile). Parameterized by a
fractional number `n = 0..1`, where the n-th percentile is equal to a value that
exceeds a specified ratio of values in the distribution. The
[median](https://en.wikipedia.org/wiki/Median) is a special case: it's defined
as the 50th percentile (`n = 0.5`), and it can be casually thought of as "the
middle" value. 2.5 and 0 are the medians of `(1, 2, 3, 4)` and `(0, 0, 0, 10)`,
respectively.

## Data modeling

Let's explore the data in the `users` cube that contains various demographic
information about users, including their age:

| name            | age |
| --------------- | --: |
| Abbott, Breanne |  52 |
| Abbott, Dallas  |  43 |
| Abbott, Gia     |  36 |
| Abbott, Tom     |  39 |
| Abbott, Ward    |  67 |

Calculating the average age is as simple as defining a measure with the built-in
[`avg` type](/reference/data-modeling/measures#type).

Calculating the percentiles would require using database-specific functions.
However, almost every database has them under names of `PERCENTILE_CONT` and
`PERCENTILE_DISC`,
[Postgres](https://www.postgresql.org/docs/current/functions-aggregate.html) and
[Snowflake](https://docs.snowflake.com/en/sql-reference/functions-aggregation)
included. For [BigQuery](https://cloud.google.com/bigquery/docs/reference/standard-sql/functions-and-operators#approx_quantiles),
you'd need to use the `APPROX_QUANTILES` function.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      # ...

      measures:
        - name: avg_age
          type: avg
          sql: age

        - name: median_age
          type: number
          sql: PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY age)

        - name: p95_age
          type: number
          sql: PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY age)
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("users", {
    measures: {
      avg_age: {
        sql: `age`,
        type: `avg`
      },

      median_age: {
        sql: `PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY age)`,
        type: `number`
      },

      p95_age: {
        sql: `PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY age)`,
        type: `number`
      }
    }
  })
  ```
</CodeGroup>

## Result

Using the measures defined above, you can explore statistics about the age of
your users. For a typical dataset, the average age closely matches the median
age, and the 95th percentile reveals the upper bound for the vast majority of
users — for example, if `p95_age` returns 82, then 95% of all users are
younger than 82 years.


# Calculating period-over-period changes
Source: https://docs.cube.dev/recipes/data-modeling/period-over-period

Often, there's a need to calculate a period-over-period change in a metric, e.g., week-over-week or month-over-month growth of clicks, orders, revenue, etc.

## Use case

Often, there's a need to calculate a period-over-period change in a
metric, e.g., week-over-week or month-over-month growth of clicks, orders,
revenue, etc.

<Note>
  This recipe compares against a single fixed interval. To let a data consumer choose the
  interval (and the rolling window) at query time, see [Configurable rolling
  windows](/recipes/data-modeling/dynamic-rolling-windows).
</Note>

## Data modeling

In Cube, calculating a period-over-period metric involves the following
steps:

* Define a [multi-stage measure][ref-multi-stage] for the *current period*.
* Define a [time-shift measure][link-time-shift] that references the current
  period measure and shifts it to the *previous period*.
* Define a [calculated measure][ref-calculated-measure] that references
  these measures and uses them in a calculation, e.g., divides or subtracts them.

<Warning>
  Multi-stage calculations are powered by Tesseract, the [next-generation data modeling
  engine][link-tesseract]. In versions before v1.7.0, it was not enabled by default.
</Warning>

The following data model allows to calculate a month-over-month change of
some value. `current_month_sum` is the base measure, `previous_month_sum`
is a time-shift measure that shifts the current month data to the previous
month, and the `month_over_month_ratio` measure divides their values:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: month_over_month
      sql: |
        SELECT 1 AS value, '2024-01-01'::TIMESTAMP AS date UNION ALL
        SELECT 2 AS value, '2024-01-01'::TIMESTAMP AS date UNION ALL
        SELECT 3 AS value, '2024-02-01'::TIMESTAMP AS date UNION ALL
        SELECT 4 AS value, '2024-02-01'::TIMESTAMP AS date UNION ALL
        SELECT 5 AS value, '2024-03-01'::TIMESTAMP AS date UNION ALL
        SELECT 6 AS value, '2024-03-01'::TIMESTAMP AS date UNION ALL
        SELECT 7 AS value, '2024-04-01'::TIMESTAMP AS date UNION ALL
        SELECT 8 AS value, '2024-04-01'::TIMESTAMP AS date

      dimensions:
        - name: date
          sql: date
          type: time

      measures:
        - name: current_month_sum
          sql: value
          type: sum

        - name: previous_month_sum
          multi_stage: true
          sql: "{current_month_sum}"
          type: number
          time_shift:
            - interval: 1 month
              type: prior

        - name: month_over_month_ratio
          multi_stage: true
          sql: "{current_month_sum} / NULLIF({previous_month_sum}, 0)"
          type: number
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`month_over_month`, {
    sql: `
      SELECT 1 AS value, '2024-01-01'::TIMESTAMP AS date UNION ALL
      SELECT 2 AS value, '2024-01-01'::TIMESTAMP AS date UNION ALL
      SELECT 3 AS value, '2024-02-01'::TIMESTAMP AS date UNION ALL
      SELECT 4 AS value, '2024-02-01'::TIMESTAMP AS date UNION ALL
      SELECT 5 AS value, '2024-03-01'::TIMESTAMP AS date UNION ALL
      SELECT 6 AS value, '2024-03-01'::TIMESTAMP AS date UNION ALL
      SELECT 7 AS value, '2024-04-01'::TIMESTAMP AS date UNION ALL
      SELECT 8 AS value, '2024-04-01'::TIMESTAMP AS date
    `,

    dimensions: {
      date: {
        sql: `date`,
        type: `time`
      }
    },

    measures: {
      current_month_sum: {
        sql: `value`,
        type: `sum`
      },

      previous_month_sum: {
        multi_stage: true,
        sql: `${current_month_sum}`,
        type: `number`,
        time_shift: [{
          interval: `1 month`,
          type: `prior`
        }]
      },

      month_over_month_ratio: {
        multi_stage: true,
        sql: `${current_month_sum} / NULLIF(${previous_month_sum}, 0)`,
        type: `number`
      }
    }
  })
  ```
</CodeGroup>

## Result

When querying period-over-period measures, use a time dimension with a
[granularity][ref-time-dimension-granularity] that matches the period — e.g.,
`month` for month-over-month calculations:

<Frame>
  <img />
</Frame>

[ref-multi-stage]: /docs/data-modeling/measures#multi-stage-measures

[ref-calculated-measure]: /docs/data-modeling/overview#4-using-calculated-measures

[ref-time-dimension-granularity]: /reference/core-data-apis/rest-api/query-format#time-dimensions-format

[link-tesseract]: https://cube.dev/blog/introducing-next-generation-data-modeling-engine

[link-time-shift]: /docs/data-modeling/measures#time-shift


# Polymorphic cubes
Source: https://docs.cube.dev/recipes/data-modeling/polymorphic-cubes

Models one shared fact or dimension table that represents multiple entity types by extending a base cube into type-specific cubes with correct joins and logic.

In programming languages, polymorphism usually means the use of a single symbol
to represent multiple different types. It can be quite common for a database and
application to be designed in such a way that leverages a single database table
for entities of different types that share common traits.

For example, you are working on an online education platform, where teachers
assign lessons to students. The database can contain only two tables: one for
`users` and another one for `lessons`. The `users` table can contain a `type`
column, with possible values `teacher` or `student`. Here is how it could look:

| **id** | **type** | **name**       | **school**         |
| ------ | -------- | -------------- | ------------------ |
| 1      | student  | Carl Anderson  | Balboa High School |
| 2      | student  | Luke Skywalker | Balboa High School |
| 31     | teacher  | John Doe       | Balboa High School |

Lessons are assigned by teachers and completed by students. The `lessons` table
has both `teacher_id` and `student_id`, which are actually references to the
`user id`. The `lessons` table can look like this:

| **id** | **teacher\_id** | **student\_id** | **name**                                      |
| ------ | --------------- | --------------- | --------------------------------------------- |
| 100    | 31              | 1               | Multiplication and the meaning of the Factors |
| 101    | 31              | 2               | Division as an Unknown Factor Problem         |

The best way to design such a data model is by using what we call **Polymorphic
Cubes**. It relies on the [`extends`][ref-schema-ref-cubes-extends] feature and
prevents you from duplicating code, while preserving the correct domain logic.
Learn more about using [`extends` here][ref-schema-advanced-extend].

The first step is to create a `user` cube, which will act as a base cube for our
`teachers` and `students` cubes and will contain all common measures and
dimensions:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql: SELECT * FROM users

      measures:
        - name: count
          type: count

      dimensions:
        - name: name
          sql: name
          type: string

        - name: school
          sql: school
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql: `SELECT * FROM users`,

    measures: {
      count: {
        type: `count`
      }
    },

    dimensions: {
      name: {
        sql: `name`,
        type: `string`
      },

      school: {
        sql: `school`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

Then you can derive the `teachers` and `students` cubes from `users`:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: teachers
      extends: users
      sql: |
        SELECT *
        FROM {users.sql()}
        WHERE type = 'teacher'

    - name: students
      extends: users
      sql: |
        SELECT *
        FROM {users.sql()}
        WHERE type = 'student'
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`teachers`, {
    extends: users,
    sql: `
      SELECT *
      FROM ${users.sql()}
      WHERE type = 'teacher'
    `
  })

  cube(`students`, {
    extends: users,
    sql: `
      SELECT *
      FROM ${users.sql()}
      WHERE type = 'student'
    `
  })
  ```
</CodeGroup>

Once we have those cubes, we can define correct joins from the `lessons` cube:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: lessons
      sql_table: lessons

      joins:
        - name: students
          relationship: many_to_one
          sql: "{CUBE}.student_id = {students.id}"

        - name: teachers
          relationship: many_to_one
          sql: "{CUBE}.teacher_id = {teachers.id}"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`lessons`, {
    sql_table: `lessons`,

    joins: {
      students: {
        relationship: `many_to_one`,
        sql: `${CUBE}.student_id = ${students.id}`
      },

      teachers: {
        relationship: `many_to_one`,
        sql: `${CUBE}.teacher_id = ${teachers.id}`
      }
    }
  })
  ```
</CodeGroup>

[ref-schema-advanced-extend]: /docs/data-modeling/extending-cubes

[ref-schema-ref-cubes-extends]: /reference/data-modeling/cube#extends


# Calculating share of total
Source: https://docs.cube.dev/recipes/data-modeling/share-of-total

Compute each dimension member's contribution to the grand total—or to a fixed subtotal—using calculated fields or multi-stage measures.

## Use case

A common analytics need is to show each row's contribution to the overall
total. For example, given revenue broken down by product brand, you might want
to display what percentage of all revenue each brand represents:

| brand            |  revenue | share of total |
| ---------------- | -------: | -------------: |
| American Apparel |  \$5,930 |         28.98% |
| Patagonia        |    \$239 |          1.17% |
| Columbia         | \$14,302 |         69.85% |

There are two ways to achieve this in Cube:

* **[Calculated fields](#using-calculated-fields)** — add a % of total column
  directly in a workbook without any data model changes. Best for ad-hoc
  exploration.
* **[Data modeling](#data-modeling)** — define the share measure in the
  semantic model so it is available everywhere: APIs, embedded analytics, AI
  agents, and Explore. Best for a metric that should be reusable across the
  product.

## Using calculated fields

[Calculated fields][ref-calculated-fields] let you add derived columns to a
workbook report without touching the data model.

To add a % of total column:

1. Build a table with the `products.brand` dimension and the
   `order_items.total_sale_price` measure.
2. Open the header menu on the `Total Sale Price` column.
3. Choose **Calculations → % of total**.

Cube adds a calculated field that divides each row's value by the sum across
all rows in the result.

<Frame>
  <img />
</Frame>

<Note>
  `% of total` is available for measures with **Count** or **Sum** aggregation
  types. See [Calculated fields][ref-calculated-fields] for the full list of
  built-in calculations and how to edit them.
</Note>

## Data modeling

When the share measure needs to be part of the semantic model — so it is
returned by the API, visible in Explore, or accessible to AI agents — define
it using multi-stage measures powered by [Tesseract][link-tesseract].

The key building block is the [`grain`][ref-grain] parameter with `keep_only`:
when set to an empty list, the inner aggregation stage groups by *nothing*,
computing the grand total across all rows. The outer stage then joins that total
back and groups by the query's dimensions as usual.

<Warning>
  Multi-stage calculations are powered by Tesseract, the [next-generation data
  modeling engine][link-tesseract]. In versions before v1.7.0, it was not enabled by default.
</Warning>

Calculating share of total requires three measures:

1. A **base measure** — the regular aggregate, e.g., `total_sale_price`.
2. A **helper measure** — a multi-stage measure that re-aggregates the base
   measure with `grain` set to `keep_only: []`, fixing the inner `GROUP BY` to
   nothing (the grand total). This measure is internal and should be hidden from
   views.
3. A **ratio measure** — a multi-stage measure that divides the base by the
   helper total.

The examples below extend the `order_items` cube from the
[ecommerce demo model][link-ecommerce-demo]. The `brand` and `category`
dimensions are proxied from the joined `products` cube so they can be
referenced by `grain`.

### Share of grand total

Add the three measures to `order_items`:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: order_items
      sql_table: ECOMMERCE.ORDER_ITEMS

      joins:
        - name: products
          sql: "{CUBE.product_id} = {products.id}"
          relationship: many_to_one

      dimensions:
        - name: id
          sql: ID
          type: number
          primary_key: true

        - name: brand
          sql: "{products.brand}"
          type: string

      measures:
        - name: total_sale_price
          sql: SALE_PRICE
          type: sum
          format: currency

        - name: total_revenue_grand_total
          multi_stage: true
          sql: "{total_sale_price}"
          type: sum
          grain:
            keep_only: []

        - name: revenue_share
          multi_stage: true
          sql: "1.0 * {total_sale_price} / NULLIF({total_revenue_grand_total}, 0)"
          type: number
          format: percent
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`order_items`, {
    sql_table: `ECOMMERCE.ORDER_ITEMS`,

    joins: {
      products: {
        sql: `${CUBE.product_id} = ${products.id}`,
        relationship: `many_to_one`
      }
    },

    dimensions: {
      id: {
        sql: `ID`,
        type: `number`,
        primary_key: true
      },
      brand: {
        sql: `${products.brand}`,
        type: `string`
      }
    },

    measures: {
      total_sale_price: {
        sql: `SALE_PRICE`,
        type: `sum`,
        format: `currency`
      },

      total_revenue_grand_total: {
        multi_stage: true,
        sql: `${total_sale_price}`,
        type: `sum`,
        grain: {
          keep_only: []
        }
      },

      revenue_share: {
        multi_stage: true,
        sql: `1.0 * ${total_sale_price} / NULLIF(${total_revenue_grand_total}, 0)`,
        type: `number`,
        format: `percent`
      }
    }
  })
  ```
</CodeGroup>

`keep_only: []` tells Tesseract that the inner stage for `total_revenue_grand_total`
should group by no dimensions, producing a single grand-total row. The outer stage
joins it back and groups by whatever dimensions are in the query (e.g., `brand`),
so every row receives the same total denominator.

### Hiding the helper measure from views

`total_revenue_grand_total` is a computation artifact — its value never changes
with dimension grouping, so it is meaningless to end users on its own. Exclude it
from the view using the `excludes` key while keeping `includes: "*"` for everything
else:

```yaml theme={"dark"}
views:
  - name: orders_transactions
    cubes:
      - join_path: order_items
        includes: "*"
        excludes:
          - total_revenue_grand_total

      - join_path: order_items.products
        prefix: true
        includes: "*"

      # ... other join paths
```

Only `total_sale_price` and `revenue_share` are exposed to consumers of the view.

### Share of a fixed subtotal

Sometimes you want each row's share *within a category* rather than the
overall total — for example, each brand's share of its product category's
revenue.

Use `grain` with `keep_only` set to the dimension you want to *fix* as the
subtotal boundary. The inner stage will group only by that dimension, and the
outer stage will group by the full set of query dimensions:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: order_items
      sql_table: ECOMMERCE.ORDER_ITEMS

      joins:
        - name: products
          sql: "{CUBE.product_id} = {products.id}"
          relationship: many_to_one

      dimensions:
        - name: id
          sql: ID
          type: number
          primary_key: true

        - name: brand
          sql: "{products.brand}"
          type: string

        - name: category
          sql: "{products.category}"
          type: string

      measures:
        - name: total_sale_price
          sql: SALE_PRICE
          type: sum
          format: currency

        - name: category_revenue_grand_total
          multi_stage: true
          sql: "{total_sale_price}"
          type: sum
          grain:
            keep_only:
              - category

        - name: revenue_share_of_category
          multi_stage: true
          sql: "1.0 * {total_sale_price} / NULLIF({category_revenue_grand_total}, 0)"
          type: number
          format: percent
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`order_items`, {
    sql_table: `ECOMMERCE.ORDER_ITEMS`,

    joins: {
      products: {
        sql: `${CUBE.product_id} = ${products.id}`,
        relationship: `many_to_one`
      }
    },

    dimensions: {
      id: {
        sql: `ID`,
        type: `number`,
        primary_key: true
      },
      brand: {
        sql: `${products.brand}`,
        type: `string`
      },
      category: {
        sql: `${products.category}`,
        type: `string`
      }
    },

    measures: {
      total_sale_price: {
        sql: `SALE_PRICE`,
        type: `sum`,
        format: `currency`
      },

      category_revenue_grand_total: {
        multi_stage: true,
        sql: `${total_sale_price}`,
        type: `sum`,
        grain: {
          keep_only: [`category`]
        }
      },

      revenue_share_of_category: {
        multi_stage: true,
        sql: `1.0 * ${total_sale_price} / NULLIF(${category_revenue_grand_total}, 0)`,
        type: `number`,
        format: `percent`
      }
    }
  })
  ```
</CodeGroup>

With `keep_only: [category]`, the inner stage computes revenue per category.
The outer stage groups by both `category` and `brand`, so each brand row
divides its revenue by the right category total. Exclude
`category_revenue_grand_total` from the view the same way as shown above.

## Result

Because `total_revenue_grand_total` is excluded from the view, only the
meaningful measures — `total_sale_price` and `revenue_share` — are visible
to end users in Explore, workbooks, and the API.

<Frame>
  <img />
</Frame>

<Note>
  Query filters applied to the dimension used in share calculations (e.g.,
  filtering to a specific brand) will also filter the data used to compute
  the total, making that row's share appear as 100%. To keep the total
  unaffected by such filters, use the [`filter`][ref-filter] parameter to
  exclude them from the helper measure — see [share of total (filter
  override)][ref-share-filter].
</Note>

[link-tesseract]: https://cube.dev/blog/introducing-next-generation-data-modeling-engine

[link-ecommerce-demo]: https://github.com/cubedevinc/ecommerce_demo

[ref-grain]: /reference/data-modeling/measures#grain

[ref-filter]: /reference/data-modeling/measures#filter

[ref-share-filter]: /docs/data-modeling/measures#share-of-total-filter-override

[ref-dynamic-params]: /recipes/data-modeling/passing-dynamic-parameters-in-a-query

[ref-calculated-fields]: /docs/explore-analyze/workbooks/calculated-fields


# Implementing data snapshots
Source: https://docs.cube.dev/recipes/data-modeling/snapshots

Build point-in-time snapshots from change-history data so you can report the latest status of an entity as of any date.

## Use case

For a dataset that contains a sequence of changes to a property over time, we
want to be able to get the most recent state of said property at any given date.
In this recipe, we'll learn how to calculate snapshots of statuses at any given
date for a cube with `Product Id`, `Status`, and `Changed At` dimensions.

<Info>
  We can consider the status property to be a
  [slowly changing dimension](https://en.wikipedia.org/wiki/Slowly_changing_dimension)
  (SCD) of type 2. Modeling data with slowly changing dimensions is an essential
  part of the data engineering skillset.
</Info>

## Data modeling

Let's explore the `statuses` cube that contains data like this:

| order\_id | status     | changed\_at         |
| --------: | ---------- | ------------------- |
|         1 | shipped    | 2019-01-19 00:00:00 |
|         1 | processing | 2019-03-14 00:00:00 |
|         1 | completed  | 2019-01-25 00:00:00 |
|         2 | processing | 2019-08-21 00:00:00 |
|         2 | completed  | 2019-04-13 00:00:00 |
|         2 | shipped    | 2019-03-18 00:00:00 |

We can see that statuses change occasionally. How do we count orders that
remained in the `shipped` status at a particular date?

First, we need to generate a range with all dates of interest, from the earliest
to the latest. Second, we need to join the dates with the statuses and leave
only the most recent statuses to date.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: status_snapshots
      extends: statuses
      sql: |
        -- Create a range from the earlist date to the latest date
        WITH range AS (
          SELECT date
          FROM GENERATE_SERIES(
            (SELECT MIN(changed_at) FROM {statuses.sql()} AS statuses),
            (SELECT MAX(changed_at) FROM {statuses.sql()} AS statuses),
            INTERVAL '1 DAY'
          ) AS date
        )

        -- Calculate snapshots for every date in the range
        SELECT range.date, statuses.*
        FROM range
        LEFT JOIN {statuses.sql()} AS statuses
          ON range.date >= statuses.changed_at
          AND statuses.changed_at = (
            SELECT MAX(changed_at)
            FROM {statuses.sql()} AS sub_statuses
            WHERE sub_statuses.order_id = statuses.order_id
          )
      dimensions:
        - name: date
          sql: date
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`status_snapshots`, {
    extends: statuses,

    sql: `
      -- Create a range from the earlist date to the latest date
      WITH range AS (
        SELECT date
        FROM GENERATE_SERIES(
          (SELECT MIN(changed_at) FROM ${statuses.sql()} AS statuses),
          (SELECT MAX(changed_at) FROM ${statuses.sql()} AS statuses),
          INTERVAL '1 DAY'
        ) AS date
      )

      -- Calculate snapshots for every date in the range
      SELECT range.date, statuses.*
      FROM range
      LEFT JOIN ${statuses.sql()} AS statuses
        ON range.date >= statuses.changed_at
        AND statuses.changed_at = (
          SELECT MAX(changed_at)
          FROM ${statuses.sql()} AS sub_statuses
          WHERE sub_statuses.order_id = statuses.order_id
        )
    `,

    dimensions: {
      date: {
        sql: `date`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

<Info>
  To generate a range of dates, here we use the
  [`GENERATE_SERIES` function](https://www.postgresql.org/docs/9.1/functions-srf.html)
  which is Postgres-specific. Other databases have similar functions, e.g.,
  [`GENERATE_DATE_ARRAY`](https://cloud.google.com/bigquery/docs/reference/standard-sql/array_functions#generate_date_array)
  in BigQuery.
</Info>

Please note that it makes sense to make the `status_snapshots` cube
[extend](/reference/data-modeling/cube#extends) the original `statuses`
cube in order to reuse the dimension definitions. We only need to add a new
dimension that indicates the `date` of a snapshot. We're also referencing the
definition of the `statuses` cube with the
[`sql()` property](/reference/data-modeling/cube#sql).

## Result

To count orders that remained in the `shipped` status at a particular date,
filter on both `status_snapshots.date` and `status_snapshots.status`. Running
the same query for two different dates shows how the snapshot changes over time:

| date       | status  | count |
| ---------- | ------- | ----: |
| 2019-04-01 | shipped |    16 |
| 2019-05-01 | shipped |    25 |


# Working around string time dimensions
Source: https://docs.cube.dev/recipes/data-modeling/string-time-dimensions

Cube always expects a timestamp with timezone (or compatible type) as an input to the time dimension.

However, there are a lot of cases when the underlying table's datetime
information is stored as a string. Most SQL databases support datetime
parsing which allows converting strings to timestamps. Let's consider an
example cube for BigQuery:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: events
      sql_table: schema.events

      dimensions:
        - name: date
          sql: PARSE_TIMESTAMP('%Y-%m-%d', date)
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`events`, {
    sql_table: `schema.events`,

    dimensions: {
      date: {
        sql: `PARSE_TIMESTAMP('%Y-%m-%d', date)`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

In this particular cube, the `date` column will be parsed using the
`%Y-%m-%d` format.

Please note that as we do not pass timezone parameter to
[`PARSE_TIMESTAMP`][bq-parse-timestamp], it will set `UTC` as the timezone by
default. You should always set timezone appropriately for parsed timestamps as
Cube always does timezone conversions according to user settings.

Although query performance of big data backends like BigQuery or Presto won't
likely suffer from date parsing, performance of RDBMS backends like Postgres
most likely will. Adding timestamp columns with indexes or transforming the
data upstream should strongly be considered in this case.

[ref-time-dimension]: /reference/data-modeling/dimensions#type

[bq-parse-timestamp]: https://cloud.google.com/bigquery/docs/reference/standard-sql/timestamp_functions#parse_timestamp


# Cube style guide
Source: https://docs.cube.dev/recipes/data-modeling/style-guide

This style guide includes best practices on data modeling in Cube.

While Cube allows for certain flexibility with regards to data modeling,
following this fairly opinionated style guide helps create maintainable semantic
layers and reduce effort to support them in the long run.

This style guide is intended to be used by:

* All users of Cube Cloud and self-hosted Cube Core deployments.
* Solution integrators from the [Cube Partner Network][cpn].
* Cube team (for demo projects, documentation, and customer engagements).

## Syntax

* Default to [YAML syntax][ref-syntax-model] for data modeling.
* Use [snake case][ref-syntax-naming] when using either YAML or JavaScript
  syntax.
* Follow the recommendations on [YAML syntax][self-yaml] and [SQL
  syntax][self-sql] below.

## Folder structure

* Put [cube and view files][ref-syntax-folder-structure] in `model/cubes` and
  `model/views` folders.
* Within these folders, create subfolders to reflect your business units
  structure.

```tree theme={"dark"}
cube_project
└── model
    ├── cubes
    │   ├── finance
    │   │   ├── stripe_invoices.yml
    │   │   └── stripe_payments.yml
    │   └── sales
    │       └── base_opportunities.yml
    └── views
        ├── product
        │   └── cloud_tenants.yml
        └── sales
            └── opportunities.yml
```

## Cubes

* Cubes should remain private; set [`public: false`][ref-public] for all cubes.
  Only views can be exposed to visualization tools.
* A cube's name should represent a business entity and be plural. If a cube's
  name may clash with a view's name, add the `base_` prefix to the cube's name,
  e.g., `base_opportunities.yml`.
* If possible, use [`sql_table`][ref-sql-table] instead of `sql`, i.e., use
  `sql_table: schema.table` instead of `sql: SELECT * FROM schema.table`.
* Use `many_to_one`, `one_to_many`, `one_to_one` [join relationship
  types][ref-join-rel] instead of `belongs_to`, `has_many`, `has_one`.
* Applicable [cube parameters][ref-cube-params] should be ordered as follows:
  * `name`
  * `sql_alias`
  * `extends`
  * `data_source`
  * `sql`
  * `sql_table`
  * `title`
  * `description`
  * `public`
  * `refresh_key`
  * `meta`
  * `pre_aggregations`
  * `joins`
  * `dimensions`
  * `hierarchies`
  * `segments`
  * `measures`
  * `access_policy`

### Dimensions & measures

* Primary key of the cube should be the first dimension listed.
* Applicable [dimension][ref-dimension-params] and [measure
  parameters][ref-measure-params] should be ordered as follows:
  * `name`
  * `title`
  * `description`
  * `sql`
  * `type`
  * `primary_key`
  * `sub_query`
  * `public`
  * `format`
  * `filters`
  * `drill_members`
* Use `title` and `description` if the name is not intuitive.

### Example cube

```yaml theme={"dark"}
cubes:
  - name: line_items
    sql_table: public.line_items
    public: false

    joins:
      - name: products
        sql: "{CUBE}.product_id = {products.id}"
        relationship: many_to_one

      - name: orders
        sql: "{CUBE}.order_id = {orders.id}"
        relationship: many_to_one

    dimensions:
      - name: id
        sql: id
        type: number
        primary_key: true

      - name: created_date
        sql: created_at
        type: time

    measures:
      - name: count
        type: count

      - name: total_amount
        sql: price
        type: sum
```

## Views

* Views should be designed for data consumers and optimized for consumption in
  visualization tools.
* Applicable [view parameters][ref-view-params] should be ordered as follows:
  * `name`
  * `description`
  * `public`
  * `cubes`
  * `folders`
  * `access_policy`

### Example view

```yaml theme={"dark"}
views:
  - name: orders

    cubes:
      - join_path: base_orders
        includes:
          # dimensions
          - status
          - created_date

          # measures
          - total_amount
          - total_amlunt_shipped
          - count
          - average_order_value

      - join_path: base_orders.line_items.products
        includes:
          - name: name
            alias: product

      - join_path: base_orders.line_items.products.product_categories
        includes:
          - name: name
            alias: product_category

      - join_path: base_orders.users
        prefix: true
        includes:
          - city
```

## SQL style guide

* Indent with 2 spaces.
* Use trailing commas.
* Use upper case for SQL keywords and function names.
* Use `!=` instead of `<>`.
* Always use the `AS` keyword when aliasing columns, expressions, and tables.
* Unless SQL query is a trivial one-liner, start SQL query from the new line.
* Use new lines, optimize for readability and maintainability.
* Use [common table expressions (CTE)][wiki-cte] rather than subqueries.
* When joining multiple tables, always prefix the column names with the table
  name/alias.
* Use single quotes for strings.
* Avoid initialisms and unnecessary table aliases.
* If there's only one thing in the list (e.g., projection expressions in
  `SELECT`), put it on the same line as the opening keyword.
* If there are multiple things in the list, put each one on its own line
  (including the first one), indented one level more than the opening keyword.

### Example SQL

```yaml theme={"dark"}
cubes:
  - name: california_users
    sql: |
      SELECT
        id,
        first_name,
        last_name
      FROM public.users WHERE state = 'CA'

    dimensions:
      - name: id
        sql: id
        type: number
        primary_key: true

      - name: first_name
        sql: first_name
        type: string

      - name: last_name
        sql: last_name
        type: string

    measures:
      - name: count
        type: count
```

## YAML style guide

* Use `.yml` extension instead of `.yaml`.
* Indent with 2 spaces.
* Indent list items.
* Use a new line to separate list items that are dictionaries, where
  appropriate.
* Make sure lines are no longer than 80 characters.
* Prefer [literal style][ref-yaml-folded-and-literal] (`|`) for multi-line strings
  over folded style (`>`).
* If quotes are needed around a string, use double quotes.

### Example YAML

```yaml theme={"dark"}
cubes:
  - name: users
    description: |
      All users in the system.
      Note that this dataset contains PII data.
    sql_table: public.users

    dimensions:
      - name: id
        sql: id
        type: number
        primary_key: true

      - name: city
        sql: city
        type: string

      - name: lifetime_value
        sql: "{line_items.total_amount}"
        type: number
        sub_query: true

    measures:
      - name: count
        type: count

      - name: total_orders_amount
        sql: "{lifetime_value}"
        type: sum
```

## JavaScript style guide

* Indent with 2 spaces.
* Don't use trailing semicolons.
* Don't use trailing commas after last elements of arrays and objects.
* Use a new line to separate list items that are objects, where appropriate.
* Make sure lines are no longer than 80 characters.
* If quotes are needed around a string, use [backticks][wiki-backtick].

### Example JavaScript

```javascript theme={"dark"}
cube(`users`, {
  sql_table: `public.users`,

  dimensions: {
    id: {
      sql: `id`,
      type: `number`,
      primary_key: true
    },

    city: {
      sql: `city`,
      type: `string`
    },

    lifetime_value: {
      sql: `${line_items.total_amount}`,
      type: `number`,
      sub_query: true
    }
  },

  measures: {
    count: {
      type: `count`
    },

    total_orders_amount: {
      sql: `${lifetime_value}`,
      type: `sum`
    }
  }
})
```

## Credits

This style guide was inspired in part by:

* [Brooklyn Data Co. SQL style guide](https://github.com/brooklyn-data/co/blob/main/sql_style_guide.md)
* [LAMS Style Guide](https://looker-open-source.github.io/look-at-me-sideways/rules.html)

[cpn]: https://cube.dev/consulting/cube-partner-network

[ref-syntax-model]: /docs/data-modeling/concepts/syntax#model-syntax

[ref-syntax-naming]: /docs/data-modeling/concepts/syntax#naming

[ref-syntax-folder-structure]: /docs/data-modeling/concepts/syntax#folder-structure

[ref-public]: /reference/data-modeling/cube#public

[ref-sql-table]: /reference/data-modeling/cube#sql_table

[ref-join-rel]: /reference/data-modeling/joins#relationship

[ref-cube-params]: /reference/data-modeling/cube#parameters

[ref-measure-params]: /reference/data-modeling/measures#parameters

[ref-dimension-params]: /reference/data-modeling/dimensions#parameters

[ref-view-params]: /reference/data-modeling/view#parameters

[self-yaml]: #yaml-style-guide

[self-sql]: #sql-style-guide

[wiki-cte]: https://en.wikipedia.org/wiki/Hierarchical_and_recursive_queries_in_SQL#Common_table_expression

[wiki-backtick]: https://en.wikipedia.org/wiki/Backtick

[ref-yaml-folded-and-literal]: /docs/data-modeling/dynamic/jinja#folded-and-literal-strings


# Generating the data model dynamically
Source: https://docs.cube.dev/recipes/data-modeling/using-dynamic-measures

Generate measures programmatically from changing reference data so distribution and percentage metrics stay in sync without hand-editing each value.

## Use case

Let's assume that we want to understand the distribution of orders by their statuses.
Let's imagine that new order statuses can be added in the future, or we get a list of
statuses from an external API. To calculate the orders percentage distribution, we need
to create several [measures][ref-measures] that refer to each other. But we don't want
to manually change the data model for each new status.

## Data modeling

To calculate the number of orders as a percentage, we need to know the total
number of orders and the number of orders with the desired status. We'll create
two measures for this. To calculate a percentage, we'll create a measure that
refers to another measure.

```javascript theme={"dark"}
const statuses = ["processing", "shipped", "completed"]

const createTotalByStatusMeasure = (status) => ({
  [`total_${status}_orders`]: {
    title: `Total ${status} orders`,
    type: `count`,
    filters: [
      {
        sql: (CUBE) => `${CUBE}."status" = '${status}'`
      }
    ]
  }
})

const createPercentageMeasure = (status) => ({
  [`percentage_of_${status}`]: {
    title: `Percentage of ${status} orders`,
    type: `number`,
    format: `percent`,
    sql: (CUBE) =>
      `ROUND(${CUBE[`total_${status}_orders`]}::NUMERIC / ${
        CUBE.total_orders
      }::NUMERIC, 2)`
  }
})

cube(`orders`, {
  sql_table: `orders`,

  measures: Object.assign(
    {
      total_orders: {
        type: `count`,
        title: `Total orders`
      }
    },
    statuses.reduce(
      (all, status) => ({
        ...all,
        ...createTotalByStatusMeasure(status),
        ...createPercentageMeasure(status)
      }),
      {}
    )
  )
})
```

## Result

Using the measures defined above, we can explore the orders percentage
distribution and easily create new measures just by adding a new status.

```javascript theme={"dark"}
[
  {
    "orders.percentage_of_processing": "33.54",
    "orders.percentage_of_shipped": "33.00",
    "orders.percentage_of_completed": "33.46"
  }
]
```

## Source code

Please feel free to check out the
[full source code](https://github.com/cube-js/cube/tree/master/examples/recipes/referencing-dynamic-measures)
or run it with the `docker-compose up` command. You'll see the result, including
queried data, in the console.

[ref-measures]: /docs/data-modeling/measures


# Overview
Source: https://docs.cube.dev/recipes/index

Step-by-step tutorials and best practices for getting the most out of Cube.

Explore **41 recipes** across data modeling, calculations, analytics patterns,
pre-aggregations, configuration, APIs, and AI.

## Data Modeling

<CardGroup>
  <Card title="Cube style guide" icon="book" href="/recipes/data-modeling/style-guide">
    Best practices and conventions for structuring your Cube data models.
  </Card>

  <Card title="Designing metrics" icon="chart-bar" href="/recipes/data-modeling/designing-metrics">
    Compare entity-first and metrics-first ways to structure views for BI tools, apps, and agents.
  </Card>

  <Card title="Entity-Attribute-Value model" icon="table" href="/recipes/data-modeling/entity-attribute-value">
    Shape sparse EAV warehouse tables into queryable dimensions and joins.
  </Card>

  <Card title="Using Cube with dbt" icon="cube" href="/recipes/data-modeling/dbt">
    Layer Cube on dbt-built warehouse models, aligning documentation patterns with your semantic layer.
  </Card>

  <Card title="Dynamic data models" icon="schema" href="/recipes/data-modeling/using-dynamic-measures">
    Generate measures programmatically from changing reference data.
  </Card>

  <Card title="Dynamic union tables" icon="stack-2" href="/recipes/data-modeling/dynamic-union-tables">
    Combine multiple database tables that relate to the same entity into a single cube.
  </Card>

  <Card title="Querying across data sources" icon="arrow-merge" href="/recipes/data-modeling/cross-data-source-queries">
    Append rows from cubes in different databases into one result set with a UNION ALL query.
  </Card>

  <Card title="Custom ordering" icon="sort-ascending-shapes" href="/recipes/data-modeling/custom-order">
    Define a custom sort order for categorical values like pipeline stages that don't sort alphabetically.
  </Card>
</CardGroup>

### Calculations & Metrics

<CardGroup>
  <Card title="Averages and percentiles" icon="percentage" href="/recipes/data-modeling/percentiles">
    Model percentile-based metrics alongside averages for accurate representation of skewed distributions.
  </Card>

  <Card title="Nested aggregates" icon="layers-selected-bottom" href="/recipes/data-modeling/nested-aggregates">
    Express aggregates-of-aggregates like a median of per-group sums using joined cubes and subquery dimensions.
  </Card>

  <Card title="Filtered aggregates" icon="filter" href="/recipes/data-modeling/filtered-aggregates">
    Model cross-cube filters so measures aggregate facts while respecting dimensions from related cubes.
  </Card>

  <Card title="Share of total" icon="chart-pie" href="/recipes/data-modeling/share-of-total">
    Compute each dimension member's contribution to the grand total or a fixed subtotal using multi-stage measures.
  </Card>

  <Card title="Period-over-period changes" icon="trending-up" href="/recipes/data-modeling/period-over-period">
    Calculate week-over-week, month-over-month, and other changes over a fixed period.
  </Card>
</CardGroup>

### Query-time parameters

Most recipes model a metric with a fixed shape — a set interval, a set window. These
recipes instead let the data consumer choose part of the calculation *at query time*,
so one set of members serves many variations without a data-model change. To generate a
family of members at model-build time instead (the consumer then picks by choosing which
member to query), see [Dynamic data models](/recipes/data-modeling/using-dynamic-measures).

<CardGroup>
  <Card title="Configurable rolling windows" icon="adjustments-alt" href="/recipes/data-modeling/dynamic-rolling-windows">
    Let consumers choose a measure's rolling-window and time-shift interval at query time, dispatching with a switch dimension.
  </Card>

  <Card title="Dynamic parameters" icon="adjustments-horizontal" href="/recipes/data-modeling/passing-dynamic-parameters-in-a-query">
    Let consumers supply a filter value at query time and use it in a calculation without filtering the entire query.
  </Card>
</CardGroup>

### Time Series & Calendars

<CardGroup>
  <Card title="String time dimensions" icon="letter-a" href="/recipes/data-modeling/string-time-dimensions">
    Work around non-timestamp time columns by casting strings to proper time dimension types.
  </Card>

  <Card title="Custom granularities" icon="clock" href="/recipes/data-modeling/custom-granularity">
    Implement custom time dimension granularities like fiscal quarters or custom week definitions.
  </Card>

  <Card title="Custom calendars" icon="calendar" href="/recipes/data-modeling/custom-calendar">
    Map fact tables to retail or fiscal calendars using dedicated calendar cubes and proxy dimensions.
  </Card>

  <Card title="Data snapshots" icon="camera" href="/recipes/data-modeling/snapshots">
    Build point-in-time snapshots from change-history data to report status as of any date.
  </Card>
</CardGroup>

### User & Event Analytics

<CardGroup>
  <Card title="Active users (DAU, WAU, MAU)" icon="users" href="/recipes/data-modeling/active-users">
    Measure customer engagement with daily, weekly, and monthly active user metrics.
  </Card>

  <Card title="Event analytics" icon="bolt" href="/recipes/data-modeling/event-analytics">
    Turn raw clickstream events into session definitions and metrics for product analytics.
  </Card>

  <Card title="Retention analysis & cohorts" icon="rotate" href="/recipes/data-modeling/cohort-retention">
    Implement cohort-based retention analysis to track user engagement over time.
  </Card>
</CardGroup>

## Pre-Aggregations

<CardGroup>
  <Card title="Non-additive measures" icon="square-root-2" href="/recipes/pre-aggregations/non-additivity">
    Accelerate averages, distinct counts, and similar non-additive measures with pre-aggregations.
  </Card>

  <Card title="Incremental builds" icon="grid-dots" href="/recipes/pre-aggregations/incrementally-building-pre-aggregations-for-a-date-range">
    Rebuild only the time-bounded partitions you need instead of refreshing entire rollups.
  </Card>

  <Card title="Disabling pre-aggregations" icon="toggle-left" href="/recipes/pre-aggregations/disabling-pre-aggregations">
    Conditionally disable pre-aggregations based on environment or deployment context.
  </Card>

  <Card title="original_sql and rollups" icon="database" href="/recipes/pre-aggregations/using-originalsql-and-rollups-effectively">
    Materialize expensive SQL once with original\_sql, then reuse across rollup pre-aggregations.
  </Card>

  <Card title="Refreshing partitions" icon="refresh" href="/recipes/pre-aggregations/refreshing-select-partitions">
    Partition-level refresh patterns for when dimension values change after initial load.
  </Card>

  <Card title="Multiple data sources" icon="topology-ring-2" href="/recipes/pre-aggregations/joining-multiple-data-sources">
    Join data from different warehouses with cross-database rollup joins.
  </Card>

  <Card title="Mixed refresh cadences" icon="clock-cog" href="/recipes/pre-aggregations/mixed-refresh-cadences-rollup-join">
    Combine a slow-changing fact rollup with a frequently-refreshed lookup rollup using a rollup join.
  </Card>
</CardGroup>

## Configuration

<CardGroup>
  <Card title="Environment variables" icon="key" href="/recipes/configuration/environment-variables">
    Reference deployment secrets and tunables from environment variables in your config.
  </Card>

  <Card title="SSL connections" icon="lock" href="/recipes/configuration/using-ssl-connections-to-data-source">
    Enable TLS to upstream databases with custom CA bundles and client certificates.
  </Card>

  <Card title="Optimizing data source usage" icon="brand-speedtest" href="/recipes/configuration/data-store-cost-saving-guide">
    Reduce warehouse spend through pre-aggregation strategy and workload-aware settings.
  </Card>

  <Card title="Custom data source per tenant" icon="server" href="/recipes/configuration/multiple-sources-same-schema">
    Route each tenant to its own database while reusing a single data model.
  </Card>

  <Card title="Custom data model per tenant" icon="file-code" href="/recipes/configuration/custom-data-model-per-tenant">
    Give each tenant a unique data model, from completely different to partially shared schemas.
  </Card>
</CardGroup>

## APIs & Frontend

<CardGroup>
  <Card title="Unique values for a field" icon="list" href="/recipes/core-data-api/getting-unique-values-for-a-field">
    Power filter dropdowns by querying distinct dimension values from Cube's data APIs.
  </Card>

  <Card title="Numeric values on the front-end" icon="hash" href="/recipes/core-data-api/cast-numerics">
    Coerce REST (JSON) numeric strings into JavaScript numbers, with precision pitfalls and caveats.
  </Card>

  <Card title="Custom sorting" icon="sort-ascending-letters" href="/recipes/core-data-api/sorting">
    Sort query result sets by custom criteria beyond default ordering.
  </Card>

  <Card title="Pagination" icon="book" href="/recipes/core-data-api/pagination">
    Implement paged tables over Cube queries using limit, offset, and deterministic ordering.
  </Card>

  <Card title="Drilldowns" icon="menu-deep" href="/recipes/core-data-api/drilldowns">
    Configure drill members and fetch detail rows behind an aggregate value.
  </Card>

  <Card title="Real-time data fetch" icon="wifi" href="/recipes/core-data-api/real-time-data-fetch">
    Build live-updating dashboards using WebSocket transport and client subscriptions.
  </Card>
</CardGroup>

## AI

<CardGroup>
  <Card title="Agent-to-agent with Chat API" icon="topology-star" href="/recipes/ai/agent-to-agent">
    Wrap the Cube Chat API as a LangChain tool so an orchestrating agent can query data on demand.
  </Card>
</CardGroup>


# Disabling pre-aggregations
Source: https://docs.cube.dev/recipes/pre-aggregations/disabling-pre-aggregations

We want to disable pre-aggregations unless some condition is fulfilled, e.g., unless the deployment is running in a production environment.

## Use case

We want to disable [pre-aggregations][ref-pre-aggs] unless some condition is
fulfilled, e.g., unless the deployment is running in a production environment.

## Data modeling

You can add an environment variable and use it in data model files to enable or
disable pre-aggregations.

### YAML files

In [YAML data model files][ref-env-vars-recipe-yaml], you can use Jinja with the
built-in `env_var` function:

```yamltitle="model/orders.yml" theme={"dark"}
cubes:
  - name: orders
    sql_table: orders
 
    measures:
      - name: count
        type: count
    
    {% if env_var('PRE_AGGREGATIONS_ENABLED', True) %}
    pre_aggregations:
      - name: count
        measures:
          - count
    {% endif %}
```

### JavaScript files

In [JavaScript data model files][ref-env-vars-recipe-js], you can use JavaScript
with an auxiliary file that exports your environment variable. Consider the
following file structure:

```tree theme={"dark"}
.
├── env.js
└── model
    └── orders.js
```

```javascripttitle="env.js" theme={"dark"}
module.exports = {
  pre_aggregations_enabled: process.env.PRE_AGGREGATIONS_ENABLED !== 'false'
}
```

```javascripttitle="model/orders.js" theme={"dark"}
import { pre_aggregations_enabled } from '../env'

cube(`orders`, {
  sql_table: `orders`,

  measures: {
    count: {
      type: `count`
    }
  },
  
  pre_aggregations: pre_aggregations_enabled
    ? {
      main: {
        measures: (CUBE) => [
          `${CUBE}.count`
        ]
      }
    }
    : {}
})
```

Note that you will have to adjust the pre-aggregation definition to account for
the [context symbol transpilation][ref-context-symbols-transpilation]. This is
the reason why `measures` are defined as such above.

[ref-pre-aggs]: /docs/pre-aggregations#pre-aggregations

[ref-env-vars-recipe-yaml]: /recipes/configuration/environment-variables#yaml-files

[ref-env-vars-recipe-js]: /recipes/configuration/environment-variables#javascript-files

[ref-context-symbols-transpilation]: /docs/data-modeling/dynamic/schema-execution-environment#context-symbols-transpile


# Incrementally building pre-aggregations for a date range
Source: https://docs.cube.dev/recipes/pre-aggregations/incrementally-building-pre-aggregations-for-a-date-range

How to rebuild only the time-bounded partitions you need instead of refreshing an entire multi-year partitioned rollup.

## Use case

In scenarios where a large dataset spanning multiple years is pre-aggregated
with partitioning, it is often useful to only rebuild pre-aggregations between a
certain date range (and therefore only a subset of all the partitions). This is
because recalculating all partitions is often an expensive and/or time-consuming
process.

This is most beneficial when using data warehouses with partitioning support
(such as [AWS Athena][self-config-aws-athena] and [Google
BigQuery][self-config-google-bigquery]).

## Data modeling

Let's use an example of a cube with a nested SQL query:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users_with_organizations
      sql: |
        WITH users AS (
          SELECT
            md5(company) AS organization_id,
            id AS user_id,
            created_at
          FROM public.users
        ), organizations AS (
          (
            SELECT
              md5(company) AS id,
              company AS name,
              MIN(created_at)
            FROM
              public.users
            GROUP BY
              1,
              2
          )
        ) SELECT
          users.*,
          organizations.name AS org_name
        FROM
          users
        LEFT JOIN organizations
          ON users.organization_id = organizations.id

      pre_aggregations:
        - name: main
          dimensions:
            - id
            - organization_id
          time_dimension: created_at
          refresh_key:
            every: 1 day
            incremental: true
          granularity: day
          partition_granularity: month
          build_range_start:
            sql: SELECT DATE('2021-01-01')
          build_range_end:
            sql: SELECT NOW()

      dimensions:
        - name: id
          sql: user_id
          type: number
          primary_key: true

        - name: organization_id
          sql: organization_id
          type: string

        - name: created_at
          sql: created_at
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube('users_with_organizations', {

    sql: `
      WITH users AS (
        SELECT
          md5(company) AS organization_id,
          id AS user_id,
          created_at
        FROM public.users
      ),
      organizations AS (
        (
          SELECT
            md5(company) AS id,
            company AS name,
            MIN(created_at)
          FROM
            public.users
          GROUP BY
            1,
            2
        )
      )
      SELECT
        users.*,
        organizations.name AS org_name
      FROM
        users
      LEFT JOIN organizations
        ON users.organization_id = organizations.id
      `,

    pre_aggregations: {
      main: {
        dimensions: [CUBE.id, CUBE.organization_id]
        time_dimension: CUBE.created_at,
        refresh_key: {
          every: `1 day`,
          incremental: true
        },
        granularity: `day`,
        partition_granularity: `month`,
        build_range_start: { sql: `SELECT DATE('2021-01-01')` },
        build_range_end: { sql: `SELECT NOW()` }
      }
    },

    dimensions: {
      id: {
        sql: `user_id`,
        type: `number`
        primary_key: true
      },

      organization_id: {
        sql: `organization_id`,
        type: `string`
      },

      created_at: {
        sql: `created_at`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

The cube above pre-aggregates the results of the `sql` property, and is
configured to incrementally build them as long as the date range is not before
January 1st, 2021.

However, if we only wanted to build pre-aggregations between a particular date
range within the users table, we would be unable to as the current configuration
only applies the date range to the final result of the SQL query defined in
`sql`.

In order to do the above, we'll "push down" the predicates to the inner SQL
query using [`FILTER_PARAMS`][ref-schema-ref-cube-filterparam] in conjunction
with the [`build_range_start` and `build_range_end`
properties][ref-schema-ref-preagg-buildrange]:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users_with_organizations
      sql: |
        WITH users AS (
          SELECT
            md5(company) AS organization_id,
            id AS user_id,
            created_at
          FROM public.users
          WHERE
        {FILTER_PARAMS.users_with_organizations.created_at.filter('created_at')}
        ), organizations AS (
          (
            SELECT
              md5(company) AS id,
              company AS name,
              MIN(created_at)
            FROM
              public.users
            GROUP BY
              1,
              2
          )
        ) SELECT
          users.*,
          organizations.name AS org_name
        FROM
          users
        LEFT JOIN organizations
          ON users.organization_id = organizations.id

    # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("users_with_organizations", {
    sql: `
  WITH users AS (
      SELECT
        md5(company) AS organization_id,
        id AS user_id,
        created_at
      FROM public.users
      WHERE ${FILTER_PARAMS.users_with_organizations.created_at.filter(
        "created_at"
      )}
  ),
  organizations AS (
    (
      SELECT
        md5(company) AS id,
        company AS name,
        MIN(created_at)
      FROM
        public.users
      GROUP BY
        1,
        2
    )
  )
  SELECT
    users.*,
    organizations.name AS org_name
  FROM
    users
  LEFT JOIN organizations
    ON users.organization_id = organizations.id
  `,

    // ...
  })
  ```
</CodeGroup>

## Result

By adding `FILTER_PARAMS` to the subquery inside the `sql` property, we now
limit the initial size of the dataset by applying the filter as early as
possible. When the pre-aggregations are incrementally built, the same filter is
used to apply the build ranges as defined by `build_range_start` and
`build_range_end`.

[ref-schema-ref-preagg-buildrange]: /reference/data-modeling/pre-aggregations#build_range_start-and-build_range_end

[ref-schema-ref-cube-filterparam]: /reference/data-modeling/context-variables#filter_params

[self-config-aws-athena]: /admin/connect-to-data/data-sources/aws-athena

[self-config-google-bigquery]: /admin/connect-to-data/data-sources/google-bigquery


# Joining data from multiple data sources
Source: https://docs.cube.dev/recipes/pre-aggregations/joining-multiple-data-sources

Cross-database rollup joins that relate entities living in different warehouses while keeping aggregation performant.

## Use case

Let's imagine we store information about products and their suppliers in
separate databases. We want to aggregate data from these data sources while
having decent performance. In the recipe below, we'll learn how to create a
[rollup join](/reference/data-modeling/pre-aggregations#rollup_join)
between two databases to achieve our goal.

## Configuration

First of all, we should define our database connections with the `dataSource`
option in the `cube.js` configuration file:

```javascript theme={"dark"}
module.exports = {
  driverFactory: ({ dataSource }) => {
    if (dataSource === "suppliers") {
      return {
        type: "postgres",
        database: "recipes",
        host: "demo-db-recipes.cube.dev",
        user: "cube",
        password: "12345",
        port: "5432"
      }
    }

    if (dataSource === "products") {
      return {
        type: "postgres",
        database: "ecom",
        host: "demo-db-recipes.cube.dev",
        user: "cube",
        password: "12345",
        port: "5432"
      }
    }

    throw new Error("dataSource is undefined")
  }
}
```

## Data modeling

First, we'll define
[rollup](/reference/data-modeling/pre-aggregations#rollup)
pre-aggregations for `products` and `suppliers`. Note that these
pre-aggregations should contain the dimension on which they're joined. In this
case, it's the `supplier_id` dimension in the `products` cube, and the `id`
dimension in the `suppliers` cube:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products
      # ...

      pre_aggregations:
        - name: products_rollup
          type: rollup
          dimensions:
            - name
            - supplier_id
          indexes:
            - name: category_index
              columns:
                - supplier_id

      joins:
        suppliers:
          sql: "{supplier_id} = {suppliers.id}"
          relationship: many_to_one
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("products", {
    // ...

    pre_aggregations: {
      products_rollup: {
        type: `rollup`,
        dimensions: [name, supplier_id],
        indexes: {
          category_index: {
            columns: [supplier_id]
          }
        }
      }
    },

    joins: {
      suppliers: {
        sql: `${supplier_id} = ${suppliers.id}`,
        relationship: `many_to_one`
      }
    },

    // ...
  })
  ```
</CodeGroup>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: suppliers
      # ...

      pre_aggregations:
        - name: suppliers_rollup
          type: rollup
          dimensions:
            - id
            - company
            - email
          indexes:
            - name: category_index
              columns:
                - id
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("suppliers", {
    // ...

    pre_aggregations: {
      suppliers_rollup: {
        type: `rollup`,
        dimensions: [id, company, email],
        indexes: {
          category_index: {
            columns: [id]
          }
        }
      }
    }
  })
  ```
</CodeGroup>

Then, we'll also define a `rollup_join` pre-aggregation in the `products` cube,
which will enable aggregating data from multiple data sources:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products
      # ...

      pre_aggregations:
        - name: combined_rollup
          type: rollup_join
          dimensions:
            - suppliers.email
            - suppliers.company
            - name
          rollups:
            - suppliers.suppliers_rollup
            - products_rollup
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("products", {
    // ...

    pre_aggregations: {
      combined_rollup: {
        type: `rollup_join`,
        dimensions: [suppliers.email, suppliers.company, name],
        rollups: [suppliers.suppliers_rollup, products_rollup]
      }
    }
  })
  ```
</CodeGroup>

## Query

Let's get the product names and their suppliers' info, such as company name and
email, with the following query:

```json theme={"dark"}
{
  "order": {
    "products.name": "asc"
  },
  "dimensions": ["products.name", "suppliers.company", "suppliers.email"],
  "limit": 3
}
```

## Result

We'll get the data from two pre-aggregations joined into one `rollup_join`:

```json theme={"dark"}
[
  {
    "products.name": "Awesome Cotton Sausages",
    "suppliers.company": "Justo Eu Arcu Inc.",
    "suppliers.email": "id.risus@luctuslobortisClass.net"
  },
  {
    "products.name": "Awesome Fresh Keyboard",
    "suppliers.company": "Quisque Purus Sapien Limited",
    "suppliers.email": "Cras@consectetuercursuset.co.uk"
  },
  {
    "products.name": "Awesome Rubber Soap",
    "suppliers.company": "Tortor Inc.",
    "suppliers.email": "Mauris@ac.com"
  }
]
```

## Source code

Please feel free to check out the
[full source code](https://github.com/cube-js/cube/tree/master/examples/recipes/joining-multiple-datasources-data)
or run it with the `docker-compose up` command. You'll see the result, including
queried data, in the console.


# Joining pre-aggregations with different refresh cadences
Source: https://docs.cube.dev/recipes/pre-aggregations/mixed-refresh-cadences-rollup-join

Use a rollup join to combine a heavy, slowly-refreshed fact pre-aggregation with a lightweight, frequently-refreshed lookup pre-aggregation so derived metrics stay fresh without rebuilding the full fact table.

## Use case

A common modeling problem is computing a metric that depends on two inputs
which change at very different rates:

* A **large fact table** that is expensive to aggregate and only needs to be
  refreshed on a slow cadence (for example, daily or hourly).
* A **small lookup table** whose values are applied to each fact row and that
  needs to be refreshed much more frequently than the fact aggregation.

Some examples of this pattern:

* Converting an amount column to a target currency using the latest foreign
  exchange (FX) rates — either a single-currency column multiplied by a rate,
  or an `amount` and `currency` column resolved with a `CASE` statement.
* Re-pricing inventory or order lines with a frequently-updated price list.
* Applying a frequently-tuned scoring weight, tax rate, or commission rate to
  historical events.

Combining both inputs into a single [rollup](/reference/data-modeling/pre-aggregations#rollup)
forces the entire pre-aggregation to refresh whenever the lookup values
change, which is wasteful. In the recipe below, we'll learn how to use a
[rollup join](/reference/data-modeling/pre-aggregations#rollup_join) to keep
each pre-aggregation on its own refresh schedule while still serving the
combined, derived query from pre-aggregations.

We'll walk through the FX conversion variant as a concrete example, but the
same pattern applies to any of the use cases above.

<Warning>
  `rollup_join` has several constraints documented on the
  [pre-aggregations reference page](/reference/data-modeling/pre-aggregations#rollup_join).
  In particular: it is currently in Preview, it is designed for joining data
  across data sources, it can only join two rollups, and it is ephemeral —
  set freshness controls on the referenced rollups rather than on the
  `rollup_join` itself.

  The rollup on the right side of the join is also bounded by the number of
  physical Cube Store partitions it can have, which depends on your Cube
  Store compute tier. Note that these are Cube Store physical partitions —
  not Cube logical partitions.
</Warning>

## Data modeling

We have two cubes: `orders`, which stores per-order amounts in the original
transaction currency, and `fx_rates`, which stores the latest exchange rate
from each currency to USD.

The `orders` table looks like this:

| id | currency | amount | created\_at         |
| -- | -------- | ------ | ------------------- |
| 1  | EUR      | 120.00 | 2026-05-18 09:14:22 |
| 2  | GBP      | 75.50  | 2026-05-18 11:02:47 |
| 3  | EUR      | 245.10 | 2026-05-19 08:31:05 |
| 4  | USD      | 310.00 | 2026-05-19 10:18:33 |
| 5  | GBP      | 89.99  | 2026-05-19 12:44:51 |

The `fx_rates` table looks like this:

| currency | rate\_to\_usd |
| -------- | ------------- |
| EUR      | 1.085         |
| GBP      | 1.262         |
| USD      | 1.000         |

First, define a `rollup` pre-aggregation on `orders` that aggregates the
amount by `currency` and day. This is the heavy pre-aggregation, so we set a
slow `refresh_key` — for example, every day:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders

      sql_table: public.orders

      joins:
        - name: fx_rates
          sql: "{CUBE}.currency = {fx_rates.currency}"
          relationship: many_to_one

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: currency
          sql: currency
          type: string

        - name: created_at
          sql: created_at
          type: time

      measures:
        - name: amount
          sql: amount
          type: sum

      pre_aggregations:
        - name: orders_rollup
          type: rollup
          measures:
            - amount
          dimensions:
            - currency
          time_dimension: created_at
          granularity: day
          refresh_key:
            every: 1 day
          indexes:
            - name: currency_index
              columns:
                - currency
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `public.orders`,

    joins: {
      fx_rates: {
        sql: `${CUBE}.currency = ${fx_rates.currency}`,
        relationship: `many_to_one`
      }
    },

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      },

      currency: {
        sql: `currency`,
        type: `string`
      },

      created_at: {
        sql: `created_at`,
        type: `time`
      }
    },

    measures: {
      amount: {
        sql: `amount`,
        type: `sum`
      }
    },

    pre_aggregations: {
      orders_rollup: {
        type: `rollup`,
        measures: [amount],
        dimensions: [currency],
        time_dimension: created_at,
        granularity: `day`,
        refresh_key: {
          every: `1 day`
        },
        indexes: {
          currency_index: {
            columns: [currency]
          }
        }
      }
    }
  })
  ```
</CodeGroup>

Next, define a `rollup` pre-aggregation on `fx_rates`. This pre-aggregation is
small (one row per currency) and cheap to rebuild, so we give it a much
faster `refresh_key` than the orders rollup — for example, every hour:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: fx_rates

      sql_table: public.fx_rates

      dimensions:
        - name: currency
          sql: currency
          type: string
          primary_key: true

        - name: rate_to_usd
          sql: rate_to_usd
          type: number

      pre_aggregations:
        - name: fx_rates_rollup
          type: rollup
          dimensions:
            - currency
            - rate_to_usd
          refresh_key:
            every: 1 hour
          indexes:
            - name: currency_index
              columns:
                - currency
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`fx_rates`, {
    sql_table: `public.fx_rates`,

    dimensions: {
      currency: {
        sql: `currency`,
        type: `string`,
        primary_key: true
      },

      rate_to_usd: {
        sql: `rate_to_usd`,
        type: `number`
      }
    },

    pre_aggregations: {
      fx_rates_rollup: {
        type: `rollup`,
        dimensions: [currency, rate_to_usd],
        refresh_key: {
          every: `1 hour`
        },
        indexes: {
          currency_index: {
            columns: [currency]
          }
        }
      }
    }
  })
  ```
</CodeGroup>

<Note>
  Both pre-aggregations must include an index on the join key (`currency` in
  this example) for the `rollup_join` to match. The `fx_rates_rollup` also
  needs `rate_to_usd` as a dimension so it's available downstream.
</Note>

Finally, define a `rollup_join` pre-aggregation on `orders` that references
both rollups. This is an ephemeral pre-aggregation — it doesn't materialize
its own data, so it doesn't need a `refresh_key`. Cube serves queries from it
by joining the two underlying rollups on the fly:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        # ...

        - name: orders_with_fx_rollup
          type: rollup_join
          measures:
            - amount
          dimensions:
            - currency
            - fx_rates.rate_to_usd
          time_dimension: created_at
          granularity: day
          rollups:
            - fx_rates.fx_rates_rollup
            - orders_rollup
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    pre_aggregations: {
      // ...

      orders_with_fx_rollup: {
        type: `rollup_join`,
        measures: [amount],
        dimensions: [currency, fx_rates.rate_to_usd],
        time_dimension: created_at,
        granularity: `day`,
        rollups: [fx_rates.fx_rates_rollup, orders_rollup]
      }
    }
  })
  ```
</CodeGroup>

To expose the USD-converted amount, add a derived measure on `orders` that
multiplies the order amount by the FX rate from the joined cube:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        # ...

        - name: amount_usd
          sql: "{CUBE.amount} * {fx_rates.rate_to_usd}"
          type: number
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      // ...

      amount_usd: {
        sql: `${CUBE.amount} * ${fx_rates.rate_to_usd}`,
        type: `number`
      }
    }
  })
  ```
</CodeGroup>

## Query

Let's query daily sales in USD by currency:

```json theme={"dark"}
{
  "measures": ["orders.amount_usd"],
  "dimensions": ["orders.currency"],
  "timeDimensions": [
    {
      "dimension": "orders.created_at",
      "granularity": "day"
    }
  ]
}
```

## Result

Cube serves the query from `orders_with_fx_rollup`, joining the cached
`orders_rollup` (refreshed daily) with the cached `fx_rates_rollup`
(refreshed hourly). The heavy aggregation never rebuilds when FX rates
change, but the converted totals always reflect the latest rates.

```javascript theme={"dark"}
[
  {
    "orders.created_at.day": "2026-05-19T00:00:00.000",
    "orders.currency": "EUR",
    "orders.amount_usd": "12450.32"
  },
  {
    "orders.created_at.day": "2026-05-19T00:00:00.000",
    "orders.currency": "GBP",
    "orders.amount_usd": "8930.17"
  }
]
```


# Accelerating non-additive measures
Source: https://docs.cube.dev/recipes/pre-aggregations/non-additivity

Modeling techniques so averages, distinct counts, and similar non-additive measures still benefit from pre-aggregation acceleration.

## Use case

We want to run queries against
[pre-aggregations](/docs/pre-aggregations#pre-aggregations) only to ensure our
application's superior performance. Usually, accelerating a query is as simple
as including its measures and dimensions to the pre-aggregation
[definition](/reference/data-modeling/pre-aggregations#measures).

[Non-additive](/docs/pre-aggregations/matching-pre-aggregations#matching-algorithm)
measures (e.g., average values or distinct counts) are a special case.
Pre-aggregations with such measures are less likely to be
[selected](/docs/pre-aggregations/matching-pre-aggregations#matching-algorithm)
to accelerate a query. However, there are a few ways to work around that.

## Data modeling

Let's explore the `users` cube that contains various measures describing users'
age:

* count of unique age values (`distinct_ages`)
* average age (`avg_age`)
* 90th [percentile][ref-percentile-recipe] of age (`p90_age`)

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      # ...

      measures:
        - name: distinct_ages
          sql: age
          type: count_distinct

        - name: avg_age
          sql: age
          type: avg

        - name: p90_age
          sql: PERCENTILE_CONT(0.9) WITHIN GROUP (ORDER BY age)
          type: number
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    measures: {
      distinct_ages: {
        sql: `age`,
        type: `count_distinct`
      },

      avg_age: {
        sql: `age`,
        type: `avg`
      },

      p90_age: {
        sql: `PERCENTILE_CONT(0.9) WITHIN GROUP (ORDER BY age)`,
        type: `number`
      }
    }
  })
  ```
</CodeGroup>

All of these measures are non-additive. Practically speaking, it means that the
pre-aggregation below would only accelerate a query that fully matches its
definition:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users

      pre_aggregations:
        - name: main
          measures:
            - distinct_ages
            - avg_age
            - p90_age
          dimensions:
            - gender
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    // ...
    pre_aggregations: {
      main: {
        measures: [distinct_ages, avg_age, p90_age],
        dimensions: [gender]
      }
    }
  })
  ```
</CodeGroup>

This query will match the pre-aggregation above and, thus, will be accelerated:

```json theme={"dark"}
{
  "measures": ["users.distinct_ages", "users.avg_age", "users.p90_age"],
  "dimensions": ["users.gender"]
}
```

Meanwhile, the query below won't match the same pre-aggregation because it
contains non-additive measures and omits the `gender` dimension. It won't be
accelerated:

```json theme={"dark"}
{
  "measures": ["users.distinct_ages", "users.avg_age", "users.p90_age"]
}
```

Let's explore some possible workarounds.

### Replacing with approximate additive measures

Often, non-additive `count_distinct` measures can be changed to have the
[`count_distinct_approx` type](/reference/data-modeling/measures#type)
which will make them additive and orders of magnitude more performant. This
`count_distinct_approx` measures can be used in pre-aggregations. However, there
are two drawbacks:

* This type is approximate, so the measures might yield slightly different
  results compared to their `count_distinct` counterparts. Please consult with
  your database's documentation to learn more.
* The `count_distinct_approx` is not supported with all databases. Currently,
  Cube supports it for Athena, BigQuery, and Snowflake.

For example, the `distinct_ages` measure can be rewritten as follows:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users

      measures:
        - name: distinct_ages
          sql: age
          type: count_distinct_approx
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    measures: {
      distinct_ages: {
        sql: `age`,
        type: `count_distinct_approx`
      }
    }
  })
  ```
</CodeGroup>

### Decomposing into a formula with additive measures

Non-additive `avg` measures can be rewritten as [calculated measures][ref-calculated-measures]
that reference additive measures only. Then, this additive measures can be used
in pre-aggregations. Please note, however, that you shouldn't include `avg_age`
measure in your pre-aggregation as it renders it non-additive.

For example, the `avg_age` measure can be rewritten as follows:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users

      measures:
        - name: avg_age
          sql: "{age_sum} / {count}"
          type: number

        - name: age_sum
          sql: age
          type: sum

        - name: count
          type: count

      pre_aggregations:
        - name: main
          measures:
            - age_sum
            - count
          dimensions:
            - gender
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    measures: {
      avg_age: {
        sql: `${age_sum} / ${count}`,
        type: `number`
      },

      age_sum: {
        sql: `age`,
        type: `sum`
      },

      count: {
        type: `count`
      }
    },

    pre_aggregations: {
      main: {
        measures: [age_sum, count],
        dimensions: [gender]
      }
    }
  })
  ```
</CodeGroup>

### Providing multiple pre-aggregations

If the two workarounds described above don't apply to your use case, feel free
to create additional pre-aggregations with definitions that fully match your
queries with non-additive measures. You will get a performance boost at the
expense of a slightly increased overall pre-aggregation build time and space
consumed.

## Source code

Please feel free to check out the
[full source code](https://github.com/cube-js/cube/tree/master/examples/recipes/non-additivity)
or run it with the `docker-compose up` command. You'll see the result, including
queried data, in the console.

[ref-percentile-recipe]: /recipes/data-modeling/percentiles

[ref-calculated-measures]: /docs/data-modeling/measures#calculated-measures


# Refreshing select partitions
Source: https://docs.cube.dev/recipes/pre-aggregations/refreshing-select-partitions

Partition-level refresh patterns using refresh_key and FILTER_PARAMS when dimension values change long after the fact.

## Use case

We have a dataset with orders and we want to aggregate data while having decent
performance. Orders have a creation time, so we can use
[partitioning](/docs/pre-aggregations/using-pre-aggregations#partitioning) by time to
optimize pre-aggregations build and refresh time. The problem is that the
order's status can change after a long period. In this case, we want to rebuild
only partitions associated with this order.

In the recipe below, we'll learn how to use the
[`refresh_key`](/reference/data-modeling/pre-aggregations#sql) together
with the [`FITER_PARAMS`](/reference/data-modeling/context-variables#filter_params)
for partition separately.

## Data modeling

Let's explore the `orders` cube data that contains various information about
orders, including number and status:

| id | number | status     | created\_at         | updated\_at         |
| -- | ------ | ---------- | ------------------- | ------------------- |
| 1  | 1      | processing | 2021-08-10 14:26:40 | 2021-08-10 14:26:40 |
| 2  | 2      | completed  | 2021-08-20 13:21:38 | 2021-08-22 13:10:38 |
| 3  | 3      | shipped    | 2021-09-01 10:27:38 | 2021-09-02 01:12:38 |
| 4  | 4      | completed  | 2021-09-20 10:27:38 | 2021-09-20 10:27:38 |

In our case, each order has `created_at` and `updated_at` properties. The
`updated_at` property is the last order update timestamp. To create a
pre-aggregation with partitions, we need to specify the
[`partition_granularity` property](/reference/data-modeling/pre-aggregations#partition_granularity).
Partitions will be split monthly by the `created_at` dimension.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: orders
          type: rollup
          dimensions:
            - number
            - status
            - created_at
            - updated_at
          time_dimension: created_at
          granularity: day
          partition_granularity: month # this is where we specify the partition
          refreshKey:
            sql: SELECT max(updated_at) FROM public.orders # check for updates of the updated_at property
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    pre_aggregations: {
      orders: {
        type: `rollup`,
        dimensions: [number, status, created_at, updated_at],
        time_dimension: created_at,
        granularity: `day`,
        partition_granularity: `month`, // this is where we specify the partition
        refresh_key: {
          sql: `SELECT max(updated_at) FROM public.orders`, // check for updates of the updated_at property
        }
      }
    }
  })
  ```
</CodeGroup>

As you can see, we defined custom a
[`refresh_key`](/reference/data-modeling/pre-aggregations#sql) that will
check for new values of the `updated_at` property. The refresh key is evaluated
for each partition separately. For example, if we update orders from August and
update their `updated_at` property, the current refresh key will update for
**all** partitions. There is how it looks in the Cube logs:

```bash theme={"dark"}
Executing SQL: 5b4c517f-b496-4c69-9503-f8cd2b4c73b6
--
  SELECT max(updated_at) FROM public.orders
--
Performing query completed: 5b4c517f-b496-4c69-9503-f8cd2b4c73b6 (15ms)
Performing query: 5b4c517f-b496-4c69-9503-f8cd2b4c73b6
Performing query: 5b4c517f-b496-4c69-9503-f8cd2b4c73b6
Executing SQL: 5b4c517f-b496-4c69-9503-f8cd2b4c73b6
--
  select min(("orders".created_at::timestamptz AT TIME ZONE 'UTC')) from public.orders AS "orders"
--
Executing SQL: 5b4c517f-b496-4c69-9503-f8cd2b4c73b6
--
  select max(("orders".created_at::timestamptz AT TIME ZONE 'UTC')) from public.orders AS "orders"
--
```

Note that the query for two partitions is the same. It's the reason why **all
partitions** will be updated.

How do we fix this and update only the partition for August? We can use the
[`FILTER_PARAMS`](/reference/data-modeling/context-variables#filter_params) for that!

Let's update our pre-aggregation definition:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: orders
          type: rollup
          dimensions:
            - number
            - status
            - created_at
            - updated_at
          time_dimension: created_at
          granularity: day
          partition_granularity: month # this is where we specify the partition
          refreshKey:
            sql: |
              SELECT max(updated_at) FROM public.orders WHERE
              {FILTER_PARAMS.orders.created_at.filter('created_at')}
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    pre_aggregations: {
      orders: {
        type: `rollup`,
        dimensions: [number, status, created_at, updated_at],
        time_dimension: created_at,
        granularity: `day`,
        partition_granularity: `month`,
        refresh_key: {
          sql: `
            SELECT max(updated_at)
            FROM public.orders
            WHERE ${FILTER_PARAMS.orders.created_at.filter("created_at")}`
        }
      }
    }
  })
  ```
</CodeGroup>

Cube will filter data by the `created_at` property and then apply the refresh
key for the `updated_at` property. Here's how it looks in the Cube logs:

```bash theme={"dark"}
Executing SQL: e1155b2f-859b-4e61-a760-17af891f5f0b
--
  select min(("updated_orders".created_at::timestamptz AT TIME ZONE 'UTC')) from public.orders AS "updated_orders"
--
Executing SQL: e1155b2f-859b-4e61-a760-17af891f5f0b
--
  select max(("updated_orders".created_at::timestamptz AT TIME ZONE 'UTC')) from public.orders AS "updated_orders"
--
Performing query completed: e1155b2f-859b-4e61-a760-17af891f5f0b (10ms)
Performing query completed: e1155b2f-859b-4e61-a760-17af891f5f0b (13ms)
Performing query: e1155b2f-859b-4e61-a760-17af891f5f0b
Performing query: e1155b2f-859b-4e61-a760-17af891f5f0b
Executing SQL: e1155b2f-859b-4e61-a760-17af891f5f0b
--
  SELECT max(updated_at) FROM public.orders WHERE created_at >= '2021-08-01T00:00:00.000Z'::timestamptz AND created_at <= '2021-08-31T23:59:59.999Z'::timestamptz
--
Executing SQL: e1155b2f-859b-4e61-a760-17af891f5f0b
--
  SELECT max(updated_at) FROM public.orders WHERE created_at >= '2021-09-01T00:00:00.000Z'::timestamptz AND created_at <= '2021-09-30T23:59:59.999Z'::timestamptz
```

Note that Cube checks the refresh key value using a date range over the
`created_at` property. With this refresh key, only one partition will be
updated.

## Result

We have received orders from two partitions of a pre-aggregation and only one of
them has been updated when an order changed its status:

```json5 theme={"dark"}
// orders before update:
[
  {
    "orders.number": "1",
    "orders.status": "processing",
    "orders.created_at": "2021-08-10T14:26:40.000",
    "orders.updated_at": "2021-08-10T14:26:40.000",
  },
  {
    "orders.number": "2",
    "orders.status": "completed",
    "orders.created_at": "2021-08-20T13:21:38.000",
    "orders.updated_at": "2021-08-20T13:21:38.000",
  },
  {
    "orders.number": "3",
    "orders.status": "shipped",
    "orders.created_at": "2021-09-01T10:27:38.000",
    "orders.updated_at": "2021-09-01T10:27:38.000",
  },
  {
    "orders.number": "4",
    "orders.status": "completed",
    "orders.created_at": "2021-09-20T10:27:38.000",
    "orders.updated_at": "2021-09-20T10:27:38.000",
  },
]
```

```json5 theme={"dark"}
// orders after update:
[
  {
    "orders.number": "1",
    "orders.status": "shipped",
    "orders.created_at": "2021-08-10T14:26:40.000",
    "orders.updated_at": "2021-09-30T06:45:28.000",
  },
  {
    "orders.number": "2",
    "orders.status": "completed",
    "orders.created_at": "2021-08-20T13:21:38.000",
    "orders.updated_at": "2021-08-20T13:21:38.000",
  },
  {
    "orders.number": "3",
    "orders.status": "shipped",
    "orders.created_at": "2021-09-01T10:27:38.000",
    "orders.updated_at": "2021-09-01T10:27:38.000",
  },
  {
    "orders.number": "4",
    "orders.status": "completed",
    "orders.created_at": "2021-09-20T10:27:38.000",
    "orders.updated_at": "2021-09-20T10:27:38.000",
  },
]
```

## Source code

Please feel free to check out the
[full source code](https://github.com/cube-js/cube/tree/master/examples/recipes/refreshing-select-partitions)
or run it with the `docker-compose up` command. You'll see the result, including
queried data, in the console.


# Using `original_sql` and `rollup` pre-aggregations effectively
Source: https://docs.cube.dev/recipes/pre-aggregations/using-originalsql-and-rollups-effectively

Recipe for materializing expensive cube SQL once with original_sql, then reusing it across rollup pre-aggregations and ad hoc queries.

## Use case

You can use the [`sql` parameter][ref-cube-sql] to define [cubes][ref-cubes]
over arbitrary SQL queries. Sometimes, these queries might be fairly complex
and take substantial time to execute. That's totally okay because you can use
[pre-aggregations][ref-preaggs] to accelerate queries to such cubes.

However, if you have more than one pre-aggregation that references members of
such a cube, its `sql` expression would have to be executed each time every
pre-aggregation is built. This also the case if you run both pre-aggregated
and non-pre-aggregated queries against such a cube.

A special [`original_sql` pre-aggregation][ref-schema-ref-preaggs-type-origsql]
can help:

* First, it will materialize the results of the `sql` expression in the data source.
* Then, it will make these results available to other `rollup` pre-aggregations
  and non-pre-aggregated queries.

## Configuration

We can do this by creating a pre-aggregation of type
[`original_sql`][ref-schema-ref-preaggs-type-origsql] on the data source
database, and then configuring our existing `rollup`
pre-aggregations to use the `original_sql` pre-aggregation with the
[`use_original_sql_pre_aggregations` property][ref-schema-ref-preaggs-use-origsql].

<Warning>
  Storing pre-aggregations on an internal database requires write-access. Please
  ensure that your database driver is not configured with `readOnly: true`.
</Warning>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql: "<YOUR_EXPENSIVE_SQL_QUERY HERE>"

      pre_aggregations:
        - name: base
          type: original_sql
          external: false

        - name: main
          dimensions:
            - id
            - name
          measures:
            - count
          time_dimension: created_at
          granularity: day
          use_original_sql_pre_aggregations: true
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube("orders", {
    sql: `<YOUR_EXPENSIVE_SQL_QUERY HERE>`,

    pre_aggregations: {
      base: {
        type: `original_sql`,
        external: false
      },

      main: {
        dimensions: [id, name],
        measures: [count],
        time_dimension: created_at,
        granularity: `day`,
        use_original_sql_pre_aggregations: true
      }
    }
  })
  ```
</CodeGroup>

## Result

With the above data model, the `main` pre-aggregation is built from the `base`
pre-aggregation.

[ref-schema-ref-preaggs-type-origsql]: /reference/data-modeling/pre-aggregations#original_sql

[ref-schema-ref-preaggs-use-origsql]: /reference/data-modeling/pre-aggregations#use_original_sql_pre_aggregations

[ref-cubes]: /reference/data-modeling/cube

[ref-cube-sql]: /reference/data-modeling/cube#sql

[ref-preaggs]: /docs/pre-aggregations/using-pre-aggregations


# Cube CLI
Source: https://docs.cube.dev/reference/cli

Command-line interface for managing Cube deployments, data models, and workspace resources.

The Cube CLI (`cube`) is a single-binary command-line interface for the Cube
platform. Use it to create and manage deployments, deploy data model code,
work with the data model Git workflow, connect GitHub repositories, tail
deployment logs, and automate workspace administration from scripts and CI.

<Info>
  The Cube CLI works with the Cube cloud platform. It is not required for
  running Cube Core locally.
</Info>

## Installation

Linux / macOS:

```bash theme={"dark"}
curl -fsSL https://raw.githubusercontent.com/cube-js/cube/master/install-cli.sh | sh
```

Windows (PowerShell):

```powershell theme={"dark"}
irm https://raw.githubusercontent.com/cube-js/cube/master/install-cli.ps1 | iex
```

The installer downloads the release binary for your platform and adds it to
your `PATH`. Set `CUBE_VERSION` to pin a release tag, or `CUBE_INSTALL_DIR`
to change the install location.

The CLI checks for new releases in the background and prints a notice when
one is available. Update in place at any time:

```bash theme={"dark"}
cube update          # install the latest release
cube update --check  # only report what's available
```

Running `cube` with no arguments prints the installed version above the help
text.

## Authentication

Sign in with the browser device flow — the CLI prints a URL and a short
code, opens your browser, and waits for approval:

```bash theme={"dark"}
cube login --url https://TENANT.cubecloud.dev
```

Credentials are saved to `~/.config/cube/config.toml` (Linux/macOS) or
`%APPDATA%\cube\config.toml` (Windows). Multiple accounts are supported as
named contexts (`--name` on login, `--context` on any command), and expired
access tokens refresh automatically.

For CI and scripts, use an [API key][ref-api-keys] instead:

```bash theme={"dark"}
cube login --api-key sk-YOUR_API_KEY --url https://TENANT.cubecloud.dev
# or, without a config file:
CUBE_API_URL=https://TENANT.cubecloud.dev CUBE_API_KEY=sk-YOUR_API_KEY cube deployments list
```

## Deploy a project

The core workflow — create a deployment, connect a database, upload your
data model, and query it:

<Steps>
  <Step title="Create a deployment">
    ```bash theme={"dark"}
    cube deployments create --name my-deployment --region aws-us-east-1-2
    cube regions  # list available regions
    ```
  </Step>

  <Step title="Connect a database">
    ```bash theme={"dark"}
    cube variables set DEPLOYMENT_ID \
      CUBEJS_DB_TYPE=postgres \
      CUBEJS_DB_HOST=db.example.com \
      CUBEJS_DB_NAME=mydb \
      CUBEJS_DB_USER=user \
      CUBEJS_DB_PASS=secret
    ```
  </Step>

  <Step title="Deploy your project">
    ```bash theme={"dark"}
    cube deployments update DEPLOYMENT_ID -d '{"deployMode":"cli"}'
    cube deploy DEPLOYMENT_ID --directory ./my-cube-project -m "initial deploy"
    ```

    `cube deploy` hashes local files, uploads only what changed, removes remote
    files deleted locally (`--keep-missing` opts out), and triggers a single
    build. Pass `--branch` to deploy to a specific data model branch instead of
    the active dev-mode branch (or the deploy branch, if none is active).
  </Step>

  <Step title="Watch the build and query">
    ```bash theme={"dark"}
    cube deployments build-status DEPLOYMENT_ID
    cube deployments token DEPLOYMENT_ID  # mints a Core Data APIs token
    ```

    Use the token against the deployment's [REST (JSON) API][ref-rest-api] endpoint.
  </Step>
</Steps>

## Import from GitHub

Connect a deployment to a GitHub repository instead of uploading files:

```bash theme={"dark"}
cube github status                       # link state of your GitHub account
cube github installations                # your GitHub App installations
cube github repos INSTALLATION_ID        # repositories in an installation
cube github branches OWNER/REPO --installation INSTALLATION_ID
cube deployments create --name from-repo --region aws-us-east-1-2 \
  -d '{"creationMethod":"github"}'
cube github connect DEPLOYMENT_ID REPO --installation INSTALLATION_ID --branch main
```

Connecting clones the repository into the deployment and triggers the first
build.

## Validate the data model

`cube validate` compiles a deployment's data model and reports the compiler's
errors, exiting non-zero when there are any — so it works as a CI gate:

```bash theme={"dark"}
cube validate DEPLOYMENT_ID                      # the deploy branch (production)
cube validate DEPLOYMENT_ID --branch my-branch   # a specific branch
cube validate DEPLOYMENT_ID --dev-mode           # your active dev-mode branch
```

The compile runs where the model runs: the command asks the branch's own Cube
API for its metadata, the same call the Cube UI makes. So the model is
checked against that environment's real variables and drivers, and a branch is
validated by the environment serving it — with `--dev-mode`, against your
uncommitted working copy, before you commit it.

```
✓ Data model on master is valid (12 cubes)
```

Pass `--json` for a machine-readable report (`valid`, `errors[]` with the file
each was reported against, `cubesCount`); the exit code is the same either way.

## Command reference

Run `cube <command> --help` for the full options of any command.

| Command                                                       | Description                                                                                                                                                                                                                           |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `login`, `logout`, `whoami`, `context`                        | Authentication and saved contexts                                                                                                                                                                                                     |
| `deployments`                                                 | List, get, create, update, delete deployments; `settings`, `versions`, `token`, `build-status`, `advance-step`, `reset-step`                                                                                                          |
| `deploy`                                                      | Upload a local project directory and build it                                                                                                                                                                                         |
| `validate`                                                    | Compile a deployment's data model and report compilation errors (`--branch`, `--dev-mode`)                                                                                                                                            |
| `logs`                                                        | Tail deployment pod logs (`--pod`, `-c/--container`, `--source production\|dev`)                                                                                                                                                      |
| `regions`                                                     | List available deployment regions                                                                                                                                                                                                     |
| `github` (`gh`)                                               | GitHub integration: `status`, `installations`, `repos`, `branches`, `connect`                                                                                                                                                         |
| `data-model`                                                  | Data model files and Git workflow: `list`, `get`, `put`, `delete`, `rename`, `file-hashes`, `branches`, `create-branch`, `delete-branch`, `enable-branch`/`disable-branch`, `dev-mode`, `commit`, `pull`, `merge`, `merge-to-default` |
| `dbt`                                                         | dbt sync: `sync` (`--ref`, `--wait`), `status`, `result`, `logs`, `history` (`--status`, `--trigger`), `cancel`                                                                                                                       |
| `environments`                                                | Deployment environments and environment tokens                                                                                                                                                                                        |
| `variables`                                                   | Deployment environment variables                                                                                                                                                                                                      |
| `folders`, `workbooks`, `reports`, `workspace`                | Workspace content management                                                                                                                                                                                                          |
| `users`, `groups`, `attributes`, `policies`                   | Users, groups, and access control                                                                                                                                                                                                     |
| `tenant`, `notifications`, `integrations`, `oidc`, `api-keys` | Account administration                                                                                                                                                                                                                |
| `embed`                                                       | Embed sessions, tokens, embed tenants; `enable-dashboard`/`disable-dashboard` toggle signed embedding for a dashboard                                                                                                                 |
| `agents`, `app`, `meta`, `scim`                               | Agents, app config, model metadata, SCIM v2                                                                                                                                                                                           |
| `spec`                                                        | Show the API's OpenAPI specification — see [Discovering the API](#discovering-the-api)                                                                                                                                                |
| `api`                                                         | Raw authenticated API request (escape hatch): `cube api GET /api/v1/... -q key=value -d '{...}'`                                                                                                                                      |
| `update`                                                      | Update the CLI to the latest release                                                                                                                                                                                                  |
| `completion`                                                  | Generate shell completions                                                                                                                                                                                                            |

List commands print tables by default; pass `--json` anywhere for raw JSON
output, suitable for piping to `jq`.

## Changing the Cube version

`cube deployments versions` lists the Cube versions a deployment can switch to
— the head of each [update channel][ref-update-channels], plus the older
versions your account has run before:

```bash theme={"dark"}
cube deployments versions DEPLOYMENT_ID
```

```
VERSION  CHANNEL  LATEST  CURRENT  PASS AS
1.7.20   latest   true    true     cubejs/cube:v1.7.20
1.6.69   latest   false   false    cubejs/cube:v1.6.69
```

Apply one with `update`. Any of `1.7.20`, `v1.7.20` or `cubejs/cube:v1.7.20` is
accepted; a version that is not on the list is rejected. The container image is
resolved from the version, so there is nothing else to set:

```bash theme={"dark"}
cube deployments update DEPLOYMENT_ID --release-channel-version 1.7.20
cube deployments update DEPLOYMENT_ID --release-channel release  # move to a channel's latest
```

`cube deployments settings DEPLOYMENT_ID` reads back every setting, including
the version and channel currently in effect.

## Discovering the API

`cube spec` prints the OpenAPI specification of the API you are logged into, so
neither you nor an AI agent has to guess an endpoint's parameters. It reads
`/api/v1/spec` from the deployment itself, which means the contract you get is
the one that build actually serves.

With no arguments it lists every operation:

```bash theme={"dark"}
cube spec
```

```
METHOD  PATH                                            SUMMARY
GET     /api/v1/deployments                             Get deployments
PUT     /api/v1/deployments/{deploymentId}              Update a deployment
...
```

Pass a pattern to narrow it down. The match is case-insensitive and covers the
method, path, summary, and operation id:

```bash theme={"dark"}
cube spec settings
```

Add `--json` to get OpenAPI instead of a table. Unfiltered, that is the entire
document — pipe it into a code generator or a validator. Filtered, it is a
smaller but still valid document containing just the matching operations plus
every schema they reference, transitively:

```bash theme={"dark"}
cube spec updateDeployment --json
```

That last form is the one to reach for when you want an endpoint's full
parameter list: the request body's schema is included rather than left as a
`$ref` pointing into a document you would then have to fetch in full.

<Tip>
  Point an agent at `cube spec <topic> --json` and it can construct a correct
  request without any hardcoded knowledge of the API.
</Tip>

## Data model Git workflow

Edit the data model through branches without touching production:

```bash theme={"dark"}
cube data-model create-branch DEPLOYMENT_ID my-branch
DEV=$(cube data-model dev-mode DEPLOYMENT_ID my-branch --json | jq -r .branchName)
cube data-model put DEPLOYMENT_ID model/cubes/orders.yml --file orders.yml --branch "$DEV"
cube data-model commit DEPLOYMENT_ID --branch "$DEV" -m "add orders cube"
cube data-model exit-dev-mode DEPLOYMENT_ID
cube data-model delete-branch DEPLOYMENT_ID "$DEV"
cube data-model merge-to-default DEPLOYMENT_ID --branch my-branch -m "add orders cube"
```

`commit` pushes the dev branch's edits to the shared branch it was forked from, and
`merge-to-default` merges that branch into the deploy branch, rebuilds production, and
**deletes the branch it merged** — pass `--keep-branch` to keep it.

<Warning>
  Check that `$DEV` is set before `put` and `commit` use it. An interactive shell has no
  `pipefail`, so a failed `dev-mode` leaves it empty and `jq` still exits 0 — and `put` and
  `commit` accept an empty `--branch`, sending an empty field rather than stopping. They
  would then act on whatever your dev-mode session currently points at. `delete-branch`,
  the third line taking `$DEV`, does refuse it, so the sequence fails eventually — but only
  after `commit` has already pushed. In a script, `set -o pipefail` and a `[ -n "$DEV" ]`
  guard cover it.
</Warning>

That accounts for `my-branch`; `exit-dev-mode` and `delete-branch` account for what
you'd otherwise leave behind. Dev mode is per-credential state, so while a session stays open every
command that omits `--branch` targets that dev branch instead of the deploy branch, and
each pass through this workflow forks another `dev-…` branch. Releasing and pruning
before the merge also keeps the fork's parent around until the fork is gone.

<Info>
  File writes (`put`, `delete`, `rename`) only land on a personal **`dev-…` branch**,
  which is what `dev-mode` forks and prints. Pass that name via `--branch`, or omit
  `--branch` to use your active dev-mode branch. Writes to any other branch are
  rejected by the API.

  `create-branch --dev-mode` is not a shortcut for this: it points your session at the
  new branch without forking, so writes to the name you gave it are rejected with
  *"Branch … is not a dev-mode branch"* even though `build-status` reports that branch
  as `dev_mode`. Run `dev-mode` on it to get a name you can write to.
</Info>

`enable-branch` keeps a shared branch's [staging environment][ref-staging-env]
always active, so it stays queryable without anyone viewing the branch in the
UI — useful for running tests against a branch from CI. `disable-branch` reverts
to the default, where the environment is only active while viewed.
`cube data-model branches DEPLOYMENT_ID` shows the current state per branch, and
`cube environments list DEPLOYMENT_ID --type staging` lists the enabled ones with
their API credentials.

```bash theme={"dark"}
cube data-model enable-branch DEPLOYMENT_ID my-branch
cube data-model disable-branch DEPLOYMENT_ID my-branch
```

## dbt sync

Pull a dbt project's models in as cubes. The repository, credential and
warehouse settings come from the deployment's dbt integration, so a sync needs
only the deployment:

```bash theme={"dark"}
cube dbt sync DEPLOYMENT_ID --wait
```

Each sync creates a **new branch** for the generated cubes and prints its name.
`--wait` polls until the sync finishes, reporting each stage, then prints the
generated files; it exits non-zero if the sync fails. Without `--wait` it returns
a `syncJobId` you can follow yourself:

```bash theme={"dark"}
cube dbt status DEPLOYMENT_ID SYNC_JOB_ID --wait
cube dbt result DEPLOYMENT_ID SYNC_JOB_ID
cube dbt cancel DEPLOYMENT_ID SYNC_JOB_ID
```

`--ref` syncs a specific branch or tag of the dbt repository instead of the one
saved on the integration — which is what makes a pull-request gate meaningful,
since otherwise every run would compile the tracked branch:

```bash theme={"dark"}
cube dbt sync DEPLOYMENT_ID --ref feature/orders-model --wait
```

<Note>
  `--ref` takes a branch or tag, not a commit SHA. Syncs are not free — each one
  provisions a sandbox and parses the project — so prefer one per push over one per
  commit.
</Note>

### Sync history and logs

`history` lists a deployment's recent syncs — how each one was triggered, how it
ended, and how long it took — and `logs` prints one sync's phase timeline,
including the text a failed phase produced:

```bash theme={"dark"}
cube dbt history DEPLOYMENT_ID
cube dbt logs DEPLOYMENT_ID SYNC_JOB_ID
```

`history` narrows with `--status` (`RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`,
`UNKNOWN`) and `--trigger` (`manual`, `api`, `webhook`, `agent`, `unknown`) — both
case-sensitive as spelled here — and pages with `--first`/`--after`, taking the cursor
from `pageInfo.endCursor` in `--json` output. A page holds at most 100 runs, so a
larger `--first` returns 100 with `pageInfo.hasNextPage` set. `logs` takes no paging
flags — one sync's timeline is one page, and each line carries the phase it belongs
to and how long that phase took.

Both need only `SchemaRead`. Durations are the server's own single-clock figure, so
they never disagree with the run they describe. `--json` carries the rest of each
record — the dbt ref that was synced, the phase that failed, per-phase timings and
manifest counts.

`logs` is what turns a red CI step into something self-explaining: a failed
`--wait` reports the reason, and the timeline says which phase produced it.

```bash theme={"dark"}
cube dbt sync "$DEPLOYMENT_ID" --ref "$GITHUB_HEAD_REF" --wait --json > sync.json || {
  SYNC_JOB_ID=$(jq -r '.syncJobId // empty' sync.json)
  [ -n "$SYNC_JOB_ID" ] && cube dbt logs "$DEPLOYMENT_ID" "$SYNC_JOB_ID"
  exit 1
}
```

A failed `--wait --json` still writes its document before exiting non-zero, which
is what leaves the `syncJobId` there to follow up on.

<Note>
  A cancelled sync is listed as `CANCELLED` by `history`, but reported as a failure by
  `status` and by `sync --wait` — a gate polling for a terminal answer needs one, and the
  reason it prints says the sync was cancelled.
</Note>

### dbt sync as a CI test gate

Sync the branch under review, compile it, query it, and fail the job if any step
breaks — without touching production:

```yaml theme={"dark"}
# Dev mode is per credential, so two runs of this gate on one deployment would
# re-point each other's session. Serialise them, and don't cancel a run in flight:
# a cancelled run skips its prune step and leaves a branch and a live session behind.
concurrency:
  group: cube-dbt-gate-${{ vars.CUBE_DEPLOYMENT_ID }}
  cancel-in-progress: false

env:
  CUBE_API_URL: ${{ secrets.CUBE_API_URL }}
  CUBE_API_KEY: ${{ secrets.CUBE_API_KEY }}
  DEPLOYMENT_ID: ${{ vars.CUBE_DEPLOYMENT_ID }}

steps:
  - name: Sync the dbt branch under review
    shell: bash
    run: |
      cube dbt sync "$DEPLOYMENT_ID" --ref "$GITHUB_HEAD_REF" --wait --json > sync.json
      BRANCH=$(jq -er '.branchName | select(length > 0)' sync.json)
      echo "BRANCH=$BRANCH" >> "$GITHUB_ENV"

  - name: Compile and query the generated model
    shell: bash   # for -o pipefail: a failed `cube … | jq` must not yield an empty variable
    run: |
      DEV_BRANCH=$(cube data-model dev-mode "$DEPLOYMENT_ID" "$BRANCH" --json | jq -r .branchName)
      echo "DEV_BRANCH=$DEV_BRANCH" >> "$GITHUB_ENV"
      cube deployments build-status "$DEPLOYMENT_ID" --branch "$DEV_BRANCH" --wait
      API=$(cube deployments get "$DEPLOYMENT_ID" --json | jq -r .deploymentUrl)
      TOKEN=$(cube deployments token "$DEPLOYMENT_ID")
      OK=
      for _ in $(seq 20); do
        rm -f res.json
        CODE=$(curl -sSG -o res.json -w '%{http_code}' --max-time 95 \
          "$API/dev-mode/$DEV_BRANCH/cubejs-api/v1/load" \
          -H "Authorization: $TOKEN" \
          --data-urlencode 'query={"measures":["dbt_fct_orders.count"]}') || CODE=curl-$?
        if [ "$CODE" = 200 ] && jq -e '.data' res.json; then OK=1; break; fi
        if jq -e '.error == "Continue wait"' res.json >/dev/null 2>&1; then sleep 5; continue; fi
        if jq -e '.error' res.json >/dev/null 2>&1; then cat res.json; exit 1; fi
        echo "no answer from the API ($CODE), retrying"; sleep 5
      done
      [ -n "$OK" ] || { echo "query never returned data (last status $CODE):"
                        cat res.json 2>/dev/null; exit 1; }

  - name: Release the dev-mode session
    if: always()
    continue-on-error: true
    run: cube data-model exit-dev-mode "$DEPLOYMENT_ID"

  - name: Prune the branches the gate created
    run: |
      rc=0
      cube data-model delete-branch "$DEPLOYMENT_ID" "$DEV_BRANCH" || rc=$?
      cube data-model delete-branch "$DEPLOYMENT_ID" "$BRANCH" || rc=$?
      exit $rc
```

With `--wait --json`, the sync returns the generated branch and terminal result in one
document. The query must use the deployment's `deploymentUrl`, and the loop must retry
[`Continue wait`][ref-rest-api-continue-wait] responses until data arrives. Replace
`dbt_fct_orders.count` with a measure generated by the sync.

<Warning>
  Give the gate its own API key. Dev mode is per credential, so concurrent runs sharing a
  key can re-point each other's session. The concurrency group serializes them, and the
  release step runs even after a failure.
</Warning>

<Warning>
  Compile the personal `dev-…` branch returned by `data-model dev-mode`, not the shared
  branch created by the sync. The shared branch has no active runtime by default.
</Warning>

Keep `shell: bash` on the piped step so a failed `cube` command cannot be hidden by a
successful `jq` process.

New dbt inputs such as `dbt sync --ref` reject an empty value, as do required branch
arguments such as `data-model dev-mode` and `delete-branch`. Existing optional flags keep
their previous behavior: `deployments build-status --branch ''` is still accepted for a
one-shot status request, but is rejected with the new `--wait` gate. Note that
`$GITHUB_HEAD_REF` is only set on `pull_request` events; on any other trigger `--ref`
gets an empty string, which is why the run stops there.

Other existing optional `--branch` flags may accept an empty value for compatibility;
omit them when you want the documented default.

The API key needs `SchemaUpdate`, `SchemaRead`, `SchemaUpdateDevBranches`, and
`DeploymentRead` for this deployment. See [API keys][ref-api-keys] and [custom
roles][ref-custom-roles].

<Info>
  A successful gate prunes both branches it creates: the sync branch and its personal
  `dev-…` fork. Failed runs keep them for inspection. Add `--remove-on-upstream` to the
  cleanup commands if the connected Git provider branch should also be deleted.
</Info>

## Environment variables

| Variable                 | Description                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------------- |
| `CUBE_API_URL`           | Tenant URL, e.g. `https://TENANT.cubecloud.dev` (alternative to a saved context)            |
| `CUBE_API_KEY`           | Credential: an API key or token (alternative to `cube login`)                               |
| `CUBE_AUTH_SCHEME`       | Force the `Authorization` scheme: `bearer` or `api-key` (auto-detected by default)          |
| `CUBE_NO_UPDATE_CHECK`   | Disable the background update check                                                         |
| `CUBE_NO_TELEMETRY`      | Disable anonymous usage telemetry (also disabled when `CI` is set)                          |
| `CUBEJS_TELEMETRY=false` | Legacy alias for `CUBE_NO_TELEMETRY`, kept for compatibility with the previous `cubejs` CLI |
| `CUBE_VERSION`           | Installer only: release tag to install                                                      |
| `CUBE_INSTALL_DIR`       | Installer only: install directory                                                           |

## Telemetry

The CLI sends anonymous usage events (command group, success/failure,
version, platform). No personal data is collected; the anonymous identifier
is a hash of the OS machine id. Telemetry is disabled automatically in CI,
or explicitly with `CUBE_NO_TELEMETRY=1` (or the legacy `CUBEJS_TELEMETRY=false`).

[ref-api-keys]: /admin/account-billing/api-keys

[ref-custom-roles]: /admin/users-and-permissions/custom-roles

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-rest-api-continue-wait]: /reference/core-data-apis/rest-api#continue-wait

[ref-staging-env]: /admin/deployment/environments#staging-environments

[ref-update-channels]: /admin/deployment#update-channels


# Configuration options
Source: https://docs.cube.dev/reference/configuration/config

Following configuration options can be defined either using Python, in a cube.py file, or using JavaScript, in a cube.js file.

<Info>
  Note that configuration options follow the [snake case][link-snake-case]
  convention in Python (`base_path`) and the [camel case][link-camel-case] convention in
  JavaScript (`basePath`).
</Info>

Every configuration option that is a function (e.g., `query_rewrite`)
can be defined as either synchronous or asynchronous. Cube will await for
the completion of asynchronous functions.

It's wise to make functions that are called on each request as fast as
possible to minimize the performance hit. Consider using caching when
applicable and performing calculations outside of these functions.

## Data model

### `schema_path`

Path to data model files.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  config.schema_path = 'my-data-model'
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    schemaPath: 'my-data-model'
  }
  ```
</CodeGroup>

This configuration option can also be set using the [`CUBEJS_SCHEMA_PATH`](/reference/configuration/environment-variables#cubejs_schema_path)
environment variable. The default value is `model`.

Use [`repositoryFactory`][self-repofactory] for [multitenancy][ref-multitenancy]
or when a more flexible setup is needed.

### `context_to_app_id`

It's a [multitenancy][ref-multitenancy] option.

`context_to_app_id` is a function to determine an app id which is used as the
caching key for the compiled data model and other data model-related in-memory
structures. Each distinct app id gets its own data model compilation, which is
what enables [`COMPILE_CONTEXT`][ref-compile-context] and per-tenant
[`repository_factory`][self-repofactory].

<Warning>
  `context_to_app_id` enables multitenancy for data model compilation only. On its
  own, it leaves querying and caching shared across app ids. To isolate those per
  tenant as well:

  * [`pre_aggregations_schema`][self-pre-aggregations-schema] gives each tenant its
    own pre-aggregation tables. It is resolved per app id, so a schema name derived
    from the security context requires `context_to_app_id` to be defined as well.
  * [`context_to_orchestrator_id`][self-orchestrator-id] gives each tenant its own
    database connections, query queues, and query results cache.

  See [multitenancy][ref-multitenancy] for details.
</Warning>

Called on each request.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('context_to_app_id')
  def context_to_app_id(ctx: dict) -> str:
    return f"CUBE_APP_{ctx['securityContext']['tenant_id']}"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    contextToAppId: ({ securityContext }) => {
      return `CUBE_APP_${securityContext.tenant_id}`
    }
  }
  ```
</CodeGroup>

### `repository_factory`

This option allows to customize the repository for Cube data model files.
It is a function, which accepts a context object and can dynamically provide
data model files. Learn more about it in [multitenancy][ref-multitenancy].

Called only once per [`app_id`][self-opts-ctx-to-appid].

You can use convenient `file_repository` implementation to read files
from a specified path:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config, file_repository

  @config('repository_factory')
  def repository_factory(ctx: dict) -> list[dict]:
    return file_repository(f"model/{ctx['securityContext']['tenant_id']}")


  ```

  ```javascript title="JavaScript" theme={"dark"}
  const { FileRepository } = require("@cubejs-backend/server-core")

  module.exports = {
    repositoryFactory: ({ securityContext }) => {
      return new FileRepository(`model/${securityContext.tenant_id}`)
    }
  }
  ```
</CodeGroup>

You can also provide file contents directly, e.g., after fetching them
from a remote storage or via an API:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config, file_repository

  @config('repository_factory')
  def repository_factory(ctx: dict) -> list[dict]:
    context = ctx['securityContext']

    return [
      {
        'fileName': 'file.js',
        'content': 'contents of file'
      }
    ]

  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    repositoryFactory: ({ securityContext }) => {
      return {
        dataSchemaFiles: async () =>
          await Promise.resolve([
            {
              fileName: 'file.js',
              content: 'contents of file'
            }
          ])
      }
    }
  }
  ```
</CodeGroup>

### `schema_version`

`schema_version` can be used to tell Cube that the data model should be recompiled
in case it depends on dynamic definitions fetched from some external database or
API.

This method is called on each request however `RequestContext` parameter is
reused per application ID as determined by
[`context_to_app_id`][self-opts-ctx-to-appid]. If the returned string is different,
the data model will be recompiled. It can be used in both multi-tenant and
single tenant environments.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config
  import random

  @config('schema_version')
  def schema_version(ctx: dict) -> str:
    # Don't do this!
    # Data model would be recompiled on each request
    context = ctx['securityContext']

    return random.random()
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    schemaVersion: ({ securityContext }) => {
      // Don't do this!
      // Data model would be recompiled on each request
      return Math.random()
    }
  }



  ```
</CodeGroup>

### `compiler_cache_size`

Maximum number of compiled data models to persist with in-memory cache. Defaults
to 250, but optimum value will depend on deployed environment. When the max is
reached, will start dropping the least recently used data models from the cache.
Must be a positive integer; the cache can not be disabled.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  config.compiler_cache_size = 100
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    compilerCacheSize: 100
  }
  ```
</CodeGroup>

This configuration option can also be set using the [`CUBEJS_COMPILER_CACHE_SIZE`](/reference/configuration/environment-variables#cubejs_compiler_cache_size)
environment variable, and takes precedence over it. Note that the environment
variable also sizes the SQL API's compiler cache, which this option does not
affect.

### `max_compiler_cache_keep_alive`

Maximum length of time in ms to keep compiled data models in memory. Default
keeps data models in memory indefinitely.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  config.max_compiler_cache_keep_alive = 10000
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    maxCompilerCacheKeepAlive: 10000
  }
  ```
</CodeGroup>

### `update_compiler_cache_keep_alive`

Setting `update_compiler_cache_keep_alive` to `True` keeps frequently used data models
in memory by reseting their `max_compiler_cache_keep_alive` every time they are
accessed.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  config.update_compiler_cache_keep_alive = True
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    updateCompilerCacheKeepAlive: true
  }
  ```
</CodeGroup>

### `allow_js_duplicate_props_in_schema`

Boolean to enable or disable a check duplicate property names in all objects of
a data model. The default value is `false`, and it is means the compiler would
use the additional transpiler for check duplicates.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  config.allow_js_duplicate_props_in_schema = True
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    allowJsDuplicatePropsInSchema: true
  }
  ```
</CodeGroup>

## Query cache & queue

### `cache_and_queue_driver`

The cache and queue driver to use for the Cube deployment. Defaults to
`memory` in development, `cubestore` in production.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  config.cache_and_queue_driver = 'cubestore'
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    cacheAndQueueDriver: 'cubestore'
  }
  ```
</CodeGroup>

This configuration option can also be set using the [`CUBEJS_CACHE_AND_QUEUE_DRIVER`](/reference/configuration/environment-variables#cubejs_cache_and_queue_driver)
environment variable.

### `context_to_orchestrator_id`

<Warning>
  In versions of Cube prior to v0.29, each tenant would have an individual
  instance of the query orchestrator.
</Warning>

`context_to_orchestrator_id` is a function used to determine a caching key for the
query orchestrator instance. The query orchestrator holds database connections,
execution queues, pre-aggregation table caches. By default, the same instance is
used for **all** tenants; override this property in situations where each tenant
requires their own Query Orchestrator.

<Warning>
  Please remember to override
  [`pre_aggregations_schema`][self-pre-aggregations-schema] if you override
  `context_to_orchestrator_id`. Otherwise, you end up with table name clashes for
  your pre-aggregations.
</Warning>

Called on each request.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('context_to_app_id')
  def context_to_app_id(ctx: dict) -> str:
    return f"CUBE_APP_{ctx['securityContext']['tenant_id']}"

  @config('context_to_orchestrator_id')
  def context_to_orchestrator_id(ctx: dict) -> str:
    return f"CUBE_APP_{ctx['securityContext']['tenant_id']}"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    contextToAppId: ({ securityContext }) => {
      return `CUBE_APP_${securityContext.tenant_id}`
    },

    contextToOrchestratorId: ({ securityContext }) => {
      return `CUBE_APP_${securityContext.tenant_id}`
    }
  }
  ```
</CodeGroup>

### `context_to_cube_store_router_id`

`context_to_cube_store_router_id` is a function used to determine which Cube Store
router a request is routed to. It returns a string id that is used as a routing
key: requests that resolve to the same id share the same Cube Store router, while
distinct ids are routed to separate routers.

This is only relevant for deployments running multiple Cube Store routers (for
example, when [tenants][ref-multitenancy] are partitioned across routers to
isolate their pre-aggregation storage and query load). By default this function
is not set, and all requests use the same Cube Store router.

<Warning>
  `context_to_cube_store_router_id` requires
  [`context_to_orchestrator_id`][self-orchestrator-id] to also be defined.
</Warning>

Called on each request.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('context_to_cube_store_router_id')
  def context_to_cube_store_router_id(ctx: dict) -> str:
    return f"CUBE_ROUTER_{ctx['securityContext']['tenant_id']}"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    contextToCubeStoreRouterId: ({ securityContext }) => {
      return `CUBE_ROUTER_${securityContext.tenant_id}`
    }
  }
  ```
</CodeGroup>

### `driver_factory`

A function to provide a custom configuration for the data source driver.

Called once per [`data_source`][ref-schema-ref-datasource] for every
[orchestrator id][self-orchestrator-id].

Should be used to configure data source connections **dynamically** in
[multitenancy][ref-multitenancy].

Not recommended to be used when [multiple data sources][ref-multiple-data-sources]
can be configured **statically**. Use [`CUBEJS_DATASOURCES`](/reference/configuration/environment-variables#cubejs_datasources) and decorated environment
variables in that case.

In Python, should return a dictionary; in JavaScript, should return an object.
It should contain the `type` element corresponding to data source type and other
options that will be passed to a data source driver. You can lookup supported options
in the drivers' [source code][link-github-cube-drivers].

<Info>
  A custom `driver_factory` takes precedence over the [`CUBEJS_PRE_AGGREGATIONS_*`
  environment variables][ref-preagg-data-source], for every data source rather than only the
  ones it handles. If both are configured, the `driver_factory` connection is used for
  pre-aggregations as well and a `Pre-aggregation driver conflict` warning is logged.

  The factory can't return a different connection for pre-aggregations either, since it
  receives no signal distinguishing a pre-aggregation connection request from a regular one.
  To use a dedicated connection for pre-aggregation builds, define it entirely through the
  `CUBEJS_PRE_AGGREGATIONS_*` environment variables and don't configure a custom
  `driver_factory`.
</Info>

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('driver_factory')
  def driver_factory(ctx: dict) -> None:
    context = ctx['securityContext']
    data_source = ctx['dataSource']
   
    return {
      'type': 'postgres',
      'host': 'demo-db-examples.cube.dev',
      'user': 'cube',
      'password': '12345',
      'database': data_source
    }
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    driverFactory: ({ securityContext, dataSource }) => {
      return {
        type: 'postgres',
        host: 'demo-db-examples.cube.dev',
        user: 'cube',
        password: '12345',
        database: dataSource
      }
    }
  }



  ```
</CodeGroup>

In JavaScript, custom driver implementations can also be loaded:

```javascript theme={"dark"}
const VeryCustomDriver = require('cube-custom-driver')

module.exports = {
  driverFactory: ({ securityContext, dataSource }) => {
    return new VeryCustomDriver({
      /* options */
    })
  }
}
```

### `orchestrator_options`

<Warning>
  We **strongly** recommend leaving these options set to the defaults. Changing
  these values can result in application instability and/or downtime.
</Warning>

You can pass this object to set advanced options for the query orchestrator.

| Option                                         | Description                                                                                                                                                                                                                                                                                                                                                                                       | Default Value           |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `continueWaitTimeout`                          | Long polling interval in seconds, maximum is 90                                                                                                                                                                                                                                                                                                                                                   | `10`                    |
| `rollupOnlyMode`                               | When enabled, an error will be thrown if a query can't be served from a pre-aggregation (rollup)                                                                                                                                                                                                                                                                                                  | `false`                 |
| `queryCacheOptions`                            | Query cache options for DB queries                                                                                                                                                                                                                                                                                                                                                                | `{}`                    |
| `queryCacheOptions.refreshKeyRenewalThreshold` | Time in seconds to cache the result of [`refresh_key`][ref-schema-cube-ref-refresh-key] check                                                                                                                                                                                                                                                                                                     | `defined by DB dialect` |
| `queryCacheOptions.backgroundRenew`            | Controls whether to wait in foreground for refreshed query data if `refresh_key` value has been changed. Refresh key queries or pre-aggregations are never awaited in foreground and always processed in background unless cache is empty. If `true` it immediately returns values from cache if available without [`refresh_key`][ref-schema-cube-ref-refresh-key] check to renew in foreground. | `false`                 |
| `queryCacheOptions.queueOptions`               | Query queue options for DB queries                                                                                                                                                                                                                                                                                                                                                                | `{}`                    |
| `preAggregationsOptions`                       | Query cache options for pre-aggregations                                                                                                                                                                                                                                                                                                                                                          | `{}`                    |
| `preAggregationsOptions.maxPartitions`         | The maximum number of partitions each pre-aggregation in a cube can use.                                                                                                                                                                                                                                                                                                                          | `10000`                 |
| `preAggregationsOptions.queueOptions`          | Query queue options for pre-aggregations                                                                                                                                                                                                                                                                                                                                                          | `{}`                    |
| `preAggregationsOptions.externalRefresh`       | When running a separate instance of Cube to refresh pre-aggregations in the background, this option can be set on the API instance to prevent it from trying to check for rollup data being current - it won't try to create or refresh them when this option is `true`                                                                                                                           | `false`                 |

`queryCacheOptions` are used while querying database tables, while
`preAggregationsOptions` settings are used to query pre-aggregated tables.

<Warning>
  Setting these options is highly discouraged as these are considered to be
  system-level settings. Please use [`CUBEJS_ROLLUP_ONLY`](/reference/configuration/environment-variables#cubejs_rollup_only), [`CUBEJS_DB_QUERY_TIMEOUT`](/reference/configuration/environment-variables#cubejs_db_query_timeout), and
  [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency) [environment variables][ref-environment-variables] instead.
</Warning>

Timeout and interval options' values are in seconds.

| Option              | Description                                                                                                                                                                                                                                                                                             | Default Value |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `concurrency`       | Maximum number of queries to be processed simultaneosly. For drivers with connection pool [`CUBEJS_DB_MAX_POOL`](/reference/configuration/environment-variables#cubejs_db_max_pool) should be adjusted accordingly. Typically pool size should be at least twice of total concurrency among all queues. | `2`           |
| `executionTimeout`  | Total timeout of single query                                                                                                                                                                                                                                                                           | `600`         |
| `orphanedTimeout`   | Query will be marked for cancellation if not requested during this period.                                                                                                                                                                                                                              | `120`         |
| `heartBeatInterval` | Worker heartbeat interval. If `4*heartBeatInterval` time passes without reporting, the query gets cancelled.                                                                                                                                                                                            | `30`          |

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  config.orchestrator_options = {
    'continueWaitTimeout': 10,
    'rollupOnlyMode': False,
    'queryCacheOptions': {
      'refreshKeyRenewalThreshold': 30,
      'backgroundRenew': True,
      'queueOptions': {
        'concurrency': 3,
        'executionTimeout': 1000,
        'orphanedTimeout': 1000,
        'heartBeatInterval': 1000
      }
    },
    'preAggregationsOptions': {
      'externalRefresh': False,
      'maxPartitions': 100,
      'queueOptions': {
        'concurrency': 3,
        'executionTimeout': 1000,
        'orphanedTimeout': 1000,
        'heartBeatInterval': 1000
      }
    }
  }
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    orchestratorOptions: {
      continueWaitTimeout: 10,
      rollupOnlyMode: false,
      queryCacheOptions: {
        refreshKeyRenewalThreshold: 30,
        backgroundRenew: true,
        queueOptions: {
          concurrency: 3,
          executionTimeout: 1000,
          orphanedTimeout: 1000,
          heartBeatInterval: 1000
        }
      },
      preAggregationsOptions: {
        externalRefresh: false,
        maxPartitions: 100,
        queueOptions: {
          concurrency: 3,
          executionTimeout: 1000,
          orphanedTimeout: 1000,
          heartBeatInterval: 1000
        }
      }
    }
  }
  ```
</CodeGroup>

## Pre-aggregations

### `pre_aggregations_schema`

Database schema name to use for storing pre-aggregations.

Either string or function can be passed. Providing a function allows to set
the schema name dynamically depending on the security context.

Defaults to `dev_pre_aggregations` in [development mode][ref-development-mode]
and `prod_pre_aggregations` in production.

<Info>
  In Cube Cloud, all [environments][ref-environments] share the same pre-aggregations schema name by default.
  This allows reusing pre-aggregations across environments, saving both time and cost.
</Info>

This configuration option can also be set using the [`CUBEJS_PRE_AGGREGATIONS_SCHEMA`](/reference/configuration/environment-variables#cubejs_pre_aggregations_schema)
environment variable.

<Warning>
  It's **strongly** recommended to use different pre-aggregation schemas in
  development and production environments to avoid pre-aggregation table clashes.
</Warning>

<Warning>
  Cube will wipe out the contents of this database schema before use. It shall
  be used exclusively by Cube and shall not be shared with any application.
</Warning>

Called once per [`app_id`][self-opts-ctx-to-appid].

<Warning>
  Because this option is evaluated once per app id, deriving the schema name from
  the security context requires [`context_to_app_id`][self-opts-ctx-to-appid] to be
  defined as well. Otherwise all tenants share a single app id, and every one of
  them ends up pinned to the schema name resolved for whichever tenant triggered
  the first data model compilation.
</Warning>

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('pre_aggregations_schema')
  def pre_aggregations_schema(ctx: dict) -> str:
    return f"pre_aggregations_{ctx['securityContext']['tenant_id']}"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    preAggregationsSchema: ({ securityContext }) => {
      return `pre_aggregations_${securityContext.tenant_id}`
    }
  }
  ```
</CodeGroup>

### `scheduled_refresh_timer`

<Warning>
  This is merely a refresh worker's heartbeat. It doesn't affect the freshness of
  pre-aggregations or refresh keys, nor how frequently Cube accesses the database.
  Setting this value to `30s` doesn't mean pre-aggregations or in-memory cache
  would be refreshed every 30 seconds but instead refresh key is checked for
  freshness every 30 seconds in the background. Please consult the [cube
  `refresh_key` documentation][ref-schema-cube-ref-refresh-key] and
  [pre-aggregation `refresh_key` documentation][ref-pre-aggregations-refresh-key]
  on how to set data refresh intervals.
</Warning>

<Warning>
  Setting this variable enables refresh worker mode, which means it shouldn't
  usually be set to any constant number but depend on your cluster environment.
  Setting it to the constant value in the cluster environment will lead to the
  instantiation of Refresh Worker on every Cube instance of your cluster,
  including API ones. This will usually lead to refreshing race conditions and to
  out of memory errors.
</Warning>

Cube enables background refresh by default using the [`CUBEJS_REFRESH_WORKER`](/reference/configuration/environment-variables#cubejs_refresh_worker)
environment variable.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  config.scheduled_refresh_timer = 60
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    scheduledRefreshTimer: 60
  }
  ```
</CodeGroup>

Best practice is to run `scheduled_refresh_timer` in a separate worker Cube
instance.

You may also need to configure
[`scheduledRefreshTimeZones`](#scheduled_refresh_time_zones) and
[`scheduledRefreshContexts`](#scheduled_refresh_contexts).

### `scheduled_refresh_time_zones`

This option specifies a list of time zones that pre-aggregations will be built
for. It has impact on [pre-aggregation matching][ref-matching-preaggs].

Either an array or function returning an array can be passed. Providing a function
allows to set the time zones dynamically depending on the security context.

Time zones should be specified in the [TZ Database Name][link-wiki-tz] format,
e.g., `America/Los_Angeles`.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  # An array of time zones
  config.scheduled_refresh_time_zones = [
    'America/Vancouver',
    'America/Toronto'
  ]

  # Alternatively, a function returning an array of time zones
  @config('scheduled_refresh_time_zones')
  def scheduled_refresh_time_zones(ctx: dict) -> list[str]:
    time_zones = {
      'tenant_1': ['America/New_York'],
      'tenant_2': ['America/Chicago'],
      'tenant_3': ['America/Los_Angeles']
    }
    default_time_zones = ['UTC']
    tenant_id = ctx['securityContext']['tenant_id']
    return time_zones.get(tenant_id, default_time_zones)
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    // An array of time zones
    scheduledRefreshTimeZones: [
      'America/Vancouver',
      'America/Toronto'
    ],

    // Alternatively, a function returning an array of time zones
    scheduledRefreshTimeZones: ({ securityContext }) => {
      let time_zones = {
        'tenant_1': ['America/New_York'],
        'tenant_2': ['America/Chicago'],
        'tenant_3': ['America/Los_Angeles']
      }
      let default_time_zones = ['UTC']  
      let tenant_id = securityContext.tenant_id
      return time_zones[tenant_id] || default_time_zones
    }
  }
  ```
</CodeGroup>

The default value is a list of a single time zone: `UTC`.

This configuration option can also be set using the
[`CUBEJS_SCHEDULED_REFRESH_TIMEZONES`](/reference/configuration/environment-variables#cubejs_scheduled_refresh_timezones) environment variable.

### `scheduled_refresh_contexts`

When trying to configure scheduled refreshes for pre-aggregations that use the
`securityContext` inside `context_to_app_id` or `context_to_orchestrator_id`, you must
also set up `scheduled_refresh_contexts`. This will allow Cube to generate the
necessary security contexts prior to running the scheduled refreshes.

<Warning>
  Leaving `scheduled_refresh_contexts` unconfigured will lead to issues where the
  security context will be `undefined`. This is because there is no way for Cube
  to know how to generate a context without the required input.
</Warning>

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('scheduled_refresh_contexts')
  def scheduled_refresh_contexts() -> list[object]:
    return [
      {
        'securityContext': {
          'tenant_id': 123,
          'bucket': 'demo'
        }
      },
      {
        'securityContext': {
          'tenant_id': 456,
          'bucket': 'demo_2'
        }
      }
    ]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    scheduledRefreshContexts: () => [
      {
        securityContext: {
          tenant_id: 123,
          bucket: 'demo'
        }
      },
      {
        securityContext: {
          tenant_id: 456,
          bucket: 'demo_2'
        }
      }
    ]
  }


  ```
</CodeGroup>

## Querying

### `query_rewrite`

This is a security hook to check your query just before it gets processed. You
can use this very generic API to implement any type of custom security checks
your app needs and rewrite input query accordingly.

Called on each request.

For example, you can use `query_rewrite` to add row-level security filter, if
needed:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('query_rewrite')
  def query_rewrite(query: dict, ctx: dict) -> dict:
    context = ctx['securityContext']

    if 'filter_by_region' in context:
      query['filters'].append({
        'member': 'regions.id',
        'operator': 'equals',
        'values': [context['region_id']],
      })

    return query
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    queryRewrite: (query, { securityContext }) => {
      if (securityContext.filter_by_region) {
        query.filters.push({
          member: 'regions.id',
          operator: 'equals',
          values: [securityContext.region_id]
        })
      }
      return query
    }
  }


  ```
</CodeGroup>

Raising an exception would prevent a query from running:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('query_rewrite')
  def query_rewrite(query: dict, ctx: dict) -> dict:
    raise Exception('You shall not pass! 🧙')
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    queryRewrite: (query, { securityContext }) => {
      throw new Error('You shall not pass! 🧙')
    }
  }
  ```
</CodeGroup>

<Note>
  Currently, there's no built-in way to access the data model metadata in
  `query_rewrite`. Please [track this issue](https://github.com/cube-js/cube/issues/4118)
  and read about a [workaround](https://github.com/cube-js/cube/issues/4118#issuecomment-2317925444).
</Note>

### `allow_ungrouped_without_primary_key`

Setting `allow_ungrouped_without_primary_key` to `True` disables the primary
key inclusion check for [ungrouped queries][ref-ungrouped-query].

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  config.allow_ungrouped_without_primary_key = True
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    allowUngroupedWithoutPrimaryKey: true
  }
  ```
</CodeGroup>

This configuration option can also be set using the
[`CUBEJS_ALLOW_UNGROUPED_WITHOUT_PRIMARY_KEY`](/reference/configuration/environment-variables#cubejs_allow_ungrouped_without_primary_key) environment variable.

<Info>
  When query pushdown in the SQL API is enabled via the `CUBESQL_SQL_PUSH_DOWN`
  environment variable, this option is enabled as well for the best user experience.
</Info>

## APIs

### `base_path`

The base path for the [REST (JSON) API](/reference/core-data-apis/rest-api/reference).

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  config.base_path = '/cube-api'
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    basePath: '/cube-api'
  }
  ```
</CodeGroup>

The default value is `/cubejs-api`.

### `http.cors`

CORS settings for the Cube REST (JSON) API can be configured by providing an object
with options [from here][link-express-cors-opts]:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  config.http = {
    'cors': {
      'origin': '*',
      'methods': 'GET,HEAD,PUT,PATCH,POST,DELETE',
      'preflightContinue': False,
      'optionsSuccessStatus': 204,
      'maxAge': 86400,
      'credentials': True
    }
  }
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    http: {
      cors: {
        origin: '*',
        methods: 'GET,HEAD,PUT,PATCH,POST,DELETE',
        preflightContinue: false,
        optionsSuccessStatus: 204,
        maxAge: 86400,
        credentials: true
      }
    }
  }
  ```
</CodeGroup>

### `web_sockets_base_path`

The base path for the [WebSocket server][ref-websockets].

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  config.web_sockets_base_path = '/websocket'
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    webSocketsBasePath: '/websocket'
  }
  ```
</CodeGroup>

The default value is `/` (the root path).

### `process_subscriptions_interval`

This property controls how often WebSocket client subscriptions are refreshed.
Defaults to `5000`.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  config.process_subscriptions_interval = 1000
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    processSubscriptionsInterval: true
  }
  ```
</CodeGroup>

### `context_to_api_scopes`

This function is used to select accessible [API scopes][ref-rest-scopes]
and effectively allow or disallow access to REST (JSON) API endpoints, based on
the [security context][ref-sec-ctx].

Security context is provided as the first argument. An array of scopes that
was set via [`CUBEJS_DEFAULT_API_SCOPES`](/reference/configuration/environment-variables#cubejs_default_api_scopes) is provided as the second argument.

Called on each request.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('context_to_api_scopes')
  def context_to_api_scopes(context: dict, default_scopes: list[str]) -> list[str]:
    return ['meta', 'data', 'graphql', 'sql']
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    contextToApiScopes: (securityContext, defaultScopes) => {
      return ['meta', 'data', 'graphql', 'sql']
    }
  }
  ```
</CodeGroup>

### `extend_context`

This function is used to extend the security context with additional data.

Called on each request.

It should return an object which gets appended to the *request context*,
an object that contains `securityContext` and that is passed as an argument to
other functions like `context_to_app_id` or `repository_factory`.

<Info>
  When using `extend_context`, you should also define [`context_to_app_id`][self-opts-ctx-to-appid]
  so that all possible values of the extended context are reflected in the app id.
</Info>

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config
   
  @config('extend_context')
  def extend_context(req: dict) -> dict:
    req.setdefault('securityContext', {}).update({'active_organization': 123})
    # req.setdefault('securityContext', {}).update({'active_organization': req['headers']['active_organization']})
    return req
   
  @config('context_to_app_id')
  def context_to_app_id(ctx: dict) -> dict:
    return f"CUBE_APP_{ctx['securityContext']['active_organization']}"
   
   
   

  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    extendContext: (req) => {
      return {
        securityContext: {
          ...req.securityContext,
          active_organization: 123
          // active_organization: req.headers.active_organization
        }
      }
    },

    contextToAppId: ({ securityContext }) => {
      return `CUBE_APP_${securityContext.active_organization}`
    }
  }
  ```
</CodeGroup>

You can use the custom value from extend context in your data model like this:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  {% set securityContext = COMPILE_CONTEXT['securityContext'] %}

  cubes:
    - name: users
      sql: |
        SELECT *
        FROM users
        WHERE organization_id={{ securityContext['active_organization'] }}

  ```

  ```javascript title="JavaScript" theme={"dark"}
  const { securityContext } = COMPILE_CONTEXT

  cube(`users`, {
    sql: `
      SELECT *
      FROM users
      WHERE organization_id=${securityContext.active_organization}
    `
  })
  ```
</CodeGroup>

<Info>
  `extend_context` is applied only to requests that go through APIs. It isn't
  applied to refresh worker execution. If you're looking for a way to provide
  global environment variables for your data model, please see the [execution
  environment documentation][ref-exec-environment-globals].
</Info>

### `check_auth`

Used in the [REST (JSON) API][ref-rest-api]. Default implementation parses the [JSON
Web Token][link-jwt] in the `Authorization` header, verifies it, and sets its
payload to the `securityContext`. [Read more][ref-sec-ctx] about JWT generation.

Called on each request.

You can return an object with the `security_context` field if you want to
customize [`SECURITY_CONTEXT`][ref-schema-cube-ref-ctx-sec-ctx].

You can use empty `check_auth` function to disable built-in security or
raise an exception to fail the authentication check.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('check_auth')
  def check_auth(ctx: dict, token: str) -> None:
    if token == 'my_secret_token':
      return {
        'security_context': {
          'user_id': 42
        }
      }

    raise Exception('Access denied')
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    checkAuth: (ctx, token) => {
      if (token === 'my_secret_token') {
        return {
          security_context: {
            user_id: 42
          }
        }
      }

      throw new Error('Access denied')
    }
  }

  ```
</CodeGroup>

<Note>
  Currently, raising an exception would result in an HTTP response with the
  status code 500 for Cube Core and 403 for Cube Cloud.
  Please [track this issue](https://github.com/cube-js/cube/issues/8136).
</Note>

### `jwt`

```typescript theme={"dark"}
  jwt: {
    jwkUrl?: ((payload: any) => string) | string;
    key?: string;
    algorithms?: string[];
    issuer?: string[];
    audience?: string;
    subject?: string;
    claimsNamespace?: string;
  };
```

| Option            | Description                                                                                                                                         | Environment variable                                                                                                              |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `jwkUrl`          | URL from which JSON Web Key Sets (JWKS) can be retrieved                                                                                            | Can also be set using [`CUBEJS_JWK_URL`](/reference/configuration/environment-variables#cubejs_jwk_url)                           |
| `key`             | JSON string that represents a cryptographic key. Similar to [`CUBEJS_API_SECRET`](/reference/configuration/environment-variables#cubejs_api_secret) | Can also be set using [`CUBEJS_JWT_KEY`](/reference/configuration/environment-variables#cubejs_jwt_key)                           |
| `algorithms`      | [Any supported algorithm for decoding JWTs][gh-jsonwebtoken-algs]                                                                                   | Can also be set using [`CUBEJS_JWT_ALGS`](/reference/configuration/environment-variables#cubejs_jwt_algs)                         |
| `issuer`          | Issuer value which will be used to enforce the [`iss` claim from inbound JWTs][link-jwt-ref-iss]                                                    | Can also be set using [`CUBEJS_JWT_ISSUER`](/reference/configuration/environment-variables#cubejs_jwt_issuer)                     |
| `audience`        | Audience value which will be used to enforce the [`aud` claim from inbound JWTs][link-jwt-ref-aud]                                                  | Can also be set using [`CUBEJS_JWT_AUDIENCE`](/reference/configuration/environment-variables#cubejs_jwt_audience)                 |
| `subject`         | Subject value which will be used to enforce the [`sub` claim from inbound JWTs][link-jwt-ref-sub]                                                   | Can also be set using [`CUBEJS_JWT_SUBJECT`](/reference/configuration/environment-variables#cubejs_jwt_subject)                   |
| `claimsNamespace` | Namespace within the decoded JWT under which any custom claims can be found                                                                         | Can also be set using [`CUBEJS_JWT_CLAIMS_NAMESPACE`](/reference/configuration/environment-variables#cubejs_jwt_claims_namespace) |

### `check_sql_auth`

Used in the [SQL API][ref-sql-api]. Default
implementation verifies user name and password from environment variables:
[`CUBEJS_SQL_USER`](/reference/configuration/environment-variables#cubejs_sql_user), [`CUBEJS_SQL_PASSWORD`](/reference/configuration/environment-variables#cubejs_sql_password), but in [development
mode][ref-development-mode] it ignores validation.

Called on each new connection to Cube SQL API, on change user by `SET USER` or `__user` field, every `CUBESQL_AUTH_EXPIRE_SECS`.

For example, you can use `check_sql_auth` to validate username and password.
`password` argument is provided only when new connections are established.
`check_sql_auth` implementation should gracefully handle missing `password` field to handle change user and re-authentication flows.
`check_sql_auth` should always return `password` as it used for validation of password provided by user.
If clear text password can't be obtained, best practice is to return `password` provided as an argument after password validation.
Only security context is used for change user and re-authentication flows so returned `password` isn't checked in this case.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('check_sql_auth')
  def check_sql_auth(req: dict, user_name: str, password: str) -> dict:
    if user_name == 'my_user':
      if password and password != 'my_password':
        raise Exception('Access denied')
      return {
        'password': password,
        'securityContext': {
          'some': 'data'
        }
      }

    raise Exception('Access denied')

  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    checkSqlAuth: (req, user_name, password) => {
      if (user_name === 'my_user') {
        if (password && password !== 'my_password') {
          throw new Error('Access denied')
        }
        return {
          password,
          securityContext: {
            some: 'data'
          }
        }
      }

      throw new Error('Access denied')
    }
  }
  ```
</CodeGroup>

You can also check for the protocol and the authentication method as follows. This can
be useful for handling the NTLM authentication in the DAX API:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config
  import os

  @config('check_sql_auth')
  def check_sql_auth(req: dict, user_name: str, password: str) -> dict:
    # Handle NTLM authentication:
    # - for Power BI `runas` command
    # - for Power BI gateway
    if req['protocol'] == 'xmla' and req['method'] == 'ntlm':
      if (user_name == os.environ.get('CUBEJS_SQL_USER')):
        return {
          'password': os.environ.get('CUBEJS_SQL_PASSWORD'),
          'securityContext': {}
        }
      
      return {
        'password': os.environ.get('CUBEJS_SQL_PASSWORD'),
        'securityContext': {}
      }

    raise Exception('Access denied')
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    checkSqlAuth: (req, user_name, password) => {
      // handle ntlm auth scenarios (PBI "runas" command + PBI gateway auth)
      if (req.protocol === 'xmla' && req.method === 'ntlm') {
        if (user_name === process.env.CUBEJS_SQL_USER) {
          return {
            password: process.env.CUBEJS_SQL_PASSWORD,
            securityContext: {}
          }
        }
        
        return {
          password: process.env.CUBEJS_SQL_PASSWORD,
          securityContext: {}
        }
      }

      throw new Error('Access denied')
    }
  }
  ```
</CodeGroup>

### `can_switch_sql_user`

Used in the [SQL API][ref-sql-api]. Default implementation depends on
[`CUBEJS_SQL_SUPER_USER`](/reference/configuration/environment-variables#cubejs_sql_super_user) and returns `true` when it's equal to session's user.

Called on each change request from Cube SQL API.

For example, you can use `can_switch_sql_user` to define your custom logic:

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('can_switch_sql_user')
  def can_switch_sql_user(current_user: str, new_user: str) -> dict:
    if current_user == 'admin':
      return True

    if current_user == 'service':
      return new_user != 'admin'

    return False


  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    canSwitchSqlUser: (current_user, new_user) => {
      if (current_user === "admin") {
        return true
      }

      if (current_user === "service") {
        return new_user !== "admin"
      }

      return false
    }
  }
  ```
</CodeGroup>

### `context_to_groups`

Used by [access policies][ref-dap]. This option is used to derive a list of groups that
the user belongs to from the [security context][ref-sec-ctx]. These groups can then be
used to match [access policies][ref-dap-roles].

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('context_to_groups')
  def context_to_groups(ctx: dict) -> list[str]:
    return ctx['securityContext'].get('groups', ['default'])
  ```

  ```javascript title="JavaScript" theme={"dark"}

  module.exports = {
    contextToGroups: ({ securityContext }) => {
      return securityContext.groups || ['default']
    }
  }
  ```
</CodeGroup>

## Utility

### `logger`

A function to define a custom logger.

Accepts the following arguments:

* `message`: the message to be logged
* `params`: additional parameters

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  @config('logger')
  def logger(message: str, params: dict) -> None:
    print(f"{message}: {params}")
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    logger: (message, params) => {
      console.log(`${message}: ${JSON.stringify(params)}`)
    }
  }
  ```
</CodeGroup>

See also the [`CUBEJS_LOG_LEVEL`](/reference/configuration/environment-variables#cubejs_log_level) environment variable.

### `telemetry`

Cube collects high-level anonymous usage statistics for servers started in
[development mode][ref-development-mode]. It doesn't track any credentials, data
model contents or queries issued. This statistics is used solely for the purpose of
constant cube.js improvement.

You can opt out of it any time by setting `telemetry` option to `False` or,
alternatively, by setting [`CUBEJS_TELEMETRY`](/reference/configuration/environment-variables#cubejs_telemetry) environment variable to `false`.

<CodeGroup>
  ```python title="Python" theme={"dark"}
  from cube import config

  config.telemetry = True
  ```

  ```javascript title="JavaScript" theme={"dark"}
  module.exports = {
    telemetry: false
  }
  ```
</CodeGroup>

[gh-jsonwebtoken-algs]: https://github.com/auth0/node-jsonwebtoken#algorithms-supported

[link-express-cors-opts]: https://expressjs.com/en/resources/middleware/cors.html#configuration-options

[link-jwt]: https://jwt.io/

[link-jwt-ref-iss]: https://tools.ietf.org/html/rfc7519#section-4.1.1

[link-jwt-ref-sub]: https://tools.ietf.org/html/rfc7519#section-4.1.2

[link-jwt-ref-aud]: https://tools.ietf.org/html/rfc7519#section-4.1.3

[link-wiki-tz]: https://en.wikipedia.org/wiki/Tz_database

[ref-development-mode]: /reference/configuration/environment-variables#cubejs_dev_mode

[ref-multitenancy]: /embedding/multitenancy

[ref-preagg-data-source]: /docs/pre-aggregations/refreshing-pre-aggregations#pre-aggregation-data-source

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-sql-api]: /reference/core-data-apis/sql-api

[ref-pre-aggregations-refresh-key]: /reference/data-modeling/pre-aggregations#refresh_key

[ref-schema-cube-ref-refresh-key]: /reference/data-modeling/cube#refresh_key

[ref-schema-cube-ref-ctx-sec-ctx]: /reference/data-modeling/context-variables#security_context

[ref-sec-ctx]: /docs/data-modeling/access-control/context

[self-pre-aggregations-schema]: #pre_aggregations_schema

[self-opts-ctx-to-appid]: #context_to_app_id

[ref-schema-ref-datasource]: /reference/data-modeling/cube#data_source

[self-repofactory]: #repository_factory

[ref-exec-environment-globals]: /docs/data-modeling/dynamic/schema-execution-environment#nodejs-globals-processenv-consolelog-and-others

[ref-environment-variables]: /reference/configuration/environment-variables

[ref-rest-scopes]: /reference/core-data-apis/rest-api#api-scopes

[ref-config-options]: /admin/connect-to-data#configuration-options

[self-orchestrator-id]: #context_to_orchestrator_id

[ref-compile-context]: /reference/data-modeling/context-variables#compile_context

[ref-multiple-data-sources]: /admin/connect-to-data/multiple-data-sources

[ref-websockets]: /recipes/core-data-api/real-time-data-fetch

[ref-matching-preaggs]: /docs/pre-aggregations/matching-pre-aggregations

[link-snake-case]: https://en.wikipedia.org/wiki/Snake_case

[link-camel-case]: https://en.wikipedia.org/wiki/Camel_case

[link-github-cube-drivers]: https://github.com/cube-js/cube/tree/master/packages

[ref-ungrouped-query]: /reference/core-data-apis/queries#ungrouped-query

[ref-dap]: /docs/data-modeling/data-access-policies

[ref-dap-roles]: /docs/data-modeling/data-access-policies#data-access-roles

[ref-auth-integration]: /docs/data-modeling/access-control#authentication-integration

[ref-environments]: /admin/deployment/environments


# Environment variables
Source: https://docs.cube.dev/reference/configuration/environment-variables

To see a complete list of environment variables for a specific data source, please check the relevant page on Connecting to Data Sources.

<Info>
  To see a complete list of environment variables for a specific data source,
  please check the relevant page on [Connecting to Data Sources][ref-config-db].
</Info>

## `CUBEJS_API_SECRET`

The secret key used to sign and verify JWTs. Generated on project scaffold with
`npx cubejs-cli create`.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid string  | N/A                    | N/A                   |

See also the [`check_auth` configuration
option](/reference/configuration/config#check_auth).

## `CUBEJS_APP`

An application ID used to uniquely identify the Cube deployment. Can be
different for multitenant setups.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid string  | `cubejs`               | `cubejs`              |

## `CUBEJS_AUTO_RUN_MODE`

The deployment-wide default for whether [Explore](/docs/explore-analyze/explore)
and [Workbooks](/docs/explore-analyze/workbooks/querying-data) tabs run their
query automatically as it's built, or wait for an explicit **Run query**. Set
via the **Auto-run** switch in [Model Configuration](/docs/data-modeling/configuration#auto-run).
A view's `meta.auto_run` setting and a user's per-tab toggle both take
precedence over this default. Only the literal string `false` turns it off —
any other value (including unset) is treated as on.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `true`                 | `true`                |

## `CUBEJS_AWS_KEY`

The AWS Access Key ID to use for database connections.

| Possible Values           | Default in Development | Default in Production |
| ------------------------- | ---------------------- | --------------------- |
| A valid AWS Access Key ID | N/A                    | N/A                   |

## `CUBEJS_AWS_SECRET`

The AWS Secret Access Key to use for database connections.

| Possible Values               | Default in Development | Default in Production |
| ----------------------------- | ---------------------- | --------------------- |
| A valid AWS Secret Access Key | N/A                    | N/A                   |

## `CUBEJS_AWS_REGION`

The AWS region to use for database connections.

| Possible Values                        | Default in Development | Default in Production |
| -------------------------------------- | ---------------------- | --------------------- |
| [A valid AWS region][aws-docs-regions] | N/A                    | N/A                   |

## `CUBEJS_AWS_S3_OUTPUT_LOCATION`

The S3 path to store [AWS Athena][aws-athena] query results made by Cube.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid S3 path | N/A                    | N/A                   |

## `CUBEJS_AWS_ATHENA_WORKGROUP`

The name of the [AWS Athena workgroup][aws-athena-workgroup] in which the query
is being started.

| Possible Values                                  | Default in Development | Default in Production |
| ------------------------------------------------ | ---------------------- | --------------------- |
| [A valid Athena Workgroup][aws-athena-workgroup] | N/A                    | N/A                   |

## `CUBEJS_AWS_ATHENA_CATALOG`

The name of the AWS Athena catalog to use for queries.

| Possible Values                                   | Default in Development | Default in Production |
| ------------------------------------------------- | ---------------------- | --------------------- |
| [A valid Athena Catalog name][aws-athena-catalog] | N/A                    | N/A                   |

## `CUBEJS_AWS_ATHENA_ASSUME_ROLE_ARN`

The ARN of the IAM role to assume for Athena access.

| Possible Values      | Default in Development | Default in Production |
| -------------------- | ---------------------- | --------------------- |
| A valid IAM role ARN | N/A                    | N/A                   |

## `CUBEJS_AWS_ATHENA_ASSUME_ROLE_EXTERNAL_ID`

The external ID to use when assuming the IAM role, if required by the role's
trust policy.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A string        | N/A                    | N/A                   |

## `CUBEJS_DB_SCHEMA`

The name of the schema to use as `information_schema` filter. Reduces count of
tables loaded during data model generation.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid schema name | N/A                    | N/A                   |

## `CUBEJS_CACHE_AND_QUEUE_DRIVER`

The cache and queue driver to use for the Cube deployment.

| Possible Values       | Default in Development | Default in Production |
| --------------------- | ---------------------- | --------------------- |
| `cubestore`, `memory` | `memory`               | `cubestore`           |

It can be also set using the [`cache_and_queue_driver` configuration
option](/reference/configuration/config#cache_and_queue_driver).

## `CUBEJS_COMPILER_CACHE_SIZE`

The maximum number of compiled data models to keep in the in-memory compiler
cache. When the maximum is reached, the least recently used data models are
dropped from the cache. The optimum value depends on the deployed environment.

This variable sizes two separate caches: the data model compiler cache and the
[SQL API][ref-sql-api]'s own compiler cache. Setting it applies the same maximum
to both. When it is unset, each falls back to its own default, so the effective
default differs between them.

| Cache                     | Possible Values   | Default in Development | Default in Production |
| ------------------------- | ----------------- | ---------------------- | --------------------- |
| Data model compiler cache | A positive number | `250`                  | `250`                 |
| SQL API compiler cache    | A positive number | `100`                  | `100`                 |

<Note>
  Neither cache can be disabled, so `0` is rejected rather than accepted and
  ignored. The same applies to the configuration option.
</Note>

The data model compiler cache can be also sized using the [`compiler_cache_size`
configuration option](/reference/configuration/config#compiler_cache_size),
which takes precedence over this environment variable. The SQL API compiler
cache reads this environment variable only, so the configuration option does not
affect it.

## `CUBEJS_CONCURRENCY`

The number of concurrent connections each query queue has to the database.

| Possible Values | Default in Development                      | Default in Production                       |
| --------------- | ------------------------------------------- | ------------------------------------------- |
| A valid number  | [See database-specific page][ref-config-db] | [See database-specific page][ref-config-db] |

It can be also set as `concurrency` in the [`orchestrator_options` configuration
option](/reference/configuration/config#orchestrator_options).

If you'd like to adjust the concurrency for the refresh worker, use
[`CUBEJS_REFRESH_WORKER_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_refresh_worker_concurrency).

## `CUBEJS_REFRESH_WORKER_CONCURRENCY`

The number of pre-aggregation queries the refresh worker executes concurrently
against the source database.

| Possible Values | Default in Development                                                                            | Default in Production                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| A valid number  | Same as [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency) | Same as [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency) |

## `CUBEJS_SCHEDULED_REFRESH_QUERIES_PER_APP_ID`

How many pre-aggregations the refresh worker will build in parallel for each
application id as determined by the [`context_to_app_id`][ref-context-to-app-id]
configuration option.

Note that this parameter doesn't override the overall refresh worker concurrency,
configured via the [`CUBEJS_REFRESH_WORKER_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_refresh_worker_concurrency) environment variable, and
it should be adjusted accordingly.

| Possible Values                      | Default in Development | Default in Production |
| ------------------------------------ | ---------------------- | --------------------- |
| A valid number of concurrent queries | 10                     | 10                    |

## `CUBEJS_CUBESTORE_HOST`

The hostname of the Cube Store deployment

| Possible Values  | Default in Development | Default in Production |
| ---------------- | ---------------------- | --------------------- |
| A valid hostname | `localhost`            | N/A                   |

## `CUBEJS_CUBESTORE_PORT`

The port of the Cube Store deployment.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid port number | `3030`                 | `3030`                |

## `CUBEJS_CUBESTORE_MAX_MESSAGE_SIZE`

The maximum size of a single message Cube will send to or accept from Cube
Store. A result above this size is reported as `Cube Store response size
exceeds the maximum message size`; see
[message size limits](/docs/pre-aggregations/cube-store-architecture#message-size-limits).
This is Cube's own limit and is independent of
[`CUBESTORE_TRANSPORT_MAX_MESSAGE_SIZE`](#cubestore_transport_max_message_size),
which Cube Store applies to what it receives.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A size in bytes | `104857600` (100 MB)   | `104857600` (100 MB)  |

## `CUBEJS_QUEUE_FAST_TRACK`

<Warning>
  The fast-track path is experimental and off by default. Its behavior may still change,
  and we don't recommend enabling it in production yet.
</Warning>

Enables the preview fast-track path for Cube Store query queues. When enabled,
Cube can atomically enqueue and retrieve a query when queue concurrency is
available, reducing queue coordination round trips. This requires Cube and Cube Store
1.7.26 or newer; against an older version Cube keeps using the regular path.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `CUBEJS_DATASOURCES`

A comma-separated list of data source names. Data sources defined here can be
used to [decorate `CUBEJS_DB_*`][ref-config-multiple-ds-decorating-env]
environment variables.

| Possible Values                   | Default in Development | Default in Production |
| --------------------------------- | ---------------------- | --------------------- |
| A comma-separated list of strings | N/A                    | N/A                   |

```dotenv theme={"dark"}
CUBEJS_DATASOURCES=default,datasource1
```

<Info>
  In Cube Cloud, this variable is **auto-maintained** when sources are managed
  from [**Settings → Data Sources**][ref-config-multiple-ds-cloud]. The page
  writes, updates, and removes it as you add or delete named sources — you
  only need to hand-edit it when configuring Cube Core or when overriding
  the UI from
  [**Settings → Environment Variables**](/admin#environment-variables).
</Info>

## `CUBEJS_DB_BQ_CREDENTIALS`

A Base64 encoded JSON key file for connecting to Google BigQuery.

| Possible Values                                                  | Default in Development | Default in Production |
| ---------------------------------------------------------------- | ---------------------- | --------------------- |
| A valid Google BigQuery JSON key file encoded as a Base64 string | N/A                    | N/A                   |

## `CUBEJS_DB_BQ_KEY_FILE`

The path to a JSON key file for connecting to Google BigQuery.

| Possible Values                       | Default in Development | Default in Production |
| ------------------------------------- | ---------------------- | --------------------- |
| A valid Google BigQuery JSON key file | N/A                    | N/A                   |

## `CUBEJS_DB_BQ_LOCATION`

The Google BigQuery dataset location to connect to. Required if used with
pre-aggregations outside of US. If not set then BQ driver will fail with
`Dataset was not found in location US` error.

| Possible Values                                                         | Default in Development | Default in Production |
| ----------------------------------------------------------------------- | ---------------------- | --------------------- |
| [A valid Google BigQuery regional location][bq-docs-regional-locations] | N/A                    | N/A                   |

## `CUBEJS_DB_BQ_PROJECT_ID`

The Google BigQuery project ID to connect to.

| Possible Values                    | Default in Development | Default in Production |
| ---------------------------------- | ---------------------- | --------------------- |
| A valid Google BigQuery Project ID | N/A                    | N/A                   |

## `CUBEJS_DB_CLICKHOUSE_READONLY`

Whether the ClickHouse user has read-only access or not.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | N/A                    | N/A                   |

## `CUBEJS_DB_CLICKHOUSE_COMPRESSION`

Whether the ClickHouse client has compression enabled or not.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `CUBEJS_DB_DATABRICKS_ACCEPT_POLICY`

To accept the license terms for the Databricks JDBC driver, this must be set to
`true`.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | N/A                    | N/A                   |

## `CUBEJS_DB_DATABRICKS_CATALOG`

The name of the [Databricks catalog][databricks-catalog] to connect to.

| Possible Values                 | Default in Development | Default in Production |
| ------------------------------- | ---------------------- | --------------------- |
| A valid Databricks catalog name | N/A                    | N/A                   |

[databricks-catalog]: https://docs.databricks.com/en/data-governance/unity-catalog/create-catalogs.html

## `CUBEJS_DB_DATABRICKS_OAUTH_CLIENT_ID`

The OAuth client ID for [service principal][ref-databricks-m2m-oauth] authentication in Databricks.

| Possible Values   | Default in Development | Default in Production |
| ----------------- | ---------------------- | --------------------- |
| A valid client ID | N/A                    | N/A                   |

## `CUBEJS_DB_DATABRICKS_OAUTH_CLIENT_SECRET`

The OAuth client secret for [service principal][ref-databricks-m2m-oauth] authentication in Databricks.

| Possible Values       | Default in Development | Default in Production |
| --------------------- | ---------------------- | --------------------- |
| A valid client secret | N/A                    | N/A                   |

## `CUBEJS_DB_DATABRICKS_TOKEN`

The [personal access token][databricks-docs-pat] used to authenticate the
Databricks connection.

| Possible Values                 | Default in Development | Default in Production |
| ------------------------------- | ---------------------- | --------------------- |
| A valid Databricks access token | N/A                    | N/A                   |

## `CUBEJS_DB_DATABRICKS_URL`

The URL for a JDBC connection.

| Possible Values  | Default in Development | Default in Production |
| ---------------- | ---------------------- | --------------------- |
| A valid JDBC URL | N/A                    | N/A                   |

## `CUBEJS_DB_DOMAIN`

A domain name within an MS SQL database to connect to.

| Possible Values                              | Default in Development | Default in Production |
| -------------------------------------------- | ---------------------- | --------------------- |
| A valid domain name within a MS SQL database | N/A                    | N/A                   |

## `CUBEJS_DB_DUCKDB_MEMORY_LIMIT`

The [maximum memory limit][duckdb-docs-config] for DuckDB. Equivalent to
`SET memory_limit=<MEMORY_LIMIT>`.

| Possible Values                  | Default in Development | Default in Production |
| -------------------------------- | ---------------------- | --------------------- |
| A valid MotherDuck service token | 75% of available RAM   | 75% of available RAM  |

[duckdb-docs-config]: https://duckdb.org/docs/sql/configuration.html

## `CUBEJS_DB_DUCKDB_SCHEMA`

The [default search schema][duckdb-docs-config] for DuckDB.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid schema name | `main`                 | `main`                |

## `CUBEJS_DB_DUCKDB_MOTHERDUCK_TOKEN`

The [service token][motherduck-docs-svc-token] to use for connections to
MotherDuck.

| Possible Values                  | Default in Development | Default in Production |
| -------------------------------- | ---------------------- | --------------------- |
| A valid MotherDuck service token | N/A                    | N/A                   |

## `CUBEJS_DB_DUCKDB_DATABASE_PATH`

The database filepath to use for connection to a local database.

| Possible Values                   | Default in Development | Default in Production |
| --------------------------------- | ---------------------- | --------------------- |
| A valid duckdb database file path | N/A                    | N/A                   |

## `CUBEJS_DB_DUCKDB_S3_ACCESS_KEY_ID`

The AWS Access Key ID to use for S3 connections.

| Possible Values           | Default in Development | Default in Production |
| ------------------------- | ---------------------- | --------------------- |
| A valid AWS Access Key ID | N/A                    | N/A                   |

## `CUBEJS_DB_DUCKDB_S3_SECRET_ACCESS_KEY`

The AWS Secret Access Key to use for S3 connections.

| Possible Values               | Default in Development | Default in Production |
| ----------------------------- | ---------------------- | --------------------- |
| A valid AWS Secret Access Key | N/A                    | N/A                   |

## `CUBEJS_DB_DUCKDB_S3_ENDPOINT`

The AWS endpoint to use for S3 connections.

| Possible Values                                   | Default in Development | Default in Production |
| ------------------------------------------------- | ---------------------- | --------------------- |
| [A valid AWS S3 endpoint][aws-docs-vpc-endpoints] | N/A                    | N/A                   |

[aws-docs-vpc-endpoints]: https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-s3.html

## `CUBEJS_DB_DUCKDB_S3_REGION`

The AWS region to use for S3 connections.

| Possible Values                        | Default in Development | Default in Production |
| -------------------------------------- | ---------------------- | --------------------- |
| [A valid AWS region][aws-docs-regions] | N/A                    | N/A                   |

## `CUBEJS_DB_DUCKDB_S3_USE_SSL`

Use SSL when connecting to S3.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| True or false   | N/A                    | N/A                   |

## `CUBEJS_DB_DUCKDB_S3_URL_STYLE`

The URL style to be used by S3.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| \[vhost/path]   | N/A                    | N/A                   |

## `CUBEJS_DB_DUCKDB_S3_SESSION_TOKEN`

The S3 session token.

| Possible Values          | Default in Development | Default in Production |
| ------------------------ | ---------------------- | --------------------- |
| A valid S3 session token | N/A                    | N/A                   |

## `CUBEJS_DB_DUCKDB_EXTENSIONS`

A comma-separated list of DuckDB extensions	to install and load.

| Possible Values                             | Default in Development | Default in Production |
| ------------------------------------------- | ---------------------- | --------------------- |
| A comma-separated list of DuckDB extensions | N/A                    | N/A                   |

## `CUBEJS_DB_DUCKDB_COMMUNITY_EXTENSIONS`

A comma-separated list of DuckDB community extensions	to install and load.

| Possible Values                                       | Default in Development | Default in Production |
| ----------------------------------------------------- | ---------------------- | --------------------- |
| A comma-separated list of DuckDB community extensions | N/A                    | N/A                   |

## `CUBEJS_DB_DUCKDB_S3_USE_CREDENTIAL_CHAIN`

A flag to use credentials chain for secrets for S3 connections.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `CUBEJS_DB_EXPORT_BUCKET`

The name of a bucket in cloud storage to store the database export snapshots.

<Info>
  When using multiple data sources, this environment variable can be [decorated
  with a data source][ref-config-multiple-ds-decorating-env].
</Info>

| Possible Values                                | Default in Development | Default in Production |
| ---------------------------------------------- | ---------------------- | --------------------- |
| A valid bucket in the configured cloud storage | N/A                    | N/A                   |

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET=exports-20210505

# Decorated with a data source named `datasource1`
CUBEJS_DS_DATASOURCE1_DB_EXPORT_BUCKET=exports-20210505
```

## `CUBEJS_DB_EXPORT_BUCKET_TYPE`

The cloud provider where the bucket is hosted.

<Info>
  When using multiple data sources, this environment variable can be [decorated
  with a data source][ref-config-multiple-ds-decorating-env].
</Info>

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `gcp`, `s3`     | N/A                    | N/A                   |

```dotenv theme={"dark"}
CUBEJS_DB_EXPORT_BUCKET_TYPE=gcp

# Decorated with a data source named `datasource1`
CUBEJS_DS_DATASOURCE1_DB_EXPORT_BUCKET_TYPE=gcp
```

## `CUBEJS_DB_EXPORT_BUCKET_AWS_KEY`

The AWS Access Key ID to use for the export bucket.

<Info>
  When using multiple data sources, this environment variable can be [decorated
  with a data source][ref-config-multiple-ds-decorating-env].
</Info>

| Possible Values           | Default in Development | Default in Production |
| ------------------------- | ---------------------- | --------------------- |
| A valid AWS Access Key ID | N/A                    | N/A                   |

## `CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET`

The AWS Secret Access Key to use for the export bucket.

<Info>
  When using multiple data sources, this environment variable can be [decorated
  with a data source][ref-config-multiple-ds-decorating-env].
</Info>

| Possible Values               | Default in Development | Default in Production |
| ----------------------------- | ---------------------- | --------------------- |
| A valid AWS Secret Access Key | N/A                    | N/A                   |

## `CUBEJS_DB_EXPORT_BUCKET_AWS_REGION`

The AWS region of the export bucket.

<Info>
  When using multiple data sources, this environment variable can be [decorated
  with a data source][ref-config-multiple-ds-decorating-env].
</Info>

| Possible Values                        | Default in Development | Default in Production |
| -------------------------------------- | ---------------------- | --------------------- |
| [A valid AWS region][aws-docs-regions] | N/A                    | N/A                   |

## `CUBEJS_DB_EXPORT_BUCKET_AZURE_KEY`

The Azure Access Key to use for the export bucket.

<Info>
  When using multiple data sources, this environment variable can be [decorated
  with a data source][ref-config-multiple-ds-decorating-env].
</Info>

| Possible Values          | Default in Development | Default in Production |
| ------------------------ | ---------------------- | --------------------- |
| A valid Azure Access Key | N/A                    | N/A                   |

## `CUBEJS_DB_EXPORT_BUCKET_AZURE_TENANT_ID`

The Azure tenant ID to use for the export bucket.

<Info>
  When using multiple data sources, this environment variable can be [decorated
  with a data source][ref-config-multiple-ds-decorating-env].
</Info>

| Possible Values         | Default in Development | Default in Production |
| ----------------------- | ---------------------- | --------------------- |
| A valid Azure Tenant ID | N/A                    | N/A                   |

## `CUBEJS_DB_EXPORT_BUCKET_AZURE_CLIENT_ID`

The Azure client ID to use for the export bucket.

<Info>
  When using multiple data sources, this environment variable can be [decorated
  with a data source][ref-config-multiple-ds-decorating-env].
</Info>

| Possible Values         | Default in Development | Default in Production |
| ----------------------- | ---------------------- | --------------------- |
| A valid Azure Client ID | N/A                    | N/A                   |

## `CUBEJS_DB_EXPORT_BUCKET_AZURE_CLIENT_SECRET`

The Azure client secret to use for the export bucket.

<Info>
  When using multiple data sources, this environment variable can be [decorated
  with a data source][ref-config-multiple-ds-decorating-env].
</Info>

| Possible Values             | Default in Development | Default in Production |
| --------------------------- | ---------------------- | --------------------- |
| A valid Azure Client Secret | N/A                    | N/A                   |

## `CUBEJS_DB_EXPORT_BUCKET_MOUNT_DIR`

The mount path to use for a [Databricks DBFS mount][databricks-docs-dbfs].

| Possible Values    | Default in Development | Default in Production |
| ------------------ | ---------------------- | --------------------- |
| A valid mount path | N/A                    | N/A                   |

## `CUBEJS_DB_EXPORT_BUCKET_REDSHIFT_ARN`

An ARN of an AWS IAM role with permission to write to the configured bucket (see
[`CUBEJS_DB_EXPORT_BUCKET`](/reference/configuration/environment-variables#cubejs_db_export_bucket)).

<Info>
  When using multiple data sources, this environment variable can be [decorated
  with a data source][ref-config-multiple-ds-decorating-env].
</Info>

| Possible Values                                                            | Default in Development | Default in Production |
| -------------------------------------------------------------------------- | ---------------------- | --------------------- |
| A valid ARN to an IAM Role associated with the target Redshift data source | N/A                    | N/A                   |

## `CUBEJS_DB_EXPORT_GCS_CREDENTIALS`

A Base64 encoded JSON key file for connecting to Google Cloud.

<Info>
  When using multiple data sources, this environment variable can be [decorated
  with a data source][ref-config-multiple-ds-decorating-env].
</Info>

| Possible Values                                               | Default in Development | Default in Production |
| ------------------------------------------------------------- | ---------------------- | --------------------- |
| A valid Google Cloud JSON key file encoded as a Base64 string | N/A                    | N/A                   |

## `CUBEJS_DB_EXPORT_INTEGRATION`

The name of the integration used in the database. Only required when using
Snowflake and Google Cloud Storage.

<Info>
  When using multiple data sources, this environment variable can be [decorated
  with a data source][ref-config-multiple-ds-decorating-env].
</Info>

| Possible Values                                                  | Default in Development | Default in Production |
| ---------------------------------------------------------------- | ---------------------- | --------------------- |
| A valid string matching the name of the integration in Snowflake | N/A                    | N/A                   |

## `CUBEJS_DB_HOST`

The host URL for a database.

| Possible Values           | Default in Development | Default in Production |
| ------------------------- | ---------------------- | --------------------- |
| A valid database host URL | N/A                    | N/A                   |

## `CUBEJS_DB_SOCKET_PATH`

The path to a Unix socket that is used to connect to a data source, e.g.,
[MySQL](/admin/connect-to-data/data-sources/mysql#connecting-via-a-unix-socket).

| Possible Values          | Default in Development | Default in Production |
| ------------------------ | ---------------------- | --------------------- |
| A valid path to a socket | N/A                    | N/A                   |

## `CUBEJS_DB_MAX_POOL`

The maximum number of concurrent database connections to pool.

| Possible Values | Default in Development                      | Default in Production                       |
| --------------- | ------------------------------------------- | ------------------------------------------- |
| A valid number  | [See database-specific page][ref-config-db] | [See database-specific page][ref-config-db] |

## `CUBEJS_DB_NAME`

The name of the database to connect to.

| Possible Values       | Default in Development | Default in Production |
| --------------------- | ---------------------- | --------------------- |
| A valid database name | N/A                    | N/A                   |

## `CUBEJS_DB_PASS`

The password used to connect to the database.

| Possible Values           | Default in Development | Default in Production |
| ------------------------- | ---------------------- | --------------------- |
| A valid database password | N/A                    | N/A                   |

## `CUBEJS_DB_PORT`

The port for the database connection.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid port number | N/A                    | N/A                   |

## `CUBEJS_DB_PRECISE_DECIMAL_IN_CUBESTORE`

If `true`, decimal columns maintain their precision and scale specifications (e.g.,
`decimal(10, 2)`) rather than being converted to a generic decimal type when data is
exported from a data source to Cube Store.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `CUBEJS_DB_PRESTO_CATALOG`

The catalog within Presto/Trino to connect to.

| Possible Values                                     | Default in Development | Default in Production |
| --------------------------------------------------- | ---------------------- | --------------------- |
| A valid catalog name within a Presto/Trino database | N/A                    | N/A                   |

## `CUBEJS_DB_PRESTO_AUTH_TOKEN`

The authentication token to use when connecting to Presto/Trino. It will be sent in the `Authorization` header.

| Possible Values              | Default in Development | Default in Production |
| ---------------------------- | ---------------------- | --------------------- |
| A valid authentication token | N/A                    | N/A                   |

## `CUBEJS_DB_QUERY_TIMEOUT`

The timeout value for any queries made to the database by Cube.

| Possible Values                          | Default in Development | Default in Production |
| ---------------------------------------- | ---------------------- | --------------------- |
| A number in seconds or a duration string | `10m`                  | `10m`                 |

<Info>
  There's a hard limit of 20 minutes for queries that ingest data into Cube Store
  when pre-aggregations are built. If you bump into this limit, consider using
  an export bucket and splitting pre-aggregations into partitions.
</Info>

## `CUBEJS_DB_FETCH_COLUMNS_BY_ORDINAL_POSITION`

Force fetching of columns by ordinal positions. Certain data-providers (e.g., Redshift) do not guarantee columns in the
same order on each request (e.g., `SELECT * FROM foo`). This flag ensures that columns will be fetched in proper order
for pre-aggregation generation.

| Possible Values                                    | Default in Development | Default in Production |
| -------------------------------------------------- | ---------------------- | --------------------- |
| Whether to force fetch columns in ordinal position | `true`                 | `true`                |

## `CUBEJS_DB_HIVE_TYPE`

The type of Hive server to connect to.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `HIVE`, `CDH`   | `HIVE`                 | `HIVE`                |

## `CUBEJS_DB_HIVE_VER`

The version of the Hive server to connect to.

| Possible Values      | Default in Development | Default in Production |
| -------------------- | ---------------------- | --------------------- |
| A valid Hive version | `2.1.1`                | `2.1.1`               |

## `CUBEJS_DB_HIVE_THRIFT_VER`

The version of the Thrift protocol used to connect to Hive.

| Possible Values        | Default in Development | Default in Production |
| ---------------------- | ---------------------- | --------------------- |
| A valid Thrift version | `0.9.3`                | `0.9.3`               |

## `CUBEJS_DB_HIVE_CDH_VER`

The Cloudera Distribution Hadoop (CDH) version, used when `CUBEJS_DB_HIVE_TYPE`
is set to `CDH`.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid CDH version | N/A                    | N/A                   |

## `CUBEJS_DB_KAFKA_HOST`

Kafka broker host(s) for [Kafka streams mode](/admin/connect-to-data/data-sources/ksqldb#kafka-streams-mode).
Multiple brokers can be comma-separated.

| Possible Values          | Default in Development | Default in Production |
| ------------------------ | ---------------------- | --------------------- |
| A valid Kafka broker URL | N/A                    | N/A                   |

## `CUBEJS_DB_KAFKA_USER`

Username for Kafka broker authentication (SASL PLAIN).

| Possible Values        | Default in Development | Default in Production |
| ---------------------- | ---------------------- | --------------------- |
| A valid Kafka username | N/A                    | N/A                   |

## `CUBEJS_DB_KAFKA_PASS`

Password for Kafka broker authentication (SASL PLAIN).

| Possible Values        | Default in Development | Default in Production |
| ---------------------- | ---------------------- | --------------------- |
| A valid Kafka password | N/A                    | N/A                   |

## `CUBEJS_DB_KAFKA_USE_SSL`

If `true`, enables SASL\_SSL for the Kafka connection.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `CUBEJS_DB_MATERIALIZE_CLUSTER`

The cluster name to use when connecting to [Materialize](/admin/connect-to-data/data-sources/materialize).

| Possible Values                  | Default in Development | Default in Production |
| -------------------------------- | ---------------------- | --------------------- |
| A valid Materialize cluster name | N/A                    | N/A                   |

## `CUBEJS_DB_MYSQL_USE_NAMED_TIMEZONES`

This flag controls how time zones conversion is done in the generated SQL for MySQL:

* If it is set to `true`, time zone names are used. In this case, your MySQL server needs
  to be [configured][mysql-server-tz-support] properly.
* If it is set to `false`, numeric offsets are used instead.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `CUBEJS_DB_MSSQL_USE_NAMED_TIMEZONES`

This flag controls how time zone conversion is done in the generated SQL for Microsoft
SQL Server:

* If it is set to `true`, time zone names are used, with DST-aware conversion via
  `AT TIME ZONE`.
* If it is set to `false`, numeric offsets are used instead.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER`

The Redshift cluster identifier. Required for IAM authentication.

| Possible Values            | Default in Development | Default in Production |
| -------------------------- | ---------------------- | --------------------- |
| A valid cluster identifier | N/A                    | N/A                   |

## `CUBEJS_DB_REDSHIFT_AWS_REGION`

The AWS region of the Redshift cluster. Required for IAM authentication.

| Possible Values    | Default in Development | Default in Production |
| ------------------ | ---------------------- | --------------------- |
| A valid AWS region | N/A                    | N/A                   |

## `CUBEJS_DB_REDSHIFT_ASSUME_ROLE_ARN`

The ARN of the IAM role to assume for cross-account access.

| Possible Values      | Default in Development | Default in Production |
| -------------------- | ---------------------- | --------------------- |
| A valid IAM role ARN | N/A                    | N/A                   |

## `CUBEJS_DB_REDSHIFT_ASSUME_ROLE_EXTERNAL_ID`

The external ID for the assumed role's trust policy.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A string        | N/A                    | N/A                   |

## `CUBEJS_DB_SNOWFLAKE_ACCOUNT`

The Snowflake account identifier to use when connecting to the database.

| Possible Values                                           | Default in Development | Default in Production |
| --------------------------------------------------------- | ---------------------- | --------------------- |
| [A valid Snowflake account ID][snowflake-docs-account-id] | N/A                    | N/A                   |

## `CUBEJS_DB_SNOWFLAKE_AUTHENTICATOR`

The type of authenticator to use with Snowflake. Use `SNOWFLAKE` with
username/password, or `SNOWFLAKE_JWT` with key pairs.

| Possible Values              | Default in Development | Default in Production |
| ---------------------------- | ---------------------- | --------------------- |
| `SNOWFLAKE`, `SNOWFLAKE_JWT` | `SNOWFLAKE`            | `SNOWFLAKE`           |

## `CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN`

The OAuth token to use with Snowflake.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid OAuth token | N/A                    | N/A                   |

## `CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH`

The path to the file containing the OAuth token for Snowflake.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid OAuth token | N/A                    | N/A                   |

## `CUBEJS_DB_SNOWFLAKE_CLIENT_SESSION_KEEP_ALIVE`

If `true`, [keep the Snowflake connection alive
indefinitely][snowflake-docs-connection-options].

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `true`                 | `true`                |

## `CUBEJS_DB_SNOWFLAKE_PRIVATE_KEY`

The content of the private RSA key (encrypted or not).

| Possible Values                | Default in Development | Default in Production |
| ------------------------------ | ---------------------- | --------------------- |
| Content of the private RSA key | N/A                    | N/A                   |

## `CUBEJS_DB_SNOWFLAKE_PRIVATE_KEY_PASS`

The password for the private RSA key. Only required for encrypted keys.

| Possible Values                                    | Default in Development | Default in Production |
| -------------------------------------------------- | ---------------------- | --------------------- |
| A valid password for the encrypted private RSA key | N/A                    | N/A                   |

## `CUBEJS_DB_SNOWFLAKE_PRIVATE_KEY_PATH`

The path to the private RSA key folder.

| Possible Values                     | Default in Development | Default in Production |
| ----------------------------------- | ---------------------- | --------------------- |
| A valid path to the private RSA key | N/A                    | N/A                   |

## `CUBEJS_DB_SNOWFLAKE_REGION`

The Snowflake region to use when connecting to the database.

| Possible Values                                    | Default in Development | Default in Production |
| -------------------------------------------------- | ---------------------- | --------------------- |
| [A valid Snowflake region][snowflake-docs-regions] | N/A                    | N/A                   |

## `CUBEJS_DB_SNOWFLAKE_ROLE`

The Snowflake role to use when connecting to the database.

| Possible Values                                               | Default in Development | Default in Production |
| ------------------------------------------------------------- | ---------------------- | --------------------- |
| [A valid Snowflake role][snowflake-docs-roles] in the account | N/A                    | N/A                   |

## `CUBEJS_DB_SNOWFLAKE_WAREHOUSE`

The Snowflake warehouse to use when connecting to the database.

| Possible Values                                                        | Default in Development | Default in Production |
| ---------------------------------------------------------------------- | ---------------------- | --------------------- |
| [A valid Snowflake warehouse][snowflake-docs-warehouse] in the account | N/A                    | N/A                   |

## `CUBEJS_DB_SNOWFLAKE_HOST`

Host address to which the driver should connect.

| Possible Values  | Default in Development | Default in Production |
| ---------------- | ---------------------- | --------------------- |
| A valid hostname | N/A                    | N/A                   |

## `CUBEJS_DB_SNOWFLAKE_QUOTED_IDENTIFIERS_IGNORE_CASE`

Whether or not [quoted identifiers should be case insensitive](https://docs.snowflake.com/en/sql-reference/identifiers-syntax#double-quoted-identifiers).

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `CUBEJS_DB_PINOT_NULL_HANDLING`

The Startree/Pinot null value support. If `true`, enables null handling.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `CUBEJS_DB_PINOT_AUTH_TOKEN`

The authentication token for StarTree to be passed as HTTP headers.

| Possible Values                     | Default in Development | Default in Production |
| ----------------------------------- | ---------------------- | --------------------- |
| A valid string containing the token | N/A                    | N/A                   |

## `CUBEJS_DB_SSL`

If `true`, enables SSL encryption for database connections from Cube.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | N/A                    | N/A                   |

## `CUBEJS_DB_SSL_CA`

The contents of a CA bundle in PEM format, or a path to one. For more
information, check the `options.ca` property for TLS Secure Contexts [in the
Node.js documentation][nodejs-docs-tls-options].

| Possible Values                    | Default in Development | Default in Production |
| ---------------------------------- | ---------------------- | --------------------- |
| A valid CA bundle or a path to one | N/A                    | N/A                   |

## `CUBEJS_DB_SSL_CERT`

The contents of an SSL certificate in PEM format, or a path to one. For more
information, check the `options.cert` property for TLS Secure Contexts [in the
Node.js documentation][nodejs-docs-tls-options].

| Possible Values                          | Default in Development | Default in Production |
| ---------------------------------------- | ---------------------- | --------------------- |
| A valid SSL certificate or a path to one | N/A                    | N/A                   |

## `CUBEJS_DB_SSL_KEY`

The contents of a private key in PEM format, or a path to one. For more
information, check the `options.key` property for TLS Secure Contexts [in the
Node.js documentation][nodejs-docs-tls-options].

| Possible Values                          | Default in Development | Default in Production |
| ---------------------------------------- | ---------------------- | --------------------- |
| A valid SSL private key or a path to one | N/A                    | N/A                   |

## `CUBEJS_DB_SSL_SERVERNAME`

The server name to use for SNI (Server Name Indication) when establishing the
TLS connection. For more information, check the `options.servername` property
for TLS Secure Contexts [in the Node.js documentation][nodejs-docs-tls-options].

| Possible Values   | Default in Development | Default in Production |
| ----------------- | ---------------------- | --------------------- |
| A valid host name | N/A                    | N/A                   |

## `CUBEJS_DB_TYPE`

A database from the list of [supported databases][ref-config-db].

| Possible Values                                       | Default in Development | Default in Production |
| ----------------------------------------------------- | ---------------------- | --------------------- |
| [Any valid database supported by Cube][ref-config-db] | N/A                    | N/A                   |

## `CUBEJS_DB_URL`

The URL for a database.

| Possible Values      | Default in Development | Default in Production |
| -------------------- | ---------------------- | --------------------- |
| A valid database URL | N/A                    | N/A                   |

## `CUBEJS_DB_USER`

The username used to connect to the database.

| Possible Values           | Default in Development | Default in Production |
| ------------------------- | ---------------------- | --------------------- |
| A valid database username | N/A                    | N/A                   |

## `CUBEJS_DB_QUERY_DEFAULT_LIMIT`

The default [row limit][ref-row-limit] in the result set if it's not explicitly
specified in an API query.

| Possible Values           | Default in Development | Default in Production |
| ------------------------- | ---------------------- | --------------------- |
| A positive integer number | `10000`                | `10000`               |

## `CUBEJS_DB_QUERY_LIMIT`

The maximum [row limit][ref-row-limit] in the result set. An explicit limit in a
query cannot exceed this value, except for [SQL API][ref-sql-api] queries when
[streaming mode][ref-sql-api-streaming] is enabled. SQL API queries that are not
streamed can be capped separately, at a lower value, with
[`CUBESQL_NON_STREAMING_QUERY_MAX_ROW_LIMIT`](#cubesql_non_streaming_query_max_row_limit).

| Possible Values           | Default in Development | Default in Production |
| ------------------------- | ---------------------- | --------------------- |
| A positive integer number | `50000`                | `50000`               |

<Warning>
  Increasing the maximum row limit may cause out-of-memory (OOM) crashes and make
  Cube susceptible to denial-of-service (DoS) attacks if it's exposed to
  untrusted environments.
</Warning>

## `CUBEJS_DEFAULT_TIMEZONE`

The default [time zone][ref-time-zone] for queries.

| Possible Values        | Default in Development | Default in Production |
| ---------------------- | ---------------------- | --------------------- |
| A valid time zone name | `UTC`                  | `UTC`                 |

You can set the time zone name in the [TZ Database Name][link-tzdb] format, e.g.,
`America/Los_Angeles`.

<Warning>
  An invalid value fails at server startup. Only TZ Database names are accepted — fixed
  UTC offsets such as `+05:00` are rejected.
</Warning>

This is the fallback. When [user time zones](/admin/time-zones) are enabled for the
account, a resolved account, personal, dashboard, or embed zone is sent with the query and
takes precedence over this value.

## `CUBEJS_DEFAULT_API_SCOPES`

[API scopes][ref-rest-scopes] used to allow or disallow access to REST (JSON) API
endpoints.

| Possible Values                                                                | Default in Development  | Default in Production   |
| ------------------------------------------------------------------------------ | ----------------------- | ----------------------- |
| A comma-delimited string with any combination of [API scopes][ref-rest-scopes] | `meta,data,graphql,sql` | `meta,data,graphql,sql` |

See also the [`context_to_api_scopes` configuration
option](/reference/configuration/config#context_to_api_scopes).

## `CUBEJS_DEV_MODE`

If `true`, enables [development mode](/docs/data-modeling/dev-mode).

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `true`                 | `false`               |

<Warning>
  **Development mode is an authentication bypass.** Cube is in development mode when
  `CUBEJS_DEV_MODE=true`, and also whenever `NODE_ENV` is not `production`. When Cube
  is started through the `cubejs` CLI — which is what the official Docker images run —
  setting `CUBEJS_DEV_MODE=true` additionally forces `NODE_ENV=development`, which
  switches off JWT verification on the
  [REST (JSON)](/reference/core-data-apis/rest-api) and
  [GraphQL](/reference/core-data-apis/graphql-api) APIs: they then accept requests with
  no token at all.

  Development mode also mounts [Playground](/docs/explore-analyze/playground) and its
  supporting endpoints with no authentication whatsoever. Anyone who can reach the
  instance is handed a ready-to-use API token, and can mint further ones carrying any
  security context signed with your API secret — and so query every data API as any user,
  bypassing [member-level access
  control](/docs/data-modeling/access-control/member-level-security) and [row-level
  security](/docs/data-modeling/access-control/row-level-security). The same endpoints
  read your data model files and the table schema of every connected data source, and
  overwrite your data model and your `.env`. With `CUBEJS_DEV_MODE=true` and no
  [`CUBEJS_SQL_PASSWORD`](/reference/configuration/environment-variables#cubejs_sql_password)
  set, the SQL API accepts any credentials as well, allowing arbitrary SQL against
  connected data sources.

  This is intentional. Development mode is designed to run on a developer's local
  machine for ease of use and debugging. Never run it where anyone else can reach it,
  never expose it to the internet, and never use it in production. Using development
  mode in the Cube cloud platform is highly discouraged — it bypasses the platform's
  security model.

  To keep it off: `cubejs server` and the official Docker images already set
  `NODE_ENV=production`, so leaving `CUBEJS_DEV_MODE` unset — its default — is enough
  there. If you embed `@cubejs-backend/server-core` directly rather than starting Cube
  through the `cubejs` CLI, set `NODE_ENV=production` yourself, since an unset `NODE_ENV`
  puts the instance in development mode whatever the flag says.
</Warning>

## `CUBEJS_DROP_PRE_AGG_WITHOUT_TOUCH`

If `true`, it enables dropping pre-aggregations that Refresh Worker doesn't
touch within [`CUBEJS_TOUCH_PRE_AGG_TIMEOUT`](/reference/configuration/environment-variables#cubejs_touch_pre_agg_timeout).
Pre-aggregations are touched whenever they are rebuilt or a Refresh Worker
checks its freshness. The first drop will be initiated when the Refresh Worker
is able to check freshness for every `scheduledRefresh: true` pre-aggregation.
If you have multiple Refresh Workers with different data model versions sharing
the same Cube Store cluster, then touches from both refresh workers are
respected.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `true`                 | `true`                |

## `CUBEJS_FIREBOLT_ACCOUNT`

The [Firebolt account name][firebolt-docs-account-name].

| Possible Values                                             | Default in Development | Default in Production |
| ----------------------------------------------------------- | ---------------------- | --------------------- |
| A valid [Firebolt account name][firebolt-docs-account-name] | N/A                    | N/A                   |

## `CUBEJS_FIREBOLT_API_ENDPOINT`

The Firebolt API endpoint. Used for authentication.

| Possible Values                                                         | Default in Development | Default in Production |
| ----------------------------------------------------------------------- | ---------------------- | --------------------- |
| `api.dev.firebolt.io`, `api.staging.firebolt.io`, `api.app.firebolt.io` | N/A                    | N/A                   |

## `CUBEJS_FIREBOLT_ENGINE_NAME`

The [name of the Firebolt engine][firebolt-docs-engine-name] to connect to.

| Possible Values                                           | Default in Development | Default in Production |
| --------------------------------------------------------- | ---------------------- | --------------------- |
| A valid [Firebolt engine name][firebolt-docs-engine-name] | N/A                    | N/A                   |

## `CUBEJS_GH_API_TOKEN`

A [GitHub Personal Access Token][gh-docs-pat] to avoid API rate limiting when
downloading Cube Store.

| Possible Values    | Default in Development | Default in Production |
| ------------------ | ---------------------- | --------------------- |
| A valid GitHub PAT | `false`                | `false`               |

## `CUBEJS_JWK_URL`

Enables [JSON Web Key (JWK)][ietf-jwk-ref]-based authentication in Cube.

| Possible Values                   | Default in Development | Default in Production |
| --------------------------------- | ---------------------- | --------------------- |
| A valid URL to a JSON Web Key Set | N/A                    | N/A                   |

It can be also set as `jwkUrl` in the [`jwt` configuration
option](/reference/configuration/config#jwt).

## `CUBEJS_JWT_ALGS`

[Any supported algorithm for decoding JWTs][gh-jsonwebtoken-algs].

| Possible Values  | Default in Development | Default in Production |
| ---------------- | ---------------------- | --------------------- |
| `HS256`, `RS256` | N/A                    | N/A                   |

It can be also set as `algorithms` in the [`jwt` configuration
option](/reference/configuration/config#jwt).

## `CUBEJS_JWT_AUDIENCE`

An audience value which will be used to enforce the [`aud` claim from inbound
JWTs][ietf-jwt-ref-aud].

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid `aud` claim | N/A                    | N/A                   |

It can be also set as `audience` in the [`jwt` configuration
option](/reference/configuration/config#jwt).

## `CUBEJS_JWT_CLAIMS_NAMESPACE`

A namespace within the decoded JWT under which any custom claims can be found.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid string  | N/A                    | N/A                   |

It can be also set as `claimsNamespace` in the [`jwt` configuration
option](/reference/configuration/config#jwt).

## `CUBEJS_JWT_ISSUER`

An issuer value which will be used to enforce the [`iss` claim from inbound
JWTs][ietf-jwt-ref-iss].

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid `iss` claim | N/A                    | N/A                   |

It can be also set as `issuer` in the [`jwt` configuration
option](/reference/configuration/config#jwt).

## `CUBEJS_JWT_KEY`

The secret key used to sign and verify JWTs. Similar to
[`CUBEJS_API_SECRET`](/reference/configuration/environment-variables#cubejs_api_secret).

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid string  | N/A                    | N/A                   |

It can be also set as `key` in the [`jwt` configuration
option](/reference/configuration/config#jwt).

## `CUBEJS_JWT_SUBJECT`

A subject value which will be used to enforce the [`sub` claim from inbound
JWTs][ietf-jwt-ref-sub].

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid `sub` claim | N/A                    | N/A                   |

It can be also set as `subject` in the [`jwt` configuration
option](/reference/configuration/config#jwt).

## `CUBEJS_LOG_LEVEL`

The logging level for Cube.

| Possible Values                  | Default in Development | Default in Production |
| -------------------------------- | ---------------------- | --------------------- |
| `error`, `info`, `trace`, `warn` | `warn`                 | `warn`                |

<Note>
  In production, Cube emits logs as structured JSON — one JSON object per line,
  each including a `level` field with the log level. In development, logs are
  emitted as human-readable text.
</Note>

See also `CUBESTORE_LOG_LEVEL`.
See also the [`logger` configuration option](/reference/configuration/config#logger).

## `CUBEJS_MAX_PARTITIONS_PER_CUBE`

The maximum number of partitions each pre-aggregation in a cube can use.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid number  | `10000`                | `10000`               |

## `CUBEJS_PG_SQL_PORT`

The port used by the [SQL API][ref-sql-api] to listen to Postgres-compatible
connections on.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid port number | N/A                    | N/A                   |

## `CUBEJS_PRE_AGGREGATIONS_BUILDER`

If `true`, this instance of Cube will build pre-aggregations, even if it is an
API instance.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `true`                 | `false`               |

<Info>
  If Cube is configured to act as a refresh worker instance using [`CUBEJS_REFRESH_WORKER`](/reference/configuration/environment-variables#cubejs_refresh_worker),
  then [`CUBEJS_PRE_AGGREGATIONS_BUILDER`](/reference/configuration/environment-variables#cubejs_pre_aggregations_builder) will be `true`.
</Info>

## `CUBEJS_PRE_AGGREGATIONS_SCHEMA`

The [database schema name](/reference/configuration/config#pre_aggregations_schema)
to use for storing pre-aggregations.

| Possible Values | Default in Development | Default in Production   |
| --------------- | ---------------------- | ----------------------- |
| A valid string  | `dev_pre_aggregations` | `prod_pre_aggregations` |

It can be also set using the [`pre_aggregations_schema` configuration
option](/reference/configuration/config#pre_aggregations_schema).

<Info>
  In Cube Cloud, all [environments][ref-environments] share the same pre-aggregations schema name by default.
  This allows reusing pre-aggregations across environments, saving both time and cost.
</Info>

## `CUBEJS_PRE_AGGREGATIONS_DB_*`

Connection variables for a dedicated data source used to build and store the default
data source's pre-aggregations, instead of its own connection. They mirror the regular
`CUBEJS_DB_*` connection variables — for example `CUBEJS_PRE_AGGREGATIONS_DB_HOST`,
`CUBEJS_PRE_AGGREGATIONS_DB_PORT`, `CUBEJS_PRE_AGGREGATIONS_DB_USER`,
`CUBEJS_PRE_AGGREGATIONS_DB_PASS`, and `CUBEJS_PRE_AGGREGATIONS_DB_SSL`. For a [named data source][ref-config-multiple-ds-decorating-env],
use the decorated form `CUBEJS_DS_<NAME>_PRE_AGGREGATIONS_DB_*`.

Driver-specific connection variables take the same segment, so the dedicated connection
is not limited to the `_DB_*` family — for example `CUBEJS_PRE_AGGREGATIONS_JDBC_URL`,
`CUBEJS_PRE_AGGREGATIONS_AWS_REGION`, and `CUBEJS_PRE_AGGREGATIONS_FIREBOLT_ENGINE_NAME`.
In the decorated form for a named data source, the `DB_`, `JDBC_`, `AWS_`, `DATABASE`,
and `FIREBOLT_` variable families are supported.

| Possible Values                                  | Default in Development | Default in Production |
| ------------------------------------------------ | ---------------------- | --------------------- |
| Same as the corresponding `CUBEJS_DB_*` variable | Not set                | Not set               |

Setting any one of these variables switches the data source's pre-aggregations onto the
dedicated connection. Configure it in full: an unset variable falls back to the driver's
default rather than to its `CUBEJS_DB_*` counterpart. `CUBEJS_PRE_AGGREGATIONS_DB_TYPE` is
ignored — the dedicated connection always uses the data source's driver. A custom
[`driver_factory`][ref-config-driver-factory] takes precedence over these variables.

See [pre-aggregation data source][ref-preagg-data-source] for details and examples.

## `CUBEJS_PRE_AGGREGATIONS_ALLOW_NON_STRICT_DATE_RANGE_MATCH`

If `true`, allows non-strict date range matching for pre-aggregations by default.
This can be overridden for individual pre-aggregations using the
[`allow_non_strict_date_range_match`][ref-schema-ref-preagg-allownonstrict] parameter.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `true`                 | `true`                |

## `CUBEJS_PRE_AGGREGATIONS_BACKOFF_MAX_TIME`

The maximum time, in seconds, for exponential backoff for retries when pre-aggregation
builds fail. When a pre-aggregation refresh fails, retries will be executed with
exponentially increasing delays, but the delay will not exceed the value specified by
this variable.

| Possible Values           | Default in Development | Default in Production |
| ------------------------- | ---------------------- | --------------------- |
| A valid number in seconds | `600`                  | `600`                 |

## `CUBEJS_REFRESH_KEY_LOCAL_TIME`

To check an `every`-based [`refresh_key`](/reference/data-modeling/cube#refresh_key), Cube
asks the database what time it is. If `true`, it uses its own clock instead and those
queries stop entirely, including the ones scheduled refresh issues to warm them.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

Cube already caches each result for a fraction of the interval, so this is not one query
saved per request — it is one per refresh key per renewal window, multiplied by every cube,
tenant, and timezone in the deployment.

Refresh keys written with `sql` or marked
[`incremental`](/reference/data-modeling/pre-aggregations#incremental) keep querying the
database, since their values depend on your data and not just on the time. So do all
refresh keys if you have set
[`queryCacheOptions.refreshKeyRenewalThreshold`][ref-config-query-cache-options], which
works by caching the query result.

<Warning>
  Cube now trusts each machine's clock, so they all have to agree. Set this variable to the
  same value on **every** API instance and refresh worker and keep them synchronized with
  NTP. Instances on opposite sides of an interval boundary compute different refresh keys,
  which can build the same pre-aggregation twice.
</Warning>

## `CUBEJS_REFRESH_WORKER`

If `true`, this instance of Cube will **only** refresh pre-aggregations.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `CUBEJS_ROLLUP_ONLY`

If `true`, the API instance of Cube will **only** fulfill queries from
pre-aggregations. See [rollup-only
mode](/docs/pre-aggregations/using-pre-aggregations#rollup-only-mode) for details.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

It can be also set using the [`orchestrator_options.rollupOnlyMode` configuration
option](/reference/configuration/config#orchestrator_options).

## `CUBEJS_SCHEDULED_REFRESH_TIMEZONES`

A comma-separated [list of timezones to schedule refreshes
for][ref-config-sched-refresh-timer].

| Possible Values                                           | Default in Development | Default in Production |
| --------------------------------------------------------- | ---------------------- | --------------------- |
| [A valid timezone from the tz database][wiki-tz-database] | N/A                    | N/A                   |

<Warning>
  An invalid value fails at server startup. Only TZ Database names are accepted — fixed
  UTC offsets such as `+05:00` are rejected.
</Warning>

It can be also set using the [`scheduled_refresh_time_zones` configuration
option](/reference/configuration/config#scheduled_refresh_time_zones).

## `CUBEJS_SCHEMA_PATH`

The path where Cube loads data models from.

| Possible Values                          | Default in Development | Default in Production |
| ---------------------------------------- | ---------------------- | --------------------- |
| A valid path containing Cube data models | `model`                | `model`               |

<Info>
  Until v0.35, the default value was `schema`.
</Info>

It can be also set using the [`schema_path` configuration
option](/reference/configuration/config#schema_path).

## `CUBEJS_SERVER_HEADERS_TIMEOUT`

The number of milliseconds to limit the amount of time the parser will wait
to receive the complete HTTP headers.
If the timeout expires, the server responds with status 408 without
forwarding the request to the request listener and then closes the connection.

| Possible Values                           | Default in Development   | Default in Production    |
| ----------------------------------------- | ------------------------ | ------------------------ |
| A valid number or string representing one | NodeJS's version default | NodeJS's version default |

## `CUBEJS_SERVER_KEEP_ALIVE_TIMEOUT`

The number of milliseconds of inactivity a server needs to wait for additional incoming data,
after it has finished writing the last response, before a socket will be destroyed.

| Possible Values                           | Default in Development   | Default in Production    |
| ----------------------------------------- | ------------------------ | ------------------------ |
| A valid number or string representing one | NodeJS's version default | NodeJS's version default |

## `CUBEJS_MAX_REQUEST_SIZE`

The maximum allowed size for incoming requests. Applies to both HTTP body parser
and WebSocket message payload limits. Must be between `100kb` and `64mb`.

| Possible Values                                  | Default in Development | Default in Production |
| ------------------------------------------------ | ---------------------- | --------------------- |
| A size string between 100kb and 64mb (e.g., 1mb) | `50mb`                 | `50mb`                |

## `CUBEJS_SQL_USER`

A username required to access the [SQL API][ref-sql-api].

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid string  | N/A                    | N/A                   |

See also the [`check_sql_auth` configuration
option](/reference/configuration/config#check_sql_auth).

## `CUBEJS_SQL_PASSWORD`

A password required to access the [SQL API][ref-sql-api].

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid string  | N/A                    | N/A                   |

See also the [`check_sql_auth` configuration
option](/reference/configuration/config#check_sql_auth).

## `CUBEJS_SQL_SUPER_USER`

A name of specific user who will be allowed to change the user during the SQL API
session.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid string  | N/A                    | N/A                   |

See also the [`can_switch_sql_user` configuration
option](/reference/configuration/config#can_switch_sql_user).

## `CUBEJS_ALLOW_UNGROUPED_WITHOUT_PRIMARY_KEY`

If `true`, disables the primary key inclusion check for
[ungrouped queries](/reference/core-data-apis/queries#ungrouped-query).

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

It can be also set using the [`allow_ungrouped_without_primary_key` configuration
option](/reference/configuration/config#allow_ungrouped_without_primary_key).

<Info>
  When query push-down in the SQL API is enabled via the `CUBESQL_SQL_PUSH_DOWN`
  environment variable, this option is enabled as well for the best user experience.
</Info>

## `CUBESQL_SQL_PUSH_DOWN`

If `true`, enables query pushdown in the [SQL API][ref-sql-api].

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `true`                 | `true`                |

## `CUBESQL_STREAM_MODE`

If `true`, enables the [streaming mode][ref-sql-api-streaming] in the [SQL API][ref-sql-api].
When enabled, SQL API queries with no `LIMIT` clause, or with one above the maximum row
limit set by
[`CUBESQL_NON_STREAMING_QUERY_MAX_ROW_LIMIT`](#cubesql_non_streaming_query_max_row_limit),
are streamed instead and aren't capped by it.
Queries with a `LIMIT` at or below that limit are not streamed.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `CUBESQL_FAIL_ON_LIMITLESS_POST_PROCESSING`

If `true`, the [SQL API][ref-sql-api] rejects a query when part of it has to run outside
the data source over a Cube query with no `LIMIT` clause, or with one above the maximum
row limit set by
[`CUBESQL_NON_STREAMING_QUERY_MAX_ROW_LIMIT`](#cubesql_non_streaming_query_max_row_limit).

Such a query is capped at that limit, without any ordering, and a `LIMIT` above it is
clamped back down to it. Sorting, filtering, or joining that capped result outside the
data source treats an arbitrary slice of the rows as if it were the whole population, so
the answer is wrong rather than merely short. The SQL API pushes these queries down to
the data source whenever it can; this option controls what happens when it cannot. Leave
it `false` to keep returning the truncated result, or set it to `true` to fail with an
error instead.

Queries that are streamed (see [`CUBESQL_STREAM_MODE`](#cubesql_stream_mode)) are never
capped, so this option has no effect on them.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `CUBESQL_CUBE_SCAN_MAX_BATCH_ROWS`

Specifies the maximum number of rows in a single record batch produced when the
[SQL API][ref-sql-api] reads data from a cube. Larger result sets are split into
several batches, which lets downstream consumers process them incrementally
instead of materializing the whole result set at once. In particular, the
[`/v1/cubesql`][ref-ref-cubesql] endpoint emits one newline-delimited JSON chunk
per batch.

Set to `0` to disable splitting.

| Possible Values               | Default in Development | Default in Production |
| ----------------------------- | ---------------------- | --------------------- |
| A non-negative integer number | `65536`                | `65536`               |

## `CUBESQL_NON_STREAMING_QUERY_MAX_ROW_LIMIT`

The maximum [row limit][ref-row-limit] for [SQL API][ref-sql-api] queries that are
not streamed. A larger `LIMIT` is reduced to this value, unless
[streaming mode][ref-sql-api-streaming] is enabled, in which case the query is
streamed instead.

| Possible Values           | Default in Development                                      | Default in Production                                       |
| ------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------- |
| A positive integer number | [`CUBEJS_DB_QUERY_LIMIT`](#cubejs_db_query_limit) (`50000`) | [`CUBEJS_DB_QUERY_LIMIT`](#cubejs_db_query_limit) (`50000`) |

Set it below `CUBEJS_DB_QUERY_LIMIT` to let other APIs return large result sets
while keeping SQL API responses small enough to fit in a single batch, or streamed
if streaming mode is enabled. Buffering very large non-streamed responses can
exhaust memory and break the client connection.

<Warning>
  This value cannot exceed [`CUBEJS_DB_QUERY_LIMIT`](#cubejs_db_query_limit). If you
  set it higher, Cube logs a warning at startup and falls back to
  `CUBEJS_DB_QUERY_LIMIT`, because non-streamed queries above that limit are rejected
  before they reach the data source.
</Warning>

## `CUBESQL_SQL_NO_IMPLICIT_ORDER`

If `true`, prevents adding implicit [default `ORDER BY`
clause](/reference/core-data-apis/queries#order) for [SQL API][ref-sql-api] queries.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `true`                 | `true`                |

## `CUBEJS_MAX_SESSIONS`

Specifies the maximum number of concurrent sessions (connections) to the
[SQL API][ref-sql-api] and safeguards your Cube deployment from out-of-memory
crashes when too many connections are attempted to be established.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid number  | 1024                   | 1024                  |

## `CUBESQL_REWRITE_MAX_NODES`

Specifies the maximum number of e-graph nodes that are allocated during
the creation of a query plan in the [SQL API][ref-sql-api].

Should be increased if you get the following error:
`Error during rewrite: Can't find rewrite due to 10002 AST node limit reached.`

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid number  | 10000                  | 10000                 |

## `CUBESQL_REWRITE_MAX_ITERATIONS`

Specifies the maximum number of e-graph term rewriting iterations that are performed
during the creation of a query plan in the [SQL API][ref-sql-api].

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid number  | 300                    | 300                   |

## `CUBESQL_REWRITE_TIMEOUT`

Specifies the maximum time, in seconds, that is allocated for
the creation of a query plan in the [SQL API][ref-sql-api].

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid number  | 30                     | 30                    |

## `CUBESQL_AUTH_EXPIRE_SECS`

Number of seconds before session's SQL API security context will be invalidated.

| Possible Values        | Default in Development | Default in Production |
| ---------------------- | ---------------------- | --------------------- |
| A valid integer number | `300`                  | `300`                 |

## `CUBEJS_DAX_CREATE_DATE_HIERARCHIES`

If `true`, the DAX API will expose time dimensions as calendar hierarchies.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `true`                 | `true`                |

## `CUBEJS_DAX_SINGLE_PERSPECTIVE`

If `true`, the DAX API exposes all views as part of a single
perspective, enabling cross-view filtering.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `CUBE_XMLA_LANGUAGE`

This variable is used to [configure the locale][ref-mdx-api-locale] for the [MDX API][ref-mdx-api].

| Possible Values                                                 | Default in Development           | Default in Production            |
| --------------------------------------------------------------- | -------------------------------- | -------------------------------- |
| Either a [LCID][link-lcid] (numeric) or a language tag (string) | `1033` (English - United States) | `1033` (English - United States) |

For example, to display currency values using the Netherlands locale (euro with comma as decimal separator), you can use either:

```bash theme={"dark"}
# LCID
CUBE_XMLA_LANGUAGE=1043

# Language tag
CUBE_XMLA_LANGUAGE=nl-NL
```

[link-lcid]: https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-lcid/70feba9f-294e-491e-b6eb-56532684c37f

## `CUBE_MDX_CREATE_DATE_HIERARCHIES`

If `true`, the [MDX API][ref-mdx-api] will automatically create additional hierarchies for all [time dimensions][ref-time-dimensions] and organize them in a separate "Calendar" folder for each dimension.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `true`                 | `true`                |

## `CUBEJS_NESTED_FOLDERS_DELIMITER`

Specifies the delimiter used to flatten the names of nested [folder][ref-folders] in
views when [visualization tools][ref-dataviz-tools] do not support nested folder
structures. When set, nested folders will be presented at the root level with path-like
names using the specified delimiter.

| Possible Values                      | Default in Development | Default in Production |
| ------------------------------------ | ---------------------- | --------------------- |
| A valid string delimiter (e.g., `/`) | N/A                    | N/A                   |

For example, if set to `/`, a nested folder structure like the `Customer Information`
folder with the `Personal Details` subfolder will be flattened to `Customer
Information / Personal Details` at the root level.

## `CUBEJS_TELEMETRY`

If `true`, then send telemetry to Cube.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `true`                 | `true`                |

## `CUBESTORE_METRICS_FORMAT`

Define which metrics collector format.

| Possible Values       | Default in Development | Default in Production |
| --------------------- | ---------------------- | --------------------- |
| `statsd`, `dogstatsd` | `statsd`               | `statsd`              |

## `CUBESTORE_METRICS_ADDRESS`

Required IP address to send metrics.

| Possible Values    | Default in Development | Default in Production |
| ------------------ | ---------------------- | --------------------- |
| A valid IP address | `127.0.0.1`            | `127.0.0.1`           |

## `CUBESTORE_METRICS_PORT`

Required port to send where collector server accept UDP connections.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid port number | `8125`                 | `8125`                |

## `CUBEJS_TOUCH_PRE_AGG_TIMEOUT`

<Warning>
  If the refresh worker’s throughput isn’t sufficient and the Cube Refresh Worker can’t refresh every partition, Cube will start dropping partitions once the timeout is reached.
  For externally refreshed pre-aggregations, make sure each pre-aggregation is refreshed at least once within the specified timeout period.
</Warning>

The number of seconds without a touch before pre-aggregation is considered
orphaned and marked for removal. Please see
[`CUBEJS_DROP_PRE_AGG_WITHOUT_TOUCH`](/reference/configuration/environment-variables#cubejs_drop_pre_agg_without_touch) to
learn more.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid number  | 86400                  | 86400                 |

## `CUBEJS_WEB_SOCKETS`

If `true`, then use WebSocket for data fetching.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `CUBEJS_TESSERACT_SQL_PLANNER`

Enables Tesseract, the [next-generation data modeling engine][link-tesseract],
which is the default SQL planner and powers
[multi-stage calculations][ref-multi-stage-calculations]. In versions before v1.7.0,
Tesseract was not enabled by default. Set to `false` to fall back to the legacy
planner, which is deprecated and will be removed in the near future.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `true`                 | `true`                |

Tesseract-based pre-aggregation matching and planning follows this flag and cannot be
toggled independently.

## `CUBESTORE_AWS_ACCESS_KEY_ID`

The Access Key ID for AWS. Required when using AWS S3.

| Possible Values                             | Default in Development | Default in Production |
| ------------------------------------------- | ---------------------- | --------------------- |
| [A valid AWS Access Key ID][aws-docs-creds] | N/A                    | N/A                   |

## `CUBESTORE_AWS_SECRET_ACCESS_KEY`

The Secret Access Key for AWS. Required when using AWS S3.

| Possible Values                                 | Default in Development | Default in Production |
| ----------------------------------------------- | ---------------------- | --------------------- |
| [A valid AWS Secret Access Key][aws-docs-creds] | N/A                    | N/A                   |

## `CUBESTORE_AWS_CREDS_REFRESH_EVERY_MINS`

The number of minutes after which Cube Store should refresh AWS credentials.
Required when using an AWS instance role.

| Possible Values           | Default in Development | Default in Production |
| ------------------------- | ---------------------- | --------------------- |
| A valid number in minutes | `180`                  | `180`                 |

## `CUBESTORE_AWS_WEB_IDENTITY_TOKEN_FILE`

The path to an AWS web identity token file. When `CUBESTORE_AWS_ACCESS_KEY_ID` is
not set and this variable is present, Cube Store authenticates to S3 using AWS Web
Identity (for example, [IRSA](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)
on Amazon EKS): it exchanges the token for
temporary credentials via STS `AssumeRoleWithWebIdentity` and re-exchanges them
when the token file changes.

| Possible Values   | Default in Development | Default in Production |
| ----------------- | ---------------------- | --------------------- |
| A valid file path | N/A                    | N/A                   |

## `CUBESTORE_AWS_ROLE_ARN`

The ARN of the AWS IAM role to assume when using
[`CUBESTORE_AWS_WEB_IDENTITY_TOKEN_FILE`](#cubestore_aws_web_identity_token_file).

| Possible Values      | Default in Development | Default in Production |
| -------------------- | ---------------------- | --------------------- |
| A valid IAM role ARN | N/A                    | N/A                   |

## `CUBESTORE_BIND_ADDR`

The address/port pair for Cube Store's MySQL-compatible interface.

| Possible Values           | Default in Development | Default in Production |
| ------------------------- | ---------------------- | --------------------- |
| A valid address/port pair | `0.0.0.0:3306`         | `0.0.0.0:3306`        |

## `CUBESTORE_CACHE_MAX_ENTRY_SIZE`

The maximum size of a single entry in Cube Store's
[cache store](/docs/pre-aggregations/cube-store-architecture#cache-and-queue-store).
Larger entries are rejected. Cannot exceed
[`CUBESTORE_TRANSPORT_MAX_MESSAGE_SIZE`](#cubestore_transport_max_message_size)
minus 1 MiB.

| Possible Values      | Default in Development | Default in Production |
| -------------------- | ---------------------- | --------------------- |
| A size, e.g. `63MiB` | `63MiB`                | `63MiB`               |

## `CUBESTORE_DATA_DIR`

A path on the local filesystem to store a local replica of the data. Must be
unique on each node and different from `CUBESTORE_REMOTE_DIR`.

| Possible Values                                             | Default in Development | Default in Production |
| ----------------------------------------------------------- | ---------------------- | --------------------- |
| A valid path on the local filesystem with read/write access | `.cubestore/data`      | `.cubestore/data`     |

## `CUBESTORE_GCP_CREDENTIALS`

A Base64-encoded JSON key for connecting to Google Cloud. Required when
using Google Cloud Storage

| Possible Values                                                                 | Default in Development | Default in Production |
| ------------------------------------------------------------------------------- | ---------------------- | --------------------- |
| [A valid Google Cloud JSON key encoded as a Base64 string][gcp-docs-creds-json] | N/A                    | N/A                   |

## `CUBESTORE_GCP_KEY_FILE`

The path to a JSON key file for connecting to Google Cloud. Required when using
Google Cloud Storage.

| Possible Values                                           | Default in Development | Default in Production |
| --------------------------------------------------------- | ---------------------- | --------------------- |
| [A valid Google Cloud JSON key file][gcp-docs-creds-json] | N/A                    | N/A                   |

## `CUBESTORE_GCS_BUCKET`

The name of a bucket in GCS. Required when using GCS

| Possible Values                                 | Default in Development | Default in Production |
| ----------------------------------------------- | ---------------------- | --------------------- |
| A valid bucket name in the Google Cloud account | N/A                    | N/A                   |

## `CUBESTORE_GCS_SUB_PATH`

The path in a GCS bucket to store pre-aggregations. Optional

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid path prefix | N/A                    | N/A                   |

## `CUBESTORE_HTTP_BIND_ADDR`

The address/port pair for Cube Store's HTTP interface.

| Possible Values           | Default in Development | Default in Production |
| ------------------------- | ---------------------- | --------------------- |
| A valid address/port pair | `0.0.0.0:3030`         | `0.0.0.0:3030`        |

## `CUBESTORE_HTTP_PORT`

The port for Cube Store to listen to HTTP connections on. Ignored when
`CUBESTORE_HTTP_BIND_ADDR` is set.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid port number | `3030`                 | `3030`                |

## `CUBESTORE_JOB_RUNNERS`

The number of parallel tasks that process non-interactive jobs like data
insertion, compaction etc.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid number  | `4`                    | `4`                   |

## `CUBESTORE_LOG_LEVEL`

The logging level for Cube Store.

| Possible Values                           | Default in Development | Default in Production |
| ----------------------------------------- | ---------------------- | --------------------- |
| `error`, `warn`, `info`, `debug`, `trace` | `error`                | `error`               |

See also [`CUBEJS_LOG_LEVEL`](/reference/configuration/environment-variables#cubejs_log_level).

## `CUBESTORE_MAX_WS_CONNECTIONS_PER_USER`

The maximum number of concurrent WebSocket connections a single authenticated
user may hold. At the limit, that user's oldest connection is closed to admit the
new one: a client that still needs it reconnects, while one that had forgotten
about it simply loses it. The limit is counted per Cube Store node, so a user
connecting to several nodes may hold up to this many on each.

Use it to keep one client that leaks connections from exhausting the node's file
descriptors for everyone else. Set it comfortably above the number of connections
a client legitimately keeps open at once, or working connections will be recycled.
`0` disables the limit.

| Possible Values        | Default in Development | Default in Production |
| ---------------------- | ---------------------- | --------------------- |
| A non-negative integer | `0`                    | `0`                   |

## `CUBESTORE_META_ADDR`

The address/port pair for the Cube Store **router** node in the cluster.

| Possible Values           | Default in Development | Default in Production |
| ------------------------- | ---------------------- | --------------------- |
| A valid address/port pair | N/A                    | N/A                   |

## `CUBESTORE_META_PORT`

The port for the Cube Store **router** node to listen for connections on.
Ignored when `CUBESTORE_META_ADDR` is set.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid port number | N/A                    | N/A                   |

## `CUBESTORE_MINIO_ACCESS_KEY_ID`

The Access Key ID for MinIO. Required when using MinIO.

| Possible Values             | Default in Development | Default in Production |
| --------------------------- | ---------------------- | --------------------- |
| A valid MinIO Access Key ID | N/A                    | N/A                   |

## `CUBESTORE_MINIO_BUCKET`

The name of the bucket that you want to use MinIO. Required when using MinIO.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid bucket name | N/A                    | N/A                   |

## `CUBESTORE_MINIO_SUB_PATH`

The name of sub path (folder) inside the bucket that you want to use. Required when using MinIO.

| Possible Values                | Default in Development | Default in Production |
| ------------------------------ | ---------------------- | --------------------- |
| A valid sub path (folder) name | N/A                    | N/A                   |

## `CUBESTORE_MINIO_CREDS_REFRESH_EVERY_MINS`

The number of minutes after which Cube Store should refresh MinIO credentials.

| Possible Values           | Default in Development | Default in Production |
| ------------------------- | ---------------------- | --------------------- |
| A valid number in minutes | `180`                  | `180`                 |

## `CUBESTORE_MINIO_REGION`

The region of a bucket in AWS. Optional when using MinIO.

| Possible Values                                        | Default in Development | Default in Production |
| ------------------------------------------------------ | ---------------------- | --------------------- |
| A valid S3 region name, an empty string if not present | N/A                    | N/A                   |

## `CUBESTORE_MINIO_SECRET_ACCESS_KEY`

The Secret Access Key for MinIO. Required when using MinIO.

| Possible Values                 | Default in Development | Default in Production |
| ------------------------------- | ---------------------- | --------------------- |
| A valid MinIO Secret Access Key | N/A                    | N/A                   |

## `CUBESTORE_MINIO_SERVER_ENDPOINT`

The MinIO server endpoint. Required when using MinIO.

| Possible Values        | Default in Development | Default in Production |
| ---------------------- | ---------------------- | --------------------- |
| A valid MinIO endpoint | N/A                    | N/A                   |

```dotenv theme={"dark"}
CUBESTORE_MINIO_SERVER_ENDPOINT=http://localhost:9000
```

## `CUBESTORE_NO_UPLOAD`

If `true`, prevents uploading serialized pre-aggregations to cloud storage.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `CUBESTORE_PORT`

The port for Cube Store to listen to connections on. Ignored when
`CUBESTORE_BIND_ADDR` is set.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid port number | `3306`                 | `3306`                |

## `CUBESTORE_QUERY_TIMEOUT`

The timeout for SQL queries in seconds.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A number in seconds | `120`                  | `120`                 |

## `CUBESTORE_QUERY_CACHE_STALE_WHILE_REVALIDATE`

Enables stale-while-revalidate behavior for Cube Store's SQL result cache. When set
to a number of seconds, a cached result that has expired is still served for up to
that many seconds while the cache is refreshed in the background. Set to `0` to
disable.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A number in seconds | `0`                    | `0`                   |

## `CUBESTORE_REMOTE_DIR`

A path on the local filesystem to store metadata and datasets from all nodes as
if it were remote storage. Not required if using GCS/S3. Not recommended for
production usage

| Possible Values                                             | Default in Development | Default in Production |
| ----------------------------------------------------------- | ---------------------- | --------------------- |
| A valid path on the local filesystem with read/write access | N/A                    | N/A                   |

## `CUBESTORE_S3_BUCKET`

The name of a bucket in AWS S3. Required when using AWS S3.

| Possible Values                        | Default in Development | Default in Production |
| -------------------------------------- | ---------------------- | --------------------- |
| A valid bucket name in the AWS account | N/A                    | N/A                   |

## `CUBESTORE_S3_REGION`

\| The region of a bucket in AWS S3. Required when using AWS S3.

| Possible Values                        | Default in Development | Default in Production |
| -------------------------------------- | ---------------------- | --------------------- |
| [A valid AWS region][aws-docs-regions] | N/A                    | N/A                   |

## `CUBESTORE_S3_SSE`

When set, Cube Store sends the `x-amz-server-side-encryption` header with this
value on every AWS S3 request. Optional. Useful when an AWS Organizations
service control policy denies `s3:PutObject` requests that lack this header,
even if the bucket has default encryption enabled.

| Possible Values                     | Default in Development | Default in Production |
| ----------------------------------- | ---------------------- | --------------------- |
| `AES256`, `aws:kms`, `aws:kms:dsse` | N/A                    | N/A                   |

## `CUBESTORE_S3_SUB_PATH`

The path in a AWS S3 bucket to store pre-aggregations. Optional.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid path prefix | N/A                    | N/A                   |

## `CUBESTORE_SELECT_WORKERS`

The number of Cube Store sub-processes that handle `SELECT` queries.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid number  | `4`                    | `4`                   |

## `CUBESTORE_SERVER_NAME`

The full name and port number of the Cube Store node (either the router
or a worker). Must be unique for each instance in the Cube Store cluster.

Should be passed to the Cube Store router and to each Cube Store worker.

| Possible Values           | Default in Development | Default in Production |
| ------------------------- | ---------------------- | --------------------- |
| A valid address/port pair | `localhost`            | `localhost`           |

## `CUBESTORE_TELEMETRY`

If `true`, then sends telemetry to Cube.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `true`                 | `true`                |

## `CUBESTORE_TRANSPORT_MAX_MESSAGE_SIZE`

The maximum size of a single message on the WebSocket connection between Cube
and Cube Store. Messages above this size are answered with an error; see
[message size limits](/docs/pre-aggregations/cube-store-architecture#message-size-limits).

| Possible Values                 | Default in Development | Default in Production |
| ------------------------------- | ---------------------- | --------------------- |
| A size from `16MiB` to `256MiB` | `64MiB`                | `64MiB`               |

## `CUBESTORE_TRANSPORT_MAX_FRAME_SIZE`

The maximum size of a single WebSocket frame on the connection between Cube
and Cube Store. A message is split into frames, so this can be smaller than
[`CUBESTORE_TRANSPORT_MAX_MESSAGE_SIZE`](#cubestore_transport_max_message_size).

| Possible Values                | Default in Development | Default in Production |
| ------------------------------ | ---------------------- | --------------------- |
| A size from `4MiB` to `256MiB` | `64MiB`                | `64MiB`               |

## `CUBESTORE_WAL_SPLIT_THRESHOLD`

The maximum number of rows to keep in a single chunk of data right after
insertion.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid number  | `262144`               | `262144`              |

## `CUBESTORE_CHUNKS_COUNT_THRESHOLD`

The number of chunks a partition can accumulate before Cube Store compacts them into
a single chunk.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid number  | `4`                    | `4`                   |

## `CUBESTORE_COMPACTION_READINESS_CHUNKS_THRESHOLD`

The number of chunks at which a table's partitions are considered ready during table
creation. When set, it must not be lower than
[`CUBESTORE_CHUNKS_COUNT_THRESHOLD`](#cubestore_chunks_count_threshold), otherwise
compaction would never reduce the number of chunks below this threshold. By default,
it is not set.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| A valid number  | N/A                    | N/A                   |

## `CUBESTORE_WORKER_PORT`

The port for Cube Store workers to listen to connections on. When set, the node
will start as a Cube Store **worker** in the cluster

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid port number | N/A                    | N/A                   |

## `CUBESTORE_WORKERS`

A comma-separated list of address/port pairs of Cube Store workers.

Should be passed to the Cube Store router and to each Cube Store worker.

| Possible Values                              | Default in Development | Default in Production |
| -------------------------------------------- | ---------------------- | --------------------- |
| A comma-separated list of address/port pairs | N/A                    | N/A                   |

```dotenv theme={"dark"}
CUBESTORE_WORKERS=worker-1:3123,localhost:3124,123.124.125.128:3123
```

Used to implement stateless addressing within a Cube Store cluster.
By analyzing `CUBESTORE_WORKERS` and `CUBESTORE_SERVER_NAME`, each node
is able to determine its position within a Cube Store cluster.
This allows each worker to know which pre-aggregation partitions it owns
and how the load is distributed across all workers.

## `DEBUG_LOG`

If `true`, enables debug logging.

| Possible Values | Default in Development | Default in Production |
| --------------- | ---------------------- | --------------------- |
| `true`, `false` | `false`                | `false`               |

## `NODE_EXTRA_CA_CERTS`

A path to a PEM file with CA certificates that Node.js should trust in
addition to its built-in bundle — additive, it doesn't replace the public CA
bundle. Read once at process start, so the deployment must restart after this
is set for it to take effect. Used by [Semantic Layer Sync][ref-sls] when the
BI tool is served with a certificate from a private or internal CA — the
sync's outbound requests run in Node.js, so `CURL_CA_BUNDLE` and
`REQUESTS_CA_BUNDLE` have no effect on it.

| Possible Values   | Default in Development | Default in Production |
| ----------------- | ---------------------- | --------------------- |
| A valid file path | N/A                    | N/A                   |

## `PORT`

The port for a Cube deployment to listen to API connections on.

| Possible Values     | Default in Development | Default in Production |
| ------------------- | ---------------------- | --------------------- |
| A valid port number | `4000`                 | `4000`                |

[aws-athena]: https://aws.amazon.com/athena

[aws-athena-workgroup]: https://docs.aws.amazon.com/athena/latest/ug/workgroups-benefits.html

[aws-athena-catalog]: https://docs.aws.amazon.com/athena/latest/ug/understanding-tables-databases-and-the-data-catalog.html

[aws-docs-creds]: https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys

[aws-docs-regions]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions

[aws-docs-vpc-endpoints]: https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-s3.html

[bq-docs-regional-locations]: https://cloud.google.com/bigquery/docs/locations#regional-locations

[databricks-docs-dbfs]: https://docs.databricks.com/data/databricks-file-system.html#mount-object-storage-to-dbfs

[databricks-docs-pat]: https://docs.databricks.com/dev-tools/api/latest/authentication.html#token-management

[firebolt-docs-account-name]: https://docs.firebolt.io/managing-your-account/concepts-and-terminology.html#firebolt-account

[firebolt-docs-engine-name]: https://docs.firebolt.io/working-with-engines/understanding-engine-fundamentals.html#engine-name

[gcp-docs-creds-json]: https://cloud.google.com/iam/docs/creating-managing-service-account-keys

[gh-docs-pat]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

[gh-jsonwebtoken-algs]: https://github.com/auth0/node-jsonwebtoken#algorithms-supported

[ietf-jwk-ref]: https://tools.ietf.org/html/rfc7517#section-4

[ietf-jwt-ref-iss]: https://tools.ietf.org/html/rfc7519#section-4.1.1

[ietf-jwt-ref-sub]: https://tools.ietf.org/html/rfc7519#section-4.1.2

[ietf-jwt-ref-aud]: https://tools.ietf.org/html/rfc7519#section-4.1.3

[motherduck-docs-svc-token]: https://motherduck.com/docs/authenticating-to-motherduck/#authentication-using-a-service-token

[ref-config-db]: /admin/connect-to-data/data-sources

[ref-config-driver-factory]: /reference/configuration/config#driver_factory

[ref-config-query-cache-options]: /reference/configuration/config#orchestrator_options

[ref-config-multiple-ds-cloud]: /admin/connect-to-data/multiple-data-sources

[ref-config-multiple-ds-decorating-env]: /admin/connect-to-data/multiple-data-sources#under-the-hood

[ref-preagg-data-source]: /docs/pre-aggregations/refreshing-pre-aggregations#pre-aggregation-data-source

[ref-config-sched-refresh-timer]: /reference/configuration/config#scheduled_refresh_timer

[ref-rest-scopes]: /reference/core-data-apis/rest-api#configuration-api-scopes

[snowflake-docs-account-id]: https://docs.snowflake.com/en/user-guide/admin-account-identifier.html

[snowflake-docs-connection-options]: https://docs.snowflake.com/en/user-guide/nodejs-driver-use.html#additional-connection-options

[snowflake-docs-regions]: https://docs.snowflake.com/en/user-guide/intro-regions.html

[snowflake-docs-roles]: https://docs.snowflake.com/en/user-guide/security-access-control-overview.html#roles

[snowflake-docs-warehouse]: https://docs.snowflake.com/en/user-guide/warehouses.html

[wiki-tz-database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

[ref-sql-api]: /reference/core-data-apis/sql-api

[ref-sql-api-streaming]: /reference/core-data-apis/sql-api#streaming

[ref-ref-cubesql]: /reference/core-data-apis/rest-api/reference#base_path/v1/cubesql

[ref-row-limit]: /reference/core-data-apis/queries#row-limit

[mysql-server-tz-support]: https://dev.mysql.com/doc/refman/8.4/en/time-zone-support.html

[ref-schema-ref-preagg-allownonstrict]: /reference/data-modeling/pre-aggregations#allow_non_strict_date_range_match

[link-tesseract]: https://cube.dev/blog/introducing-next-generation-data-modeling-engine

[ref-multi-stage-calculations]: /docs/data-modeling/measures#multi-stage-measures

[ref-folders]: /reference/data-modeling/view#folders

[ref-dataviz-tools]: /admin/connect-to-data/visualization-tools

[ref-context-to-app-id]: /reference/configuration/config#context_to_app_id

[ref-environments]: /admin/deployment/environments

[ref-databricks-m2m-oauth]: https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m

[ref-mdx-api]: /reference/core-data-apis/mdx-api

[ref-mdx-api-locale]: /reference/core-data-apis/mdx-api#measure-format

[ref-time-dimensions]: /reference/data-modeling/dimensions#type

[ref-time-zone]: /reference/core-data-apis/queries#time-zone

[link-tzdb]: https://en.wikipedia.org/wiki/Tz_database

[nodejs-docs-tls-options]: https://nodejs.org/docs/latest/api/tls.html#tls_tls_createsecurecontext_options

[ref-sls]: /docs/integrations/semantic-layer-sync


# Control Plane API
Source: https://docs.cube.dev/reference/control-plane-api

REST surface for automating Cube Cloud deployments, environments, JWT issuance, and audit log export.

Control Plane API enables programmatic management of [deployments][ref-deployments]
and [environments][ref-environments] in Cube Cloud. You can use it to list
deployments, manage environments, generate JWT tokens for accessing
[Core Data APIs][ref-core-data-apis], and export [audit log][ref-audit-log] events.

<Info>
  Control Plane API is only available in Cube Cloud.
</Info>

## Prerequisites

### Authentication

Control Plane API uses [API key][ref-api-keys] authentication. Include your API
key in the `Authorization` header with the `Bearer` prefix:

```bash theme={"dark"}
curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://YOUR_CUBE_CLOUD_HOST/api/v1/deployments
```

### Error handling

In case of an error, Control Plane API returns a JSON object with an `error` property:

```json theme={"dark"}
{
  "error": "Error message"
}
```

### Pagination

Endpoints that return lists support pagination using `offset` and `limit` query
parameters:

| Parameter | Description                                      |
| --------- | ------------------------------------------------ |
| `offset`  | Number of items to skip. Default: `0`            |
| `limit`   | Maximum number of items to return. Default: `20` |

Paginated responses include a `pagination` object:

```json theme={"dark"}
{
  "data": [...],
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 42
  }
}
```

## Reference

### `/api/v1/deployments`

Send a `GET` request to list all [deployments][ref-deployments] accessible to the authenticated user.

Query parameters:

| Parameter | Description       | Required |
| --------- | ----------------- | -------- |
| `offset`  | Pagination offset | No       |
| `limit`   | Pagination limit  | No       |

Example request:

```bash theme={"dark"}
curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://YOUR_CUBE_CLOUD_HOST/api/v1/deployments"
```

Example response:

```json theme={"dark"}
{
  "data": {
    "deployments": [
      {
        "id": "123",
        "name": "My Deployment",
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    ]
  },
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 1
  }
}
```

### `/api/v1/deployments/{deployment_id}/environments`

Send a `GET` request to list [environments][ref-environments] for a specific [deployment][ref-deployments].

Path parameters:

| Parameter       | Description       |
| --------------- | ----------------- |
| `deployment_id` | The deployment ID |

Query parameters:

| Parameter | Description                                                           | Required |
| --------- | --------------------------------------------------------------------- | -------- |
| `type`    | Filter by environment type: `production`, `staging`, or `development` | No       |
| `offset`  | Pagination offset                                                     | No       |
| `limit`   | Pagination limit                                                      | No       |

Example request:

```bash theme={"dark"}
curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://YOUR_CUBE_CLOUD_HOST/api/v1/deployments/123/environments"
```

Example response:

```json theme={"dark"}
{
  "data": {
    "environments": [
      {
        "id": "456",
        "name": "Production",
        "type": "production",
        "api_credentials": {
          "rest": {
            "url": "https://example.cubecloud.dev/cubejs-api"
          },
          "sql": {
            "host": "example.sql.cubecloud.dev",
            "port": 5432
          }
        }
      }
    ]
  },
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 1
  }
}
```

### `/api/v1/deployments/{deployment_id}/environments/{environment_id}/tokens-for-meta-sync`

Send a `POST` request to create a JWT token for accessing the
[Metadata API][ref-metadata-api]. The generated token is scoped specifically
to metadata endpoints (e.g., `/v1/data-sources`, `/v1/entities`) and cannot
be used to query data via the [REST (JSON) API][ref-rest-api]. This makes it suitable
for integrations such as data catalogs and lineage tools that only need to
read data model metadata.

The [security context][ref-security-context] you provide is embedded in the
token and controls which parts of the data model are visible, following the
same multi-tenancy rules as regular API tokens.

Path parameters:

| Parameter        | Description        |
| ---------------- | ------------------ |
| `deployment_id`  | The deployment ID  |
| `environment_id` | The environment ID |

Request body:

| Property           | Type     | Description                                                                                                                               | Required |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `security_context` | `object` | [Security context][ref-security-context] to embed in the token. Controls data model visibility based on your multi-tenancy configuration. | Yes      |
| `expires_in`       | `number` | Token expiration time in seconds. Default: `86400` (24 hours)                                                                             | No       |

Example request:

```bash theme={"dark"}
curl \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "security_context": {"tenant_id": "acme"},
    "expires_in": 3600
  }' \
  "https://YOUR_CUBE_CLOUD_HOST/api/v1/deployments/123/environments/456/tokens-for-meta-sync"
```

Example response:

```json theme={"dark"}
{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "created_at": "2024-01-15T10:30:00.000Z",
    "expires_at": "2024-01-15T11:30:00.000Z"
  }
}
```

### `/build/api/v1/deployments/{deployment_id}/branches/staging-environment`

Send a `PUT` request to enable or disable a branch, i.e. to control whether its
[staging environment][ref-environments-staging] stays always active. Disabled
(the default), a staging environment is only active while the branch is viewed
in the Cube UI; enabled, it remains active and accessible regardless of user
activity, and it is reported by
[`/api/v1/deployments/{deployment_id}/environments`](#apiv1deploymentsdeployment_idenvironments)
as a `staging` environment.

Only shared branches can be enabled — personal development branches and the
production branch are rejected.

<Info>
  Note the `/build` prefix: data model and branch endpoints are served by the
  build API.
</Info>

Path parameters:

| Parameter       | Description       |
| --------------- | ----------------- |
| `deployment_id` | The deployment ID |

Body parameters:

| Parameter    | Description                                                                                         | Required                          |
| ------------ | --------------------------------------------------------------------------------------------------- | --------------------------------- |
| `enabled`    | `true` enables the branch, `false` disables it                                                      | Yes                               |
| `branchName` | Name of the branch to update                                                                        | One of `branchName` or `branchId` |
| `branchId`   | ID of the branch to update, as returned by `GET /build/api/v1/deployments/{deployment_id}/branches` | One of `branchName` or `branchId` |

Example request:

```bash theme={"dark"}
curl -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"branchName": "staging", "enabled": true}' \
  "https://YOUR_CUBE_CLOUD_HOST/build/api/v1/deployments/123/branches/staging-environment"
```

Example response:

```json theme={"dark"}
{
  "data": {
    "id": 456,
    "name": "staging",
    "parentBranch": "main",
    "lastHash": "9f2c1ab",
    "isStagingEnvironmentEnabled": true
  }
}
```

The same operation is available in the [CLI][ref-cli] as
`cube data-model enable-branch` / `cube data-model disable-branch`.

### `/api/v1/deployments/{deployment_id}/versions`

Send a `GET` request to list the Cube versions a deployment can be switched
to — the same set the Cube Cloud UI's version picker offers: the head of each
[update channel][ref-update-channels], plus the older versions your account has
run before.

Example request:

```bash theme={"dark"}
curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://YOUR_CUBE_CLOUD_HOST/api/v1/deployments/123/versions"
```

Example response:

```json theme={"dark"}
{
  "data": [
    {
      "releaseChannelVersion": "cubejs/cube:v1.7.20",
      "version": "1.7.20",
      "releaseChannel": "latest",
      "isLatestInChannel": true,
      "isCurrent": true
    },
    {
      "releaseChannelVersion": "cubejs/cube:v1.6.69",
      "version": "1.6.69",
      "releaseChannel": "latest",
      "isLatestInChannel": false,
      "isCurrent": false
    }
  ]
}
```

To change the version, send a listed value as `releaseChannelVersion` to
`PUT /api/v1/deployments/{deployment_id}`. Any of `1.7.20`, `v1.7.20` or
`cubejs/cube:v1.7.20` is accepted; a version that is not on the list is
rejected with a `400`. The container image is resolved from the version
server-side and cannot be set directly.

<Note>
  Leaving `releaseChannelVersion` out and sending only `releaseChannel` moves the
  deployment to that channel's latest version.
</Note>

The same operation is available in the [CLI][ref-cli] as
`cube deployments versions`, with `cube deployments update ID --release-channel-version 1.7.20` to apply one.

### `/api/v1/audit-logs/export`

Send a `GET` request to export [audit log][ref-audit-log] events as a CSV
file. This endpoint allows you to programmatically retrieve security-related
events for compliance reviews, external log aggregation, or integration with
SIEM tools.

<Info>
  Requires [Audit Log][ref-audit-log] to be enabled on the
  [Enterprise plan](https://cube.dev/pricing). The authenticated user
  must have the `AuditLogManage` permission.
</Info>

Query parameters:

| Parameter   | Description                                                   | Required |
| ----------- | ------------------------------------------------------------- | -------- |
| `start`     | Start of the date range (ISO 8601 format, e.g., `2024-01-01`) | No       |
| `end`       | End of the date range (ISO 8601 format, e.g., `2024-01-31`)   | No       |
| `search`    | Full-text search across event data                            | No       |
| `eventName` | Filter by event type (e.g., `Logged in`)                      | No       |
| `userEmail` | Filter by user email                                          | No       |

The response is a CSV file streamed as an attachment.

Example request:

```bash theme={"dark"}
curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o audit_log.csv \
  "https://YOUR_CUBE_CLOUD_HOST/api/v1/audit-logs/export?start=2024-01-01&end=2024-01-31"
```

Example request with filters:

```bash theme={"dark"}
curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o audit_log.csv \
  "https://YOUR_CUBE_CLOUD_HOST/api/v1/audit-logs/export?start=2024-01-01&end=2024-01-31&eventName=Logged+in&userEmail=user@example.com"
```

[ref-core-data-apis]: /reference/core-data-apis

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-metadata-api]: /reference/core-data-apis/rest-api/reference#metadata-api

[ref-deployments]: /admin/deployment

[ref-environments]: /admin/deployment/environments

[ref-environments-staging]: /admin/deployment/environments#staging-environments

[ref-cli]: /reference/cli

[ref-api-keys]: /admin/account-billing/api-keys

[ref-security-context]: /docs/data-modeling/access-control/context

[ref-audit-log]: /admin/monitoring/audit-log

[ref-update-channels]: /admin/deployment#update-channels


# GraphQL API
Source: https://docs.cube.dev/reference/core-data-apis/graphql-api/index

Query Cube over HTTP using GraphQL for embedded analytics and front-end data applications.

GraphQL API

GraphQL API enables Cube to deliver data over the HTTP protocol to
[GraphQL][graphql]-enabled data applications, e.g., most commonly, front-end
applications.

Often, the GraphQL API is used to enable the [embedded analytics][cube-ea] use
case.

Under the hood, the GraphQL API is exposed via the `/graphql` endpoint of the
[REST (JSON) API][ref-rest-api].

See [GraphQL API reference][ref-ref-graphql-api] for the list of supported
requests and parameters.

<Warning>
  Compared to the [REST (JSON) API][ref-rest-api], GraphQL API currently has the
  following limitations:

  * No support for the [WebSockets transport][ref-websockets].
  * No support for [subscriptions to changes][ref-subscriptions].
  * No support for referencing [segments][ref-segments] in queries.
  * No support for [compare date range queries][ref-compare-date-range].
  * No support for querying [data model metadata][ref-metadata].
  * No ability to apply a [pivot config][ref-pivot-config] on the front-end.
</Warning>

## Configuration

GraphQL API is enabled by default and secured using [API scopes][ref-api-scopes]
and [CORS][ref-cors]. To disallow access to GraphQL API, disable the `graphql`
scope, e.g., by setting the [`CUBEJS_DEFAULT_API_SCOPES`](/reference/configuration/environment-variables#cubejs_default_api_scopes) environment variable to
`meta,data`.

To find your GraphQL API endpoint in Cube Cloud, go to the **Overview**
page, click **API credentials**, and choose the **GraphQL API** tab.

## Getting started

As an example, let's use the `orders` cube from the example eCommerce database:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      measures:
        - name: count
          type: count

      dimensions:
        - name: status
          sql: status
          type: string

        - name: created_at
          sql: created_at
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    measures: {
      count: {
        type: `count`
      }
    },

    dimensions: {
      status: {
        sql: `status`,
        type: `string`
      },

      created_at: {
        sql: `created_at`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

A GraphQL query to return the number of orders by status would look something
like this:

```graphql theme={"dark"}
{
  cube {
    orders {
      count
      status
      created_at {
        day
      }
    }
  }
}
```

The equivalent query to the REST (JSON) API endpoint would look like this:

```json theme={"dark"}
{
  "measures": ["orders.count"],
  "dimensions": ["orders.status"],
  "timeDimensions": [
    {
      "dimension": "orders.created_at",
      "granularity": "day"
    }
  ]
}
```

### Modifying time dimension granularity

The granularity for a time dimension can easily be changed by specifying it in
the query:

```graphql theme={"dark"}
{
  cube {
    orders {
      created_at {
        month
      }
    }
  }
}
```

[Any supported granularity][ref-schema-ref-preagg-granularity] can be used. If
you prefer to not specify a granularity, then use `value`:

```graphql theme={"dark"}
{
  cube {
    orders {
      created_at {
        value
      }
    }
  }
}
```

### Specifying filters and ranges

Filters can be set on the load query or on a specific cube. Specifying the
filter on the load query applies it to all cubes in the query. Filters can be
added to the query as follows:

```graphql theme={"dark"}
query {
  cube(limit: 100, offset: 50, timezone: "America/Los_Angeles") {
    orders(
      orderBy: { created_at: asc, count: desc }
      where: { status: { equals: "completed" } }
    ) {
      count
      status
      created_at
    }
  }
}
```

Some other differences between the JSON query filters and the GraphQL filters to
note:

* `number` values are used for number types instead of strings
* The `notSet` filter is replaced by `{ set: false }`
* New `in` and `notIn` filters to check for multiple values
* `AND` and `OR` fields for boolean operators

The GraphQL API supports `@skip` and `@include` directives too:

```graphql theme={"dark"}
query GetOrders($byStatus: Boolean) {
  cube(limit: 100, offset: 50, timezone: "America/Los_Angeles") {
    orders(
      orderBy: { created_at: asc, count: desc }
      where: { status: { equals: "completed" } }
    ) {
      count
      status @include(if: $byStatus)
      created_at
    }
  }
}
```

### Querying multiple cubes

Using the same `orders` cube as before, let's try and get the numbers of
products for each order status too. We can do this by adding the `products` cube
to our query as follows:

```graphql theme={"dark"}
{
  cube {
    orders {
      status
      count
      created_at {
        month
      }
    }
    products {
      count
    }
  }
}
```

[ref-schema-ref-preagg-granularity]: /reference/data-modeling/pre-aggregations#granularity

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-api-scopes]: /reference/core-data-apis/rest-api#configuration-api-scopes

[ref-cors]: /reference/core-data-apis/rest-api#configuration-cors

[graphql]: https://graphql.org

[cube-ea]: https://cube.dev/use-cases/embedded-analytics

[ref-ref-graphql-api]: /reference/core-data-apis/graphql-api/reference

[ref-websockets]: /recipes/core-data-api/real-time-data-fetch#web-sockets

[ref-subscriptions]: /recipes/core-data-api/real-time-data-fetch#client-subscriptions

[ref-compare-date-range]: /reference/core-data-apis/queries#compare-date-range-query

[ref-metadata]: /reference/core-data-apis/rest-api/reference#base_path/v1/meta

[ref-pivot-config]: /reference/javascript-sdk/reference/cubejs-client-core#pivotconfig

[ref-segments]: /reference/data-modeling/segments


# GraphQL API reference
Source: https://docs.cube.dev/reference/core-data-apis/graphql-api/reference

GraphQL API supports the following requests and parameters.

[GraphQL API][ref-graphql-api] supports the following requests and parameters.

## `cube`

```graphql theme={"dark"}
query {
  cube [([cubeQueryArgs])] {
    <cubeName> [([cubeArgs])] {
      <cubeMember>
    }
  }
}
```

| Key             | Schema                            | Description                                |
| --------------- | --------------------------------- | ------------------------------------------ |
| `cubeQueryArgs` | [`CubeQueryArgs`](#cubequeryargs) | Options that apply to the entire query     |
| `cubeArgs`      | [`CubeArgs`](#cubeargs)           | Options that apply only to a specific cube |

## Response extensions

In addition to the `data` field, the GraphQL response includes an `extensions`
object with query metadata:

* `annotation` — metadata for the query members (titles, types), the same as the
  `annotation` field of the [REST API][ref-rest-api] response.
* `lastRefreshTime` — an ISO 8601 timestamp indicating when the data was last
  refreshed.
* `usedPreAggregations` — the pre-aggregations the result was served from, the
  same as the `usedPreAggregations` field of the [REST API][ref-rest-api]
  response. Absent when the query hit no pre-aggregation.

## `CubeQueryArgs`

* **`where` ([`RootWhereInput`](#rootwhereinput)):** Represents a SQL `WHERE` clause.
* **`limit` (`Int`):** A [row limit][ref-row-limit] for your query.
* **`offset` (`Int`):** The number of initial rows to be skipped for your query. The default value is `0`.
* **`timezone` (`String`):** The [time zone][ref-time-zone] for your query. You can set the
  desired time zone in the [TZ Database Name](https://en.wikipedia.org/wiki/Tz_database)
  format, e.g., `America/Los_Angeles`.
* **`ungrouped` (`Boolean`):** If set to `true`, Cube will run an
  [ungrouped query][ref-ungrouped-query].

## `RootWhereInput`

| Key          | Schema                                 | Description |
| ------------ | -------------------------------------- | ----------- |
| `AND`        | [`[RootWhereInput!]`](#rootwhereinput) |             |
| `OR`         | [`[RootWhereInput!]`](#rootwhereinput) |             |
| `<cubeName>` | [`CubeWhereInput`](#cubewhereinput)    |             |

## `CubeArgs`

| Key       | Schema                              | Description |
| --------- | ----------------------------------- | ----------- |
| `where`   | [`CubeWhereInput`](#cubewhereinput) |             |
| `orderBy` | `CubeOrderByInput`                  |             |

## `CubeWhereInput`

| Key            | Schema                                 | Description |
| -------------- | -------------------------------------- | ----------- |
| `AND`          | [`[RootWhereInput!]`](#rootwhereinput) |             |
| `OR`           | [`[RootWhereInput!]`](#rootwhereinput) |             |
| `<cubeMember>` | [`Filter`](#filter)                    |             |

## `CubeOrderByInput`

| Key            | Schema                | Description |
| -------------- | --------------------- | ----------- |
| `<cubeMember>` | [`OrderBy`](#orderby) |             |

## `Filter`

[`DateTimeFilter`](#datetimefilter) | [`FloatFilter`](#floatfilter) |
[`StringFilter`](#stringfilter)

## `DateTimeFilter`

| Key              | Schema     | Description |
| ---------------- | ---------- | ----------- |
| `equals`         | `String`   |             |
| `notEquals`      | `String`   |             |
| `in`             | `[String]` |             |
| `notIn`          | `[String]` |             |
| `inDateRange`    | `[String]` |             |
| `notInDateRange` | `[String]` |             |
| `beforeDate`     | `String`   |             |
| `afterDate`      | `String`   |             |
| `set`            | `Boolean`  |             |

## `FloatFilter`

| Key         | Schema    | Description |
| ----------- | --------- | ----------- |
| `equals`    | `Float`   |             |
| `notEquals` | `Float`   |             |
| `in`        | `[Float]` |             |
| `notIn`     | `[Float]` |             |
| `set`       | `Boolean` |             |

## `StringFilter`

| Key           | Schema     | Description |
| ------------- | ---------- | ----------- |
| `equals`      | `String`   |             |
| `notEquals`   | `String`   |             |
| `in`          | `[String]` |             |
| `notIn`       | `[String]` |             |
| `contains`    | `String`   |             |
| `notContains` | `String`   |             |
| `set`         | `Boolean`  |             |

## `OrderBy`

`asc` | `desc`

[ref-graphql-api]: /reference/core-data-apis/graphql-api

[ref-rest-api]: /reference/core-data-apis/rest-api/reference

[ref-row-limit]: /reference/core-data-apis/queries#row-limit

[ref-time-zone]: /reference/core-data-apis/queries#time-zone

[ref-ungrouped-query]: /reference/core-data-apis/queries#ungrouped-query


# Core Data APIs
Source: https://docs.cube.dev/reference/core-data-apis/index

Query the Cube semantic layer using SQL, DAX, REST (JSON), or GraphQL protocols depending on your application needs.

Core Data APIs

Core Data APIs enable you to query and retrieve data from your Cube semantic layer using various protocols and formats, including SQL, DAX, REST (JSON), and GraphQL.

## Choosing the Right API

* To connect to [Microsoft Excel][ref-excel], use [Cube for Excel][ref-cube-cloud-for-excel]

* To connect to [Google Sheets][ref-sheets], use [Cube for Sheets][ref-cube-cloud-for-sheets]

* To connect to AI assistants, use the [Model Context Protocol (MCP) server][ref-mcp-server]

* For internal or self-serve [business intelligence][cube-issbi], connect via the [SQL API][ref-sql-api]

* For [embedded analytics][cube-ea] and [real-time analytics][cube-rta], use [REST (JSON) API][ref-rest-api] or [GraphQL API][ref-graphql-api]. When using the REST (JSON) API, the [JavaScript SDK][ref-js-sdk] can simplify integration with your front-end code

All Core Data APIs share common [querying concepts][ref-queries] and support authentication, security contexts, and access policies defined in your semantic layer.

<Note>
  See this [GitHub issue](https://github.com/cube-js/cube/issues/1744#issuecomment-2291680777)
  for an unofficial, community-maintained [client library for Python](https://github.com/mharrisb1/cube-http-client).
</Note>

## Data modeling

Support for data modeling features differ across APIs, integrations, and [visualization
tools][ref-viz-tools]. Some of the features with partial support are listed below:

| Feature                                        | ✅ Supported in                                                                                                                                          |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Hierarchies][ref-hierarchies]                 | [Cube for Excel][ref-cube-cloud-for-excel]<br />[Cube for Sheets][ref-cube-cloud-for-sheets]<br /><br />Also, supported in [Playground][ref-playground] |
| Flat [folders][ref-folders]                    | [Cube for Excel][ref-cube-cloud-for-excel]<br />[Cube for Sheets][ref-cube-cloud-for-sheets]<br /><br />Also, supported in [Playground][ref-playground] |
| [Custom time formats][ref-custom-time-formats] | [Playground][ref-playground] and [Workbooks][ref-workbooks]                                                                                             |

## Personal Core Data API Token

Cube users can generate a personal token to authenticate SQL API and
[REST (JSON) API][ref-rest-api] connections from external tools like BI
dashboards, notebooks, and SQL clients. Navigate to **Preferences → Personal
Core Data API Token** and click **Generate Token**.

The token authenticates as that user, so all [groups][ref-groups],
[user attributes][ref-user-attributes], and [data access policies][ref-dap]
are applied to queries made with this token. The page also provides connection
instructions for your deployment: host, port, and database name for the SQL
API, and a sample `curl` request using the token as a bearer token for the
REST (JSON) API:

```bash theme={"dark"}
curl <deployment-url>/cubejs-api/v1/meta \
  -H "Authorization: Bearer YOUR-CORE-DATA-API-TOKEN"
```

## Authentication methods

Support for authentication methods differ across APIs, integrations, and [visualization
tools][ref-viz-tools]:

| Method                                                        | ✅ Supported in                                                                               |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [User name and password][ref-auth-user-pass]                  | [MDX API][ref-mdx-api]<br />[SQL API][ref-sql-api]                                           |
| Kerberos and NTLM                                             | [MDX API][ref-mdx-api]                                                                       |
| [Identity provider][ref-auth-idp]                             | [Cube for Excel][ref-cube-cloud-for-excel]<br />[Cube for Sheets][ref-cube-cloud-for-sheets] |
| [JSON Web Token][ref-auth-jwt]                                | [REST (JSON) API][ref-rest-api]<br />[GraphQL API][ref-graphql-api]                          |
| [Personal Core Data API Token](#personal-core-data-api-token) | [SQL API][ref-sql-api]<br />[REST (JSON) API][ref-rest-api]                                  |

[cube-issbi]: https://cube.dev/use-cases/semantic-layer

[cube-ea]: https://cube.dev/use-cases/embedded-analytics

[cube-rta]: https://cube.dev/use-cases/real-time-analytics

[ref-queries]: /reference/core-data-apis/queries

[ref-sql-api]: /reference/core-data-apis/sql-api

[ref-mdx-api]: /reference/core-data-apis/mdx-api

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-graphql-api]: /reference/core-data-apis/graphql-api

[ref-js-sdk]: /reference/javascript-sdk

[ref-cube-cloud-for-excel]: /docs/integrations/microsoft-excel

[ref-cube-cloud-for-sheets]: /docs/integrations/google-sheets

[ref-mcp-server]: /docs/integrations/mcp-server

[ref-viz-tools]: /admin/connect-to-data/visualization-tools

[ref-hierarchies]: /reference/data-modeling/hierarchies

[ref-folders]: /reference/data-modeling/view#folders

[ref-excel]: /admin/connect-to-data/visualization-tools/excel

[ref-sheets]: /admin/connect-to-data/visualization-tools/google-sheets

[ref-auth-user-pass]: /embedding/authentication/jwt

[ref-auth-idp]: /embedding/authentication/jwt

[ref-auth-jwt]: /embedding/authentication/jwt

[ref-playground]: /docs/explore-analyze/playground

[ref-custom-time-formats]: /reference/data-modeling/dimensions#format

[ref-workbooks]: /docs/explore-analyze/workbooks

[ref-groups]: /admin/users-and-permissions/user-groups

[ref-user-attributes]: /admin/users-and-permissions/user-attributes

[ref-dap]: /docs/data-modeling/data-access-policies


# Querying data APIs
Source: https://docs.cube.dev/reference/core-data-apis/queries

Cross-cutting query behavior in Cube—default ordering and limits, query kinds, and how REST (JSON), GraphQL, and SQL APIs interpret them.

After creating a [data model][ref-data-model], you would like to *ask questions
to it*, i.e., run queries against this data model. This page describes the common
concepts of querying Cube through its [data APIs][ref-apis].

All queries share the same [query defaults](#query-defaults) and each query fall
into one of [query types](#query-types).

## Query defaults

The following defaults apply to all queries run by Cube.

### Order

By default, for [REST (JSON) API][ref-rest-api] and [GraphQL API][ref-graphql-api]
queries, Cube will apply ordering to [any query](#query-types) that does not
set it explicitly. The default heuristics are to sort the result set by a time
dimension, if any; otherwise, sort it by the first measure, if any; otherwise,
sort it by the first dimension, if any. These heuristics provide a result set
that works great for most data visualization purposes. You can opt out from
default ordering by passing an empty array (`[]`) object as `order`.

[SQL API][ref-sql-api] queries do not get a default ordering in case there's no
`ORDER BY` clause in the query. You can opt in for default ordering for SQL API
queries (except for [ungrouped](#ungrouped-query) ones) by setting
`CUBESQL_SQL_NO_IMPLICIT_ORDER` to `false`.

### Row limit

By default, [any query](#query-types) that does not explicitly specify the row
limit, will return no more than 10,000 rows in the result set. You can use the
[`CUBEJS_DB_QUERY_DEFAULT_LIMIT`](/reference/configuration/environment-variables#cubejs_db_query_default_limit) environment variable to override it. This serves
as a safeguard against data scraping and denial-of-service (DoS) attacks if Cube
is exposed to untrusted environments.

The maximum allowed limit is 50,000 rows. You can use the [`CUBEJS_DB_QUERY_LIMIT`](/reference/configuration/environment-variables#cubejs_db_query_limit)
environment variable to override it. You can also implement
[pagination][ref-pagination-recipe] to fetch more rows than the maximum limit.

If you're using the [SQL API][ref-sql-api], you can enable
[streaming mode][ref-sql-api-streaming] to bypass the maximum row limit for
queries with an explicit `LIMIT` clause. Without an explicit `LIMIT`,
`CUBEJS_DB_QUERY_DEFAULT_LIMIT` still applies even in streaming mode. SQL API
queries that are not streamed can also be capped separately with
[`CUBESQL_NON_STREAMING_QUERY_MAX_ROW_LIMIT`](/reference/configuration/environment-variables#cubesql_non_streaming_query_max_row_limit).

### Time zone

All time-based calculations performed by Cube are time zone-aware.

By default, Cube assumes that time values in your queries (e.g., in date range
filters) are in the [UTC time zone][wiki-utc-time-zone]. Similarly, it will use
the same time zone for time dimension values in result sets. You can use the
[`CUBEJS_DEFAULT_TIMEZONE`](/reference/configuration/environment-variables#cubejs_default_timezone) environment variable to override it.

You can also use the `timezone` option with [REST (JSON) API][ref-rest-api-query-format-options]
or [GraphQL API][ref-ref-graphql-api-args] to specify the time zone for a query.
Also, you can use the [`SQL_UTILS` context variable][ref-sql-utils] to apply the
time zone conversion to dimensions that are not used as time dimensions in a query.

Additionally, note that time zones have impact on [pre-aggregation
matching][ref-matching-preaggs-time-dimensions].

In the Cube cloud platform, queries run from the interface, dashboards, and Analytics Chat
can resolve a time zone per account, per user, or per dashboard — see
[Time zones](/admin/time-zones).

## Query types

Most commonly, you will run [regular queries](#regular-query). See the table
and the sections below for details on each query type.

| Query type                                                | Supported by [APIs][ref-apis]                                                           | Supported in [Playground][ref-playground] |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------- |
| [Regular query](#regular-query)                           | [SQL API][ref-sql-api], [REST (JSON) API][ref-rest-api], [GraphQL API][ref-graphql-api] | ✅ Yes                                     |
| [Query with post-processing](#query-with-post-processing) | [SQL API][ref-sql-api] only                                                             | ❌ No                                      |
| [Query with pushdown](#query-with-pushdown)               | [SQL API][ref-sql-api] only                                                             | ❌ No                                      |
| [Compare date range query](#compare-date-range-query)     | [REST (JSON) API][ref-rest-api] only                                                    | ❌ No                                      |
| [Total query](#total-query)                               | [REST (JSON) API][ref-rest-api] only                                                    | ❌ No                                      |
| [Ungrouped query](#ungrouped-query)                       | [SQL API][ref-sql-api], [REST (JSON) API][ref-rest-api], [GraphQL API][ref-graphql-api] | ❌ No                                      |

### Regular query

**This is the most common type of queries.** Regular queries include:

* Lists of dimensions and measures that you'd like to see in the result set.
* Optionally, filters to apply before returning the result set.
* Optionally, a [row limit](#row-limit) and an offset for the result set.

For regular queries, Cube generates the SQL for the upstream [data
sources][ref-data-sources] that always includes all dimensions in the `GROUP BY`
statement. See [ungrouped queries](#ungrouped-query) if you'd like to override
this behavior.

Regular queries immensely benefit from [in-memory cache and
pre-aggregations][ref-caching]. They can also be modified before execution with
[`query_rewrite`][ref-query-rewrite].

#### Example

See an example of a regular query using the SQL API syntax:

```sql theme={"dark"}
SELECT
  users.state,
  users.city,
  orders.status,
  MEASURE(orders.count)
FROM orders
CROSS JOIN users
WHERE
  users.state != 'us-wa'
  AND orders.created_at BETWEEN '2020-01-01' AND '2021-01-01'
GROUP BY 1, 2, 3
LIMIT 10;
```

The same query using the REST (JSON) API syntax looks as follows:

```json theme={"dark"}
{
  "dimensions": [
    "users.state",
    "users.city",
    "orders.status"
  ],
  "measures": [
    "orders.count"
  ],
  "filters": [
    {
      "member": "users.state",
      "operator": "notEquals",
      "values": ["us-wa"]
    }
  ],
  "timeDimensions": [
    {
      "dimension": "orders.created_at",
      "dateRange": ["2020-01-01", "2021-01-01"]
    }
  ],
  "limit": 10
}
```

### Query with post-processing

**Queries with post-processing are specific to the [SQL API][ref-sql-api].**
Generally, they are structured in such a way that a [regular query](#regular-query) is
part of a `FROM` clause or a common table expression (CTE):

```sql theme={"dark"}
-- Regular query in FROM
SELECT ...
FROM (
  -- Regular query
) AS regular_query_in_from
GROUP BY ...
ORDER BY ...

-- Regular query in CTE
WITH regular_query_in_cte AS (
  -- Regular query
)
SELECT ...
FROM regular_query_in_cte
GROUP BY ...
ORDER BY ...
```

To execute the *regular query* part, Cube will generate the SQL for an upstream
[data source][ref-data-sources]. Then, Cube will do *post-processing* by
executing the rest of the query using an internal SQL execution engine.
Learn more in the [SQL API documentation][ref-sql-api-qpp].

Queries with post-processing, since they include regular queries, benefit from
[in-memory cache and pre-aggregations][ref-caching]. They can also be modified
before execution with [`query_rewrite`][ref-query-rewrite].

However, the trade-off is that queries with post-processing support only a
limited set of SQL functions and operators.

#### Example

The simplest example of a query with post-processing:

```sql theme={"dark"}
SELECT VERSION();
```

This query invokes a function that is implemented by the SQL API and executed without
querying the upstream data source.

Now, see a more complex example of a query with post-processing. In this query, we derive
new dimensions, post-aggregate measures, and perform additional filtering:

```sql theme={"dark"}
SELECT
  UPPER(SUBSTRING(state FROM 4)) AS state,
  CHAR_LENGTH(city) AS city_name_length,
  CASE WHEN status = 'completed' THEN 'done' ELSE 'pending' END AS status,
  SUM(count) AS total_count
FROM (
  SELECT
    users.state,
    users.city,
    orders.status,
    MEASURE(orders.count) AS count
  FROM orders
  CROSS JOIN users
  WHERE
    users.state != 'us-wa'
    AND orders.created_at BETWEEN '2020-01-01' AND '2021-01-01'
  GROUP BY 1, 2, 3
  LIMIT 10
) AS regular_query
GROUP BY 1, 2, 3
HAVING city_name_length > 10;
```

Let's assume that we run the query above and the following pre-aggregation
is defined:

```yaml theme={"dark"}
pre_aggregations:
  - name: main
    measures:
      - orders.count
    dimensions:
      - users.state
      - users.city
      - orders.status
    time_dimension: orders.created_at
    granularity: day
```

Cube will use this pre-aggregation, run the following SQL in Cube Store for
the regular query, and then do post-processing to produce the result set:

```sql theme={"dark"}
SELECT
  `users__state`,
  `users__city`,
  `orders__status`,
  sum(`orders__count`) `orders__count`
FROM
  prod_pre_aggregations.orders_main_s3ebmau3_mw1bchy_1j4umn8
WHERE
  (
    `users__state` <> 'us-wa'
    OR `users__state` IS NULL
  )
  AND (
    `orders__created_at_day` >= to_timestamp('2020-01-01T00:00:00.000')
    AND `orders__created_at_day` <= to_timestamp('2021-01-01T23:59:59.999')
  )
GROUP BY 1, 2, 3
ORDER BY 4 DESC
LIMIT 10;
```

### Query with pushdown

**Queries with pushdown are specific to the [SQL API][ref-sql-api].**
Unlike [queries with post-processing](#query-with-post-processing), they can
have arbitrary structure and contain pretty much any SQL functions and operators.

Thus, queries with pushdown are not reducible to [regular
queries](#regular-query) and post-processing on top of them. To execute a query
with pushdown, Cube will need to transform it and generate the SQL for an
upstream [data source][ref-data-sources].
Learn more in the [SQL API documentation][ref-sql-api-qpd].

Queries with pushdown, since they don't include regular queries, can not
utilize pre-aggregations; however, they still benefit from [in-memory
cache][ref-caching]. Queries with pushdown can also be modified before
execution with [`query_rewrite`][ref-query-rewrite]; however, only applying
additional filters is supported.

#### Example

See an example of a query with pushdown. In this query, the filter in `WHERE`
references a subquery. So, it can't be executed as a query with post-processing.
It will be executed as a query with pushdown instead:

```sql theme={"dark"}
SELECT
  users.state,
  users.city
FROM users
WHERE
  users.orders_made = (
    SELECT MAX(orders_made)
    FROM users
  )
GROUP BY 1, 2;
```

### Compare date range query

**Compare date range queries are special cases of regular queries.**
Similarly to [regular queries](#regular-query), they include lists of
dimensions and measures, filters, etc. and return a result set.

However, unlike regular queries, they provide a convenient way to retrieve
measure values for *more than one date range* for a time dimension.

You can make a compare date range query by using the `compareDateRange`
option with the [REST (JSON) API][ref-rest-api-query-format-options-tdf]. Note that
you also need to set the `queryType` parameter of the [`/v1/load`
endpoint][ref-rest-api-load] to `multi`.

#### Example

```json theme={"dark"}
{
  "dimensions": ["orders.city"],
  "measures": ["orders.amount"],
  "filters": [
    {
      "member": "orders.status",
      "operator": "equals",
      "values": ["shipped"]
    }
  ],
  "timeDimensions": [{
    "dimension": "orders.created_at",
    "compareDateRange": [
      ["2024-01-01", "2024-12-31"],
      ["2023-01-01", "2023-12-31"],
      ["2022-01-01", "2022-12-31"],
    ],
    "granularity": "year",
  }],
  "limit": 100
}
```

See [this blog post][blog-compare-date-range] for more details and examples.

For the SQL API, you can write an equivalent query using the `UNION ALL` statement.

### Total query

**Total queries are special cases of regular queries.**
Similarly to [regular queries](#regular-query), they include lists of
dimensions and measures, filters, etc. and return a result set.

In addition to that, they provide a convenient way to retrieve the total number
of rows in the result set as if no [row limit](#row-limit) or offset are set in
the query. This is useful for creating user interfaces with
[pagination][ref-pagination-recipe].

You can make a total query by using the `total` option with the [REST
API][ref-rest-api-query-format-options]. For the SQL API, you can write an
equivalent query using the `UNION ALL` statement.

### Ungrouped query

Similarly to [regular queries](#regular-query), ungrouped queries include
lists of dimensions and measures, filters, etc. and return a result set.

However, unlike for regular queries, Cube will not add the
`GROUP BY` statement when generating the SQL for an upstream data source.
Instead, raw results after filtering and joining will be returned without any
grouping. Measures will be rendered as their `sql` without any aggregation.
Time dimensions will be truncated by granularity as usual, however, not grouped by.

You can make a regular query ungrouped by using the `ungrouped` option with
[REST (JSON) API][ref-rest-api-query-format-options] or [GraphQL API][ref-ref-graphql-api-args].
For the [SQL API][ref-sql-api], you can omit the `GROUP BY` statement from the
SQL API query.

By default, for security purposes, ungrouped queries require [primary
keys][ref-primary-key] of all cubes involved in a query to be added as
dimensions. You can use the [`allow_ungrouped_without_primary_key` configration
option][ref-conf-allow-ungrouped] to override this.

Additionally, note that ungrouped queries have additional requirements for
[pre-aggregation matching][ref-matching-preaggs-ungrouped].

## Troubleshooting

### No `count` measure

You might encounter the following error when running an [ungrouped query](#ungrouped-query)
that includes `HAVING COUNT(1) > 0` (or a similar expression) against a cube or a view that
have no measure called `count`. Some BI tools are known to generate such queries.

```text theme={"dark"}
Failed to deserialize: invalid type: unit value, expected struct JoinDefinitionStatic
```

The rrot cause is that Cube needs to know how to calculate `COUNT(1)` and it expects a measure
called `count` to be defined in the cube or view. Please add one to resolve this issue.

[wiki-utc-time-zone]: https://en.wikipedia.org/wiki/Coordinated_Universal_Time

[ref-data-model]: /docs/data-modeling/overview

[ref-playground]: /docs/explore-analyze/playground

[ref-apis]: /reference

[ref-sql-api]: /reference/core-data-apis/sql-api

[ref-sql-api-qpp]: /reference/core-data-apis/sql-api/query-format#query-post-processing

[ref-sql-api-qpd]: /reference/core-data-apis/sql-api/query-format#query-pushdown

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-rest-api-load]: /reference/core-data-apis/rest-api/reference#v1load

[ref-graphql-api]: /reference/core-data-apis/graphql-api

[ref-data-sources]: /admin/connect-to-data/data-sources

[ref-rest-api-query-format-options]: /reference/core-data-apis/rest-api/query-format#query-properties

[ref-rest-api-query-format-options-tdf]: /reference/core-data-apis/rest-api/query-format#time-dimensions-format

[ref-ref-graphql-api-args]: /reference/core-data-apis/graphql-api/reference#cubequeryargs

[ref-sql-utils]: /reference/data-modeling/context-variables#sql_utils

[ref-matching-preaggs-time-dimensions]: /docs/pre-aggregations/matching-pre-aggregations#matching-time-dimensions

[ref-matching-preaggs-ungrouped]: /docs/pre-aggregations/matching-pre-aggregations#matching-ungrouped-queries

[ref-pagination-recipe]: /recipes/core-data-api/pagination

[ref-primary-key]: /reference/data-modeling/dimensions#primary_key

[ref-conf-allow-ungrouped]: /reference/configuration/config#allow_ungrouped_without_primary_key

[ref-caching]: /docs/pre-aggregations

[ref-query-rewrite]: /reference/configuration/config#query_rewrite

[blog-compare-date-range]: https://cube.dev/blog/comparing-data-over-different-time-periods

[ref-sql-api-streaming]: /reference/core-data-apis/sql-api#streaming


# REST (JSON) API
Source: https://docs.cube.dev/reference/core-data-apis/rest-api/index

Deliver data from Cube over HTTP to front-end apps, notebooks, low-code tools, and automated jobs.

REST (JSON) API

REST (JSON) API enables Cube to deliver data over the HTTP protocol to certain kinds of
data applications, including but not limited to the following ones:

* Most commonly, front-end applications
* Some [data notebooks][ref-notebooks], e.g., [Observable][ref-observable]
* [Low-code tools][ref-low-code], e.g., [Retool][ref-retool]
* Automated jobs

Often, the REST (JSON) API is used to enable [embedded analytics][cube-ea] and
[real-time analytics][cube-rta] use cases.

See [REST (JSON) API reference][ref-ref-rest-api] for the list of supported API endpoints.
Also, check [query format][ref-rest-query-format] for details about query syntax.

<Info>
  You can find a mostly complete OpenAPI documentation for the REST (JSON) API in the
  linked [`openspec.yml` file][gh-cube-openspec] that you can use with tools like Swagger.
</Info>

<Info>
  If you've chosen [GraphQL][graphql] as a query language for your front-end
  application, consider using the [GraphQL API][ref-graphql-api] that Cube also
  provides.
</Info>

REST (JSON) API also provides endpoints for [GraphQL API][ref-graphql-api] and
[Orchestration API][ref-orchestration-api]. However, they target specific use
cases and are not considered part of the REST (JSON) API.

## Transport

The REST (JSON) API supports the following transports:

| Transport | Description                                                                   | When to use                                                          |
| --------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| HTTP      | HTTP-based protocol with long polling                                         | Use by default                                                       |
| WebSocket | [WebSocket][link-websocket]-based protocol with support for real-time updates | Use for applications that require subscriptions to real-time updates |

### HTTP transport

You can use the `curl` utility to execute requests to the REST (JSON) API. Provide the [API
token](#authentication) in the `Authorization` header:

```bash theme={"dark"}
curl \
  -H "Authorization: TOKEN" \
  -G \
  --data-urlencode 'query={
    "dimensions": [
      "users.state",
      "users.city",
      "orders.status"
    ],
    "measures": [
      "orders.count"
    ],
    "filters": [
      {
        "member": "users.state",
        "operator": "notEquals",
        "values": ["us-wa"]
      }
    ],
    "timeDimensions": [
      {
        "dimension": "orders.created_at",
        "dateRange": ["2020-01-01", "2021-01-01"]
      }
    ],
    "limit": 10
  }' \
  http://localhost:4000/cubejs-api/v1/load
```

You can also use the [`jq` utility][link-jq-utility] to format responses
from the REST (JSON) API in your terminal:

```bash theme={"dark"}
curl \
  -H "Authorization: TOKEN" \
  -G \
  --data-urlencode 'query={"measures": ["orders.count"]}' \
  http://localhost:4000/cubejs-api/v1/load | jq .data
```

You can also introspect the data model by querying the [`/v1/meta`
endpoint][ref-ref-meta-endpoint]:

```bash theme={"dark"}
curl \
  -H "Authorization: TOKEN" \
  http://localhost:4000/cubejs-api/v1/meta | jq
```

You can also use the [JavaScript SDK][ref-javascript-sdk] to call the REST (JSON) API
from your JavaScript applications.

### WebSocket transport

WebSocket transport can be used to provide real-time experience. You can configure it via
the [`CUBEJS_WEB_SOCKETS`](/reference/configuration/environment-variables#cubejs_web_sockets) environment variable.

You can use the [`websocat` utility][link-websocat] to test the WebSocket transport:

```bash theme={"dark"}
websocat ws://localhost:4000/cubejs-api/v1/ws --text
```

After connecting, send the [API token](#authentication) as the first message:

```json theme={"dark"}
{"authorization":"TOKEN"}
```

Then, send requests. Each request should include a distinct `messageId`, the desired API
endpoint in `method`, and additional `params`:

```json theme={"dark"}
{"messageId":"1","method":"load","params":{"query":{"measures":["orders.count"]}}}
```

Clients using the [JavaScript SDK][ref-javascript-sdk] can be switched to WebSocket
by passing `WebSocketTransport` to the `CubeApi` constructor:

```javascript theme={"dark"}
import cube from "@cubejs-client/core"
import WebSocketTransport from "@cubejs-client/ws-transport"

const cubeApi = cube({
  transport: new WebSocketTransport({
    authorization: TOKEN,
    apiUrl: "ws://localhost:4000/"
  })
})
```

<Note>
  See [this recipe][ref-recipe-real-time-data-fetch] for an example of real-time
  data fetch using the WebSocket transport.
</Note>

## Configuration

REST (JSON) API is enabled by default and secured using [API scopes][self-api-scopes]
and [CORS][self-cors].

To find your REST (JSON) API endpoint in Cube Cloud, go to the **Overview**
page, click **API credentials**, and choose the **REST (JSON) API** tab.

### Base path

By default, all REST (JSON) API endpoints are prefixed with a base path of
`/cubejs-api`, e.g., the `/v1/load` endpoint will be available at
`/cubejs-api/v1/load`.

<Info>
  Exception: `/livez` and `/readyz` endpoints are not prefixed with a base path.
</Info>

You can set a desired base path using the [`basePath`][ref-conf-basepath]
configuration option.

### API scopes

Each REST (JSON) API endpoint belongs to an API scope, e.g., the `/v1/load` endpoint
belongs to the `data` scope. API scopes allow to secure access to API endpoints
by making them accessible to specific users only or disallowing access for
everyone. By default, API endpoints in all scopes, except for `jobs`, are
accessible for everyone.

| API scope | REST (JSON) API endpoints                                    | Accessible by default? |
| --------- | ------------------------------------------------------------ | ---------------------- |
| `meta`    | [`/v1/meta`][ref-ref-meta], [Metadata API][ref-ref-metadata] | ✅ Yes                  |
| `data`    | [`/v1/load`][ref-ref-load], [`/v1/cubesql`][ref-ref-cubesql] | ✅ Yes                  |
| `graphql` | `/graphql`                                                   | ✅ Yes                  |
| `sql`     | [`/v1/sql`][ref-ref-sql]                                     | ✅ Yes                  |
| `jobs`    | [`/v1/pre-aggregations/jobs`][ref-ref-paj]                   | ❌ No                   |
| No scope  | `/livez`, `/readyz`                                          | ✅ Yes                  |

You can set accessible API scopes *for all requests* using the
[`CUBEJS_DEFAULT_API_SCOPES`](/reference/configuration/environment-variables#cubejs_default_api_scopes) environment variable. For example, to disallow
access to the GraphQL API for everyone, set [`CUBEJS_DEFAULT_API_SCOPES`](/reference/configuration/environment-variables#cubejs_default_api_scopes) to
`meta,data`.

You can also select accessible API scopes *for each request* using the
[`contextToApiScopes`][ref-conf-contexttoapiscopes] configuration option, based
on the provided [security context][ref-security-context]. For example, to
restrict access to the `/v1/meta` endpoint to service accounts only, you can set
[`CUBEJS_DEFAULT_API_SCOPES`](/reference/configuration/environment-variables#cubejs_default_api_scopes) to `data,graphql` and use the following
configuration in the `cube.js` file, assuming that service accounts have
`service: true` in their security context:

```javascript theme={"dark"}
module.exports = {
  contextToApiScopes: (securityContext, defaultScopes) => {
    if (securityContext.service) {
      return ["meta", ...defaultScopes]
    }

    return defaultScopes
  }
}
```

### CORS

REST (JSON) API supports [Cross-Origin Resource Sharing (CORS)][mdn-cors]. By default,
requests from any origin (`*`) are allowed.

You can configure CORS using the [`http.cors`][ref-config-cors] configuration
option. For example, to allow requests from a specific domain only, use the
following configuration in the `cube.js` file:

```javascript theme={"dark"}
module.exports = {
  http: {
    cors: {
      origin: "https://example.com"
    }
  }
}
```

## Prerequisites

### Authentication

Cube uses API tokens to authorize requests and also for passing additional
security context, which can be used in the
[`queryRewrite`][ref-config-queryrewrite] property in your [`cube.js`
configuration file][ref-config-js].

The API Token is passed via the Authorization Header. The token itself is a
[JSON Web Token](https://jwt.io), the [Security section][ref-security] describes
how to generate it.

In the development environment the token is not required for authorization, but
you can still use it to pass a security context.

### Error handling

Cube REST (JSON) API has basic errors and HTTP Error codes for all requests.

| Status | Error response                 | Description                                                                                          |
| ------ | ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| 400    | Error message                  | General error. It may be a database error, timeout, or other issue. Check error message for details. |
| 403    | Authorization header isn't set | You didn't provide an auth token. Provide a valid API Token or disable authorization.                |
| 403    | Invalid token                  | The auth token provided is not valid. It may be expired or have invalid signature.                   |
| 500    | Error message                  | Cube internal server error. Check error message for details.                                         |

### Request span annotation

For monitoring tools such as Cube Cloud proper request span annotation should be
provided in `x-request-id` header of a request. Each request id should consist
of two parts: `spanId` and `requestSequenceId` which define `x-request-id` as
whole: `${spanId}-span-${requestSequenceId}`. Values of `x-request-id` header
should be unique for each separate request. `spanId` should define user
interaction span such us `Continue wait` retry cycle and it's value shouldn't
change during one single interaction.

## Cache control

[`/v1/load`][ref-ref-load] and [`/v1/cubesql`][ref-ref-cubesql] endpoints of the REST (JSON) API
allow to control the in-memory cache behavior. The following querying strategies with regards to
the cache are supported:

| Strategy                 | Description                                                                                                                                                                                                                                        |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stale-if-slow`          | If [refresh keys][ref-refresh-keys] are up-to-date, returns cached value. If expired, tries to return fresh value from the data source. If the data source query is slow (hits [`Continue wait`](#continue-wait)), returns stale value from cache. |
| `stale-while-revalidate` | If [refresh keys][ref-refresh-keys] are up-to-date, returns cached value. If expired, returns stale data from cache and updates cache in background.                                                                                               |
| `must-revalidate`        | If [refresh keys][ref-refresh-keys] are up-to-date, returns cached value. If expired, always waits for fresh value from the data source, even if slow (hits one or more [`Continue wait`](#continue-wait) intervals).                              |
| `no-cache`               | Skips [refresh key][ref-refresh-keys] checks. Always returns fresh data from the data source, regardless of cache or query performance.                                                                                                            |

## `Continue wait`

If the request takes too long to be processed, the REST (JSON) API responds with
`{ "error": "Continue wait" }` and the status code 200.

This is part of the long polling mechanism:

* After an API instance receives a request, it adds the query to the query queue.
* If the query takes too long to be processed, the API instance will respond with `Continue wait`. Receiving `Continue wait` doesn't mean the database query has been canceled, and it's actually still being processed by Cube.
* Clients who received `Continue wait` should continuously retry the same query in a loop until they get a successful result. Database queries that are no longer retried by clients will be marked as orphaned and removed from the query queue. Subsequent calls to the REST (JSON) API are idempotent and don't lead to scheduling new database queries if not required by the [`refresh_key`][ref-schema-ref-cube-refresh-key].

Possible reasons of `Continue wait`:

* The query is too heavy for the upstream database, i.e., it takes too long to be processed.
* The maximum [concurrency][ref-concurrency] is reached, i.e., there are many queries
  waiting in the query queue until the previous ones are completed.

[`continueWaitTimeout`][ref-conf-queue-opts] configuration option can be adjusted
in order to change the time Cube waits before returning `Continue wait` message.
However, it's recommended to address the root cause of the issue instead of
increasing the timeout:

* Switch from a [traditional database][ref-traditional-databases] to a [data
  warehouse][ref-data-warehouses].
* Increase the [concurrency][ref-concurrency] if your database can handle it.
* Implement [pre-aggregations][ref-pre-aggregations] to reduce the query time by using Cube Store.

[mdn-cors]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS

[ref-config-js]: /reference/configuration/config

[ref-config-queryrewrite]: /reference/configuration/config#queryrewrite

[ref-conf-queue-opts]: /reference/configuration/config#queueoptions

[ref-rest-query-format]: /reference/core-data-apis/rest-api/query-format#query-properties

[ref-ref-meta-endpoint]: /reference/core-data-apis/rest-api/reference#base_path/v1/meta

[ref-config-cors]: /reference/configuration/config#http

[ref-schema-ref-cube-refresh-key]: /reference/data-modeling/cube#refresh_key

[ref-security]: /docs/data-modeling/access-control

[ref-notebooks]: /admin/connect-to-data/visualization-tools#notebooks

[ref-observable]: /admin/connect-to-data/visualization-tools/observable

[ref-low-code]: /admin/connect-to-data/visualization-tools#low-code-tools-internal-tool-builders

[ref-retool]: /admin/connect-to-data/visualization-tools/retool

[ref-conf-basepath]: /reference/configuration/config#basepath

[ref-conf-contexttoapiscopes]: /reference/configuration/config#contexttoapiscopes

[ref-ref-load]: /reference/core-data-apis/rest-api/reference#base_path/v1/load

[ref-ref-meta]: /reference/core-data-apis/rest-api/reference#base_path/v1/meta

[ref-ref-sql]: /reference/core-data-apis/rest-api/reference#base_path/v1/sql

[ref-ref-cubesql]: /reference/core-data-apis/rest-api/reference#base_path/v1/cubesql

[ref-ref-paj]: /reference/core-data-apis/rest-api/reference#base_path/v1/pre-aggregations/jobs

[ref-security-context]: /docs/data-modeling/access-control/context

[ref-graphql-api]: /reference/core-data-apis/graphql-api

[ref-orchestration-api]: /reference/orchestration-api

[cube-ea]: https://cube.dev/use-cases/embedded-analytics

[cube-rta]: https://cube.dev/use-cases/real-time-analytics

[graphql]: https://graphql.org

[self-api-scopes]: #configuration-api-scopes

[self-cors]: #configuration-cors

[ref-ref-rest-api]: /reference/core-data-apis/rest-api/reference

[link-jq-utility]: https://jqlang.github.io/jq/

[gh-cube-openspec]: https://github.com/cube-js/cube/blob/master/packages/cubejs-api-gateway/openspec.yml

[link-websocket]: https://en.wikipedia.org/wiki/WebSocket

[ref-concurrency]: /admin/connect-to-data/concurrency

[ref-data-warehouses]: /admin/connect-to-data/data-sources#data-warehouses

[ref-traditional-databases]: /admin/connect-to-data/data-sources#transactional-databases

[ref-pre-aggregations]: /docs/pre-aggregations/using-pre-aggregations

[ref-javascript-sdk]: /reference/javascript-sdk

[ref-recipe-real-time-data-fetch]: /recipes/core-data-api/real-time-data-fetch

[ref-refresh-keys]: /reference/data-modeling/cube#refresh_key

[link-websocat]: https://github.com/vi/websocat

[ref-ref-metadata]: /reference/core-data-apis/rest-api/reference#metadata-api


# Query format in the REST (JSON) API
Source: https://docs.cube.dev/reference/core-data-apis/rest-api/query-format

Field-by-field guide to the REST (JSON) API `/load` query JSON, including members, filters, time dimensions, limits, totals, and data blending arrays.

Queries to the REST (JSON) API are plain JavaScript objects, describing an analytics
query. The basic elements of a query (query members) are `measures`, `dimensions`,
and `segments`.

The query member format name is `cube_name.member_name`, for example the `email`
dimension in the `users` cube would have the `users.email` name.

In the case of a dimension of the `time` type, a granularity could be optionally
added to the name, in the following format: `cube_name.time_dimension_name.granularity_name`,
e.g., `stories.time.week`. It can be one of the [default granularities][ref-default-granularities]
(e.g., `year` or `week`) or a [custom granularity][ref-custom-granularities].

The Cube client also accepts an array of queries. By default, it will be treated
as a Data Blending query type.

## Query Properties

A Query has the following properties:

* `measures`: An array of measures.
* `dimensions`: An array of dimensions.
* `filters`: An array of objects, describing filters. Learn about
  [filters format](#filters-format).
* `timeDimensions`: A convenient way to specify a time dimension with a filter.
  It is an array of objects in [timeDimension format.](#time-dimensions-format)
* `segments`: An array of segments. A segment is a named filter, created in the
  data model.
* `limit`: A [row limit][ref-row-limit] for your query.
* `total`: If set to `true`, Cube will run a [total query][ref-total-query] and
  return the total number of rows as if no row limit or offset are set in the query.
  The default value is `false`.
* `offset`: The number of initial rows to be skipped for your query. The default
  value is `0`.
* `order`: An object, where the keys are measures or dimensions to order by and
  their corresponding values are either `asc` or `desc`. For [time dimensions][ref-default-granularities],
  a granularity can be optionally provided, e.g., `orders.created_at.month`.
  The order of the fields to order on is based on the order of the keys in the object.
  If not provided, the [default ordering][ref-default-order] is applied.
  If an empty object (`[]`) is provided, no ordering is applied.
* `timezone`: A [time zone][ref-time-zone] for your query. You can set the
  desired time zone in the [TZ Database Name](https://en.wikipedia.org/wiki/Tz_database)
  format, e.g., `America/Los_Angeles`.
* `ungrouped`: If set to `true`, Cube will run an [ungrouped
  query][ref-ungrouped-query].
* `joinHints`: Query-time [join hints][ref-join-hints], provided as an array of
  two-element arrays of cube names.

```json theme={"dark"}
{
  "measures": ["stories.count"],
  "dimensions": ["stories.category"],
  "filters": [
    {
      "member": "stories.isDraft",
      "operator": "equals",
      "values": ["No"]
    }
  ],
  "timeDimensions": [
    {
      "dimension": "stories.time",
      "dateRange": ["2015-01-01", "2015-12-31"],
      "granularity": "month"
    }
  ],
  "limit": 100,
  "offset": 50,
  "order": {
    "stories.time": "asc",
    "stories.count": "desc"
  },
  "timezone": "America/Los_Angeles"
}
```

### Default order

If the `order` property is not specified in the query, Cube sorts results by
default using the following rules:

* The first time dimension with a granularity, ascending. If no time dimension
  with a granularity exists...
* The first measure, descending. If no measure exists...
* The first dimension, ascending.

### Alternative order format

Also you can control the ordering of the `order` specification, Cube support
alternative order format - array of tuples:

```json theme={"dark"}
{
  "order": [
      ["stories.time", "asc"],
      ["stories.count", "asc"]
    ]
  }
}
```

## Filters Format

A filter is a JavaScript object with the following properties:

* `member`: Dimension or measure to be used in the filter, for example:
  `stories.isDraft`. See below on difference between filtering dimensions vs
  filtering measures.
* `operator`: An operator to be used in the filter. Only some operators are
  available for measures. For dimensions the available operators depend on the
  type of the dimension. Please see the reference below for the full list of
  available operators.
* `values`: An array of values for the filter. Values must be of type String. If
  you need to pass a date, pass it as a string in `YYYY-MM-DD` format.

### Filtering Dimensions vs Filtering Measures

Filters are applied differently to dimensions and measures.

When you filter on a dimension, you are restricting the raw data before any
calculations are made. When you filter on a measure, you are restricting the
results after the measure has been calculated.

## Filters Operators

Only some operators are available for measures. For dimensions, the available
operators depend on the
[type of the dimension](/reference/data-modeling/dimensions#type).

### `equals`

Use it when you need an exact match. It supports multiple values.

* Applied to measures.
* Dimension types: `string`, `number`, `time`.

```json theme={"dark"}
{
  "member": "users.country",
  "operator": "equals",
  "values": ["US", "Germany", "Israel"]
}
```

<Info>
  If you would like to check if a value is `NULL`, use the [`notSet`](#notset)
  operator instead.
</Info>

### `notEquals`

The opposite operator of `equals`. It supports multiple values.

* Applied to measures.
* Dimension types: `string`, `number`, `time`.

```json theme={"dark"}
{
  "member": "users.country",
  "operator": "notEquals",
  "values": ["France"]
}
```

<Info>
  If you would like to check if a value is not `NULL`, use the [`set`](#set)
  operator instead.
</Info>

### `contains`

The `contains` filter acts as a wildcard case-insensitive `LIKE` operator. In
the majority of SQL backends it uses `ILIKE` operator with values being
surrounded by `%`. It supports multiple values.

* Dimension types: `string`.

```json theme={"dark"}
{
  "member": "posts.title",
  "operator": "contains",
  "values": ["serverless", "aws"]
}
```

### `notContains`

The opposite operator of `contains`. It supports multiple values.

* Dimension types: `string`.

```json theme={"dark"}
{
  "member": "posts.title",
  "operator": "notContains",
  "values": ["ruby"]
}
```

This operator adds `IS NULL` check to include `NULL` values unless you add
`null` to `values`. For example:

```json theme={"dark"}
{
  "member": "posts.title",
  "operator": "notContains",
  "values": ["ruby", null]
}
```

### `startsWith`

The `startsWith` filter acts as a case-insensitive `LIKE` operator with a
wildcard at the end. In the majority of SQL backends, it uses the `ILIKE`
operator with `%` at the end of each value. It supports multiple values.

* Dimension types: `string`.

```json theme={"dark"}
{
  "member": "posts.title",
  "operator": "startsWith",
  "values": ["ruby"]
}
```

### `notStartsWith`

The opposite operator of `startsWith`.

### `endsWith`

The `endsWith` filter acts as a case-insensitive `LIKE` operator with a wildcard
at the beginning. In the majority of SQL backends, it uses the `ILIKE` operator with
`%` at the beginning of each value. It supports multiple values.

* Dimension types: `string`.

```json theme={"dark"}
{
  "member": "posts.title",
  "operator": "endsWith",
  "values": ["ruby"]
}
```

### `notEndsWith`

The opposite operator of `endsWith`.

### `gt`

The `gt` operator means **greater than** and is used with measures or dimensions
of type `number`.

* Applied to measures.
* Dimension types: `number`.

```json theme={"dark"}
{
  "member": "posts.upvotes_count",
  "operator": "gt",
  "values": ["100"]
}
```

### `gte`

The `gte` operator means **greater than or equal to** and is used with measures
or dimensions of type `number`.

* Applied to measures.
* Dimension types: `number`.

```json theme={"dark"}
{
  "member": "posts.upvotes_count",
  "operator": "gte",
  "values": ["100"]
}
```

### `lt`

The `lt` operator means **less than** and is used with measures or dimensions of
type `number`.

* Applied to measures.
* Dimension types: `number`.

```json theme={"dark"}
{
  "member": "posts.upvotes_count",
  "operator": "lt",
  "values": ["10"]
}
```

### `lte`

The `lte` operator means **less than or equal to** and is used with measures or
dimensions of type `number`.

* Applied to measures.
* Dimension types: `number`.

```json theme={"dark"}
{
  "member": "posts.upvotes_count",
  "operator": "lte",
  "values": ["10"]
}
```

### `set`

Operator `set` checks whether the value of the member **is not** `NULL`. You
don't need to pass `values` for this operator.

* Applied to measures.
* Dimension types: `number`, `string`, `time`.

```json theme={"dark"}
{
  "member": "posts.author_name",
  "operator": "set"
}
```

### `notSet`

An opposite to the `set` operator. It checks whether the value of the member
**is** `NULL`. You don't need to pass `values` for this operator.

* Applied to measures.
* Dimension types: `number`, `string`, `time`.

```json theme={"dark"}
{
  "member": "posts.author_name",
  "operator": "notSet"
}
```

### `inDateRange`

<Warning>
  From a pre-aggregation standpoint, `inDateRange` filter is applied as a generic
  filter. All pre-aggregation granularity matching rules aren't applied in this
  case. It feels like pre-aggregation isn't matched. However, pre-aggregation is
  just missing the filtered time dimension in
  [dimensions][ref-schema-ref-preaggs-dimensions] list. If you want date range
  filter to match [timeDimension][ref-schema-ref-preaggs-time-dimension] please
  use [timeDimensions](#time-dimensions-format) `dateRange` instead.
</Warning>

The operator `inDateRange` is used to filter a time dimension into a specific
date range. The values must be an array of timestamps in the [ISO 8601][wiki-iso-8601]
format, for example `2025-01-02` or `2025-01-02T03:04:05.067Z`. If only one timestamp
is specified, the filter would be set exactly to this timestamp.

You may also pass a single-element array containing a [relative date range
string][ref-relative-date-range] (for example, `["last 2 weeks"]`), using the
same formats supported by `timeDimensions.dateRange`. Cube resolves the string
to an absolute `[start, end]` range using the query timezone before generating
SQL. This applies to every date operator on this page.

There is a convenient way to use date filters with grouping -
[learn more about the `timeDimensions` property here](#time-dimensions-format)

* Dimension types: `time`.

```json theme={"dark"}
{
  "member": "posts.time",
  "operator": "inDateRange",
  "values": ["2015-01-01", "2015-12-31"]
}
```

```json theme={"dark"}
{
  "member": "posts.time",
  "operator": "inDateRange",
  "values": ["last 2 weeks"]
}
```

### `notInDateRange`

<Warning>
  From a pre-aggregation standpoint, `notInDateRange` filter is applied as a
  generic filter. All pre-aggregation granularity matching rules aren't applied in
  this case. It feels like pre-aggregation isn't matched. However, pre-aggregation
  is just missing the filtered time dimension in
  [dimensions][ref-schema-ref-preaggs-dimensions] list.
</Warning>

An opposite operator to `inDateRange`, use it when you want to exclude specific
timestamps. The values must be in the same format as for [`inDateRange`](#indaterange).

* Dimension types: `time`.

```json theme={"dark"}
{
  "member": "posts.time",
  "operator": "notInDateRange",
  "values": ["2015-01-01", "2015-12-31"]
}
```

### `beforeDate`

<Warning>
  From a pre-aggregation standpoint, `beforeDate` filter is applied as a generic
  filter. All pre-aggregation granularity matching rules aren't applied in this
  case. It feels like pre-aggregation isn't matched. However, pre-aggregation is
  just missing the filtered time dimension in
  [dimensions][ref-schema-ref-preaggs-dimensions] list.
</Warning>

Use it when you want to retrieve all results before some specific timestamp. The
values should be an array of one element in the same format as for [`inDateRange`](#indaterange).

* Dimension types: `time`.

```json theme={"dark"}
{
  "member": "posts.time",
  "operator": "beforeDate",
  "values": ["2015-01-01"]
}
```

### `beforeOrOnDate`

<Warning>
  From a pre-aggregation standpoint, `beforeOrOnDate` filter is applied as a generic
  filter. All pre-aggregation granularity matching rules aren't applied in this
  case. It feels like pre-aggregation isn't matched. However, pre-aggregation is
  just missing the filtered time dimension in
  [dimensions][ref-schema-ref-preaggs-dimensions] list.
</Warning>

Use it when you want to retrieve all results before or on a specific timestamp. The
values should be an array of one element in the same format as for [`inDateRange`](#indaterange).

* Dimension types: `time`.

```json theme={"dark"}
{
  "member": "posts.time",
  "operator": "beforeOrOnDate",
  "values": ["2015-01-01"]
}
```

### `afterDate`

<Warning>
  From a pre-aggregation standpoint, `afterDate` filter is applied as a generic
  filter. All pre-aggregation granularity matching rules aren't applied in this
  case. It feels like pre-aggregation isn't matched. However, pre-aggregation is
  just missing the filtered time dimension in
  [dimensions][ref-schema-ref-preaggs-dimensions] list.
</Warning>

The same as `beforeDate`, but is used to get all results after a specific timestamp.
The values should be an array of one element in the same format as for [`inDateRange`](#indaterange).

* Dimension types: `time`.

```json theme={"dark"}
{
  "member": "posts.time",
  "operator": "afterDate",
  "values": ["2015-01-01"]
}
```

### `afterOrOnDate`

<Warning>
  From a pre-aggregation standpoint, `afterOrOnDate` filter is applied as a generic
  filter. All pre-aggregation granularity matching rules aren't applied in this
  case. It feels like pre-aggregation isn't matched. However, pre-aggregation is
  just missing the filtered time dimension in
  [dimensions][ref-schema-ref-preaggs-dimensions] list.
</Warning>

The same as `beforeOrOnDate`, but is used to get all results after or on a specific timestamp.
The values should be an array of one element in the same format as for [`inDateRange`](#indaterange).

* Dimension types: `time`.

```json theme={"dark"}
{
  "member": "posts.time",
  "operator": "afterOrOnDate",
  "values": ["2015-01-01"]
}
```

### `measureFilter`

The `measureFilter` operator is used to apply an existing measure's filters to
the current query.

This usually happens when you call
[`ResultSet.drilldown()`][ref-client-core-resultset-drilldown], which will
return a query for the drill members. If the original query has a filter on a
measure, that filter will be added as otherwise the drilldown query will lose
that context. Not supported by pre-aggregations.

* Applied to measures.

```json theme={"dark"}
{
  "member": "Orders.count",
  "operator": "measureFilter"
}
```

## Boolean logical operators

Filters can contain `or` and `and` logical operators. Logical operators have
only one of the following properties:

* `or` An array with one or more filters or other logical operators
* `and` An array with one or more filters or other logical operators

```json theme={"dark"}
{
  "or": [
    {
      "member": "visitors.source",
      "operator": "equals",
      "values": ["some"]
    },
    {
      "and": [
        {
          "member": "visitors.source",
          "operator": "equals",
          "values": ["other"]
        },
        {
          "member": "visitor_checkins.cards_count",
          "operator": "equals",
          "values": ["0"]
        }
      ]
    }
  ]
}
```

**You can not put dimensions and measures filters in the same logical operator.**
When Cube generates a SQL query to the data source, dimension and measure filters
are translated to expressions in `WHERE` and `HAVING` clauses, respectively.\
In other words, dimension filters apply to raw (unaggregated) data and measure filters
apply to aggregated data, so it's not possible to express such filters in SQL semantics.

### Date filters in logical operators

Date operators (`inDateRange`, `notInDateRange`, `beforeDate`, `beforeOrOnDate`,
`afterDate`, `afterOrOnDate`, `onTheDate`) can be placed inside `or`/`and`
logical operators. The date predicate is emitted inside the corresponding
logical group, so you can express date constraints that apply to only one
branch of an `or`:

```json theme={"dark"}
{
  "filters": [{
    "or": [
      {
        "member": "Orders.createdAt",
        "operator": "inDateRange",
        "values": ["last 2 weeks"]
      },
      {
        "member": "Orders.status",
        "operator": "equals",
        "values": ["pending"]
      }
    ]
  }]
}
```

The resulting SQL has the date predicate inside the `OR`, not as a global `AND`:

```sql theme={"dark"}
WHERE (created_at >= ... AND created_at <= ...)
   OR (status = 'pending')
```

<Warning>
  This differs from [`timeDimensions.dateRange`](#time-dimensions-format), which
  is always emitted as a global `AND` at the top of the `WHERE` clause and also
  drives granularity and pre-aggregation matching. Use a `filters` entry when
  you need the date constraint scoped to one branch of an `or`/`and` group;
  use `timeDimensions.dateRange` when you need a global date constraint that
  can match pre-aggregations.

  If you set both `timeDimensions.dateRange` and a date filter in `filters` on
  the same member, both predicates are emitted and `AND`-ed together — the
  `timeDimensions` range constrains the entire query, including every branch
  of any `or` group. This is rarely the intended behavior; prefer one path
  or the other.
</Warning>

## Time Dimensions Format

Since grouping and filtering by a time dimension is quite a common case, Cube
provides a convenient shortcut to pass a dimension and a filter as a
`timeDimension` property.

* `dimension`: Time dimension name.
* `dateRange`: An array of dates with the following format `YYYY-MM-DD` or in
  `YYYY-MM-DDTHH:mm:ss.SSS` format. Values should always be local and in query
  `timezone`. Dates in `YYYY-MM-DD` format are also accepted. Such dates are
  padded to the start and end of the day if used in start and end of date range
  interval accordingly. Please note that for timestamp comparison, `>=` and `<=`
  operators are used. It requires, for example, that the end date range date
  `2020-01-01` is padded to `2020-01-01T23:59:59.999`. If only one date is
  specified it's equivalent to passing two of the same dates as a date range.
  You can also pass a string with a [relative date
  range][ref-relative-date-range], for example, `last quarter`.
* `compareDateRange`: An array of date ranges to compare measure values. See
  [compare date range queries][ref-compare-date-range] for details.
* `granularity`: A granularity for a time dimension. It can be one of the [default
  granularities][ref-default-granularities] (e.g., `year` or `week`) or a [custom
  granularity][ref-custom-granularities].
  If you don't provide a granularity, Cube will only perform filtering by a
  specified time dimension, without grouping.

```json theme={"dark"}
{
  "measures": ["stories.count"],
  "timeDimensions": [
    {
      "dimension": "stories.time",
      "dateRange": ["2015-01-01", "2015-12-31"],
      "granularity": "month"
    }
  ]
}
```

You can use [compare date range queries][ref-compare-date-range] when you want
to see, for example, how a metric performed over a period in the past and how it
performs now. You can pass two or more date ranges where each of them is in the
same format as a `dateRange`:

```javascript theme={"dark"}
// ...
const resultSet = await cubeApi.load({
  measures: ["stories.count"],
  timeDimensions: [
    {
      dimension: "stories.time",
      compareDateRange: ["this week", ["2020-05-21", "2020-05-28"]],
      granularity: "month"
    }
  ]
})
```

### Relative date range

You can also use a string with a relative date range in the `dateRange`
property, for example:

```json theme={"dark"}
{
  "measures": ["stories.count"],
  "timeDimensions": [
    {
      "dimension": "stories.time",
      "dateRange": "last week",
      "granularity": "day"
    }
  ]
}
```

Some of supported formats:

* `today`, `yesterday`, or `tomorrow`
* `last year`, `last quarter`, or `last 360 days`
* `next month` or `last 6 months` (current date not included)
* `from 7 days ago to now` or `from now to 2 weeks from now` (current date
  included)

<Info>
  Cube uses the [Chrono][chrono-website] library to parse relative dates. Please
  refer to its documentation for more examples.
</Info>

The same relative-date strings are accepted in the `values` array of date
filter operators (`inDateRange`, `notInDateRange`, `beforeDate`, etc.) when
the array contains a single string. See [`inDateRange`](#indaterange) and
[Date filters in logical operators](#date-filters-in-logical-operators).

[ref-client-core-resultset-drilldown]: /reference/javascript-sdk/reference/cubejs-client-core#drilldown

[ref-schema-ref-preaggs-dimensions]: /reference/data-modeling/pre-aggregations#dimensions

[ref-schema-ref-preaggs-time-dimension]: /reference/data-modeling/pre-aggregations#time_dimension

[ref-relative-date-range]: #relative-date-range

[chrono-website]: https://github.com/wanasit/chrono

[ref-row-limit]: /reference/core-data-apis/queries#row-limit

[ref-time-zone]: /reference/core-data-apis/queries#time-zone

[ref-compare-date-range]: /reference/core-data-apis/queries#compare-date-range-query

[ref-total-query]: /reference/core-data-apis/queries#total-query

[ref-ungrouped-query]: /reference/core-data-apis/queries#ungrouped-query

[ref-default-order]: /reference/core-data-apis/queries#order

[ref-default-granularities]: /docs/data-modeling/dimensions#time-dimensions

[ref-custom-granularities]: /reference/data-modeling/dimensions#granularities

[wiki-iso-8601]: https://en.wikipedia.org/wiki/ISO_8601

[ref-join-hints]: /docs/data-modeling/joins#join-hints


# REST (JSON) API reference
Source: https://docs.cube.dev/reference/core-data-apis/rest-api/reference

The REST (JSON) API provides the following endpoints.

<Info>
  The `{base_path}` part of the endpoint URLs can be [configured][ref-basepath].
  By default, it's `/cubejs-api`.
</Info>

## `{base_path}/v1/load`

Run the query to the REST (JSON) API and get the results.

| Parameter        | Description                                                                                                                                                                                                                                                | Required |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `query`          | Either a single URL encoded Cube [Query](/reference/core-data-apis/rest-api/query-format), or an array of queries                                                                                                                                          | ✅ Yes    |
| `queryType`      | If multiple queries are passed in `query` for [data blending][ref-recipes-data-blending], this must be set to `multi`                                                                                                                                      | ❌ No     |
| `cache`          | See [cache control][ref-cache-control]. `stale-if-slow` by default                                                                                                                                                                                         | ❌ No     |
| `responseFormat` | Output format of the result `data` payload: `default` (row-oriented), `compact` (a `{ members, dataset }` object with rows of primitive arrays), or `columnar` (a `{ members, columns }` object with one primitive array per member). `default` by default | ❌ No     |

### Headers

| Header          | Description                                                                                                                                                                                                                            | Required |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `Authorization` | API token for authentication                                                                                                                                                                                                           | ✅ Yes    |
| `x-request-id`  | Custom request identifier. When provided, this ID is used to track the query through the system and can be used to [cancel the query](#base_path/v1/running-query/requestid). If not provided, a unique ID is generated automatically. | ❌ No     |

Response

* `query` - The query passed via params. It can be an array of queries and in
  such case it will be treated as a [Data Blending][ref-recipes-data-blending]
  query.
* `data` - Formatted dataset of query results.
* `annotation` - Metadata for query. Contains descriptions for all query items.
  * `title` - Human readable title from the data model.
  * `shortTitle` - Short title for visualization usage (ex. chart overlay)
  * `type` - Data type
* `lastRefreshTime` - An ISO 8601 timestamp indicating when the data was last refreshed.
* `external` - A boolean indicating whether the query was served from a
  pre-aggregation in Cube Store.
* `usedPreAggregations` - The pre-aggregations this result was served from, keyed
  by pre-aggregation table name. Each entry carries `preAggregationId` (the name in
  the data model, e.g. `Orders.main`, stable across rebuilds), `lastUpdatedAt` and
  `type`. Absent when the query hit no pre-aggregation.

  A `rollupJoin` or `rollupLambda` pre-aggregation is reported as the rollups it
  references, not as itself, because that is what the query actually reads. Look
  for those rollups rather than for the joining or lambda pre-aggregation.

  <Note>
    These fields name your pre-aggregations and are returned to every API consumer -
    including browsers holding a public embedding token. Fields that describe
    storage layout or query results stay behind
    [`CUBEJS_DEV_MODE`](/reference/configuration/environment-variables#cubejs_dev_mode)
    (a local-development-only setting that bypasses authentication)
    and the Playground: `targetTableName` (the physical table of one specific build,
    version hashes included) and `refreshKeyValues`.
  </Note>
* `total` - The total number of rows returned for the query. Useful for
  paginating results.

Example request:

```bash theme={"dark"}
# Request with http method GET
curl \
  -H "Authorization: TOKEN" \
  -G \
  --data-urlencode 'query={"measures":["users.count"]}' \
  http://localhost:4000/cubejs-api/v1/load

# Request with http method POST
# Use POST to fix problem with query length limits
curl \
 -X POST  \
 -H "Content-Type: application/json" \
 -H "Authorization: TOKEN" \
 --data '{"query": {"measures":["users.count"]}}' \
 http://localhost:4000/cubejs-api/v1/load
```

Example response:

```json theme={"dark"}
{
  "query": {
    "measures": ["users.count"],
    "filters": [],
    "timezone": "UTC",
    "dimensions": [],
    "timeDimensions": []
  },
  "data": [
    {
      "users.count": "700"
    }
  ],
  "lastRefreshTime": "2025-01-13T12:00:00.000Z",
  "annotation": {
    "measures": {
      "users.count": {
        "title": "Users Count",
        "shortTitle": "Count",
        "type": "number"
      }
    },
    "dimensions": {},
    "segments": {},
    "timeDimensions": {}
  }
}
```

<Warning>
  Currently all fetched numericals are returned in the same format as driver
  returns it without any additional processing. Most of drivers return numerical
  values as strings instead of javascript integer or float to ensure there's no
  loss of significance. Client code should take care of parsing such numerical
  values.
</Warning>

## `{base_path}/v1/sql`

Takes an API query and returns the SQL query that can be executed against the data source
that is generated by Cube. This endpoint is useful for debugging, understanding how
Cube translates API queries into SQL queries, and providing transparency to SQL-savvy
end users.

Using this endpoint to take the SQL query and execute it against the data source directly
is not recommended  as it bypasses Cube's caching layer and other optimizations.

Request parameters:

| Parameter, type                      | Description                                                                                                                    | Required |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | -------- |
| `format`, `string`                   | Query format:<br />`sql` for [SQL API][ref-sql-api] queries,<br />`rest` for [REST (JSON) API][ref-rest-api] queries (default) | ❌ No     |
| `query`, `string`                    | Query as an URL-encoded JSON object or SQL query                                                                               | ✅ Yes    |
| `disable_post_processing`, `boolean` | Flag that affects query planning, `true` or `false`                                                                            | ❌ No     |

If `disable_post_processing` is set to `true`, Cube will try to generate the SQL
as if the query is run without [post-processing][ref-query-wpp], i.e., if it's run as a
query with [pushdown][ref-query-wpd].

The response will contain a JSON object with the following properties under the `sql` key:

| Property, type                             | Description                                                                |
| ------------------------------------------ | -------------------------------------------------------------------------- |
| `status`, `string`                         | Query planning status, `ok` or `error`                                     |
| `sql`, `array`                             | Two-element array (see below)                                              |
| `sql[0]`, `string`                         | Generated query with parameter placeholders                                |
| `sql[1]`, <nobr>`array` or `object`</nobr> | Generated query parameters                                                 |
| `dataSource`, `string`                     | The name of the [data source][ref-datasources] the generated query targets |

For queries with the `sql` format, the response will also include the following additional
properties under the `sql` key:

| Property, type         | Description                                                                                                                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `query_type`, `string` | `regular` for [regular][ref-regular-queries] queries,<br />`post_processing` for queries with [post-processing][ref-query-wpp],<br />`pushdown` for queries with [pushdown][ref-query-wpd] |

For queries with the `sql` format, in case of an error, the response will only contain
`status`, `query_type`, and `error` properties.

For example, an error will be returned if `disable_post_processing` was set to `true` but
the query can't be run without post-processing.

### Example

Request with a query in the REST (JSON) API format:

```bash theme={"dark"}
curl \
  -H "Authorization: TOKEN" \
  -G \
  --data-urlencode 'query={"measures":["orders.count"]}' \
  --data-urlencode 'format=rest'  \
  http://localhost:4000/cubejs-api/v1/sql
```

Response:

```json theme={"dark"}
{
  "sql": {
    "sql": [
      "SELECT sum(`base_orders__count`) `orders__count` FROM prod_pre_aggregations.base_orders_orders_by_month AS `base_orders__orders_by_month`  LIMIT 10000",
      []
    ]
  }
}
```

Request with a query in the SQL API format:

```bash theme={"dark"}
curl \
  -H "Authorization: TOKEN" \
  -G \
  --data-urlencode 'query=SELECT COUNT(*) FROM orders' \
  --data-urlencode 'format=sql'  \  
  http://localhost:4000/cubejs-api/v1/sql
```

Response:

```json theme={"dark"}
{
  "sql": {
    "status": "ok",
    "sql": [
      "SELECT\n      count(\"base_orders\".id) \"count_uint8_1__\"\n    FROM\n      (SELECT * FROM 's3://cube-tutorial/orders.csv') AS \"base_orders\"  LIMIT 50000",
      []
    ],
    "query_type": "regular"
  }
}
```

Request with a query in the SQL API format that is executed with post-processing:

```bash theme={"dark"}
curl \
  -H "Authorization: TOKEN" \
  -G \
  --data-urlencode 'query=SELECT AVG(count) FROM (SELECT COUNT(*) AS count FROM orders) AS table' \
  --data-urlencode 'format=sql'  \ 
  http://localhost:4000/cubejs-api/v1/sql
```

Response:

```json theme={"dark"}
{
  "sql": {
    "status": "error",
    "error": "Provided query can not be executed without post-processing.",
    "query_type": "post_processing"
  }
}
```

Request with a query in the SQL API format that is forced to be executed without
post-processing, i.e., as a query with pushdown:

```bash theme={"dark"}
curl \
  -H "Authorization: TOKEN" \
  -G \
  --data-urlencode 'query=SELECT AVG(count) FROM (SELECT COUNT(*) AS count FROM orders) AS table' \
  --data-urlencode 'format=sql' \
  --data-urlencode 'disable_post_processing=true'  \
  http://localhost:4000/cubejs-api/v1/sql
```

Response:

```json theme={"dark"}
{
  "sql": {
    "status": "ok",
    "sql": [
      "SELECT \"table\".\"avg_table_count_\" \"avg_table_count_\" \nFROM (\n  SELECT AVG(\"table\".\"count\") \"avg_table_count_\" \n  FROM (\n    SELECT\n          count(\"base_orders\".id) \"count\"\n        FROM\n          (SELECT * FROM 's3://cube-tutorial/orders.csv') AS \"base_orders\" \n  ) AS \"table\"\n) AS \"table\"\nLIMIT 50000",
      []
    ],
    "query_type": "pushdown"
  }
}
```

## `{base_path}/v1/convert-query`

Takes an API query in the specified input format and converts it to the specified
output format. Currently, only conversion from [SQL API](/reference/core-data-apis/sql-api) queries to
[REST (JSON) API](/reference/core-data-apis/rest-api) queries is supported.

This endpoint is useful for translating SQL API queries into equivalent REST (JSON) API
queries that can be used with the [`/v1/load`](#base_path%2Fv1%2Fload) endpoint.

Request parameters (JSON body):

| Parameter, type    | Description                                                                                       | Required |
| ------------------ | ------------------------------------------------------------------------------------------------- | -------- |
| `input`, `string`  | Input query format. Use `sql` for [SQL API](/reference/core-data-apis/sql-api) queries            | ✅ Yes    |
| `output`, `string` | Output query format. Use `rest` for [REST (JSON) API](/reference/core-data-apis/rest-api) queries | ✅ Yes    |
| `query`, `string`  | Input query in the specified format                                                               | ✅ Yes    |

The response will contain a JSON object with the following properties:

| Property, type     | Description                                                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`, `string` | Query conversion status, `ok` or `error`                                                                                                    |
| `query`, `object`  | Converted query in the [REST (JSON) API query format](/reference/core-data-apis/rest-api/query-format) (only present when `status` is `ok`) |
| `error`, `string`  | Error message (only present when `status` is `error`)                                                                                       |

An error will be returned if the input query can't be converted to the specified
output format, e.g., if the SQL API query requires post-processing on top of
REST (JSON) API capabilities or if the SQL API query results in multiple REST (JSON) API queries.

### Example

Request to convert a SQL API query with a filter:

```bash theme={"dark"}
curl \
  -X POST \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": "sql", "output": "rest", "query": "SELECT MEASURE(total_amount) FROM orders WHERE status = '\''foo'\''"}' \
  http://localhost:4000/cubejs-api/v1/convert-query
```

Successful response:

```json theme={"dark"}
{
  "status": "ok",
  "query": {
    "measures": [
      "orders.total_amount"
    ],
    "dimensions": [],
    "filters": [
      {
        "member": "orders.status",
        "operator": "equals",
        "values": ["foo"]
      }
    ],
    "segments": [],
    "order": []
  }
}
```

## `{base_path}/v1/meta`

<Info>
  In Cube Cloud, consider using the [Metadata API][self-metadata-api] instead.
  It provides additional information such as data lineage.
</Info>

Get meta-information for cubes and views defined in the data model. Information about cubes and views with `public: false` will not be returned.

Response

* `cubes` - Array of cubes and views
  * `name` - Codename of the cube/view
  * `type` - Type can be "cube" or "view"
  * `title` - Human-readable cube/view name
  * `meta` - Custom metadata
  * `measures` - Array of measures in this cube/view
  * `dimensions` - Array of dimensions in this cube/view
  * `hierarchies` - Array of hierarchies in this cube
  * `segments` - Array of segments in this cube/view
  * `folders` and `nestedFolders` - Arrays of flat and nested [folder][ref-folders] structures in this view, respectively
  * `connectedComponent` - An integer representing a join relationship. If the same value is returned for two cubes, then there is
    at least one join path between them.

Example request:

```bash theme={"dark"}
curl \
  -H "Authorization: TOKEN" \
  -G \
  http://localhost:4000/cubejs-api/v1/meta
```

Example response:

```json theme={"dark"}
{
  "cubes": [
    {
      "name": "Users",
      "title": "Users",
      "meta": {
          "someKey": "someValue",
          "nested": {
            "someKey": "someValue"
          }
      },
      "connectedComponent": 1,
      "measures": [
        {
          "name": "users.count",
          "title": "Users Count",
          "shortTitle": "Count",
          "aliasName": "users.count",
          "type": "number",
          "aggType": "count",
          "drillMembers": ["users.id", "users.city", "users.createdAt"]
        }
      ],
      "dimensions": [
        {
          "name": "users.city",
          "title": "Users City",
          "type": "string",
          "aliasName": "users.city",
          "shortTitle": "City",
          "suggestFilterValues": true
        }
      ],
      "segments": []
    }
  ]
}
```

## `{base_path}/v1/cubesql`

Run the query to the SQL API and get the results.

<Info>
  This endpoint is part of the [SQL API][ref-sql-api].
</Info>

| Parameter  | Description                                                                                                            | Required |
| ---------- | ---------------------------------------------------------------------------------------------------------------------- | -------- |
| `query`    | The SQL query to run                                                                                                   | ✅ Yes    |
| `timezone` | The [time zone][ref-time-zone] for this query in the [TZ Database Name][link-tzdb] format, e.g., `America/Los_Angeles` | ❌ No     |
| `cache`    | See [cache control][ref-cache-control]. `stale-if-slow` by default                                                     | ❌ No     |

### Headers

| Header          | Description                                                                                                                                                                                                                            | Required |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `Authorization` | API token for authentication                                                                                                                                                                                                           | ✅ Yes    |
| `x-request-id`  | Custom request identifier. When provided, this ID is used to track the query through the system and can be used to [cancel the query](#base_path/v1/running-query/requestid). If not provided, a unique ID is generated automatically. | ❌ No     |

Response: a stream of newline-delimited JSON objects. The first object contains
the `schema` property with column names and types, optionally
`lastRefreshTime` indicating when the data was last refreshed, and optionally
`usedPreAggregations` naming the pre-aggregations the result was served from
(same shape as in the [JSON query](#base_path/v1/load) response). Neither field is
reported for queries served in [streaming mode](/reference/core-data-apis/sql-api#streaming),
which records no result metadata.
The following objects contain chunks of the result set under the `data` property.
Each chunk includes one or more rows of the result set; the maximum number of rows
per chunk is set by
[`CUBESQL_CUBE_SCAN_MAX_BATCH_ROWS`](/reference/configuration/environment-variables#cubesql_cube_scan_max_batch_rows).

### Example

Simple request:

```bash theme={"dark"}
curl \
  -X POST \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT 123 AS value UNION ALL SELECT 456 AS value UNION ALL SELECT 789 AS value"}' \
  http://localhost:4000/cubejs-api/v1/cubesql
```

Response:

```json theme={"dark"}
{"schema":[{"name":"value","column_type":"Int64"}],"lastRefreshTime":"2025-01-13T12:00:00.000Z"}
{"data":[["789"]]}
{"data":[["123"]]}
{"data":[["456"]]}
```

Simple request with a query that returns multiple columns:

```bash theme={"dark"}
curl \
  -X POST \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT full_name, MEASURE(results_race_wins) AS wins, MEASURE(results_average_race_position) AS avg_position FROM session_results GROUP BY 1 ORDER BY 3 LIMIT 5"}' \
  http://localhost:4000/cubejs-api/v1/cubesql
```

Response:

```json theme={"dark"}
{"schema":[{"name":"full_name","column_type":"String"},{"name":"wins","column_type":"Int64"},{"name":"avg_position","column_type":"Double"}],"lastRefreshTime":"2025-01-13T12:00:00.000Z"}
{"data":[["Max VERSTAPPEN","10","3.730769230769231"],["Lando NORRIS","4","4"],["Charles LECLERC","4","4.730769230769231"],["Oscar PIASTRI","3","4.8076923076923075"],["Andrea Kimi ANTONELLI","0","5"]]}
```

## `{base_path}/v1/running-query/{requestId}`

Cancel a running query by its request ID. This endpoint cancels any in-flight
queries matching the given request ID across all query queues.

The request ID can be obtained from the `x-request-id` header sent with
the original query request to endpoints like
[`/v1/load`](#base_path/v1/load) or [`/v1/cubesql`](#base_path/v1/cubesql).

| Parameter   | Description                                                | Required |
| ----------- | ---------------------------------------------------------- | -------- |
| `requestId` | The request ID of the query to cancel (URL path parameter) | ✅ Yes    |

Response:

* `result` — an array of cancelled query definitions. Empty array if no
  matching queries were found in the queue.

### Example

Cancel a query:

```bash theme={"dark"}
curl \
  -X DELETE \
  -H "Authorization: TOKEN" \
  http://localhost:4000/cubejs-api/v1/running-query/my-request-id-span-1
```

Example response when a query was cancelled:

```json theme={"dark"}
{
  "result": [
    {
      "queryHandler": "query",
      "queryKey": "...",
      "requestId": "my-request-id-span-1"
    }
  ]
}
```

Example response when no matching query was found:

```json theme={"dark"}
{
  "result": []
}
```

## `{base_path}/v1/pre-aggregations/jobs`

Trigger pre-aggregation build jobs or retrieve statuses of such jobs.

<Info>
  This endpoint is part of the [Orchestration API][ref-orchestration-api].
</Info>

### Triggering jobs

| Parameter                  | Description                                                    | Required |
| -------------------------- | -------------------------------------------------------------- | -------- |
| `action`                   | Use `post` to trigger jobs                                     | ✅        |
| `selector.contexts`        | Array of objects, each containing a `securityContext`          | ✅        |
| `selector.timezones`       | Array of timezones                                             | ✅        |
| `selector.dataSources`     | Array of data source names which have pre-aggregations defined | ❌        |
| `selector.cubes`           | Array of cube names which contain pre-aggregations             | ❌        |
| `selector.preAggregations` | Array of pre-aggregation names                                 | ❌        |
| `selector.dateRange`       | Date Range tuple \['range-date-start', 'range-date-end']       | ❌        |

To trigger pre-aggregation builds, send a `POST` request with a payload
including `post` as the `action` and `selector` properties. The response will
contain an array of `tokens` (identifiers) of triggered jobs.

Example request triggering builds of all pre-aggregations defined in all cubes
using an empty security context and a `UTC` timezone:

```bash theme={"dark"}
curl \
  -d '{
    "action": "post",
    "selector": {
      "contexts": [{ "securityContext": {} }],
      "timezones": ["UTC"]
    }
  }' \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  https://localhost:4000/cubejs-api/v1/pre-aggregations/jobs
```

Example request triggering builds of all pre-aggregations defined in the
`orders` cube using an empty security context and a `UTC` timezone:

```bash theme={"dark"}
curl \
  -d '{
    "action": "post",
    "selector": {
      "contexts": [{ "securityContext": {} }],
      "timezones": ["UTC"],
      "cubes": ["orders"]
    }
  }' \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  https://localhost:4000/cubejs-api/v1/pre-aggregations/jobs
```

Example request triggering builds of the `main` pre-aggregation defined in the
`orders` cube using an empty security context and a `UTC` timezone:

```bash theme={"dark"}
curl \
  -d '{
    "action": "post",
    "selector": {
      "contexts": [{ "securityContext": {} }],
      "timezones": ["UTC"],
      "preAggregations": ["orders.main"]
    }
  }' \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  https://localhost:4000/cubejs-api/v1/pre-aggregations/jobs
```

Example request triggering builds of the `main` pre-aggregation defined in the
`orders` cube within date range with some security context data
and an `America/Los_Angeles` timezone:

```bash theme={"dark"}
curl \
  -d '{
    "action": "post",
    "selector": {
      "contexts": [{ "securityContext": { "tenantId": "tenant1" } }],
      "timezones": ["America/Los_Angeles"],
      "preAggregations": ["orders.main"],
      "dateRange": ["2020-01-01", "2020-02-01"]
    }
  }' \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  https://localhost:4000/cubejs-api/v1/pre-aggregations/jobs
```

Example response:

```json theme={"dark"}
[
  "e9a6a0c55885cea5371348500ce7d7dc",
  "d1329b6c8d152e734fc4dcf7307b1b58",
  "6f4ea38373663fffc4334a576574845b",
  "ea903b10634b2f3141b35a2529870e89"
]
```

### Retrieving statuses of jobs

| Parameter | Description                                                       | Required |
| --------- | ----------------------------------------------------------------- | -------- |
| `action`  | Use `get` to retrieve statuses of previously triggered jobs       | ✅        |
| `tokens`  | Array of `tokens` returned when triggering jobs                   | ✅        |
| `resType` | Use `object` to get a JSON object instead of an array in response | ❌        |

To retrieve statuses of previously triggered jobs, send a `POST` request with a
payload including the `tokens` property.

In the `status` property of the payload, you can get the following statuses:

| Status              | Description                        |
| ------------------- | ---------------------------------- |
| `scheduled`         | The job hasn't run yet             |
| `processing`        | The job is currently running       |
| `missing_partition` | The job has failed                 |
| `done`              | The job has successfully completed |

Example request:

```bash theme={"dark"}
curl \
  -d '{
    "action": "get",
    "tokens": [
      "e9a6a0c55885cea5371348500ce7d7dc",
      "d1329b6c8d152e734fc4dcf7307b1b58"
    ]
  }' \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  https://localhost:4000/cubejs-api/v1/pre-aggregations/jobs
```

Example response:

```json theme={"dark"}
[
  {
    "token": "e9a6a0c55885cea5371348500ce7d7dc",
    "table": "prod_pre_aggregations.orders_category_and_date_hod0x3hf_03krd5ns_1hop3hn",
    "status": "processing",
    "selector": {
      "cubes": ["orders"],
      "preAggregations": ["orders.category_and_date"],
      "contexts": [{ "securityContext": { "tenant": "tenant_1" } }],
      "timezones": ["UTC"],
      "dataSources": ["default"]
    }
  },
  {
    "token": "d1329b6c8d152e734fc4dcf7307b1b58",
    "table": "prod_pre_aggregations.orders_category_and_date_mzfp445f_r2h2isa5_1hop3hn",
    "status": "processing",
    "selector": {
      "cubes": ["orders"],
      "preAggregations": ["orders.category_and_date"],
      "contexts": [{ "securityContext": { "tenant": "tenant_1" } }],
      "timezones": ["UTC"],
      "dataSources": ["default"]
    }
  }
]
```

## Metadata API

<Info>
  Metadata API is only available in Cube Cloud.
</Info>

These endpoints provide programmatic access to data model metadata for data
catalogs, lineage tools, and other integrations. To access these endpoints,
you need a JWT token which can be obtained via the
[Control Plane API][ref-control-plane-api].

### `{base_path}/v1/data-sources`

Send a `GET` request to list configured data sources visible to the authenticated user.

Example request:

```bash theme={"dark"}
curl \
  -H "Authorization: Bearer TOKEN" \
  https://example.cubecloud.dev/cubejs-api/v1/data-sources
```

Example response:

```json theme={"dark"}
{
  "data": {
    "data_sources": [
      {
        "name": "default",
        "type": "postgres",
        "database": "analytics",
        "schema": "public"
      }
    ]
  }
}
```

### `{base_path}/v1/entities`

Send a `GET` request to list all cubes and views in the data model. Results are
sorted by type (cubes first), then by name. Each item contains only `type` and
`name`; use [`/v1/entities/{name}`](#base_path/v1/entities/name) or
[`/v1/entities/all`](#base_path/v1/entities/all) for detailed metadata.

Query parameters:

| Parameter | Description                                              | Required |
| --------- | -------------------------------------------------------- | -------- |
| `offset`  | Pagination offset. Defaults to `0`                       | No       |
| `limit`   | Maximum number of items to return. Defaults to all items | No       |

Example request:

```bash theme={"dark"}
curl \
  -H "Authorization: Bearer TOKEN" \
  "https://example.cubecloud.dev/cubejs-api/v1/entities?limit=10"
```

Example response. `data` is an array of entities; `pagination` reports the
total number of entities before `offset` and `limit` are applied:

```json theme={"dark"}
{
  "data": [
    {
      "type": "cube",
      "name": "orders"
    },
    {
      "type": "view",
      "name": "orders_view"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 2
  }
}
```

### `{base_path}/v1/entities/{name}`

Send a `GET` request to get detailed metadata for a single cube or view.

Path parameters:

| Parameter | Description           |
| --------- | --------------------- |
| `name`    | The cube or view name |

Response includes:

* `type` - Either `cube` or `view`
* `name` - The cube or view name
* `title` - Human-readable title
* `description` - Description from the data model, or an empty string
* `table_references` - Data lineage to source tables, each with `data_source`,
  `table`, and, if the table is qualified, `schema`
* `cube_references` - Relationships to other cubes, each as an object with
  `type` (currently always `upstream`) and `cube`
* `measures` and `dimensions` - Arrays of members, sorted by name

Each member includes:

| Field               | Description                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------- |
| `name`              | The member name, without the cube prefix                                                             |
| `title`             | Human-readable title                                                                                 |
| `description`       | Description from the data model, or an empty string                                                  |
| `type`              | The member type, e.g. `count`, `sum`, or `string`                                                    |
| `sql`               | The member's SQL definition (see below). Omitted when it can't be resolved                           |
| `is_primary_key`    | Whether the dimension is a primary key. Dimensions only                                              |
| `member_references` | Upstream members the member is derived from, each with `cube` and `member`                           |
| `column_references` | Source columns, each with `data_source`, `table`, `column`, and, if the table is qualified, `schema` |

`sql` is the member's SQL expression as written in the data model, with any
enclosing quotes removed — for example `COUNT(*)`, `${CUBE}.status`, or
`${total_amount} - ${refunds}`. References to other members appear as `${member}`
interpolations, and `${CUBE}` refers to the cube's own table alias. Members of a
view carry the alias expression they resolve to, e.g. `${orders.total_amount}`.

Example request:

```bash theme={"dark"}
curl \
  -H "Authorization: Bearer TOKEN" \
  https://example.cubecloud.dev/cubejs-api/v1/entities/orders
```

Example response:

```json theme={"dark"}
{
  "data": {
    "type": "cube",
    "name": "orders",
    "title": "Orders",
    "description": "Order transactions",
    "table_references": [
      {
        "data_source": "default",
        "schema": "public",
        "table": "orders"
      }
    ],
    "cube_references": [],
    "measures": [
      {
        "name": "total_amount",
        "title": "Total Amount",
        "description": "",
        "type": "sum",
        "sql": "${CUBE}.amount",
        "member_references": [],
        "column_references": [
          {
            "data_source": "default",
            "schema": "public",
            "table": "orders",
            "column": "amount"
          }
        ]
      }
    ],
    "dimensions": [
      {
        "name": "id",
        "title": "Id",
        "description": "",
        "type": "number",
        "sql": "${CUBE}.id",
        "is_primary_key": true,
        "member_references": [],
        "column_references": [
          {
            "data_source": "default",
            "schema": "public",
            "table": "orders",
            "column": "id"
          }
        ]
      },
      {
        "name": "status",
        "title": "Status",
        "description": "",
        "type": "string",
        "sql": "${CUBE}.status",
        "is_primary_key": false,
        "member_references": [],
        "column_references": [
          {
            "data_source": "default",
            "schema": "public",
            "table": "orders",
            "column": "status"
          }
        ]
      }
    ]
  }
}
```

### `{base_path}/v1/entities/all`

Send a `POST` request to get detailed metadata for multiple cubes and views in one request.

Request body:

| Property | Type    | Description                     | Required |
| -------- | ------- | ------------------------------- | -------- |
| `cubes`  | `array` | Array of cube names to retrieve | No       |
| `views`  | `array` | Array of view names to retrieve | No       |

Query parameters:

| Parameter | Description                                              | Required |
| --------- | -------------------------------------------------------- | -------- |
| `offset`  | Pagination offset. Defaults to `0`                       | No       |
| `limit`   | Maximum number of items to return. Defaults to all items | No       |

If neither `cubes` nor `views` is provided, all cubes and views are returned.

Example request:

```bash theme={"dark"}
curl \
  -X POST \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cubes": ["orders"], "views": ["orders_view"]}' \
  https://example.cubecloud.dev/cubejs-api/v1/entities/all
```

Example response. `data` is an array of entities, each in the same format as the
single-entity response above; `pagination` reports the total number of matching
entities before `offset` and `limit` are applied:

```json theme={"dark"}
{
  "data": [
    {
      "type": "cube",
      "name": "orders",
      "title": "Orders",
      "description": "Order transactions",
      "table_references": [
        {
          "data_source": "default",
          "schema": "public",
          "table": "orders"
        }
      ],
      "cube_references": [],
      "measures": [
        {
          "name": "total_amount",
          "title": "Total Amount",
          "description": "",
          "type": "sum",
          "sql": "${CUBE}.amount",
          "member_references": [],
          "column_references": [
            {
              "data_source": "default",
              "schema": "public",
              "table": "orders",
              "column": "amount"
            }
          ]
        }
      ],
      "dimensions": [
        {
          "name": "id",
          "title": "Id",
          "description": "",
          "type": "number",
          "sql": "${CUBE}.id",
          "is_primary_key": true,
          "member_references": [],
          "column_references": [
            {
              "data_source": "default",
              "schema": "public",
              "table": "orders",
              "column": "id"
            }
          ]
        },
        {
          "name": "status",
          "title": "Status",
          "description": "",
          "type": "string",
          "sql": "${CUBE}.status",
          "is_primary_key": false,
          "member_references": [],
          "column_references": [
            {
              "data_source": "default",
              "schema": "public",
              "table": "orders",
              "column": "status"
            }
          ]
        }
      ]
    },
    {
      "type": "view",
      "name": "orders_view",
      "title": "Orders View",
      "description": "",
      "table_references": [
        {
          "data_source": "default",
          "schema": "public",
          "table": "orders"
        }
      ],
      "cube_references": [
        { "type": "upstream", "cube": "orders" }
      ],
      "measures": [
        {
          "name": "total_amount",
          "title": "Total Amount",
          "description": "",
          "type": "sum",
          "sql": "${orders.total_amount}",
          "member_references": [
            { "cube": "orders", "member": "total_amount" }
          ],
          "column_references": [
            {
              "data_source": "default",
              "schema": "public",
              "table": "orders",
              "column": "amount"
            }
          ]
        }
      ],
      "dimensions": [
        {
          "name": "status",
          "title": "Status",
          "description": "",
          "type": "string",
          "sql": "${orders.status}",
          "is_primary_key": false,
          "member_references": [
            { "cube": "orders", "member": "status" }
          ],
          "column_references": [
            {
              "data_source": "default",
              "schema": "public",
              "table": "orders",
              "column": "status"
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 2,
    "total": 2
  }
}
```

## Health checks

### `/readyz`

Reports if the deployment has successfully started. To do so, it will try to test
the connection to the *default* [data source][ref-datasources].

Example of a successful request:

```bash theme={"dark"}
curl -i http://localhost:4000/readyz
HTTP/1.1 200 OK
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"health":"HEALTH"}
```

Example of a failed response:

```bash theme={"dark"}
curl -i http://localhost:4000/readyz
HTTP/1.1 500 Internal Server Error
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"health":"DOWN"}
```

### `/livez`

Reports if the deployment is still healthy. This is confirmed by testing any
existing connections to data sources.

Example of a successful response:

```bash theme={"dark"}
curl -i http://localhost:4000/livez
HTTP/1.1 200 OK
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"health":"HEALTH"}
```

Example of a failed response:

```bash theme={"dark"}
curl -i http://localhost:4000/livez
HTTP/1.1 500 Internal Server Error
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"health":"DOWN"}
```

[ref-recipes-data-blending]: /docs/data-modeling/concepts/data-blending#data-blending

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-basepath]: /reference/core-data-apis/rest-api#base-path

[ref-datasources]: /admin/connect-to-data/multiple-data-sources

[ref-sql-api]: /reference/core-data-apis/sql-api

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-regular-queries]: /reference/core-data-apis/queries#regular-query

[ref-query-wpp]: /reference/core-data-apis/queries#query-with-post-processing

[ref-query-wpd]: /reference/core-data-apis/queries#query-with-pushdown

[ref-sql-api]: /reference/core-data-apis/sql-api

[ref-orchestration-api]: /reference/orchestration-api

[ref-folders]: /reference/data-modeling/view#folders

[ref-cache-control]: /reference/core-data-apis/rest-api#cache-control

[ref-time-zone]: /reference/core-data-apis/queries#time-zone

[link-tzdb]: https://en.wikipedia.org/wiki/Tz_database

[ref-control-plane-api]: /reference/control-plane-api

[self-metadata-api]: #metadata-api


# Cube Core
Source: https://docs.cube.dev/reference/core-data-apis/sql-api/index

Connect any Postgres-compatible client or BI tool to Cube using the Postgres-protocol SQL API.

SQL API

The SQL API enables Cube to deliver data over the [Postgres-compatible
protocol][postgres-protocol] to a wide range of [data visualization tools][ref-dataviz-tools].
In general, if an application connects to [PostgreSQL][link-postgres] database,
it can connect to Cube as well.

See [SQL API reference][ref-ref-sql-api] for the list of supported SQL commands,
functions, and operators. Also, check [query format][ref-sql-query-format] for
details about supported queries.

## Transport

The SQL API supports the following transports:

| Transport | Description                                                                  | When to use                                                                                                          |
| --------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Postgres  | Same protocol that is used by the `psql` utility and other Postgres clients  | Use by default                                                                                                       |
| HTTP      | JSON-based protocol that is also used by the [REST (JSON) API][ref-rest-api] | Use when you need to run a SQL API query from an embedded analytics application and REST (JSON) API is not an option |

### Postgres protocol

You can use the [`psql` utility][link-psql] to connect to the SQL API:

```bash theme={"dark"}
# Cube Core
PGPASSWORD=password \
  psql -h localhost \
  -p 15432 \
  -U user cube
```

```bash theme={"dark"}
# Cube Cloud
PGPASSWORD=password \
  psql -h awesome-ecom.sql.gcp-us-central1.cubecloudapp.dev \
  -p 5432 \
  -U cube awesome-ecom
```

Then, you can run queries in the Postgres dialect, just like the following one:

```sql theme={"dark"}
SELECT
  users.state,
  users.city,
  orders.status,
  MEASURE(orders.count)
FROM orders
CROSS JOIN users
WHERE
  users.state != 'us-wa'
  AND orders.created_at BETWEEN '2020-01-01' AND '2021-01-01'
GROUP BY 1, 2, 3
LIMIT 10;
```

You can also introspect the data model in a Postgres-native way by querying [tables
in `information_schema`][link-postgres-information-schema] or using [backslash
commands][link-postgres-backslash-commands]:

```sql theme={"dark"}
SELECT *
FROM information_schema.tables
WHERE table_schema = 'public';
```

```sql theme={"dark"}
\d
```

### HTTP protocol

You can use the `curl` utility to run a SQL API query over the HTTP protocol:

```bash theme={"dark"}
curl \
  -X POST \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT 123 AS value UNION ALL SELECT 456 AS value UNION ALL SELECT 789 AS value"}' \
  http://localhost:4000/cubejs-api/v1/cubesql
```

See the [`/v1/cubesql` endpoint][ref-rest-api-cubesql] reference for more details.

## Fundamentals

In the SQL API, each cube or view from the [data model][ref-data-model-concepts]
is represented as a table. Measures, dimensions, and segments are represented as
columns in these tables. SQL API can execute [regular queries][ref-regular-queries],
[queries with post-processing][ref-queries-wpp], and [queries with
pushdown][ref-queries-wpd] that can reference these tables and columns.

Under the hood, the SQL API uses [Apache DataFusion][link-datafusion] as
its query engine. It's responsible for query planning and execution.
As part of query planning, the SQL API also uses [egg][link-egg] (an [e-graph term
rewriting][link-egraphs] library) to analyze incoming SQL queries and find the best
query plan out of a wide variety of possible plans to execute.

<Frame>
  <img />
</Frame>

Overall, query planning is a seamless process.
SQL API does its best to execute a query as a [regular query][ref-regular-queries]
or a [query with post-processing][ref-queries-wpp]. If that is not possible,
then the query would be executed as a [query with pushdown][ref-queries-wpd].
There are trade-offs associated with each query type:

| Query type                                      | In-memory cache | Pre-aggregations | SQL support     |
| ----------------------------------------------- | --------------- | ---------------- | --------------- |
| [Regular queries][ref-regular-queries]          | ✅ Used          | ✅ Used           | 🟡 Very limited |
| [Queries with post-processing][ref-queries-wpp] | ✅ Used          | ✅ Used           | 🟡 Limited      |
| [Queries with pushdown][ref-queries-wpd]        | ✅ Used          | ❌ Not used       | ✅ Extensive     |

<Info>
  [Read more](https://cube.dev/blog/query-push-down-in-cubes-semantic-layer) about Query pushdown in the SQL API in the blog.
</Info>

## Configuration

### Cube Core

**SQL API is disabled by default.** To enable the SQL API, set [`CUBEJS_PG_SQL_PORT`](/reference/configuration/environment-variables#cubejs_pg_sql_port)
to a port number you'd like to connect to with a Postgres-compatible tool.

| Credential | Environment variable, etc.                                                                          |
| :--------- | :-------------------------------------------------------------------------------------------------- |
| Host       | Host you're running Cube at                                                                         |
| Port       | Set via [`CUBEJS_PG_SQL_PORT`](/reference/configuration/environment-variables#cubejs_pg_sql_port)   |
| User name  | Set via [`CUBEJS_SQL_USER`](/reference/configuration/environment-variables#cubejs_sql_user)         |
| Password   | Set via [`CUBEJS_SQL_PASSWORD`](/reference/configuration/environment-variables#cubejs_sql_password) |
| Database   | Any valid string, e.g., `cube`                                                                      |

You can also use
[`checkSqlAuth`][ref-config-checksqlauth],
[`canSwitchSqlUser`][ref-config-canswitchsqluser], and [`CUBEJS_SQL_SUPER_USER`](/reference/configuration/environment-variables#cubejs_sql_super_user)
to configure [custom authentication][ref-sql-api-auth].

#### Example

The following Docker Compose file will run Cube with the SQL API enabled on
port 15432, accessible using `user` as the user name, `password` as the password,
and any string as the database name:

```yamltitle="docker-compose.yml" theme={"dark"}
services:
  cube:
    image: cubejs/cube:latest
    ports:
      - 4000:4000
      - 15432:15432
    environment:
      - CUBEJS_DEV_MODE=true
      - CUBEJS_API_SECRET=SECRET

      - CUBEJS_DB_USER=cube
      - CUBEJS_DB_PASS=12345
      - CUBEJS_DB_HOST=demo-db-examples.cube.dev
      - CUBEJS_DB_NAME=ecom
      - CUBEJS_DB_TYPE=postgres

      - CUBEJS_PG_SQL_PORT=15432      # SQL API credential
      - CUBEJS_SQL_USER=user          # SQL API credential
      - CUBEJS_SQL_PASSWORD=password  # SQL API credential
    volumes:
      - .:/cube/conf
```

After running it with `docker compose up`, you can finally connect and execute
an [example request](#transport).

<Warning>
  Development mode is an authentication bypass. Cube is in development mode when
  `CUBEJS_DEV_MODE=true` — which, under the `cubejs` CLI and the official Docker images,
  also forces `NODE_ENV=development` and so switches off JWT verification on the
  REST (JSON) and GraphQL APIs — and whenever `NODE_ENV` is not
  `production`. Playground's endpoints are served with no authentication too: anyone who
  can reach the instance is handed a ready-to-use API token, can mint others carrying any
  security context, can read your data model files, and can overwrite your data model and
  your `.env`. With `CUBEJS_DEV_MODE=true` and no
  [`CUBEJS_SQL_PASSWORD`](/reference/configuration/environment-variables#cubejs_sql_password)
  set, the SQL API accepts any credentials as well, allowing arbitrary SQL against
  connected data sources. Use it only on a local development machine, never in
  production. See
  [`CUBEJS_DEV_MODE`](/reference/configuration/environment-variables#cubejs_dev_mode).
</Warning>

### Cube Cloud

**SQL API is enabled by default.** To find your SQL API endpoint and credentials
in Cube Cloud, go to the **Overview** page, click **API credentials**,
and choose the **SQL API** tab.

By default, the SQL API is enabled on port 5432, the user name is `cube`, and
a random  string is generated for the password. You can customize these with
[`CUBEJS_PG_SQL_PORT`](/reference/configuration/environment-variables#cubejs_pg_sql_port), [`CUBEJS_SQL_USER`](/reference/configuration/environment-variables#cubejs_sql_user), and [`CUBEJS_SQL_PASSWORD`](/reference/configuration/environment-variables#cubejs_sql_password) environment
variables by navigating to **Settings → Configration**.

### Query planning

The SQL API executes queries as [regular queries][ref-regular-queries], [queries with
post-processing][ref-queries-wpp], or [queries with pushdown][ref-queries-wpd].

### Streaming

By default, query results are loaded in a single batch. However, a more effective
*streaming mode* can be used for large result sets. To enable it, set the
[`CUBESQL_STREAM_MODE`](/reference/configuration/environment-variables#cubesql_stream_mode)
environment variable to `true`.

<Info>
  When the streaming mode is enabled, the maximum [row limit][ref-queries-row-limit]
  does not apply to SQL API queries with an explicit `LIMIT` clause. This means
  you can use a very large `LIMIT` value to retrieve large result sets.

  If a query does not include an explicit `LIMIT` clause,
  [`CUBEJS_DB_QUERY_DEFAULT_LIMIT`](/reference/configuration/environment-variables#cubejs_db_query_default_limit)
  still applies even in streaming mode. To retrieve large result sets without an
  explicit `LIMIT`, increase `CUBEJS_DB_QUERY_DEFAULT_LIMIT` as needed.
</Info>

Queries that are not streamed are capped by
[`CUBESQL_NON_STREAMING_QUERY_MAX_ROW_LIMIT`](/reference/configuration/environment-variables#cubesql_non_streaming_query_max_row_limit),
which defaults to the value of `CUBEJS_DB_QUERY_LIMIT`. It also acts as the threshold
above which a query is streamed rather than loaded in a single batch.

### Session limit

Each concurrent connection to the SQL API consumes some resources and attempting
to establish too many connections at once can lead to an out-of-memory crash.
You can use the [`CUBEJS_MAX_SESSIONS`](/reference/configuration/environment-variables#cubejs_max_sessions) environment variable to adjust the session
limit.

## Cache control

You can use the `cube_cache` session variable with the [`SET` command][ref-set-command]
to control [in-memory cache][ref-caching] behavior.
It works the same way as [cache control in the REST (JSON) API][ref-rest-cache-control].

Example:

```sql theme={"dark"}
SET cube_cache = 'must-revalidate';
```

## Troubleshooting

### `Can't find rewrite`

[Query planning](#query-planning) is a resource-intensive task, and sometimes you can get the following
error: `Error during rewrite: Can't find rewrite due to 10002 AST node limit reached.`
Use the following environment variables to allocate more resources for query planning:
`CUBESQL_REWRITE_MAX_NODES`, `CUBESQL_REWRITE_MAX_ITERATIONS`, `CUBESQL_REWRITE_TIMEOUT`.

[link-postgres]: https://www.postgresql.org

[ref-mdx-api]: /reference/core-data-apis/mdx-api

[ref-sql-api-auth]: /reference/core-data-apis/sql-api/security

[ref-config-checksqlauth]: /reference/configuration/config#checksqlauth

[ref-config-canswitchsqluser]: /reference/configuration/config#canswitchsqluser

[ref-dataviz-tools]: /admin/connect-to-data/visualization-tools

[ref-bi]: /admin/connect-to-data/visualization-tools#bi-data-exploration-tools

[ref-thoughtspot]: /admin/connect-to-data/visualization-tools/thoughtspot

[ref-sigma]: /admin/connect-to-data/visualization-tools/sigma

[ref-looker-studio]: /admin/connect-to-data/visualization-tools/looker-studio

[ref-notebooks]: /admin/connect-to-data/visualization-tools#notebooks

[ref-jupyter]: /admin/connect-to-data/visualization-tools/jupyter

[ref-hex]: /admin/connect-to-data/visualization-tools/hex

[ref-deepnote]: /admin/connect-to-data/visualization-tools/deepnote

[ref-sql-query-format]: /reference/core-data-apis/sql-api/query-format

[ref-ref-sql-api]: /reference/core-data-apis/sql-api/reference

[ref-data-model-concepts]: /docs/data-modeling/overview

[ref-regular-queries]: /reference/core-data-apis/queries#regular-query

[ref-queries-wpp]: /reference/core-data-apis/queries#query-with-post-processing

[ref-queries-wpd]: /reference/core-data-apis/queries#query-with-pushdown

[ref-ungrouped-queries]: /reference/core-data-apis/queries#ungrouped-query

[link-datafusion]: https://arrow.apache.org/datafusion/

[link-egg]: https://github.com/egraphs-good/egg

[link-egraphs]: https://docs.rs/egg/latest/egg/tutorials/_01_background/index.html

[link-psql]: https://www.postgresql.org/docs/current/app-psql.html

[link-postgres-information-schema]: https://www.postgresql.org/docs/16/information-schema.html

[link-postgres-backslash-commands]: https://www.postgresql.org/docs/current/app-psql.html#APP-PSQL-META-COMMANDS

[postgres-protocol]: https://www.postgresql.org/docs/current/protocol.html

[cube-bi-use-case]: https://cube.dev/use-cases/connected-bi

[ref-queries-row-limit]: /reference/core-data-apis/queries#row-limit

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-rest-api-cubesql]: /reference/core-data-apis/rest-api/reference#base_path/v1/cubesql

[ref-caching]: /docs/pre-aggregations

[ref-rest-cache-control]: /reference/core-data-apis/rest-api#cache-control

[ref-set-command]: /reference/core-data-apis/sql-api/reference#set


# Joins in the SQL API
Source: https://docs.cube.dev/reference/core-data-apis/sql-api/joins

The best practice is to use views to specify explicit join paths for SQL API queries.

## Views

The best practice is to use [views][ref-views] to specify explicit [join
paths][ref-join-paths] for SQL API queries.

While BI tools would see a view as a table, in fact, no materialization is performed
until Cube is queried through the SQL API. At the query time, Cube will try to maximize
member pushdown, so only required parts of the view are materialized at query time.

Cube also solves fan and chasm traps based on the dimensions selected in the query, so
if measure aggregation types are properly set up, you will see correct results in BI tools
even though cubes and views are seen just as tables.

Consider the following data model:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: orders_users
      cubes:
        - join_path: orders
          includes:
            - status
            - count

        - join_path: orders.users
          prefix: true
          includes: 
            - id
            - city
            - state
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`orders_users`, {
    cubes: [
      {
        join_path: orders,
        includes: ['status', 'count']
      },
      {
        join_path: orders.users,
        prefix: true,
        includes: ['id', 'city', 'state']
      }
    ]
  })
  ```
</CodeGroup>

With this data model, here's how you can get orders count by users' cities:

```sql theme={"dark"}
cube=> SELECT MEASURE(count) AS count, users_city FROM orders_users GROUP BY 2;

 count |   users_city
-------+---------------
  1416 | Los Angeles
  1412 | Seattle
  1365 | Mountain View
  1263 | New York
  1220 | Austin
  1164 | Chicago
  1101 | San Francisco
  1059 | Palo Alto
(8 rows)
```

## `CROSS JOIN` and `__cubeJoinField`

The SQL API also supports joins through the `__cubeJoinField` virtual column, which
allows to control how specific cubes are joined. This is considered an advanced
functionality, and views should be used where possible. Join can also be done through
`CROSS JOIN`.

Usage of `CROSS JOIN` or `__cubeJoinField` instructs Cube to perform join as it's defined
in a data model while using provided cubes as [join hints][ref-join-hints].

For example, the following query joins the `orders` and `products` tables under
the hood on `orders.product_id = products.id`, exactly the same way as the
REST (JSON) API query does:

```sql theme={"dark"}
cube=> SELECT p.name, SUM(o.count) FROM orders o LEFT JOIN products p ON o.__cubeJoinField = p.__cubeJoinField GROUP BY 1 LIMIT 5;
           name           | SUM(o.count)
--------------------------+--------------
 Tasty Plastic Mouse      |          121
 Intelligent Cotton Ball  |          119
 Ergonomic Steel Tuna     |          116
 Intelligent Rubber Pants |          116
 Generic Wooden Gloves    |          116
(5 rows)
```

Or through `CROSS JOIN`:

```sql theme={"dark"}
cube=> SELECT p.name, sum(o.count) FROM orders o CROSS JOIN products p GROUP BY 1 LIMIT 5;
           name           | SUM(o.count)
--------------------------+--------------
 Tasty Plastic Mouse      |          121
 Intelligent Cotton Ball  |          119
 Ergonomic Steel Tuna     |          116
 Intelligent Rubber Pants |          116
 Generic Wooden Gloves    |          116
(5 rows)
```

In the resulting query plan, you won't see any joins as you can't see those for
REST (JSON) API queries either:

```sql theme={"dark"}
cube=> EXPLAIN SELECT p.name, sum(o.count) FROM orders o LEFT JOIN products p ON o.__cubeJoinField = p.__cubeJoinField GROUP BY 1 LIMIT 5;
   plan_type   |         plan
---------------+-----------------------
 logical_plan  | CubeScan: request={  +
               |   "measures": [      +
               |     "orders.count"   +
               |   ],                 +
               |   "dimensions": [    +
               |     "products.name"  +
               |   ],                 +
               |   "segments": [],    +
               |   "limit": 5         +
               | }
 physical_plan | CubeScanExecutionPlan+
               |
(2 rows)
```

This feature allows you to join cubes even joined transitively only.

In most of the BI tools you'd use `__cubeJoinField` to define joins between cube
tables. In tools that allow defining custom SQL datasets, you can use joined
tables as a dataset SQL. For example:

```sql theme={"dark"}
SELECT o.count as count, p.name as product_name, p.description as product_description
FROM orders o
CROSS JOIN products p;
```

Please note we use aliasing to avoid name clashing between cube members in a
resulting data set. In this case, wrapped SQL will be properly processed by
Cube, pushing down all operations to Cube query:

```sql theme={"dark"}
cube=> SELECT product_name, SUM(count) FROM (
  SELECT o.count as count, p.name as product_name, p.description as product_description
  FROM orders o CROSS
  JOIN products p
) joined
GROUP BY 1
ORDER BY 2 DESC
LIMIT 5;
       product_name       | SUM(joined.count)
--------------------------+-------------------
 Tasty Plastic Mouse      |               121
 Intelligent Cotton Ball  |               119
 Ergonomic Steel Tuna     |               116
 Intelligent Rubber Pants |               116
 Generic Wooden Gloves    |               116
(5 rows)
```

We can see this by introspecting the `EXPLAIN` plan for this query:

```sql theme={"dark"}
cube=> EXPLAIN SELECT product_name, SUM(count) FROM (
  SELECT o.count as count, p.name as product_name, p.description as product_description
  FROM orders o
  CROSS JOIN products p
) joined
GROUP BY 1
ORDER BY 2 DESC
LIMIT 5;
   plan_type   |         plan
---------------+-----------------------
 logical_plan  | CubeScan: request={  +
               |   "measures": [      +
               |     "orders.count"   +
               |   ],                 +
               |   "dimensions": [    +
               |     "products.name"  +
               |   ],                 +
               |   "segments": [],    +
               |   "order": [         +
               |     [                +
               |       "orders.count",+
               |       "desc"         +
               |     ]                +
               |   ],                 +
               |   "limit": 5         +
               | }
 physical_plan | CubeScanExecutionPlan+
               |
(2 rows)
```

Please note that, even if `product_description` is in the inner selection, it isn't
evaluated in the final query as it isn't used in any way.

## Joining views on a shared dimension

When you join two views on a dimension that resolves to the **same underlying
cube member** and group by that dimension, Cube doesn't perform a row-level
join. Instead it merges them into a single
[multi-fact query][ref-multi-fact-views]: each view becomes its own
aggregating subquery and the results are stitched together on the shared key,
so measures from both views are combined without fan-out.

```sql theme={"dark"}
SELECT
  o.name,
  MEASURE(o.total_amount),
  MEASURE(r.total_refund)
FROM orders_view o
LEFT JOIN returns_view r ON r.name = o.name
GROUP BY 1
```

The `JOIN` type (`INNER`, `LEFT`, `RIGHT`, `FULL`) controls which keys are
kept. This only applies to grouped queries whose `GROUP BY` is the join key. See
[multi-fact views][ref-multi-fact-views] for the full explanation.

[ref-views]: /docs/data-modeling/views

[ref-join-paths]: /docs/data-modeling/joins#join-paths

[ref-join-hints]: /docs/data-modeling/joins#join-hints

[ref-multi-fact-views]: /docs/data-modeling/multi-fact-views


# Query format in the SQL API
Source: https://docs.cube.dev/reference/core-data-apis/sql-api/query-format

SQL API runs queries in the Postgres dialect that can reference those tables and columns.

The SQL API is able to execute [regular queries][ref-regular-queries], [queries with
post-processing][ref-queries-wpp] and [queries with pushdown][ref-queries-wpd]. This page
explains their format and details if they are handled differently by the SQL API.

## Data model mapping

In the SQL API, each cube or view from the [data model][ref-data-model-concepts]
is represented as a table. Measures, dimensions, and segments are represented as
columns in these tables.

### Cubes and views

Given that you have a cube or a view called `orders`, you can query it as if it's
a table:

```sql theme={"dark"}
SELECT * FROM orders;
```

### Dimensions

Given that your cube or view has a dimension called `status`, you can reference it
as a column in the `SELECT` clause. Note that you'll also have to add it to the
`GROUP BY` clause:

```sql theme={"dark"}
SELECT status
FROM orders
GROUP BY 1;
```

### Measures

Given that your cube or view has a measure called `count`, you can reference it
by wrapping with the `MEASURE` aggregate function:

```sql theme={"dark"}
SELECT MEASURE(count)
FROM orders;
```

The SQL API allows aggregate functions on measures as long as they match measure types.

#### Aggregate functions

The special `MEASURE` function works with measures of any type.
Measure columns can also be aggregated with the following aggregate functions that
correspond to [measure types][ref-measure-types]:

| Measure type in Cube                                              | Aggregate function in an aggregated query       |
| ----------------------------------------------------------------- | ----------------------------------------------- |
| [`avg`](/reference/data-modeling/measures#type)                   | `MEASURE` or `AVG`                              |
| [`boolean`](/reference/data-modeling/measures#type)               | `MEASURE`                                       |
| [`count`](/reference/data-modeling/measures#type)                 | `MEASURE` or `COUNT`                            |
| [`count_distinct`](/reference/data-modeling/measures#type)        | `MEASURE` or `COUNT(DISTINCT …)`                |
| [`count_distinct_approx`](/reference/data-modeling/measures#type) | `MEASURE` or `COUNT(DISTINCT …)`                |
| [`max`](/reference/data-modeling/measures#type)                   | `MEASURE` or `MAX`                              |
| [`min`](/reference/data-modeling/measures#type)                   | `MEASURE` or `MIN`                              |
| [`number`](/reference/data-modeling/measures#type)                | `MEASURE` or any other function from this table |
| [`string`](/reference/data-modeling/measures#type)                | `MEASURE` or `STRING_AGG`                       |
| [`sum`](/reference/data-modeling/measures#type)                   | `MEASURE` or `SUM`                              |
| [`time`](/reference/data-modeling/measures#type)                  | `MEASURE` or `MAX` or `MIN`                     |

<Warning>
  If an aggregate function doesn't match the measure type, the following error
  will be thrown: `Measure aggregation type doesn't match`.
</Warning>

### Segments

Segments are exposed as columns of the [`boolean` type][link-postgres-boolean].
Given that your cube or view has a segment called `is_completed`, you can reference it
as a column in the `WHERE` clause:

```sql theme={"dark"}
SELECT *
FROM orders
WHERE is_completed IS TRUE;
```

### Joins

Please [refer to this page](/reference/core-data-apis/sql-api/joins) for details
on joins.

## Post-processing and pushdown

Since 1.0 by default, the SQL API executes [regular queries][ref-regular-queries],
[queries with post-processing][ref-queries-wpp], and [queries with
pushdown][ref-queries-wpd].

### Query post-processing

The following query is performing a `SELECT` from the `orders` cube:

```sql theme={"dark"}
SELECT
  city,
  SUM(amount)
FROM orders
WHERE status = 'shipped'
GROUP BY 1
```

For this query, the SQL API would transform `SELECT` query fragments into a [regular
query][ref-regular-queries]. It can be represented as follows in the REST (JSON) API query
format:

```json theme={"dark"}
{
  "dimensions": [
    "orders.city"
  ],
  "measures": [
    "orders.amount"
  ],
  "filters": [
    {
      "member": "orders.status",
      "operator": "equals",
      "values": [
        "shipped"
      ]
    }
  ]
}
```

Because of this transformation, not all functions and expressions are supported
in query fragments performing `SELECT` from cube tables. Please refer to the
[SQL API reference][ref-ref-sql-api] to see whether a specific expression or function
is supported and whether it can be used in [selection][link-selection-projection]
(e.g., `WHERE`) or [projection][link-selection-projection] (e.g., `SELECT`) parts
of SQL queries.

Expressions over dimensions, such as a `CASE` expression used as a grouping key,
can't be translated into a [regular query][ref-regular-queries] or
[post-processing][ref-queries-wpp]; they are handled by
[query pushdown](#query-pushdown) instead. For example, the following query
derives a fiscal year that starts in April and groups a measure by it:

```sql theme={"dark"}
SELECT
  CASE
    WHEN EXTRACT(MONTH FROM created_at) >= 4
    THEN EXTRACT(YEAR FROM created_at)
    ELSE EXTRACT(YEAR FROM created_at) - 1
  END AS fiscal_year,
  MEASURE(count)
FROM orders
GROUP BY 1
ORDER BY 1;
```

Query pushdown is enabled by default. Queries like the one above can't be
rewritten and fail with the following error if pushdown is disabled via the
[`CUBESQL_SQL_PUSH_DOWN`][ref-env-var-push-down] environment variable, or if the
data source doesn't support pushing down one of the expressions used:

```text theme={"dark"}
Can't detect Cube query and it may be not supported yet
```

If you hit this error, check that query pushdown is enabled and that every
expression in the query is supported for your data source. Alternatively, you
can leverage nested queries: wrap your `SELECT` statement from a cube table
(**inner query**) into another `SELECT` statement (**outer query**) to perform
calculations with expressions like `CASE`. The outer `SELECT` is applied as
post-processing on top of the cube query rather than being rewritten into it,
which allows you to use more SQL functions, operators, and expressions.

Keep the inner query to shapes that a [regular query][ref-regular-queries]
supports, and move every expression to the outer query:

```sql theme={"dark"}
SELECT
  CASE
    WHEN EXTRACT(MONTH FROM month) >= 4
    THEN EXTRACT(YEAR FROM month)
    ELSE EXTRACT(YEAR FROM month) - 1
  END AS fiscal_year,
  SUM(orders_count) AS total
FROM (
  SELECT
    DATE_TRUNC('month', created_at) AS month,
    MEASURE(count) AS orders_count
  FROM orders
  GROUP BY 1
) AS inner_query
GROUP BY 1
ORDER BY 1;
--- You can also use CTEs to achieve the same result
```

This works because `count` is additive, so monthly values can be re-aggregated
with `SUM`. For non-additive measures, such as `count_distinct` or `avg`, group
the inner query by the same granularity you need in the output — re-aggregating
their partial results would produce incorrect values. If no supported
granularity matches that grouping, as is the case for a fiscal year, enable
query pushdown or define the grouping as a dimension in your data model.

### Query pushdown

Query pushdown provides a safe net for queries that can't be rewritten
into combination of a [regular query][ref-regular-queries] and post-processing.
Such queries' SQL would be transpiled to target database query leveraging
all target database capabilities for data processing.

During the rewrite process, Cube validates that the target database would support transpired SQL queries.
If direct conversion is not possible, different SQL transformation rewrite rules can be applied to achieve successful translation.
Please refer to the [SQL API reference][ref-ref-sql-api] for the list of supported SQL functions and clauses.
Support varies based on the target database.

## Top-down and bottom-up evaluation

Fundamentally, every SQL operation results in a tabular data set.
This is usually referred to as SQL operational closure or bottom-up SQL evaluation.
However, for OLAP queries, most of the time, top-down evaluation is required.
Top-down evaluation is whenever the outermost sub-query operation decides on how measures would be actually evaluated as opposed to
innermost sub-query in case of standard SQL behavior.

To balance between SQL guarantees and OLAP requirements, Cube

* uses top-down evaluation from the innermost aggregation operation down to all ungrouped sub-queries,
* uses bottom-up evaluation from the innermost aggregation tabular result set up to the outermost sub-query.

<Warning>
  This behavior is enabled whenever query pushdown is enabled.
  It's enabled by default since 1.0.
</Warning>

To drill-down on how this works, let's consider following example date model

```yaml theme={"dark"}
cubes:
  - name: orders
    sql_table: ECOM.ORDERS

    dimensions:
      - name: id
        sql: ID
        type: number
        primary_key: true

      - name: status
        sql: STATUS
        type: string
        description: The status of the order (completed etc)

      - name: created_at
        sql: "{CUBE}.CREATED_AT"
        type: time

    measures:
      - name: count
        type: count

      - name: completed_count
        type: count
        filters:
          - sql: "{CUBE}.STATUS = 'completed'"

      - name: completed_percentage
        type: number
        sql: "(1.0 * {CUBE.completed_count} / NULLIF({CUBE.count}, 0))"
        format: percent
```

And the query to the SQL API:

```sql theme={"dark"}
SELECT id, status, created_at, completed_percentage FROM orders
```

Such a query is considered an ungrouped query and would result in the following result set:

| id | status    | created\_at | completed\_percentage |
| -- | --------- | ----------- | --------------------- |
| 1  | shipped   | 2024-01-01  | 0.0                   |
| 2  | completed | 2024-01-01  | 100.0                 |
| 3  | completed | 2024-01-02  | 100.0                 |

On the other hand, a typical query that various BI tools generate:

```sql theme={"dark"}
SELECT date_trunc('day', created_at), MEASURE(completed_percentage)
FROM (
  SELECT id, status, created_at, completed_percentage FROM orders
) inner_query
GROUP BY 1
```

...would still yield correct results

| date\_trunc('day', created\_at) | completed\_percentage |
| ------------------------------- | --------------------- |
| 2024-01-01                      | 50.0                  |
| 2024-01-02                      | 100.0                 |

For this particular query, `inner_query` won't be evaluated as a table.
Instead, Cube would postpone its execution until wrapping `GROUP BY` and would use only `date_trunc('day', created_at)` as a dimension to evaluate `completed_percentage` measure instead of full set of `inner_query` columns `id`,`status` and `created_at`.
To make it possible, Cube keeps track of ungrouped queries and evaluates them only on the first occurrence of a `GROUP BY` query in case there's one.

## Aggregated and non-aggregated queries

SQL API supports two types of queries against *cube tables*: aggregated
(those with `GROUP BY` statement) and non-aggregated (those without).

<Info>
  Without query pushdown, queries that Cube runs against your database will always be aggregated,
  regardless of whether you use aggregated (with `GROUP BY`) or non-aggregated
  queries with the SQL API.
  Whenever you enable query pushdown, queries which do not contain `GROUP BY` clause will be executed as ungrouped queries.
</Info>

A non-aggregated query would only include bare column names in SQL:

```sql theme={"dark"}
SELECT
  status,  -- dimension
  count    -- measure
FROM orders
```

With query pushdown disabled, Cube will still use `GROUP BY` to execute such a query.

<Warning>
  Automatic use of `GROUP BY` is disabled by default.
</Warning>

Whenever query pushdown is enabled, such query would run as ungrouped query.
As with REST (JSON) API such queries do not use `GROUP BY` and render measures as if those would be grouped by primary key of a cube.

<Warning>
  If query pushdown is enabled, calculated `number`, `string` or `time` measures queried by SQL API can't use aggregation function definitions with it's `sql` paremeter.
  Such measures can still reference other aggregate type measures though.
</Warning>

Aggregated query must aggregate all measure columns and group by
all dimension columns. You can use the special `MEASURE` aggregate function
for measures of [any type][ref-measure-types]. This is quite convenient, especially
in case you're manually writing ad-hoc queries:

```sql theme={"dark"}
SELECT
  status,         -- dimension
  MEASURE(count)  -- measure
FROM orders
GROUP BY 1
```

<Warning>
  If any measure columns are not aggregated or any dimension columns aren't included
  in `GROUP BY`, the following error will be thrown: `Projection references
    non-aggregate values`. This is a standard SQL consistency check for the `GROUP BY`
  operation, and it's enforced by the SQL API as well.
</Warning>

## Filtering

Without query pushdown, Cube supports most simple equality operators like
`=`, `<>`, `<`, `<=`, `>`, `>=` as well as `IN` and `LIKE` operators.
Cube tries to push down all filters into a [regular query][ref-regular-queries].
In some cases, filtering can only be done during [post-processing][ref-queries-wpp].
Time dimension filters will be converted to time dimension date ranges whenever
it's possible.

## Ordering

Without query pushdown, Cube tries to push down all `ORDER BY` statements into
a [regular query][ref-regular-queries].

### Row limit edge case

When part of a query can't be pushed down, that part is performed during
[post-processing][ref-queries-wpp]. The [regular query][ref-regular-queries] it reads from
is cut off at [50,000 rows][ref-query-default-limit] unless a smaller limit of its own
applies, and the post-processing then runs over only those rows, so the result can be
incorrect without any error being raised.

Aggregated queries usually return far fewer rows than the limit, so this rarely comes up
in practice; please keep it in mind when designing your queries.

Consider the following query. Because of the `SUM(total_value) + 2` expression
in the projection of the outer query, the SQL API can't push down `ORDER BY`:

```sql theme={"dark"}
SELECT
  status,
  SUM(total_value) + 2 AS transformed_amount
FROM (
  SELECT * FROM orders
) AS orders
GROUP BY status
ORDER BY status DESC
LIMIT 100;
```

You can use `EXPLAIN` against the above query to look at the query plan.
As you can see, the sorting operation is done after the regular query and the projection:

```bash theme={"dark"}
+ GlobalLimitExec: skip=None, fetch=100
+- SortExec: [transformed_amount@1 DESC]
+-- ProjectionExec: expr=[status@0 as status, SUM(orders.total_value)@1 + CAST(2 AS Float64) as transformed_amount]
+--- CubeScanExecutionPlan
```

`ORDER BY` is not the only operation this happens to. Anything left to post-processing
over a regular query that isn't bounded by a small enough limit behaves the same way, so
`EXPLAIN` is the reliable way to tell. `CubeScanExecutionPlan` prints the query it will
run: `CubeScanExecutionPlan, Request:` followed by JSON, or `CubeScanExecutionPlan, SQL:`
followed by SQL where the query is pushed down. Pushdown can be partial, so operations
may still sit above a scan that prints `SQL:`. If the JSON has no `limit` key, or the
limit in the JSON or the printed SQL is larger than the number of rows you expect, the
row limit is applied when the query runs and every operation above the scan sees at most
that many rows.

If a query of yours has that shape, you can:

* Add an explicit `LIMIT` and confirm with `EXPLAIN` that it reaches the scan. It only
  does so when the limit ends up directly above the regular query — in the plan above a
  `SortExec` sits in between, so the limit bounds the final output rather than what the
  sorting reads.
* Raise [`CUBEJS_DB_QUERY_LIMIT`][ref-env-db-query-limit] so the intermediate result is
  truncated later. Non-streaming SQL API queries are capped by
  [`CUBESQL_NON_STREAMING_QUERY_MAX_ROW_LIMIT`][ref-env-non-streaming-limit], which
  defaults to `CUBEJS_DB_QUERY_LIMIT` and can't exceed it — if you've set it explicitly,
  raise it too.
* Enable [`CUBESQL_STREAM_MODE`][ref-env-cubesql-stream-mode]: streamed queries aren't
  capped, so there is nothing to truncate. Whether a query streams is decided by the
  limit in the scan's request — the one `EXPLAIN` prints — and not by the `LIMIT` clause
  in your SQL: it streams when that request has no limit, or one above the cap. So this
  combines with the first workaround only up to a point: a `LIMIT` that reaches the scan
  and is below the cap turns streaming back off, while one that doesn't reach it, as in
  the plan above, leaves it on.
* Restructure the query so it is pushed down in full, e.g. by removing the expression
  that prevents it.

[ref-regular-queries]: /reference/core-data-apis/queries#regular-query

[ref-queries-wpp]: /reference/core-data-apis/queries#query-with-post-processing

[ref-queries-wpd]: /reference/core-data-apis/queries#query-with-pushdown

[ref-data-model-concepts]: /docs/data-modeling/overview

[ref-measure-types]: /reference/data-modeling/measures#type

[ref-query-default-limit]: /reference/core-data-apis/queries#row-limit

[ref-env-db-query-limit]: /reference/configuration/environment-variables#cubejs_db_query_limit

[ref-env-cubesql-stream-mode]: /reference/configuration/environment-variables#cubesql_stream_mode

[ref-env-non-streaming-limit]: /reference/configuration/environment-variables#cubesql_non_streaming_query_max_row_limit

[ref-ref-sql-api]: /reference/core-data-apis/sql-api/reference

[ref-env-var-push-down]: /reference/configuration/environment-variables#cubesql_sql_push_down

[link-postgres-boolean]: https://www.postgresql.org/docs/current/datatype-boolean.html

[link-selection-projection]: https://stackoverflow.com/a/1031101


# SQL API reference
Source: https://docs.cube.dev/reference/core-data-apis/sql-api/reference

SQL API supports the following commands as well as functions and operators.

[SQL API][ref-sql-api] supports the following [commands](#sql-commands) as well
as [functions and operators](#sql-functions-and-operators).

<Info>
  If you'd like to propose a function or an operator to be supported in the SQL API,
  check the existing [issues on GitHub][link-github-sql-api]. If there are no relevant
  issues, please [file a new one][link-github-new-sql-api-issue].
</Info>

## SQL commands

### `SELECT`

Synopsis:

```sql theme={"dark"}
SELECT select_expr [, ...]
  FROM from_item
    CROSS JOIN join_item
    ON join_criteria]*
  [ WHERE where_condition ]
  [ GROUP BY grouping_expression ]
  [ HAVING having_expression ]
  [ LIMIT number ] [ OFFSET number ];
```

`SELECT` retrieves rows from a cube.

The `FROM` clause specifies one or more source **cube tables** for the `SELECT`.
Qualification conditions can be added (via `WHERE`) to restrict the returned
rows to a small subset of the original dataset.

Example:

```sql theme={"dark"}
SELECT COUNT(*), orders.status, users.city
FROM orders
  CROSS JOIN users
WHERE city IN ('San Francisco', 'Los Angeles')
GROUP BY orders.status, users.city
HAVING status = 'shipped'
LIMIT 1 OFFSET 1;
```

`SELECT DISTINCT ON (expression [, ...])` is also supported, with the same
semantics as PostgreSQL: for each set of rows with matching values in the
given expressions, only the first row is kept, using the order specified by
`ORDER BY` (which must start with the `DISTINCT ON` expressions).

Example:

```sql theme={"dark"}
SELECT DISTINCT ON (status) status, city
FROM orders
ORDER BY status, id DESC;
```

### `EXPLAIN`

Synopsis:

```sql theme={"dark"}
EXPLAIN [ ANALYZE ] statement
```

The `EXPLAIN` command displays the query execution plan that the Cube planner
will generate for the supplied `statement`.

The `ANALYZE` will execute `statement` and display actual runtime statistics,
including the total elapsed time expended within each plan node and the total
number of rows it actually returned.

Example:

```sql theme={"dark"}
EXPLAIN WITH cte AS (
  SELECT o.count as count, p.name as product_name, p.description as product_description
  FROM orders o
    CROSS JOIN products p
)
SELECT COUNT(*) FROM cte;
   plan_type   |                                plan
---------------+---------------------------------------------------------------------
 logical_plan  | Projection: #COUNT(UInt8(1))                                       +
               |   Aggregate: groupBy=[[]], aggr=[[COUNT(UInt8(1))]]                +
               |     CubeScan: request={                                            +
               |   "measures": [                                                    +
               |     "orders.count"                                                 +
               |   ],                                                               +
               |   "dimensions": [                                                  +
               |     "products.name",                                               +
               |     "products.description"                                         +
               |   ],                                                               +
               |   "segments": []                                                   +
               | }
 physical_plan | ProjectionExec: expr=[COUNT(UInt8(1))@0 as COUNT(UInt8(1))]        +
               |   HashAggregateExec: mode=Final, gby=[], aggr=[COUNT(UInt8(1))]    +
               |     HashAggregateExec: mode=Partial, gby=[], aggr=[COUNT(UInt8(1))]+
               |       CubeScanExecutionPlan                                        +
               |
(2 rows)
```

With `ANALYZE`:

```sql theme={"dark"}
EXPLAIN ANALYZE WITH cte AS (
  SELECT o.count as count, p.name as product_name, p.description as product_description
  FROM orders o
    CROSS JOIN products p
)
SELECT COUNT(*) FROM cte;
     plan_type     |                                                                                plan
-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------
 Plan with Metrics | ProjectionExec: expr=[COUNT(UInt8(1))@0 as COUNT(UInt8(1))], metrics=[output_rows=1, elapsed_compute=541ns, spill_count=0, spilled_bytes=0, mem_used=0]           +
                   |   HashAggregateExec: mode=Final, gby=[], aggr=[COUNT(UInt8(1))], metrics=[output_rows=1, elapsed_compute=6.583µs, spill_count=0, spilled_bytes=0, mem_used=0]     +
                   |     HashAggregateExec: mode=Partial, gby=[], aggr=[COUNT(UInt8(1))], metrics=[output_rows=1, elapsed_compute=13.958µs, spill_count=0, spilled_bytes=0, mem_used=0]+
                   |       CubeScanExecutionPlan, metrics=[]                                                                                                                           +
                   |
(1 row)
```

### `SHOW`

Synopsis:

```sql theme={"dark"}
SHOW name
SHOW ALL
```

Returns the value of a runtime parameter using `name`, or all runtime parameters
if `ALL` is specified.

Example:

```sql theme={"dark"}
SHOW timezone;
 setting
---------
 GMT
(1 row)

SHOW ALL;
            name             |    setting     | description
-----------------------------+----------------+-------------
 max_index_keys              | 32             |
 max_allowed_packet          | 67108864       |
 timezone                    | GMT            |
 client_min_messages         | NOTICE         |
 standard_conforming_strings | on             |
 extra_float_digits          | 1              |
 transaction_isolation       | read committed |
 application_name            | NULL           |
 lc_collate                  | en_US.utf8     |
(9 rows)
```

### `SET`

Synopsis:

```sql theme={"dark"}
SET name TO value
SET name = value
```

The `SET` command changes a session variable to a new value.

Use `SET` with the `cube_cache` session variable for [cache control][ref-sql-cache-control].

You can also set the session time zone with `SET TIME ZONE` (or `SET TIMEZONE`):

```sql theme={"dark"}
SET TIME ZONE 'Europe/Rome';
SET TIME ZONE 'UTC';
```

Use `DEFAULT` to reset the time zone to its default. The `LOCAL` form
(`SET TIME ZONE LOCAL`) is not supported.

### `CREATE TEMPORARY TABLE`

Synopsis:

```sql theme={"dark"}
CREATE TEMPORARY TABLE table_name AS query
CREATE TEMPORARY TABLE table_name ( column_name data_type [, ...] )
```

Creates a table that lives for the duration of the session, either filled by a
query or empty, to be filled by [`COPY`](#copy). Temporary tables can be joined
with cubes, and are dropped with `DROP TABLE`.

Column types are limited to those `COPY` can load:

* `boolean`
* `smallint`, `integer`, `bigint`
* `real`, `double precision`, `numeric` (up to a precision of 38)
* `varchar`, `text`, and the other variable-width character types (`character
  varying`, `nvarchar`, `string`), as well as `uuid`, `json` and `jsonb`, all of
  which are stored as text
* `date`, `timestamp` (and `datetime`) without a time zone

A `numeric` without a precision holds `numeric(38, 10)`, so values are rounded to
ten decimal places. Give the precision and scale to keep more of them.

Fixed-width `character`/`char` columns are not accepted: PostgreSQL pads their
values to the declared width and ignores trailing blanks when comparing them, which
a text column does not do. Use `varchar` or `text` instead.

The amount of data held is capped per session and per server, by the
`CUBESQL_TEMP_TABLE_SESSION_MEM` (10 MiB) and `CUBESQL_TEMP_TABLE_TOTAL_MEM`
(100 MiB) environment variables.

### `COPY`

Synopsis:

```sql theme={"dark"}
COPY table_name [ ( column_name [, ...] ) ]
FROM STDIN
[ [ WITH ] ( option [, ...] ) ]
```

Loads data sent by the client into a [temporary
table](#create-temporary-table). Only `FROM STDIN` is supported: cubes are a
read-only data source, so a temporary table is the only place data can go, and
a file or a program target would read on the Cube host rather than on the
machine running the client.

Columns not listed in the statement are left `NULL`. Repeating the command
appends more rows to the table.

Supported options: `FORMAT` (`text` or `csv`), `DELIMITER`, `NULL`, `HEADER`,
`QUOTE`, `ESCAPE`, `FORCE_NOT_NULL`, `FORCE_NULL`, and `ENCODING` (`UTF8`
only). They behave as [in PostgreSQL][link-postgres-copy], including their
defaults. The pre-9.0 syntax (e.g. `CSV HEADER`) is supported as well; the
`BINARY` format is not.

Example, using the `\copy` command of `psql` to load a CSV file:

```sql theme={"dark"}
CREATE TEMPORARY TABLE targets (city text, target numeric(10, 2));
CREATE TABLE

\copy targets FROM 'targets.csv' WITH (FORMAT csv, HEADER)
COPY 42

SELECT city, SUM(count), MAX(target)
FROM orders CROSS JOIN targets
WHERE orders.city = targets.city
GROUP BY 1;
```

## SQL functions and operators

SQL API currently implements a subset of functions and operators [supported by
PostgreSQL][link-postgres-funcs]. Additionally, it supports a few [custom
functions](#custom-functions).

### Comparison operators

<Info>
  Learn more in the
  [relevant section](https://www.postgresql.org/docs/current/functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE)
  of the PostgreSQL documentation.
</Info>

| Function     | Description                                                                      | [Pushdown][ref-qpd] | <nobr>[Post-processing][ref-qpp]</nobr>                                                             |
| ------------ | -------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |
| `<`          | Returns `TRUE` if the first value is **less** than the second                    | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `>`          | Returns `TRUE` if the first value is **greater** than the second                 | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `<=`         | Returns `TRUE` if the first value is **less** than or **equal** to the second    | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `>=`         | Returns `TRUE` if the first value is **greater** than or **equal** to the second | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `=`          | Returns `TRUE` if the first value is **equal** to the second                     | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `<>` or `!=` | Returns `TRUE` if the first value is **not equal** to the second                 | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |

### Comparison predicates

<Info>
  Learn more in the
  [relevant section](https://www.postgresql.org/docs/current/functions-comparison.html#FUNCTIONS-COMPARISON-PRED-TABLE)
  of the PostgreSQL documentation.
</Info>

| Function      | Description                                                           | [Pushdown][ref-qpd] | <nobr>[Post-processing][ref-qpp]</nobr>                                                             |
| ------------- | --------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |
| `BETWEEN`     | Returns `TRUE` if the first value is between the second and the third | ❌ No                | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>❌ Inner (projections)</nobr> |
| `IS NULL`     | Test whether value is `NULL`                                          | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `IS NOT NULL` | Test whether value is not `NULL`                                      | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |

### Mathematical functions

<Info>
  Learn more in the
  [relevant section](https://www.postgresql.org/docs/current/functions-math.html#FUNCTIONS-MATH-FUNC-TABLE)
  of the PostgreSQL documentation.
</Info>

| Function       | Description                                             | [Pushdown][ref-qpd] | <nobr>[Post-processing][ref-qpp]</nobr>                                                             |
| -------------- | ------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |
| `ABS`          | Absolute value                                          | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `CEIL`         | Nearest integer greater than or equal to argument       | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `DEGREES`      | Converts radians to degrees                             | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `EXP`          | Exponential (`e` raised to the given power)             | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `FLOOR`        | Nearest integer less than or equal to argument          | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `LN`           | Natural logarithm                                       | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `LOG`          | Base 10 logarithm                                       | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `LOG10`        | Base 10 logarithm (same as `LOG`)                       | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `PI`           | Approximate value of `π`                                | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `POWER`        | `a` raised to the power of `b`                          | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `RADIANS`      | Converts degrees to radians                             | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `ROUND`        | Rounds `v` to `s` decimal places                        | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `SIGN`         | Sign of the argument (`-1`, `0`, or `+1`)               | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `SQRT`         | Square root                                             | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `TRUNC`        | Truncates to integer (towards zero)                     | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>❌ Inner (projections)</nobr> |
| `WIDTH_BUCKET` | Assigns a value to a bucket in an equal-width histogram | ✅ Yes               | ❌ No                                                                                                |

<Note>
  `WIDTH_BUCKET` pushdown is only available on data sources whose SQL dialect
  supports it. It is not supported with Apache Pinot, BigQuery, CrateDB, Cube Store,
  Dremio, Druid, DuckDB, Firebolt, Hive, ksqlDB, Microsoft SQL Server, MySQL,
  QuestDB, or SQLite.
</Note>

### Trigonometric functions

<Info>
  Learn more in the
  [relevant section](https://www.postgresql.org/docs/current/functions-math.html#FUNCTIONS-MATH-TRIG-TABLE)
  of the PostgreSQL documentation.
</Info>

| Function | Description                                 | [Pushdown][ref-qpd] | <nobr>[Post-processing][ref-qpp]</nobr>                                                             |
| -------- | ------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |
| `ACOS`   | Inverse cosine, result in radians           | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `ASIN`   | Inverse sine, result in radians             | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `ATAN`   | Inverse tangent, result in radians          | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `ATAN2`  | Inverse tangent of `y/x`, result in radians | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `COS`    | Cosine, argument in radians                 | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `COT`    | Cotangent, argument in radians              | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `SIN`    | Sine, argument in radians                   | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `TAN`    | Tangent, argument in radians                | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |

### String functions and operators

<Info>
  Learn more in the
  [relevant section](https://www.postgresql.org/docs/current/functions-string.html#FUNCTIONS-STRING-SQL)
  of the PostgreSQL documentation.
</Info>

| Function                            | Description                                                                                                       | [Pushdown][ref-qpd] | <nobr>[Post-processing][ref-qpp]</nobr>                                                             |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |
| `\|\|`                              | Concatenates two strings                                                                                          | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>❌ Inner (projections)</nobr> |
| `BTRIM`                             | Removes the longest string containing only characters in `characters` from the start and end of `string`          | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `BIT_LENGTH`                        | Returns number of bits in the string (8 times the `OCTET_LENGTH`)                                                 | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>❌ Inner (projections)</nobr> |
| `CHAR_LENGTH` or `CHARACTER_LENGTH` | Returns number of characters in the string                                                                        | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>❌ Inner (projections)</nobr> |
| `LOWER`                             | Converts the string to all lower case                                                                             | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>❌ Inner (projections)</nobr> |
| `LTRIM`                             | Removes the longest string containing only characters in `characters` from the start of `string`                  | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `OCTET_LENGTH`                      | Returns number of bytes in the string                                                                             | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>❌ Inner (projections)</nobr> |
| `POSITION`                          | Returns first starting index of the specified `substring` within `string`, or zero if it's not present            | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `RTRIM`                             | Removes the longest string containing only characters in `characters` from the end of `string`                    | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `SUBSTRING`                         | Extracts the substring of `string`                                                                                | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `TRIM`                              | Removes the longest string containing only characters in `characters` from the start, end, or both ends of string | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>❌ Inner (projections)</nobr> |
| `UPPER`                             | Converts the string to all upper case                                                                             | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>❌ Inner (projections)</nobr> |

### Other string functions

<Info>
  Learn more in the
  [relevant section](https://www.postgresql.org/docs/current/functions-string.html#FUNCTIONS-STRING-OTHER)
  of the PostgreSQL documentation.
</Info>

| Function      | Description                                                                                                   | [Pushdown][ref-qpd] | <nobr>[Post-processing][ref-qpp]</nobr>                                                             |
| ------------- | ------------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |
| `ASCII`       | Returns the numeric code of the first character of the argument                                               | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `CONCAT`      | Concatenates the text representations of all the arguments                                                    | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `LEFT`        | Returns first `n` characters in the string, or when `n` is negative, returns all but last `ABS(n)` characters | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `REPEAT`      | Repeats string the specified number of times                                                                  | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `REPLACE`     | Replaces all occurrences in `string` of substring `from` with substring `to`                                  | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `RIGHT`       | Returns last `n` characters in the string, or when `n` is negative, returns all but first `ABS(n)` characters | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `STARTS_WITH` | Returns `TRUE` if string starts with prefix                                                                   | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>❌ Inner (projections)</nobr> |

### Pattern matching

<Info>
  Learn more in the
  [relevant section](https://www.postgresql.org/docs/current/functions-matching.html)
  of the PostgreSQL documentation.
</Info>

| Function        | Description                                                           | [Pushdown][ref-qpd] | <nobr>[Post-processing][ref-qpp]</nobr>                                                             |
| --------------- | --------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |
| `LIKE`          | Returns `TRUE` if the string matches the supplied pattern             | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `REGEXP_SUBSTR` | Returns the substring that matches a POSIX regular expression pattern | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |

### Data type formatting functions

<Info>
  Learn more in the
  [relevant section](https://www.postgresql.org/docs/current/functions-formatting.html)
  of the PostgreSQL documentation.
</Info>

| Function  | Description                                                  | [Pushdown][ref-qpd] | <nobr>[Post-processing][ref-qpp]</nobr>                                                             |
| --------- | ------------------------------------------------------------ | ------------------- | --------------------------------------------------------------------------------------------------- |
| `TO_CHAR` | Converts a timestamp to string according to the given format | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |

### Date/time functions

<Info>
  Learn more in the
  [relevant section](https://www.postgresql.org/docs/current/functions-datetime.html#FUNCTIONS-DATETIME-TABLE)
  of the PostgreSQL documentation.
</Info>

| Function         | Description                                                                                                                                                             | [Pushdown][ref-qpd] | <nobr>[Post-processing][ref-qpp]</nobr>                                                             |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |
| `DATE_ADD`       | Add an interval to a timestamp with time zone                                                                                                                           | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `DATE_TRUNC`     | Truncate a timestamp to specified precision. Only [default granularities][ref-default-granularities] are supported, see below                                           | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `DATEDIFF`       | From [Redshift](https://docs.aws.amazon.com/redshift/latest/dg/r_DATEDIFF_function.html). Returns the difference between the date parts of two date or time expressions | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `EXTRACT`        | Retrieves subfields such as year or hour from date/time values                                                                                                          | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `LOCALTIMESTAMP` | Returns the current date and time **without** time zone                                                                                                                 | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `NOW`            | Returns the current date and time **with** time zone                                                                                                                    | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |

<Warning>
  `DATE_TRUNC` only accepts the default granularities: `year`, `quarter`, `month`,
  `week`, `day`, `hour`, `minute`, `second`. [Custom
  granularities][ref-granularities] can't be addressed by name via the SQL API,
  even though they are exposed in the [metadata][ref-meta-api] and can be queried
  via the [REST API][ref-rest-api]. (The [GraphQL API][ref-graphql-api] can't
  address them by name either — its schema only exposes fields for the default
  granularities.) Using a custom granularity name results in an error:

  ```
  Execution error: Unsupported date_trunc granularity: fiscal_quarter
  ```

  To query a custom granularity via the SQL API, define a [proxy
  dimension][ref-proxy-granularity] that references it. It is exposed as a regular
  time dimension and can be selected directly.
</Warning>

### Conditional expressions

<Info>
  Learn more in the
  [relevant section](https://www.postgresql.org/docs/current/functions-conditional.html)
  of the PostgreSQL documentation.
</Info>

| Function, expression | Description                                                                      | [Pushdown][ref-qpd] | <nobr>[Post-processing][ref-qpp]</nobr>                                                             |
| -------------------- | -------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |
| `CASE`               | Generic conditional expression                                                   | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `COALESCE`           | Returns the first of its arguments that is not `NULL`                            | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `NULLIF`             | Returns `NULL` if both arguments are equal, otherwise returns the first argument | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `GREATEST`           | Select the largest value from a list of expressions                              | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `LEAST`              | Select the smallest value from a list of expressions                             | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>❌ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |

### General-purpose aggregate functions

<Info>
  Learn more in the
  [relevant section](https://www.postgresql.org/docs/current/functions-aggregate.html#FUNCTIONS-AGGREGATE-TABLE)
  of the PostgreSQL documentation.
</Info>

| Function          | Description                                                                                 | [Pushdown][ref-qpd] | <nobr>[Post-processing][ref-qpp]</nobr>                                                             |
| ----------------- | ------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |
| `AVG`             | Computes the average (arithmetic mean) of all the non-`NULL` input values                   | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `COUNT`           | Computes the number of input rows in which the input value is not `NULL`                    | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `COUNT(DISTINCT)` | Computes the number of input rows containing unique input values                            | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `MAX`             | Computes the maximum of the non-`NULL` input values                                         | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `MIN`             | Computes the minimum of the non-`NULL` input values                                         | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `SUM`             | Computes the sum of the non-`NULL` input values                                             | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `MEASURE`         | Works with measures of [any type][ref-sql-api-aggregate-functions]                          | ✅ Yes               | <nobr>❌ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `STRING_AGG`      | Concatenates the input values into a string, separated by a delimiter (supports `DISTINCT`) | ✅ Yes               | ❌ No                                                                                                |
| `PERCENTILE_CONT` | Computes a continuous percentile, used with `WITHIN GROUP (ORDER BY ...)`                   | ✅ Yes               | ❌ No                                                                                                |

In projections in inner parts of post-processing queries:

* `AVG`, `COUNT`, `MAX`, `MIN`, and `SUM` can only be used with measures of
  [compatible types][ref-sql-api-aggregate-functions].
* If `COUNT(*)` is specified, Cube will query the **first** measure of type `count`
  of the relevant cube.

<Note>
  `PERCENTILE_CONT` pushdown is only available on data sources whose SQL dialect
  supports it. It is not supported with BigQuery, ClickHouse, Microsoft SQL Server,
  MySQL, or Presto.
</Note>

### Aggregate functions for statistics

<Info>
  Learn more in the
  [relevant section](https://www.postgresql.org/docs/current/functions-aggregate.html#FUNCTIONS-AGGREGATE-STATISTICS-TABLE)
  of the PostgreSQL documentation.
</Info>

| Function      | Description                                                    | [Pushdown][ref-qpd] | <nobr>[Post-processing][ref-qpp]</nobr>                                                             |
| ------------- | -------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |
| `COVAR_POP`   | Computes the population covariance                             | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `COVAR_SAMP`  | Computes the sample covariance                                 | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `STDDEV_POP`  | Computes the population standard deviation of the input values | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `STDDEV_SAMP` | Computes the sample standard deviation of the input values     | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `VAR_POP`     | Computes the population variance of the input values           | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `VAR_SAMP`    | Computes the sample variance of the input values               | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |

### Window functions

<Info>
  Learn more in the
  [relevant section](https://www.postgresql.org/docs/current/tutorial-window.html)
  of the PostgreSQL documentation.
</Info>

Window functions are supported via [query pushdown][ref-qpd] only; they are not
available in [query post-processing][ref-qpp]. Two kinds are supported:

* **Aggregate functions used as window functions** — any supported aggregate
  function (such as `SUM`, `AVG`, `COUNT`, `MIN`, or `MAX`) combined with an
  `OVER (...)` clause.
* **The `LAG` and `LEAD` window functions:**

| Function | Description                                                                                | [Pushdown][ref-qpd] | <nobr>[Post-processing][ref-qpp]</nobr> |
| -------- | ------------------------------------------------------------------------------------------ | ------------------- | --------------------------------------- |
| `LAG`    | Returns the value from a row at a given offset before the current row within its partition | ✅ Yes               | ❌ No                                    |
| `LEAD`   | Returns the value from a row at a given offset after the current row within its partition  | ✅ Yes               | ❌ No                                    |

### Row and array comparisons

<Info>
  Learn more in the
  [relevant section](https://www.postgresql.org/docs/current/functions-comparisons.html)
  of the PostgreSQL documentation.
</Info>

| Function | Description                                                               | [Pushdown][ref-qpd] | <nobr>[Post-processing][ref-qpp]</nobr>                                                             |
| -------- | ------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |
| `IN`     | Returns `TRUE` if a left-side value matches **any** of right-side values  | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |
| `NOT IN` | Returns `TRUE` if a left-side value matches **none** of right-side values | ✅ Yes               | <nobr>✅ Outer</nobr><br /><nobr>✅ Inner (selections)</nobr><br /><nobr>✅ Inner (projections)</nobr> |

### Custom functions

| Function | Description                                                                    |
| -------- | ------------------------------------------------------------------------------ |
| `XIRR`   | Calculates the [internal rate of return][link-xirr] for a series of cash flows |

<Note>
  See the [XIRR recipe](/recipes/data-modeling/xirr) for more details.
</Note>

[ref-qpd]: /reference/core-data-apis/sql-api/query-format#query-pushdown

[ref-qpp]: /reference/core-data-apis/sql-api/query-format#query-post-processing

[ref-sql-api]: /reference/core-data-apis/sql-api

[ref-sql-api-aggregate-functions]: /reference/core-data-apis/sql-api/query-format#aggregate-functions

[ref-granularities]: /reference/data-modeling/dimensions#granularities

[ref-default-granularities]: /docs/data-modeling/dimensions#time-dimensions

[ref-proxy-granularity]: /docs/data-modeling/dimensions#time-dimension-granularity-references

[ref-meta-api]: /reference/core-data-apis/rest-api/reference#metadata-api

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-graphql-api]: /reference/core-data-apis/graphql-api

[link-postgres-funcs]: https://www.postgresql.org/docs/current/functions.html

[link-postgres-copy]: https://www.postgresql.org/docs/current/sql-copy.html

[link-github-sql-api]: https://github.com/cube-js/cube/issues?q=is%3Aopen+is%3Aissue+label%3Aapi%3Asql

[link-github-new-sql-api-issue]: https://github.com/cube-js/cube/issues/new?assignees=&labels=&projects=&template=sql_api_query_issue.md&title=

[link-xirr]: https://support.microsoft.com/en-us/office/xirr-function-de1242ec-6477-445b-b11b-a303ad9adc9d

[ref-sql-cache-control]: /reference/core-data-apis/sql-api#cache-control


# Authentication and Authorization
Source: https://docs.cube.dev/reference/core-data-apis/sql-api/security

Harden the SQL API with `checkSqlAuth`, per-user passwords, security-context switching, and row-level enforcement hooks.

Cube can be configured with dynamic username & password verification system by
setting a [`checkSqlAuth()`][ref-config-check-sql-auth] function in the
configuration file. This function should verify username and return
an object with password and security context.

If password returned from this function matches provided in connection string
user will be authenticated with provided security context.

```javascript theme={"dark"}
module.exports = {
  checkSqlAuth: async (req, username) => {
    if (username === "fooUser") {
      return {
        password: "mypassword",
        securityContext: {}
      }
    }

    throw new Error("Incorrect user name or password")
  }
}
```

## Security Context (Row-Level Security)

Cube's SQL API can also use the Security Context for [Dynamic data model
creation][ref-dynamic-schemas] or [`queryRewrite`][ref-config-queryrewrite]
property in your configuration file.

By default, the SQL API uses the current user's Security Context, but this
behaviour can be modified so that certain users are allowed to switch. To do
this, we must first define which user is allowed to change Security Context:

### Example

First, you need to define what user is allowed to change security context:

```dotenv theme={"dark"}
CUBEJS_SQL_SUPER_USER=admin
```

Then configure the [`contextToAppId()`][ref-config-ctx-to-app-id],
[`queryRewrite()`][ref-config-queryrewrite] and
[`checkSqlAuth()`][ref-config-check-sql-auth] properties in your `cube.js`
configuration file:

```javascripttitle="cube.js" theme={"dark"}
module.exports = {
  // Create a new appId for each team so that a separate data model is
  // compiled for each of them and `COMPILE_CONTEXT` can be used below
  // https://cube.dev/docs/product/configuration/reference/config#context_to_app_id
  contextToAppId: ({ securityContext }) => {
    return securityContext.team
  },

  // Enforce a default value for `team` if one is not provided
  // in the security context
  // https://cube.dev/docs/product/configuration/reference/config#extendcontext
  extendContext: ({ securityContext }) => {
    if (!securityContext.team) {
      securityContext.team = "public"
    }

    return {
      securityContext
    }
  },

  // Here we create a new security context for each team so that we can
  // use it in our data model later
  checkSqlAuth: (query, username) => {
    const securityContext = {
      team: username
    }

    return {
      password: process.env.CUBEJS_SQL_PASSWORD,
      securityContext: securityContext
    }
  }
}
```

Now, you can use the `securityContext` in your data model:

```twigtitle="model/cubes/users.yml" theme={"dark"}
{# Is the current team trusted? #}
{% set trusted_teams = ['cx', 'exec' ] %}
{% set is_trusted_team = COMPILE_CONTEXT.securityContext.team in trusted_teams %}

{# Convenient function to mask values if the current team is not trusted #}
{% macro masked(sql, is_visible) -%}
{{ sql if is_visible else "\"'--- masked ---'\"" }}
{%- endmacro %}

cubes:
  - name: users
    sql_table: users
    public: false

    dimensions:

      {# This property will be masked unless the requesting user is part of a trusted team #}
      - name: first_name
        sql: {{ masked('first_name', is_trusted_team) }}
        type: string

      {# This property will be masked unless the requesting user is part of a trusted team #}
      - name: last_name
        sql: {{ masked('last_name', is_trusted_team) }}
        type: string

      - name: state
        sql: state
        type: string

      - name: city
        sql: city
        type: string

      - name: created_at
        sql: created_at
        type: time

    measures:
      - name: count
        type: count

```

## Virtual User Filter

With the above now configured, we can query Cube using SQL with a user that is
part of a trusted team:

```sql theme={"dark"}
SELECT users_city, users_first_name, users_last_name
FROM users
WHERE __user = 'cx'
```

This pairs well with other security functionality in tools like Preset, which
allows configuring [row-level security to allow
access][preset-docs-rls-inclusive] to data based on the current user's security
context.

If it's not enough for your case, you define your logic for check with
[`canSwitchSqlUser` property][ref-config-can-switch-sql-user] in your `cube.js`
configuration file.

You can change security context for specific query via virtual filter on:

```sql theme={"dark"}
SELECT * FROM orders WHERE __user = 'anotheruser';
```

[preset-docs-rls-inclusive]: https://docs.preset.io/docs/row-level-security-rls#define-inclusive-regular-rls-filter

[ref-config-can-switch-sql-user]: /reference/configuration/config#canswitchsqluser

[ref-config-check-sql-auth]: /reference/configuration/config#checksqlauth

[ref-config-ctx-to-app-id]: /reference/configuration/config#context_to_app_id

[ref-config-queryrewrite]: /reference/configuration/config#queryrewrite

[ref-dynamic-schemas]: /docs/data-modeling/dynamic


# Cube Store SQL commands
Source: https://docs.cube.dev/reference/cubestore/sql-commands

Reference for the diagnostic, maintenance, and recovery SQL commands supported by Cube Store.

Cube Store, the [pre-aggregation storage engine][ref-cube-store-architecture],
partially supports the MySQL protocol. Alongside queries, it accepts a set of
administrative commands, which fall into three tiers:

* [Diagnostics](#diagnostics) — inspect pre-aggregations and query plans. These
  don't change cluster state.
* [Cache and queue](#cache-and-queue) — inspect and manipulate the cache and the
  queue used for pre-aggregation builds.
* [Store maintenance and recovery](#store-maintenance-and-recovery) — operate on
  the underlying stores. Includes destructive commands.

<Warning>
  Apart from the [diagnostic commands](#diagnostics), which only read state, the
  commands on this page are intended for recovering a Cube Store cluster that is
  already in a bad state. Several of them discard data irreversibly, and the
  distinction between them is not obvious from their names — `CLEAR` and
  `TRUNCATE` do different things, and `WIPE` is unrecoverable by design.

  Don't run them unless you understand what a given command does and why you need
  it. If you're not sure, they're not the right tool.
</Warning>

## Connecting

Cube Store's MySQL protocol is served by the router on port `3306` by default
(configurable via `CUBESTORE_PORT`, or `CUBESTORE_BIND_ADDR` for the full
address). Connect with the MySQL CLI client:

```bash theme={"dark"}
mysql -h <CUBESTORE_IP> --user=cubestore -pcubestore --protocol=TCP
```

<Warning>
  Only Linux and Mac OS versions of MySQL client are supported as of right now.
  You can install one on ubuntu using `apt-get install default-mysql-client`
  command or `brew install mysql-client` on Mac OS. Windows versions of the MySQL
  client aren't supported.
</Warning>

<Note>
  This connection is available when you run Cube Store yourself. Cube's cloud
  platform doesn't expose the Cube Store port, so you can't attach a MySQL client
  to it.

  You can still inspect query plans there: in the SQL Runner, pick the `cache` data
  source and run `EXPLAIN` or `EXPLAIN ANALYZE` against Cube Store. That path only
  accepts read-only statements, so the [cache and queue](#cache-and-queue) and
  [store maintenance and recovery](#store-maintenance-and-recovery) commands below
  are rejected before they reach Cube Store. If you need one of those, contact
  support.

  Avoid `DUMP` there. It wraps a `SELECT`, so it reads as a query and gets through,
  but it writes to the router's local disk and nothing cleans it up.
</Note>

## Diagnostics

These commands don't change cluster state and are safe to run on a healthy
cluster. `DUMP` is the one exception to watch: it doesn't touch cluster state
either, but it does write to the router's local disk — see below.

### `information_schema.tables`

To check which pre-aggregations are managed by Cube Store, query
`information_schema.tables`:

```sql theme={"dark"}
SELECT * FROM information_schema.tables;
+----------------------+-----------------------------------------------+
| table_schema         | table_name                                    |
+----------------------+-----------------------------------------------+
| dev_pre_aggregations | orders_main20190101_23jnqarg_uiyfxd0f_1gifflf |
| dev_pre_aggregations | orders_main20190301_24ph0a1c_utzntnv_1gifflf  |
| dev_pre_aggregations | orders_main20190201_zhrh5kj1_rkmsrffi_1gifflf |
| dev_pre_aggregations | orders_main20191001_mdw2hxku_waxajvwc_1gifflf |
| dev_pre_aggregations | orders_main20190701_izc2tl0h_bxsf1zlb_1gifflf |
+----------------------+-----------------------------------------------+
5 rows in set (0.01 sec)
```

These pre-aggregations are stored as Parquet files under the `.cubestore/`
folder in the project root during development.

### `EXPLAIN`

Synopsis:

```sql theme={"dark"}
EXPLAIN select_statement;
```

`EXPLAIN` shows the logical plan for a query:

```sql theme={"dark"}
 EXPLAIN SELECT orders__platform, orders__gender, sum(orders__count) FROM dev_pre_aggregations.orders_general_o32v4dvq_vbyemtl2_1h5hs8r
 GROUP BY orders__gender, orders__platform;
+-------------------------------------------------------------------------------------------------------------------------------------+
| logical plan                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+--------------------------------------------------------------------------------------------------------------------------------------+
| Projection, [dev_pre_aggregations.orders_general_o32v4dvq_vbyemtl2_1h5hs8r.orders__platform, dev_pre_aggregations.orders_general_o32v4dvq_vbyemtl2_1h5hs8r.orders__gender, SUM(dev_pre_aggregations.orders_general_o32v4dvq_vbyemtl2_1h5hs8r.orders__count)]
  Aggregate
    ClusterSend, indices: [[96]]
      Scan dev_pre_aggregations.orders_general_o32v4dvq_vbyemtl2_1h5hs8r, source: CubeTable(index: orders_general_plat_gender_o32v4dvq_vbyemtl2_1h5hs8r:96:[123, 126]), fields: [orders__gender, orders__platform, orders__count] |
+-------------------------------------------------------------------------------------------------------------------------------------+
```

### `EXPLAIN ANALYZE`

Synopsis:

```sql theme={"dark"}
EXPLAIN ANALYZE select_statement;
```

`EXPLAIN ANALYZE` shows the physical plan for the router and all workers used for
query processing:

```sql theme={"dark"}
 EXPLAIN ANALYZE SELECT orders__platform, orders__gender, sum(orders__count) FROM dev_pre_aggregations.orders_general_o32v4dvq_vbyemtl2_1h5hs8r
 GROUP BY orders__gender, orders__platform

+-----------+-----------------+--------------------------------------------------------------------------------------------------------------------------+
| node type | node name       | physical plan                                                                                                                                                                                                                                                                                                                                                   |
+-----------+-----------------+--------------------------------------------------------------------------------------------------------------------------+
| router    |                 | Projection, [orders__platform, orders__gender, SUM(dev_pre_aggregations.orders_general_o32v4dvq_vbyemtl2_1h5hs8r.orders__count)@2:SUM(orders__count)]
  FinalInplaceAggregate
    ClusterSend, partitions: [[123, 126]]                                                                                                                                         |
| worker    | 127.0.0.1:10001 | PartialInplaceAggregate
  Merge
    Scan, index: orders_general_plat_gender_o32v4dvq_vbyemtl2_1h5hs8r:96:[123, 126], fields: [orders__gender, orders__platform, orders__count]
      Projection, [orders__gender, orders__platform, orders__count]
        ParquetScan, files: /.cubestore/data/126-0qtyakym.parquet |
+-----------+-----------------+--------------------------------------------------------------------------------------------------------------------------+
```

System-table selects don't produce a distributable plan, so neither `EXPLAIN
ANALYZE` nor `EXPLAIN ANALYZE DETAILED` accepts one. Plain `EXPLAIN` is the only
one of the three that works on `information_schema.tables`.

### `EXPLAIN ANALYZE DETAILED`

Synopsis:

```sql theme={"dark"}
EXPLAIN ANALYZE DETAILED select_statement;
```

Unlike `EXPLAIN` and `EXPLAIN ANALYZE`, which only show the plan, `EXPLAIN ANALYZE
DETAILED` actually executes the query under per-query tracing and renders a
detailed execution trace as a tree with a per-category timing summary. Use it to
diagnose where time is spent within a query:

```sql theme={"dark"}
EXPLAIN ANALYZE DETAILED SELECT orders__platform, sum(orders__count) FROM dev_pre_aggregations.orders_general_o32v4dvq_vbyemtl2_1h5hs8r
GROUP BY orders__platform;
```

### Reading a query plan

When you're debugging performance, one thing to keep in mind is that Cube Store, due to its design, will always use some index to query data, and usage of the index itself doesn't necessarily tell if the particular query is performing optimally or not.
What's important to look at is aggregation and partition merge strategies.
In most of the cases for aggregation, Cube Store will use `HashAggregate` or `InplaceAggregate` strategy as well as `Merge` and `MergeSort` operators to merge different partitions.
Even for larger datasets, scan operations on sorted data will almost always be much more efficient and faster than hash aggregate as the Cube Store optimizer decides to use those only if there's an index with appropriate sorting.
So, as a rule of thumb, if you see in your plan `PartialHashAggregate` and `FinalHashAggregate` nodes together with `Merge` operators, those queries most likely perform sub-optimally.
On the other hand, if you see `PartialInplaceAggregate`, `FinalInplaceAggregate`, and `FullInplaceAggregate` together with `MergeSort` operators in your plan, then there's a high chance the query performs optimally.
Sometimes, there can be exceptions to this rule.
For example, a total count query run on top of the index will perform `HashAggregate` strategy on top of `MergeSort` nodes even if all required indexes are in place.
This query would be optimal as well.

### `DUMP`

Synopsis:

```sql theme={"dark"}
DUMP select_statement;
```

`DUMP` plans the query, then writes a metastore backup together with the Parquet
files the query reads into a new directory under `dumps/` and returns its path.
Use it to capture the exact state behind a query for offline inspection.

<Warning>
  Unlike the other diagnostic commands, `DUMP` writes to the router's local disk,
  and the directory it creates is never cleaned up automatically. A query that
  touches many partitions copies every Parquet file it reads, so repeated dumps on
  a production router accumulate without bound. Delete the directory once you're
  done with it.
</Warning>

## Cache and queue

Cube Store keeps a key-value cache and a job queue in its cache store. These
commands operate on them directly.

### `CACHE`

Synopsis:

```sql theme={"dark"}
CACHE SET [NX] [TTL ttl] key 'value';
CACHE GET key;
CACHE KEYS prefix;
CACHE INCR key;
CACHE REMOVE key;
CACHE CLEAR;
```

`CACHE SET` stores a value, optionally only if the key doesn't exist (`NX`) and
optionally with a time to live in seconds (`TTL`). `CACHE GET` reads a single
key, `CACHE KEYS` lists keys under a prefix, `CACHE INCR` atomically increments a
counter, and `CACHE REMOVE` deletes a single key.

`CACHE CLEAR` removes every entry by iterating over them and deleting each one.
It requires a cache store healthy enough to be read.

### `QUEUE`

Synopsis:

```sql theme={"dark"}
QUEUE ADD [EXCLUSIVE] [PRIORITY priority] [ORPHANED timeout] [EXTERNAL_ID 'id'] key 'value';
QUEUE ADD_AND_RETRIEVE [EXCLUSIVE] [PRIORITY priority] [ORPHANED timeout] [EXTERNAL_ID 'id'] key 'value' concurrency;
QUEUE GET key;
QUEUE LIST [WITH_PAYLOAD] prefix;
QUEUE PENDING [WITH_PAYLOAD] prefix;
QUEUE ACTIVE [WITH_PAYLOAD] prefix;
QUEUE RESULT [EXTERNAL_ID 'id'] key;
QUEUE RESULT_BLOCKING timeout key;
QUEUE ACK key { result | NULL };
QUEUE CANCEL key;
QUEUE HEARTBEAT key;
QUEUE RETRIEVE [EXTENDED] [CONCURRENCY n] key;
QUEUE STALLED heartbeat_timeout prefix;
QUEUE ORPHANED orphaned_timeout prefix;
QUEUE TO_CANCEL heartbeat_timeout orphaned_timeout prefix;
QUEUE MERGE_EXTRA key 'payload';
QUEUE CLEAR;
```

The queue coordinates pre-aggregation builds. `QUEUE LIST`, `QUEUE PENDING`, and
`QUEUE ACTIVE` inspect it; `QUEUE STALLED`, `QUEUE ORPHANED`, and `QUEUE
TO_CANCEL` list jobs that have stopped making progress. The remaining commands
add, claim, acknowledge, and cancel individual jobs.

`QUEUE ADD`'s options may be given in any order. For `GET`, `ACK`, `CANCEL`,
`HEARTBEAT`, `RESULT`, `RESULT_BLOCKING`, and `MERGE_EXTRA`, `key` is either the
job's path or its numeric queue id.

`QUEUE ADD_AND_RETRIEVE` adds an item and, in the same atomic operation, claims
it — moving it straight to the active status — if the prefix's `concurrency`
budget allows. It combines what otherwise takes a separate `QUEUE ADD`
followed by `QUEUE RETRIEVE`.

`QUEUE CLEAR` empties the queue by iterating over its entries, the same way
`CACHE CLEAR` does.

## Store maintenance and recovery

Cube Store keeps two RocksDB-backed stores: the **metastore**, which holds
pre-aggregation metadata (tables, partitions, indexes, jobs), and the
**cachestore**, which holds the cache and queue above.

### `SYS METASTORE`

Synopsis:

```sql theme={"dark"}
SYS METASTORE HEALTHCHECK;
SYS METASTORE COMPACTION;
SYS METASTORE SET_CURRENT snapshot_id;
SYS METASTORE TRUNCATE;
```

`HEALTHCHECK` verifies the store is readable. `COMPACTION` triggers a RocksDB
compaction. `SET_CURRENT` switches the metastore to a specific snapshot by id.

<Warning>
  `SYS METASTORE TRUNCATE` erases the entire metastore keyspace — all
  pre-aggregation metadata — with a single low-level RocksDB range deletion, with
  no per-row reads. That is precisely why it exists: it still works when the store
  is too damaged to iterate. It is not a cache flush, and it cannot be undone.
</Warning>

### `SYS CACHESTORE`

Synopsis:

```sql theme={"dark"}
SYS CACHESTORE HEALTHCHECK;
SYS CACHESTORE INFO;
SYS CACHESTORE COMPACTION;
SYS CACHESTORE PERSIST;
SYS CACHESTORE EVICTION;
SYS CACHESTORE TRUNCATE;
SYS CACHESTORE WIPE;
```

`HEALTHCHECK` verifies the store is readable and `INFO` reports its current
state. `COMPACTION` triggers a RocksDB compaction, `PERSIST` flushes to durable
storage, and `EVICTION` runs the eviction pass that reclaims space.

<Warning>
  `SYS CACHESTORE TRUNCATE` erases the entire cachestore keyspace — cache and queue
  alike — as a single low-level range deletion, in the same way as `SYS METASTORE
    TRUNCATE` and for the same reason.

  `SYS CACHESTORE WIPE` goes further: it stops the store's background loops, then
  destroys and reopens RocksDB from scratch to force a clean snapshot. Once the
  teardown begins the previous state cannot be restored. If the teardown then fails
  to finish, the cachestore is left closed and rejects every operation until the
  node is restarted. Use it only when the cachestore is unrecoverable by other
  means.
</Warning>

### `SYS`

Synopsis:

```sql theme={"dark"}
SYS KILL ALL JOBS;
SYS REPARTITION partition_id;
SYS DROP CACHE;
SYS DROP QUERY CACHE;
SYS PANIC WORKER;
```

`SYS KILL ALL JOBS` deletes every queued job from the metastore, which is how a
cluster stuck on a wedged build is cleared. `SYS REPARTITION` schedules a
repartition of a single partition by id.

`SYS DROP CACHE` and `SYS DROP QUERY CACHE` both clear the in-memory query result
cache; they are currently equivalent.

`SYS PANIC WORKER` deliberately panics a worker process. It exists for testing
failure handling and has no operational use.

[ref-cube-store-architecture]: /docs/pre-aggregations/cube-store-architecture


# Context variables
Source: https://docs.cube.dev/reference/data-modeling/context-variables

Context variables like CUBE, FILTER_PARAMS, SQL_UTILS, and COMPILE_CONTEXT are available within cube definitions for dynamic SQL and model generation.

* [`CUBE`](#cube) for [referencing members][ref-syntax-references] of the same cube.
* [`FILTER_PARAMS`](#filter_params) and [`FILTER_GROUP`](#filter_group) for optimizing generated SQL queries.
* [`SQL_UTILS`](#sql_utils) for time zone conversion.
* [`COMPILE_CONTEXT`](#compile_context) for creation of [dynamic data models][ref-dynamic-data-models].

## `CUBE`

You can use the `CUBE` context variable to reference columns or members of
the current cube so you don't have to repeat the its name over and over.

It helps [reference members][ref-syntax-references] while keeping the data
model code DRY and easy to maintain.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      joins:
        - name: contacts
          sql: "{CUBE}.contact_id = {contacts.id}"
          relationship: one_to_one

      dimensions:
        - name: id
          sql: "{CUBE}.id"
          type: number
          primary_key: true

        - name: name
          sql: "COALESCE({CUBE.name}, {contacts.name})"
          type: string

    - name: contacts
      sql_table: contacts

      dimensions:
        - name: id
          sql: "{CUBE}.id"
          type: number
          primary_key: true

        - name: name
          sql: "{CUBE}.name"
          type: string









  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    joins: {
      contacts: {
        sql: `${CUBE}.contact_id = ${contacts.id}`,
        relationship: `one_to_one`
      }
    },

    dimensions: {
      id: {
        sql: `${CUBE}.id`,
        type: `number`,
        primary_key: true
      },

      name: {
        sql: `COALESCE(${CUBE}.name, ${contacts.name})`,
        type: `string`
      }
    }
  })

  cube(`contacts`, {
    sql_table: `contacts`,

    dimensions: {
      id: {
        sql: `${CUBE}.id`,
        type: `number`,
        primary_key: true
      },

      name: {
        sql: `${CUBE}.name`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

## `FILTER_PARAMS`

`FILTER_PARAMS` context variable allows you to use [filter][ref-query-filter]
values from the Cube query during SQL generation.

This is useful for hinting your database optimizer to use a specific index
or filter out partitions or shards in your cloud data warehouse so you won't
be billed for scanning those. It can also be useful for constructing [links][ref-links].

<Warning>
  Heavy usage of `FILTER_PARAMS` is considered a bad practice. It usually
  leads to hard-to-maintain data models. Good rule of thumb is to use
  `FILTER_PARAMS` only for predicate pushdown performance optimizations.

  If you find yourself relying a lot on `FILTER_PARAMS`, it might mean that
  you need to rethink your approach to data modeling and potentially move
  some transformations upstream. Also, you might reconsider the choice of the
  data source.
</Warning>

`FILTER_PARAMS` has to be a top-level expression in `WHERE` and it has the
following syntax:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: cube_name
      sql: |
        SELECT *
        FROM table
        WHERE {FILTER_PARAMS.cube_name.member_name.filter(sql_expression)}

      dimensions:
        - name: member_name
          # ...



  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`cube_name`, {
    sql: `
      SELECT *
      FROM table
      WHERE ${FILTER_PARAMS.cube_name.member_name.filter(sql_expression)}
    `,

    dimensions: {
      member_name: {
        // ...
      }
    }
  })
  ```
</CodeGroup>

The `filter()` function accepts `sql_expression`, which could be either
a string or a function returning a string.

### Example with string

See the example below for the case when a string is passed to `filter()`:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: order_facts
      sql: |
        SELECT *
        FROM orders
        WHERE {FILTER_PARAMS.order_facts.date.filter('date')}

      measures:
        - name: count
          type: count

      dimensions:
        - name: date
          sql: date
          type: time





  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`order_facts`, {
    sql: `
      SELECT *
      FROM orders
      WHERE ${FILTER_PARAMS.order_facts.date.filter('date')}
    `,

    measures: {
      count: {
        type: `count`
      }
    },

    dimensions: {
      date: {
        sql: `date`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

This will generate the following SQL...

```sql theme={"dark"}
SELECT COUNT(*) AS orders__count
FROM orders
WHERE
  date >= '2018-01-01 00:00:00' AND
  date <= '2018-12-31 23:59:59'
```

...for the `['2018-01-01', '2018-12-31']` date range passed for the
`order_facts.date` dimension as in following query:

```json theme={"dark"}
{
  "measures": ["order_facts.count"],
  "time_dimensions": [
    {
      "dimension": "order_facts.date",
      "dateRange": ["2018-01-01", "2018-12-31"]
    }
  ]
}
```

### Example with function

You can also pass a function as a `filter()` argument. This way, you can
add BigQuery shard filtering, which will reduce your billing cost.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: events
      sql: |
        SELECT *
        FROM schema.`events*`
        WHERE {FILTER_PARAMS.events.date.filter(
          lambda x, y: f"""
            _TABLE_SUFFIX >= FORMAT_TIMESTAMP('%Y%m%d', TIMESTAMP({x})) AND
            _TABLE_SUFFIX <= FORMAT_TIMESTAMP('%Y%m%d', TIMESTAMP({y}))
          """
        )}

      dimensions:
        - name: date
          sql: date
          type: time
          


  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`events`, {
    sql: `
      SELECT *
      FROM schema.\`events*\`
      WHERE ${FILTER_PARAMS.events.date.filter(
        (x, y) => `
          _TABLE_SUFFIX >= FORMAT_TIMESTAMP('%Y%m%d', TIMESTAMP(${x})) AND
          _TABLE_SUFFIX <= FORMAT_TIMESTAMP('%Y%m%d', TIMESTAMP(${y}))
        `
      )}
    `,

    dimensions: {
      date: {
        sql: `date`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

<Info>
  When a function is passed to `filter()`, its arguments are passed as
  strings from the data source driver and it's your responsibility to handle
  type conversions in this case.
</Info>

In the example above, the filter on a time dimension accepts two values: the
lower and the upper bounds of a date range. If a filter accepts multiple values,
they are passed to the function as individual parameters:

```javascript theme={"dark"}
cube(`multi_filter`, {
  sql: `
    SELECT 123 AS value
    -- Multiple values: ${FILTER_PARAMS.multi_filter.dummy.filter(
      (...args) => JSON.stringify(args)
    )}
  `,

  dimensions: {
    dummy: {
      sql: `1`,
      type: `number`
    }
  }
})
```

### Example with segment

A `FILTER_PARAMS` argument can also name a [segment][ref-ref-segments]. A segment
is not compared to a value, so the expression passed to `filter()` is the whole
predicate rather than a column: it is rendered as-is when the query selects that
segment, and as `1 = 1` when it does not.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: events
      sql: |
        SELECT *
        FROM events
        WHERE {FILTER_PARAMS.events.start_load.filter(
          "evid = 115 AND action_group = 'load'"
        )}

      segments:
        - name: start_load
          sql: "{CUBE}.evid = 115 AND {CUBE}.action_group = 'load'"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`events`, {
    sql: `
      SELECT *
      FROM events
      WHERE ${FILTER_PARAMS.events.start_load.filter(
        `evid = 115 AND action_group = 'load'`
      )}
    `,

    segments: {
      start_load: {
        sql: `${CUBE}.evid = 115 AND ${CUBE}.action_group = 'load'`
      }
    }
  })
  ```
</CodeGroup>

The segment's own `sql` prefixes its columns with the cube, which is not in
scope inside the `sql` that builds that cube, so the pushed-down predicate is
restated in `filter()` — the same way a dimension's column is.

A function may be passed instead of a string, as long as it takes no arguments:
a segment carries no filter values to pass to it. A function that does take
arguments renders as `1 = 1`.

<Info>
  Naming a segment is only supported by the default SQL planner. With
  [`CUBEJS_TESSERACT_SQL_PLANNER`][ref-env-tesseract] set to `false`, such a
  binding always renders as `1 = 1`.
</Info>

### Example with a time shift

A measure with a [`time_shift`][ref-ref-time-shift] over a
[calendar cube][ref-calendar-cubes] reads a different period than the one the
query reports: which rows those are is held in the calendar's own table, and no
expression over the source column reproduces it. A binding that restated the
reported period there would narrow the scan past the rows that period needs, so
it does not render — the shift has to be addressed explicitly:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: sales
      sql: |
        SELECT *
        FROM sales
        WHERE {FILTER_GROUP(
          FILTER_PARAMS.fiscal_calendar.report_date.filter('day_date'),
          FILTER_PARAMS.fiscal_calendar.report_date.time_shifts.prev_fiscal_year.filter(
            lambda x, y: f"day_date >= {x}::date - 364 AND day_date <= {y}::date - 364"
          )
        )}
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`sales`, {
    sql: `
      SELECT *
      FROM sales
      WHERE ${FILTER_GROUP(
        FILTER_PARAMS.fiscal_calendar.report_date.filter(`day_date`),
        FILTER_PARAMS.fiscal_calendar.report_date.time_shifts.prev_fiscal_year.filter(
          (from, to) => `day_date >= ${from}::date - 364 AND day_date <= ${to}::date - 364`
        )
      )}
    `
  })
  ```
</CodeGroup>

Each binding renders in one place only: the plain one where no calendar shift
is applied, and `time_shifts.prev_fiscal_year` where that shift is. Where the
model declares no binding for the shift a query applies, nothing is pushed down
and the cube's `sql` scans unrestricted — correct, but without the narrowing.

The name is the one the calendar cube gives the shift in its dimension's
`time_shift`, and it is reached whether the measure asks for that shift by name
or by the interval the calendar declares it with. The bounds passed to the
callback are the reported ones, unshifted: the model states which rows its own
table holds for that period. A `time_shifts` binding therefore takes a function
of both bounds — a string column cannot express a mapping, and a query filtering
the member with anything but a date range is an error.

An interval shift on a dimension that is not part of a calendar cube needs none
of this: the plain binding renders there, with the interval applied to the
column.

<Info>
  Addressing a time shift is only supported by the default SQL planner. With
  [`CUBEJS_TESSERACT_SQL_PLANNER`][ref-env-tesseract] set to `false`, such a
  binding always renders as `1 = 1`.
</Info>

## `FILTER_GROUP`

If you use `FILTER_PARAMS` in your query more than once, you must wrap them
with `FILTER_GROUP`.

<Warning>
  Otherwise, if you combine `FILTER_PARAMS` with any logical operators other than
  `AND` in SQL or if you use filters with [boolean operators][ref-filter-boolean]
  in your Cube queries, incorrect SQL might be generated.
</Warning>

`FILTER_GROUP` has to be a top-level expression in `WHERE` and it has the
following syntax:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: cube_name
      sql: |
        SELECT *
        FROM table
        WHERE {FILTER_GROUP(
          FILTER_PARAMS.cube_name.member_name.filter(sql_expression),
          FILTER_PARAMS.cube_name.another_member_name.filter(sql_expression)
        )}

      dimensions:
        - name: member_name
          # ...

        - name: another_member_name
          # ...




  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`cube_name`, {
    sql: `
      SELECT *
      FROM table
      WHERE ${FILTER_GROUP(
        FILTER_PARAMS.cube_name.member_name.filter(sql_expression),
        FILTER_PARAMS.cube_name.another_member_name.filter(sql_expression)
      )}
    `,

    dimensions: {
      member_name: {
        // ...
      },
      
      another_member_name: {
        // ...
      }
    }
  })
  ```
</CodeGroup>

### Example

To understand the value of `FILTER_GROUP`, consider the following data model
where two `FILTER_PARAMS` are combined in SQL using the `OR` operator:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: filter_group
      sql: |
        SELECT *
          FROM (
            SELECT 1 AS a, 3 AS b UNION ALL
            SELECT 2 AS a, 2 AS b UNION ALL
            SELECT 3 AS a, 1 AS b
          ) AS data
          WHERE
            {FILTER_PARAMS.filter_group.a.filter("a")} OR
            {FILTER_PARAMS.filter_group.b.filter("b")}

      dimensions:
        - name: a
          sql: a
          type: number

        - name: b
          sql: b
          type: number




  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`filter_group`, {
    sql: `
      SELECT *
        FROM (
          SELECT 1 AS a, 3 AS b UNION ALL
          SELECT 2 AS a, 2 AS b UNION ALL
          SELECT 3 AS a, 1 AS b
        ) AS data
        WHERE
          ${FILTER_PARAMS.filter_group.a.filter('a')} OR
          ${FILTER_PARAMS.filter_group.b.filter('b')}
    `,

    dimensions: {
      a: {
        sql: `a`,
        type: `number`
      },

      b: {
        sql: `b`,
        type: `number`
      }
    }
  })
  ```
</CodeGroup>

If the following query is run...

```json theme={"dark"}
{
  "dimensions": [
    "filter_group.a",
    "filter_group.b"
  ],
  "filters": [
    {
      "member": "filter_group.a",
      "operator": "gt",
      "values": ["1"]
    },
    {
      "member": "filter_group.b",
      "operator": "gt",
      "values": ["1"]
    }
  ]
}
```

...the following (logically incorrect) SQL will be generated:

```sql theme={"dark"}
SELECT
  "filter_group".a,
  "filter_group".b
FROM (
  SELECT *
  FROM (
    SELECT 1 AS a, 3 AS b UNION ALL
    SELECT 2 AS a, 2 AS b UNION ALL
    SELECT 3 AS a, 1 AS b
  ) AS data
  WHERE
    (a > 1) OR  -- Incorrect logical operator here
    (b > 1)
) AS "filter_group"
WHERE
  "filter_group".a > 1 AND
  "filter_group".b > 1
GROUP BY 1, 2
```

As you can see, since an array of filters has `AND` semantics, Cube has
correctly used the `AND` operator in the "outer" `WHERE`. At the same time,
the hardcoded `OR` operator has propagated to the "inner" `WHERE`, leading to
a logically incorrect query.

Now, if the cube is defined the following way...

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: filter_group
      sql: |
        SELECT *
          FROM (
            SELECT 1 AS a, 3 AS b UNION ALL
            SELECT 2 AS a, 2 AS b UNION ALL
            SELECT 3 AS a, 1 AS b
          ) AS data
          WHERE
            {FILTER_GROUP(
              FILTER_PARAMS.filter_group.a.filter("a"),
              FILTER_PARAMS.filter_group.b.filter("b")
            )}

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`filter_group`, {
    sql: `
      SELECT *
        FROM (
          SELECT 1 AS a, 3 AS b UNION ALL
          SELECT 2 AS a, 2 AS b UNION ALL
          SELECT 3 AS a, 1 AS b
        ) AS data
        WHERE
          ${FILTER_GROUP(
            FILTER_PARAMS.filter_group.a.filter('a'),
            FILTER_PARAMS.filter_group.b.filter('b')
          )}
    `,

    // ...
  ```
</CodeGroup>

...the following correct SQL will be generated for the same query:

```sql theme={"dark"}
SELECT
  "filter_group".a,
  "filter_group".b
FROM (
  SELECT *
  FROM (
    SELECT 1 AS a, 3 AS b UNION ALL
    SELECT 2 AS a, 2 AS b UNION ALL
    SELECT 3 AS a, 1 AS b
  ) AS data
  WHERE
    (a > 1) AND  -- Correct logical operator here
    (b > 1)
) AS "filter_group"
WHERE
  "filter_group".a > 1 AND
  "filter_group".b > 1
GROUP BY 1, 2
```

You can also use [boolean operators][ref-filter-boolean] in the Cube query
to express more complex filtering logic:

```json theme={"dark"}
{
  "dimensions": [
    "filter_group.a",
    "filter_group.b"
  ],
  "filters": [
    {
      "or": [
        {
          "member": "filter_group.a",
          "operator": "gt",
          "values": ["1"]
        },
        {
          "member": "filter_group.b",
          "operator": "gt",
          "values": ["1"]
        }
      ]
    }
  ]
}
```

With `FILTER_GROUP`, the following correct SQL will be generated:

```sql theme={"dark"}
SELECT
  "filter_group".a,
  "filter_group".b
FROM (
  SELECT *
  FROM (
    SELECT 1 AS a, 3 AS b UNION ALL
    SELECT 2 AS a, 2 AS b UNION ALL
    SELECT 3 AS a, 1 AS b
  ) AS data
  WHERE
    (a > 1) OR
    (b > 1)
) AS "filter_group"
WHERE
  "filter_group".a > 1 OR
  "filter_group".b > 1
GROUP BY 1, 2
```

## `SQL_UTILS`

### `convertTz`

In case you need to convert your timestamp to user request timezone in cube or
member SQL you can use `SQL_UTILS.convertTz()` method. Note that Cube will
automatically convert timezones for `timeDimensions` fields in
[queries](/reference/core-data-apis/rest-api/query-format#query-properties).

<Warning>
  Dimensions that use `SQL_UTILS.convertTz()` should not be used as
  `timeDimensions` in queries. Doing so will apply the conversion multiple times
  and yield wrong results.
</Warning>

In case the same database field needs to be queried in `dimensions` and
`timeDimensions`, create dedicated dimensions in the cube definition for the
respective use:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: visitors
      # ...

      dimensions:
        # Do not use in timeDimensions query property
        - name: created_at_converted
          sql: "{SQL_UTILS.convertTz(`created_at`)}"
          type: time

        # Use in timeDimensions query property
        - name: created_at
          sql: created_at
          type: time



  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`visitors`, {
    // ...

    dimensions: {
      // Do not use in timeDimensions query property
      created_at_converted: {
        sql: SQL_UTILS.convertTz(`created_at`),
        type: `time`
      },

      // Use in timeDimensions query property
      created_at: {
        sql: `created_at`,
        type: "time"
      }
    }
  })
  ```
</CodeGroup>

## `COMPILE_CONTEXT`

<Warning>
  `COMPILE_CONTEXT` is evaluated only once per each key generated by `context_to_app_id`.
  The `securityContext` defined in `COMPILE_CONTEXT` doesn't change
  its value for different users, however, it will change for
  different tenants as defined in `context_to_app_id`.
</Warning>

A global `COMPILE_CONTEXT` contains `securityContext` and any other variables provided by
[`extendContext`][ref-config-ext-ctx].

Use [Jinja][ref-dynamic-jinja] `{{ }}` syntax to access `COMPILE_CONTEXT` variable.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: "user_{{ COMPILE_CONTEXT.securityContext.deployment_id }}.users"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `user_${COMPILE_CONTEXT.securityContext.deployment_id}.users`
  })
  ```
</CodeGroup>

## `SECURITY_CONTEXT`

<Warning>
  **`SECURITY_CONTEXT` is deprecated and can be removed without further notice.**
  Use [`query_rewrite`][ref-config-queryrewrite] instead.
</Warning>

`SECURITY_CONTEXT` global variable holds a security context that is passed to Cube via API.
Please read the [Security Context page][ref-sec-ctx] for more information on how
to provide security context to Cube.

```javascript theme={"dark"}
cube(`orders`, {
  sql: `
    SELECT *
    FROM orders
    WHERE ${SECURITY_CONTEXT.email.filter("email")}
  `,

  dimensions: {
    date: {
      sql: `date`,
      type: `time`
    }
  }
})
```

To ensure filter value presents for all requests `requiredFilter` can be used:

```javascript theme={"dark"}
cube(`orders`, {
  sql: `
    SELECT *
    FROM orders
    WHERE ${SECURITY_CONTEXT.email.requiredFilter("email")}
  `,

  dimensions: {
    date: {
      sql: `date`,
      type: `time`
    }
  }
})
```

You can access values of context variables directly in JavaScript in order to
use it during your SQL generation. For example:

<Warning>
  Use of this feature entails SQL injection security risk. Use it with caution.
</Warning>

```javascript theme={"dark"}
cube(`orders`, {
  sql: `
    SELECT *
    FROM ${
      SECURITY_CONTEXT.type.unsafeValue() === "employee" ? "employee" : "public"
    }.orders
  `,

  dimensions: {
    date: {
      sql: `date`,
      type: `time`
    }
  }
})
```

[ref-config-ext-ctx]: /reference/configuration/config#extendcontext

[ref-config-queryrewrite]: /reference/configuration/config#query_rewrite

[ref-sec-ctx]: /docs/data-modeling/access-control/context

[ref-ref-cubes]: /reference/data-modeling/cube

[ref-syntax-references]: /docs/data-modeling/concepts/syntax#references

[ref-dynamic-data-models]: /docs/data-modeling/dynamic/jinja

[ref-query-filter]: /reference/core-data-apis/rest-api/query-format#query-properties

[ref-dynamic-jinja]: /docs/data-modeling/dynamic/jinja

[ref-filter-boolean]: /reference/core-data-apis/rest-api/query-format#boolean-logical-operators

[ref-links]: /reference/data-modeling/dimensions#links

[ref-ref-segments]: /reference/data-modeling/segments

[ref-env-tesseract]: /reference/configuration/environment-variables#cubejs_tesseract_sql_planner

[ref-ref-time-shift]: /reference/data-modeling/measures#time_shift

[ref-calendar-cubes]: /docs/data-modeling/concepts/calendar-cubes


# Cubes
Source: https://docs.cube.dev/reference/data-modeling/cube

Cubes represent tables of data. Each cube contains measures, dimensions, joins, pre-aggregations, and access policies.

Cubes are typically declared in separate files with one cube per file.
Within each cube are definitions of [measures][ref-ref-measures],
[dimensions][ref-ref-dimensions], [hierarchies][ref-ref-hierarchies],
[segments][ref-ref-segments], [joins][ref-ref-joins] between cubes,
[pre-aggregations][ref-ref-pre-aggs], and [access policies][ref-ref-dap].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      joins:
        - name: organizations
          relationship: many_to_one
          sql: "{CUBE.organization_id} = {organizations.id}"

      measures:
        - name: count
          type: count
          sql: id

      dimensions:
        - name: organization_id
          sql: organization_id
          type: number
          primary_key: true

        - name: created_at
          sql: created_at
          type: time

        - name: country
          sql: country
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    joins: {
      organizations: {
        relationship: `many_to_one`,
        sql: `${users.organization_id} = ${organizations.id}`
      }
    },

    measures: {
      count: {
        type: `count`,
        sql: `id`
      }
    },

    dimensions: {
      organization_id: {
        sql: `organization_id`,
        type: `number`,
        primary_key: true
      },

      created_at: {
        sql: `created_at`,
        type: `time`
      },

      country: {
        sql: `country`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

## Parameters

### `name`

The `name` parameter serves as the identifier of a cube. It must be unique among
*all cubes and views* within a deployment and follow the [naming
conventions][ref-naming].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: orders
  })
  ```
</CodeGroup>

### `sql_alias`

Use `sql_alias` when auto-generated cube alias prefix is too long and truncated
by databases such as Postgres:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: order_facts_about_literally_everything_in_the_world
      sql_table: orders
      sql_alias: order_facts
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`order_facts_about_literally_everything_in_the_world`, {
    sql_table: `orders`,
    sql_alias: `order_facts`
  })
  ```
</CodeGroup>

It'll generate aliases for members such as `order_facts__count`. `sql_alias` affects
all member names including pre-aggregation table names.

### `extends`

You can use the `extends` parameter to [extend cubes][ref-extension] in order to reuse
all declared members of a cube.

In the example below, `extended_order_facts` will reuse the `sql` and `count` measures
from `order_facts`:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: order_facts
      sql_table: orders

      measures:
        - name: count
          type: count
          sql: id

    - name: extended_order_facts
      extends: order_facts

      measures:
        - name: double_count
          type: number
          sql: "{count} * 2"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`order_facts`, {
    sql_table: `orders`,

    measures: {
      count: {
        type: `count`,
        sql: `id`
      }
    }
  })

  cube(`extended_order_facts`, {
    extends: order_facts,

    measures: {
      double_count: {
        type: `number`,
        sql: `${count} * 2`
      }
    }
  })
  ```
</CodeGroup>

You can also omit the cube name while defining a cube in JavaScript. This way,
Cube doesn't register this cube globally; instead it returns a reference which
you can use while combining cubes. It makes sense to use it for dynamic data
model generation and reusing with `extends`. Previous example without defining
`order_facts` cube globally:

```javascript theme={"dark"}
const order_facts = cube({
  sql: `orders`,

  measures: {
    count: {
      type: `count`,
      sql: `id`
    }
  }
})

cube(`extended_order_facts`, {
  extends: order_facts,

  measures: {
    double_count: {
      type: `number`,
      sql: `${count} * 2`
    }
  }
})
```

### `data_source`

Each cube can have its own `data_source` name to support scenarios where data
should be fetched from multiple databases. The value of the `data_source`
parameter will be passed to the [`driverFactory()`][ref-config-driverfactory]
function as part of the `context` parameter. By default, each cube has a
`default` value for its `data_source`; to override it you can use:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: order_facts
      data_source: prod_db
      sql_table: orders
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`order_facts`, {
    data_source: `prod_db`,
    sql_table: `orders`
  })
  ```
</CodeGroup>

### `sql`

The `sql` parameter specifies the SQL that will be used to generate a table that
will be queried by a cube. It can be any valid SQL query, but usually it takes
the form of a `SELECT * FROM my_table` query. Please note that you don't need to
use `GROUP BY` in a SQL query on the cube level. This query should return a
plain table, without aggregations.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql: SELECT * FROM orders
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql: `SELECT * FROM orders`
  })
  ```
</CodeGroup>

You can also reference other cubes' SQL statements for code reuse using the
[`{cube.sql()}`][ref-syntax-cube-sql] function:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: companies
      sql:
        SELECT
          users.company_name,
          users.company_id
        FROM {users.sql()} AS users
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`companies`, {
    sql: `
      SELECT
        users.company_name,
        users.company_id
      FROM ${users.sql()} AS users
    `
  })
  ```
</CodeGroup>

It is recommended to prefer the [`sql_table`](#sql_table) parameter
over the `sql` parameter for all cubes that are supposed to use queries like
this: `SELECT * FROM table`.

### `sql_table`

The `sql_table` parameter is used as a concise way for defining a cube that uses
a query like this: `SELECT * FROM table`. Instead of using the
[`sql`](#sql) parameter, use `sql_table` with the table name that this
cube will query.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: public.orders
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `public.orders`
  })
  ```
</CodeGroup>

### `title`

Use the `title` parameter to change the display name of the cube.

By default, Cube will humanize the cube's name, so for instance, `users_orders`
would become `Users Orders`. If default humanizing doesn't work in your case,
please use the `title` parameter. It is highly recommended to give human readable
names to your cubes. It will help everyone on a team better understand the data
structure and will help maintain a consistent set of definitions across an
organization.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders
      title: Product Orders
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,
    title: `Product Orders`
  })
  ```
</CodeGroup>

### `description`

This parameter provides a human-readable description of a cube.
When applicable, it will be displayed in [Playground][ref-playground] and exposed
to data consumers via [APIs and integrations][ref-apis].

A description can give a hint both to your team and end users, making sure they
interpret the data correctly.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders
      title: Product Orders
      description: All orders-related information
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,
    title: `Product Orders`,
    description: `All orders-related information`
  })
  ```
</CodeGroup>

### `public`

The `public` parameter is used to manage the visibility of a cube. Valid values
for `public` are `true` and `false`. When set to `false`, this cube **cannot**
be queried through the API. Defaults to `true`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: public.orders
      public: false
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `public.orders`,
    public: false
  })
  ```
</CodeGroup>

To learn more about using `public` to control visibility based on security
context, read the [Controlling access to cubes and views
recipe][ref-recipe-control-access-cubes-views].

### `refresh_key`

Cube's caching layer uses `refresh_key` queries to get the current version of
content for a specific cube. If a query result changes, Cube will invalidate all
queries that rely on that cube.

The default values for `refresh_key` are

* `every: '2 minute'` for BigQuery, Athena, Snowflake, Presto, and Firebolt.
* `every: '10 second'` for all other databases.

Refresh key of a query is a concatenation of all cubes refresh keys involved in
query. For rollup queries pre-aggregation table name is used as a refresh key.

You can set up a custom refresh check SQL by changing the `refresh_key` parameter.
Often, a `MAX(updated_at_timestamp)` for OLTP data is a viable option, or
examining a metadata table for whatever system is managing the data to see when
it last ran. timestamp in that case.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: order_facts
      sql_table: orders
      refresh_key:
        sql: SELECT MAX(updated_at_timestamp) FROM orders
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`order_facts`, {
    sql_table: `orders`,

    // With this refresh_key Cube will only refresh the data if
    // the value of previous MAX(updated_at_timestamp) changed.
    // By default Cube will check this refreshKey every 10 seconds
    refresh_key: {
      sql: `SELECT MAX(updated_at_timestamp) FROM orders`
    }
  })
  ```
</CodeGroup>

You can use interval-based `refresh_key`. For example:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: order_facts
      sql_table: orders
      refresh_key:
        every: 1 hour
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`order_facts`, {
    sql_table: `orders`,

    refresh_key: {
      every: `1 hour`
    }
  })
  ```
</CodeGroup>

<Warning>
  The `every` parameter guarantees that the refresh key will be executed **at
  least** once during the specified interval. However, it does **not** guarantee
  that it will be executed **at most** once. The refresh key may be checked more
  frequently.

  When using `every` with `sql`, the purpose is to reduce the load from running
  the refresh key query itself, not to minimize the number of cache
  refreshes. The refresh key SQL should be designed to return consistent results
  and only change when the underlying data needs to be updated, ensuring minimal
  refreshes even if the query is executed multiple times.
</Warning>

`every` - can be set as an interval with granularities `second`, `minute`,
`hour`, `day`, and `week` or accept CRON string with some limitations. If you
set `every` as CRON string, you can use the `timezone` parameter. It takes
precedence over the query timezone.

For example:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: order_facts
      sql_table: orders

      refresh_key:
        every: 30 5 * * 5
        timezone: America/Los_Angeles
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`order_facts`, {
    sql_table: `orders`,

    refresh_key: {
      every: "30 5 * * 5",
      timezone: "America/Los_Angeles"
    }
  })
  ```
</CodeGroup>

`every` can accept only equal time intervals - so "Day of month" and "month"
intervals in CRON expressions are not supported.

<Warning>
  Cube supports two different formats of CRON expressions: standard and advanced
  with support for seconds.
</Warning>

Such `refresh_key` is just a syntactic sugar over `refresh_key` SQL. It's
guaranteed that `refresh_key` change it's value at least once during `every`
interval. It will be converted to appropriate SQL select which value will change
over time based on interval value. Values of interval based `refresh_key` are
tried to be checked ten times within defined interval but not more than once per
`1 second` and not less than once per `5 minute`. For example if interval is
`10 minute` it's `refreshKeyRenewalThreshold` will be 60 seconds and generated
`refresh_key` SQL (Postgres) would be:

```sql theme={"dark"}
SELECT FLOOR(EXTRACT(EPOCH FROM NOW()) / 600)
```

For `5 second` interval `refreshKeyRenewalThreshold` will be just 1 second and
SQL will be:

```sql theme={"dark"}
SELECT FLOOR(EXTRACT(EPOCH FROM NOW()) / 5)
```

#### Supported cron formats

* Standard cron syntax

```text theme={"dark"}
*    *    *    *    *
┬    ┬    ┬    ┬    ┬
│    │    │    │    |
│    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)
│    │    │    └───── month (1 - 12)
│    │    └────────── day of month (1 - 31, L)
│    └─────────────── hour (0 - 23)
└──────────────────── minute (0 - 59)
```

* Advanced cron format with support for seconds

```text theme={"dark"}
*    *    *    *    *    *
┬    ┬    ┬    ┬    ┬    ┬
│    │    │    │    │    |
│    │    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)
│    │    │    │    └───── month (1 - 12)
│    │    │    └────────── day of month (1 - 31, L)
│    │    └─────────────── hour (0 - 23)
│    └──────────────────── minute (0 - 59)
└───────────────────────── second (0 - 59, optional)
```

### `meta`

Custom metadata. Can be used to pass any information to the frontend.

You can also use the `ai_context` key to provide context to the
[AI agent][ref-ai-context] without exposing it in the user interface.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders
      title: Product Orders
      meta:
        any: value
        ai_context: >
          This cube contains all e-commerce orders. When users ask
          about revenue, prefer the total_revenue measure.

  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,
    title: `Product Orders`,
    meta: {
      any: `value`,
      ai_context: `This cube contains all e-commerce orders. When users ask
        about revenue, prefer the total_revenue measure.`
    }
  })
  ```
</CodeGroup>

### `calendar`

The `calendar` parameter is used to mark [calendar cubes][ref-calendar-cubes].
It's set to `false` by default.

When set to `true`, Cube will treat this cube as a calendar cube and allow to
[override time-shifts][ref-calendar-cubes-time-shifts] and [granularities][ref-calendar-cubes-granularities]
on its [time dimensions][ref-time-dimensions]. This can be useful for [time-shift
calculations][ref-time-shift] with a custom calendar.

### `pre_aggregations`

The `pre_aggregations` parameter is used to configure [pre-aggregations][ref-ref-pre-aggs].

### `joins`

The `joins` parameter is used to configure [joins][ref-ref-joins].

### `dimensions`

The `dimensions` parameter is used to configure [dimensions][ref-ref-dimensions].

### `hierarchies`

The `hierarchies` parameter is used to configure [hierarchies][ref-ref-hierarchies].

### `segments`

The `segments` parameter is used to configure [segments][ref-ref-segments].

### `measures`

The `measures` parameter is used to configure [measures][ref-ref-measures].

### `access_policy`

The `access_policy` parameter is used to configure [access policies][ref-ref-dap].

[ref-ai-context]: /docs/data-modeling/ai-context

[ref-config-driverfactory]: /reference/configuration/config#driver_factory

[ref-recipe-control-access-cubes-views]: /docs/data-modeling/access-control

[ref-naming]: /docs/data-modeling/concepts/syntax#naming

[ref-playground]: /docs/explore-analyze/playground

[ref-apis]: /reference

[ref-ref-measures]: /reference/data-modeling/measures

[ref-ref-dimensions]: /reference/data-modeling/dimensions

[ref-ref-hierarchies]: /reference/data-modeling/hierarchies

[ref-ref-segments]: /reference/data-modeling/segments

[ref-ref-joins]: /reference/data-modeling/joins

[ref-ref-pre-aggs]: /reference/data-modeling/pre-aggregations

[ref-ref-dap]: /reference/data-modeling/data-access-policies

[ref-syntax-cube-sql]: /docs/data-modeling/concepts/syntax#cubesql-function

[ref-extension]: /docs/data-modeling/extending-cubes

[ref-calendar-cubes]: /docs/data-modeling/concepts/calendar-cubes

[ref-calendar-cubes-time-shifts]: /docs/data-modeling/concepts/calendar-cubes#overriding-time-shifts

[ref-calendar-cubes-granularities]: /docs/data-modeling/concepts/calendar-cubes#overriding-granularities

[ref-time-dimensions]: /docs/data-modeling/dimensions#time-dimensions

[ref-time-shift]: /docs/data-modeling/measures#time-shift


# `cube` package
Source: https://docs.cube.dev/reference/data-modeling/cube-package

The cube Python package provides tools for setting configuration options and the Jinja template context for YAML data models.

`cube` package contains tools for setting [configuration
options][ref-config-options] and providing the Jinja template context for
the data model in [YAML][ref-model-syntax].

* `cube` package is available out of the box, it doesn't need to be installed explicitly
* Submit issues to [`cube`][link-cube-repo-issues] on GitHub

## Reference

### `config` object

This object is used to set configuration options in the `cube.py` file.

You can set properties of this object, named after supported [configuration
options][ref-ref-config-options], to values or functions that would be used
as these configuration options.

```python theme={"dark"}
from cube import config

config.base_path = '/cube-api'

config.context_to_app_id = lambda ctx: ctx['securityContext']['tenant_id']

def rewrite(query, ctx):
  query['measures'].append('orders.count')
  return query

config.query_rewrite = rewrite
```

Alternatively, this object can be used as a decorator with a single
`name` argument. In that case, the decorated function will be set as the
configuration option under that `name`.

```python theme={"dark"}
from cube import config

@config('context_to_app_id')
def app_id(ctx):
  return ctx['securityContext']['tenant_id']

@config('query_rewrite')
def rewrite(query, ctx):
  query['measures'].append('orders.count')
  return query
```

### `TemplateContext` class

Instances of this class are used for registering variables, functions, and
filters so that they are accessible from Jinja templates when defining the
data model in YAML.

```python theme={"dark"}
from cube import TemplateContext

template = TemplateContext()
```

#### `add_variable`

The `add_variable` method registers a variable so that it's available in
a Jinja template. Should be called with two arguments, a `name` and a `value`
of the variable.

```python theme={"dark"}
from cube import TemplateContext

template = TemplateContext()

# Accessible from Jinja as 'my_var'
template.add_variable('my_var', 123)
```

#### `add_function` and `function`

The `add_function` method registers a function so that it's callable from
a Jinja template as a Python function. Should be called with two arguments,
a `name` and a function that will be registered under that `name`:

```python theme={"dark"}
from cube import TemplateContext

template = TemplateContext()

# Accessible from Jinja as 'get_data()'
def get_data_1():
  return 1
template.add_function('get_data', get_data_1)
```

Also, you can use the `template.function` decorator with a single `name`
argument; the decorated function will be registered under that `name`:

```python theme={"dark"}
from cube import TemplateContext

template = TemplateContext()

# Accessible from Jinja as 'get_more_data()'
@template.function('get_more_data')
def get_data_2():
  return 2
```

#### `add_filter` and `filter`

The `add_filter` method registers a function so that it's callable from
a Jinja template as a [Jinja filter][link-jinja-filters]. Should be called
with two arguments, a `name` and a function that will be registered as a filter
under that `name`:

```python theme={"dark"}
from cube import TemplateContext

template = TemplateContext()

# Accessible from Jinja as 'data | wrap'
def wrap_1(data):
  return f"< {data} >"
template.add_filter('wrap', wrap_1)
```

Also, you can use the `template.filter` decorator with a single `name`
argument; the decorated function will be registered as a filter under that
`name`:

```python theme={"dark"}
from cube import TemplateContext

template = TemplateContext()

# Accessible from Jinja as 'data | wrap_more'
@template.filter('wrap_more')
def wrap_2(data):
  return f"<<< {data} >>>"
```

[link-cube-repo-issues]: https://github.com/cube-js/cube/issues

[link-jinja-filters]: https://jinja.palletsprojects.com/en/3.1.x/templates/#filters

[ref-config-options]: /admin/connect-to-data#configuration-options

[ref-ref-config-options]: /reference/configuration/config

[ref-model-syntax]: /docs/data-modeling/concepts/syntax#model-syntax


# `cube_dbt` package
Source: https://docs.cube.dev/reference/data-modeling/cube_dbt

cube_dbt is a Python package for loading dbt project metadata and generating Cube data models from dbt models.

`cube_dbt` package simplifies defining the data model in the semantic layer
on top of [dbt][link-dbt-docs] models. It provides convenient tools for
loading the metadata of a dbt project, inspecting dbt models, and rendering
them as [cubes][ref-cubes] in [YAML][ref-model-syntax].

* Install [`cube_dbt`][link-cube-dbt-pypi] package from PyPI
* Check the source code in [`cube_dbt`][link-cube-dbt-repo] on GitHub
* Submit issues to [`cube`][link-cube-repo-issues] on GitHub

## Installation

### Cube Cloud

Add the `cube_dbt` package to the `requirements.txt` file in the root
directory of your Cube project. Cube Cloud will install the dependencies
automatically.

## Reference

### `Dbt` class

Encapsulates tools for working with the metadata of a dbt project.

#### `Dbt.__init__`

The constructor accepts the metadata of a dbt project as a `dict` with the
contents of a [`manifest.json` file][link-dbt-manifest].

```python theme={"dark"}
import json
from cube_dbt import Dbt

manifest_path = './manifest.json'

with open(manifest_path, 'r') as file:
  manifest = json.loads(file.read())
  dbt = Dbt(manifest)
```

Use in cases when `Dbt.from_file` and `Dbt.from_url` aren't applicable,
e.g., when `manifest.json` is loaded from a private AWS S3 bucket.

#### `Dbt.from_file`

This static method loads the metadata of a dbt project from a `manifest.json`
file by its path and returns an instance of the `Dbt` class.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_path = './manifest.json'

dbt = Dbt.from_file(manifest_path)
```

#### `Dbt.from_url`

This static method loads the metadata of a dbt project from a `manifest.json`
file by its URL and returns an instance of the `Dbt` class.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
```

#### `Dbt.filter`

This method filters loaded dbt models by their path prefixes, tags, or names.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url).filter(
  paths=['marts/'],  # Only models under the 'marts/' path
  tags=['cube'],     # Only models with the 'cube' tag
  names=['orders']   # Only the 'orders' model 
)
```

Use to expose only necessary dbt models to the semantic layer.

Note that values in `paths` should not be prefixed with `models/`.

#### `Dbt.models`

This property exposes a list of loaded dbt models as instances of the
`Model` class.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)

for model in dbt.models:
  print(model)
```

Only dbt models that comply with `Dbt.filter` rules and are not
materialized as [ephemeral][link-dbt-materializations] will be returned.

#### `Dbt.model`

This method returns a loaded dbt model by its name as an instance of the
`Model` class.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)

model = dbt.model('orders')
print(model)
```

Only dbt models that comply with `Dbt.filter` rules and are not
materialized as [ephemeral][link-dbt-materializations] will be returned.

### `Model` class

Encapsulates tools for working with the metadata of a dbt model.

#### `Model.name`

This property exposes the name of a dbt model.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
model = dbt.model('orders')

print(model.name)
# For example, 'orders'
```

#### `Model.description`

This property exposes the description of a dbt model.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
model = dbt.model('orders')

print(model.description)
# For example, 'All Jaffle Shop orders'
```

#### `Model.sql_table`

This property exposes the fully-qualified SQL relation name of a dbt model
that can be used as the [`sql_table` parameter][ref-cube-sql-table] of a cube.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
model = dbt.model('orders')

print(model.sql_table)
# For example, '"db"."public"."orders"'
```

#### `Model.columns`

This property exposes a list of columns that belong to this dbt model as
instances of the `Column` class.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
model = dbt.model('orders')

for column in model.columns:
  print(column)
```

#### `Model.column`

This method exposes a column that belongs to this dbt model by its name as
an instance of the `Column` class.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
model = dbt.model('orders')

column = model.column('status')
print(column)
```

#### `Model.primary_key`

This method returns the primary key column, if this dbt model has any, as an
instance of the `Column` class. Returns `None` if there's no primary key in
this dbt model.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
model = dbt.model('orders')

print(model.primary_key)
```

See [`Column.primary_key`][self-column-pk] for details on the detection of
primary key columns.

#### `Model.as_cube`

This method renders this dbt model as a YAML snippet that can be inserted
into YAML data models. Includes `name`, `description` (if present), and
`sql_table`.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
model = dbt.model('orders')

print(model.as_cube())
```

In the returned multiline string, all lines except for the first one are
left-padded with 4 spaces for easier use in YAML data models:

```yaml theme={"dark"}
# Jinja template
cubes:
  - {{ model.as_cube() }}

# YAML
cubes:
  - name: orders
    description: All Jaffle Shop orders
    sql_table: '"db"."public"."orders"'
```

#### `Model.as_dimensions`

This method renders the list of columns that belong to this dbt model as
a YAML snippet that can be inserted into YAML data models.

Optionally, accepts a list of column names that should be ignored in `skip`.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
model = dbt.model('orders')

print(model.as_dimensions(skip=['status']))
```

See [`Column.as_dimension`][self-column-as-dimension] for details on the
dimension rendering.

In the returned multiline string, all lines except for the first one are
left-padded with 6 spaces for easier use in YAML data models:

```yaml theme={"dark"}
# Jinja template
cubes:
  - {{ model.as_cube() }}

    dimensions:
      {{ model.as_dimensions() }}

# YAML
cubes:
  - name: orders
    description: All Jaffle Shop orders
    sql_table: '"db"."public"."orders"'

    dimensions:
      - name: id
        sql: id
        type: number
        primary_key: true
```

### `Column` class

Encapsulates tools for working with the metadata of a column that belongs
to a dbt model.

#### `Column.name`

This property exposes the name of a column.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
model = dbt.model('orders')
column = model.column('status')

print(column.name)
# For example, 'status'
```

#### `Column.description`

This property exposes the description of a column.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
model = dbt.model('orders')
column = model.column('status')

print(column.description)
# For example, 'Order execution status: new, in progress, delivered'
```

#### `Column.sql`

This property exposes the name of a column that can be used as the
[`sql` parameter][ref-dimension-sql] of a dimension.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
model = dbt.model('orders')
column = model.column('status')

print(column.sql)
# For example, 'status'
```

#### `Column.type`

This property exposes the data type of a column that can be used as the
[`type` parameter][ref-dimension-type] of a dimension.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
model = dbt.model('orders')
column = model.column('status')

print(column.type)
# For example, 'string'
```

`cube_dbt` package applies a set of heuristics to map database-specific
types to [dimension types][ref-dimension-types]. You can check the [source
code](https://github.com/cube-js/cube_dbt/blob/main/src/cube_dbt/column.py#L217-L233)
for implementation details.

If a column type is not defined in the metadata of a dbt project, `string`
is used by default.

#### `Column.meta`

This property exposes the meta data of a column as a `dict` that can be
used as the [`meta` parameter][ref-dimension-meta] of a dimension.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
model = dbt.model('orders')
column = model.column('status')

print(column.meta)
# For example, '{some: "data"}'
```

#### `Column.primary_key`

This property exposes a `bool` value that indicates if a column is
a primary key or not.

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
model = dbt.model('orders')
column = model.column('status')

print(column.primary_key)
# For example, 'False'
```

By convention, the column is considered a primary key if it has the
`primary_key` tag in the metadata of a dbt project.

#### `Column.as_dimension`

This method renders this column as a YAML snippet that can be inserted
into YAML data models. Includes `name`, `description` (if present), `sql`,
`type`, `primary_key` (if `True`), and `meta` (if present).

```python theme={"dark"}
from cube_dbt import Dbt

manifest_url = 'https://bucket.s3.amazonaws.com/manifest.json'

dbt = Dbt.from_url(manifest_url)
model = dbt.model('orders')
column = model.column('status')

print(column.as_dimension())
```

In the returned multiline string, all lines except for the first one are
left-padded with 8 spaces for easier use in YAML data models:

```yaml theme={"dark"}
# Jinja template
cubes:
  - {{ model.as_cube() }}

    dimensions:
      {% for column in model.columns() %}
      - {{ column.as_dimension() }}
      {% endfor %}

# YAML
cubes:
  - name: orders
    description: All Jaffle Shop orders
    sql_table: '"db"."public"."orders"'

    dimensions:
      - name: id
        sql: id
        type: number
        primary_key: true

      - name: status
        description: 'Order execution status: new, in progress, delivered'
        sql: status
        type: string
        meta:
          some: data
```

[link-dbt-docs]: https://docs.getdbt.com/docs/build/projects

[link-cube-dbt-repo]: https://github.com/cube-js/cube_dbt

[link-cube-dbt-pypi]: https://pypi.org/project/cube_dbt/

[link-cube-repo-issues]: https://github.com/cube-js/cube/issues

[link-dbt-manifest]: https://docs.getdbt.com/reference/artifacts/manifest-json

[link-dbt-materializations]: https://docs.getdbt.com/docs/build/materializations

[ref-cubes]: /reference/data-modeling/cube

[ref-model-syntax]: /docs/data-modeling/concepts/syntax#model-syntax

[ref-cube-sql-table]: /reference/data-modeling/cube#sql_table

[ref-dimension-sql]: /reference/data-modeling/dimensions#sql

[ref-dimension-type]: /reference/data-modeling/dimensions#type

[ref-dimension-meta]: /reference/data-modeling/dimensions#meta

[ref-dimension-types]: /reference/data-modeling/dimensions#type

[self-column-pk]: #columnprimary_key

[self-column-as-dimension]: #columnas_dimension


# Access policies
Source: https://docs.cube.dev/reference/data-modeling/data-access-policies

Access policies control row-level and member-level security on cubes and views, restricting what data users can see.

## Parameters

The `access_policy` parameter should define a list of access policies. Each policy
can be configured using the following parameters:

* [`group`](#group) or [`groups`](#groups) define which groups a policy applies to.
* [`conditions`](#conditions) can be optionally used to specify when a policy
  takes effect.
* [`member_level`](#member_level) and [`row_level`](#row_level) parameters are used
  to configure [member-level][ref-dap-mls] and [row-level][ref-dap-rls] access.
* [`member_masking`](#member_masking) can be optionally used to configure
  [data masking][ref-dap-masking] for members not included in `member_level`.

<Info>
  When you define access policies for specific groups, access is automatically denied to all other groups. You don't need to create a default policy that denies access.
</Info>

### `group`

The `group` parameter defines which group a policy applies to. To define a policy that applies to all users regardless of their groups, use the *any group* shorthand: `group: "*"`.

In the following example, two access policies are defined for users with `marketing` or `finance` groups, respectively.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      access_policy:
        - group: marketing
          # ...

        - group: finance
          # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    access_policy: [
      {
        group: `marketing`,
        // ...
      },
      {
        group: `finance`,
        // ...
      }
    ]
  })
  ```
</CodeGroup>

### `groups`

The `groups` parameter (plural) allows you to apply the same policy to multiple groups at once by providing an array of group names.

In the following example, a single policy applies to both `analysts` and `managers` groups:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      access_policy:
        - groups: [analysts, managers]
          member_level:
            includes: "*"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    access_policy: [
      {
        groups: [`analysts`, `managers`],
        member_level: {
          includes: `*`
        }
      }
    ]
  })
  ```
</CodeGroup>

### `conditions`

The optional `conditions` parameter, when present, defines a list of conditions
that should all be `true` in order for a policy to take effect. Each condition is
configured with an `if` parameter that is expected to reference the [security
context][ref-sec-ctx] or user attributes.

In the following example, a permissive policy for all groups will only apply to
EMEA-based users, as determined by the `is_EMEA_based` user attribute:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      access_policy:
        - group: "*"
          conditions:
            - if: "{ userAttributes.is_EMEA_based }"
          member_level:
            includes: "*"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    access_policy: [
      {
        group: `*`,
        conditions: [
          { if: userAttributes.is_EMEA_based }
        ],
        member_level: {
          includes: `*`
        }
      }
    ]
  })
  ```
</CodeGroup>

You can use the `conditions` parameter to define multiple policies for the same
group.

In the following example, the first policy provides access to a *subset of members*
to users in the manager group who are full-time employees while the other one provides access to
*all members* to users in the manager group who are full-time employees and have also completed a
data privacy training:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      access_policy:
        - group: manager
          conditions:
            - if: "{ userAttributes.is_full_time_employee }"
          member_level:
            includes:
              - status
              - count

        - group: manager
          conditions:
            - if: "{ userAttributes.is_full_time_employee }"
            - if: "{ userAttributes.has_completed_privacy_training }"
          member_level:
            includes: "*"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    access_policy: [
      {
        group: `manager`,
        conditions: [
          { if: userAttributes.is_full_time_employee }
        ],
        member_level: {
          includes: [
            `status`,
            `count`
          ]
        }
      },
      {
        group: `manager`,
        conditions: [
          { if: userAttributes.is_full_time_employee },
          { if: userAttributes.has_completed_privacy_training }
        ],
        member_level: {
          includes: `*`
        }
      }
    ]
  })
  ```
</CodeGroup>

#### Supported operators

The `if` expression must evaluate to a boolean. The syntax you can use inside it
depends on the data model format:

* In **YAML** data models, the expression inside `{ }` is evaluated as a Python
  expression. Only logical operators, member access, and method calls are supported.
* In **JavaScript** data models, the expression is evaluated as a JavaScript
  expression, so a broader set of operators is available.

The following operators and constructs are supported:

| Operator                       | Python (YAML)  | JavaScript                    |
| ------------------------------ | -------------- | ----------------------------- |
| Logical AND                    | `and`          | `&&`                          |
| Logical OR                     | `or`           | <code>\|\|</code>             |
| Logical NOT                    | `not`          | `!`                           |
| Member access                  | `.`            | `.`                           |
| Method call (e.g., `includes`) | `.includes(…)` | `.includes(…)`                |
| Equality and inequality        | —              | `===`, `!==`, `==`, `!=`      |
| Comparison                     | —              | `<`, `>`, `<=`, `>=`          |
| Arithmetic                     | —              | `+`, `-`, `*`, `/`, `%`, `**` |
| Ternary                        | —              | `? :`                         |
| Optional chaining              | —              | `?.`                          |

For example, the following policy applies to users who are not blocked, are either
administrators or based in the EMEA region, and belong to the `admins` group. Each
requirement is expressed as a separate condition, and all conditions must be `true`
for the policy to take effect:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  conditions:
    - if: "{ not userAttributes.is_blocked }"
    - if: "{ userAttributes.is_admin or userAttributes.is_EMEA_based }"
    - if: "{ userAttributes.groups.includes('admins') }"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  conditions: [
    { if: !userAttributes.is_blocked },
    { if: userAttributes.is_admin || userAttributes.is_EMEA_based },
    { if: userAttributes.groups.includes(`admins`) }
  ]
  ```
</CodeGroup>

<Tip>
  Prefer decomposing a condition chained with logical AND into separate
  conditions. Since conditions are combined with AND, the result is equivalent
  but easier to read and maintain.
</Tip>

<Note>
  The set of operators supported in JavaScript data models is currently broader than
  in YAML data models. If you'd like to use additional operators in YAML, please
  request support by opening an issue on
  [GitHub](https://github.com/cube-js/cube/issues?q=is%3Aissue+label%3A%22data+modeling%3Aaccess+policies%22).
</Note>

### `member_level`

The optional `member_level` parameter, when present, configures [member-level
access][ref-dap-mls] for a policy by specifying allowed or disallowed members.

You can either provide a list of allowed members with the `includes` parameter,
or a list of disallowed members with the `excludes` parameter. There's also the
*all members* shorthand for both of these paramaters: `includes: "*"`, `excludes: "*"`.

In the following example, member-level access is configured this way:

| Group            | Access                                        |
| ---------------- | --------------------------------------------- |
| `manager`        | All members except for `count`                |
| `observer`       | All members except for `count` and `count_7d` |
| `guest`          | Only the `count_30d` measure                  |
| All other groups | No access to this cube at all                 |

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...
      
      access_policy:
        - group: manager
          member_level:
            # Includes all members except for `count`
            excludes:
              - count
        
        - group: observer
          member_level:
            # Includes all members except for `count` and `count_7d`
            excludes:
              - count
              - count_7d
        
        - group: guest
          # Includes only `count_30d`, excludes all other members
          member_level:
            includes:
              - count_30d
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    access_policy: [
      {
        group: `manager`,
        // Includes all members except for `count`
        member_level: {
          excludes: [
            `count`
          ]
        }
      },
      {
        group: `observer`,
        // Includes all members except for `count` and `count_7d`
        member_level: {
          excludes: [
            `count`,
            `count_7d`
          ]
        }
      },
      {
        group: `guest`,
        // Includes only `count_30d`, excludes all other members
        member_level: {
          includes: [
            `count_30d`
          ]
        }
      }
    ]
  })
  ```
</CodeGroup>

Note that access policies also respect [member-level security][ref-mls] restrictions
configured via `public` parameters. See [member-level access][ref-dap-mls] to
learn more about policy evaluation.

### `member_masking`

The optional `member_masking` parameter, when present, configures [data
masking][ref-dap-masking] for a policy. It requires `member_level` to be
defined in the same policy.

Members included in `member_level` get full access. Members not in
`member_level` but included in `member_masking` return masked values instead
of being denied. The mask value is defined by the [`mask` parameter][ref-mask-dim]
on each dimension or measure.

You can provide a list of maskable members with `includes`, or a list of
non-maskable members with `excludes`. Use `"*"` as a shorthand for all members.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...
      
      access_policy:
        - group: manager
          member_level:
            includes:
              - status
              - count
          member_masking:
            includes: "*"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    access_policy: [
      {
        group: `manager`,
        member_level: {
          includes: [
            `status`,
            `count`
          ]
        },
        member_masking: {
          includes: `*`
        }
      }
    ]
  })
  ```
</CodeGroup>

### `row_level`

The optional `row_level` parameter, when present, configures [row-level
access][ref-dap-rls] for a policy by specifying `filters` that should apply to result set rows.

In the following example, users in the `manager` group are allowed to access only
rows that have the `state` dimension matching the state from the [security context][ref-sec-ctx].
All other users are disallowed from accessing any rows at all.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...
      
      access_policy:
        - group: manager
          row_level:
            filters:
              - member: state
                operator: equals
                values: [ "{ userAttributes.state }" ]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    access_policy: [
      {
        group: `manager`,
        row_level: {
          filters: [
            {
              member: `state`,
              operator: `equals`,
              values: [ userAttributes.state ]
            }
          ]
        }
      }
    ]
  })
  ```
</CodeGroup>

You can also pass multiple values in the `values` array to match against several
user attributes at once. This is useful when you need to check a dimension
against more than one attribute, for example, when a user may have access based
on multiple properties:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...
      
      access_policy:
        - group: manager
          row_level:
            filters:
              - member: users_country
                operator: equals
                values: [ "{ userAttributes.country }", "{ userAttributes.customCountryProperty }" ]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    access_policy: [
      {
        group: `manager`,
        row_level: {
          filters: [
            {
              member: `users_country`,
              operator: `equals`,
              values: [
                userAttributes.country,
                userAttributes.customCountryProperty
              ]
            }
          ]
        }
      }
    ]
  })
  ```
</CodeGroup>

For convenience, row filters are configured using the same format as [filters in
REST (JSON) API][ref-rest-query-filters] queries, allowing to use the same set of
[filter operators][ref-rest-query-ops], e.g., `equals`, `contains`, `gte`, etc.
You can also use `and` and `or` parameters to combine multiple filters into
[boolean logical operators][ref-rest-boolean-ops].

Note that access policies also respect [row-level security][ref-rls] restrictions
configured via the `query_rewrite` configuration option. See [row-level access][ref-dap-rls] to
learn more about policy evaluation.

## Using securityContext

The [`userAttributes`][ref-sec-ctx] object is only available in Cube Cloud platform. If you are using Cube Core or authenticating against [Core Data APIs][ref-core-data-apis] directly, you won't have access to `userAttributes`. Instead, you need to use `securityContext` directly when referencing user attributes in access policies (e.g., in `row_level` filters or `conditions`). For example, use `securityContext.userId` instead of `userAttributes.userId`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      access_policy:
        - group: manager
          row_level:
            filters:
              - member: country
                operator: equals
                values: [ "{ securityContext.country }" ]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    access_policy: [
      {
        group: `manager`,
        row_level: {
          filters: [
            {
              member: `country`,
              operator: `equals`,
              values: [ securityContext.country ]
            }
          ]
        }
      }
    ]
  })
  ```
</CodeGroup>

[ref-ref-cubes]: /reference/data-modeling/cube

[ref-ref-views]: /reference/data-modeling/view

[ref-dap]: /docs/data-modeling/data-access-policies

[ref-dap-mls]: /docs/data-modeling/data-access-policies#member_level-access

[ref-dap-rls]: /docs/data-modeling/data-access-policies#row_level-access

[ref-mls]: /docs/data-modeling/access-control/member-level-security

[ref-rls]: /docs/data-modeling/access-control/row-level-security

[ref-sec-ctx]: /docs/data-modeling/access-control/context

[ref-core-data-apis]: /reference/core-data-apis

[ref-dap-masking]: /docs/data-modeling/data-access-policies#data-masking

[ref-mask-dim]: /reference/data-modeling/dimensions#mask

[ref-rest-query-filters]: /reference/core-data-apis/rest-api/query-format#filters-format

[ref-rest-query-ops]: /reference/core-data-apis/rest-api/query-format#filters-operators

[ref-rest-boolean-ops]: /reference/core-data-apis/rest-api/query-format#boolean-logical-operators


# Dimensions
Source: https://docs.cube.dev/reference/data-modeling/dimensions

Dimensions are attributes related to measures, such as country, age, or occupation. They support various types, formatting, and hierarchy membership.

You can use the `dimensions` parameter within [cubes][ref-ref-cubes] to define dimensions.
You can think about a dimension as an attribute related to a measure, e.g. the measure `user_count`
can have dimensions like `country`, `age`, `occupation`, etc.

Any dimension should have the following parameters: [`name`](#name), [`sql`](#sql), and [`type`](#type).

Dimensions can be also organized into [hierarchies][ref-ref-hierarchies].

## Parameters

### `name`

The `name` parameter serves as the identifier of a dimension. It must be unique
among all dimensions, measures, and segments within a cube and follow the
[naming conventions][ref-naming].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products

      dimensions:
        - name: price
          sql: price
          type: number

        - name: brand_name
          sql: brand_name
          type: string


  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`products`, {
    dimensions: {
      price: {
        sql: `price`,
        type: `number`
      },

      brand_name: {
        sql: `brand_name`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

### `case`

The `case` statement is used to define dimensions based on SQL conditions.

The `when` parameters declares a series of `sql` conditions and `labels`
that are returned if the condition is truthy. The `else` parameter declares
the default `label` that would be returned if there's no truthy `sql`
condition.

The following example will create a `size` dimension with values
`xl`, `xxl`, and `Unknown`:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products
      # ...

      dimensions:
        - name: size
          type: string
          case:
            when:
              - sql: "{CUBE}.size_value = 'xl-en'"
                label: xl
              - sql: "{CUBE}.size_value = 'xl'"
                label: xl
              - sql: "{CUBE}.size_value = 'xxl-en'"
                label: xxl
              - sql: "{CUBE}.size_value = 'xxl'"
                label: xxl
            else:
              label: Unknown
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`products`, {
    // ...

    dimensions: {
      size: {
        type: `string`,
        case: {
          when: [
            { sql: `${CUBE}.size_value = 'xl-en'`, label: `xl` },
            { sql: `${CUBE}.size_value = 'xl'`, label: `xl` },
            { sql: `${CUBE}.size_value = 'xxl-en'`, label: `xxl` },
            { sql: `${CUBE}.size_value = 'xxl'`, label: `xxl` }
          ],
          else: { label: `Unknown` }
        }
      }
    }
  })

  ```
</CodeGroup>

The `label` property can be defined dynamically as an object with a `sql`
property in JavaScript models:

```javascript theme={"dark"}
cube(`products`, {
  // ...

  dimensions: {
    size: {
      type: `string`,
      case: {
        when: [
          {
            sql: `${CUBE}.meta_value = 'xl-en'`,
            label: { sql: `${CUBE}.english_size` }
          },
          {
            sql: `${CUBE}.meta_value = 'xl'`,
            label: { sql: `${CUBE}.euro_size` }
          },
          {
            sql: `${CUBE}.meta_value = 'xxl-en'`,
            label: { sql: `${CUBE}.english_size` }
          },
          {
            sql: `${CUBE}.meta_value = 'xxl'`,
            label: { sql: `${CUBE}.euro_size` }
          }
        ],
        else: { label: `Unknown` }
      }
    }
  }
})
```

### `title`

You can use the `title` parameter to change a dimension's displayed name. By
default, Cube will humanize your dimension key to create a display name. In
order to override default behavior, please use the `title` property:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products
      # ...

      dimensions:
        - name: meta_value
          title: Size
          sql: meta_value
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`products`, {
    // ...

    dimensions: {
      meta_value: {
        title: `Size`,
        sql: `meta_value`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

### `description`

This parameter provides a human-readable description of a dimension.
When applicable, it will be displayed in [Playground][ref-playground] and exposed
to data consumers via [APIs and integrations][ref-apis].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products
      # ...

      dimensions:
        - name: comment
          description: Comments for orders
          sql: comments
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`products`, {
    // ...

    dimensions: {
      comment: {
        description: `Comments for orders`,
        sql: `comments`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

### `public`

The `public` parameter is used to manage the visibility of a dimension. Valid
values for `public` are `true` and `false`. When set to `false`, this dimension
**cannot** be queried through the API. Defaults to `true`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products
      # ...

      dimensions:
        - name: comment
          sql: comment
          type: string
          public: false
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`products`, {
    // ...

    dimensions: {
      comment: {
        sql: `comment`,
        type: `string`,
        public: false
      }
    }
  })
  ```
</CodeGroup>

### `format`

`format` is an optional parameter. It controls how dimension values are
displayed to data consumers. The available formats depend on the dimension type.

For `string` dimensions:

| Format     | Description                                                            |
| ---------- | ---------------------------------------------------------------------- |
| `imageUrl` | Display the value as an image, using the value itself as the image URL |
| `link`     | Display the value as a hyperlink, using the value itself as the URL    |

The `link` format also accepts an object form — `format: { type: link, label: … }` — so the
cell shows a label instead of the raw URL (see `crm_link` in the example below).

In [Workbooks][ref-workbooks], a `link`-formatted value renders as a clickable link in
table cells. Values that aren't `http`, `https`, or `mailto` URLs render as plain text.

In [Workbooks][ref-workbooks], an `imageUrl`-formatted value renders as an inline
thumbnail in table cells, with no chart configuration needed. Height, shape, and fit can
be adjusted per column on the chart's Style tab. Values that aren't `https` or
`data:image/*` URLs render as plain text.

<Info>
  Images at `https` URLs are fetched directly by the viewer's browser, so they must be
  publicly reachable — Cube does not proxy or cache them. `data:image/*` values are
  rendered inline and need no network access.
</Info>

A thumbnail is clickable only where the dimension also declares [`links`](#links). The
`imageUrl` format makes a value an image source, not a destination.

For `number` dimensions, you can use the same named formats and custom
[d3-format][link-d3-format] specifiers as [measures](/reference/data-modeling/measures#format):

| Format                        | Description              | Example        | Output     |
| ----------------------------- | ------------------------ | -------------- | ---------- |
| `number` / `number_N`         | Grouped fixed-point      | `number`       | 1,234.57   |
| `percent` / `percent_N`       | Percentage               | `percent_1`    | 12.5%      |
| `currency` / `currency_N`     | Currency with grouping   | `currency_0`   | \$1,235    |
| `abbr` / `abbr_N`             | SI prefix (K, M, G, …)   | `abbr`         | 1.2K       |
| `accounting` / `accounting_N` | Negatives in parentheses | `accounting_2` | (1,234.57) |
| `id`                          | Raw integer, no grouping | `id`           | 12345      |

For `time` dimensions, you can use [POSIX strftime][link-strftime] format strings
with [d3-time-format][link-d3-time-format] extensions (e.g., `%Y-%m-%d %H:%M:%S`).

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      dimensions:
        - name: total
          sql: amount
          type: number
          format: currency

        - name: image
          sql: "CONCAT('https://img.example.com/id/', {id})"
          type: string
          format: imageUrl

        - name: order_link
          sql: "'http://mywebsite.com/orders/' || id"
          type: string
          format: link

        - name: crm_link
          sql: "'https://na1.salesforce.com/' || id"
          type: string
          format:
            type: link
            label: View in Salesforce

        - name: created_at
          sql: created_at
          type: time
          format: "%Y-%m-%d %H:%M:%S"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    dimensions: {
      total: {
        sql: `amount`,
        type: `number`,
        format: `currency`
      },

      image: {
        sql: `CONCAT('https://img.example.com/id/', ${id})`,
        type: `string`,
        format: `imageUrl`
      },

      order_link: {
        sql: `'http://mywebsite.com/orders/' || id`,
        type: `string`,
        format: `link`
      },

      crm_link: {
        sql: `'https://na1.salesforce.com/' || id`,
        type: `string`,
        format: {
          type: `link`,
          label: `View in Salesforce`
        }
      },

      created_at: {
        sql: `created_at`,
        type: `time`,
        format: `%Y-%m-%d %H:%M:%S`
      }
    }
  })
  ```
</CodeGroup>

Common time format examples:

| Format string       | Example output        |
| ------------------- | --------------------- |
| `%m/%d/%Y %H:%M`    | 12/04/2025 14:30      |
| `%Y-%m-%d %H:%M:%S` | 2025-12-04 14:30:00   |
| `%B %d, %Y`         | December 04, 2025     |
| `%b %d, %Y`         | Dec 04, 2025          |
| `%I:%M %p`          | 02:30 PM              |
| `%A, %B %d`         | Thursday, December 04 |
| `Q%q %Y`            | Q4 2025               |
| `Week %V, %Y`       | Week 49, 2025         |

### `currency`

The optional `currency` parameter specifies the [ISO 4217][link-iso-4217]
currency code for a `number`-type dimension. Use it alongside
`format: currency` to indicate which currency the values represent.

The value is a 3-letter currency code (e.g., `USD`, `EUR`, `GBP`) and is
case-insensitive.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      dimensions:
        - name: price
          sql: price
          type: number
          format: currency
          currency: EUR
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    dimensions: {
      price: {
        sql: `price`,
        type: `number`,
        format: `currency`,
        currency: `EUR`
      }
    }
  })
  ```
</CodeGroup>

<Info>
  The `currency` parameter can only be used with dimensions of type `number`.
  Using it with other dimension types will result in a validation error.
</Info>

### `links`

The `links` parameter allows you to define **one or more** links associated with a
dimension (it is a list). In [Workbooks][ref-workbooks], every link is available from the
table **cell context menu**, and the link marked `primary` also renders inline, as a
clickable link on the cell value itself.

Links are useful to let users navigate to related external resources (e.g., Google
search), internal tools (e.g., Salesforce), or other pages in a BI tool.

Each link must have a `name` and a `label`. The `name` is used as an identifier
in the [synthetic dimension](#synthetic) name.

A link must specify either a `url` or a `dashboard`:

* `url` is a SQL expression that constructs the link URL. It can [reference][ref-references]
  column and dimension values, just like the [`sql` parameter](#sql) or [`mask` parameter](#mask).
* `dashboard` is a target dashboard reference. When set, the link URL is generated as
  `/dashboard/<dashboard>` and `params` are appended as a query string. In Cube Cloud
  this is the target dashboard's **slug** (set in the dashboard's options and resolved
  within the current deployment); choosing the link drills in-app to that dashboard with
  `params` applied as equality filters. Links surface in the table **cell context menu**.

Optionally, a link might use the `icon` parameter to reference an icon from a [supported
icon set][link-tabler] to be displayed alongside the link label. Use the icon's kebab-case
name without any prefix (e.g. `brand-google`, `external-link`, `layout-dashboard`, `send`);
browse the available names at [tabler.io/icons][link-tabler]. When omitted, a default link
icon is shown.

Optionally, one link per dimension might set `primary: true`. In [Workbooks][ref-workbooks]
that link renders inline on the cell value, so it is reachable in one click while the rest
stay in the cell context menu. A dimension may mark at most one link as primary. Rows whose
primary link URL resolves to an empty value render the cell as plain text.

Optionally, a link might use the `target` parameter to specify [where to open it][link-target]:
`blank` to open in a new tab/window or `self` to open in the same tab/window. The default
depends on the link kind: `url:` links default to `blank` (new tab), while `dashboard:`
drill-ins default to `self` (in-app). An explicit `target` on a `dashboard:` drill-in is
honored on Cube **v1.7.5** or newer.

```yaml theme={"dark"}
cubes:
  - name: users

    dimensions:
      # Definitions of dimensions such as `email`, etc.

      - name: full_name
        sql: full_name
        type: string
        links:
          - name: google_search
            label: Search on Google
            url: "CONCAT('https://www.google.com/search?q=', {CUBE}.full_name)"
            icon: brand-google
            target: blank
            primary: true
          
          - name: salesforce_search
            label: Search in Salesforce
            url: "CONCAT('https://your-company.salesforce.com/search/results/?q=', {email})"
            target: blank

          - name: send_email
            label: Write an email
            url: "CONCAT('mailto:', {email})"
            icon: send
```

#### `params`

The optional `params` parameter can be used to add additional query parameters to the
URL. It accepts a map of key-value pairs, where keys are parameter names and values are
SQL expressions (just like `url`).

Values in `params` can [reference][ref-references] columns and dimension values.
All parameter values will be [URL-encoded][link-encode-uri-component] in the generated SQL
using a database-specific encoding function.

```yaml theme={"dark"}
cubes:
  - name: users

    dimensions:
      # Definitions of dimensions such as `id`, `country`, etc.

      - name: full_name
        sql: full_name
        type: string
        links:
          - name: performance
            label: Check performance dashboard
            dashboard: KSqDYdUz6Ble
            params:
              - key: filter_user_id
                value: "{id}"
              - key: filter_country
                value: "{country}"
```

#### Synthetic dimensions

Each link will be rendered as an additional [synthetic](#synthetic) dimension in the
result set, with the following naming convention:

* `<dimension_name>___link_<link_name>_url`

<Info>
  All references in link URLs and parameters must resolve to a single value for a given
  value of the dimension on which the link is defined. Otherwise, it will result in
  duplicate rows in the result set.
</Info>

### `meta`

The `meta` parameter allows you to attach arbitrary information to a dimension.
It can be consumed and interpreted by supporting tools.

You can also use the `ai_context` key to provide context to the
[AI agent][ref-ai-context] without exposing it in the user interface.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products
      # ...

      dimensions:
        - name: users_count
          sql: "{users.count}"
          type: number
          meta:
            any: value
            ai_context: >
              This is a subquery dimension. Use it to get the
              number of users associated with each product.
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`products`, {
    // ...

    dimensions: {
      users_count: {
        sql: `${users.count}`,
        type: `number`,
        meta: {
          any: "value",
          ai_context: `This is a subquery dimension. Use it to get the
            number of users associated with each product.`
        }
      }
    }
  })
  ```
</CodeGroup>

### `order`

The `order` parameter specifies the default sort order for a dimension. Valid
values are `asc` (ascending) and `desc` (descending). This parameter is optional.

When set, the dimension's default sort order is exposed via
[APIs and integrations][ref-apis]. Consuming applications, such as BI tools
and custom frontends, can use this metadata to apply consistent default sorting
when displaying dimension values, ensuring a uniform user experience across
different tools connected to the semantic layer.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      dimensions:
        - name: status
          sql: status
          type: string
          order: asc

        - name: created_at
          sql: created_at
          type: time
          order: desc
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    dimensions: {
      status: {
        sql: `status`,
        type: `string`,
        order: `asc`
      },

      created_at: {
        sql: `created_at`,
        type: `time`,
        order: `desc`
      }
    }
  })
  ```
</CodeGroup>

### `primary_key`

Specify if a dimension is a primary key for a cube. The default value is
`false`.

A primary key is used to make [joins][ref-schema-ref-joins] work properly.

<Info>
  Setting `primary_key` to `true` will change the default value of the [`public`
  parameter](#public) to `false`. If you still want `public` to be `true`, set it
  explicitly.
</Info>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products
      # ...

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`products`, {
    // ...

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      }
    }
  })
  ```
</CodeGroup>

It is possible to have more than one primary key dimension in a cube if you'd
like them all to be parts of a composite key:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products
      sql: |
        SELECT 1 AS column_a, 1 AS column_b UNION ALL
        SELECT 2 AS column_a, 1 AS column_b UNION ALL
        SELECT 1 AS column_a, 2 AS column_b UNION ALL
        SELECT 2 AS column_a, 2 AS column_b

      dimensions:
        - name: composite_key_a
          sql: column_a
          type: number
          primary_key: true

        - name: composite_key_b
          sql: column_b
          type: number
          primary_key: true

      measures:
        - name: count
          type: count
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`products`, {
    sql: `
      SELECT 1 AS column_a, 1 AS column_b UNION ALL
      SELECT 2 AS column_a, 1 AS column_b UNION ALL
      SELECT 1 AS column_a, 2 AS column_b UNION ALL
      SELECT 2 AS column_a, 2 AS column_b
    `,

    dimensions: {
      composite_key_a: {
        sql: `column_a`,
        type: `number`,
        primary_key: true
      },

      composite_key_b: {
        sql: `column_b`,
        type: `number`,
        primary_key: true
      }
    },

    measures: {
      count: {
        type: `count`
      }
    }
  })
  ```
</CodeGroup>

Querying the `count` measure of the cube shown above will generate the following
SQL to the upstream data source:

```sql theme={"dark"}
SELECT
  count(
    CAST("product".column_a as TEXT) || CAST("product".column_b as TEXT)
  ) "product__count"
FROM (
  SELECT 1 AS column_a, 1 AS column_b UNION ALL
  SELECT 2 AS column_a, 1 AS column_b UNION ALL
  SELECT 1 AS column_a, 2 AS column_b UNION ALL
  SELECT 2 AS column_a, 2 AS column_b
) AS "product"
```

### `propagate_filters_to_sub_query`

When this statement is set to `true`, the filters applied to the query will be
passed to the [subquery][self-subquery].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products
      # ...

      dimensions:
        - name: users_count
          sql: "{users.count}"
          type: number
          sub_query: true
          propagate_filters_to_sub_query: true
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`products`, {
    // ...

    dimensions: {
      users_count: {
        sql: `${users.count}`,
        type: `number`,
        sub_query: true,
        propagate_filters_to_sub_query: true
      }
    }
  })
  ```
</CodeGroup>

### `sql`

`sql` is a required parameter. It can take any valid SQL expression depending on
the `type` of the dimension. Please refer to the \[Dimension
Types]\[ref-schema-ref-dims-types] to understand what the `sql` parameter should
be for a given dimension type.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      dimensions:
        - name: created_at
          sql: created_at
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    dimensions: {
      created_at: {
        sql: `created_at`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

### `mask`

The optional `mask` parameter defines the replacement value used when the
dimension is masked by a [data masking][ref-data-masking] access policy.

The mask can be a static value (number, boolean, or string) or a SQL expression:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      dimensions:
        - name: secret_code
          sql: secret_code
          type: string
          mask:
            sql: "CONCAT('***', RIGHT({CUBE}.secret_code, 3))"

        - name: revenue
          sql: revenue
          type: number
          mask: -1
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    dimensions: {
      secret_code: {
        sql: `secret_code`,
        type: `string`,
        mask: {
          sql: `CONCAT('***', RIGHT(${CUBE}.secret_code, 3))`
        }
      },

      revenue: {
        sql: `revenue`,
        type: `number`,
        mask: -1
      }
    }
  })
  ```
</CodeGroup>

If no `mask` is defined, the default mask value is `NULL`. See
[data masking][ref-data-masking] for more details.

### `sub_query`

The `sub_query` statement allows you to reference a measure in a dimension. It's
an advanced concept and you can learn more about it [here][ref-subquery].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: products
      # ...

      dimensions:
        - name: users_count
          sql: "{users.count}"
          type: number
          sub_query: true
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`products`, {
    // ...

    dimensions: {
      users_count: {
        sql: `${users.count}`,
        type: `number`,
        sub_query: true
      }
    }
  })
  ```
</CodeGroup>

### `type`

`type` is a required parameter. There are various types that can be assigned to
a dimension. A dimension can only have one type.

| Type      | Description                                                                                                                                                                                                                                                                                      |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `time`    | Timestamp column for time series data. The target column should be `TIMESTAMP`; cast other temporal types in `sql`. See [this recipe][ref-string-time-dims] for string-based datetimes.                                                                                                          |
| `string`  | Text fields containing letters or special characters.                                                                                                                                                                                                                                            |
| `number`  | Numeric or integer fields.                                                                                                                                                                                                                                                                       |
| `boolean` | Boolean fields or data coercible to boolean.                                                                                                                                                                                                                                                     |
| `switch`  | Predefined set of allowed values (enum-like). Takes only a `values` sub-parameter — no `sql`, and no other parameters such as `title` or `public`. Useful for [`case` measures][ref-case-measures]. [Pre-aggregations][ref-matching-switch-dimensions] don't need to include it. Tesseract only. |
| `geo`     | Geographic coordinates. Requires `latitude` and `longitude` sub-parameters instead of `sql`.                                                                                                                                                                                                     |

<Warning>
  `switch` dimensions are powered by Tesseract, the [next-generation data modeling
  engine][link-tesseract]. In versions before v1.7.0, it was not enabled by default.
</Warning>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      dimensions:
        - name: completed_at
          sql: completed_at
          type: time

        - name: full_name
          sql: "CONCAT({first_name}, ' ', {last_name})"
          type: string

        - name: amount
          sql: amount
          type: number

        - name: is_enabled
          sql: is_enabled
          type: boolean

        - name: growth_window
          type: switch
          values:
            - 3m
            - 6m
            - 12m

        - name: location
          type: geo
          latitude:
            sql: "{CUBE}.latitude"
          longitude:
            sql: "{CUBE}.longitude"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    dimensions: {
      completed_at: {
        sql: `completed_at`,
        type: `time`
      },

      full_name: {
        sql: `CONCAT(${first_name}, ' ', ${last_name})`,
        type: `string`
      },

      amount: {
        sql: `amount`,
        type: `number`
      },

      is_enabled: {
        sql: `is_enabled`,
        type: `boolean`
      },

      growth_window: {
        type: `switch`,
        values: [`3m`, `6m`, `12m`]
      },

      location: {
        type: `geo`,
        latitude: {
          sql: `${CUBE}.latitude`
        },
        longitude: {
          sql: `${CUBE}.longitude`
        }
      }
    }
  })
  ```
</CodeGroup>

### `synthetic`

The `synthetic` parameter can't be set by a user directly. It is used to mark dimensions
that are automatically created by Cube, e.g., for [links](#links).

You can check if a dimension is synthetic via the [`/v1/meta` API endpoint][ref-meta-api].

### `granularities`

By default, the following granularities are available for time dimensions:
`year`, `quarter`, `month`, `week` (starting on Monday), `day`, `hour`, `minute`,
`second`.

You can use the `granularities` parameter with any dimension of the [type
`time`][ref-time-dimensions] to define one or more custom granularities, such as
a *week starting on Sunday* or a *fiscal year*.

<Note>
  See [this recipe][ref-custom-granularity-recipe] for more custom granularity
  examples.
</Note>

<Warning>
  Custom granularities are supported for the following [data sources][ref-data-sources]:
  Amazon Athena, Amazon Redshift, DuckDB, Databricks, Google BigQuery, ClickHouse, Microsoft SQL Server, MySQL, Postgres, and Snowflake.
  Please [file an issue](https://github.com/cube-js/cube/issues) if you need support for another data source.
</Warning>

<Warning>
  Custom granularities can be queried by name via the [REST API][ref-rest-api].
  However, neither the [SQL API][ref-sql-api] nor the [GraphQL
  API][ref-graphql-api] can address them by name: the SQL API only supports the
  default granularities in `DATE_TRUNC`, and the GraphQL schema only exposes
  fields for the default granularities. To query a custom granularity via the SQL
  API, the GraphQL API, or a BI tool, use a [proxy
  dimension][ref-proxy-granularity] that references it.
</Warning>

For each custom granularity, the `interval` parameter is required. It specifies
the duration of the time interval and has the following format:
`quantity unit [quantity unit...]`, e.g., `5 days` or `1 year 6 months`. The only
exception is a granularity that overrides a default granularity with `sql`, described
[below](#calendar-cubes).

Optionally, a custom granularity might use the `offset` parameter to specify how
the time interval is shifted forward or backward in time. It has the same
format as `interval`, however, you can also provide negative quantities, e.g.,
`-1 day` or `1 month -10 days`.

Alternatively, instead of `offset`, you can provide the `origin` parameter.
When `origin` is provided, time intervals will be shifted in a way that one of
them will match the provided origin. It accepts an ISO 8601-compliant [date time
string][link-date-time-string], e.g., `2024-01-02` or `2024-01-02T12:00:00.000Z`.

Optionally, a custom granularity might have the `title` parameter with a
human-friendly description.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql: |
        SELECT '2025-01-01T00:12:00.000Z'::TIMESTAMP AS time UNION ALL
        SELECT '2025-02-01T00:15:00.000Z'::TIMESTAMP AS time UNION ALL
        SELECT '2025-03-01T00:18:00.000Z'::TIMESTAMP AS time

      dimensions:
        - name: time
          sql: time
          type: time

          granularities:
            - name: quarter_hour
              interval: 15 minutes

            - name: week_starting_on_sunday
              interval: 1 week
              offset: -1 day

            - name: fiscal_year_starting_on_april_01
              title: Corporate and government fiscal year in the United Kingdom
              interval: 1 year
              origin: "2025-04-01"
              # You have to use quotes here to make `origin` a valid YAML string 
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql: `
      SELECT '2025-01-01T00:12:00.000Z'::TIMESTAMP AS time UNION ALL
      SELECT '2025-02-01T00:15:00.000Z'::TIMESTAMP AS time UNION ALL
      SELECT '2025-03-01T00:18:00.000Z'::TIMESTAMP AS time
    `,

    dimensions: {
      time: {
        sql: `time`,
        type: `time`,
        granularities: {
          quarter_hour: {
            interval: `15 minutes`
          },
          week_starting_on_sunday: {
            interval: `1 week`,
            offset: `-1 day`
          },
          fiscal_year_starting_on_april_01: {
            title: `Corporate and government fiscal year in the United Kingdom`,
            interval: `1 year`,
            origin: `2025-04-01`
          }
        }
      }
    }
  })
  ```
</CodeGroup>

#### Calendar cubes

The `granularities` parameter can also override the *default granularities* by mapping
them to pre-calculated columns with the `sql` parameter. This is most useful in
[calendar cubes][ref-calendar-cubes], for modeling custom calendars such as fiscal
calendars.

A granularity defined with `sql` must be named after a default granularity:
`second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, or `year`. Names are
matched case-insensitively. Use `sql` to change what an existing unit of time means,
not to introduce a new one. A granularity under a name of your own, such as
`fiscal_week`, must be defined with `interval` instead. See [overriding
granularities][ref-calendar-cubes-granularities] for when to use each style.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: fiscal_calendar
      calendar: true
      sql: >
        SELECT
          date_key,
          calendar_date,
          start_of_month,
          start_of_quarter,
          start_of_year
        FROM calendar_table

      dimensions:
        - name: date_key
          sql: date_key
          type: time
          primary_key: true

        - name: date
          sql: calendar_date
          type: time
          granularities:
            - name: month
              sql: "{CUBE}.start_of_month"

            - name: quarter
              sql: "{CUBE}.start_of_quarter"

            - name: year
              sql: "{CUBE}.start_of_year"

  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`fiscal_calendar`, {
    calendar: true,
    sql: `
      SELECT
        date_key,
        calendar_date,
        start_of_month,
        start_of_quarter,
        start_of_year
      FROM calendar_table
    `,

    dimensions: {
      date_key: {
        sql: `date_key`,
        type: `time`,
        primary_key: true
      },

      date: {
        sql: `calendar_date`,
        type: `time`,
        granularities: {
          month: {
            sql: `${CUBE}.start_of_month`
          },
          quarter: {
            sql: `${CUBE}.start_of_quarter`
          },
          year: {
            sql: `${CUBE}.start_of_year`
          }
        }
      }
    }
  })
  ```
</CodeGroup>

<Info>
  **A pre-aggregation over an overridden granularity must declare that granularity.**
  A rollup at another granularity will not serve those queries correctly.
</Info>

### `time_shift`

The `time_shift` parameter allows overriding the time shift behavior for time dimensions
within [calendar cubes][ref-calendar-cubes]. Such time shifts can be referenced in
[time-shift measures][ref-time-shift] of other cubes, enabling the use of custom calendars.

The `time_shift` parameter can only be set on *time dimensions* within *calendar cubes*,
i.e., cubes where the [`calendar` parameter][ref-cube-calendar] is set to `true`.

The `time_shift` parameter accepts an array of time shift definitions. Each definition
can include `time_dimension`, `type`, `interval`, and `name` parameters, similarly to the
[`time_shift` parameter][ref-measure-time-shift] of time-shift measures. Additionally,
you can use the `sql` parameter to define a custom time mapping using a SQL expression.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: fiscal_calendar
      calendar: true
      sql: >
        SELECT
          date_key,
          calendar_date,
          fiscal_date_prior_year,
          fiscal_date_next_quarter
        FROM calendar_table

      dimensions:
        - name: date_key
          sql: date_key
          type: time
          primary_key: true

        - name: date
          sql: calendar_date
          type: time
          time_shift:
            - name: prior_calendar_year
              type: prior
              interval: 1 year

            - name: next_calendar_quarter
              type: next
              interval: 1 quarter

            - name: prior_fiscal_year
              sql: "{CUBE}.fiscal_date_prior_year"

            - name: next_fiscal_quarter
              sql: "{CUBE}.fiscal_date_next_quarter"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`fiscal_calendar`, {
    calendar: true,
    sql: `
      SELECT
        date_key,
        calendar_date,
        fiscal_date_prior_year,
        fiscal_date_next_quarter
      FROM calendar_table
    `,

    dimensions: {
      date_key: {
        sql: `date_key`,
        type: `time`,
        primary_key: true
      },

      date: {
        sql: `calendar_date`,
        type: `time`,
        time_shift: [
          {
            name: `prior_calendar_year`,
            type: `prior`,
            interval: `1 year`
          },
          {
            name: `next_calendar_quarter`,
            type: `next`,
            interval: `1 quarter`
          },
          {
            name: `prior_fiscal_year`,
            sql: `${CUBE}.fiscal_date_prior_year`
          },
          {
            name: `next_fiscal_quarter`,
            sql: `${CUBE}.fiscal_date_next_quarter`
          }
        ]
      }
    }
  });
  ```
</CodeGroup>

[ref-ai-context]: /docs/data-modeling/ai-context

[ref-ref-cubes]: /reference/data-modeling/cube

[ref-schema-ref-joins]: /reference/data-modeling/joins

[ref-subquery]: /docs/data-modeling/dimensions#subquery-dimensions

[self-subquery]: #sub-query

[ref-naming]: /docs/data-modeling/concepts/syntax#naming

[ref-playground]: /docs/explore-analyze/playground

[ref-apis]: /reference

[ref-time-dimensions]: #type

[link-date-time-string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format

[ref-custom-granularity-recipe]: /recipes/data-modeling/custom-granularity

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-graphql-api]: /reference/core-data-apis/graphql-api

[ref-sql-api]: /reference/core-data-apis/sql-api

[ref-proxy-granularity]: /docs/data-modeling/dimensions#time-dimension-granularity-references

[ref-ref-hierarchies]: /reference/data-modeling/hierarchies

[ref-data-sources]: /admin/connect-to-data/data-sources

[ref-calendar-cubes]: /docs/data-modeling/concepts/calendar-cubes

[ref-time-shift]: /docs/data-modeling/measures#time-shift

[ref-cube-calendar]: /reference/data-modeling/cube#calendar

[ref-measure-time-shift]: /reference/data-modeling/measures#time_shift

[ref-data-masking]: /docs/data-modeling/data-access-policies#data-masking

[link-iso-4217]: https://en.wikipedia.org/wiki/ISO_4217

[link-d3-format]: https://d3js.org/d3-format

[link-strftime]: https://pubs.opengroup.org/onlinepubs/009695399/functions/strptime.html

[link-d3-time-format]: https://d3js.org/d3-time-format

[link-tesseract]: https://cube.dev/blog/introducing-next-generation-data-modeling-engine

[ref-case-measures]: /reference/data-modeling/measures#case

[ref-matching-switch-dimensions]: /docs/pre-aggregations/matching-pre-aggregations#matching-switch-dimensions

[ref-meta-api]: /reference/core-data-apis/rest-api/reference#base_path/v1/meta

[ref-string-time-dims]: /recipes/data-modeling/string-time-dimensions

[ref-workbooks]: /docs/explore-analyze/workbooks

[link-target]: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a#target

[link-tabler]: https://tabler.io/icons

[ref-references]: /docs/data-modeling/concepts/syntax#references

[ref-filter-params]: /reference/data-modeling/context-variables#filter_params

[link-encode-uri-component]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent

[ref-rest-filters]: /reference/core-data-apis/rest-api/query-format#query-properties

[ref-calendar-cubes-granularities]: /docs/data-modeling/concepts/calendar-cubes#overriding-granularities


# Hierarchies
Source: https://docs.cube.dev/reference/data-modeling/hierarchies

Hierarchies group dimensions into levels of granularity, allowing users to drill down or roll up for analysis.

You can use the `hierarchies` parameter within [cubes][ref-ref-cubes] to define hierarchies.
You can think about a hierarchy as a means to group [dimensions][ref-ref-dimensions] together and organize
them into levels of granularity, allowing users to drill down or roll up for analysis.

<Info>
  Hierarchies display is subject to support in [visualization tools][ref-viz-tools].
  Check [APIs & Integrations][ref-apis-support] for details.
  You can also preview hierarchies in [Playground][ref-playground].
</Info>

Any hierarchy should have the following parameters: [`name`](#name) and [`levels`](#levels).

<Note>
  Just like other members, hierarchies can be exposed to data consumers through
  [views][ref-ref-views]. List them in the `includes` parameter of a view's
  `cubes` block alongside measures, dimensions, and segments.
</Note>

<iframe title="YouTube video" />

## Parameters

### `name`

The `name` parameter serves as the identifier of a hierarchy. It must be unique
among all members within a cube and follow the [naming conventions][ref-naming].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      # ...

      hierarchies:
        - name: location
          title: User Location
          levels:
            - state
            - city
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    // ...

    hierarchies: {
      location: {
        title: `User Location`,
        levels: [
          state,
          city
        ]
      }
    }
  })
  ```
</CodeGroup>

### `title`

You can use the `title` parameter to set the human-readable name of a hierarchy:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      # ...

      hierarchies:
        - name: location
          title: User Location
          levels:
            - state
            - city
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    // ...

    hierarchies: {
      location: {
        title: `User Location`,
        levels: [
          state,
          city
        ]
      }
    }
  })
  ```
</CodeGroup>

### `levels`

The `levels` parameter is used to define the levels of the hierarchy. You can do so
by listing the dimensions included in the hierarchy, from less granular to more
granular ones:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      dimensions:
        - name: state
          sql: state
          type: string

        - name: city
          sql: city
          type: string

      hierarchies:
        - name: location
          title: User Location
          levels:
            - state
            - city
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    dimensions: {
      state: {
        sql: `state`,
        type: `string`
      },

      city: {
        sql: `city`,
        type: `string`
      }
    },

    hierarchies: {
      location: {
        title: `User Location`,
        levels: [
          state,
          city
        ]
      }
    }
  })
  ```
</CodeGroup>

You can include the same dimension in multiple hierarchies. It is also possible to
include a dimension from a joined cube into a hierarchy:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      joins:
        - name: orders
          sql: "{CUBE.id} = {orders.user_id}"
          relationship: one_to_many

      dimensions:
        - name: state
          sql: state
          type: string

        - name: city
          sql: city
          type: string

        - name: status
          sql: status
          type: string

      hierarchies:
        - name: details
          title: User Details
          levels:
            - status
            - state
            - city

        - name: statuses
          title: User & Order Statuses
          levels:
            - status
            - orders.status
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    joins: {
      orders: {
        sql: `${CUBE.id} = ${orders.user_id}`,
        relationship: `one_to_many`
      }
    },

    dimensions: {
      state: {
        sql: `state`,
        type: `string`
      },

      city: {
        sql: `city`,
        type: `string`
      },

      status: {
        sql: `status`,
        type: `string`
      }
    },

    hierarchies: {
      location: {
        title: `User Location`,
        levels: [
          state,
          city
        ]
      },

      statuses: {
        title: `User & Order Statuses`,
        levels: [
          status,
          orders.status
        ]
      }
    }
  })
  ```
</CodeGroup>

### `public`

The `public` parameter is used to manage the visibility of a hierarchy. Valid
values for `public` are `true` and `false`. When set to `false`, this hierarchy
**cannot** be queried through the API. Defaults to `true`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      sql_table: users

      # ...

      hierarchies:
        - name: location
          title: User Location
          levels:
            - state
            - city
          public: false
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    sql_table: `users`,

    // ...

    hierarchies: {
      location: {
        title: `User Location`,
        levels: [
          state,
          city
        ],
        public: false
      }
    }
  })
  ```
</CodeGroup>

[ref-ref-cubes]: /reference/data-modeling/cube

[ref-ref-dimensions]: /reference/data-modeling/dimensions

[ref-ref-views]: /reference/data-modeling/view

[ref-naming]: /docs/data-modeling/concepts/syntax#naming

[ref-apis-support]: /reference#data-modeling

[ref-playground]: /docs/explore-analyze/playground#viewing-the-data-model

[ref-viz-tools]: /admin/connect-to-data/visualization-tools


# Joins
Source: https://docs.cube.dev/reference/data-modeling/joins

Joins define relationships between cubes, allowing you to access and compare members from multiple cubes at the same time.

You can use the `joins` parameter within [cubes][ref-ref-cubes] to define joins to other cubes.
Joins allow to access and compare members from two or more cubes at the same time.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: my_cube
      # ...

      joins:
        - name: target_cube
          relationship: one_to_one || one_to_many || many_to_one
          sql: SQL ON clause
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`my_cube`, {
    // ...

    joins: {
      target_cube: {
        relationship: `one_to_one` || `one_to_many` || `many_to_one`,
        sql: `SQL ON clause`
      }
    }
  })
  ```
</CodeGroup>

All joins are generated as `LEFT JOIN`. The cube which defines the join serves
as a main table, and any cubes referenced inside the `joins` property are used
in the `LEFT JOIN` clause. Learn more about direction of joins
[here][ref-schema-fundamentals-join-dir].

The semantics of `INNER JOIN` can be achieved with additional filtering. For
example, a simple check of whether the column value `IS NOT NULL` by using [set
filter][ref-restapi-query-filter-op-set] satisfies this requirement.

There's also no way to define `FULL OUTER JOIN` and `RIGHT OUTER JOIN` for the
sake of join modeling simplicity. To get `RIGHT OUTER JOIN` semantics just
define join [from other side of relationship][ref-schema-fundamentals-join-dir].
The `FULL OUTER JOIN` can be built inside cube [sql][ref-schema-cube-sql]
parameter. Quite frequently, `FULL OUTER JOIN` is used to solve [Data
Blending][ref-schema-data-blenging] or similar problems. In that case, it's best
practice to have a separate cube for such an operation.

## Parameters

### name

The name must match the name of the joined cube and, thus, follow the [naming
conventions][ref-naming].

For example, when the `products` cube is joined on to the `orders` cube, we
would define the join as follows:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      joins:
        - name: products
          relationship: many_to_one
          sql: "{CUBE.id} = {products.order_id}"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    joins: {
      products: {
        relationship: `many_to_one`,
        sql: `${CUBE.id} = ${products.order_id}`
      }
    }
  })
  ```
</CodeGroup>

### relationship

The `relationship` property is used to describe the type of the relationship
between joined cubes. It’s important to properly define the type of relationship
so Cube can accurately calculate measures.

The cube that declares the join is considered *left* in terms of the [left
join][wiki-left-join] semantics, and the joined cube is considered *right*. It
means that all rows of the *left* cube are selected, while only those rows of
the *right* cube that match the condition are selected as well. For more
information and specific examples, please see [join
directions][ref-schema-fundamentals-join-dir].

<Info>
  The join does not need to be defined on both cubes, but the definition can
  affect the [join direction][ref-schema-fundamentals-join-dir].
</Info>

You can use the following types of relationships:

* `one_to_one` for [one-to-one][wiki-1-1] relationships
* `one_to_many` for [one-to-many][wiki-1-m] relationships
* `many_to_one` for the opposite of [one-to-many][wiki-1-m] relationships

<Warning>
  The types of relationships listed above were introduced in v0.32.19 for clarity
  as they are commonly used in the data space. The following aliases were used
  before and are still valid, so there's no need to update existing data models:

  * `one_to_one` was known as `has_one` or `hasOne`
  * `one_to_many` was known as `has_many` or `hasMany`
  * `many_to_one` was known as `belongs_to` or `belongsTo`
</Warning>

#### One-to-one

The `one_to_one` type indicates a [one-to-one][wiki-1-1] relationship between
the declaring cube and the joined cube. It means that one row in the declaring
cube can match only one row in the joined cube.

For example, in a data model containing `users` and their `profiles`, the
`users` cube would declare the following join:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      # ...

      joins:
        - name: profiles
          relationship: one_to_one
          sql: "{users}.id = {profiles.user_id}"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    // ...

    joins: {
      profiles: {
        relationship: `one_to_one`,
        sql: `${CUBE}.id = ${profiles.user_id}`
      }
    }
  })
  ```
</CodeGroup>

#### One-to-many

The `one_to_many` type indicates a [one-to-many][wiki-1-m] relationship between
the declaring cube and the joined cube. It means that one row in the declaring
cube can match many rows in the joined cube.

For example, in a data model containing `authors` and the `books` they have
written, the `authors` cube would declare the following join:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: authors
      # ...

      joins:
        - name: books
          relationship: one_to_many
          sql: "{authors}.id = {books.author_id}"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`authors`, {
    // ...

    joins: {
      books: {
        relationship: `one_to_many`,
        sql: `${CUBE}.id = ${books.author_id}`
      }
    }
  })
  ```
</CodeGroup>

#### Many-to-one

The `many_to_one` type indicates the many-to-one relationship between the
declaring cube and the joined cube. You’ll often find this type of relationship
on the opposite side of the [one-to-many][wiki-1-m] relationship. It means that
one row in the declaring cube matches a single row in the joined cube, while a
row in the joined cube can match many rows in the declaring cube.

For example, in a data model containing `orders` and `customers` who made them,
the `orders` cube would have the following join:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      joins:
        - name: customers
          relationship: many_to_one
          sql: "{orders}.customer_id = {customers.id}"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    joins: {
      customers: {
        relationship: `many_to_one`,
        sql: `${CUBE}.customer_id = ${customers.id}`
      }
    }
  })
  ```
</CodeGroup>

### sql

`sql` is necessary to indicate a related column between cubes. It is important
to properly specify a matching column when creating joins. Take a look at the
example below:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      joins:
        - name: customers
          relationship: many_to_one
          sql: "{orders}.customer_id = {customers.id}"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    joins: {
      customers: {
        relationship: `many_to_one`,
        // The `customer_id` column of the `orders` cube corresponds to the
        // `id` dimension of the `customers` cube
        sql: `${CUBE}.customer_id = ${customers.id}`
      }
    }
  })
  ```
</CodeGroup>

## Setting a primary key

In order for a join to work, it is necessary to define a `primary_key` as
specified below. It is a requirement when a join is defined so that Cube can
handle row multiplication issues such as chasm and fan traps.

Let's imagine you want to calculate `Order Amount` by `Order Item Product Name`.
In this case, `Order` rows will be multiplied by the `Order Item` join due to
the `one_to_many` relationship. In order to produce correct results, Cube will
select distinct primary keys from `Order` first and then will join these primary
keys with `Order` to get the correct `Order Amount` sum result. Please note that
`primary_key` should be defined in the `dimensions` section.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      dimensions:
        - name: customer_id
          sql: id
          type: number
          primary_key: true
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    dimensions: {
      customer_id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      }
    }
  })
  ```
</CodeGroup>

<Info>
  Setting `primary_key` to `true` will change the default value of the `public`
  parameter to `false`. If you still want `public` to be `true` — set it manually.
</Info>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      dimensions:
        - name: customer_id
          sql: id
          type: number
          primary_key: true
          public: true
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    dimensions: {
      customer_id: {
        sql: `id`,
        type: `number`,
        primary_key: true,
        public: true
      }
    }
  })
  ```
</CodeGroup>

If you don't have a single column in a cube's table that can act as a primary
key, you can create a composite primary key as shown below.

<Info>
  The example uses Postgres string concatenation; note that SQL may be different
  depending on your database.
</Info>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      # ...

      dimensions:
        - name: id
          sql:
            "{CUBE}.user_id || '-' || {CUBE}.signup_week || '-' ||
            {CUBE}.activity_week"
          type: string
          primary_key: true
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    // ...

    dimensions: {
      id: {
        sql: `${CUBE}.user_id || '-' || ${CUBE}.signup_week || '-' || ${CUBE}.activity_week`,
        type: `string`,
        primary_key: true
      }
    }
  })
  ```
</CodeGroup>

## Chasm and fan traps

Cube automatically detects chasm and fan traps based on the `many_to_one` and `one_to_many` relationships defined in join.
When detected, Cube generates a deduplication query that evaluates all distinct primary keys within the multiplied measure's cube and then joins distinct primary keys to this cube on itself to calculate the aggregation result.
If there's more than one multiplied measure in a query, then such query is generated for every such multiplied measure, and results are joined.
Cube solves for chasm and fan traps during query time.
If there's pre-aggregregation that fits measure multiplication requirements it'd be leveraged to serve such a query.
Such pre-aggregations and queries are always considered non-additive for the purpose of pre-aggregation matching.

Let's consider an example data model:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true
        - name: city
          sql: city
          type: string

      joins:
        - name: customers
          relationship: many_to_one
          sql: "{orders}.customer_id = {customers.id}"

  - name: customers
      sql_table: customers

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

      measures:
        - name: average_age
          sql: age
          type: avg

  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      },
      city: {
        sql: `city`,
        type: `string`
      }
    },

    joins: {
      customers: {
        relationship: `many_to_one`,
        sql: `${CUBE}.customer_id = ${customers.id}`
      }
    }
  })

  cube(`customers`, {
    sql_table: `customers`

    measures: {
      count: {
        type: `count`
      }
    },

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      }
    }
  })
  ```
</CodeGroup>

If we try to query `customers.average_age` by `orders.city`, the Cube detects that the `average_age` measure in the `customers` cube would be multiplied by `orders` to `customers` and would generate SQL similar to:

```sql theme={"dark"}
SELECT
  "keys"."orders__city",
  avg("customers_key__customers".age) "customers__average_age"
FROM
  (
    SELECT
      DISTINCT "customers_key__orders".city "orders__city",
      "customers_key__customers".id "customers__id"
    FROM
      orders AS "customers_key__orders"
      LEFT JOIN customers AS "customers_key__customers" ON "customers_key__orders".customer_id = "customers_key__customers".id
  ) AS "keys"
  LEFT JOIN customers AS "customers_key__customers" ON "keys"."customers__id" = "customers_key__customers".id
GROUP BY
  1
```

## CUBE reference

When you have several joined cubes, you should accurately use columns’ names to
avoid any mistakes. One way to make no mistakes is to use the `CUBE` reference.
It allows you to specify columns’ names in cubes without any ambiguity. During
the implementation of the query, this reference will be used as an alias for a
basic cube. Take a look at the following example:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      # ...

      dimensions:
        - name: name
          sql: "{CUBE}.name"
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    // ...

    dimensions: {
      name: {
        sql: `${CUBE}.name`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

## Transitive joins

<Warning>
  Join graph is directed and `a → b` join is different from `b → a`. [Learn more
  about it here][ref-schema-fundamentals-join-dir].
</Warning>

Cube automatically takes care of transitive joins. For example, consider the
following data model:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: a
      # ...

      joins:
        - name: b
          sql: "{a}.b_id = {b.id}"
          relationship: many_to_one

      measures:
        - name: count
          type: count

    - name: b
      # ...

      joins:
        - name: c
          sql: "{b}.c_id = {c.id}"
          relationship: many_to_one

    - name: c
      # ...

      dimensions:
        - name: category
          sql: category
          type: string
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`a`, {
    // ...

    joins: {
      b: {
        sql: `${a}.b_id = ${b.id}`,
        relationship: `many_to_one`
      }
    },

    measures: {
      count: {
        type: `count`
      }
    }
  })

  cube(`b`, {
    // ...

    joins: {
      c: {
        sql: `${b}.c_id = ${c.id}`,
        relationship: `many_to_one`
      }
    }
  })

  cube(`c`, {
    // ...

    dimensions: {
      category: {
        sql: `category`,
        type: `string`
      }
    }
  })
  ```
</CodeGroup>

Assume that the following query is run:

```json theme={"dark"}
{
  "measures": ["a.count"],
  "dimensions": ["c.category"]
}
```

Joins `a → b` and `b → c` will be resolved automatically. Cube uses the
[Dijkstra algorithm][wiki-djikstra-alg] to find a join path between cubes given
requested members.

In case there are multiple join paths that can be used to join the same set of cubes, Cube will collect cube names from members in the following order:

1. Measures
2. Dimensions
3. Segments
4. Time dimensions

Cube makes join trees as predictable and stable as possible, but this isn't guaranteed in case multiple join paths exist.
Please use views to address join predictability and stability.

[ref-ref-cubes]: /reference/data-modeling/cube

[ref-restapi-query-filter-op-set]: /reference/core-data-apis/rest-api/query-format#set

[ref-schema-fundamentals-join-dir]: /docs/data-modeling/joins#direction-of-joins

[ref-schema-cube-sql]: /reference/data-modeling/cube#sql

[ref-schema-data-blenging]: /docs/data-modeling/concepts/data-blending#data-blending

[ref-naming]: /docs/data-modeling/concepts/syntax#naming

[wiki-djikstra-alg]: https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm

[wiki-left-join]: https://en.wikipedia.org/wiki/Join_\(SQL\)#Left_outer_join

[wiki-1-1]: https://en.wikipedia.org/wiki/One-to-one_\(data_model\)

[wiki-1-m]: https://en.wikipedia.org/wiki/One-to-many_\(data_model\)


# `lkml2cube` package
Source: https://docs.cube.dev/reference/data-modeling/lkml2cube

lkml2cube is a command-line tool for converting LookML models into Cube data models during a Looker-to-Cube migration.

`lkml2cube` package facilitates the migration from [Looker][link-looker]
to Cube. It provides a convenient command-line tool for converting
[LookML][link-lookml] models into the Cube data model.

* Install [`lkml2cube`][link-lkml2cube-pypi] package from PyPI
* Check the source code in [`lkml2cube`][link-lkml2cube-repo] on GitHub
* Submit issues to [`cube`][link-cube-repo-issues] on GitHub

## Installation

Run the following command:

```bash theme={"dark"}
pip install lkml2cube
```

## Usage

There are two commands: `cubes` and `views`. Both commands read all the
files in the provided input parameter, including those referenced by the
LookML keyword `include`.

### `cubes`

The `cubes` command would inspect LookML [views][link-lookml-views] and
generate [cubes][ref-cubes].

Since join relationships are defined at the `explore` level in LookML
syntax, generated cubes would not have [join][ref-joins] definitions.

#### Debugging

Run the following command to display a representation of a LookML object
as a Python dictionary:

```bash theme={"dark"}
lkml2cube cubes --parseonly path/to/file.view.lkml
```

#### Converting

Run the following command to convert LookML [views][link-lookml-views]
into [cubes][ref-cubes]:

```bash theme={"dark"}
lkml2cube cubes path/to/file.view.lkml --outputdir ./
```

### `views`

The `views` command would inspect LookML [explores][link-lookml-explores]
and generate [cubes][ref-cubes] and [views][ref-views].

Since join relationships are defined at the `explore` level in LookML
syntax, generated cubes and views would have [join][ref-joins] definitions.

#### Converting

Run the following command to convert LookML [explores][link-lookml-explores]
into [cubes][ref-cubes] and [views][ref-views]:

```bash theme={"dark"}
lkml2cube views path/to/file.explore.lkml --outputdir ./
```

[link-looker]: https://cloud.google.com/looker/

[link-lookml]: https://cloud.google.com/looker/docs/reference/lookml-quick-reference

[link-lookml-views]: https://cloud.google.com/looker/docs/reference/param-view

[link-lookml-explores]: https://cloud.google.com/looker/docs/reference/param-explore

[link-lkml2cube-repo]: https://github.com/cube-js/lkml2cube

[link-lkml2cube-pypi]: https://pypi.org/project/lkml2cube/

[link-cube-repo-issues]: https://github.com/cube-js/cube/issues

[ref-cubes]: /reference/data-modeling/cube

[ref-views]: /reference/data-modeling/view

[ref-joins]: /reference/data-modeling/joins


# Measures
Source: https://docs.cube.dev/reference/data-modeling/measures

Measures are aggregations over columns in your database table, supporting types like count, sum, avg, rolling windows, and more.

You can use the `measures` parameter within [cubes][ref-ref-cubes] to define measures.
Each measure is an aggregation over a certain column in your database table.

Any measure should have the following parameters: [`name`](#name), [`sql`](#sql), and [`type`](#type).

## Parameters

### `name`

The `name` parameter serves as the identifier of a measure. It must be unique
among all measures, dimensions, and segments within a cube and follow the
[naming conventions][ref-naming].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: count
          sql: id
          type: count

        - name: total_amount
          sql: amount
          type: sum
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      count: {
        sql: `id`,
        type: `count`
      },

      total_amount: {
        sql: `amount`,
        type: `sum`
      }
    }
  })
  ```
</CodeGroup>

### `title`

You can use the `title` parameter to change a measure’s displayed name. By
default, Cube will humanize your measure key to create a display name. In order
to override default behavior, please use the `title` parameter.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: orders_count
          title: Number of Orders Placed
          sql: id
          type: count
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      orders_count: {
        title: `Number of Orders Placed`,
        sql: `id`,
        type: `count`
      }
    }
  })
  ```
</CodeGroup>

### `description`

This parameter provides a human-readable description of a measure.
When applicable, it will be displayed in [Playground][ref-playground] and exposed
to data consumers via [APIs and integrations][ref-apis].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: orders_count
          description: Count of all orders
          sql: id
          type: count
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      orders_count: {
        sql: `id`,
        type: `count`,
        description: `Count of all orders`
      }
    }
  })
  ```
</CodeGroup>

### `public`

The `public` parameter is used to manage the visibility of a measure. Valid
values for `public` are `true` and `false`. When set to `false`, this measure
**cannot** be queried through the API. Defaults to `true`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: orders_count
          sql: id
          type: count
          public: false
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      orders_count: {
        sql: `id`,
        type: `count`,
        public: false
      }
    }
  })
  ```
</CodeGroup>

### `meta`

Custom metadata. Can be used to pass any information to the frontend.

You can also use the `ai_context` key to provide context to the
[AI agent][ref-ai-context] without exposing it in the user interface.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: revenue
          type: sum
          sql: price
          meta:
            any: value
            ai_context: >
              Use this measure for all revenue-related questions.
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      revenue: {
        type: `sum`,
        sql: `price`,
        meta: {
          any: "value",
          ai_context: `Use this measure for all revenue-related questions.`
        }
      }
    }
  })
  ```
</CodeGroup>

### `sql`

`sql` is a required parameter. It can take any valid SQL expression depending on
the `type` of the measure. Please refer to the \[Measure Types
Guide]\[ref-schema-ref-types-formats-measures-types] for detailed information on
the corresponding `sql` parameter.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: users_count
          sql: "COUNT(*)"
          type: number
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      users_count: {
        sql: `COUNT(*)`,
        type: `number`
      }
    }
  })
  ```
</CodeGroup>

Depending on the measure [type](#type), the `sql` parameter would either:

* Be skipped (in case of the `count` type).
* Contain an aggregate function, e.g., `STRING_AGG(string_dimension, ',')`
  (in case of `string`, `time`, `boolean`, and `number` types).
* Contain a non-aggregated expression that Cube would wrap into an aggregate
  function according to the measure type (in case of the `avg`, `count_distinct`,
  `count_distinct_approx`, `min`, `max`, and `sum` types).

### `mask`

The optional `mask` parameter defines the replacement value used when the
measure is masked by a [data masking][ref-data-masking] access policy.

The mask can be a static value (number, boolean, or string) or a SQL expression.
When using a SQL expression, it should be an aggregate expression (the same way
as the measure's [`sql`](#sql) parameter for `number` type measures), because
the mask replaces the entire measure expression including aggregation:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: count
          type: count
          mask: 0

        - name: total_revenue
          sql: revenue
          type: sum
          mask: -1

        - name: avg_revenue
          sql: revenue
          type: avg
          mask:
            sql: "AVG(CASE WHEN {CUBE}.is_public THEN {CUBE}.revenue END)"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      count: {
        type: `count`,
        mask: 0
      },

      total_revenue: {
        sql: `revenue`,
        type: `sum`,
        mask: -1
      },

      avg_revenue: {
        sql: `revenue`,
        type: `avg`,
        mask: {
          sql: `AVG(CASE WHEN ${CUBE}.is_public THEN ${CUBE}.revenue END)`
        }
      }
    }
  })
  ```
</CodeGroup>

If no `mask` is defined, the default mask value is `NULL`. See
[data masking][ref-data-masking] for more details.

<Warning>
  SQL masks on measures are not applied in ungrouped queries (e.g., `SELECT *`
  via the SQL API). If you need dynamic masking in ungrouped mode, use a
  masked dimension instead.
</Warning>

### `filters`

If you want to add some conditions for a metric's calculation, you should use
the `filters` parameter. The syntax looks like the following:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: orders_completed_count
          sql: id
          type: count
          filters:
            - sql: "{CUBE}.status = 'completed'"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      orders_completed_count: {
        sql: `id`,
        type: `count`,
        filters: [{ sql: `${CUBE}.status = 'completed'` }]
      }
    }
  })
  ```
</CodeGroup>

### `type`

`type` is a required parameter. There are various types that can be assigned to
a measure. A measure can only have one type.

| Type                    | `sql` parameter                          | Description                                                                                                                                                            |
| ----------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `count`                 | Optional                                 | Table count, similar to SQL `COUNT`. Properly handles join row multiplication.                                                                                         |
| `count_distinct`        | Non-aggregated expression                | Number of distinct values, similar to SQL `COUNT(DISTINCT …)`.                                                                                                         |
| `count_distinct_approx` | Non-aggregated expression                | Approximate distinct count using HyperLogLog. Unlike `count_distinct`, it is **additive** and can be used in [rollup pre-aggregations][ref-schema-ref-preaggs-rollup]. |
| `sum`                   | Non-aggregated numeric expression        | Sum of values, similar to SQL `SUM`. Properly handles join row duplication.                                                                                            |
| `avg`                   | Non-aggregated numeric expression        | Average of values, similar to SQL `AVG`. Properly handles join row duplication.                                                                                        |
| `min`                   | Non-aggregated numeric expression        | Minimum value, similar to SQL `MIN`.                                                                                                                                   |
| `max`                   | Non-aggregated numeric expression        | Maximum value, similar to SQL `MAX`.                                                                                                                                   |
| `number`                | Aggregate expression                     | Arithmetic on other measures, e.g., in [calculated measures][ref-calculated-measures].                                                                                 |
| `number_agg`            | Custom aggregate function                | Custom aggregate not covered by other types (e.g., `PERCENTILE_CONT`). Tesseract only.                                                                                 |
| `string`                | Aggregate expression returning string    | String-valued measure.                                                                                                                                                 |
| `time`                  | Aggregate expression returning timestamp | Timestamp-valued measure.                                                                                                                                              |
| `boolean`               | Aggregate expression returning boolean   | Boolean-valued measure.                                                                                                                                                |

<Warning>
  The `number_agg` type is only available in Tesseract, the [next-generation data modeling
  engine][link-tesseract]. In versions before v1.7.0, it was not enabled by default.
</Warning>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: orders_count
          type: count

        - name: unique_user_count
          sql: user_id
          type: count_distinct

        - name: revenue
          sql: amount
          type: sum

        - name: avg_transaction
          sql: amount
          type: avg

        - name: purchases_ratio
          sql: "1.0 * {purchases} / {orders_count}"
          type: number
          format: percent
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      orders_count: {
        type: `count`
      },

      unique_user_count: {
        sql: `user_id`,
        type: `count_distinct`
      },

      revenue: {
        sql: `amount`,
        type: `sum`
      },

      avg_transaction: {
        sql: `amount`,
        type: `avg`
      },

      purchases_ratio: {
        sql: `1.0 * ${purchases} / ${orders_count}`,
        type: `number`,
        format: `percent`
      }
    }
  })
  ```
</CodeGroup>

### `rolling_window`

The `rolling_window` parameter is used to for [rolling window][ref-rolling-window]
calculations, e.g., to calculate a metric over a moving window of time, e.g. a
week or a month.

<Warning>
  Rolling window calculations require the query to contain a single time dimension
  with a provided date range. It is used to calculate the minimum and maximum values
  for the series of time windows.

  With Tesseract, the [next-generation data modeling engine][link-tesseract],
  rolling window calculations don't require the date range for the time dimension. In versions before v1.7.0, Tesseract was not enabled by default.

  Omitting the date range requires the data source to generate the time series in
  SQL. It is supported for Amazon Athena, Databricks, Google BigQuery, Microsoft SQL
  Server, Postgres, Presto, Snowflake, and Trino, as well as for MySQL with the
  `CUBEJS_DB_MYSQL_USE_GENERATED_TIME_SERIES` environment variable set. With other
  data sources, and with [custom granularities][ref-custom-granularities] on Google
  BigQuery, Microsoft SQL Server, and Snowflake, the date range is still required.
</Warning>

#### `offset`

The `offset` parameter is used to specify the starting point of the time window.

You can set the window `offset` parameter to either `start` or `end`, which will
match the start or end of the window.

By default, the `offset` parameter is set to `end`.

#### `trailing` and `leading`

The `trailing` and `leading` parameters define the size of the time window.
The `trailing` parameter defines the size of the window part before the `offset` point,
and the `leading` parameter defines the size of the window part after the `offset` point.

These parameters have a format defined as `(-?\d+) (minute|hour|day|week|month|year)`.
It means that you can define these parameters using both positive and negative integers.

The `trailing` and `leading` parameters can also be set to `unbounded`,
which means *infinite size* for the corresponding window part.

By default, the `leading` and `trailing` parameters are set to zero.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: rolling_count_month
          sql: id
          type: count
          rolling_window:
            trailing: 1 month
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      rolling_count_month: {
        sql: `id`,
        type: `count`,
        rolling_window: {
          trailing: `1 month`
        }
      }
    }
  })
  ```
</CodeGroup>

Here's an example of an `unbounded` window that's used for cumulative counts:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: cumulative_count
          type: count
          rolling_window:
            trailing: unbounded
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      cumulative_count: {
        type: `count`,
        rolling_window: {
          trailing: `unbounded`
        }
      }
    }
  })
  ```
</CodeGroup>

### `multi_stage`

The `multi_stage` parameter is used to define measures that are used with [multi-stage
calculations][ref-multi-stage], e.g., [time-shift measures][ref-time-shift].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: time_shift
      sql: >
        SELECT '2024-01-01'::TIMESTAMP AS time, 100 AS revenue UNION ALL
        SELECT '2024-02-01'::TIMESTAMP AS time, 200 AS revenue UNION ALL
        SELECT '2024-03-01'::TIMESTAMP AS time, 300 AS revenue UNION ALL

        SELECT '2025-01-01'::TIMESTAMP AS time, 400 AS revenue UNION ALL
        SELECT '2025-02-01'::TIMESTAMP AS time, 500 AS revenue UNION ALL
        SELECT '2025-03-01'::TIMESTAMP AS time, 600 AS revenue

      dimensions:
        - name: time
          sql: time
          type: time

      measures:
        - name: revenue
          sql: revenue
          type: sum

        - name: revenue_prior_year
          multi_stage: true
          sql: "{revenue}"
          type: number
          time_shift:
            - time_dimension: time
              interval: 1 year
              type: prior
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`time_shift`, {
    sql: `
      SELECT '2024-01-01'::TIMESTAMP AS time, 100 AS revenue UNION ALL
      SELECT '2024-02-01'::TIMESTAMP AS time, 200 AS revenue UNION ALL
      SELECT '2024-03-01'::TIMESTAMP AS time, 300 AS revenue UNION ALL

      SELECT '2025-01-01'::TIMESTAMP AS time, 400 AS revenue UNION ALL
      SELECT '2025-02-01'::TIMESTAMP AS time, 500 AS revenue UNION ALL
      SELECT '2025-03-01'::TIMESTAMP AS time, 600 AS revenue
    `,

    dimensions: {
      time: {
        sql: `time`,
        type: `time`
      }
    },

    measures: {
      revenue: {
        sql: `revenue`,
        type: `sum`
      },

      revenue_prior_year: {
        multi_stage: true,
        sql: `${revenue}`,
        type: `number`,
        time_shift: [
          {
            time_dimension: `time`,
            interval: `1 year`,
            type: `prior`
          }
        ]
      }
    }
  })
  ```
</CodeGroup>

### `grain`

The `grain` parameter is used with [multi-stage measures][ref-multi-stage] to control the
dimensions of the inner aggregation stage's `GROUP BY` — the *grain* at which the base
measure is computed before the outer aggregation is applied. It accepts an object with
three keys, each taking a list of dimension names from the same cube:

* `keep_only` — group the inner stage by *only* the listed dimensions, ignoring the
  query's dimensions. Use it for fixed-grain calculations such as percent of total.
* `exclude` — group the inner stage by the query's dimensions *minus* the listed
  dimensions. Use it for ranking within groups.
* `include` — group the inner stage by the query's dimensions *plus* the listed
  dimensions. Use it for nested aggregates (an aggregate of an aggregate).

`keep_only` and `exclude` are mutually exclusive.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  measures:
    - name: country_revenue
      multi_stage: true
      sql: "{revenue}"
      type: sum
      grain:
        keep_only:
          - country
  ```

  ```javascript title="JavaScript" theme={"dark"}
  measures: {
    country_revenue: {
      multi_stage: true,
      sql: `${revenue}`,
      type: `sum`,
      grain: {
        keep_only: [country]
      }
    }
  }
  ```
</CodeGroup>

| `grain` key | Inner `GROUP BY`              | Outer `GROUP BY` |
| ----------- | ----------------------------- | ---------------- |
| `keep_only` | Only the listed dimensions    | Query dimensions |
| `exclude`   | Query dimensions minus listed | Query dimensions |
| `include`   | Query dimensions plus listed  | Query dimensions |

`grain` applies to the measure it's declared on and does not expose the added
dimension to a measure built on top of it. When a measure combines several
other multi-stage measures at a shared grain, declare `grain` on the
combining measure — see [nested aggregates][ref-nested-aggregate].

<Note>
  `grain` replaces the standalone `group_by`, `reduce_by`, and `add_group_by` parameters,
  which remain supported. To migrate, use `grain.keep_only` instead of `group_by`,
  `grain.exclude` instead of `reduce_by`, and `grain.include` instead of `add_group_by`.
</Note>

### `group_by`, `reduce_by`, and `add_group_by` (legacy)

These three parameters were the original way to control the inner aggregation stage's
`GROUP BY` for [multi-stage measures][ref-multi-stage]. They are still supported, but
[`grain`](#grain) now covers all three and is the recommended way to express the grain of
a multi-stage measure.

| Legacy parameter | `grain` equivalent          | Effect on the inner stage's `GROUP BY`                |
| ---------------- | --------------------------- | ----------------------------------------------------- |
| `group_by`       | [`grain.keep_only`](#grain) | Only the listed dimensions, ignoring query dimensions |
| `reduce_by`      | [`grain.exclude`](#grain)   | Query dimensions minus the listed dimensions          |
| `add_group_by`   | [`grain.include`](#grain)   | Query dimensions plus the listed dimensions           |

Each accepts a list of dimension names from the same cube. For new data models, use
[`grain`](#grain) instead.

### `filter`

The `filter` parameter is used with [multi-stage measures][ref-multi-stage] to
override the filter context that the inner aggregation stage inherits from the
query. By default, a multi-stage measure inherits all filters applied to the
query; `filter` lets you drop, replace, or extend those filters at the inner
stage.

This is commonly used for "share of total" calculations where the denominator
must ignore a filter applied by the query — for example, computing each status's
share of the per-category total while the query is filtered to a single status.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  measures:
    - name: amount_all_statuses
      multi_stage: true
      sql: "{total_amount}"
      type: number
      filter:
        exclude:
          - status
  ```

  ```javascript title="JavaScript" theme={"dark"}
  measures: {
    amount_all_statuses: {
      multi_stage: true,
      sql: `${total_amount}`,
      type: `number`,
      filter: {
        exclude: [status]
      }
    }
  }
  ```
</CodeGroup>

`filter` accepts the following keys, which can be combined:

| Key         | Description                                                                                                                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `exclude`   | A list of members (dimensions or segments) whose query filters are *dropped* at the inner stage.                                                                                                              |
| `keep_only` | A list of members whose query filters are *kept*; all other inherited filters are dropped.                                                                                                                    |
| `include`   | A list of additional predicates injected at the inner stage, regardless of the query. Each entry is a query-style filter (`member`, `operator`, `values`) and entries may be nested into `and` / `or` groups. |
| `mode`      | How the override composes along a multi-stage chain: `relative` (default) or `fixed`.                                                                                                                         |

The `mode` key controls how the override interacts with the filter context of
an upstream multi-stage measure when measures are chained:

* `relative` (default): the override is applied *relative* to the filter context
  inherited from the chain.
* `fixed`: the override is applied as an *absolute* filter context, ignoring the
  filters inherited from upstream multi-stage measures.

At the top level (not inside a chain), `relative` and `fixed` are equivalent.

An `include` entry uses the same shape as a [query filter][ref-filters-query],
and `and` / `or` groups can be nested arbitrarily:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  measures:
    - name: high_value_west_coast
      multi_stage: true
      sql: "{total_amount}"
      type: number
      filter:
        mode: relative
        exclude:
          - status
        include:
          - member: amount
            operator: gt
            values: ["0"]
          - or:
              - member: city
                operator: equals
                values: [NYC]
              - member: city
                operator: equals
                values: [SF]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  measures: {
    high_value_west_coast: {
      multi_stage: true,
      sql: `${total_amount}`,
      type: `number`,
      filter: {
        mode: `relative`,
        exclude: [status],
        include: [
          { member: amount, operator: `gt`, values: [`0`] },
          { or: [
            { member: city, operator: `equals`, values: [`NYC`] },
            { member: city, operator: `equals`, values: [`SF`] }
          ] }
        ]
      }
    }
  }
  ```
</CodeGroup>

### `time_shift`

The `time_shift` parameter is used to configure a [time shift][ref-time-shift] for a
measure. It accepts an array of time shift configurations that consist of `time_dimension`,
`type`, `interval`, and `name` parameters.

#### `type` and `interval`

These parameters define the time shift direction and size. The `type` can be either
`prior` (shifting time backwards) or `next` (shifting time forwards).
The `interval` parameter defines the size of the time shift and has the following format:
`quantity unit`, e.g., `1 year` or `7 days`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
      measures:
        - name: revenue
          sql: revenue
          type: sum

        - name: revenue_7d_ago
          multi_stage: true
          sql: "{revenue}"
          type: number
          time_shift:
            - interval: 7 days
              type: prior

        - name: revenue_1y_ago
          multi_stage: true
          sql: "{revenue}"
          type: number
          time_shift:
            - interval: 1 year
              type: prior
  ```

  ```javascript title="JavaScript" theme={"dark"}
    measures: {
      revenue: {
        sql: `revenue`,
        type: `sum`
      },

      revenue_7d_ago: {
        multi_stage: true,
        sql: `${revenue}`,
        type: `number`,
        time_shift: [
          {
            interval: `7 days`,
            type: `prior`
          }
        ]
      },

      revenue_1y_ago: {
        multi_stage: true,
        sql: `${revenue}`,
        type: `number`,
        time_shift: [
          {
            interval: `1 year`,
            type: `prior`
          }
        ]
      }
    }
  ```
</CodeGroup>

#### `time_dimension`

The `time_dimension` parameter is used to specify the time dimension for the time shift.
If it's omitted, Cube will apply the time shift to all time dimensions in the query.
In this case, only single time shift configuration is allowed in `time_shift`.

If `time_dimension` is specified, the time shift will only happen if the query contains
this very time dimension. This is useful if you'd like to apply different time shifts to
different time dimensions or if you want to apply a time shift only when a specific time
dimension is present in the query.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
      measures:
        - name: revenue
          sql: revenue
          type: sum

        - name: lagging_revenue
          multi_stage: true
          sql: "{revenue}"
          type: number
          time_shift:
            - time_dimension: purchase_date
              interval: 3 months
              type: prior

            - time_dimension: shipping_date
              interval: 2 months
              type: prior

            - time_dimension: delivery_date
              interval: 1 month
              type: prior
  ```

  ```javascript title="JavaScript" theme={"dark"}
    measures: {
      revenue: {
        sql: `revenue`,
        type: `sum`
      },

      lagging_revenue: {
        multi_stage: true,
        sql: `${revenue}`,
        type: `number`,
        time_shift: [
          {
            time_dimension: `purchase_date`,
            interval: `3 months`,
            type: `prior`
          },
          {
            time_dimension: `shipping_date`,
            interval: `2 months`,
            type: `prior`
          },
          {
            time_dimension: `delivery_date`,
            interval: `1 month`,
            type: `prior`
          }
        ]
      }
    }
  ```
</CodeGroup>

#### `name`

The `name` parameter is used to reference a *named time shift* that is defined on a time
dimension from a [calendar cube][ref-calendar-cubes]. Named time shifts are used in cases
when different measures use the same time shift configuration (e.g., `prior` + `1 year`)
but have to be shifted differently depending on the custom calendar.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: sales_calendar
      calendar: true
      sql: >
        SELECT '2025-06-02Z' AS date, '2024-06-01Z' AS mapped_date, '2024-06-03Z' AS mapped_date_alt UNION ALL
        SELECT '2025-06-03Z' AS date, '2024-06-02Z' AS mapped_date, '2024-06-04Z' AS mapped_date_alt UNION ALL
        SELECT '2025-06-04Z' AS date, '2024-06-03Z' AS mapped_date, '2024-06-05Z' AS mapped_date_alt UNION ALL
        SELECT '2025-06-05Z' AS date, '2024-06-04Z' AS mapped_date, '2024-06-06Z' AS mapped_date_alt UNION ALL
        SELECT '2025-06-06Z' AS date, '2024-06-05Z' AS mapped_date, '2024-06-07Z' AS mapped_date_alt UNION ALL
        SELECT '2025-06-07Z' AS date, '2024-06-06Z' AS mapped_date, '2024-06-08Z' AS mapped_date_alt UNION ALL
        SELECT '2025-06-08Z' AS date, '2024-06-07Z' AS mapped_date, '2024-06-09Z' AS mapped_date_alt

      dimensions:
        - name: date_key
          sql: "{CUBE}.date::TIMESTAMP"
          type: time
          primary_key: true

        - name: date
          sql: "{CUBE}.date::TIMESTAMP"
          type: time
          time_shift:
            - name: 1_year_prior
              sql: "{CUBE}.mapped_date::TIMESTAMP"

            - name: 1_year_prior_alternative
              sql: "{CUBE}.mapped_date_alt::TIMESTAMP"

    - name: sales
      sql: >
        SELECT 101 AS id, '2024-06-01Z' AS date, 101 AS amount UNION ALL
        SELECT 102 AS id, '2024-06-02Z' AS date, 102 AS amount UNION ALL
        SELECT 103 AS id, '2024-06-03Z' AS date, 103 AS amount UNION ALL
        SELECT 104 AS id, '2024-06-04Z' AS date, 104 AS amount UNION ALL
        SELECT 105 AS id, '2024-06-05Z' AS date, 105 AS amount UNION ALL
        SELECT 106 AS id, '2024-06-06Z' AS date, 106 AS amount UNION ALL
        SELECT 107 AS id, '2024-06-07Z' AS date, 107 AS amount UNION ALL
        SELECT 108 AS id, '2024-06-08Z' AS date, 108 AS amount UNION ALL
        SELECT 109 AS id, '2024-06-09Z' AS date, 109 AS amount UNION ALL

        SELECT 202 AS id, '2025-06-02Z' AS date, 202 AS amount UNION ALL
        SELECT 203 AS id, '2025-06-03Z' AS date, 203 AS amount UNION ALL
        SELECT 204 AS id, '2025-06-04Z' AS date, 204 AS amount UNION ALL
        SELECT 205 AS id, '2025-06-05Z' AS date, 205 AS amount UNION ALL
        SELECT 206 AS id, '2025-06-06Z' AS date, 206 AS amount UNION ALL
        SELECT 207 AS id, '2025-06-07Z' AS date, 207 AS amount UNION ALL
        SELECT 208 AS id, '2025-06-08Z' AS date, 208 AS amount

      joins:
        - name: sales_calendar
          sql: "{sales.date} = {sales_calendar.date_key}"
          relationship: many_to_one

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: date
          sql: "{CUBE}.date::TIMESTAMP"
          type: time
          public: false

      measures:
        - name: total_amount
          sql: amount
          type: sum

        - name: total_amount_1y_prior
          multi_stage: true
          sql: "{total_amount}"
          type: number
          time_shift:
            - name: 1_year_prior

        - name: total_amount_1y_prior_alternative
          multi_stage: true
          sql: "{total_amount}"
          type: number
          time_shift:
            - name: 1_year_prior_alternative
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`sales_calendar`, {
    sql: `
      SELECT '2025-06-02Z' AS date, '2024-06-01Z' AS mapped_date, '2024-06-03Z' AS mapped_date_alt UNION ALL
      SELECT '2025-06-03Z' AS date, '2024-06-02Z' AS mapped_date, '2024-06-04Z' AS mapped_date_alt UNION ALL
      SELECT '2025-06-04Z' AS date, '2024-06-03Z' AS mapped_date, '2024-06-05Z' AS mapped_date_alt UNION ALL
      SELECT '2025-06-05Z' AS date, '2024-06-04Z' AS mapped_date, '2024-06-06Z' AS mapped_date_alt UNION ALL
      SELECT '2025-06-06Z' AS date, '2024-06-05Z' AS mapped_date, '2024-06-07Z' AS mapped_date_alt UNION ALL
      SELECT '2025-06-07Z' AS date, '2024-06-06Z' AS mapped_date, '2024-06-08Z' AS mapped_date_alt UNION ALL
      SELECT '2025-06-08Z' AS date, '2024-06-07Z' AS mapped_date, '2024-06-09Z' AS mapped_date_alt
    `,

    dimensions: {
      date_key: {
        sql: `${CUBE}.date::TIMESTAMP`,
        type: `time`,
        primary_key: true
      },

      date: {
        sql: `${CUBE}.date::TIMESTAMP`,
        type: `time`,
        time_shift: [
          {
            name: `1_year_prior`,
            sql: `${CUBE}.mapped_date::TIMESTAMP`
          },
          {
            name: `1_year_prior_alternative`,
            sql: `${CUBE}.mapped_date_alt::TIMESTAMP`
          }
        ]
      }
    }
  })

  cube(`sales`, {
    sql: `
      SELECT 101 AS id, '2024-06-01Z' AS date, 101 AS amount UNION ALL
      SELECT 102 AS id, '2024-06-02Z' AS date, 102 AS amount UNION ALL
      SELECT 103 AS id, '2024-06-03Z' AS date, 103 AS amount UNION ALL
      SELECT 104 AS id, '2024-06-04Z' AS date, 104 AS amount UNION ALL
      SELECT 105 AS id, '2024-06-05Z' AS date, 105 AS amount UNION ALL
      SELECT 106 AS id, '2024-06-06Z' AS date, 106 AS amount UNION ALL
      SELECT 107 AS id, '2024-06-07Z' AS date, 107 AS amount UNION ALL
      SELECT 108 AS id, '2024-06-08Z' AS date, 108 AS amount UNION ALL
      SELECT 109 AS id, '2024-06-09Z' AS date, 109 AS amount UNION ALL

      SELECT 202 AS id, '2025-06-02Z' AS date, 202 AS amount UNION ALL
      SELECT 203 AS id, '2025-06-03Z' AS date, 203 AS amount UNION ALL
      SELECT 204 As id, '2025-06-04Z' As date, 204 As amount UNION ALL
      SELECT 205 As id, '2025-06-05Z' As date, 205 As amount UNION ALL
      SELECT 206 As id, '2025-06-06Z' As date, 206 As amount UNION ALL
      SELECT 207 As id, '2025-06-07Z' As date, 207 As amount UNION ALL
      SELECT 208 As id, '2025-06-08Z' As date, 208 As amount
    `,

    joins: {
      sales_calendar: {
        sql: `${sales}.date = ${sales_calendar}.date_key`,
        relationship: `many_to_one`
      }
    },

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      },

      date: {
        sql: `${CUBE}.date::TIMESTAMP`,
        type: `time`,
        public: false
      }
    },
    
    measures: {
      total_amount: {
        sql: `amount`,
        type: `sum`
      },

      total_amount_1y_prior: {
        multi_stage: true,
        sql: `${total_amount}`,
        type: `number`,
        time_shift: [{
          name: `1_year_prior`
        }]
      },

      total_amount_1y_prior_alternative: {
        multi_stage: true,
        sql: `${total_amount}`,
        type: `number`,
        time_shift: [{
          name: `1_year_prior_alternative`
        }]
      }
    }
  )
  ```
</CodeGroup>

Named time shifts also allow to reuse the same time shift configuration across multiple
measures and cubes where they are defined.

### `case`

The `case` parameter is used to define conditional measures, i.e., measures that are
calculated based on the value of a [`switch` dimension][ref-switch-dimensions].

<Warning>
  `case` measures are powered by Tesseract, the [next-generation data modeling
  engine][link-tesseract]. In versions before v1.7.0, it was not enabled by default.
</Warning>

You do not need to include the [`sql` parameter](#sql) if the `case` parameter is used.
However, the [`multi_stage` parameter](#multi_stage) must be set to `true` for `case`
measures, and an `else` branch is required to provide the value when the `switch`
dimension matches none of the `when` clauses.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      dimensions:
        - name: currency
          type: switch
          values:
            - USD
            - EUR
            - GBP
      
      measures:
        - name: amount_usd
          sql: amount_usd
          type: sum

        - name: amount_eur
          sql: amount_eur
          type: sum

        - name: amount_gbp
          sql: amount_gbp
          type: sum

        - name: amount_in_currency
          multi_stage: true
          case:
            switch: "{CUBE.currency}"
            when:
              - value: EUR
                sql: "{CUBE.amount_eur}"
              - value: GBP
                sql: "{CUBE.amount_gbp}"
            else:
              sql: "{CUBE.amount_usd}"
          type: number
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    dimensions: {
      currency: {
        type: `switch`,
        values: [
          `USD`,
          `EUR`,
          `GBP`
        ]
      }
    },

    measures: {
      amount_usd: {
        sql: `amount_usd`,
        type: `sum`
      },

      amount_eur: {
        sql: `amount_eur`,
        type: `sum`
      },

      amount_gbp: {
        sql: `amount_gbp`,
        type: `sum`
      },

      amount_in_currency: {
        multi_stage: true,
        case: {
          switch: `${CUBE.currency}`,
          when: [
            {
              value: `EUR`,
              sql: `${CUBE.amount_eur}`
            },
            {
              value: `GBP`,
              sql: `${CUBE.amount_gbp}`
            }
          ],
          else: {
            sql: `${CUBE.amount_usd}`
          }
        },
        type: `number`
      }
    }
  })
  ```
</CodeGroup>

When `case` measures span multiple cubes, define the `switch` dimension on a
single shared cube joined into every fact cube, rather than defining a separate
one on each cube. All `case` measures then dispatch on the same dimension, so one
filter resolves every measure. With a `switch` dimension per cube, a single
filter pins only one of them; the others fall back to their full set of values,
and each value emits its own row — so the query returns extra rows.

### `format`

`format` is an optional parameter. It controls how measure values are
displayed to data consumers.

You can use a named format or a custom [d3-format][link-d3-format]
specifier string. Named formats accept an optional `_N` suffix (0–6)
to set the maximum decimal precision; insignificant trailing zeros are trimmed,
so `N` is an upper bound rather than a fixed number of digits. Without a suffix,
named formats default to a maximum of 2 decimal places.

| Format                        | Description                    | Example        | Output     |
| ----------------------------- | ------------------------------ | -------------- | ---------- |
| `number` / `number_N`         | Grouped fixed-point            | `number`       | 1,234.57   |
| `percent` / `percent_N`       | Percentage                     | `percent_1`    | 12.5%      |
| `currency` / `currency_N`     | Currency with grouping         | `currency_0`   | \$1,235    |
| `abbr` / `abbr_N`             | SI prefix (K, M, G, …)         | `abbr`         | 1.2K       |
| `accounting` / `accounting_N` | Negative values in parentheses | `accounting_2` | (1,234.57) |

For full control, you can also pass any valid [d3-format][link-d3-format]
specifier string directly (e.g., `$,.2f`, `.0%`, `.2s`).

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: total_amount
          sql: amount
          type: sum
          format: currency_2

        - name: conversion_rate
          sql: "1.0 * {completed_count} / {count}"
          type: number
          format: percent_1

        - name: total_revenue_abbr
          sql: revenue
          type: sum
          format: abbr

        - name: custom_formatted
          sql: amount
          type: sum
          format: "$,.2f"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      total_amount: {
        sql: `amount`,
        type: `sum`,
        format: `currency_2`
      },

      conversion_rate: {
        sql: `1.0 * ${completed_count} / ${count}`,
        type: `number`,
        format: `percent_1`
      },

      total_revenue_abbr: {
        sql: `revenue`,
        type: `sum`,
        format: `abbr`
      },

      custom_formatted: {
        sql: `amount`,
        type: `sum`,
        format: `$,.2f`
      }
    }
  })
  ```
</CodeGroup>

### `currency`

The optional `currency` parameter specifies the [ISO 4217][link-iso-4217]
currency code for the measure. Use it alongside `format: currency` to indicate
which currency the values represent, so downstream tools can display the
appropriate symbol.

The value is a 3-letter currency code (e.g., `USD`, `EUR`, `GBP`) and is
case-insensitive.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: total_amount
          sql: amount
          type: sum
          format: currency
          currency: USD

        - name: total_amount_eur
          sql: amount_eur
          type: sum
          format: currency
          currency: EUR
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      total_amount: {
        sql: `amount`,
        type: `sum`,
        format: `currency`,
        currency: `USD`
      },

      total_amount_eur: {
        sql: `amount_eur`,
        type: `sum`,
        format: `currency`,
        currency: `EUR`
      }
    }
  })
  ```
</CodeGroup>

<Info>
  The `currency` parameter can only be used with numeric measure types
  (`sum`, `avg`, `min`, `max`, `number`, `count`, `count_distinct`,
  `count_distinct_approx`). Using it with `string`, `boolean`, or `time`
  measures will result in a validation error.
</Info>

### `drill_members`

Using the `drill_members` parameter, you can define a set of [drill
down][ref-drilldowns] fields for the measure. `drill_members` is defined as an
array of dimensions. Cube automatically injects dimensions’ names and other
cubes’ names with dimensions in the context, so you can reference these
variables in the `drill_members` array. [Learn more about how to define and use
drill downs][ref-drilldowns].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      measures:
        - name: revenue
          type: sum
          sql: price
          drill_members:
            - id
            - price
            - status
            - products.name
            - products.id
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    measures: {
      revenue: {
        type: `sum`,
        sql: `price`,
        drill_members: [id, price, status, products.name, products.id]
      }
    }
  })
  ```
</CodeGroup>

[ref-ai-context]: /docs/data-modeling/ai-context

[ref-ref-cubes]: /reference/data-modeling/cube

[ref-schema-ref-types-formats-measures-formats]: /reference/data-modeling/measures#format

[ref-drilldowns]: /recipes/core-data-api/drilldowns

[ref-naming]: /docs/data-modeling/concepts/syntax#naming

[ref-playground]: /docs/explore-analyze/playground

[ref-apis]: /reference

[ref-rolling-window]: /docs/data-modeling/measures#rolling-windows

[link-tesseract]: https://cube.dev/blog/introducing-next-generation-data-modeling-engine

[ref-multi-stage]: /docs/data-modeling/measures#multi-stage-measures

[ref-time-shift]: /docs/data-modeling/measures#time-shift

[ref-nested-aggregate]: /docs/data-modeling/measures#nested-aggregates

[ref-calendar-cubes]: /docs/data-modeling/concepts/calendar-cubes

[ref-switch-dimensions]: /reference/data-modeling/dimensions#type

[ref-custom-granularities]: /reference/data-modeling/dimensions#granularities

[ref-filters-query]: /reference/core-data-apis/rest-api/query-format#filters-format

[ref-data-masking]: /docs/data-modeling/data-access-policies#data-masking

[link-d3-format]: https://d3js.org/d3-format

[link-iso-4217]: https://en.wikipedia.org/wiki/ISO_4217

[ref-calculated-measures]: /docs/data-modeling/measures#calculated-measures

[ref-schema-ref-preaggs-rollup]: /reference/data-modeling/pre-aggregations#rollup


# Pre-aggregations
Source: https://docs.cube.dev/reference/data-modeling/pre-aggregations

Pre-aggregations are materialized summaries of data that accelerate query performance by pre-computing results.

Pre-aggregations must have, at minimum, a [name](#name) and a [type](#type).
Pre-aggregations must include all dimensions and measures you will query with.

A pre-aggregation is typically placed in a cube that defines most of dimensions
and measures that this pre-aggregation includes. If a pre-aggregation doesn't
include any dimensions or measures from a cube it's defined in, this
pre-aggregation is ignored.

## Parameters

### `name`

The `name` parameter serves as the identifier of a pre-aggregation. It must be
unique among all pre-aggregations within a cube and follow the [naming
conventions][ref-naming].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: orders_by_status
          dimensions:
            - CUBE.status
          measures:
            - CUBE.count

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      orders_by_status: {
        dimensions: [
          status
        ],
        measures: [
          count
        ]
      }
    },

    // ...
  })
  ```
</CodeGroup>

This `name`, along with the name of the cube, will be used as a prefix for
pre-aggregation tables created in the database.

### `type`

Cube supports the following types of pre-aggregations:

* [`rollup`][self-rollup]
* [`original_sql`][self-originalsql]
* [`rollup_join`][self-rollupjoin]
* [`rollup_lambda`][self-rolluplambda]

The default type is `rollup`.

#### `rollup`

Rollup pre-aggregations are the most effective way to boost performance of any
analytical application. The blazing fast performance of tools like Google
Analytics or Mixpanel are backed by a similar concept. The theory behind it lies
in multi-dimensional analysis, and a rollup pre-aggregation is the result of a
[roll-up operation on an OLAP cube][wiki-olap-ops]. A rollup pre-aggregation is
essentially the summarized data of the original cube grouped by any selected
dimensions of interest.

The most performant kind of rollup pre-aggregation is an **additive** rollup:
all measures of which are based on [decomposable aggregate
functions][wiki-composable-agg-fn]. Additive measure types are: `count`, `sum`,
`min`, `max` or `count_distinct_approx`. The performance boost in this case is
based on two main properties of additive rollup pre-aggregations:

1. A rollup pre-aggregation table usually contains many fewer rows than its'
   corresponding original fact table. The fewer dimensions that are selected
   for roll-up means fewer rows in the materialized result. A smaller number of
   rows therefore means less time to query rollup pre-aggregation tables.

2. If your query is a subset of dimensions and measures of an additive rollup,
   then it can be used to calculate a query without accessing the raw data. The
   more dimensions and measures are selected for roll-up, the more queries can
   use this particular rollup.

Rollup definitions can contain members from a single cube as well as from
multiple cubes. In case of multiple cubes being involved, the join query will be
built according to the standard rules of cubes joining.

Rollups are selected for querying based on properties found in queries made to
the Cube REST (JSON) API. A thorough explanation can be found under [Getting Started
with Pre-Aggregations][ref-caching-preaggs-target].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: orders_by_company
          measures:
            - count
          dimensions:
            - status

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      orders_by_company: {
        measures: [
          count
        ],
        dimensions: [
          status
        ]
      }
    },

    // ...
  })
  ```
</CodeGroup>

#### `original_sql`

As the name suggests, it persists the results of the `sql` property of the cube
in the data source (rather than Cube Store). `original_sql` pre-aggregations should
**only** be used when the cube's `sql` is a complex query (i.e., nested subqueries,
window functions, and/or multiple joins).

<Warning>
  `originalSql` pre-aggregations **must only** be stored in the data source.
  While you can set `external: true` for `original_sql` pre-aggregation, this is
  not recommended or generally supported.
</Warning>

They often do not provide much in the way of performance directly, but there are
two specific applications:

1. They can be used in tandem with the
   [`use_original_sql_pre_aggregations`][self-origsql-preaggs] option in other
   rollup pre-aggregations.

2. Situations where it is not possible to use a `rollup` pre-aggregations, such
   as [funnels][ref-recipe-funnels].

For example, to pre-aggregate all completed orders, you could do the following:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: completed_orders
      sql: |
        SELECT *
        FROM orders
        WHERE completed = true

      pre_aggregations:
        - name: main
          type: original_sql

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`completed_orders`, {
    sql: `
      SELECT *
      FROM orders
      WHERE completed = true
    `,

    pre_aggregations: {
      main: {
        type: `original_sql`
      }
    },

    // ...
  })
  ```
</CodeGroup>

#### `rollup_join`

<Warning>
  `rollup_join` is currently in Preview, and the API may change in a future
  version.
</Warning>

<Warning>
  Rollup join is designed to join data across different data sources.
  To join data within the same data source you can list members from different
  cubes within a regular rollup. Rollup join can be used only to join two
  rollups.

  The rollup on the right side of the join is bounded by the number of physical
  Cube Store partitions it can have, which depends on your Cube Store compute
  tier. Note that these are Cube Store physical partitions — not Cube logical
  partitions.
</Warning>

Cube is capable of performing joins between pre-aggregations from different
[data sources][ref-schema-ref-cube-datasource] to avoid making excessive queries
to them.

<Warning>
  `rollup_join` is an ephemeral pre-aggregation that relies on referenced rollups
  when queries are executed. Setting
  [`scheduled_refresh`](#scheduled_refresh) to `true` is unnecessary
  for `rollup_join` and will result in an error. Appropriate freshness controls
  should be set on referenced rollups instead.
</Warning>

In the following example, we have a `users` cube with a `users_rollup`
pre-aggregation, and an `orders` cube with an `orders_rollup` pre-aggregation,
and an `orders_with_users_rollup` pre-aggregation. Note the following:

* Both cubes have different values for `data_source`.
* The type of `orders_with_users_rollup` is `rollup_join`.
* This pre-aggregation has a special property `rollups` which is an array
  containing references to both "source" rollups.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      data_source: postgres
      sql_table: users

      pre_aggregations:
        - name: users_rollup
          dimensions:
            - CUBE.id
            - CUBE.name

      measures:
        - name: count
          type: count

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: name
          sql: "{CUBE}.first_name || {CUBE}.last_name"
          type: string

    - name: orders
      data_source: mssql
      sql_table: orders

      pre_aggregations:
        - name: orders_rollup
          measures:
            - CUBE.count
          dimensions:
            - CUBE.user_id
            - CUBE.status
          time_dimension: CUBE.created_at
          granularity: day

        - name: orders_with_users_rollup
          type: rollup_join
          measures:
            - CUBE.count
          dimensions:
            - users.name
          rollups:
            - users.users_rollup
            - CUBE.orders_rollup

      joins:
        - name: users
          relationship: many_to_one
          sql: "{CUBE.user_id} = {users.id}"

      measures:
        - name: count
          type: count

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: user_id
          sql: user_id
          type: number

        - name: status
          sql: status
          type: string

        - name: created_at
          sql: created_at
          type: time
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    data_source: `postgres`,
    sql_table: `users`,

    pre_aggregations: {
      users_rollup: {
        dimensions: [CUBE.id, CUBE.name]
      }
    },

    measures: {
      count: {
        type: `count`
      }
    },

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        // We need to set this field as the primary key for joins to work
        primary_key: true
      },

      name: {
        sql: `first_name || last_name`,
        type: `string`
      }
    }
  })

  cube(`orders`, {
    data_source: `mssql`,
    sql_table: `orders`,

    pre_aggregations: {
      orders_rollup: {
        measures: [CUBE.count],
        dimensions: [CUBE.user_id, CUBE.status],
        time_dimension: CUBE.created_at,
        granularity: `day`
      },

      // Here we add a new pre-aggregation of type `rollup_join`
      orders_with_users_rollup: {
        type: `rollup_join`,
        measures: [CUBE.count],
        dimensions: [users.name],
        rollups: [users.users_rollup, CUBE.orders_rollup]
      }
    },

    joins: {
      users: {
        relationship: `many_to_one`,
        // Make sure the join uses dimensions on the cube, rather than
        // the column names from the underlying SQL
        sql: `${CUBE.user_id} = ${users.id}`
      }
    },

    measures: {
      count: {
        type: `count`
      }
    },

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      },

      user_id: {
        sql: `user_id`,
        type: `number`
      },

      status: {
        sql: `status`,
        type: `string`
      },

      created_at: {
        sql: `created_at`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

<Info>
  `rollup_join` is not required to join cubes from the same data source; instead,
  include the foreign cube's dimensions/measures in the rollup definition
  directly:
</Info>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: orders_rollup
          measures:
            - CUBE.count
          dimensions:
            - users.name
            - CUBE.status
          time_dimension: CUBE.created_at
          granularity: day
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      orders_rollup: {
        measures: [CUBE.count],
        dimensions: [users.name, CUBE.status],
        time_dimension: CUBE.created_at,
        granularity: `day`
      }
    }
  })
  ```
</CodeGroup>

<Info>
  Each referenced rollup needs an [index][self-indexes] whose leading columns
  cover the join key. For queries that also filter the joined rollup by a
  selective, single-value dimension, put that dimension before the join key in
  the index so that Cube Store can prune partitions — see
  [indexing the joined rollup for partition pruning][ref-rollup-join-indexing].
</Info>

#### `rollup_lambda`

<Warning>
  `rollup_lambda` pre-aggregations **must** be defined **before** any other
  pre-aggregations in a cube.
</Warning>

A `rollup_lambda` pre-aggregation is a special type of pre-aggregation that can
combine data from data sources and other rollups. It is extremely useful in
scenarios where real-time data is required.

[Lambda pre-aggregations][ref-caching-lambda-preaggs] can be used to combine
data from a data source and a pre-aggregation, or even from multiple
pre-aggregations across different cubes that share the same dimensions and
measures.

### `measures`

The `measures` property is an array of [measures from the
cube][ref-schema-measures] that should be included in the pre-aggregation:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: users_rollup
          measures:
            - CUBE.count

      measures:
        - name: count
          type: count
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      users_rollup: {
        measures: [CUBE.count]
      }
    },

    measures: {
      count: {
        type: `count`
      }
    }
  })
  ```
</CodeGroup>

### `dimensions`

The `dimensions` property is an array of [dimensions from the
cube][ref-schema-dimensions] that should be included in the pre-aggregation:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: users_rollup
          dimensions:
            - CUBE.status

      dimensions:
        - name: status
          type: string
          sql: status
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      users_rollup: {
        dimensions: [CUBE.status]
      }
    },

    dimensions: {
      status: {
        type: `string`,
        sql: `status`
      }
    }
  })
  ```
</CodeGroup>

### `time_dimension`

The `time_dimension` property can be any [`dimension`][ref-schema-dimensions] of
type [`time`][ref-schema-types-dim-time]. All other measures and dimensions in
the data model are aggregated. This property is an extremely useful tool for
improving performance with massive datasets.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: orders_by_status
          measures:
            - CUBE.count
          dimensions:
            - CUBE.status
          time_dimension: CUBE.created_at
          granularity: day

      measures:
        - name: count
          type: count

      dimensions:
        - name: status
          type: string
          sql: status

        - name: created_at
          type: time
          sql: created_at
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      orders_by_status: {
        measures: [CUBE.count],
        dimensions: [CUBE.status],
        time_dimension: CUBE.created_at,
        granularity: `day`
      }
    },

    measures: {
      count: {
        type: `count`
      }
    },

    dimensions: {
      status: {
        type: `string`,
        sql: `status`
      },

      created_at: {
        type: `time`,
        sql: `created_at`
      }
    }
  })
  ```
</CodeGroup>

A [`granularity`][self-granularity] **must** also be included in the
pre-aggregation definition.

### `granularity`

The `granularity` property defines the time dimension granularity of data
*within* the pre-aggregation. If set to `week`, for example, then Cube will
pre-aggregate the data by week and persist it to Cube Store.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: users_rollup_by_week
          measures:
            - CUBE.count
          dimensions:
            - CUBE.status
          time_dimension: CUBE.created_at
          granularity: week
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      users_rollup_by_week: {
        measures: [CUBE.count],
        dimensions: [CUBE.status],
        time_dimension: CUBE.created_at,
        granularity: `week`
      }
    },

    // ...
  })
  ```
</CodeGroup>

The value can be either a default granularity (i.e., `second`, `minute`, `hour`,
`day`, `week`, `month`, `quarter`, or `year`) or a [custom
granularity][ref-custom-granularity]. This property is required when using
[`time_dimension`][self-timedimension].

### `segments`

The `segments` property is an array of [segments from the
cube][ref-schema-segments] that can target the pre-aggregation:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: main
          measures:
            - CUBE.count
          segments:
            - CUBE.only_complete

      measures:
        - name: count
          type: count

      segments:
        - name: only_complete
          sql: "{CUBE}.status = 'completed'"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      main: {
        measures: [CUBE.count],
        segments: [CUBE.only_complete]
      }
    },

    measures: {
      count: {
        type: `count`
      }
    },

    segments: {
      only_complete: {
        sql: `${CUBE}.status = 'completed'`
      }
    }
  })
  ```
</CodeGroup>

### `partition_granularity`

The `partition_granularity` defines the granularity for each
[partition][ref-caching-partitioning] of the pre-aggregation:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: users_rollup
          measures:
            - CUBE.count
          dimensions:
            - CUBE.status
          time_dimension: CUBE.created_at
          granularity: day
          partition_granularity: month

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      users_rollup: {
        measures: [CUBE.count],
        dimensions: [CUBE.status],
        time_dimension: CUBE.created_at,
        granularity: `day`,
        partition_granularity: `month`
      }
    },

    // ...
  })
  ```
</CodeGroup>

The value can be one of `hour`, `day`, `week`, `month`, `quarter`, `year`. A
[`time_dimension`][self-timedimension] and [`granularity`][self-granularity]
**must** also be included in the pre-aggregation definition. This property is
required when using [partitioned pre-aggregations][ref-caching-partitioning].

Number of partitions to be built per cube is calculated as
[build\_range][self-buildrange] divided by `partition_granularity`. Number of
partitions to be built per cube is multiplied by the count of time zones and
tenants in case different tenants have different pre-aggregation SQL.

<Warning>
  Choose the count of partitions wisely as those consume memory and CPU resources.
  As a rule of thumb, you do not want to go over 500-1,000 partitions per pre-aggregation in total
  to keep the partitioning overhead low. Too many partitions will most likely
  cause out of memory.
  In case of very long build ranges please consider use [Lambda pre-aggregations][ref-caching-lambda-preaggs] to reduce partition count per pre-aggregation.
</Warning>

### `refresh_key`

Cube can also take care of keeping pre-aggregations up to date with the
`refresh_key` property. By default, it is set to `every: '1 hour'`,
if neither of the cubes' pre-aggregation references don't override `refresh_key`.

<Info>
  When using [partitioned pre-aggregations][ref-caching-partitioning], the refresh
  key is evaluated for each partition separately.
</Info>

#### `sql`

You can set up a custom refresh check strategy by using the `sql` property:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: main
          measures:
            - CUBE.count
          refresh_key:
            sql: SELECT MAX(created_at) FROM orders

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      main: {
        measures: [CUBE.count],
        refresh_key: {
          sql: `SELECT MAX(created_at) FROM orders`
        }
      }
    },

    // ...
  })
  ```
</CodeGroup>

In the above example, the refresh key SQL will be executed every 10 seconds, as
[`every`][self-refreshkey-every] is not defined. If the results of the SQL
refresh key differ from the last execution, then the pre-aggregation will be
refreshed.

#### `every`

The `refresh_key` can define an `every` property which can be used to refresh
pre-aggregations based on a time interval. By default, it is set to `1 hour`
unless the [`sql` property][self-refreshkey-sql] is also defined in any of cubes pre-aggregation references, in which case
it is set to `10 seconds`. For example:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: main
          measures:
            - CUBE.count
          refresh_key:
            every: 1 day

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      main: {
        measures: [CUBE.count],
        refresh_key: {
          every: `1 day`
        }
      }
    },

    // ...
  })
  ```
</CodeGroup>

To have a pre-aggregation rebuild at a specific time of day, you can use a CRON string with some limitations. For more details about values that can be used with the `every` parameter, please refer to the
[`refreshKey`][ref-cube-refreshkey] documentation.

You can also use `every` with `sql`:

<Warning>
  Using CRON strings and `sql` is not supported and will result in a compilation error.
</Warning>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: main
          measures:
            - CUBE.count
          refresh_key:
            every: 1 hour
            sql: SELECT MAX(created_at) FROM orders
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      main: {
        measures: [CUBE.count],
        refreshKey: {
          every: `1 hour`,
          sql: `SELECT MAX(created_at) FROM orders`
        }
      }
    }
  })
  ```
</CodeGroup>

In the above example, the refresh key SQL will be executed every hour. If the
results of the SQL refresh key differ from the last execution, then the
pre-aggregation will be refreshed.

<Warning>
  The `every` parameter guarantees that the refresh key will be executed **at
  least** once during the specified interval. However, it does **not** guarantee
  that it will be executed **at most** once. The refresh key may be checked more
  frequently.

  When using `every` with `sql`, the purpose is to reduce the load from running
  the refresh key query itself, not to minimize the number of pre-aggregation
  refreshes. The refresh key SQL should be designed to return consistent results
  and only change when the underlying data needs to be updated, ensuring minimal
  refreshes even if the query is executed multiple times.
</Warning>

#### `incremental`

You can incrementally refresh partitioned rollups by setting
`incremental: true`. This option defaults to `false`.

<Warning>
  Partition tables are refreshed as a whole. When a new partition table is
  available, it replaces the old one. Old partition tables are collected by a
  garbage collection mechanism. Append is never used to add new rows to the
  existing tables.
</Warning>

<Warning>
  Because incremental refreshes generate their own SQL, you **must not** use the
  [`sql`](#refresh_key) property here.
</Warning>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: main
          measures:
            - CUBE.count
          time_dimension: CUBE.created_at
          granularity: day
          partition_granularity: day
          refresh_key:
            every: 1 day
            incremental: true

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      main: {
        measures: [CUBE.count],
        time_dimension: CUBE.created_at,
        granularity: `day`,
        partition_granularity: `day`,
        refresh_key: {
          every: `1 day`,
          incremental: true
        }
      }
    },

    // ...
  })
  ```
</CodeGroup>

#### `update_window`

<Warning>
  Incremental refreshes without a defined `update_window` will only update the
  last partition as determined by the pre-aggregation's `partition_granularity`.
</Warning>

The `incremental: true` flag generates a special `refresh_key` SQL query which
triggers a refresh for partitions where the end date lies within the
`update_window` from the current time.

<Warning>
  Because incremental refreshes generate their own SQL, you **must not** use the
  [`sql`](#refresh_key) property here.
</Warning>

In the example below, it will refresh today's and the last 7 days of partitions
once a day. Partitions before the `7 day` interval **will not** be refreshed
once they are built unless the rollup SQL is changed.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: main
          measures:
            - CUBE.count
          time_dimension: CUBE.created_at
          granularity: day
          partition_granularity: day
          refresh_key:
            every: 1 day
            incremental: true
            update_window: 7 day

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      main: {
        measures: [CUBE.count],
        time_dimension: CUBE.created_at,
        granularity: `day`,
        partition_granularity: `day`,
        refresh_key: {
          every: `1 day`,
          incremental: true,
          update_window: `7 day`
        }
      }
    },

    // ...
  })
  ```
</CodeGroup>

This property is required when using [`incremental`][self-incremental]
refreshes.

### `allow_non_strict_date_range_match`

The `allow_non_strict_date_range_match` parameter is used to allow queries to match a
pre-aggregation even if a query contains a *non-strict date range*. It is set to `true`
by default via the \[[`CUBEJS_PRE_AGGREGATIONS_ALLOW_NON_STRICT_DATE_RANGE_MATCH`](/reference/configuration/environment-variables#cubejs_pre_aggregations_allow_non_strict_date_range_match)][ref-env-allow-non-strict]
environment variable.

If this flag is set to `false`, Cube would check if requested date range exactly matches
pre-aggregation granularity. For example, if you're requesting half of a day or your date
range filter is just one millisecond off for a pre-aggregation with the daily granularity,
Cube would not use such a pre-aggregation.

With this flag set to `true`, that strict check is lifted. It allows queries from BI tools
to still match pre-aggregations at the cost of a slight potential data discrepancy.
This is convenient when using Cube with visualization tools that use loose date ranges.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: main
          measure:
            - CUBE.count
          time_dimension: CUBE.created_at
          granularity: day
          partition_granularity: day
          allow_non_strict_date_range_match: true
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql: `orders`,

    pre_aggregations: {
      main: {
        measure: [CUBE.count],
        time_dimension: CUBE.created_at,
        granularity: `day`,
        partition_granularity: `day`,
        allow_non_strict_date_range_match: true
      }
    },

    // ...
  })
  ```
</CodeGroup>

### `use_original_sql_pre_aggregations`

Cube supports multi-stage pre-aggregations by reusing original SQL
pre-aggregations in rollups through the `use_original_sql_pre_aggregations`
property. It is helpful in cases where you want to re-use a heavy SQL query
calculation in multiple `rollup` pre-aggregations. Without
`use_original_sql_pre_aggregations` enabled, Cube will always re-execute all
underlying SQL calculations every time it builds new rollup tables.

<Warning>
  `originalSql` pre-aggregations **must only** be stored in the data source.
  While you can set `external: true` for `original_sql` pre-aggregation, this is
  not recommended or generally supported.
</Warning>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql: |
        SELECT * FROM orders1 UNION ALL SELECT * FROM orders2 UNION ALL SELECT *
        FROM orders3

      pre_aggregations:
        - name: main
          type: original_sql

        - name: statuses
          measures:
            - CUBE.count
          dimensions:
            - CUBE.status
          use_original_sql_pre_aggregations: true

        - name: completed_orders
          measures:
            - CUBE.count
          time_dimension: CUBE.completed_at
          granularity: day
          use_original_sql_pre_aggregations: true

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql: `
      SELECT * FROM orders1
      UNION ALL
      SELECT * FROM orders2
      UNION ALL
      SELECT * FROM orders3
    `,

    pre_aggregations: {
      main: {
        type: `original_sql`
      },

      statuses: {
        measures: [CUBE.count],
        dimensions: [CUBE.status],
        use_original_sql_pre_aggregations: true
      },

      completed_orders: {
        measures: [CUBE.count],
        time_dimension: CUBE.completed_at,
        granularity: `day`,
        use_original_sql_pre_aggregations: true
      }
    },

    // ...
  })
  ```
</CodeGroup>

### `scheduled_refresh`

To always keep pre-aggregations up-to-date, you can set
`scheduled_refresh: true`. This option defaults to `true`.
In production mode, pre-aggregations with `scheduled_refresh: false` will not be
built automatically and require external orchestration to trigger their refresh.
Additionally, any `scheduled_refresh: false` pre-aggregations that were built manually or on-demand will be considered
stale and orphaned over time, and will be dropped by the refresh worker during
cleanup processes.
The [`refresh_key`][self-refreshkey] is used to determine if there's a need to
update specific pre-aggregations on each scheduled refresh run. For partitioned
pre-aggregations, `min` and `max` dates for
[`time_dimension`][self-timedimension] are checked to determine range for the
refresh.

Each time a scheduled refresh is run, it takes every pre-aggregation partition
starting with most recent ones in time and checks if the
[`refresh_key`][self-refreshkey] has changed. If a change was detected, then
that partition will be refreshed.

In [development mode](/reference/configuration/environment-variables#cubejs_dev_mode),
Cube runs the background refresh by default and will refresh all pre-aggregations
which have `scheduled_refresh: true`.

Please consult [Production Checklist][ref-production-checklist-refresh] for best
practices on running background refresh in production environments.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: orders_by_status
          measures:
            - CUBE.count
          dimensions:
            - CUBE.status
          time_dimension: CUBE.created_at
          granularity: day
          partition_granularity: month

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      orders_by_status: {
        measures: [CUBE.count],
        dimensions: [CUBE.status],
        time_dimension: CUBE.created_at,
        granularity: `day`,
        partition_granularity: `month`
      }
    },

    // ...
  })
  ```
</CodeGroup>

### `build_range_start` and `build_range_end`

<Warning>
  Currently `build_range_start` and `build_range_end` doesn't have any effect on
  pre-aggregations without `partition_granularity`. This behavior can be changed
  in future versions.
</Warning>

<Warning>
  Cube will **not** return results outside of the defined build range. Data will
  **only** be queried within this range, which can lead to an empty result set,
  depending on the query. Consider using [Lambda
  pre-aggregations][self-rolluplambda] if you want to query data outside of the
  build range.
</Warning>

The build range defines what partitions should be built by a scheduled refresh.
By default, the build range is defined as the minimum and maximum values
possible for the [`time_dimension`][self-timedimension] used in the rollup.

<Warning>
  The SQL queries for the build range (as defined by the `sql` property) are
  executed based on the [`refresh_key`][self-refreshkey] settings of the
  pre-aggregation.

  In case of very small `update_window` or `FILTER_PARAMS` are used in the [`refresh_key`][self-refreshkey] definition
  and the current timestamp is used as `build_range_end`, there's a possibility
  to write [`refresh_key`][self-refreshkey] which won't refresh due to cycle dependency on each other.
  To address such cases, you can use relative date in the future for the `build_range_end`.
  For example, you can add one day to the current timestamp and use it as `build_range_end`.
  The actual value to be added depends on how frequently `refresh_key` is updated.

  On the other hand, if the current timestamp is used as `build_range_end`, it can trigger
  updates of the first and last partitions more frequently than the [`refresh_key`][self-refreshkey] does,
  since the build range boundaries change with each evaluation.
</Warning>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: main
          measures:
            - CUBE.count
          time_dimension: CUBE.created_at
          granularity: day
          partition_granularity: month
          build_range_start:
            sql: SELECT CURRENT_DATE - INTERVAL '300 day'
          build_range_end:
            sql: SELECT CURRENT_DATE

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      main: {
        measures: [CUBE.count],
        time_dimension: CUBE.created_at,
        granularity: `day`,
        partition_granularity: `month`,
        build_range_start: {
          sql: `SELECT CURRENT_DATE - INTERVAL '300 day'`
        },
        build_range_end: {
          sql: `SELECT CURRENT_DATE`
        }
      }
    },

    // ...
  })
  ```
</CodeGroup>

It can be used together with the pre-aggregation's `refresh_key` to define
granular update settings. Set `refresh_key.update_window` to the interval in
which your data can change and `build_range_start` to the earliest point of time
when history should be available.

In the following example, `refresh_key.update_window` is `1 week` and
`build_range_start` is `SELECT NOW() - INTERVAL '365 day'`, so the scheduled
refresh will build historical partitions for 365 days in the past and will only
refresh last week's data.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: main
          measures:
            - CUBE.count
          time_dimension: CUBE.created_at
          granularity: day
          partition_granularity: month
          build_range_start:
            sql: SELECT NOW() - INTERVAL '365 day'
          build_range_end:
            sql: SELECT NOW()
          refresh_key:
            update_window: 1 week
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      main: {
        measures: [CUBE.count],
        time_dimension: CUBE.created_at,
        granularity: `day`,
        partition_granularity: `month`,
        build_range_start: {
          sql: `SELECT NOW() - INTERVAL '365 day'`
        },
        build_range_end: {
          sql: `SELECT NOW()`
        },
        refresh_key: {
          update_window: `1 week`
        }
      }
    },

    // ...
  })
  ```
</CodeGroup>

### `union_with_source_data`

This option allows combining a pre-aggregation with fresh data retrieved from
the data source; this is extremely useful in scenarios where latency can be
sacrificed for accuracy.

To configure a pre-aggregation to behave in this way, ensure the pre-aggregation
is of type `rollup_lambda`, and then set `union_with_source_data` to `true`:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: lambda
          type: rollup_lambda
          union_with_source_data: true
          rollups:
            - orders.main
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    pre_aggregations: {
      lambda: {
        type: `rollup_lambda`,
        union_with_source_data: true,
        rollups: [orders.main]
      }
    }
  })
  ```
</CodeGroup>

### `indexes`

This option allows to define [indexes][ref-indexes]. Indexes are used to
fine-tune pre-aggregation performance when pre-aggregations have significant
cardinality. (For [aggregating indexes][ref-aggregating-indexes], see the
[`type` option](#type-2) below.)

Here's how you can define an index:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: category_and_date
          measures:
            - count
          dimensions:
            - category
          time_dimension: created_at
          granularity: day
          indexes:
            - name: category_index
              columns:
                - category

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      category_and_date: {
        measures: [
          count
        ],
        dimensions: [
          category
        ],
        time_dimension: created_at,
        granularity: `day`,
        indexes: {
          category_index: {
            columns: [
              category
            ]
          }
        }
      }
    },

    // ...
  })
  ```
</CodeGroup>

To reference a time dimension column with its granularity in the index,
use the `CUBE.<time_dimension>.<granularity>` syntax:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: category_and_date
          measures:
            - CUBE.count
          dimensions:
            - CUBE.category
          time_dimension: CUBE.created_at
          granularity: day
          indexes:
            - name: category_created_at_index
              columns:
                - CUBE.category
                - CUBE.created_at.day
      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      category_and_date: {
        measures: [
          CUBE.count
        ],
        dimensions: [
          CUBE.category
        ],
        time_dimension: CUBE.created_at,
        granularity: `day`,
        indexes: {
          category_created_at_index: {
            columns: [
              CUBE.category,
              CUBE.created_at.day
            ]
          }
        }
      }
    },

    // ...
  })
  ```
</CodeGroup>

Alternatively, you can reference the time dimension column as a string
using the `<cube_name>__<time_dimension_name>_<granularity>` format:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      # ...

      pre_aggregations:
        - name: category_and_date
          # ...

          indexes:
            - name: category_created_at_index
              columns:
                - CUBE.category
                - "{'orders__created_at_day'}"
      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    // ...

    pre_aggregations: {
      category_and_date: {
        // ...

        indexes: {
          category_created_at_index: {
            columns: [
              CUBE.category,
              `orders__created_at_day`
            ]
          }
        }
      }
    },

    // ...
  })
  ```
</CodeGroup>

The same approach works for `original_sql` pre-aggregations:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: main
          type: original_sql
          indexes:
            - name: timestamp_index
              columns:
                - timestamp
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      main: {
        type: `original_sql`,
        indexes: {
          timestamp_index: {
            columns: [
              `timestamp`
            ]
          }
        }
      }
    }
  })
  ```
</CodeGroup>

<Note>
  In some cases, indexes would not work with `original_sql` pre-aggregations.
  Please [track this issue](https://github.com/cube-js/cube/issues/7420).
</Note>

#### `type`

This option is used to define [aggregating indexes][ref-aggregating-indexes]
that contain **only** dimensions and pre-aggregated measures from the
pre-aggregation definition.

<Note>
  A query can only target an aggregating index when every measure it uses is
  [additive](/docs/pre-aggregations/matching-pre-aggregations)
  (e.g. built on `sum`, `count`, `min`, `max`, or `countDistinctApprox`), and every
  dimension and filter in the query is one of the index's `columns`. Non-additive
  measures, such as `avg` or exact `countDistinct`, cannot use an aggregating index.
  Queries that don't qualify automatically fall back to a regular index.
</Note>

Here's how you can define an aggregating index:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders

      pre_aggregations:
        - name: category_and_date
          measures:
            - CUBE.count
          dimensions:
            - CUBE.status
          time_dimension: CUBE.created_at
          granularity: day
          indexes:
            - name: category_index
              columns:
                - CUBE.status
                - Products.name
            - name: aggregating_index
              columns:
                - CUBE.status
              type: aggregate

      # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,

    pre_aggregations: {
      category_and_date: {
        measures: [
          CUBE.count
        ],
        dimensions: [
          CUBE.status
        ],
        time_dimension: CUBE.created_at,
        granularity: `day`,
        indexes: {
          category_index: {
            columns: [
              CUBE.status,
              products.name
            ]
          },
          aggregating_index: {
            columns: [
              CUBE.status
            ],
            type: `aggregate`
          }
        }
      }
    },

    // ...
  })
  ```
</CodeGroup>

[ref-caching-lambda-preaggs]: /docs/pre-aggregations/lambda-pre-aggregations

[ref-caching-partitioning]: /docs/pre-aggregations/using-pre-aggregations#partitioning

[ref-caching-preaggs-target]: /docs/pre-aggregations/matching-pre-aggregations#matching-algorithm

[ref-cube-refreshkey]: /reference/data-modeling/cube#refresh_key

[ref-production-checklist-refresh]: /cube-core/running-in-production#set-up-refresh-worker

[ref-recipe-funnels]: /recipes/data-modeling/funnels

[ref-schema-ref-cube-datasource]: /reference/data-modeling/cube#data_source

[ref-schema-dimensions]: /reference/data-modeling/dimensions

[ref-schema-measures]: /reference/data-modeling/measures

[ref-schema-segments]: /reference/data-modeling/segments

[ref-schema-types-dim-time]: /reference/data-modeling/dimensions#type

[ref-naming]: /docs/data-modeling/concepts/syntax#naming

[self-granularity]: #granularity

[self-incremental]: #incremental

[self-origsql-preaggs]: #use_original_sql_pre_aggregations

[self-originalsql]: #original_sql

[self-refreshkey]: #refresh_key

[self-refreshkey-every]: #every

[self-refreshkey-sql]: #sql

[self-rollup]: #rollup

[self-rollupjoin]: #rollup_join

[self-indexes]: #indexes

[self-rolluplambda]: #rollup_lambda

[self-timedimension]: #time_dimension

[self-buildrange]: #build_range_start-and-build_range_end

[wiki-olap-ops]: https://en.wikipedia.org/wiki/OLAP_cube#Operations

[wiki-composable-agg-fn]: https://en.wikipedia.org/wiki/Aggregate_function#Decomposable_aggregate_functions

[ref-indexes]: /docs/pre-aggregations/using-pre-aggregations#using-indexes

[ref-aggregating-indexes]: /docs/pre-aggregations/using-pre-aggregations#aggregating-indexes

[ref-pre-aggs]: /docs/pre-aggregations/using-pre-aggregations

[ref-ref-cubes]: /reference/data-modeling/cube

[ref-custom-granularity]: /reference/data-modeling/dimensions#granularities

[ref-env-allow-non-strict]: /reference/configuration/environment-variables#cubejs-pre-aggregations-allow-non-strict-date-range-match

[ref-rollup-join-indexing]: /docs/pre-aggregations/using-pre-aggregations#indexing-the-joined-rollup-for-partition-pruning


# Segments
Source: https://docs.cube.dev/reference/data-modeling/segments

Segments are predefined, reusable filters that package common SQL predicates for use in queries and tooling.

You can use the `segments` parameter within [cubes][ref-ref-cubes] to define segments.
Segments are predefined filters. You can use segments to define complex filtering logic in SQL.

For example, users for one particular city can be treated as a segment:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      # ...

      segments:
        - name: sf_users
          sql: "{CUBE}.location = 'San Francisco'"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    // ...
    segments: {
      sf_users: {
        sql: `${CUBE}.location = 'San Francisco'`
      }
    }
  })
  ```
</CodeGroup>

Or use segments to implement cross-column `OR` logic:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      # ...

      segments:
        - name: sf_users
          sql: |
            {CUBE}.location = 'San Francisco' OR {CUBE}.state = 'CA'
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    // ...

    segments: {
      sf_users: {
        sql: `
          ${CUBE}.location = 'San Francisco' OR
          ${CUBE}.state = 'CA'
        `
      }
    }
  })
  ```
</CodeGroup>

As with other cube member definitions, segments can be
[generated][ref-schema-gen]:

```javascript theme={"dark"}
const userSegments = {
  sf_users: ["San Francisco", "CA"],
  ny_users: ["New York City", "NY"]
}

cube(`users`, {
  // ...

  segments: {
    ...Object.keys(userSegments)
      .map((segment) => ({
        [segment]: {
          sql: `${CUBE}.location = '${userSegments[segment][0]}' or ${CUBE}.state = '${userSegments[segment][1]}'`
        }
      }))
      .reduce((a, b) => ({ ...a, ...b }))
  }
})
```

After defining a segment, you can pass it in [query object][ref-backend-query]:

```json theme={"dark"}
{
  "measures": ["users.count"],
  "segments": ["users.sf_users"]
}
```

## Parameters

### `name`

The `name` parameter serves as the identifier of a segment. It must be unique
among all segments, dimensions, and measures within a cube and follow the
[naming conventions][ref-naming].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      # ...

      segments:
        - name: sf_users
          sql: "{CUBE}.location = 'San Francisco'"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    // ...

    segments: {
      sf_users: {
        sql: `${CUBE}.location = 'San Francisco'`
      }
    }
  })
  ```
</CodeGroup>

### `description`

This parameter provides a human-readable description of a segment.
When applicable, it will be displayed in [Playground][ref-playground] and exposed
to data consumers via [APIs and integrations][ref-apis].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      # ...

      segments:
        - name: sf_users
          sql: "{CUBE}.location = 'San Francisco'"
          description: Users from San Francisco
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    // ...

    segments: {
      sf_users: {
        sql: `${CUBE}.location = 'San Francisco'`,
        description: `Users from San Francisco`
      }
    }
  })
  ```
</CodeGroup>

### `public`

The `public` parameter is used to manage the visibility of a segment. Valid
values for `public` are `true` and `false`. When set to `false`, this segment
**cannot** be queried through the API. Defaults to `true`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      segments:
        - name: sf_users
          sql: "{CUBE}.location = 'San Francisco'"
          public: false
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    segments: {
      sf_users: {
        sql: `${CUBE}.location = 'San Francisco'`,
        public: false
      }
    }
  })
  ```
</CodeGroup>

### `sql`

The `sql` parameter defines how a segment would filter out a subset of data. It
takes any SQL expression that would be valid within a `WHERE` statement.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      # ...

      segments:
        - name: sf_users
          sql: "{CUBE}.location = 'San Francisco'"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    // ...

    segments: {
      sf_users: {
        sql: `${CUBE}.location = 'San Francisco'`
      }
    }
  })
  ```
</CodeGroup>

## Segments vs Dimension Filters

As segments are simply predefined filters, it can be difficult to determine when
to use segments instead of filters on dimensions.

Let's consider an example:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      # ...

      dimensions:
        - name: location
          sql: location
          type: string

      segments:
        - name: sf_users
          sql: "{CUBE}.location = 'San Francisco'"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    // ...

    dimensions: {
      location: {
        sql: `location`,
        type: `string`
      }
    },

    segments: {
      sf_users: {
        sql: `${CUBE}.location = 'San Francisco'`
      }
    }
  })
  ```
</CodeGroup>

In this case following queries are equivalent:

```json theme={"dark"}
{
  "measures": ["users.count"],
  "filters": [
    {
      "member": "users.location",
      "operator": "equals",
      "values": ["San Francisco"]
    }
  ]
}
```

and

```json theme={"dark"}
{
  "measures": ["users.count"],
  "segments": ["users.sf_users"]
}
```

This case is a bad candidate for segment usage and a filter on a dimension works
better here. `users.location` filter value can change a lot for user queries and
`users.sf_users` segment won't be used much in this case.

A good candidate case for a segment is when you have a complex filtering
expression which can be reused for a lot of user queries. For example:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: users
      # ...

      segments:
        - name: sf_ny_users
          sql: |
            {CUBE}.location = 'San Francisco' OR {CUBE}.location like '%New York%'
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`users`, {
    // ...

    segments: {
      sf_ny_users: {
        sql: `
          ${CUBE}.location = 'San Francisco' OR
          ${CUBE}.location like '%New York%'
        `
      }
    }
  })
  ```
</CodeGroup>

[ref-ref-cubes]: /reference/data-modeling/cube

[ref-backend-query]: /reference/core-data-apis/rest-api/query-format

[ref-schema-gen]: /recipes/data-modeling/using-dynamic-measures

[ref-naming]: /docs/data-modeling/concepts/syntax#naming

[ref-playground]: /docs/explore-analyze/playground

[ref-apis]: /reference


# Views
Source: https://docs.cube.dev/reference/data-modeling/view

Views are curated compositions of cube members that simplify consumption and clarify join paths for downstream tools.

Views sit on top of the data graph of [cubes][ref-ref-cubes] and create a facade of your whole
data model with which data consumers can interact. They are useful for defining
metrics, managing governance and data access, and controlling ambiguous join
paths.

Any view should have the following parameters: [`name`](#name) and [`cubes`](#cubes).

## Parameters

### `name`

The `name` parameter serves as the identifier of a view. It must be unique among
*all cubes and views* within a deployment and follow the [naming
conventions][ref-naming].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: active_users
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`active_users`, {})

  ```
</CodeGroup>

### `extends`

You can use the `extends` parameter to [extend views][ref-extension] in order to reuse
all declared members of a view.

In the example below, `extended_orders` will extend `orders` with an additional join path:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: orders
      cubes:
        - join_path: base_orders
          includes: "*"

    - name: extended_orders
      extends: orders
      cubes:
        - join_path: base_orders.users
          includes: "*"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`orders`, {
    cubes: [
      {
        join_path: `base_orders`,
        includes: `*`
      }
    ]
  })

  view(`extended_orders`, {
    extends: orders,
    cubes: [
      {
        join_path: `base_orders.users`,
        includes: `*`
      }
    ]
  })
  ```
</CodeGroup>

### `title`

Use the `title` parameter to change the display name of the view.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: orders
      sql_table: orders
      title: Product Orders
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`orders`, {
    sql_table: `orders`,
    title: `Product Orders`
  })
  ```
</CodeGroup>

### `description`

This parameter provides a human-readable description of a view.
When applicable, it will be displayed in [Playground][ref-playground] and exposed
to data consumers via [APIs and integrations][ref-apis].

A description can give a hint both to your team and end users, making sure they
interpret the data correctly.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: active_users
      description: 14 days rolling count of active users
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`active_users`, {
    description: `14 days rolling count of active users`
  })
  ```
</CodeGroup>

### `public`

The `public` parameter is used to manage the visibility of a view. Valid values
for `public` are `true` and `false`. When set to `false`, this view **cannot**
be queried through the API. Defaults to `true`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: orders
      public: false
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`orders`, {
    public: false
  })
  ```
</CodeGroup>

You can also use `COMPILE_CONTEXT` for dynamic visibility if necessary, check
out our
[Controlling access to cubes and views ](/docs/data-modeling/access-control)
recipe.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: arr
      description: Annual Recurring Revenue
      public: COMPILE_CONTEXT.security_context.is_finance

      cubes:
        - join_path: revenue
          includes:
            - arr
            - date

        - join_path: revenue.customers
          includes:
            - plan
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`arr`, {
    description: `Annual Recurring Revenue`,
    public: COMPILE_CONTEXT.security_context.is_finance,

    cubes: [
      {
        join_path: revenue,
        includes: [
          `arr`,
          `date`
        ]
      },
      {
        join_path: revenue.customers,
        includes: `plan`
      }
    ]
  })
  ```
</CodeGroup>

To learn more about using `public` to control visibility based on security
context, read the [Controlling access to cubes and views
recipe][ref-recipe-control-access-cubes-views].

### `meta`

Custom metadata. Can be used to pass any information to the frontend.

You can also use the `ai_context` key to provide context to the
[AI agent][ref-ai-context] without exposing it in the user interface.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: active_users
      meta:
        any: value
        ai_context: >
          This view shows users active in the last 14 days.
          Use for engagement analysis questions.

  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`active_users`, {
    meta: {
      any: `value`,
      ai_context: `This view shows users active in the last 14 days.
        Use for engagement analysis questions.`
    }
  })
  ```
</CodeGroup>

#### `auto_run`

In the Cube cloud platform, you can use the `auto_run` key in a view's `meta`
to control whether [workbook][ref-workbook-running] queries against the view
run automatically. By default, a workbook re-runs the query every time a data
consumer changes it — adds a member, edits a filter, and so on. Setting
`auto_run: false` turns this off for the view: the query only runs when the
user clicks **Run query**.

This is useful for views backed by heavy or expensive queries, where running
on every change would be wasteful.

<Info>
  Please note, currently `auto_run` is defined inside the `meta` property; this
  may change in the future.
</Info>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: orders_view

      cubes:
        - join_path: orders
          includes: "*"

      meta:
        auto_run: false
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`orders_view`, {
    cubes: [
      {
        join_path: orders,
        includes: `*`
      }
    ],

    meta: {
      auto_run: false
    }
  });
  ```
</CodeGroup>

The setting only provides the default for the view. Data consumers can toggle
auto-run on or off in each workbook tab, and their choice takes precedence
over the view's default. When `auto_run` is not set, auto-run is on.

#### `default_ui_filters`

In the Cube cloud platform, you can use the `default_ui_filters` key in a
view's `meta` to define default filters for [workbooks][ref-workbook-filtering],
views embedded via the React Embed SDK, and the Google Sheets / Excel add-in.
When the view is selected, these filters are pre-populated as regular, fully
editable filters — data consumers can change their values, switch operators,
or remove them entirely.

Each entry has a `member` (a dimension or measure exposed by the view), an
`operator`, and a list of `values` — or a single `value`, which is natural for
single-value operators. The null and empty checks take no value.

<Info>
  Please note, currently default UI filters are defined inside the `meta`
  property; this may change in the future.
</Info>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: orders_view

      cubes:
        - join_path: orders
          includes: "*"

      meta:
        default_ui_filters:
          # "is yesterday" → equality at day grain, shows yesterday's data
          - member: created_at
            operator: is
            value: yesterday
          # Rolling window → use "between" with two bounds
          - member: updated_at
            operator: between
            values: ["7 days ago", "today"]
          - member: status
            operator: is
            values: ["completed", "shipped"]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`orders_view`, {
    cubes: [
      {
        join_path: orders,
        includes: `*`
      }
    ],

    meta: {
      default_ui_filters: [
        // "is yesterday" → equality at day grain, shows yesterday's data
        {
          member: `created_at`,
          operator: `is`,
          value: `yesterday`
        },
        // Rolling window → use "between" with two bounds
        {
          member: `updated_at`,
          operator: `between`,
          values: [`7 days ago`, `today`]
        },
        {
          member: `status`,
          operator: `is`,
          values: [`completed`, `shipped`]
        }
      ]
    }
  });
  ```
</CodeGroup>

##### Operators

Operators use the same labels data consumers see in the workbook filter bar —
what you see in the filter bar is what you type:

* Any member: `is`, `is not`, `is null`, `is not null`.
* Strings: `contains`, `not contains`, `starts with`, `not starts with`,
  `ends with`, `not ends with`, `is empty`, `is not empty`.
* Numbers: `greater than`, `greater than or equal`, `less than`,
  `less than or equal`, `between`.
* Dates and times: `after`, `after or on`, `before`, `before or on`, `between`,
  and the period comparisons `in the month`, `not in the month`,
  `in the quarter`, `not in the quarter`, `in the year`, `not in the year`. A
  period comparison takes any date inside the period, so `in the year` with
  `2026-03-14` means all of 2026.

Operators are case-insensitive and whitespace-tolerant. Internal type names and
REST (JSON) API aliases (e.g. `equals`, `gte`, `inDateRange`) are also accepted,
as are the older `after date` / `before or on date` spellings the filter bar used
before the noun was dropped.

On a date or time member, `is` with a relative value is an **equality** at that
value's grain, not a range — `is yesterday` matches yesterday only (e.g.
`DATE_TRUNC('day', created_at) = CURRENT_DATE - INTERVAL '1 day'`), and
`is this month` matches the current month. For a rolling window, use `between`
with two bounds.

##### Relative date values

A `between` filter always takes an explicit two-element `[start, end]` pair.
Each bound is one of:

* **A relative value**: `today`, `yesterday`,
  `N days|weeks|months|quarters|years ago` (e.g. `7 days ago`),
  `N ... from now` (e.g. `2 weeks from now`), or
  `this week|month|quarter|year`. `now` is accepted as an alias for `today`.
* **A fixed ISO date**: `"2026-01-15"`, meaning that whole day.
* **A number**, for numeric members.

Relative values also work with `is` and the open-ended comparison operators —
for example, `after date` with `value: 7 days ago`.

Relative bounds resolve when a query runs, not when the filter is seeded:
`["7 days ago", "today"]` produces SQL based on the current date (e.g.
`BETWEEN CURRENT_DATE - INTERVAL '7 days' AND CURRENT_DATE`), so the window
rolls forward day over day. Both bounds are inclusive — `["7 days ago",
"today"]` covers 8 calendar days for daily data. In the workbook, the seeded
filter opens the date editor on the **Relative** tab showing its bounds.

Values are case- and whitespace-insensitive. Entries are validated: an
unrecognized operator or value, or a `between` filter without exactly two
bounds, drops that filter entry with a browser-console warning — the remaining
entries still apply, and view selection never breaks.

Unlike [`default_filters`](#default_filters), which are enforced on every query
against the view, `default_ui_filters` only provide a starting point: they
don't apply to queries made through APIs or other visualization tools, and
data consumers can freely modify or remove them. They also only apply to new
queries — defining or changing them in the data model does not add them to
existing queries or saved explorations.

### `cubes`

Use `cubes` parameter in view to include exposed cubes in bulk. You can build
your view by combining multiple joined cubes together and specifying the path by
which they should be joined for that particular view.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: orders

      cubes:
        - join_path: base_orders
          includes:
            - status
            - created_date
            - total_amount
            - total_amount_shipped
            - count
            - average_order_value

        - join_path: base_orders.line_items.products
          includes:
            - name: name
              alias: product
              title: My custom product
              description: My custom product description
              format: number
              meta:
                some: custom
                meta: data

        - join_path: base_orders.users
          prefix: true
          includes: "*"
          excludes:
            - company
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`orders`, {
    cubes: [
      {
        join_path: base_orders,
        includes: [
          `status`,
          `created_date`,
          `total_amount`,
          `total_amount_shipped`,
          `count`,
          `average_order_value`
        ]
      },
      {
        join_path: base_orders.line_items.products,
        includes: [
          {
            name: `name`,
            alias: `product`,
            title: `My custom product`,
            description: `My custom product description`,
            format: `number`,
            meta: {
              some: `custom`,
              meta: `data`
            }
          }
        ]
      },
      {
        join_path: base_orders.users,
        prefix: true
        includes: `*`,
        excludes: [
          `company`
        ]
      }
    ]
  })
  ```
</CodeGroup>

#### `join_path`

When listing cubes to expose, you need to provide a `join_path` parameter.
It uses the "dot notation" to describe the join path: `cube_1.cube_2.cube_3`.

For the root cube of the view, just use the cube name as in the example
above for `base_orders`.

#### `includes` and `excludes`

The other required parameter inside the `cubes` block is `includes`. Use it
to list measures, dimensions, [hierarchies][ref-ref-hierarchies], or segments
you'd like to include into the view.

To include all members from a cube, use the *includes all* shorthand: `includes: "*"`.
In that case, you can also use the `excludes` parameter to list members that
you'd like to exclude.

<Info>
  A view defines its own surface, so included members don't inherit the
  [`public`][ref-dim-public] flag from the underlying cube: a member that is
  `public: false` on the cube becomes queryable through the view. Use `excludes`
  to keep such members out of the view.
</Info>

#### `prefix`

If you'd like to prefix exposed members with the cube name, you can do so by setting the
`prefix` parameter to `true`. It will prefix members with the cube name, e.g. `users_city`.
You can use the [`alias` parameter](#alias) to specify a custom prefix.

#### `alias`

If you'd like to [rename][ref-dim-name] an included member, you can use the `alias`
parameter.

#### `title`

If you'd like to override the [title][ref-dim-title] of a member, you can use the
`title` parameter.

#### `description`

If you'd like to override the [description][ref-dim-description] of a member, you
can use the `description` parameter.

#### `format`

If you'd like to override the [format][ref-dim-format] of a member, you can use the
`format` parameter.

#### `meta`

If you'd like to override the [metadata][ref-dim-meta] of a member, you can use the
`meta` parameter. Note that the `meta` is overridded as a whole.

### `measures`

The `measures` parameter defines measures on the view itself. A view measure is
always *derived*: its `sql` may only reference members that the view already
includes, never columns of a table. Use it for a metric whose parts come from
different cubes. (A cube can own such a metric too, by referencing the other
cube's member; the [average order value recipe][ref-recipe-aov] compares the two
placements.)

Reference the included members as `{CUBE.member}` (or `{view_name.member}`); a
bare `{member}` does not resolve inside a view.

In the example below, `orders` joins `line_items` `one_to_many`:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: orders_overview
      cubes:
        - join_path: orders
          includes:
            - total_amount
        - join_path: orders.line_items
          includes:
            - count

      measures:
        - name: average_line_value
          type: number
          multi_stage: true
          sql: "{CUBE.total_amount} / NULLIF({CUBE.count}, 0)"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`orders_overview`, {
    cubes: [
      {
        join_path: orders,
        includes: [`total_amount`]
      },
      {
        join_path: orders.line_items,
        includes: [`count`]
      }
    ],

    measures: {
      average_line_value: {
        type: `number`,
        multi_stage: true,
        sql: `${CUBE.total_amount} / NULLIF(${CUBE.count}, 0)`
      }
    }
  })
  ```
</CodeGroup>

A view measure that owns its SQL — anything that reads a column rather than a
member — is rejected at compile time with `View 'orders_overview' defines own
member 'orders_overview.average_line_value'`. Move that definition to a cube and
include it instead.

Mark a measure that combines members of **different cubes**
[`multi_stage`][ref-ref-multi-stage], as above. Without it the expression is
evaluated inside a single joined scan, which is only correct when nothing in it
is affected by the join:

* Across cubes joined `one_to_many`, an aggregate on the one side is taken over
  the rows the join multiplied, so the result is silently inflated.
* Across cubes that don't join to each other at all, there is no single join
  tree to evaluate it in and the query fails with `Can't find join path to
  join …`. See [multi-fact views][ref-multi-fact-views].

`multi_stage` defers the expression until each referenced measure has been
aggregated on its own, so neither happens.

### `dimensions`

The `dimensions` parameter defines dimensions on the view itself, under the same
rule as [`measures`](#measures): the `sql` may only combine members the view
already includes.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: orders_overview
      cubes:
        - join_path: orders.products
          includes:
            - category
            - name

      dimensions:
        - name: category_and_name
          type: string
          sql: "{CUBE.category} || ' / ' || {CUBE.name}"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`orders_overview`, {
    cubes: [
      {
        join_path: orders.products,
        includes: [`category`, `name`]
      }
    ],

    dimensions: {
      category_and_name: {
        type: `string`,
        sql: `${CUBE.category} || ' / ' || ${CUBE.name}`
      }
    }
  })
  ```
</CodeGroup>

### `folders`

The `folders` parameter is used to organize members of a view (e.g., dimensions,
hierarchies, measures, etc.) into logical groups. Folders can contain non-overlapping
subsets of members from a view.

<Info>
  Folders display is subject to support in [visualization tools][ref-viz-tools].
  Check [APIs & Integrations][ref-apis-support] for details.
  You can also preview folders in [Playground][ref-playground].
</Info>

Each folder should specify a human-readable name via the `name` parameter and list
included members via the `includes` parameter:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: customers

      cubes:
        - join_path: users
          includes: "*"

        - join_path: users.orders
          prefix: true
          includes:
            - status
            - price
            - count

      folders:
        - name: Basic Details
          includes:
            - created_at
            - location
            - orders_status
            - orders_count

        - name: Sensitive Details
          includes:
            - name
            - gender
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`customers`, {
    cubes: [
      {
        join_path: `users`,
        includes: `*`
      },
      {
        join_path: `users.orders`,
        prefix: true,
        includes: [
          `status`,
          `price`,
          `count`
        ]
      }
    ],

    folders: [
      {
        name: `Basic Details`,
        includes: [
          `created_at`,
          `location`,
          `orders_status`,
          `orders_count`
        ]
      },

      {
        name: `Sensitive Details`,
        includes: [
          `name`,
          `gender`
        ]
      }
    ]
  })
  ```
</CodeGroup>

You can also use the `join_path` parameter within `includes` to add all members from a
specific [join path](#join_path) without listing them individually. You can mix
`join_path` with individual member names in the same folder:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: orders

      cubes:
        - join_path: base_orders
          includes: "*"

        - join_path: base_orders.line_items
          includes: "*"

        - join_path: base_orders.users
          includes:
            - count
            - name: count_distinct
              alias: users_distinct_count

      folders:
        - name: Order Details
          includes:
            - join_path: base_orders

        - name: Line Items & Users
          includes:
            - join_path: base_orders.line_items
            - count
            - users_distinct_count
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`orders`, {
    cubes: [
      {
        join_path: base_orders,
        includes: `*`
      },
      {
        join_path: base_orders.line_items,
        includes: `*`
      },
      {
        join_path: base_orders.users,
        includes: [
          `count`,
          {
            name: `count_distinct`,
            alias: `users_distinct_count`
          }
        ]
      }
    ],

    folders: [
      {
        name: `Order Details`,
        includes: [
          { join_path: base_orders }
        ]
      },
      {
        name: `Line Items & Users`,
        includes: [
          { join_path: base_orders.line_items },
          `count`,
          `users_distinct_count`
        ]
      }
    ]
  })
  ```
</CodeGroup>

#### Nesting

Nested folders are also supported. The `includes` parameter can contain not only
references to view members but also other folders:

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: customers

      cubes:
        - join_path: users
          includes: "*"

        - join_path: users.orders
          prefix: true
          includes:
            - status
            - price
            - count

      folders:
        - name: Customer Information
          includes:
            - name: Personal Details
              includes:
                - name
                - gender

            - name: Location
              includes:
                - address
                - postal_code
                - city

        - name: Order Analytics
          includes:
            - orders_status
            - orders_price
            
            - name: Metrics
              includes:
                - orders_count
                - orders_average_value
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`customers`, {
    cubes: [
      {
        join_path: `users`,
        includes: `*`
      },
      {
        join_path: `users.orders`,
        prefix: true,
        includes: [
          `status`,
          `price`,
          `count`
        ]
      }
    ],

    folders: [
      {
        name: `Customer Information`,
        includes: [
          {
            name: `Personal Details`,
            includes: [
              `name`,
              `gender`
            ]
          },
          {
            name: `Location`,
            includes: [
              `address`,
              `postal_code`,
              `city`
            ]
          }
        ]
      },
      {
        name: `Order Analytics`,
        includes: [
          `orders_status`,
          `orders_price`,
          {
            name: `Metrics`,
            includes: [
              `orders_count`,
              `orders_average_value`
            ]
          }
        ]
      }
    ]
  })
  ```
</CodeGroup>

You can still define nested folders in the data model even if some of your [visualization
tools][ref-viz-tools] do not support them. Check [APIs & Integrations][ref-apis-support]
for details on the nested folders support.

For tools that do not support nested folders, the nested structure will be flattened:
by default, the members of nested folders are merged into folders at the root level.
You can also set the [`CUBEJS_NESTED_FOLDERS_DELIMITER`](/reference/configuration/environment-variables#cubejs_nested_folders_delimiter) environment variable to preserve
nested folders and give them path-like names, e.g., `Customer Information / Personal
Details`.

### `default_filters`

The `default_filters` parameter is used to define default filters on a view.
These filters are applied to every query against the view, narrowing down the
result set to a specific subset of data without requiring data consumers to
specify the filter explicitly.

Default filters are useful for governance scenarios where a view should
always be scoped to a particular value (e.g., a tenant, region, or currency).
To provide sensible defaults that data consumers can edit or remove in the UI,
use [`meta.default_ui_filters`](#default_ui_filters) instead.

<Note>
  `default_filters` are enforced on every query against the view, including
  filter suggestions.
</Note>

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: orders_us

      cubes:
        - join_path: orders
          includes: "*"

      default_filters:
        - member: country
          operator: equals
          values:
            - US
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`orders_us`, {
    cubes: [
      {
        join_path: orders,
        includes: `*`
      }
    ],

    defaultFilters: [
      {
        member: `country`,
        operator: `equals`,
        values: [`US`]
      }
    ]
  });
  ```
</CodeGroup>

Each default filter accepts the following parameters:

#### `member`

The name of the dimension to filter on. The member must be exposed by the view.

#### `operator`

The filter operator. Supported operators match the ones available in the
[REST API query format][ref-rest-query-ops]: `equals`, `notEquals`, `contains`,
`notContains`, `startsWith`, `notStartsWith`, `endsWith`, `notEndsWith`, `in`,
`notIn`, `gt`, `gte`, `lt`, `lte`, `set`, `notSet`, `inDateRange`,
`notInDateRange`, `onTheDate`, `beforeDate`, `beforeOrOnDate`, `afterDate`,
`afterOrOnDate`.

#### `values`

A list of values for the filter operator. Required for all operators except
`set` and `notSet`.

#### `unless`

The `unless` parameter optionally lists members that, when referenced in a
query (either in the projection or in an explicit filter), will cause the
default filter to be released. This allows consumers to override the
default filter by querying or filtering by one of the listed members.

If `unless` is not specified, the filter is always applied.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  views:
    - name: orders_default_us

      cubes:
        - join_path: orders
          includes: "*"

      default_filters:
        - member: country
          operator: equals
          values:
            - US
          unless:
            - country
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view(`orders_default_us`, {
    cubes: [
      {
        join_path: orders,
        includes: `*`
      }
    ],

    defaultFilters: [
      {
        member: `country`,
        operator: `equals`,
        values: [`US`],
        unless: [`country`]
      }
    ]
  });
  ```
</CodeGroup>

In the example above, the `country = US` filter is applied by default. However,
if a query explicitly filters on `country` (e.g., `country = FR`), the default
filter is released and the explicit filter is used instead.

### `access_policy`

The `access_policy` parameter is used to configure [access policies][ref-ref-dap].

[ref-ai-context]: /docs/data-modeling/ai-context

[ref-recipe-control-access-cubes-views]: /docs/data-modeling/access-control

[ref-naming]: /docs/data-modeling/concepts/syntax#naming

[ref-apis]: /reference

[ref-ref-cubes]: /reference/data-modeling/cube

[ref-ref-multi-stage]: /reference/data-modeling/measures#multi_stage

[ref-multi-fact-views]: /docs/data-modeling/multi-fact-views

[ref-recipe-aov]: /recipes/data-modeling/average-order-value#where-to-put-the-measure

[ref-ref-hierarchies]: /reference/data-modeling/hierarchies

[ref-ref-dap]: /reference/data-modeling/data-access-policies

[ref-rest-query-ops]: /reference/core-data-apis/rest-api/query-format#filters-operators

[ref-apis-support]: /reference#data-modeling

[ref-playground]: /docs/explore-analyze/playground#viewing-the-data-model

[ref-viz-tools]: /admin/connect-to-data/visualization-tools

[ref-workbook-filtering]: /docs/explore-analyze/workbooks/querying-data#filtering

[ref-workbook-running]: /docs/explore-analyze/workbooks/querying-data#running-queries

[ref-extension]: /docs/data-modeling/extending-cubes

[ref-dim-name]: /reference/data-modeling/dimensions#name

[ref-dim-public]: /reference/data-modeling/dimensions#public

[ref-dim-title]: /reference/data-modeling/dimensions#title

[ref-dim-description]: /reference/data-modeling/dimensions#description

[ref-dim-format]: /reference/data-modeling/dimensions#format

[ref-dim-meta]: /reference/data-modeling/dimensions#meta


# View groups
Source: https://docs.cube.dev/reference/data-modeling/view-group

View groups organize views into named collections, making it easier for data consumers to navigate and discover related views.

View groups let you organize [views][ref-views] into named collections.
When a data model contains many views, grouping them by domain or purpose
helps downstream consumers — including AI agents, embedded analytics, and
visualization tools — discover the right dataset faster.

View groups are returned as a top-level `viewGroups` array in the
[`/v1/meta`][ref-meta-endpoint] response, alongside the `cubes` array.
Each view that belongs to at least one group also carries a `viewGroups`
string array on its own entry.

A view group should have the following parameter: [`name`](#name).

## Parameters

### `name`

The `name` parameter serves as the identifier of a view group. It must be
unique among all view groups within a deployment and follow the [naming
conventions][ref-naming].

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  view_groups:
    - name: sales
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view_group(`sales`, {})
  ```
</CodeGroup>

### `title`

Use the `title` parameter to set a human-readable display name for the
view group.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  view_groups:
    - name: sales
      title: Sales
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view_group(`sales`, {
    title: `Sales`
  })
  ```
</CodeGroup>

### `description`

This parameter provides a human-readable description of the view group.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  view_groups:
    - name: sales
      title: Sales
      description: Revenue, order, and customer views for the sales team
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view_group(`sales`, {
    title: `Sales`,
    description: `Revenue, order, and customer views for the sales team`
  })
  ```
</CodeGroup>

### `includes`

A list of [views][ref-views] that belong to this group. It can also contain
nested view groups (see [Nesting](#nesting) below).

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  view_groups:
    - name: sales
      title: Sales
      includes:
        - orders_overview
        - revenue
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view_group(`sales`, {
    title: `Sales`,
    includes: [`orders_overview`, `revenue`]
  })
  ```
</CodeGroup>

#### Nesting

View groups can be nested, similar to [nested folders][ref-view-nesting]. The
`includes` parameter can contain not only references to views but also other
view groups, each with its own `title`, `description`, and `includes`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  view_groups:
    - name: sales
      title: Sales
      includes:
        - orders_overview
        - revenue

        - name: enterprise_sales
          title: Enterprise Sales
          description: Views for the enterprise sales team
          includes:
            - enterprise_deals
  ```

  ```javascript title="JavaScript" theme={"dark"}
  view_group(`sales`, {
    title: `Sales`,
    includes: [
      `orders_overview`,
      `revenue`,
      {
        name: `enterprise_sales`,
        title: `Enterprise Sales`,
        description: `Views for the enterprise sales team`,
        includes: [`enterprise_deals`]
      }
    ]
  })
  ```
</CodeGroup>

## Assigning views to groups

To associate a view with a view group, list its name in the
[`includes`](#includes) parameter on the view group.

### Example

The following model defines two view groups. The `sales` group lists
`orders_overview` and `revenue` in its `includes` parameter, while the
`people` group lists `customers_view`.

<CodeGroup>
  ```yaml title="YAML" theme={"dark"}
  cubes:
    - name: order_items
      sql_table: ECOMMERCE.ORDER_ITEMS

      measures:
        - name: count
          type: count

        - name: total_sale_price
          sql: sale_price
          type: sum

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: status
          sql: status
          type: string

        - name: created_at
          sql: created_at
          type: time

    - name: users
      sql_table: ECOMMERCE.USERS

      measures:
        - name: count
          type: count

      dimensions:
        - name: id
          sql: id
          type: number
          primary_key: true

        - name: city
          sql: city
          type: string

  views:
    - name: orders_overview
      cubes:
        - join_path: order_items
          includes:
            - count
            - total_sale_price
            - status
            - created_at

    - name: revenue
      cubes:
        - join_path: order_items
          includes:
            - total_sale_price
            - created_at

    - name: customers_view
      cubes:
        - join_path: users
          includes: "*"

  view_groups:
    - name: sales
      title: Sales
      description: Revenue and order views for the sales team
      includes:
        - orders_overview
        - revenue

    - name: people
      title: People
      description: Customer and user views
      includes:
        - customers_view
  ```

  ```javascript title="JavaScript" theme={"dark"}
  cube(`order_items`, {
    sql_table: `ECOMMERCE.ORDER_ITEMS`,

    measures: {
      count: {
        type: `count`
      },

      total_sale_price: {
        sql: `sale_price`,
        type: `sum`
      }
    },

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      },

      status: {
        sql: `status`,
        type: `string`
      },

      created_at: {
        sql: `created_at`,
        type: `time`
      }
    }
  })

  cube(`users`, {
    sql_table: `ECOMMERCE.USERS`,

    measures: {
      count: {
        type: `count`
      }
    },

    dimensions: {
      id: {
        sql: `id`,
        type: `number`,
        primary_key: true
      },

      city: {
        sql: `city`,
        type: `string`
      }
    }
  })

  view(`orders_overview`, {
    cubes: [
      {
        join_path: order_items,
        includes: [
          `count`,
          `total_sale_price`,
          `status`,
          `created_at`
        ]
      }
    ]
  })

  view(`revenue`, {
    cubes: [
      {
        join_path: order_items,
        includes: [
          `total_sale_price`,
          `created_at`
        ]
      }
    ]
  })

  view(`customers_view`, {
    cubes: [
      {
        join_path: users,
        includes: `*`
      }
    ]
  })

  view_group(`sales`, {
    title: `Sales`,
    description: `Revenue and order views for the sales team`,
    includes: [`orders_overview`, `revenue`]
  })

  view_group(`people`, {
    title: `People`,
    description: `Customer and user views`,
    includes: [`customers_view`]
  })
  ```
</CodeGroup>

With this model, the `/v1/meta` response includes a `viewGroups` array:

```json theme={"dark"}
{
  "viewGroups": [
    {
      "name": "sales",
      "title": "Sales",
      "description": "Revenue and order views for the sales team",
      "includes": ["orders_overview", "revenue"]
    },
    {
      "name": "people",
      "title": "People",
      "description": "Customer and user views",
      "includes": ["customers_view"]
    }
  ]
}
```

Each view group carries an `includes` array that preserves the authoring order
and contains the group's views as well as any nested view groups.

[ref-views]: /docs/data-modeling/views

[ref-view-nesting]: /reference/data-modeling/view#nesting

[ref-naming]: /docs/data-modeling/concepts/syntax#naming

[ref-meta-endpoint]: /reference/core-data-apis/rest-api/reference


# Chat API
Source: https://docs.cube.dev/reference/embed-apis/chat-api

The Chat API enables real-time conversations with AI agents for analytics and data exploration.

<Info>
  The Chat API is available on [Premium and Enterprise plans](https://cube.dev/pricing).
</Info>

## Endpoint

The endpoint can be addressed either by agent or by deployment.

Addressed by agent, it talks to that specific agent:

```text theme={"dark"}
https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state
```

Copy the exact URL from your agent settings (**Chat API URL** field) in **Admin → Agents**.

Addressed by deployment, it talks to the deployment's Auto agent — the agent
used when no specific one is selected:

```text theme={"dark"}
https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/deployments/{deploymentId}/chat/stream-chat-state
```

Copy the exact URL from the deployment's **Settings → API credentials → Chat API**
tab, also reachable from the **Chat** entry on the deployment's **Status** page.

The two forms differ in which authentication they accept:

| URL form                        | [API key](#api-key-authentication) | [Cube token](#cube-token-authentication) |
| ------------------------------- | :--------------------------------: | :--------------------------------------: |
| `/agents/{agentId}/…`           |                  ✓                 |                     ✓                    |
| `/deployments/{deploymentId}/…` |                  —                 |                     ✓                    |

The deployment form is served **only** through the Cube token exchange, which is
what resolves the Auto agent — an API key carries no agent, so a request without
`{agentId}` in the path is rejected with `403 agentId is required for Api-Key
authentication`. Because [Cube token authentication](#cube-token-authentication)
is disabled by default, the deployment form works only once it is enabled in
**Settings** → **Configuration** → **Use Cube authentication for Chat and
embedding APIs**. Request body and streaming response are identical for both.

## Overview

The Chat API enables real-time streaming conversations with Cube's AI agents. This endpoint allows applications to integrate AI-powered analytics conversations directly into their user interfaces.

## Authentication

<Warning>
  Accounts are limited to 10,000 non-ephemeral external users. To increase this limit, please contact support.
</Warning>

<Info>
  All users created using this API are ephemeral by default and will be removed after `sessionSettings.ephemeralTtlSeconds` (1 week by default). If users need to be persisted, pass `isEphemeral: false` in `sessionSettings`. Ephemeral users are guaranteed to not live longer than `sessionSettings.ephemeralTtlSeconds`.
</Info>

The Chat API supports two authentication methods:

* [API key authentication](#api-key-authentication) — pass a Cube [API key][ref-api-keys] in the `Authorization` header.
* [Cube token authentication](#cube-token-authentication) — pass your deployment's own [Cube token][ref-jwt-auth] (JWT) in the `X-Cube-Auth-Token` header.

### API key authentication

Pass your [API key][ref-api-keys] directly to the Chat API endpoint. The session will be created automatically based on the `externalId` provided:

```javascript theme={"dark"}
// Copy the Chat API URL from your agent settings (Admin → Agents → Chat API URL field)
const CHAT_API_URL = 'YOUR_CHAT_API_URL';

const response = await fetch(
  CHAT_API_URL,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Api-Key ${API_KEY}',
    },
    body: JSON.stringify({
      input: 'What were the total sales last month?',
      sessionSettings: {
        externalId: 'user@example.com',
        email: 'user@example.com', // optional
        userAttributes: [ // optional
          {
            name: 'city',
            value: 'San Francisco'
          }
        ]
      }
    }),
  }
);

// Handle streaming response
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}
```

### Cube token authentication

<Note>
  Cube token authentication for the Chat API is disabled by default. You can
  enable it in your deployment settings: **Settings** → **Configuration** →
  **Use Cube authentication for Chat and embedding APIs**.
</Note>

Instead of an API key, the Chat API can authenticate requests with your
deployment's own [Cube authentication][ref-jwt-auth] — the same JSON Web
Tokens (JWTs) your application already uses with the Core Data APIs. Cube
validates the token using the deployment's existing authentication
configuration: the API secret, JWKS, or a custom
[`check_auth`][ref-config-check-auth] implementation.

This is useful for [headless embedding][ref-headless-embedding]: your
application issues a single kind of token, and the same token works for both
data queries and AI-powered conversations.

Pass the token in the `X-Cube-Auth-Token` header instead of the
`Authorization` header:

```javascript theme={"dark"}
// Copy the Chat API URL from your agent settings (Admin → Agents → Chat API URL field)
const CHAT_API_URL = 'YOUR_CHAT_API_URL';

const response = await fetch(
  CHAT_API_URL,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Cube-Auth-Token': CUBE_TOKEN,
    },
    body: JSON.stringify({
      input: 'What were the total sales last month?'
    }),
  }
);
```

<Warning>
  If the request also carries an `Authorization` header, it takes precedence
  and the `X-Cube-Auth-Token` header is ignored. Send exactly one of the two.
</Warning>

To be accepted by the Chat API, the token must be valid for the deployment and
include the following claims in its payload:

* `externalId` (required) — unique identifier for the external user.
  Normalized to lowercase, so ids that differ only in casing map to the same
  user. When `externalId` is not present, the standard JWT `sub` claim is
  used instead.
* `scope` (required) — an array of scopes that must include `chat`.
* `email` (optional) — email address to store on the provisioned external
  user.

```javascript theme={"dark"}
const jwt = require("jsonwebtoken")

const cubeToken = jwt.sign(
  {
    externalId: "user@example.com",
    scope: ["chat"],
    // Security context claims, e.g.:
    tenant_id: "acme"
  },
  process.env.CUBEJS_API_SECRET,
  { expiresIn: "1h" }
)
```

<Info>
  The `chat` scope is asserted on the token's *resolved security context*.
  With the default JWT authentication the security context is simply the
  token payload, so including `scope: ["chat"]` in the token is enough. If
  your deployment uses a custom [`check_auth`][ref-config-check-auth]
  implementation that rewrites the security context, make sure the resolved
  security context carries `scope: ["chat"]` for tokens that should be
  allowed to use the Chat API.
</Info>

When Cube token authentication is used:

* The external user is identified by the `externalId` (or `sub`) claim, and
  their security context is resolved from the token claims — so you don't
  need to pass identity fields in `sessionSettings`; users are provisioned
  automatically from the token.
* The agent queries the deployment with the same token you sent, so
  row-level security and any other security-context-based access controls
  apply to the conversation exactly as they apply to your direct API queries.
* Tokens that are invalid for the deployment, miss the `externalId` (or
  `sub`) claim, or don't carry the `chat` scope are rejected.

**Request Body Fields:**

| Field                             | Type      | Required | Description                                                                                                                                                                                                                                                         |
| --------------------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `input`                           | string    | No       | The user's message or question. If omitted returns current state of thread with provided chatId.                                                                                                                                                                    |
| `chatId`                          | string    | No       | Chat thread ID. If omitted, a new thread is created automatically. If provided, it should match the previously returned `chatId` from a message with id `__cutoff__` sent as the `state.chatId` field.                                                              |
| `messageId`                       | string    | No       | Client-provided identifier for the user message. Must match the format `<timestamp>-message` (a 13+ digit Unix timestamp in milliseconds followed by `-message`), e.g. `1717500000000-message`. Used to make requests idempotent — see [Idempotency](#idempotency). |
| `sessionSettings.externalId`      | string    | No       | Unique identifier for the external user, lowercase and without spaces. Either `externalId` or `internalId` should be provided.                                                                                                                                      |
| `sessionSettings.internalId`      | string    | No       | Email address of an internal Cube Cloud user. Either `externalId` or `internalId` should be provided.                                                                                                                                                               |
| `sessionSettings.email`           | string    | No       | User's email address                                                                                                                                                                                                                                                |
| `sessionSettings.userAttributes`  | array     | No       | Array of `{name, value}` pairs for row-level security. Not allowed with `internalId`.                                                                                                                                                                               |
| `sessionSettings.groups`          | string\[] | No       | Array of group names the user belongs to. Not allowed with `internalId`.                                                                                                                                                                                            |
| `sessionSettings.securityContext` | object    | No       | Custom security context object passed to Cube queries. Not allowed with `internalId`.                                                                                                                                                                               |
| `activeBranchName`                | string    | No       | Name of a development branch to use for the chat session. When provided, queries run against the specified branch instead of the main branch.                                                                                                                       |
| `isDefaultBranch`                 | boolean   | No       | Whether the specified `activeBranchName` is the default branch. Defaults to `true` when `activeBranchName` is not set, and `false` when it is. Set to `true` if passing the main/production branch name.                                                            |

<Info>
  When using `internalId`, the user must already exist in Cube Cloud. You cannot specify `roles`, `groups`, `userAttributes`, or `securityContext` with `internalId` — the internal user's existing permissions are used instead.
</Info>

### User Attributes

User attributes allow you to pass contextual information about the user to the AI agent. This enables personalized responses and automatic data filtering based on user permissions through row-level security policies.

<Info>
  User attributes must first be configured in your Cube admin panel before they can be used. See the [User Attributes documentation](/admin/users-and-permissions/user-attributes) for setup instructions.
</Info>

**Supported Fields:**

* `externalId` (optional): Unique identifier for the external user. Either `externalId` or `internalId` should be provided.
* `internalId` (optional): Email address of an internal Cube Cloud user. The user must already exist. Either `externalId` or `internalId` should be provided.
* `email` (optional): User's email address
* `userAttributes` (optional): Array of key-value pairs containing user metadata. Only available with `externalId`.

**User Attribute Structure:**

```javascript theme={"dark"}
{
  name: 'string',    // Must match an attribute name configured in admin panel
  value: 'string'    // Attribute value (e.g., 'San Francisco', 'Engineering')
}
```

**How User Attributes Work:**

1. **Row-Level Security**: Automatically filter data based on user attributes through access policies
2. **Personalized Responses**: AI agent can tailor responses based on user context
3. **Access Control**: Restrict data access to only what the user should see

**Example Use Cases:**

* Filter sales data by user's assigned territory
* Show only customers from user's city
* Limit financial data based on user's department
* Personalize dashboards by user role

The attributes passed during session generation become available as `userAttributes.{attributeName}` for use in access policies.

## Endpoint Reference

**POST**

```text theme={"dark"}
https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state
https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/deployments/{deploymentId}/chat/stream-chat-state
```

<Info>
  Copy the complete Chat API URL from your agent settings (**Chat API URL** field)
  in **Admin → Agents**, or — for the deployment's Auto agent — from
  **Settings → API credentials → Chat API**.
</Info>

### Path Parameters

* **`cloudRegion`** (string): The cloud region identifier (e.g., "gcp-us-central1")
* **`accountName`** (string, required): The account identifier (e.g., "acme"). It is in your account URL, e.g. [https://acme.cubecloud.dev](https://acme.cubecloud.dev)
* **`agentId`** (string, required for the agent form): The AI agent identifier (e.g., "1"). You can find it in **Admin → Agents → Click on Agent row in the table**.
* **`deploymentId`** (string, required for the deployment form): The deployment identifier (e.g., "9"). It is in the deployment URL, e.g. [https://acme.cubecloud.dev/d/9](https://acme.cubecloud.dev/d/9). Resolves to the deployment's Auto agent.

### Request Body

* **`input`** (string): User message or query to send to the AI agent, e.g. "What is our revenue last month?". If omitted, returns current state of thread with provided `chatId`.
* **`chatId`** (string): Chat thread ID. If omitted, a new thread is created automatically. If provided, it should match the previously returned `chatId` from a message with id `__cutoff__`.
* **`messageId`** (string): Client-provided identifier for the user message. Must match the format `<timestamp>-message` (a 13+ digit Unix timestamp in milliseconds followed by `-message`), e.g. `1717500000000-message`. Used to make requests idempotent — see [Idempotency](#idempotency).
* **`sessionSettings`** (object, required for API key authentication; ignored
  with Cube token authentication, where identity comes from the token claims):
  Session configuration for the user
  * **`externalId`** (string): Unique identifier for the external user. Either `externalId` or `internalId` should be provided.
  * **`internalId`** (string): Email address of an internal Cube Cloud user. The user must already exist. Either `externalId` or `internalId` should be provided.
  * **`email`** (string): User's email address
  * **`userAttributes`** (array): Array of `{name, value}` pairs for row-level security. Not allowed with `internalId`.
  * **`groups`** (string\[]): Array of group names for user. Not allowed with `internalId`.
  * **`securityContext`** (object): Custom security context object passed to Cube queries. Not allowed with `internalId`.
* **`activeBranchName`** (string): Name of a development branch to use for the chat session. When provided, queries run against the specified branch instead of the main branch.
* **`isDefaultBranch`** (boolean): Whether the specified `activeBranchName` is the default branch. Defaults to `true` when `activeBranchName` is not set, and `false` when it is. Set to `true` if passing the main/production branch name.

## Idempotency

You can pass a client-provided `messageId` in the request body to make Chat API
requests idempotent. The value must match the format `<timestamp>-message`,
where `<timestamp>` is a Unix timestamp in milliseconds with 13 or more digits,
e.g. `1717500000000-message`.

If a request with the same `messageId` arrives while a stream for that message
is still active on the thread, the API resubscribes the new request to the
existing stream instead of starting a new one. This is useful for retrying
after a dropped connection: the client can replay the same request and resume
receiving the stream from the current point without producing duplicate
assistant messages.

Without a matching `messageId`, sending a new message to a thread that is
already streaming returns a `Streaming for thread is in progress` error.

## Response Format

<Info>
  The API returns streaming JSON responses. Each line contains a separate JSON object representing a chat message or state update.
</Info>

### Response Fields

* **`id`** (string): Unique message identifier
* **`role`** (string): Message sender: `"user"` or `"assistant"`
* **`content`** (string): Message content (streamed incrementally for assistant messages)
* **`thinking`** (string): Agent's internal reasoning process (visible in development mode)
* **`toolCall`** (object): Information about tool calls made by the agent during processing
  * **`name`** (string): Name of the tool being called
  * **`input`** (string): JSON string containing the input parameters for the tool
  * **`result`** (string): JSON string containing the tool's response (only present when tool call is complete)
* **`graphPath`** (string\[]): Identifies which node of the agent graph produced this message. For example, `["cube_data_analyst_agent"]` for the main agent node or `["cube_data_analyst_agent", "tools"]` for tool calls. Messages with `graphPath[0] === "final"` represent the final consolidated answer.
* **`isDelta`** (boolean): Whether this is an incremental content update
* **`isInProcess`** (boolean): Whether the message is still being generated
* **`sort`** (number): Message ordering sequence number
* **`state`** (object): Current streaming state information

### Response Examples

The API returns a series of JSON objects, each on a separate line. Here's what a typical conversation looks like:

**Initial State Message:**

```json theme={"dark"}
{
  "id": "__cutoff__",
  "role": "assistant",
  "state": {
    "isStreaming": false
  },
  "sort": 0
}
```

**User Message Echo:**

```json theme={"dark"}
{
  "id": "1732512345678-message",
  "role": "user",
  "content": "Show me revenue trends for the last 6 months",
  "isDelta": false,
  "sort": 1
}
```

**Assistant Response Start:**

```json theme={"dark"}
{
  "id": "cdfe1a84-08d7-40b9-8b1c-e7e3a698647e",
  "role": "assistant",
  "content": "",
  "thinking": "",
  "graphPath": ["cube_data_analyst_agent"],
  "isStructuredResponse": false,
  "isInProcess": true,
  "isDelta": true,
  "sort": 2
}
```

**Thinking Process:**

```json theme={"dark"}
{
  "id": "cdfe1a84-08d7-40b9-8b1c-e7e3a698647e",
  "role": "assistant",
  "content": "",
  "thinking": "The user wants to see revenue trends for the last 6 months. I need to query the revenue data and create a visualization.",
  "graphPath": ["cube_data_analyst_agent"],
  "isStructuredResponse": false,
  "isInProcess": true,
  "isDelta": true,
  "sort": 3
}
```

**Content Streaming:**

```json theme={"dark"}
{
  "id": "cdfe1a84-08d7-40b9-8b1c-e7e3a698647e",
  "role": "assistant",
  "content": "I'll help you analyze revenue trends for the last 6 months. Let me query the data and create a visualization.",
  "thinking": "",
  "graphPath": ["cube_data_analyst_agent"],
  "isStructuredResponse": false,
  "isInProcess": true,
  "isDelta": true,
  "sort": 4
}
```

**Tool Call Initiated:**

```json theme={"dark"}
{
  "id": "4849adb2-b55d-4afe-946b-fc117bcadaf5",
  "role": "assistant",
  "toolCall": {
    "name": "cubeMeta",
    "input": "{\"searchQuery\":\"revenue trends\"}"
  },
  "isInProcess": true,
  "graphPath": ["cube_data_analyst_agent", "tools"],
  "isStructuredResponse": false,
  "isDelta": false,
  "sort": 5
}
```

**Tool Call Result:**

```json theme={"dark"}
{
  "id": "4849adb2-b55d-4afe-946b-fc117bcadaf5",
  "role": "assistant",
  "toolCall": {
    "name": "cubeMeta",
    "input": "{\"searchQuery\":\"revenue trends\"}",
    "result": "{\"cubes\":[{\"name\":\"Revenue\",\"measures\":[\"Revenue.totalRevenue\",\"Revenue.monthlyGrowth\"]}]}"
  },
  "isInProcess": false,
  "graphPath": ["cube_data_analyst_agent", "tools"],
  "isStructuredResponse": false,
  "isDelta": false,
  "sort": 6
}
```

**SQL Query Tool Call:**

```json theme={"dark"}
{
  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
  "role": "assistant",
  "toolCall": {
    "name": "cubeSqlApi",
    "input": "{\"query\":\"SELECT Revenue.totalRevenue, Revenue.month FROM Revenue WHERE Revenue.dateRange BETWEEN '2024-01-01' AND '2024-06-30' ORDER BY Revenue.month\"}"
  },
  "isInProcess": true,
  "graphPath": ["cube_data_analyst_agent", "tools"],
  "isStructuredResponse": false,
  "isDelta": false,
  "sort": 7
}
```

**SQL Query Result:**

```json theme={"dark"}
{
  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
  "role": "assistant",
  "toolCall": {
    "name": "cubeSqlApi",
    "input": "{\"query\":\"SELECT Revenue.totalRevenue, Revenue.month FROM Revenue WHERE Revenue.dateRange BETWEEN '2024-01-01' AND '2024-06-30' ORDER BY Revenue.month\"}",
    "result": "{\"data\":[{\"Revenue.totalRevenue\":1800000,\"Revenue.month\":\"2024-01\"},{\"Revenue.totalRevenue\":1950000,\"Revenue.month\":\"2024-02\"},{\"Revenue.totalRevenue\":2300000,\"Revenue.month\":\"2024-03\"},{\"Revenue.totalRevenue\":2100000,\"Revenue.month\":\"2024-04\"},{\"Revenue.totalRevenue\":2250000,\"Revenue.month\":\"2024-05\"},{\"Revenue.totalRevenue\":2400000,\"Revenue.month\":\"2024-06\"}],\"annotation\":{\"measures\":{\"Revenue.totalRevenue\":{\"title\":\"Total Revenue\",\"type\":\"number\"}},\"dimensions\":{\"Revenue.month\":{\"title\":\"Month\",\"type\":\"time\"}}}}"
  },
  "isInProcess": false,
  "graphPath": ["cube_data_analyst_agent", "tools"],
  "isStructuredResponse": false,
  "isDelta": false,
  "sort": 8
}
```

**Final Complete Message:**

```json theme={"dark"}
{
  "id": "cdfe1a84-08d7-40b9-8b1c-e7e3a698647e",
  "role": "assistant",
  "content": "I'll help you analyze revenue trends for the last 6 months. Let me query the data and create a visualization.\n\nBased on your revenue data, here are the key trends:\n\n📈 **Overall Growth**: 15% increase over the 6-month period\n💰 **Peak Month**: March 2024 with $2.3M revenue\n📊 **Steady Growth**: Consistent month-over-month growth of 2-3%\n\nWould you like me to break this down by product category or region?",
  "thinking": "",
  "graphPath": ["cube_data_analyst_agent"],
  "isStructuredResponse": false,
  "isInProcess": false,
  "isDelta": false,
  "sort": 9
}
```

**Final State Update:**

```json theme={"dark"}
{
  "id": "__state__",
  "role": "assistant",
  "state": {
    "messages": [{
      "lc": 1,
      "type": "constructor",
      "id": ["langchain_core", "messages", "HumanMessage"],
      "kwargs": {
        "content": "Show me revenue trends for the last 6 months"
      }
    }]
  },
  "isDelta": false,
  "sort": 10
}
```

### Getting the Final Assistant Message

When consuming the streamed NDJSON response, you may want to extract only
the final answer that the agent produced — for example, to display it in a
chat UI or to store it for later reference.

The agent graph emits many intermediate messages (thinking steps, tool calls,
incremental deltas, state updates, etc.). To isolate the **final answer**,
filter the streamed messages using these two conditions:

1. `role === "assistant"` — only assistant messages.
2. `graphPath[0] === "final"` **and** `graphPath.length <= 2` — messages
   produced by the "final" node of the agent graph.

The **last** message that satisfies both conditions is the final answer.

```javascript theme={"dark"}
// Collect all streamed messages first
const messages = [];

for await (const line of readLines(response.body)) {
  if (line) {
    messages.push(JSON.parse(line));
  }
}

// Filter for final-answer messages
const finalMessages = messages.filter(
  (msg) =>
    msg.role === "assistant" &&
    Array.isArray(msg.graphPath) &&
    msg.graphPath[0] === "final" &&
    msg.graphPath.length <= 2
);

// The last one is the definitive final answer
const finalAnswer = finalMessages[finalMessages.length - 1];
console.log("Final answer:", finalAnswer?.content);
```

<Info>
  The `graphPath` property is an array of strings that traces the path through
  the agent's internal execution graph. Intermediate nodes (e.g.,
  `["cube_data_analyst_agent"]` or `["cube_data_analyst_agent", "tools"]`)
  produce working messages, while the `"final"` node emits the consolidated
  response that should be presented to the user.
</Info>

### Tool Calls

When the AI agent performs actions like querying data or searching metadata, tool calls are included in the response stream. These provide transparency into the agent's reasoning and data retrieval process.

<Info>
  All tool results are returned as **JSON strings** within the `toolCall.result` field, not as parsed JSON objects. You must parse these strings to access the structured data.
</Info>

**Key Points:**

* `toolCall.input` - JSON string containing tool parameters
* `toolCall.result` - JSON string containing tool response (only present when `isInProcess: false`)
* Both input and result contain escaped JSON that requires parsing
* Results may contain nested JSON structures, especially for complex data queries
* Error responses are also JSON strings with consistent error formatting

**Parsing Example:**

```javascript theme={"dark"}
// Parse the tool result JSON string
const toolResult = JSON.parse(message.toolCall.result);

if (toolResult.error) {
  console.error('Tool error:', toolResult.error);
} else {
  // Handle successful result based on tool type
  if (message.toolCall.name === 'cubeSqlApi') {
    const data = toolResult.data;
    const annotation = toolResult.annotation;
    // Process query results...
  }
}
```

#### cubeMeta

Searches cube metadata and schema information

The `cubeMeta` tool returns cube schema information as a JSON string. When successful, the result contains:

```json theme={"dark"}
{
  "toolCall": {
    "name": "cubeMeta",
    "input": "...",
    "result": "..."
  }
}
```

**Input Structure:**

```json theme={"dark"}
{
  "searchQuery": "sales pipeline revenue"
}
```

**Input Fields:**

* `searchQuery` (string): Search query for data model

**Result Structure:**

```json theme={"dark"}
{
  "cubes": [
    {
      "name": "sales_pipeline_view",
      "type": "view",
      "title": "Sales Pipeline View",
      "members": [
        {
          "name": "sales_pipeline_view.company_name",
          "title": "Company Name",
          "description": "Name of the company/prospect",
          "type": "string"
        },
        {
          "name": "sales_pipeline_view.deal_amount",
          "title": "Deal Amount",
          "description": "Total deal value",
          "type": "number"
        },
        {
          "name": "sales_pipeline_view.stage",
          "title": "Sales Stage",
          "description": "Current stage of the deal (Lead, Demo, Negotiation, Won, Lost, etc.)",
          "type": "string"
        },
        {
          "name": "sales_pipeline_view.count",
          "title": "Deal Count",
          "description": "Total number of deals",
          "type": "number",
          "aggType": "count"
        }
      ]
    },
    {
      "name": "revenue_view",
      "type": "view",
      "title": "Revenue View",
      "members": [
        {
          "name": "revenue_view.total_amount",
          "title": "Total Revenue",
          "description": "Sum of all revenue",
          "type": "number",
          "aggType": "sum"
        },
        {
          "name": "revenue_view.month",
          "title": "Revenue Month",
          "description": "Month of revenue recognition",
          "type": "time"
        },
        {
          "name": "revenue_view.is_recurring",
          "title": "Is Recurring Revenue",
          "description": "Whether this is recurring or one-time revenue",
          "type": "boolean"
        }
      ]
    }
  ],
  "searchQuery": "sales pipeline revenue"
}
```

**Result Fields:**

* `cubes` (array): Available cube/view definitions with members
* `searchQuery` (string): The original search query used

#### cubeSqlApi

Executes SQL queries against cube data

The `cubeSqlApi` tool executes SQL queries and returns data with metadata. The input typically includes additional context fields:

```json theme={"dark"}
{
  "toolCall": {
    "name": "cubeSqlApi",
    "input": "...",
    "result": "..."
  }
}
```

**Input Structure:**

```json theme={"dark"}
{
  "sqlQuery": "SELECT deals_view.company_name, deals_view.deal_name FROM deals_view WHERE deals_view.stage = 'Negotiation' LIMIT 10",
  "queryTitle": "Sales Pipeline Overview",
  "description": "Retrieving deal information from the deals view for current negotiations",
  "userRequest": "show me current deals in negotiation",
  "memoryId": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
  "vegaSpec": "vega lite v5 visualization spec as JSON string"
}
```

**Input Fields:**

* `sqlQuery` (string): The SQL query to execute
* `queryTitle` (string): Human-readable title for the query
* `description` (string): Detailed description of what the query does
* `userRequest` (string): Original user request that triggered this query
* `memoryId` (string): Reference to previous analysis or context
* `vegaSpec` (string): Vega-Lite v5 visualization specification as JSON string (when visualization is generated)

**Result Structure:**

```json theme={"dark"}
{
  "sqlQuery": "SELECT deals_view.company_name, deals_view.name AS deal_name...",
  "queryTitle": "Current Deals Overview",
  "description": "Retrieving deals showing company names, deal names, stages...",
  "userRequest": "show me deals",
  "schema": [
    {
      "name": "company_name",
      "column_type": "String"
    },
    {
      "name": "deal_name", 
      "column_type": "String"
    },
    {
      "name": "stage",
      "column_type": "String"
    },
    {
      "name": "tenant_name",
      "column_type": "String"
    },
    {
      "name": "activity_score",
      "column_type": "Double"
    },
    {
      "name": "deal_count",
      "column_type": "Int64"
    }
  ],
  "data": [
    ["Acme Corp", "Enterprise Solution", "Negotiation", "acme-workspace", "245", "1"],
    ["Beta Industries", "Analytics Platform", "Testing", "beta-analytics", "189", "1"],
    ["Gamma LLC", "Data Pipeline", "Demo", "gamma-data", "156", "1"]
  ],
  "totalRows": 25,
  "uuid": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
  "vegaSpec": "vega lite v5 visualization spec as JSON string"
}
```

**Result Fields:**

* `sqlQuery` (string): The executed SQL query
* `queryTitle` (string): Human-readable title for the query
* `description` (string): Detailed description of what the query does
* `userRequest` (string): Original user request that triggered this query
* `schema` (array): Column definitions with `name` and `column_type` for each field
* `data` (array): Query result rows as arrays of values
* `totalRows` (number): Total number of rows returned
* `uuid` (string): Unique identifier for this query result
* `vegaSpec` (string): Vega-Lite v5 visualization specification as JSON string (when visualization is generated)

#### Loading all Results

<Warning>
  Query results in cubeSqlApi `toolCall.result.data` are limited to **100 rows** by default. Use `totalRows` to check if more data is available.
</Warning>

If you need to load all the data, you need to use `sqlQuery` from the results to make a call to the Cube API.

#### Displaying charts

The `cubeSqlApi` tool call returns `vegaSpec` that can be used to display data.

Note that it doesn't contain data. You need to use the data from `toolCall.result.data`.

#### Styling charts

When rendering Vega charts, you can apply custom styling to match the look and feel of your application.
This includes adjusting colors, fonts, and other visual elements.

Here's a configuration example that mimics Cube's default styling:

```json theme={"dark"}
{
  // Your Vega configuration

  "config": {
    "background": "#ffffff",
    "padding": 16,
    "view": {
      "stroke": "transparent"
    },
    "axis": {
      "domainColor": "#E0E0E0",
      "gridColor": "#F5F5F5",
      "grid": true,
      "labelFont": "Inter, sans-serif",
      "labelFontSize": 12,
      "labelColor": "#43436B",
      "titleFont": "Inter, sans-serif",
      "titleFontSize": 12,
      "titleColor": "#43436B",
      "titlePadding": 8
    },
    "numberFormat": "s",
    "timeFormat": "%Y-%m",
    "format": {
      "number": {
        "format": "s",
        "formatType": "number"
      },
      "time": {
        "format": "%Y-%m",
        "formatType": "time"
      }
    },
    "legend": {
      "labelFont": "Inter, sans-serif",
      "titleFont": "Inter, sans-serif",
      "labelColor": "#43436B",
      "titleColor": "#43436B",
      "labelFontSize": 12,
      "titleFontSize": 12,
      "titlePadding": 8,
      "padding": 8
    },
    "line": {
      "strokeWidth": 3,
      "strokeCap": "round",
      "point": true
    },
    "text": {
      "color": "#43436B"
    },
    "point": {
      "filled": true,
      "size": 60
    },
    "range": {
      "category": [
        "#4E79A7",
        "#F28E2B",
        "#E15759",
        "#76B7B2",
        "#59A14F",
        "#EDC948",
        "#B07AA1",
        "#FF9DA7",
        "#9C755F",
        "#BAB0AC"
      ],
      "heatmap": [
        "#eff6ff",
        "#1e40af"
      ]
    },
    "scale": {
      "band": {
        "padding": 0.1,
        "round": true
      },
      "linear": {
        "nice": true,
        "zero": true
      },
      "ordinal": {
        "type": "band",
        "padding": 0.1
      },
      "time": {
        "type": "utc",
        "nice": true
      },
      "log": {
        "base": 10,
        "domain": {
          "data": "table",
          "field": "x"
        },
        "range": {
          "data": "table",
          "field": "y"
        }
      },
      "range": [
        "#4E79A7",
        "#F28E2B"
      ]
    }
  }
}
```

#### Error Handling

When a tool encounters an error, the result field contains structured error information as a JSON string:

**Standard Error Format:**

When an error occurs, the `result` property of the toolCall will contain an `error` property.

```json theme={"dark"}
{
  "toolCall": {
    "name": "cubeMeta",
    "input": "{\"searchQuery\":\"opportunities deals\"}",
    "result": "{\n  \"error\": \"Error: BadRequestError: Bad branch\"\n}"
  },
  "isInProcess": false
}
```

## Abort Endpoint

The Abort endpoint stops an in-progress chat stream. This is useful when the
user cancels a request or navigates away while the agent is still generating a
response.

### Endpoint

**POST**

```text theme={"dark"}
https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/abort
https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/deployments/{deploymentId}/chat/abort
```

The abort URL is derived from the Chat API URL by replacing `/stream-chat-state`
with `/abort` — for whichever form, agent or deployment, you used to start the
stream.

### Authentication

Supports the same authentication methods as the Chat API: an
[API key](#api-key-authentication) or, when enabled for your deployment, a
[Cube token](#cube-token-authentication). As with `stream-chat-state`, the
`/deployments/{deploymentId}/…` form accepts only a Cube token.

### Request Body

* **`chatId`** (string, required): The chat thread ID to abort. This must match
  the `chatId` of an active or recently completed chat session.
* **`sessionSettings`** (object): Same session settings as `stream-chat-state`
  to authenticate the request.
  * **`externalId`** (string): Unique identifier for the external user.

### Response

* **`204 No Content`**: Chat streaming was aborted successfully.
* **`403 Forbidden`**: The authenticated user does not own the specified chat
  thread.
* **`404 Not Found`**: The specified `chatId` does not exist.

<Info>
  A successful cancellation is indicated solely by the `204 No Content` status —
  the response has no body. The aborted `stream-chat-state` request itself does
  not fail with an HTTP error: the streaming response already returned `200 OK`
  when the stream opened, so treat the abort endpoint's `204` as the
  confirmation that the stream was aborted.
</Info>

### Code Examples

<CodeGroup>
  ```python title="Python" Python theme={"dark"}
  import requests

  CHAT_API_URL = "YOUR_CHAT_API_URL"
  ABORT_URL = CHAT_API_URL.replace("/stream-chat-state", "/abort")
  API_KEY = "YOUR_API_KEY"

  response = requests.post(
      ABORT_URL,
      headers={
          "Content-Type": "application/json",
          "Authorization": f"Api-Key {API_KEY}"
      },
      json={
          "chatId": "CHAT_ID_TO_ABORT",
          "sessionSettings": {
              "externalId": "user@example.com"
          }
      }
  )

  if response.status_code == 204:
      print("Chat streaming aborted successfully")
  ```

  ```bash title="Bash" cURL theme={"dark"}
  # Derive the abort URL from your Chat API URL by replacing /stream-chat-state with /abort
  ABORT_URL="${CHAT_API_URL/stream-chat-state/abort}"

  curl -X POST "$ABORT_URL" \
    -H "Content-Type: application/json" \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -d '{
      "chatId": "CHAT_ID_TO_ABORT",
      "sessionSettings": {
        "externalId": "user@example.com"
      }
    }'
  ```

  ```javascript title="JavaScript" JavaScript theme={"dark"}
  const CHAT_API_URL = 'YOUR_CHAT_API_URL';
  const ABORT_URL = CHAT_API_URL.replace(/\/stream-chat-state$/, '/abort');
  const API_KEY = 'YOUR_API_KEY';

  const response = await fetch(ABORT_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Api-Key ${API_KEY}`
    },
    body: JSON.stringify({
      chatId: 'CHAT_ID_TO_ABORT',
      sessionSettings: {
        externalId: 'user@example.com'
      }
    })
  });

  if (response.status === 204) {
    console.log('Chat streaming aborted successfully');
  }
  ```
</CodeGroup>

## Code Examples

<CodeGroup>
  ```python title="Python" Python theme={"dark"}
  import requests
  import json

  # Copy the Chat API URL from your agent settings (Admin → Agents → Chat API URL field)
  CHAT_API_URL = "YOUR_CHAT_API_URL"
  API_KEY = "YOUR_API_KEY"

  headers = {
      "Content-Type": "application/json",
      "Authorization": f"Api-Key {API_KEY}"
  }

  data = {
      "input": "What are our top performing products?",
      "sessionSettings": {
          "externalId": "user@example.com",
          "email": "user@example.com",  # optional
          "userAttributes": [  # optional
              {
                  "name": "city",
                  "value": "San Francisco"
              }
          ]
      }
  }

  response = requests.post(CHAT_API_URL, headers=headers, json=data, stream=True)

  for line in response.iter_lines():
      if line:
          message = json.loads(line.decode('utf-8'))
          print("Received:", message)
  ```

  ```bash title="Bash" cURL theme={"dark"}
  # Copy YOUR_CHAT_API_URL from your agent settings (Admin → Agents → Chat API URL field)
  curl -X POST "YOUR_CHAT_API_URL" \
    -H "Content-Type: application/json" \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -d '{
      "input": "Show me revenue trends for the last 6 months",
      "sessionSettings": {
        "externalId": "user@example.com"
      }
    }'
  ```

  ```javascript title="JavaScript" JavaScript theme={"dark"}
  // Copy the Chat API URL from your agent settings (Admin → Agents → Chat API URL field)
  const CHAT_API_URL = 'YOUR_CHAT_API_URL';
  const API_KEY = 'YOUR_API_KEY';

  const response = await fetch(
    CHAT_API_URL,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Api-Key ${API_KEY}`
      },
      body: JSON.stringify({
        input: 'Hello, how can you help me analyze our data?',
        sessionSettings: {
          externalId: 'user@example.com',
          email: 'user@example.com', // optional
          userAttributes: [ // optional
            {
              name: 'city',
              value: 'San Francisco'
            }
          ]
        }
      })
    }
  );

  // Handle streaming response
  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value);
    const lines = chunk.trim().split('\n');
    
    lines.forEach(line => {
      if (line) {
        const message = JSON.parse(line);
        console.log('Received:', message);
        
        // Handle different message types
        if (message.role === 'assistant' && message.content) {
          updateChatUI(message);
        }
      }
    });
  }
  ```
</CodeGroup>

## Error Handling

* **204 No Content**: (Abort endpoint only) Chat streaming was aborted successfully.
* **400 Bad Request**: Invalid request body or parameters. Check required fields and data types.
* **Authentication errors**: Returned as a JSON-RPC error object in an HTTP 200
  response. Verify your API key is correct and has the necessary permissions.
  For Cube token authentication, verify the token is valid for the agent's
  deployment, identifies a user via `externalId` (or `sub`), and carries the
  `chat` scope.
* **403 Forbidden**: (Abort endpoint only) The authenticated user does not own the specified chat thread.
* **404 Not Found**: Agent, tenant, or chat thread not found. Verify the Chat API URL from your agent settings and the `chatId`.
* **500 Internal Server Error**: Server processing error. Contact support if the issue persists.

[ref-api-keys]: /admin/account-billing/api-keys

[ref-jwt-auth]: /embedding/authentication/jwt

[ref-config-check-auth]: /reference/configuration/config#check_auth

[ref-headless-embedding]: /embedding#headless-embedding


# Generate Session
Source: https://docs.cube.dev/reference/embed-apis/generate-session

HTTP reference for minting short-lived embed sessions that authorize external viewers under signed embedding without sharing API keys.

The Generate Session API provides secure, session-based authentication for [signed embedding][ref-signed-embedding]. This API creates temporary sessions that allow external users to access embedded dashboards and visualizations without exposing your API keys.

<Info>
  The Generate Session API is available on [Premium and Enterprise plans](https://cube.dev/pricing).
</Info>

## Authentication

The Generate Session API requires your [Cube Cloud API key][ref-api-keys] for authentication.

If the API key is [scoped to specific deployments][ref-api-keys], the `deploymentId` in the request body must be within the key's scope; otherwise the request is rejected with `403 Forbidden`. Unscoped keys can mint sessions for any deployment.

## Endpoint

```text theme={"dark"}
POST https://{accountName}.cubecloud.dev/api/v1/embed/generate-session
```

### Request Headers

| Header          | Value                  | Required |
| --------------- | ---------------------- | -------- |
| `Content-Type`  | `application/json`     | Yes      |
| `Authorization` | `Api-Key YOUR_API_KEY` | Yes      |

### Request Body

| Field                      | Type      | Required    | Description                                                                                                                                                                             |
| -------------------------- | --------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deploymentId`             | number    | Yes         | ID of the deployment the session should grant access to.                                                                                                                                |
| `externalId`               | string    | Conditional | Stable identifier for the external user. Provide either `externalId` or `internalId` (not both). Must be lowercase and trimmed.                                                         |
| `internalId`               | string    | Conditional | Username of an existing internal Cube Cloud user. Provide either `externalId` or `internalId` (not both). The user must already exist.                                                  |
| `email`                    | string    | No          | Email to attach to the provisioned external user. Used only with `externalId`.                                                                                                          |
| `userProfile`              | object    | No          | Display name and profile picture to attach to the external user. See [User profile](#user-profile). Not allowed with `internalId`.                                                      |
| `embedTenantName`          | string    | No          | Embed tenant to scope content to. Lowercase, 5–36 chars, must start with a letter and end with a letter or digit, only `a-z`, `0-9`, `-`. Defaults to the current tenant.               |
| `creatorMode`              | boolean   | No          | When `true`, mints a [creator-mode][ref-creator-mode] session and resolves groups/attributes against the embed tenant's scoped tables. Requires the `useCreatorMode` tenant flag.       |
| `userAttributes`           | array     | No          | Attribute values for row-level security. See [User attributes](#user-attributes). Not allowed with `internalId`.                                                                        |
| `groups`                   | string\[] | No          | Group memberships for the user. See [Groups](#groups). Not allowed with `internalId`.                                                                                                   |
| `userAttributeDefinitions` | array     | No          | Idempotently upsert attribute definitions before applying values. Requires `creatorMode: true`. See [Creator mode bootstrap](#creator-mode-bootstrapping-groups-and-user-attributes).   |
| `groupDefinitions`         | array     | No          | Idempotently upsert group definitions before assigning memberships. Requires `creatorMode: true`. See [Creator mode bootstrap](#creator-mode-bootstrapping-groups-and-user-attributes). |
| `securityContext`          | object    | No          | Custom security context object passed to Cube queries. Not allowed with `internalId`.                                                                                                   |
| `settings`                 | object    | No          | Per-session overrides for embed behavior, applied to every embed viewed with this session. See [Session settings](#session-settings).                                                   |

<Info>
  When using `internalId`, the user must already exist in Cube Cloud. You cannot specify `groups`, `userAttributes`, `groupDefinitions`, `userAttributeDefinitions`, `securityContext`, or `userProfile` with `internalId` — the internal user's existing permissions are used instead.
</Info>

<Warning>
  Accounts are limited to 10,000 external users. To increase this limit, please contact support.
</Warning>

## Session settings

`settings` is an object of per-session overrides for embed behavior. Each key is
**tri-state**: omit it to inherit the account-wide setting, or set `true`/`false`
to force the behavior for every embed viewed with this session, taking precedence
over the account-wide setting.

```json theme={"dark"}
{
  "settings": {
    "showDashboardChat": false
  }
}
```

| Property            | Type    | Required | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `showDashboardChat` | boolean | No       | Show or hide the AI chat (agent panel and launcher bubble) on embedded dashboards for this session. Omit to inherit the account-wide **Show dashboard chat** toggle (**Embed → Settings**; shown by default); `false` hides it even if enabled account-wide, `true` shows it even if disabled. Affects embedded **published dashboards** only — not the standalone [embedded chat][ref-analytics-chat] surface. See [Hiding the AI chat][ref-signed-embedding]. |

<Note>
  The dashboard header's title, back button, Edit, and Duplicate controls are hidden with URL parameters on the embed iframe instead — they aren't part of this `settings` object. See [Show or hide header controls](/embedding/iframe/dashboards#show-or-hide-header-controls).
</Note>

## User profile

`userProfile` lets you attach a human-readable display name and avatar to an external user so they render with a recognizable identity inside embedded surfaces (workbook owners, dashboard headers, etc.) instead of the raw `externalId`.

```json theme={"dark"}
{
  "userProfile": {
    "displayName": "Jane Query",
    "picture": "https://example.com/avatars/jq.png"
  }
}
```

| Property      | Type   | Required | Notes                                                                                                   |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `displayName` | string | No       | Human-readable name shown next to the user's avatar.                                                    |
| `picture`     | string | No       | Publicly accessible URL of the user's profile picture. Must be an absolute `http://` or `https://` URL. |

**Behavior**:

* Both fields are persisted on the external user (keyed by `externalId`).
* Sending `userProfile` on subsequent `generate-session` calls overwrites the previously-saved values.
* Omitting `userProfile` (or omitting a property inside it) preserves whatever was saved before.

### Picture format

The `picture` URL must be reachable by the end-user's browser — it's loaded directly via an `<img>` tag in the embedded UI, not proxied through Cube Cloud. The server validates only that the value is a syntactically valid `http(s)://` URL; it does not download or sniff the content.

Use a URL that returns one of the common web image formats: **PNG, JPEG, GIF, WebP, or SVG**. Other content types (videos, PDFs, HTML pages) will fail to render and the avatar will fall back to the user's initials.

Practical guidance:

* Prefer HTTPS URLs — mixed-content rules will block `http://` images on HTTPS embed pages.
* Keep the image under \~1 MB and ideally square (e.g. 96×96 or 256×256). Avatars are displayed in small containers, so anything larger is wasted bandwidth.
* The URL must be publicly reachable — signed URLs that expire or assets behind auth headers will not load.
* If the URL fails to load for any reason (404, wrong content type, CORS, network error), the UI gracefully falls back to an initials avatar derived from `displayName`. No error is returned to the caller.

## User attributes

`userAttributes` is an array of `{ name, value }` pairs that drive row-level security in queries.

```json theme={"dark"}
{
  "userAttributes": [
    { "name": "department", "value": "Sales" },
    { "name": "tier", "value": 2 },
    { "name": "regions", "value": ["us-east", "eu-west"] },
    { "name": "thresholds", "value": [10, 25, 50] }
  ]
}
```

| Property | Type                                                       | Notes                                                                       |
| -------- | ---------------------------------------------------------- | --------------------------------------------------------------------------- |
| `name`   | string                                                     | Must reference an existing attribute definition (see lookup rules below).   |
| `value`  | `string` \| `number` \| `string[]` \| `number[]` \| `null` | The value type must match the definition's `type`. `null` clears the value. |

**Attribute definition lookup**:

* **Read-only mode** (`creatorMode` omitted or `false`): names are resolved against the tenant-wide attribute catalog (managed in **Settings → User Attributes** or via the admin GraphQL API). Any name not present there fails with `User attributes not found`.
* **Creator mode** (`creatorMode: true`): names are resolved against the embed tenant's scoped catalog (`embed_user_attributes`). Use `userAttributeDefinitions` in the same request to upsert definitions on the fly — see [Creator mode bootstrap](#creator-mode-bootstrapping-groups-and-user-attributes).

**Rules**:

* Duplicate `name` entries are rejected with `400 Bad Request`.
* Values are persisted per user. Subsequent calls with the same `externalId` overwrite previous values for the supplied names.

## Groups

`groups` is an array of group **names** (not IDs) that the user should belong to. Group definitions must already exist (or be created in the same request via `groupDefinitions` in creator mode).

```json theme={"dark"}
{ "groups": ["analysts", "marketing"] }
```

**Behavior**:

| Value                       | Effect                                                    |
| --------------------------- | --------------------------------------------------------- |
| Field omitted (`undefined`) | Existing memberships are preserved.                       |
| `[]` (empty array)          | All memberships are cleared.                              |
| Populated array             | Memberships are replaced with exactly the supplied names. |

**Group definition lookup**:

* **Read-only mode**: names are resolved against tenant-wide groups (managed in **Settings → Groups** or via the admin GraphQL API). The membership row references the global group.
* **Creator mode**: names are resolved against the embed tenant's scoped groups (`embed_user_groups`). Use `groupDefinitions` in the same request to upsert them.

If any name in `groups` cannot be resolved, the request fails with `Groups with names <missing> not found`.

## Creator mode: bootstrapping groups and user attributes

In API-first integrations you often want to mint an embed session and define the groups/attributes it references in a single call, without first making a round trip to the admin UI. The `groupDefinitions` and `userAttributeDefinitions` fields do that — they idempotently upsert definitions in the embed tenant's scoped tables and are validated **before** `groups` and `userAttributes` are applied.

Both fields:

* Require `creatorMode: true`.
* Require an `embedTenantName` (definitions are only meaningful inside an embed tenant).
* Require the `useCreatorMode` tenant flag — contact support to enable.
* Land in the embed-tenant scope only — they never modify tenant-wide groups or attributes.
* Are idempotent: running the same request twice produces the same end state.

### `groupDefinitions`

```json theme={"dark"}
{
  "groupDefinitions": [
    { "name": "analysts", "description": "Read-only viewers" },
    { "name": "marketing" }
  ]
}
```

| Property      | Type   | Required | Notes                                                                     |
| ------------- | ------ | -------- | ------------------------------------------------------------------------- |
| `name`        | string | Yes      | Group name. Existing groups with this name are reused.                    |
| `description` | string | No       | Updated when supplied and different from the stored value. Never cleared. |

Duplicate `name` entries within the same request are rejected.

### `userAttributeDefinitions`

```json theme={"dark"}
{
  "userAttributeDefinitions": [
    {
      "name": "department",
      "type": "string",
      "displayName": "Department",
      "defaultValue": "Unassigned",
      "description": "Org unit"
    }
  ]
}
```

| Property       | Type   | Required | Notes                                                                                 |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `name`         | string | Yes      | Attribute name. Existing attributes with this name are reused.                        |
| `type`         | enum   | Yes      | One of `string`, `number`, `string_array`, `number_array`. **Immutable** — see below. |
| `displayName`  | string | No       | Updated when supplied and different from the stored value.                            |
| `defaultValue` | string | No       | Updated when supplied and different from the stored value.                            |
| `description`  | string | No       | Updated when supplied and different from the stored value.                            |

**`type` is immutable.** If a definition with the supplied `name` already exists with a different `type`, the request fails with `cannot change type` and nothing is upserted. This protects every value already stored against that attribute from silently becoming invalid. To change the type, delete the attribute via the [embed-tenant admin API](#embed-tenant-admin-api) and recreate it.

Duplicate `name` entries within the same request are rejected.

### Bootstrap example

Define a group and an attribute, assign the user to both, and mint a session — all in one call:

```javascript theme={"dark"}
const session = await fetch(
  `https://${ACCOUNT_NAME}.cubecloud.dev/api/v1/embed/generate-session`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Api-Key ${API_KEY}`,
    },
    body: JSON.stringify({
      deploymentId: DEPLOYMENT_ID,
      externalId: "user-123",
      embedTenantName: "acme-corp",
      creatorMode: true,

      // Upserted before validation runs
      groupDefinitions: [
        { name: "analysts", description: "Read-only viewers" },
      ],
      userAttributeDefinitions: [
        { name: "department", type: "string", displayName: "Department" },
      ],

      // Reference the names we just defined
      groups: ["analysts"],
      userAttributes: [{ name: "department", value: "Sales" }],
    }),
  }
);
```

A second call with the same body produces the same end state: the group and attribute already exist, descriptions/display names are reconciled if they changed, and the user's memberships and values are re-applied.

## Embed-tenant admin API

To list or delete the groups and attributes that have been bootstrapped into an embed tenant, use the admin endpoints scoped to that tenant:

```text theme={"dark"}
GET    /api/v1/embed-tenants/{embedTenantName}/groups
DELETE /api/v1/embed-tenants/{embedTenantName}/groups/{id}
GET    /api/v1/embed-tenants/{embedTenantName}/user-attributes
DELETE /api/v1/embed-tenants/{embedTenantName}/user-attributes/{id}
```

These endpoints use the same `Api-Key` authentication as Generate Session and require admin access. List endpoints return cursor-paginated results (`?first=`, `?after=`).

### Response

The API returns a session object:

```json theme={"dark"}
{
  "sessionId": "abc123def456..."
}
```

| Field       | Type   | Description                                            |
| ----------- | ------ | ------------------------------------------------------ |
| `sessionId` | string | Unique session identifier to use for embedding content |

Use the `sessionId` directly in your embed URL to authenticate and load content securely.

## Code Example

<CodeGroup>
  ```python title="Python" Python theme={"dark"}
  import requests

  API_KEY = 'YOUR_API_KEY'
  ACCOUNT_NAME = 'your-account'

  # Generate a session on your server
  response = requests.post(
      f'https://{ACCOUNT_NAME}.cubecloud.dev/api/v1/embed/generate-session',
      headers={
          'Content-Type': 'application/json',
          'Authorization': f'Api-Key {API_KEY}'
      },
      json={
          'deploymentId': 32,
          'externalId': 'user@example.com',
          'userAttributes': [
              {'name': 'department', 'value': 'Sales'}
          ],
          'groups': ['analysts']
      }
  )

  session_id = response.json()['sessionId']
  ```

  ```javascript title="JavaScript" JavaScript theme={"dark"}
  const API_KEY = "YOUR_API_KEY";
  const ACCOUNT_NAME = "your-account";

  // Generate a session on your server
  const response = await fetch(
    `https://${ACCOUNT_NAME}.cubecloud.dev/api/v1/embed/generate-session`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Api-Key ${API_KEY}`,
      },
      body: JSON.stringify({
        deploymentId: 32,
        externalId: "user@example.com",
        userAttributes: [{ name: "department", value: "Sales" }],
        groups: ["analysts"],
      }),
    }
  );

  const { sessionId } = await response.json();
  ```

  ```bash title="Bash" cURL theme={"dark"}
  curl -X POST "https://your-account.cubecloud.dev/api/v1/embed/generate-session" \
    -H "Content-Type: application/json" \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -d '{
      "deploymentId": 32,
      "externalId": "user@example.com",
      "userAttributes": [
        {"name": "department", "value": "Sales"}
      ],
      "groups": ["analysts"]
    }'
  ```
</CodeGroup>

Use session ID in [signed embedding][ref-signed-embedding].

[ref-api-keys]: /admin/account-billing/api-keys

[ref-signed-embedding]: /embedding/iframe/auth/signed

[ref-creator-mode]: /embedding/iframe/creator-mode

[ref-analytics-chat]: /embedding/iframe/analytics-chat


# Embed APIs
Source: https://docs.cube.dev/reference/embed-apis/index

Integrate Cube analytics into your applications using the Chat API and session-based secure embedding.

Embed APIs

Embed APIs enable you to integrate Cube's analytics capabilities directly into your applications with secure, session-based authentication.

## Available APIs

### [Chat API][ref-chat-api]

API-first approach to build custom Analytics Chat experiences. Use this API to programmatically integrate AI-powered conversations with your data into your applications.

### [Generate Session][ref-generate-session]

Create secure, temporary sessions for embedding Cube content. Use sessions to authenticate users for [signed embedding][ref-embedding] without exposing API keys.

[ref-chat-api]: /reference/embed-apis/chat-api

[ref-generate-session]: /reference/embed-apis/generate-session

[ref-embedding]: /embedding/iframe/auth/signed


# Angular
Source: https://docs.cube.dev/reference/javascript-sdk/angular

Cube is visualization-agnostic, so you can build any user interface for your application.

You can directly query Cube using the
JSON [query format](/reference/core-data-apis/rest-api/query-format) via the [REST (JSON) API](/reference/core-data-apis/rest-api/reference)
or
[WebSockets](/recipes/core-data-api/real-time-data-fetch)
and visualize analytical data with tools of your choice. However, it’s much
easier to use the Cube JavaScript client and bindings for popular frameworks
such as React, Angular, and Vue.

The client has methods to communicate with the Cube API Gateway, and retrieve
and process data. It is designed to work with existing charting libraries
including Chart.js, D3.js, and more.

## Cube JavaScript Client

The client provides methods to solve common tasks:

**Abstract from the transport and query data.** You can
[fetch data](/reference/javascript-sdk/reference/cubejs-client-core#load) from Cube Backend or
subscribe to
[real-time updates](/recipes/core-data-api/real-time-data-fetch)
regardless of the protocol, be it HTTP or WebSockets.

**Transform data for visualization.** You can
[pivot](/reference/javascript-sdk/reference/cubejs-client-core#pivot) the result set to display
as a [chart](/reference/javascript-sdk/reference/cubejs-client-core#chartpivot) or as a
[table](/reference/javascript-sdk/reference/cubejs-client-core#tablepivot), split into
[series](/reference/javascript-sdk/reference/cubejs-client-core#series) or
[table columns](/reference/javascript-sdk/reference/cubejs-client-core#tablecolumns).

**Simplify work with complex query types.** You can build
[drill down](/reference/javascript-sdk/reference/cubejs-client-core#drilldown) queries and
[decompose](/reference/javascript-sdk/reference/cubejs-client-core#decompose) the results of
[compare date range queries][ref-compare-date-range]
or [data blending](/docs/data-modeling/concepts/data-blending) queries.

[Learn more](/reference/javascript-sdk/reference/cubejs-client-core) in the documentation for
the `@cubejs-client/core` package.

## Cube Angular Package

The package provides convenient tools to work with Cube in Angular:

**Modules.** Inject [`CubeClientModule` and `CubeClient`](/reference/javascript-sdk/reference/cubejs-client-ngx#api) into your
components and services to get access to `@cubejs-client/core` API.

**Subjects.** Use [RxJS Subject](/reference/javascript-sdk/reference/cubejs-client-ngx#api) and
query to watch changes.

## Example Usage

Here are the typical steps to query and visualize analytical data in Angular:

* **Import `@cubejs-client/core` and `@cubejs-client/ngx` packages.** These
  packages provide all the necessary methods and convenient Angular tools.
* **Create an instance of Cube JavaScript Client.** The client is initialized
  with Cube API URL. In development mode, the default URL is
  [http://localhost:4000/cubejs-api/v1](http://localhost:4000/cubejs-api/v1).
  The client is also initialized with an [API token](/docs/data-modeling/access-control), but it
  takes effect only in [production](/cube-core/running-in-production): with
  `NODE_ENV` unset the API accepts requests with no token, and development mode
  [bypasses authentication](/reference/configuration/environment-variables#cubejs_dev_mode)
  outright, so both are intended for local development machines only.
* **Query data from Cube Backend and Transform data for visualization.** Use
  [`CubeClient`](/reference/javascript-sdk/reference/cubejs-client-ngx#api) to load data. The
  client accepts a query, which is a plain JavaScript object. See
  [Query Format](/reference/core-data-apis/rest-api/query-format) for details.
* **Visualize the data.** Use tools of your choice to draw charts and create
  visualizations.

See an example of using Cube with Angular and Chart.js library. Note that you
can always use a different charting library that suits your needs:

<iframe />

## Getting Started

You can install Cube JavaScript Client and the Angular package with npm or Yarn:

```bash theme={"dark"}
# npm
npm install --save @cubejs-client/core @cubejs-client/ngx

# Yarn
yarn add @cubejs-client/core @cubejs-client/ngx
```

Now you can build your application from scratch or connect to one of our
[supported data visualization tools](/admin/connect-to-data/visualization-tools).

[ref-compare-date-range]: /reference/core-data-apis/queries#compare-date-range-query


# npm
Source: https://docs.cube.dev/reference/javascript-sdk/index

Use Cube's JavaScript client and React, Vue, or Angular bindings to build data-driven UIs.

JavaScript SDK

Cube is visualization-agnostic, so you can build any user interface for your
application.

You can directly query Cube using the
JSON [query format](/reference/core-data-apis/rest-api/query-format) via the [REST (JSON) API](/reference/core-data-apis/rest-api/reference)
or
[WebSockets](/recipes/core-data-api/real-time-data-fetch)
and visualize analytical data with tools of your choice. However, it's much
easier to use the Cube JavaScript client and bindings for popular frameworks
such as React, Angular, and Vue.

The client has methods to communicate with Cube API Gateway and retrieve and
process data. It is designed to work with existing charting libraries including
Chart.js, D3.js, and more.

## Cube JavaScript Client

The client provides methods to solve common tasks:

**Abstract from the transport and query data.** You can
[fetch data](/reference/javascript-sdk/reference/cubejs-client-core#load) from Cube Backend or
subscribe to
[real-time updates](/recipes/core-data-api/real-time-data-fetch)
regardless of the protocol, be it HTTP or WebSockets.

**Transform data for visualization.** You can
[pivot](/reference/javascript-sdk/reference/cubejs-client-core#pivot) the result set to display
as a [chart](/reference/javascript-sdk/reference/cubejs-client-core#chartpivot) or as a
[table](/reference/javascript-sdk/reference/cubejs-client-core#tablepivot), split into
[series](/reference/javascript-sdk/reference/cubejs-client-core#series) or
[table columns](/reference/javascript-sdk/reference/cubejs-client-core#tablecolumns).

**Simplify work with complex query types.** You can build
[drill down](/reference/javascript-sdk/reference/cubejs-client-core#drilldown) queries and
[decompose](/reference/javascript-sdk/reference/cubejs-client-core#decompose) the results of
[compare date range queries][ref-compare-date-range]
or [data blending](/docs/data-modeling/concepts/data-blending) queries.

[Learn more](/reference/javascript-sdk/reference/cubejs-client-core) in the documentation for
the `@cubejs-client/core` package.

## Example Usage

Here are the typical steps to query and visualize analytical data:

* **Import the `@cubejs-client/core` package.** This package provides all the
  necessary methods.
* **Create an instance of Cube JavaScript Client.** The client is initialized
  with Cube API URL. In development mode, the default URL is
  [http://localhost:4000/cubejs-api/v1](http://localhost:4000/cubejs-api/v1).
  The client is also initialized with an [API token](/docs/data-modeling/access-control), but it
  takes effect only in [production](/cube-core/running-in-production): with
  `NODE_ENV` unset the API accepts requests with no token, and development mode
  [bypasses authentication](/reference/configuration/environment-variables#cubejs_dev_mode)
  outright, so both are intended for local development machines only.
* **Query data from Cube Backend.** The client accepts a query, which is a plain
  JavaScript object. See
  [Query Format](/reference/core-data-apis/rest-api/query-format) for details.
* **Transform data for visualization.** The result set has convenient methods,
  such as `series` and `chartPivot`, to prepare data for charting.
* **Visualize the data.** Use tools of your choice to draw charts and create
  visualizations.

See an example of using Cube with vanilla JavaScript and Chart.js library. Note
that you can always use a different charting library that suits your needs:

<iframe />

## Getting Started

You can install Cube JavaScript Client with npm or Yarn:

```bash theme={"dark"}
# npm
npm install --save @cubejs-client/core

# Yarn
yarn add @cubejs-client/core
```

Now you can build your application from scratch or connect to one of our
[supported data visualization tools](/admin/connect-to-data/visualization-tools).

## Data format

The [REST (JSON) API][ref-rest-api] uses JSON to serialize and transfer result sets.
Numbers, e.g., values of numeric measures, are represented as strings.

By default, JavaScript SDK also returns numbers as strings because an automatic
conversion might lead to a precision loss. In JavaScript, only numbers between
[`Number.MAX_SAFE_INTEGER`][link-max-safe-int] and `Number.MIN_SAFE_INTEGER`
can be safely parsed from strings. However, there's no guarantee that a measure
value or a column value from a supported [data source][ref-data-sources] would
not be outside of this range.

If you'd like Cube to convert strings to numbers anyway, you can use the
[`castNumerics` option][ref-ref-loadmethodoptions] for that:

```javascript theme={"dark"}
import cube from '@cubejs-client/core'
 
const cubeApi = cube(CUBE_API_TOKEN, {
  apiUrl: CUBE_API_URL
})

const resultSet = await cubeApi.load(query, {
  castNumerics: true
})

console.log(resultSet.tablePivot())
```

[ref-compare-date-range]: /reference/core-data-apis/queries#compare-date-range-query

[ref-rest-api]: /reference/core-data-apis/rest-api

[link-max-safe-int]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER

[ref-data-sources]: /admin/connect-to-data/data-sources

[ref-ref-loadmethodoptions]: /reference/javascript-sdk/reference/cubejs-client-core#loadmethodoptions


# React
Source: https://docs.cube.dev/reference/javascript-sdk/react

Cube is visualization-agnostic, so you can build any user interface for your application.

You can directly query Cube using the
JSON [query format](/reference/core-data-apis/rest-api/query-format) via the [REST (JSON) API](/reference/core-data-apis/rest-api/reference)
or
[WebSockets](/recipes/core-data-api/real-time-data-fetch)
and visualize analytical data with tools of your choice. However, it's much
easier to use the Cube JavaScript client and bindings for popular frameworks
such as React, Angular, and Vue.

The client has methods to communicate with Cube API Gateway and retrieve and
process data. It is designed to work with existing charting libraries including
Chart.js, D3.js, and more.

## Cube JavaScript Client

The client provides methods to solve common tasks:

**Abstract from the transport and query data.** You can
[fetch data](/reference/javascript-sdk/reference/cubejs-client-core#load) from Cube Backend or
subscribe to
[real-time updates](/recipes/core-data-api/real-time-data-fetch)
regardless of the protocol, be it HTTP or WebSockets.

**Transform data for visualization.** You can
[pivot](/reference/javascript-sdk/reference/cubejs-client-core#pivot) the result set to display
as a [chart](/reference/javascript-sdk/reference/cubejs-client-core#chartpivot) or as a
[table](/reference/javascript-sdk/reference/cubejs-client-core#tablepivot), split into
[series](/reference/javascript-sdk/reference/cubejs-client-core#series) or
[table columns](/reference/javascript-sdk/reference/cubejs-client-core#tablecolumns).

**Simplify work with complex query types.** You can build
[drill down](/reference/javascript-sdk/reference/cubejs-client-core#drilldown) queries and
[decompose](/reference/javascript-sdk/reference/cubejs-client-core#decompose) the results of
[compare date range queries][ref-compare-date-range]
or [data blending](/docs/data-modeling/concepts/data-blending) queries.

[Learn more](/reference/javascript-sdk/reference/cubejs-client-core) in the documentation for
the `@cubejs-client/core` package.

## Cube React Package

The package provides convenient tools to work with Cube in React:

**Hooks.** You can add the
[useCubeQuery hook](/reference/javascript-sdk/reference/cubejs-client-react#usecubequery) to
functional React components to execute Cube queries.

**Components.** You can use
[`QueryBuilder`](/reference/javascript-sdk/reference/cubejs-client-react#querybuilder) and
[`QueryRenderer`](/reference/javascript-sdk/reference/cubejs-client-react#queryrenderer)
components to separate state management and API calls from your rendering code.
You can also use
[`CubeProvider`](/reference/javascript-sdk/reference/cubejs-client-react#cubeprovider) and
[`CubeContext`](/reference/javascript-sdk/reference/cubejs-client-react#cubecontext) components
for direct access to Cube client anywhere in your application.

## Example Usage

Here are the typical steps to query and visualize analytical data in React:

* **Import `@cubejs-client/core` and `@cubejs-client/react` packages.** These
  packages provide all the necessary methods and convenient React tools.
* **Create an instance of Cube JavaScript Client.** The client is initialized
  with Cube API URL. In development mode, the default URL is
  [http://localhost:4000/cubejs-api/v1](http://localhost:4000/cubejs-api/v1).
  The client is also initialized with an [API token](/docs/data-modeling/access-control), but it
  takes effect only in [production](/cube-core/running-in-production): with
  `NODE_ENV` unset the API accepts requests with no token, and development mode
  [bypasses authentication](/reference/configuration/environment-variables#cubejs_dev_mode)
  outright, so both are intended for local development machines only.
* **Query data from Cube Backend.** In functional React components, use the
  `useCubeQuery` hook to execute a query, which is a plain JavaScript object.
  See [Query Format](/reference/core-data-apis/rest-api/query-format) for
  details.
* **Transform data for visualization.** The result set has convenient methods,
  such as `series` and `chartPivot`, to prepare data for charting.
* **Visualize the data.** Use tools of your choice to draw charts and create
  visualizations.

See an example of using Cube with React and Chart.js library. Note that you can
always use a different charting library that suits your needs:

<iframe />

## Getting Started

You can install Cube JavaScript Client and the React package with npm or Yarn:

```bash theme={"dark"}
# npm
npm install --save @cubejs-client/core @cubejs-client/react

# Yarn
yarn add @cubejs-client/core @cubejs-client/react
```

Now you can build your application from scratch or connect to one of our
[supported data visualization tools](/admin/connect-to-data/visualization-tools).

[ref-compare-date-range]: /reference/core-data-apis/queries#compare-date-range-query


# `@cubejs-client/core`
Source: https://docs.cube.dev/reference/javascript-sdk/reference/cubejs-client-core

Vanilla JavaScript client for Cube.

## `cube`

> **cube**(**apiToken**: string |  () => *Promise‹string›*, **options**: [CubeApiOptions](#cubeapioptions)): *[CubeApi](#cubeapi)*

Creates an instance of the `CubeApi`. The API entry point.

```js theme={"dark"}
import cube from '@cubejs-client/core';
const cubeApi = cube(
  'CUBE-API-TOKEN',
  { apiUrl: 'http://localhost:4000/cubejs-api/v1' }
);
```

You can also pass an async function or a promise that will resolve to the API token

```js theme={"dark"}
import cube from '@cubejs-client/core';
const cubeApi = cube(
  async () => await Auth.getJwtToken(),
  { apiUrl: 'http://localhost:4000/cubejs-api/v1' }
);
```

If you need to set up cancellation for all requests made by this API instance:

```js theme={"dark"}
import cube from '@cubejs-client/core';

// Create a controller for managing request cancellation
const controller = new AbortController();
const { signal } = controller;

const cubeApi = cube(
  'CUBE-API-TOKEN',
  {
    apiUrl: 'http://localhost:4000/cubejs-api/v1',
    signal: signal
  }
);

// Later when you need to cancel all pending requests:
// controller.abort();
```

**Parameters:**

| Name     | Type                               | Description                                                                                                                                                                                                                                                                                                                                                                                      |
| -------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| apiToken | string \|  () => *Promise‹string›* | [API token][ref-security] is used to authorize requests and determine SQL database you're accessing. In [development mode](/reference/configuration/environment-variables#cubejs_dev_mode) (local use only — it bypasses authentication), Cube will print the API token to the console on startup. In case of async function `authorization` is updated for `options.transport` on each request. |
| options  | [CubeApiOptions](#cubeapioptions)  | -                                                                                                                                                                                                                                                                                                                                                                                                |

> **cube**(**options**: [CubeApiOptions](#cubeapioptions)): *[CubeApi](#cubeapi)*

## `defaultHeuristics`

> **defaultHeuristics**(**newQuery**: [Query](#query-2), **oldQuery**: [Query](#query-2), **options**: [TDefaultHeuristicsOptions](#tdefaultheuristicsoptions)): *any*

## `defaultOrder`

> **defaultOrder**(**query**: [Query](#query-2)): *object*

## `movePivotItem`

> **movePivotItem**(**pivotConfig**: [PivotConfig](#pivotconfig), **sourceIndex**: number, **destinationIndex**: number, **sourceAxis**: TSourceAxis, **destinationAxis**: TSourceAxis): *[PivotConfig](#pivotconfig)*

## Format API

A set of helpers for formatting member values on the client, consistently with how
Cube formats them. They are imported from the `@cubejs-client/core/format` subpath:

```js theme={"dark"}
import { formatValue, getFormat, formatDateByGranularity } from '@cubejs-client/core/format';
```

### `formatValue`

> **formatValue**(**value**: any, **options**: FormatValueOptions): *string*

Formats a single value according to a member's `type` and `format`. `options` extends the
member's metadata (`type`, `format`, `currency`, `granularity`) with an optional `locale`
(e.g. `'en-US'`, `'de-DE'`) and an `emptyPlaceholder` for empty values. Numeric formats use
[d3-format](https://d3js.org/d3-format) specifiers, and the precision of named formats (e.g.
`currency_2`) is treated as an upper bound — insignificant trailing zeros are trimmed.

```js theme={"dark"}
import { formatValue } from '@cubejs-client/core/format';

formatValue(1234.5, { type: 'number', format: 'currency_2', currency: 'EUR', locale: 'de-DE' });
```

### `getFormat`

> **getFormat**(**member**: FormatValueMember, **options?**: GetFormatOptions): *GetFormatResult*

Returns a reusable formatter for a member. `options` accepts an optional `locale`. The result
has two properties: `formatString` (the resolved format specifier, or `null` for non-numeric
formats) and `formatFunc`, a function that formats a value. Use it when formatting many values
for the same member.

### `formatDateByGranularity`

> **formatDateByGranularity**(**value**: Date | string | number, **granularity?**: string): *string*

Formats a date value for a given time dimension `granularity` (e.g. `'day'`, `'month'`,
`'year'`).

## `CubeApi`

Main class for accessing Cube API

### `cubeSql`

> **cubeSql**(**sqlQuery**: string, **options?**: [CubeSqlOptions](#cubesqloptions)): *Promise‹[CubeSqlResult](#cubesqlresult)›*

> **cubeSql**(**sqlQuery**: string, **options?**: [CubeSqlOptions](#cubesqloptions), **callback?**: [LoadMethodCallback](#loadmethodcallback)‹[CubeSqlResult](#cubesqlresult)›): *void*

Run a SQL query via the [`/v1/cubesql`][ref-cubesql-endpoint] endpoint of the
[SQL API][ref-sql-api] and get the results.

```js theme={"dark"}
const result = await cubeApi.cubeSql(
  'SELECT status, MEASURE(count) FROM orders GROUP BY 1',
  { timezone: 'America/Los_Angeles' }
);
```

**Parameters:**

| Name      | Type                                                                       | Description          |
| --------- | -------------------------------------------------------------------------- | -------------------- |
| sqlQuery  | string                                                                     | The SQL query to run |
| options?  | [CubeSqlOptions](#cubesqloptions)                                          | -                    |
| callback? | [LoadMethodCallback](#loadmethodcallback)‹[CubeSqlResult](#cubesqlresult)› | -                    |

### `cubeSqlStream`

> **cubeSqlStream**(**sqlQuery**: string, **options?**: [CubeSqlOptions](#cubesqloptions)): *AsyncGenerator‹CubeSqlStreamChunk›*

Same as [`cubeSql`](#cubesql), but yields the results as they stream in. Each
chunk is either `{ type: 'schema', schema, lastRefreshTime?, external?, usedPreAggregations? }`,
`{ type: 'data', data }` (one row), or `{ type: 'error', error }`.

```js theme={"dark"}
for await (const chunk of cubeApi.cubeSqlStream(
  'SELECT status, MEASURE(count) FROM orders GROUP BY 1',
  { timezone: 'America/Los_Angeles' }
)) {
  if (chunk.type === 'data') {
    console.log(chunk.data);
  }
}
```

**Parameters:**

| Name     | Type                              | Description          |
| -------- | --------------------------------- | -------------------- |
| sqlQuery | string                            | The SQL query to run |
| options? | [CubeSqlOptions](#cubesqloptions) | -                    |

### `dryRun`

> **dryRun**(**query**: [Query](#query-2) | [Query](#query-2)\[], **options?**: [LoadMethodOptions](#loadmethodoptions)): *Promise‹[TDryRunResponse](#tdryrunresponse)›*

> **dryRun**(**query**: [Query](#query-2) | [Query](#query-2)\[], **options**: [LoadMethodOptions](#loadmethodoptions), **callback?**: [LoadMethodCallback](#loadmethodcallback)‹[TDryRunResponse](#tdryrunresponse)›): *void*

Get query related meta without query execution

### `load`

> **load**(**query**: [Query](#query-2) | [Query](#query-2)\[], **options?**: [LoadMethodOptions](#loadmethodoptions)): *Promise‹[ResultSet](#resultset)›*

> **load**(**query**: [Query](#query-2) | [Query](#query-2)\[], **options?**: [LoadMethodOptions](#loadmethodoptions), **callback?**: [LoadMethodCallback](#loadmethodcallback)‹[ResultSet](#resultset)›): *void*

Fetch data for the passed `query`.

```js theme={"dark"}
import cube from '@cubejs-client/core';
import Chart from 'chart.js';
import chartjsConfig from './toChartjsData';

const cubeApi = cube('CUBE_TOKEN');

const resultSet = await cubeApi.load({
 measures: ['Stories.count'],
 timeDimensions: [{
   dimension: 'Stories.time',
   dateRange: ['2015-01-01', '2015-12-31'],
   granularity: 'month'
  }]
});

const context = document.getElementById('myChart');
new Chart(context, chartjsConfig(resultSet));
```

You can also use AbortController to cancel a request:

```js theme={"dark"}
import cube from '@cubejs-client/core';

const cubeApi = cube('CUBE_TOKEN');

// Create an AbortController instance
const controller = new AbortController();
const { signal } = controller;

try {
  // Pass the signal to the load method
  const resultSetPromise = cubeApi.load(
    {
      measures: ['Orders.count'],
      dimensions: ['Orders.status']
    },
    { signal }
  );

  // To cancel the request at any time:
  // controller.abort();

  const resultSet = await resultSetPromise;
  // Process the result
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Request was cancelled');
  } else {
    console.error('Error loading data:', error);
  }
}
```

**Parameters:**

| Name      | Type                                                               | Description                      |
| --------- | ------------------------------------------------------------------ | -------------------------------- |
| query     | [Query](#query-2) \| [Query](#query-2)\[]                          | [Query object][ref-query-format] |
| options?  | [LoadMethodOptions](#loadmethodoptions)                            | -                                |
| callback? | [LoadMethodCallback](#loadmethodcallback)‹[ResultSet](#resultset)› | -                                |

### `meta`

> **meta**(**options?**: [MetaMethodOptions](#metamethodoptions)): *Promise‹[Meta](#meta-2)›*

> **meta**(**options?**: [MetaMethodOptions](#metamethodoptions), **callback?**: [LoadMethodCallback](#loadmethodcallback)‹[Meta](#meta-2)›): *void*

Get meta description of cubes available for querying.

Pass `onlyViews: true` to request views only. On large data models this keeps cubes
out of the response payload:

```js theme={"dark"}
const meta = await cubeApi.meta({ onlyViews: true });
```

<Info>
  Cube versions predating this option behave differently per transport: over HTTP they
  ignore it and return the full data model, while over
  [`WebSocketTransport`](/reference/javascript-sdk/reference/cubejs-client-ws-transport)
  they reject the message with a `400`, because `meta` params are validated strictly.
</Info>

**Parameters:**

| Name      | Type                                                       | Description |
| --------- | ---------------------------------------------------------- | ----------- |
| options?  | [MetaMethodOptions](#metamethodoptions)                    | -           |
| callback? | [LoadMethodCallback](#loadmethodcallback)‹[Meta](#meta-2)› | -           |

### `sql`

> **sql**(**query**: [Query](#query-2) | [Query](#query-2)\[], **options?**: [LoadMethodOptions](#loadmethodoptions)): *Promise‹[SqlQuery](#sqlquery)›*

> **sql**(**query**: [Query](#query-2) | [Query](#query-2)\[], **options?**: [LoadMethodOptions](#loadmethodoptions), **callback?**: [LoadMethodCallback](#loadmethodcallback)‹[SqlQuery](#sqlquery)›): *void*

Get generated SQL string for the given `query`.

**Parameters:**

| Name      | Type                                                             | Description                      |
| --------- | ---------------------------------------------------------------- | -------------------------------- |
| query     | [Query](#query-2) \| [Query](#query-2)\[]                        | [Query object][ref-query-format] |
| options?  | [LoadMethodOptions](#loadmethodoptions)                          | -                                |
| callback? | [LoadMethodCallback](#loadmethodcallback)‹[SqlQuery](#sqlquery)› | -                                |

### `subscribe`

> **subscribe**(**query**: [Query](#query-2) | [Query](#query-2)\[], **options**: [LoadMethodOptions](#loadmethodoptions) | null, **callback**: [LoadMethodCallback](#loadmethodcallback)‹[ResultSet](#resultset)›): *void*

Allows you to fetch data and receive updates over time. See [Real-Time Data Fetch](/recipes/core-data-api/real-time-data-fetch)

```js theme={"dark"}
cubeApi.subscribe(
  {
    measures: ['Logs.count'],
    timeDimensions: [
      {
        dimension: 'Logs.time',
        granularity: 'hour',
        dateRange: 'last 1440 minutes',
      },
    ],
  },
  options,
  (error, resultSet) => {
    if (!error) {
      // handle the update
    }
  }
);
```

## `HttpTransport`

Default transport implementation.

### constructor

> **new HttpTransport**(**options**: [TransportOptions](#transportoptions)): *[HttpTransport](#httptransport)*

### `request`

> **request**(**method**: string, **params**: any): () => *Promise‹any›*

*Implementation of ITransport*

## `Meta`

Contains information about available cubes and it's members.

### `defaultTimeDimensionNameFor`

> **defaultTimeDimensionNameFor**(**memberName**: string): *string*

### `filterOperatorsForMember`

> **filterOperatorsForMember**(**memberName**: string, **memberType**: [MemberType](#membertype) | [MemberType](#membertype)\[]): *any*

### `membersForQuery`

> **membersForQuery**(**query**: [Query](#query-2) | null, **memberType**: [MemberType](#membertype)): *[TCubeMeasure](#tcubemeasure)\[] | [TCubeDimension](#tcubedimension)\[] | [TCubeMember](#tcubemember)\[]*

Get all members of a specific type for a given query.
If empty query is provided no filtering is done based on query context and all available members are retrieved.

**Parameters:**

| Name       | Type                      | Description                                                                  |
| ---------- | ------------------------- | ---------------------------------------------------------------------------- |
| query      | [Query](#query-2) \| null | context query to provide filtering of members available to add to this query |
| memberType | [MemberType](#membertype) | -                                                                            |

### `resolveMember`

> **resolveMember**‹**T**›(**memberName**: string, **memberType**: T | T\[]): *object | [TCubeMemberByType](#tcubememberbytype)‹T›*

Get meta information for a cube member
Member meta information contains:

```javascript theme={"dark"}
{
  name,
  title,
  shortTitle,
  type,
  description,
  format
}
```

**Type parameters:**

* **T**: *[MemberType](#membertype)*

**Parameters:**

| Name       | Type      | Description                                             |
| ---------- | --------- | ------------------------------------------------------- |
| memberName | string    | Fully qualified member name in a form `Cube.memberName` |
| memberType | T \| T\[] | -                                                       |

## `ProgressResult`

### `stage`

> **stage**(): *string*

### `timeElapsed`

> **timeElapsed**(): *string*

## `ResultSet`

Provides a convenient interface for data manipulation.

### `annotation`

> **annotation**(): *[QueryAnnotations](#queryannotations)*

### `chartPivot`

> **chartPivot**(**pivotConfig?**: [PivotConfig](#pivotconfig)): *[ChartPivotRow](#chartpivotrow)\[]*

Returns normalized query result data in the following format.

You can find the examples of using the `pivotConfig` [here](#pivotconfig)

```js theme={"dark"}
// For the query
{
  measures: ['Stories.count'],
  timeDimensions: [{
    dimension: 'Stories.time',
    dateRange: ['2015-01-01', '2015-12-31'],
    granularity: 'month'
  }]
}

// ResultSet.chartPivot() will return
[
  { "x":"2015-01-01T00:00:00", "Stories.count": 27120, "xValues": ["2015-01-01T00:00:00"] },
  { "x":"2015-02-01T00:00:00", "Stories.count": 25861, "xValues": ["2015-02-01T00:00:00"]  },
  { "x":"2015-03-01T00:00:00", "Stories.count": 29661, "xValues": ["2015-03-01T00:00:00"]  },
  //...
]

```

When using `chartPivot()` or `seriesNames()`, you can pass `aliasSeries` in the [pivotConfig](#pivotconfig)
to give each series a unique prefix. This is useful for `blending queries` which use the same measure multiple times.

```js theme={"dark"}
// For the queries
{
  measures: ['Stories.count'],
  timeDimensions: [
    {
      dimension: 'Stories.time',
      dateRange: ['2015-01-01', '2015-12-31'],
      granularity: 'month',
    },
  ],
},
{
  measures: ['Stories.count'],
  timeDimensions: [
    {
      dimension: 'Stories.time',
      dateRange: ['2015-01-01', '2015-12-31'],
      granularity: 'month',
    },
  ],
  filters: [
    {
      member: 'Stores.read',
      operator: 'equals',
      values: ['true'],
    },
  ],
},

// ResultSet.chartPivot({ aliasSeries: ['one', 'two'] }) will return
[
  {
    x: '2015-01-01T00:00:00',
    'one,Stories.count': 27120,
    'two,Stories.count': 8933,
    xValues: ['2015-01-01T00:00:00'],
  },
  {
    x: '2015-02-01T00:00:00',
    'one,Stories.count': 25861,
    'two,Stories.count': 8344,
    xValues: ['2015-02-01T00:00:00'],
  },
  {
    x: '2015-03-01T00:00:00',
    'one,Stories.count': 29661,
    'two,Stories.count': 9023,
    xValues: ['2015-03-01T00:00:00'],
  },
  //...
];
```

### `decompose`

> **decompose**(): *Object*

Can be used when you need access to the methods that can't be used with some query types (eg `compareDateRangeQuery` or `blendingQuery`)

```js theme={"dark"}
resultSet.decompose().forEach((currentResultSet) => {
  console.log(currentResultSet.rawData());
});
```

### `drillDown`

> **drillDown**(**drillDownLocator**: [DrillDownLocator](#drilldownlocator), **pivotConfig?**: [PivotConfig](#pivotconfig)): *[Query](#query-2) | null*

Returns a measure drill down query.

Provided you have a measure with the defined `drillMemebers` on the `Orders` cube

```js theme={"dark"}
measures: {
  count: {
    type: `count`,
    drillMembers: [Orders.status, Users.city, count],
  },
  // ...
}
```

Then you can use the `drillDown` method to see the rows that contribute to that metric

```js theme={"dark"}
resultSet.drillDown(
  {
    xValues,
    yValues,
  },
  // you should pass the `pivotConfig` if you have used it for axes manipulation
  pivotConfig
)
```

the result will be a query with the required filters applied and the dimensions/measures filled out

```js theme={"dark"}
{
  measures: ['Orders.count'],
  dimensions: ['Orders.status', 'Users.city'],
  filters: [
    // dimension and measure filters
  ],
  timeDimensions: [
    //...
  ]
}
```

In case when you want to add `order` or `limit` to the query, you can simply spread it

```js theme={"dark"}
// An example for React
const drillDownResponse = useCubeQuery(
   {
     ...drillDownQuery,
     limit: 30,
     order: {
       'Orders.ts': 'desc'
     }
   },
   {
     skip: !drillDownQuery
   }
 );
```

### `pivot`

> **pivot**(**pivotConfig?**: [PivotConfig](#pivotconfig)): *[PivotRow](#pivotrow)\[]*

Base method for pivoting [ResultSet](#resultset) data.
Most of the times shouldn't be used directly and [`chartPivot`](#chartpivot)
or [`tablePivot`](#tablepivot) should be used instead.

You can find the examples of using the `pivotConfig` [here](#pivotconfig)

```js theme={"dark"}
// For query
{
  measures: ['Stories.count'],
  timeDimensions: [{
    dimension: 'Stories.time',
    dateRange: ['2015-01-01', '2015-03-31'],
    granularity: 'month'
  }]
}

// ResultSet.pivot({ x: ['Stories.time'], y: ['measures'] }) will return
[
  {
    xValues: ["2015-01-01T00:00:00"],
    yValuesArray: [
      [['Stories.count'], 27120]
    ]
  },
  {
    xValues: ["2015-02-01T00:00:00"],
    yValuesArray: [
      [['Stories.count'], 25861]
    ]
  },
  {
    xValues: ["2015-03-01T00:00:00"],
    yValuesArray: [
      [['Stories.count'], 29661]
    ]
  }
]
```

### `query`

> **query**(): *[Query](#query-2)*

### `rawData`

> **rawData**(): *T\[]*

### `serialize`

> **serialize**(): *Object*

Can be used to stash the `ResultSet` in a storage and restored later with [deserialize](#deserialize)

### `series`

> **series**‹**SeriesItem**›(**pivotConfig?**: [PivotConfig](#pivotconfig)): *[Series](#series-2)‹SeriesItem›\[]*

Returns an array of series with key, title and series data.

```js theme={"dark"}
// For the query
{
  measures: ['Stories.count'],
  timeDimensions: [{
    dimension: 'Stories.time',
    dateRange: ['2015-01-01', '2015-12-31'],
    granularity: 'month'
  }]
}

// ResultSet.series() will return
[
  {
    key: 'Stories.count',
    title: 'Stories Count',
    series: [
      { x: '2015-01-01T00:00:00', value: 27120 },
      { x: '2015-02-01T00:00:00', value: 25861 },
      { x: '2015-03-01T00:00:00', value: 29661 },
      //...
    ],
  },
]
```

**Type parameters:**

* **SeriesItem**

### `seriesNames`

> **seriesNames**(**pivotConfig?**: [PivotConfig](#pivotconfig)): *[SeriesNamesColumn](#seriesnamescolumn)\[]*

Returns an array of series objects, containing `key` and `title` parameters.

```js theme={"dark"}
// For query
{
  measures: ['Stories.count'],
  timeDimensions: [{
    dimension: 'Stories.time',
    dateRange: ['2015-01-01', '2015-12-31'],
    granularity: 'month'
  }]
}

// ResultSet.seriesNames() will return
[
  {
    key: 'Stories.count',
    title: 'Stories Count',
    yValues: ['Stories.count'],
  },
]
```

### `tableColumns`

> **tableColumns**(**pivotConfig?**: [PivotConfig](#pivotconfig)): *[TableColumn](#tablecolumn)\[]*

Returns an array of column definitions for `tablePivot`.

For example:

```js theme={"dark"}
// For the query
{
  measures: ['Stories.count'],
  timeDimensions: [{
    dimension: 'Stories.time',
    dateRange: ['2015-01-01', '2015-12-31'],
    granularity: 'month'
  }]
}

// ResultSet.tableColumns() will return
[
  {
    key: 'Stories.time',
    dataIndex: 'Stories.time',
    title: 'Stories Time',
    shortTitle: 'Time',
    type: 'time',
    format: undefined,
  },
  {
    key: 'Stories.count',
    dataIndex: 'Stories.count',
    title: 'Stories Count',
    shortTitle: 'Count',
    type: 'count',
    format: undefined,
  },
  //...
]
```

In case we want to pivot the table axes

```js theme={"dark"}
// Let's take this query as an example
{
  measures: ['Orders.count'],
  dimensions: ['Users.country', 'Users.gender']
}

// and put the dimensions on `y` axis
resultSet.tableColumns({
  x: [],
  y: ['Users.country', 'Users.gender', 'measures']
})
```

then `tableColumns` will group the table head and return

```js theme={"dark"}
{
  key: 'Germany',
  type: 'string',
  title: 'Users Country Germany',
  shortTitle: 'Germany',
  meta: undefined,
  format: undefined,
  children: [
    {
      key: 'male',
      type: 'string',
      title: 'Users Gender male',
      shortTitle: 'male',
      meta: undefined,
      format: undefined,
      children: [
        {
          // ...
          dataIndex: 'Germany.male.Orders.count',
          shortTitle: 'Count',
        },
      ],
    },
    {
      // ...
      shortTitle: 'female',
      children: [
        {
          // ...
          dataIndex: 'Germany.female.Orders.count',
          shortTitle: 'Count',
        },
      ],
    },
  ],
},
// ...
```

### `tablePivot`

> **tablePivot**(**pivotConfig?**: [PivotConfig](#pivotconfig)): *Array‹object›*

Returns normalized query result data prepared for visualization in the table format.

You can find the examples of using the `pivotConfig` [here](#pivotconfig)

For example:

```js theme={"dark"}
// For the query
{
  measures: ['Stories.count'],
  timeDimensions: [{
    dimension: 'Stories.time',
    dateRange: ['2015-01-01', '2015-12-31'],
    granularity: 'month'
  }]
}

// ResultSet.tablePivot() will return
[
  { "Stories.time": "2015-01-01T00:00:00", "Stories.count": 27120 },
  { "Stories.time": "2015-02-01T00:00:00", "Stories.count": 25861 },
  { "Stories.time": "2015-03-01T00:00:00", "Stories.count": 29661 },
  //...
]
```

### `deserialize`

> `static` **deserialize**‹**TData**›(**data**: Object, **options?**: Object): *[ResultSet](#resultset)‹TData›*

```js theme={"dark"}
import { ResultSet } from '@cubejs-client/core';

const resultSet = await cubeApi.load(query);
// You can store the result somewhere
const tmp = resultSet.serialize();

// and restore it later
const resultSet = ResultSet.deserialize(tmp);
```

**Type parameters:**

* **TData**

**Parameters:**

| Name     | Type   | Description                           |
| -------- | ------ | ------------------------------------- |
| data     | Object | the result of [serialize](#serialize) |
| options? | Object | -                                     |

### `getNormalizedPivotConfig`

> `static` **getNormalizedPivotConfig**(**query**: [PivotQuery](#pivotquery), **pivotConfig?**: Partial‹[PivotConfig](#pivotconfig)›): *[PivotConfig](#pivotconfig)*

## `SqlQuery`

### `rawQuery`

> **rawQuery**(): *[SqlData](#sqldata)*

### `sql`

> **sql**(): *string*

## `ITransport`

### `request`

> **request**(**method**: string, **params**: any): () => *Promise‹void›*

## Types

### `Annotation`

| Name       | Type                                |
| ---------- | ----------------------------------- |
| format?    | "currency" \| "percent" \| "number" |
| shortTitle | string                              |
| title      | string                              |
| type       | string                              |

### `CacheMode`

> **CacheMode**: *"stale-if-slow" | "stale-while-revalidate" | "must-revalidate" | "no-cache"*

Cache mode options for query execution. See [cache control][ref-cache-control] for details on available strategies.

### `BinaryFilter`

| Name       | Type                              |
| ---------- | --------------------------------- |
| and?       | [BinaryFilter](#binaryfilter)\[]  |
| dimension? | string                            |
| member?    | string                            |
| operator   | [BinaryOperator](#binaryoperator) |
| or?        | [BinaryFilter](#binaryfilter)\[]  |
| values     | string\[]                         |

### `BinaryOperator`

> **BinaryOperator**: *"equals" | "notEquals" | "contains" | "notContains" | "gt" | "gte" | "lt" | "lte" | "inDateRange" | "notInDateRange" | "beforeDate" | "afterDate"*

### `ChartPivotRow`

| Name    | Type      |
| ------- | --------- |
| x       | string    |
| xValues | string\[] |

### `Column`

| Name   | Type   |
| ------ | ------ |
| key    | string |
| series | \[]    |
| title  | string |

### `CubeApiOptions`

| Name               | Type                                 | Description                                                                                                  |
| ------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| apiUrl             | string                               | URL of your Cube API. By default, in the development environment it is `http://localhost:4000/cubejs-api/v1` |
| credentials?       | "omit" \| "same-origin" \| "include" | -                                                                                                            |
| headers?           | Record‹string, string›               | -                                                                                                            |
| parseDateMeasures? | boolean                              | -                                                                                                            |
| pollInterval?      | number                               | -                                                                                                            |
| transport?         | [ITransport](#itransport)            | Transport implementation to use. [HttpTransport](#httptransport) will be used by default.                    |
| signal?            | AbortSignal                          | AbortSignal to cancel requests                                                                               |

### `CubeSqlOptions`

Extends [`LoadMethodOptions`](#loadmethodoptions) with the options accepted by
[`cubeSql`](#cubesql) and [`cubeSqlStream`](#cubesqlstream).

| Name       | Type     | Optional? | Description                                                                                                                                                                                                                                                                    |
| ---------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `timeout`  | `number` | ✅ Yes     | Query timeout in milliseconds.                                                                                                                                                                                                                                                 |
| `timezone` | `string` | ✅ Yes     | The [time zone][ref-time-zone] for this query in the [TZ Database Name][link-tzdb] format, e.g., `America/Los_Angeles` — same as `query.timezone` in the REST (JSON) API's [`/v1/load`][ref-query-format]. When omitted, the query runs in the deployment's default time zone. |

### `CubeSqlResult`

| Name                 | Type                                                                                  | Description                                                                                                                                                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| schema               | `{ name: string, column_type: string, format?: string }[]`                            | -                                                                                                                                                                                                                                    |
| data                 | `(string \| number \| boolean \| null)[][]`                                           | -                                                                                                                                                                                                                                    |
| lastRefreshTime?     | string                                                                                | -                                                                                                                                                                                                                                    |
| external?            | boolean                                                                               | Whether the result was served from the external (pre-aggregation) store. Only reported when true.                                                                                                                                    |
| usedPreAggregations? | `Record<string, { preAggregationId?: string, lastUpdatedAt?: number, type: string }>` | Pre-aggregations this result was served from, keyed by pre-aggregation table name. Absent when the query hit none, and on deployments older than the field. Entries also carry `targetTableName` in dev mode and for the Playground. |

### `DateRange`

> **DateRange**: *string | \[string, string]*

### `DrillDownLocator`

| Name     | Type      |
| -------- | --------- |
| xValues  | string\[] |
| yValues? | string\[] |

### `Filter`

> **Filter**: *[BinaryFilter](#binaryfilter) | [UnaryFilter](#unaryfilter)*

### `LoadMethodCallback`

> **LoadMethodCallback**: *function*

### `LoadMethodOptions`

| Name               | Type                      | Optional? | Description                                                                                                                                                                                                                                                                                                                                |
| ------------------ | ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cache`            | [`CacheMode`](#cachemode) | ✅ Yes     | Server-side cache policy for query execution. Does not control client-side caching. See [cache control][ref-cache-control] for details on available strategies.                                                                                                                                                                            |
| `castNumerics`     | `boolean`                 | ✅ Yes     | Pass `true` if you'd like all members with the `number` type to be automatically converted to JavaScript `Number` type. Note that this is a potentially unsafe operation since numbers more than [`Number.MAX_SAFE_INTEGER`][link-mdn-max-safe-integer] or less than `Number.MIN_SAFE_INTEGER` can't be represented as JavaScript `Number` |
| `mutexKey`         | `string`                  | ✅ Yes     | Key to store the current request's MUTEX inside the `mutexObj`. MUTEX object is used to reject orphaned queries results when new queries are sent. For example: if two queries are sent with the same `mutexKey` only the last one will return results.                                                                                    |
| `mutexObj`         | `Object`                  | ✅ Yes     | Object to store MUTEX                                                                                                                                                                                                                                                                                                                      |
| `progressCallback` |                           | ✅ Yes     |                                                                                                                                                                                                                                                                                                                                            |
| `subscribe`        | `boolean`                 | ✅ Yes     | Pass `true` to use continuous fetch behavior.                                                                                                                                                                                                                                                                                              |
| `signal`           | `AbortSignal`             | ✅ Yes     | AbortSignal to cancel the request. This allows you to manually abort requests using AbortController.                                                                                                                                                                                                                                       |
| `baseRequestId`    | `string`                  | ✅ Yes     | Base request ID ([`spanId`](https://cube.dev/docs/product/apis-integrations/core-data-apis/rest-api#request-span-annotation)) to be used for the request. If not provided a random request ID will be generated.                                                                                                                           |

### `MetaMethodOptions`

Extends [`LoadMethodOptions`](#loadmethodoptions) with the options accepted by [`meta`](#meta).

| Name        | Type      | Optional? | Description                                                                                                                                                                                                                                          |
| ----------- | --------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onlyViews` | `boolean` | ✅ Yes     | Pass `true` to request views only — the response's `cubes` array then contains only entries whose `type` is `view`. Over HTTP, Cube versions predating this flag ignore it and return the full data model, so don't assume the response is filtered. |

### `LoadResponse`

| Name       | Type                                            |
| ---------- | ----------------------------------------------- |
| pivotQuery | [PivotQuery](#pivotquery)                       |
| queryType  | [QueryType](#querytype)                         |
| results    | [LoadResponseResult](#loadresponseresult)‹T›\[] |

### `LoadResponseResult`

| Name            | Type                                  |
| --------------- | ------------------------------------- |
| annotation      | [QueryAnnotations](#queryannotations) |
| data            | T\[]                                  |
| lastRefreshTime | string                                |
| query           | [Query](#query-2)                     |

### `MemberType`

> **MemberType**: *"measures" | "dimensions" | "segments"*

### `PivotConfig`

Configuration object that contains information about pivot axes and other options.

Let's apply `pivotConfig` and see how it affects the axes

```js theme={"dark"}
// Example query
{
  measures: ['Orders.count'],
  dimensions: ['Users.country', 'Users.gender']
}
```

If we put the `Users.gender` dimension on **y** axis

```js theme={"dark"}
resultSet.tablePivot({
  x: ['Users.country'],
  y: ['Users.gender', 'measures']
})
```

The resulting table will look the following way

| Users Country | male, Orders.count | female, Orders.count |
| ------------- | ------------------ | -------------------- |
| Australia     | 3                  | 27                   |
| Germany       | 10                 | 12                   |
| US            | 5                  | 7                    |

Now let's put the `Users.country` dimension on **y** axis instead

```js theme={"dark"}
resultSet.tablePivot({
  x: ['Users.gender'],
  y: ['Users.country', 'measures'],
});
```

in this case the `Users.country` values will be laid out on **y** or **columns** axis

| Users Gender | Australia, Orders.count | Germany, Orders.count | US, Orders.count |
| ------------ | ----------------------- | --------------------- | ---------------- |
| male         | 3                       | 10                    | 5                |
| female       | 27                      | 12                    | 7                |

It's also possible to put the `measures` on **x** axis. But in either case it should always be the last item of the array.

```js theme={"dark"}
resultSet.tablePivot({
  x: ['Users.gender', 'measures'],
  y: ['Users.country'],
});
```

| Users Gender | measures     | Australia | Germany | US |
| ------------ | ------------ | --------- | ------- | -- |
| male         | Orders.count | 3         | 10      | 5  |
| female       | Orders.count | 27        | 12      | 7  |

| Name              | Type            | Description                                                                                                                                                                                                                               |
| ----------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| aliasSeries?      | string\[]       | Give each series a prefix alias. Should have one entry for each query:measure. See [chartPivot](#chartpivot)                                                                                                                              |
| fillMissingDates? | boolean \| null | **`true` by default.** If set to `true`, missing dates on the time dimensions will be filled with `fillWithValue` or `0` by default for all measures. Note: setting this option to `true` will override any `order` applied to the query. |
| fillWithValue?    | string \| null  | Value to autofill all the missing date's measure.                                                                                                                                                                                         |
| x?                | string\[]       | Dimensions to put on **x** or **rows** axis.                                                                                                                                                                                              |
| y?                | string\[]       | Dimensions to put on **y** or **columns** axis.                                                                                                                                                                                           |

### `PivotQuery`

> **PivotQuery**: *[Query](#query-2) & object*

### `PivotRow`

| Name         | Type                        |
| ------------ | --------------------------- |
| xValues      | Array‹string \| number›     |
| yValuesArray | Array‹\[string\[], number]› |

### `ProgressResponse`

| Name        | Type   |
| ----------- | ------ |
| stage       | string |
| timeElapsed | number |

### `Query`

| Name            | Type                                                                             |
| --------------- | -------------------------------------------------------------------------------- |
| dimensions?     | string\[]                                                                        |
| filters?        | [Filter](#filter)\[]                                                             |
| limit?          | number                                                                           |
| measures?       | string\[]                                                                        |
| offset?         | number                                                                           |
| order?          | [TQueryOrderObject](#tqueryorderobject) \| [TQueryOrderArray](#tqueryorderarray) |
| segments?       | string\[]                                                                        |
| timeDimensions? | [TimeDimension](#timedimension)\[]                                               |
| timezone?       | string                                                                           |
| ungrouped?      | boolean                                                                          |

### `QueryAnnotations`

| Name           | Type                                        |
| -------------- | ------------------------------------------- |
| dimensions     | Record‹string, [Annotation](#annotation-2)› |
| measures       | Record‹string, [Annotation](#annotation-2)› |
| timeDimensions | Record‹string, [Annotation](#annotation-2)› |

### `QueryOrder`

> **QueryOrder**: *"asc" | "desc"*

### `QueryType`

> **QueryType**: *"regularQuery" | "compareDateRangeQuery" | "blendingQuery"*

### `Series`

| Name   | Type   |
| ------ | ------ |
| key    | string |
| series | T\[]   |
| title  | string |

### `SeriesNamesColumn`

| Name    | Type      |
| ------- | --------- |
| key     | string    |
| title   | string    |
| yValues | string\[] |

### `SqlApiResponse`

| Name | Type                |
| ---- | ------------------- |
| sql  | [SqlData](#sqldata) |

### `SqlData`

| Name              | Type                            |
| ----------------- | ------------------------------- |
| aliasNameToMember | Record‹string, string›          |
| cacheKeyQueries   | object                          |
| dataSource        | boolean                         |
| external          | boolean                         |
| sql               | [SqlQueryTuple](#sqlquerytuple) |

### `SqlQueryTuple`

> **SqlQueryTuple**: *\[string, boolean | string | number]*

### `TCubeDimension`

> **TCubeDimension**: *[TCubeMember](#tcubemember) & object*

### `TCubeMeasure`

> **TCubeMeasure**: *[TCubeMember](#tcubemember) & object*

### `TCubeMember`

| Name       | Type                                |
| ---------- | ----------------------------------- |
| name       | string                              |
| shortTitle | string                              |
| title      | string                              |
| isVisible? | boolean                             |
| meta?      | any                                 |
| type       | [TCubeMemberType](#tcubemembertype) |

### `TCubeMemberByType`

> **TCubeMemberByType**: *T extends "measures" ? TCubeMeasure : T extends "dimensions" ? TCubeDimension : T extends "segments" ? TCubeSegment : never*

### `TCubeMemberType`

> **TCubeMemberType**: *"time" | "number" | "string" | "boolean"*

### `TCubeSegment`

> **TCubeSegment**: *Pick‹[TCubeMember](#tcubemember), "name" | "shortTitle" | "title"›*

### `TDefaultHeuristicsOptions`

| Name                | Type                                                  |
| ------------------- | ----------------------------------------------------- |
| meta                | [Meta](#meta-2)                                       |
| sessionGranularity? | [TimeDimensionGranularity](#timedimensiongranularity) |

### `TDryRunResponse`

| Name              | Type                      |
| ----------------- | ------------------------- |
| normalizedQueries | [Query](#query-2)\[]      |
| pivotQuery        | [PivotQuery](#pivotquery) |
| queryOrder        | Array‹object›             |
| queryType         | [QueryType](#querytype)   |

### `TFlatFilter`

| Name       | Type                              |
| ---------- | --------------------------------- |
| dimension? | string                            |
| member?    | string                            |
| operator   | [BinaryOperator](#binaryoperator) |
| values     | string\[]                         |

### `TQueryOrderArray`

> **TQueryOrderArray**: *Array‹\[string, [QueryOrder](#queryorder)]›*

### `TQueryOrderObject`

### `TableColumn`

| Name       | Type                           |
| ---------- | ------------------------------ |
| children?  | [TableColumn](#tablecolumn)\[] |
| dataIndex  | string                         |
| format?    | any                            |
| key        | string                         |
| meta       | any                            |
| shortTitle | string                         |
| title      | string                         |
| type       | string \| number               |

### `TimeDimension`

> **TimeDimension**: *[TimeDimensionComparison](#timedimensioncomparison) | [TimeDimensionRanged](#timedimensionranged)*

### `TimeDimensionBase`

| Name         | Type                                                  |
| ------------ | ----------------------------------------------------- |
| dimension    | string                                                |
| granularity? | [TimeDimensionGranularity](#timedimensiongranularity) |

### `TimeDimensionComparison`

> **TimeDimensionComparison**: *[TimeDimensionBase](#timedimensionbase) & object*

### `TimeDimensionGranularity`

> **TimeDimensionGranularity**: *"second" | "minute" | "hour" | "day" | "week" | "month" | "year"*

### `TimeDimensionRanged`

> **TimeDimensionRanged**: *[TimeDimensionBase](#timedimensionbase) & object*

### `TransportOptions`

| Name          | Type                                 | Description                    |
| ------------- | ------------------------------------ | ------------------------------ |
| apiUrl        | string                               | path to `/cubejs-api/v1`       |
| authorization | string                               | [jwt auth token][ref-security] |
| credentials?  | "omit" \| "same-origin" \| "include" | -                              |
| headers?      | Record‹string, string›               | custom headers                 |
| signal?       | AbortSignal                          | AbortSignal to cancel requests |

### `UnaryFilter`

| Name       | Type                            |
| ---------- | ------------------------------- |
| and?       | [UnaryFilter](#unaryfilter)\[]  |
| dimension? | string                          |
| member?    | string                          |
| operator   | [UnaryOperator](#unaryoperator) |
| or?        | [UnaryFilter](#unaryfilter)\[]  |
| values?    | never                           |

### `UnaryOperator`

> **UnaryOperator**: *"set" | "notSet"*

[link-mdn-max-safe-integer]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER

[ref-query-format]: /reference/core-data-apis/rest-api/query-format

[ref-security]: /docs/data-modeling/access-control

[ref-cache-control]: /reference/core-data-apis/rest-api#cache-control

[ref-sql-api]: /reference/core-data-apis/sql-api

[ref-cubesql-endpoint]: /reference/core-data-apis/rest-api/reference#base_path/v1/cubesql

[ref-time-zone]: /reference/core-data-apis/queries#time-zone

[link-tzdb]: https://en.wikipedia.org/wiki/Tz_database


# `@cubejs-client/ngx`
Source: https://docs.cube.dev/reference/javascript-sdk/reference/cubejs-client-ngx

@cubejs-client/ngx provides Angular Module for easy integration Cube into an Angular app.

## Installation

First, install `@cubejs-client/ngx` using npm or yarn:

```bash theme={"dark"}
npm install --save @cubejs-client/ngx
# or
yarn add @cubejs-client/ngx
```

Now you can add `CubeClientModule` to your **app.module.ts** file:

```typescript theme={"dark"}
import { CubeClientModule } from '@cubejs-client/ngx';
import { environment } from '../../environments/environment';

const cubeOptions = {
  token: environment.CUBE_API_TOKEN,
  options: { apiUrl: environment.CUBE_API_URL }
};

@NgModule({
  declarations: [
    ...
  ],
  imports: [
    ...,
    CubeClientModule.forRoot(cubeOptions)
  ],
  providers: [...],
  bootstrap: [...]
})
export class AppModule { }
```

The `options` object is passed directly to
[`@cubejs-client/core`](/reference/javascript-sdk/reference/cubejs-client-core).

`CubeClientModule` provides `CubeClient`, which you can inject into your
components or services:

```typescript theme={"dark"}
import { CubeClient } from "@cubejs-client/ngx";

export class AppComponent {
  constructor(private cube: CubeClient) {}

  ngOnInit() {
    this.cube
      .load({
        measures: ["some_measure"],
      })
      .subscribe(
        (resultSet) => {
          this.data = resultSet.chartPivot();
        },
        (err) => console.log("HTTP Error", err)
      );
  }
}
```

## API

`CubeClient` provides the same API methods as
[`@cubejs-client/core`](/reference/javascript-sdk/reference/cubejs-client-core#cubeapi). The
difference is that instead of Promise it returns an
[Observable](http://reactivex.io/rxjs/class/es6/Observable.js~Observable.html),
which passes [`resultSet`](/reference/javascript-sdk/reference/cubejs-client-core#resultset) into the
callback function.

Also you can use [RxJS Subject](https://rxjs-dev.firebaseapp.com/guide/subject)
with a query using `watch` method:

```typescript theme={"dark"}
private query;

ngOnInit() {
  this.query = new Subject();
  this.cube.watch(this.query).subscribe(
    resultSet => {
      console.log(resultSet.chartPivot()[0].x);
      console.log(resultSet.seriesNames()[0]);
    },
    err => console.log('HTTP Error', err)
  );
}

button1ClickHandler() {
  this.query.next({ query_1 });
}

button2ClickHandler() {
  this.query.next({ query_2 });
}
```


# `@cubejs-client/react`
Source: https://docs.cube.dev/reference/javascript-sdk/reference/cubejs-client-react

@cubejs-client/react provides React Components for easy Cube integration in a React app.

## `useCubeQuery`

> **useCubeQuery**‹**TData**›(**query**: Query | Query\[], **options?**: [UseCubeQueryOptions](#usecubequeryoptions)): *[UseCubeQueryResult](#usecubequeryresult)‹Query, TData›*

A React hook for executing Cube queries

```js theme={"dark"}
import React from 'react';
import { Table } from 'antd';
import { useCubeQuery }  from '@cubejs-client/react';

export default function App() {
  const { resultSet, isLoading, error, progress } = useCubeQuery({
    measures: ['Orders.count'],
    dimensions: ['Orders.createdAt.month'],
  });

  if (isLoading) {
    return <div>{progress && progress.stage && progress.stage.stage || 'Loading...'}</div>;
  }

  if (error) {
    return <div>{error.toString()}</div>;
  }

  if (!resultSet) {
    return null;
  }

  const dataSource = resultSet.tablePivot();
  const columns = resultSet.tableColumns();

  return <Table columns={columns} dataSource={dataSource} />;
}

```

**Type parameters:**

* **TData**

### `UseCubeQueryOptions`

| Name                     | Type                                                                            | Description                                                                                                                                                                                                                                                                                                                                | Optional? |
| ------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- |
| `cubeApi`                | `CubeApi`                                                                       | A `CubeApi` instance to use. Taken from the context if the param is not passed                                                                                                                                                                                                                                                             | ✅ Yes     |
| `resetResultSetOnChange` | `boolean`                                                                       | When `true` the resultSet will be reset to `null` first                                                                                                                                                                                                                                                                                    | ✅ Yes     |
| `skip`                   | `boolean`                                                                       | Query execution will be skipped when `skip` is set to `true`. You can use this flag to avoid sending incomplete queries.                                                                                                                                                                                                                   | ✅ Yes     |
| `subscribe`              | `boolean`                                                                       | Use continuous fetch behavior. See [Real-Time Data Fetch](/recipes/core-data-api/real-time-data-fetch)                                                                                                                                                                                                                                     | ✅ Yes     |
| `cache`                  | [`CacheMode`](/reference/javascript-sdk/reference/cubejs-client-core#cachemode) | Server-side cache policy for query execution. Does not control client-side caching. See [cache control][ref-cache-control] for details on available strategies.                                                                                                                                                                            | ✅ Yes     |
| `castNumerics`           | `boolean`                                                                       | Pass `true` if you'd like all members with the `number` type to be automatically converted to JavaScript `Number` type. Note that this is a potentially unsafe operation since numbers more than [`Number.MAX_SAFE_INTEGER`][link-mdn-max-safe-integer] or less than `Number.MIN_SAFE_INTEGER` can't be represented as JavaScript `Number` | ✅ Yes     |

### `UseCubeQueryResult`

| Name          | Type                     |
| ------------- | ------------------------ |
| error         | Error \| null            |
| isLoading     | boolean                  |
| previousQuery | TQuery                   |
| progress      | ProgressResponse         |
| resultSet     | ResultSet‹TData› \| null |

## `isQueryPresent`

> **isQueryPresent**(**query**: Query | Query\[]): *boolean*

Checks whether the query is ready

## `QueryBuilder`

> **QueryBuilder** extends **React.Component** ‹[QueryBuilderProps](#querybuilderprops), [QueryBuilderState](#querybuilderstate)›:

`<QueryBuilder />` is used to build interactive analytics query builders. It abstracts state management and API calls to Cube API. It uses render prop technique and doesn’t render anything itself, but calls the render function instead.

**Example**

[Open in CodeSandbox](https://codesandbox.io/s/z6r7qj8wm)

```js theme={"dark"}
import React from 'react';
import ReactDOM from 'react-dom';
import { Layout, Divider, Empty, Select } from 'antd';
import { QueryBuilder } from '@cubejs-client/react';
import cube from '@cubejs-client/core';
import 'antd/dist/antd.css';

import ChartRenderer from './ChartRenderer';

const cubeApi = cube('YOUR-CUBE-API-TOKEN', {
  apiUrl: 'http://localhost:4000/cubejs-api/v1',
});

const App = () => (
  <QueryBuilder
    query={{
      timeDimensions: [
        {
          dimension: 'LineItems.createdAt',
          granularity: 'month',
        },
      ],
    }}
    cubeApi={cubeApi}
    render={({ resultSet, measures, availableMeasures, updateMeasures }) => (
      <Layout.Content style={{ padding: '20px' }}>
        <Select
          mode="multiple"
          style={{ width: '100%' }}
          placeholder="Please select"
          onSelect={(measure) => updateMeasures.add(measure)}
          onDeselect={(measure) => updateMeasures.remove(measure)}
        >
          {availableMeasures.map((measure) => (
            <Select.Option key={measure.name} value={measure}>
              {measure.title}
            </Select.Option>
          ))}
        </Select>
        <Divider />
        {measures.length > 0 ? (
          <ChartRenderer resultSet={resultSet} />
        ) : (
          <Empty description="Select measure or dimension to get started" />
        )}
      </Layout.Content>
    )}
  />
);

const rootElement = document.getElementById("root");
ReactDOM.render(<App />, rootElement);
```

### `QueryBuilderProps`

| Name                   | Type                                                                                              | Description                                                                                                                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| cubeApi                | CubeApi                                                                                           | `CubeApi` instance to use                                                                                                                                                                                    |
| defaultChartType?      | [ChartType](#charttype)                                                                           | -                                                                                                                                                                                                            |
| disableHeuristics?     | boolean                                                                                           | Defaults to `false`. This means that the default heuristics will be applied. For example: when the query is empty and you select a measure that has a default time dimension it will be pushed to the query. |
| query?                 | Query                                                                                             | Default query                                                                                                                                                                                                |
| render                 | (**renderProps**: [QueryBuilderRenderProps](#querybuilderrenderprops)) => *React.ReactNode*       | -                                                                                                                                                                                                            |
| setQuery?              | (**query**: Query) => *void*                                                                      | Called by the `QueryBuilder` when the query state has changed. Use it when state is maintained outside of the `QueryBuilder` component.                                                                      |
| setVizState?           | (**vizState**: [VizState](#vizstate)) => *void*                                                   | -                                                                                                                                                                                                            |
| stateChangeHeuristics? | (**state**: [QueryBuilderState](#querybuilderstate)) => *[QueryBuilderState](#querybuilderstate)* | A function that accepts the `newState` just before it's applied. You can use it to override the **defaultHeuristics** or to tweak the query or the vizState in any way.                                      |
| vizState?              | [VizState](#vizstate)                                                                             | -                                                                                                                                                                                                            |
| wrapWithQueryRenderer? | boolean                                                                                           | Defaults to `true`. Use QueryRenderer to render. Set this to `false` to use your own QueryRenderer.                                                                                                          |

### `QueryBuilderRenderProps`

| Name                    | Type                            | Description                                                                             |
| ----------------------- | ------------------------------- | --------------------------------------------------------------------------------------- |
| availableDimensions     | TCubeDimension\[]               | An array of available dimensions to select. They are loaded via the API from Cube.      |
| availableMeasures       | TCubeMeasure\[]                 | An array of available measures to select. They are loaded via the API from Cube.        |
| availableSegments       | TCubeMember\[]                  | An array of available segments to select. They are loaded via the API from Cube.        |
| availableTimeDimensions | TCubeDimension\[]               | An array of available time dimensions to select. They are loaded via the API from Cube. |
| dimensions              | string\[]                       | -                                                                                       |
| error?                  | Error \| null                   | -                                                                                       |
| isQueryPresent          | boolean                         | Indicates whether the query is ready to be displayed or not                             |
| loadingState?           | [TLoadingState](#tloadingstate) | -                                                                                       |
| measures                | string\[]                       | -                                                                                       |
| resultSet?              | ResultSet \| null               | -                                                                                       |
| segments                | string\[]                       | -                                                                                       |
| timeDimensions          | Filter\[]                       | -                                                                                       |
| updateDimensions        | [MemberUpdater](#memberupdater) | -                                                                                       |
| updateMeasures          | [MemberUpdater](#memberupdater) | -                                                                                       |
| updateQuery             | (**query**: Query) => *void*    | Used for partial of full query update                                                   |
| updateSegments          | [MemberUpdater](#memberupdater) | -                                                                                       |
| updateTimeDimensions    | [MemberUpdater](#memberupdater) | -                                                                                       |

### `QueryBuilderState`

> **QueryBuilderState**: *[VizState](#vizstate) & object*

## `QueryRenderer`

> **QueryRenderer** extends **React.Component** ‹[QueryRendererProps](#queryrendererprops)›:

`<QueryRenderer />` a react component that accepts a query, fetches the given query, and uses the render prop to render the resulting data

### `QueryRendererProps`

| Name                     | Type                                                                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------ | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cache?                   | [`CacheMode`](/reference/javascript-sdk/reference/cubejs-client-core#cachemode)    | Server-side cache policy for query execution. Does not control client-side caching. See [cache control][ref-cache-control] for details on available strategies.                                                                                                                                                                                                                                                             |
| cubeApi                  | CubeApi                                                                            | `CubeApi` instance to use                                                                                                                                                                                                                                                                                                                                                                                                   |
| loadSql?                 | "only" \| boolean                                                                  | Indicates whether the SQL Code generated by Cube should be requested. See [rest-api#sql](/reference/core-data-apis/rest-api/reference#base_path/v1/sql). When set to `only` then only the request to [/v1/sql](/reference/core-data-apis/rest-api/reference#base_path/v1/sql) will be performed. When set to `true` the sql request will be performed along with the query request. Will not be performed if set to `false` |
| queries?                 | object                                                                             | -                                                                                                                                                                                                                                                                                                                                                                                                                           |
| query                    | Query                                                                              | Analytic query. [Learn more about it's format](/reference/core-data-apis/rest-api/query-format)                                                                                                                                                                                                                                                                                                                             |
| render                   | (**renderProps**: [QueryRendererRenderProps](#queryrendererrenderprops)) => *void* | Output of this function will be rendered by the `QueryRenderer`                                                                                                                                                                                                                                                                                                                                                             |
| resetResultSetOnChange?  | boolean                                                                            | When `true` the **resultSet** will be reset to `null` first on every state change                                                                                                                                                                                                                                                                                                                                           |
| updateOnlyOnStateChange? | boolean                                                                            | -                                                                                                                                                                                                                                                                                                                                                                                                                           |

### `QueryRendererRenderProps`

| Name         | Type                            |
| ------------ | ------------------------------- |
| error        | Error \| null                   |
| loadingState | [TLoadingState](#tloadingstate) |
| resultSet    | ResultSet \| null               |

## `CubeProvider`

> **CubeProvider**: *React.FC‹[CubeProviderProps](#cubeproviderprops)›*

Cube context provider

```js theme={"dark"}
import React from 'react';
import cube from '@cubejs-client/core';
import { CubeProvider } from '@cubejs-client/react';

const API_URL = 'https://harsh-eel.aws-us-east-2.cubecloudapp.dev';
const CUBE_TOKEN =
  'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.* eyJpYXQiOjE1OTE3MDcxNDgsImV4cCI6MTU5NDI5OTE0OH0.* n5jGLQJ14igg6_Hri_Autx9qOIzVqp4oYxmX27V-4T4';

const cubeApi = cube(CUBE_TOKEN, {
  apiUrl: `${API_URL}/cubejs-api/v1`,
});

export default function App() {
  return (
    <CubeProvider cubeApi={cubeApi}>
      //...
    </CubeProvider>
  )
}
```

## `CubeContext`

> **CubeContext**: *Context‹[CubeContextProps](#cubecontextprops)›*

In case when you need direct access to `cubeApi` you can use `CubeContext` anywhere in your app

```js theme={"dark"}
import React from 'react';
import { CubeContext } from '@cubejs-client/react';

export default function DisplayComponent() {
  const { cubeApi } = React.useContext(CubeContext);
  const [rawResults, setRawResults] = React.useState([]);
  const query = {
    ...
  };

  React.useEffect(() => {
    cubeApi.load(query).then((resultSet) => {
      setRawResults(resultSet.rawData());
    });
  }, [query]);

  return (
    <>
      {rawResults.map(row => (
        ...
      ))}
    </>
  )
}
```

## Types

### `ChartType`

> **ChartType**: *"line" | "bar" | "table" | "area"*

### `CubeContextProps`

| Name      | Type                  | Optional? |
| --------- | --------------------- | --------- |
| `cubeApi` | `CubeApi`             | ❌ No      |
| `options` | `CubeProviderOptions` | ✅ Yes     |

### `CubeProviderProps`

| Name       | Type                  | Optional? |
| ---------- | --------------------- | --------- |
| `cubeApi`  | `CubeApi`             | ❌ No      |
| `children` | `React.ReactNode`     | ❌ No      |
| `options`  | `CubeProviderOptions` | ✅ Yes     |

### `CubeProviderOptions`

| Name           | Type      | Optional? |
| -------------- | --------- | --------- |
| `castNumerics` | `boolean` | ✅ Yes     |

### `MemberUpdater`

You can use the following methods for member manipulaltion

```js theme={"dark"}
<QueryBuilder
  // ...
  cubeApi={cubeApi}
  render={({
    // ...
    availableMeasures,
    updateMeasures,
  }) => {
    return (
      // ...
      <Select
        mode="multiple"
        placeholder="Please select"
        onSelect={(measure) => updateMeasures.add(measure)}
        onDeselect={(measure) => updateMeasures.remove(measure)}
      >
        {availableMeasures.map((measure) => (
          <Select.Option key={measure.name} value={measure}>
            {measure.title}
          </Select.Option>
        ))}
      </Select>
    );
  }}
/>
```

NOTE: if you need to add or remove more than one member at a time you should use `updateQuery` prop of [QueryBuilderRenderProps](#querybuilderrenderprops)

```js theme={"dark"}
<QueryBuilder
  // ...
  cubeApi={cubeApi}
  render={({
    // ...
    measures,
    updateMeasures,
    updateQuery,
  }) => {
    // ...
    return (
      <>
        // WRONG: This code will not work properly
        <button
          onClick={() =>
            measures.forEach((measure) => updateMeasures.remove(measure))
          }
        >
          Remove all
        </button>

        // CORRECT: Using `updateQuery` for removing all measures
        <button
          onClick={() =>
            updateQuery({
              measures: [],
            })
          }
        >
          Remove all
        </button>
      </>
    );
  }}
/>
```

| Name   | Type                                                           |
| ------ | -------------------------------------------------------------- |
| add    | (**member**: MemberType) => *void*                             |
| remove | (**member**: MemberType) => *void*                             |
| update | (**member**: MemberType, **updateWith**: MemberType) => *void* |

### `TLoadingState`

| Name      | Type    |
| --------- | ------- |
| isLoading | boolean |

### `VizState`

| Name                       | Type                    |
| -------------------------- | ----------------------- |
| chartType?                 | [ChartType](#charttype) |
| pivotConfig?               | PivotConfig             |
| shouldApplyHeuristicOrder? | boolean                 |

[link-mdn-max-safe-integer]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER

[ref-cache-control]: /reference/core-data-apis/rest-api#cache-control


# `@cubejs-client/vue3`
Source: https://docs.cube.dev/reference/javascript-sdk/reference/cubejs-client-vue

@cubejs-client/vue3 provides Vue Components to easily integrate Cube within a Vue.js app.

## QueryBuilder

`<QueryBuilder />` is used to build interactive analytics query builders. It
abstracts state management and API calls to Cube Backend. It uses scoped slot
props technique.

### Props

| Name                   | Type                                                                                              | Description                                                                                                                                                                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cubeApi                | [`CubeApi`](/reference/javascript-sdk/reference/cubejs-client-core#cubeapi)                       | `CubeApi` instance to use                                                                                                                                                                                                         |
| initialChartType?      | [ChartType](#charttype)                                                                           | The type of chart to display initially. Default is `line`.                                                                                                                                                                        |
| disableHeuristics?     | boolean                                                                                           | Defaults to `false`. This means that the default heuristics will be applied. For example: when the query is empty and you select a measure that has a default time dimension it will be pushed to the query.                      |
| query?                 | Query                                                                                             | Query parameters ([learn more about the format](/reference/core-data-apis/rest-api/query-format)). This property is reactive - if you change the object here, the internal query values will be overwritten. This is not two-way. |
| stateChangeHeuristics? | (**state**: [QueryBuilderState](#querybuilderstate)) => *[QueryBuilderState](#querybuilderstate)* | A function that accepts the `newState` just before it's applied. You can use it to override the **defaultHeuristics** or to tweak the query or the vizState in any way.                                                           |
| initialVizState?       | [VizState](#vizstate)                                                                             | -                                                                                                                                                                                                                                 |
| wrapWithQueryRenderer? | boolean                                                                                           | Defaults to `true`. Use QueryRenderer to render. Set this to `false` to use your own QueryRenderer.                                                                                                                               |

### Slots

#### Default Slot

##### Slot Props

* `resultSet`: A `resultSet` is an object containing data obtained from the
  query. [`ResultSet`](/reference/javascript-sdk/reference/cubejs-client-core#resultset) object
  provides a convenient interface for data manipulation.

#### Empty Slot

This slot functions as an empty/loading state; when the query is loading or
empty, you can show something in the meantime.

#### Error Slot

This slot will be rendered if any error happens while the query is loading or
rendering.

##### Slot Props

* `error`: the error.
* `sqlQuery`: the attempted query.

#### Builder Slot

* `measures`, `dimensions`, `segments`, `timeDimensions`, `filters` - arrays
  containing the selected query builder members.
* `availableMeasures`, `availableDimensions`, `availableTimeDimensions`,
  `availableSegments` - arrays containing available members to select. They are
  loaded via API from Cube Backend.
* `addMeasures`, `addDimensions`, `addSegments`, `addTimeDimensions` - functions
  to control the adding of new members to query builder.
* `removeMeasures`, `removeDimensions`, `removeSegments`,
  `removeTimeDimensions` - functions to control the removing of members to query
  builder.
* `setMeasures`, `setDimensions`, `setSegments`, `setTimeDimensions` - functions
  to control the setting of members to query builder.
* `updateMeasures`, `updateDimensions`, `updateSegments`,
  `updateTimeDimensions` - functions to control the updating of members to query
  builder.
* `chartType` - string containing currently selected chart type.
* `updateChartType` - function-setter for chart type.
* `isQueryPresent` - bool indicating whether is query ready to be displayed or
  not.
* `query` - current query, based on selected members.
* `setLimit`, `removeLimit` - functions to control the number of results
  returned.
* `setOffset`, `removeOffset` - functions to control the number of rows skipped
  before results returned. Use with limit to control pagination.

### Example

<a href="https://codesandbox.io/s/vue-js-query-builder-with-vue-js-0ydws">
  Open in CodeSandbox
</a>

```html theme={"dark"}
<template>
  <query-builder :cube-api="cubeApi" :query="query">
    <template #builder="{ measures, setMeasures, availableMeasures }">
      <multiselect
        placeholder="Please Select"
        label="Title"
        track-by="name"
        multiple
        :customLabel="customLabel"
        :value="measures"
        :options="availableMeasures"
        @input="(...args) => set(setMeasures, ...args)"
      />
    </template>

    <template #default="{ resultSet }">
      <chart-renderer v-if="resultSet" :result-set="resultSet" />
    </template>

    <template #empty>Loading...</template>
  </query-builder>
</template>

<script>
  import cube from "@cubejs-client/core";
  import Multiselect from "vue-multiselect";
  import { QueryBuilder } from "@cubejs-client/vue";
  import ChartRenderer from "./ChartRenderer.vue";

  const API_URL =
    "https://awesome-ecom.gcp-us-central1.cubecloudapp.dev/cubejs-api/v1";
  const CUBE_TOKEN =
    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1OTQ2NjY4OTR9.0fdi5cuDZ2t3OSrPOMoc3B1_pwhnWj4ZmM3FHEX7Aus";

  const cubeApi = cube(CUBE_TOKEN, { apiUrl: API_URL });

  export default {
    name: "QueryBuilderExample",
    components: {
      Multiselect,
      QueryBuilder,
      ChartRenderer,
    },
    data() {
      const query = {
        measures: [],
        timeDimensions: [
          {
            dimension: "LineItems.createdAt",
            granularity: "month",
          },
        ],
      };

      return {
        cubeApi,
        selected: undefined,
        query,
      };
    },
    methods: {
      customLabel(a) {
        return a.title;
      },
      set(setMeasures, value) {
        setMeasures(value.map((e) => e.name));
      },
    },
  };
</script>
```

## QueryRenderer

`<QueryRenderer />` Vue component takes a query, fetches the given query, and
uses the slot scoped props to render the resulting data.

### Props

| Name     | Type              | Description                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cubeApi  | CubeApi           | `CubeApi` instance to use                                                                                                                                                                                                                                                                                                                                                                                                   |
| loadSql? | "only" \| boolean | Indicates whether the generated by Cube SQL Code should be requested. See [rest-api#sql](/reference/core-data-apis/rest-api/reference#base_path/v1/sql). When set to `only` then only the request to [/v1/sql](/reference/core-data-apis/rest-api/reference#base_path/v1/sql) will be performed. When set to `true` the sql request will be performed along with the query request. Will not be performed if set to `false` |
| queries? | object            | -                                                                                                                                                                                                                                                                                                                                                                                                                           |
| query    | Query             | Analytic query. [Learn more about it's format](/reference/core-data-apis/rest-api/query-format)                                                                                                                                                                                                                                                                                                                             |

### Slots

#### Default Slot

##### Slot Props

* `resultSet`: A `resultSet` is an object containing data obtained from the
  query. [`ResultSet`](/reference/javascript-sdk/reference/cubejs-client-core#resultset) object
  provides a convenient interface for data manipulation.

#### Empty Slot

This slot functions as an empty/loading state; when the query is loading or
empty, you can show something in the meantime.

#### Error Slot

This slot will be rendered if any error happens while the query is loading or
rendering.

##### Slot Props

* `error`: the error.
* `sqlQuery`: the attempted query.

### Example

```html theme={"dark"}
<template>
  <query-renderer :cube-api="cubeApi" :query="query" v-if="cubeApi">
    <template #default="{ resultSet }"> </template>

    <template #empty> Loading... </template>
  </query-renderer>
</template>

<script>
  import cube from "@cubejs-client/core";
  import { QueryRenderer } from "@cubejs-client/vue";

  const cubeApi = cube("YOUR-CUBE-API-TOKEN", {
    apiUrl: "http://localhost:4000/cubejs-api/v1",
  });

  export default {
    name: "QueryRendererExample",
    components: {
      QueryRenderer,
    },
    data() {
      const query = {
        measures: ["LineItems.count", "LineItems.quantity", "Orders.count"],
        timeDimensions: [
          {
            dimension: "LineItems.createdAt",
            granularity: "month",
          },
        ],
      };

      return {
        cubeApi,
        query,
      };
    },
  };
</script>
<style src="vue-multiselect/dist/vue-multiselect.min.css"></style>

<style scoped>
  h3 {
    margin: 40px 0 0;
  }
  ul {
    list-style-type: none;
    padding: 0;
  }
  li {
    display: inline-block;
    margin: 0 10px;
  }
  a {
    color: #42b983;
  }
</style>
```

## Types

### ChartType

> **ChartType**: *"line" | "bar" | "table" | "area" | "number" | "pie"*

### QueryBuilderState

| Name       | Type                                                                      |
| ---------- | ------------------------------------------------------------------------- |
| query      | [`Query`](/reference/javascript-sdk/reference/cubejs-client-core#query-2) |
| chartType? | [ChartType](#charttype)                                                   |

### VizState

| Name                       | Type                                                                                |
| -------------------------- | ----------------------------------------------------------------------------------- |
| chartType?                 | [ChartType](#charttype)                                                             |
| pivotConfig?               | [`PivotConfig`](/reference/javascript-sdk/reference/cubejs-client-core#pivotconfig) |
| shouldApplyHeuristicOrder? | boolean                                                                             |


# `@cubejs-client/ws-transport`
Source: https://docs.cube.dev/reference/javascript-sdk/reference/cubejs-client-ws-transport

WebSocket transport for Cube client

## `WebSocketTransport`

### constructor

> **new WebSocketTransport**(**\_\_namedParameters**: object): *[WebSocketTransport](#websockettransport)*

### `apiUrl`

> **apiUrl**: *string*

### `hearBeatInterval`

> **hearBeatInterval**: *number*

### `messageCounter`

> **messageCounter**: *number*

### `messageIdToSubscription`

> **messageIdToSubscription**: *Record‹number, [Subscription](#subscription)›*

### `messageQueue`

> **messageQueue**: *[Message](#message)\[]*

### `token`

> **token**: *string*

### `ws`

> **ws**: *any*

### `authorization`

### `initSocket`

> **initSocket**(): *any*

### `request`

> **request**(**method**: string, **\_\_namedParameters**: object): *object*

### `sendMessage`

> `protected` **sendMessage**(**message**: any): *void*

## `WebSocketTransportResult`

### constructor

> **new WebSocketTransportResult**(**\_\_namedParameters**: object): *[WebSocketTransportResult](#result)*

### `result`

> **result**: *unknown*

### `status`

> **status**: *unknown*

### `json`

> **json**(): *Promise‹unknown›*

## Types

### `Message`

| Name      | Type   |
| --------- | ------ |
| messageId | number |
| method    | string |
| params    | string |
| requestId | any    |

### `Subscription`

| Name     | Type                                                        |
| -------- | ----------------------------------------------------------- |
| callback | (**result**: [WebSocketTransportResult](#result)) => *void* |
| message  | [Message](#message)                                         |

### `WebSocketTransportOptions`

| Name               | Type   |
| ------------------ | ------ |
| apiUrl             | string |
| authorization      | string |
| hearBeatInterval?  | number |
| heartBeatInterval? | number |


# Vue
Source: https://docs.cube.dev/reference/javascript-sdk/vue

Cube is visualization-agnostic, so you can build any user interface for your application.

You can directly query Cube using the
JSON [query format](/reference/core-data-apis/rest-api/query-format) via the [REST (JSON) API](/reference/core-data-apis/rest-api/reference)
or
[WebSockets](/recipes/core-data-api/real-time-data-fetch)
and visualize analytical data with tools of your choice. However, it's much
easier to use the Cube JavaScript client and bindings for popular frameworks
such as React, Angular, and Vue.

The client has methods to communicate with Cube API Gateway and retrieve and
process data. It is designed to work with existing charting libraries including
Chart.js, D3.js, and more.

## Cube JavaScript Client

The client provides methods to solve common tasks:

**Abstract from the transport and query data.** You can
[fetch data](/reference/javascript-sdk/reference/cubejs-client-core#load) from Cube Backend or
subscribe to
[real-time updates](/recipes/core-data-api/real-time-data-fetch)
regardless of the protocol, be it HTTP or WebSockets.

**Transform data for visualization.** You can
[pivot](/reference/javascript-sdk/reference/cubejs-client-core#pivot) the result set to display
as a [chart](/reference/javascript-sdk/reference/cubejs-client-core#chartpivot) or as a
[table](/reference/javascript-sdk/reference/cubejs-client-core#tablepivot), split into
[series](/reference/javascript-sdk/reference/cubejs-client-core#series) or
[table columns](/reference/javascript-sdk/reference/cubejs-client-core#tablecolumns).

**Simplify work with complex query types.** You can build
[drill down](/reference/javascript-sdk/reference/cubejs-client-core#drilldown) queries and
[decompose](/reference/javascript-sdk/reference/cubejs-client-core#decompose) the results of
[compare date range queries][ref-compare-date-range]
or [data blending](/docs/data-modeling/concepts/data-blending) queries.

[Learn more](/reference/javascript-sdk/reference/cubejs-client-core) in the documentation for
the `@cubejs-client/core` package.

## Cube Vue Package

The package provides convenient tools to work with Cube in Vue:

**Components.** You can use
[`QueryBuilder`](/reference/javascript-sdk/reference/cubejs-client-vue#querybuilder) and
[`QueryRenderer`](/reference/javascript-sdk/reference/cubejs-client-vue#queryrenderer) components
to abstract state management and API calls from your rendering code.

## Example Usage

Here are the typical steps to query and visualize analytical data in Vue:

* **Import `@cubejs-client/core` and `@cubejs-client/vue3` packages.** These
  packages provide all the necessary methods and convenient Vue tools.
* **Create an instance of Cube JavaScript Client.** The client is initialized
  with Cube API URL. In development mode, the default URL is
  [http://localhost:4000/cubejs-api/v1](http://localhost:4000/cubejs-api/v1).
  The client is also initialized with an [API token](/docs/data-modeling/access-control), but it
  takes effect only in [production](/cube-core/running-in-production): with
  `NODE_ENV` unset the API accepts requests with no token, and development mode
  [bypasses authentication](/reference/configuration/environment-variables#cubejs_dev_mode)
  outright, so both are intended for local development machines only.
* **Query data from Cube Backend.** Use
  [`QueryBuilder`](/reference/javascript-sdk/reference/cubejs-client-vue#querybuilder) or
  [`QueryRenderer`](/reference/javascript-sdk/reference/cubejs-client-vue#queryrenderer) and
  their props to execute a query and transform the result set. See
  [Query Format](/reference/core-data-apis/rest-api/query-format) for details.
* **Transform data for visualization.** Use
  [`QueryBuilder`](/reference/javascript-sdk/reference/cubejs-client-vue#querybuilder) and
  [`QueryRenderer`](/reference/javascript-sdk/reference/cubejs-client-vue#queryrenderer) slots
  props to transform the result set. Furthermore, the result set has convenient
  methods, such as `series` and `chartPivot`, to prepare data for charting.
* **Visualize the data.** Use tools of your choice to draw charts and create
  visualizations.

See an example of using Cube with Vue and Chart.js library. Note that you can
always use a different charting library that suits your needs:

<iframe />

## Getting Started

You can install Cube JavaScript Client and the Vue package with npm or Yarn:

```bash theme={"dark"}
# npm
npm install --save @cubejs-client/core @cubejs-client/vue3

# Yarn
yarn add @cubejs-client/core @cubejs-client/vue3
```

Now you can build your application from scratch or connect to one of our
[supported data visualization tools](/admin/connect-to-data/visualization-tools).

[ref-compare-date-range]: /reference/core-data-apis/queries#compare-date-range-query


# Integration with Apache Airflow
Source: https://docs.cube.dev/reference/orchestration-api/airflow

Pair Airflow (including Astro) with Cube using `airflow-provider-cube` operators for loads, pre-aggregations, and orchestration triggers.

[Apache Airflow][airflow] is a popular open-source workflow scheduler commonly
used for data orchestration. [Astro][astro] is a fully managed service for
Airflow by [Astronomer][astro].

This guide demonstrates how to setup Cube and Airflow to work together so that
Airflow can push changes from upstream data sources to Cube via the
[Orchestration API][ref-orchestration-api].

## Tasks

In Airflow, pipelines are represented by directed acyclic graphs (DAGs), Python
function decorated with a `@dag` decorator. DAGs include calls to tasks,
implemented as instances of the `Operator` class. Operators can perform various
tasks: poll for some precondition, perform extract-load-transform (ETL), or
trigger external systems like Cube.

Integration between Cube and Airflow is enabled by the
[`airflow-provider-cube`][github-airflow-provider-cube] package that provides
the following operators.

### CubeQueryOperator

`CubeQueryOperator` is used to query Cube via the
[`/v1/load`][ref-load-endpoint] endpoint of the [REST (JSON) API][ref-rest-api].

It supports the following options:

| Option         | Type     | Default        | Description                              |
| -------------- | -------- | -------------- | ---------------------------------------- |
| `cube_conn_id` | `string` | `cube_default` | Airflow connection name.                 |
| `headers`      | `dict`   |                | HTTP headers to be added to the request. |
| `query`        | `dict`   |                | Cube query object.                       |
| `timeout`      | `int`    | 30             | Response wait timeout in seconds.        |
| `wait`         | `int`    | 10             | Interval between API calls in seconds.   |

### CubeBuildOperator

`CubeBuildOperator` is used to trigger pre-aggregation builds and check their
status via the [`/v1/pre-aggregations/jobs`][ref-ref-jobs-endpoint] endpoint of
the [Orchestration API][ref-orchestration-api].

It supports the following options:

| Option         | Type     | Default        | Description                                                    |
| -------------- | -------- | -------------- | -------------------------------------------------------------- |
| `cube_conn_id` | `string` | `cube_default` | Airflow connection name.                                       |
| `headers`      | `dict`   |                | HTTP headers to be added to the request.                       |
| `selector`     | `dict`   |                | [`/v1/pre-aggregations/jobs`][ref-ref-jobs-endpoint] selector. |
| `complete`     | `bool`   | `False`        | Whether a task should wait for builds to complete or not.      |
| `wait`         | `int`    | 10             | Interval between API calls in seconds.                         |

## Installation

Install [Astro CLI installed][astro-cli].

Create a new directory and [initialize][astro-cli-dev-init] a new Astro project:

```bash theme={"dark"}
mkdir cube-astro
cd cube-astro
astro dev init
```

Add the integration package to `requirements.txt`:

```bash theme={"dark"}
echo "airflow-provider-cube" >> ./requirements.txt
```

## Configuration

### Connection

Create an Airflow connection via the web console or by adding the following
contents to the `airflow_settings.yaml` file:

```yaml theme={"dark"}
airflow:
  connections:
    - conn_id: cube_default
      conn_type: generic
      conn_host: https://awesome-ecom.gcp-us-central1.cubecloudapp.dev
      conn_schema:
      conn_login:
      conn_password: SECRET
      conn_port:
      conn_extra:
        security_context: {}
```

Let's break the options down:

* By default, Cube operators use `cube_default` as an Airflow connection name.
* The connection shoud be of the `generic` type.
* `conn_host` should be set to the URL of your Cube deployment.
* `conn_password` should be set to the value of the [`CUBEJS_API_SECRET`](/reference/configuration/environment-variables#cubejs_api_secret)
  environment variable.
* `conn_extra` should contain a security context (as `security_context`) that
  will be sent with API requests.

### DAGs

Create a new DAG named `cube_query.py` in the `dags` subdirectory with the
following contents. As you can see, the `CubeQueryOperator` accepts a Cube query
via the `query` option.

```python theme={"dark"}
from typing import Any
from pendulum import datetime
from airflow.decorators import dag, task
from cube_provider.operators.cube import CubeQueryOperator

@dag(
  start_date=datetime(2023, 6, 1),
  schedule='*/1 * * * *',
  max_active_runs=1,
  concurrency=1,
  default_args={"retries": 1, "cube_conn_id": "cube_default"},
  tags=["cube"],
)
def cube_query_workflow():
  query_op = CubeQueryOperator(
    task_id="query_op",
    query={
      "measures": ["Orders.count"],
      "dimensions": ["Orders.status"]
    }
  )

  @task()
  def print_op(data: Any):
    print(f"Result: {data}")

  print_op(query_op.output)

cube_query_workflow()
```

Create a new DAG named `cube_build.py` in the `dags` subdirectory with the
following contents. As you can see, the `CubeBuildOperator` accepts a
pre-aggregation selector via the `selector` option.

```python theme={"dark"}
from typing import Any
from pendulum import datetime
from airflow.decorators import dag, task
from cube_provider.operators.cube import CubeBuildOperator

@dag(
  start_date=datetime(2023, 6, 1),
  schedule='*/1 * * * *',
  max_active_runs=1,
  concurrency=1,
  default_args={"retries": 1, "cube_conn_id": "cube_default"},
  tags=["cube"],
)
def cube_build_workflow():
  build_op = CubeBuildOperator(
      task_id="build_op",
      selector={
        "contexts": [
          {"securityContext": {}}
        ],
        "timezones": ["UTC"]
      },
      complete=True,
      wait=10,
  )

  @task()
  def print_op(data: Any):
    print(f"Result: {data}")

  print_op(build_op.output)

cube_build_workflow()
```

Pay attention to the `complete` option. When it's set to `True`, the operator
will wait for pre-aggregation builds to complete before allowing downstream
tasks to run.

## Running workflows

Now, you can run these DAGs:

```bash theme={"dark"}
astro run cube_query_workflow
astro run cube_build_workflow
```

Alternatively, you can run Airflow and navigate to the web console at
[`localhost:8080`](http://localhost:8080) (use `admin`/`admin` to authenticate):

```bash theme={"dark"}
astro dev start
```

[airflow]: https://airflow.apache.org

[astro]: https://www.astronomer.io

[astro-cli]: https://docs.astronomer.io/astro/cli/overview

[astro-cli-dev-init]: https://docs.astronomer.io/astro/cli/astro-dev-init

[github-airflow-provider-cube]: https://github.com/cube-js/airflow-provider-cube/

[ref-load-endpoint]: /reference/core-data-apis/rest-api/reference#v1load

[ref-ref-jobs-endpoint]: /reference/core-data-apis/rest-api/reference#base_path/v1/pre-aggregations/jobs

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-orchestration-api]: /reference/orchestration-api


# Integration with Dagster
Source: https://docs.cube.dev/reference/orchestration-api/dagster

Dagster is a popular open-source data pipeline orchestrator. Dagster Cloud is a fully managed service for Dagster.

[Dagster][dagster] is a popular open-source data pipeline orchestrator. [Dagster
Cloud][dagster-cloud] is a fully managed service for Dagster.

This guide demonstrates how to setup Cube and Dagster to work together so that
Dagster can push changes from upstream data sources to Cube via the
[Orchestration API][ref-orchestration-api].

## Resources

In Dagster, each workflow is represented by jobs, Python functions decorated
with a `@job` decorator. Jobs include calls to ops, Python functions decorated
with an `@op` decorator. Ops represent distinct pieces of work executed within a
job. They can perform various jobs: poll for some precondition, perform
extract-load-transform (ETL), or trigger external systems like Cube.

Integration between Cube and Dagster is enabled by the
[`dagster_cube`][github-dagster-cube] package.

<Info>
  Cube and Dagster integration package was originally contributed by
  [Olivier Dupuis](https://github.com/olivierdupuis), founder of
  [discursus.io](https://www.discursus.io), for which we're very grateful.
</Info>

The package provides the `CubeResource` class:

* For querying Cube via the [`/v1/load`][ref-load-endpoint] endpoint of the
  [REST (JSON) API][ref-rest-api].
* For triggering pre-aggregation builds via the
  [`/v1/pre-aggregations/jobs`][ref-ref-jobs-endpoint] endpoint of the
  [Orchestration API][ref-orchestration-api].

Please refer to the [package documentation][github-dagster-cube-docs] for
details and options reference.

## Installation

Install [Dagster][dagster-docs-install].

Create a new directory:

```bash theme={"dark"}
mkdir cube-dagster
cd cube-dagster
```

Install the integration package:

```bash theme={"dark"}
pip install dagster_cube
```

## Configuration

Create a new file named `cube.py` with the following contents:

```python theme={"dark"}
from dagster import asset
from dagster_cube.cube_resource import CubeResource

@asset
def cube_query_workflow():
  my_cube_resource = CubeResource(
    instance_url="https://awesome-ecom.gcp-us-central1.cubecloudapp.dev/cubejs-api/v1/",
    api_key="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjEwMDAwMDAwMDAsImV4cCI6NTAwMDAwMDAwMH0.OHZOpOBVKr-sCwn8sbZ5UFsqI3uCs6e4omT7P6WVMFw"
  )

  response = my_cube_resource.make_request(
    method="POST",
    endpoint="load",
    data={
      'query': {
        'measures': ['Orders.count'],
        'dimensions': ['Orders.status']
      }
    }
  )

  return response

@asset
def cube_build_workflow():
  my_cube_resource = CubeResource(
    instance_url="https://awesome-ecom.gcp-us-central1.cubecloudapp.dev/cubejs-api/v1/",
    api_key="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjEwMDAwMDAwMDAsImV4cCI6NTAwMDAwMDAwMH0.OHZOpOBVKr-sCwn8sbZ5UFsqI3uCs6e4omT7P6WVMFw"
  )

  response = my_cube_resource.make_request(
    method="POST",
    endpoint="pre-aggregations/jobs",
    data={
      'action': 'post',
      'selector': {
        'timezones': ['UTC'],
        'contexts': [{'securityContext': {}}]
      }
    }
  )

  return response
```

As you can see, the `make_request` method for the `load` endpoint accepts a Cube
query via the `query` option and the `make_request` method for the
`pre-aggregations/jobs` endpoint accepts a pre-aggregation selector via the
`selector` option.

## Running jobs

Now, you can load these jobs to Dagster:

```bash theme={"dark"}
dagster dev -f cube.py
```

Navigate to [Dagit UI][dagster-docs-dagit] at
[localhost:3000](http://localhost:3000) and click **Materialize all** to
run both jobs:

<Frame>
  <img />
</Frame>

[dagster]: https://dagster.io

[dagster-cloud]: https://dagster.io/cloud

[dagster-docs-install]: https://docs.dagster.io/getting-started/install

[dagster-docs-dagit]: https://docs.dagster.io/concepts/webserver/ui

[github-dagster-cube]: https://github.com/discursus-data/dagster-cube

[github-dagster-cube-docs]: https://github.com/discursus-data/dagster-cube/blob/main/README.md

[ref-load-endpoint]: /reference/core-data-apis/rest-api/reference#v1load

[ref-ref-jobs-endpoint]: /reference/core-data-apis/rest-api/reference#base_path/v1/pre-aggregations/jobs

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-orchestration-api]: /reference/orchestration-api


# Orchestration API
Source: https://docs.cube.dev/reference/orchestration-api/index

Trigger pre-aggregation refreshes from Airflow, Dagster, or Prefect instead of relying on Cube's scheduled refresh.

Orchestration API enables Cube to work with data orchestration tools and let
them *push* changes from upstream data sources to Cube, as opposed to letting
Cube *pull* changes from upstream data sources via the
[`scheduledRefresh`][ref-scheduled-refresh] configration option of
pre-aggregations.

<Frame>
  <img />
</Frame>

Orchestration API can be used to implement both [embedded analytics][cube-ea]
and internal or self-serve [business intelligence][cube-issbi] use cases. When
implementing [real-time analytics][cube-rta], consider pulling data from
upstream data sources with [lambda pre-aggregations][ref-lambda-pre-aggs].

Under the hood, the Orchestration API is exposed via the
[`/v1/pre-aggregations/jobs`][ref-ref-jobs-endpoint] endpoint of the
[REST (JSON) API][ref-rest-api].

## Supported tools

Orchestration API has integration packages to work with popular data
orchestration tools. Check the following guides to get tool-specific
instructions:

<CardGroup>
  <Card title="Apache Airflow" href="/reference/orchestration-api/airflow">
    Trigger pre-aggregation builds from Apache Airflow DAGs.
  </Card>

  <Card title="Dagster" href="/reference/orchestration-api/dagster">
    Trigger pre-aggregation builds from Dagster assets and jobs.
  </Card>

  <Card title="Prefect" href="/reference/orchestration-api/prefect">
    Trigger pre-aggregation builds from Prefect flows.
  </Card>
</CardGroup>

## Configuration

Orchestration API is enabled by default but inaccessible due to the default [API
scopes][ref-api-scopes] configuration. To allow access to the Orchestration API,
enable the `jobs` scope, e.g., by setting the [`CUBEJS_DEFAULT_API_SCOPES`](/reference/configuration/environment-variables#cubejs_default_api_scopes)
environment variable to `meta,data,graphql,jobs`.

## Building pre-aggregations

Orchestration API allows to trigger pre-aggregation builds programmatically. It
can be useful for data orchestration tools to push changes from upstream data
sources to Cube or for any third parties to invalidate and rebuild
pre-aggregations on demand.

You can trigger pre-aggregation builds and check build statuses using the
[`/v1/pre-aggregations/jobs`][ref-ref-jobs-endpoint] endpoint. It is possible to
rebuild all pre-aggregations or specify the ones to be rebuilt:

* Particular pre-aggregations.
* Pre-aggregations that reference particular cubes.
* Pre-aggregations that reference cubes from particular data sources.
* For [partitioned pre-aggregations][ref-pre-agg-partitions], only partitions that contain
  data from a particular date range.

[ref-scheduled-refresh]: /reference/data-modeling/pre-aggregations#scheduled_refresh

[cube-ea]: https://cube.dev/use-cases/embedded-analytics

[cube-issbi]: https://cube.dev/use-cases/semantic-layer

[cube-rta]: https://cube.dev/use-cases/real-time-analytics

[ref-lambda-pre-aggs]: /docs/pre-aggregations/lambda-pre-aggregations

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-api-scopes]: /reference/core-data-apis/rest-api#configuration-api-scopes

[ref-ref-jobs-endpoint]: /reference/core-data-apis/rest-api/reference#base_path/v1/pre-aggregations/jobs

[ref-pre-agg-partitions]: /docs/pre-aggregations/using-pre-aggregations#partitioning


# Integration with Prefect
Source: https://docs.cube.dev/reference/orchestration-api/prefect

Prefect is a popular open-source orchestrator for data-intensive workflows. Prefect Cloud is a fully managed service for Prefect.

[Prefect][prefect] is a popular open-source orchestrator for data-intensive
workflows. [Prefect Cloud][prefect-cloud] is a fully managed service for
Prefect.

This guide demonstrates how to setup Cube and Prefect to work together so that
Prefect can push changes from upstream data sources to Cube via the
[Orchestration API][ref-orchestration-api].

## Tasks

In Prefect, each workflow is represented by flows, Python functions decorated
with a `@flow` decorator. Flows include calls to tasks, Python functions
decorated with a `@task` decorator, as well as to child flows. Tasks represent
distinct pieces of work executed within a flow. They can perform various jobs:
poll for some precondition, perform extract-load-transform (ETL), or trigger
external systems like Cube.

Integration between Cube and Prefect is enabled by the
[`prefect-cubejs`][github-prefect-cubejs] package.

<Info>
  Cube and Prefect integration package was originally contributed by
  [Alessandro Lollo](https://github.com/AlessandroLollo), Data Engineering Manager
  at Cloud Academy
  ([case study](https://cube.dev/case-studies/cloud-academy-and-cube)), for which
  we're very grateful.
</Info>

The package provides the following tasks:

* `run_query` for querying Cube via the [`/v1/load`][ref-load-endpoint] endpoint
  of the [REST (JSON) API][ref-rest-api].
* `build_pre_aggregations` for triggering pre-aggregation builds via the
  [`/v1/pre-aggregations/jobs`][ref-ref-jobs-endpoint] endpoint of the
  [Orchestration API][ref-orchestration-api].

Please refer to the [package documentation][github-prefect-cubejs-docs] for
details and options reference.

## Installation

Install [Prefect][prefect-docs-install].

Create a new directory:

```bash theme={"dark"}
mkdir cube-prefect
cd cube-prefect
```

Install the integration package:

```bash theme={"dark"}
pip install prefect-cubejs
```

## Configuration

Create a new workflow named `cube_query.py` with the following contents. As you
can see, the `run_query` task accepts a Cube query via the `query` option.

```python theme={"dark"}
from prefect import flow
from prefect_cubejs.tasks import (
  run_query
)

@flow
def cube_query_workflow():
  run_query(
    url="https://awesome-ecom.gcp-us-central1.cubecloudapp.dev/cubejs-api",
    api_secret="SECRET",
    query="""{
      "measures": ["Orders.count"],
      "dimensions": ["Orders.status"]
    }"""
  )

cube_query_workflow()
```

Create a new workflow named `cube_build.py` with the following contents. As you
can see, the `build_pre_aggregations` task accepts a pre-aggregation selector
via the `selector` option.

```python theme={"dark"}
from prefect import flow
from prefect_cubejs.tasks import (
  build_pre_aggregations
)

@flow
def cube_build_workflow():
  build_pre_aggregations(
    url="https://awesome-ecom.gcp-us-central1.cubecloudapp.dev/cubejs-api",
    api_secret="SECRET",
    selector={
      "contexts": [
        {"securityContext": {}}
      ],
      "timezones": ["UTC"]
    },
    wait_for_job_run_completion=True
  )

cube_build_workflow()
```

## Running workflows

Now, you can run these workflows:

```bash theme={"dark"}
python cube_query.py
python cube_build.py
```

[prefect]: https://www.prefect.io

[prefect-cloud]: https://www.prefect.io/cloud/

[prefect-docs-install]: https://docs.prefect.io/2.10.13/getting-started/installation/#install-prefect

[github-prefect-cubejs]: https://github.com/AlessandroLollo/prefect-cubejs

[github-prefect-cubejs-docs]: https://alessandrolollo.github.io/prefect-cubejs/tasks/

[ref-load-endpoint]: /reference/core-data-apis/rest-api/reference#v1load

[ref-ref-jobs-endpoint]: /reference/core-data-apis/rest-api/reference#base_path/v1/pre-aggregations/jobs

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-orchestration-api]: /reference/orchestration-api