From 750279f7eeade29728bafb84099f9ac6692f2432 Mon Sep 17 00:00:00 2001
From: Artyom Keydunov <artyom@cube.dev>
Date: Thu, 14 May 2026 12:24:18 -0700
Subject: [PATCH 1/5] docs: add Access Policies viewer page and clean up
 modeling docs (#10887)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add a new page under Data Modeling → Developing Model that documents
  the Access Policies viewer in Cube Cloud, including the list view
  (with screenshot) and the per-policy detail view.
- Remove the broken hero image from the Visual Modeler page.
- Drop the redundant "Available on all plans" callout from nine pages;
  the convention is to use a plan-availability <Note> only when the
  feature is actually plan-gated.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../admin/deployment/environments.mdx         |  6 --
 .../admin/deployment/infrastructure.mdx       |  6 --
 .../admin/monitoring/pre-aggregations.mdx     |  6 --
 .../admin/monitoring/query-history.mdx        |  4 +-
 docs-mintlify/docs.json                       |  3 +-
 .../data-modeling/access-control/context.mdx  |  6 --
 .../data-modeling/access-policies-viewer.mdx  | 85 +++++++++++++++++++
 .../docs/data-modeling/data-model-ide.mdx     |  6 --
 docs-mintlify/docs/data-modeling/dev-mode.mdx |  6 --
 .../docs/data-modeling/sql-runner.mdx         |  6 --
 .../docs/data-modeling/visual-modeler.mdx     |  4 -
 .../authentication/security-context.mdx       |  6 --
 12 files changed, 89 insertions(+), 55 deletions(-)
 create mode 100644 docs-mintlify/docs/data-modeling/access-policies-viewer.mdx

diff --git a/docs-mintlify/admin/deployment/environments.mdx b/docs-mintlify/admin/deployment/environments.mdx
index a95d411660a96..cb51403eb296c 100644
--- a/docs-mintlify/admin/deployment/environments.mdx
+++ b/docs-mintlify/admin/deployment/environments.mdx
@@ -9,12 +9,6 @@ Every Cube Cloud deployment provides a number of environments:
 - Multiple [staging environments](#staging-environments).
 - Per-user [development environments](#development-environments).
 
-<Note>
-
-Available on [all plans](https://cube.dev/pricing).
-
-</Note>
-
 ## Production environment
 
 This is the main environment. It runs the data model from the _main branch_.
diff --git a/docs-mintlify/admin/deployment/infrastructure.mdx b/docs-mintlify/admin/deployment/infrastructure.mdx
index ebc9a2ab29e65..4bee7d6f2f195 100644
--- a/docs-mintlify/admin/deployment/infrastructure.mdx
+++ b/docs-mintlify/admin/deployment/infrastructure.mdx
@@ -26,12 +26,6 @@ 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.
 
-<Note>
-
-Available on [all plans](https://cube.dev/pricing).
-
-</Note>
-
 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.
diff --git a/docs-mintlify/admin/monitoring/pre-aggregations.mdx b/docs-mintlify/admin/monitoring/pre-aggregations.mdx
index 49958e0f80c76..87692c309018b 100644
--- a/docs-mintlify/admin/monitoring/pre-aggregations.mdx
+++ b/docs-mintlify/admin/monitoring/pre-aggregations.mdx
@@ -9,12 +9,6 @@ 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.
 
-<Note>
-
-Available on [all plans](https://cube.dev/pricing).
-
-</Note>
-
 <Frame>
   <img src="https://ucarecdn.com/eb10de99-4ff6-4a9f-abd5-736971497583/" />
 </Frame>
diff --git a/docs-mintlify/admin/monitoring/query-history.mdx b/docs-mintlify/admin/monitoring/query-history.mdx
index 438e2da63e98d..511a93f2ba6f9 100644
--- a/docs-mintlify/admin/monitoring/query-history.mdx
+++ b/docs-mintlify/admin/monitoring/query-history.mdx
@@ -10,8 +10,8 @@ failed.
 
 <Note>
 
-Available on [all plans](https://cube.dev/pricing).
-You can also choose a [Query History tier](/admin/account-billing/pricing#query-history-tiers).
+You can choose a [Query History tier](/admin/account-billing/pricing#query-history-tiers)
+to fit your retention and throughput needs.
 
 </Note>
 
diff --git a/docs-mintlify/docs.json b/docs-mintlify/docs.json
index 2fac5fa690c74..724945f33bb93 100644
--- a/docs-mintlify/docs.json
+++ b/docs-mintlify/docs.json
@@ -175,7 +175,8 @@
                 "pages": [
                   "docs/data-modeling/visual-modeler",
                   "docs/data-modeling/data-model-ide",
-                  "docs/data-modeling/dev-mode"
+                  "docs/data-modeling/dev-mode",
+                  "docs/data-modeling/access-policies-viewer"
                 ]
               }
             ]
diff --git a/docs-mintlify/docs/data-modeling/access-control/context.mdx b/docs-mintlify/docs/data-modeling/access-control/context.mdx
index d9f6626f4ff68..b0cca7e0fe97d 100644
--- a/docs-mintlify/docs/data-modeling/access-control/context.mdx
+++ b/docs-mintlify/docs/data-modeling/access-control/context.mdx
@@ -300,12 +300,6 @@ enrich the security context with additional attributes.
 When using Cube Cloud, you can enrich the security context with information about
 an authenticated user, obtained during their authentication.
 
-<Note>
-
-Available on [all plans](https://cube.dev/pricing).
-
-</Note>
-
 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.
 
diff --git a/docs-mintlify/docs/data-modeling/access-policies-viewer.mdx b/docs-mintlify/docs/data-modeling/access-policies-viewer.mdx
new file mode 100644
index 0000000000000..b4875fe8ee07d
--- /dev/null
+++ b/docs-mintlify/docs/data-modeling/access-policies-viewer.mdx
@@ -0,0 +1,85 @@
+---
+title: Access Policies viewer
+description: 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 src="https://static.cube.dev/docs/data-modeling/access-policies-viewer/list-view.png" 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
\ No newline at end of file
diff --git a/docs-mintlify/docs/data-modeling/data-model-ide.mdx b/docs-mintlify/docs/data-modeling/data-model-ide.mdx
index 8d5daa3076c15..f22e5800d9654 100644
--- a/docs-mintlify/docs/data-modeling/data-model-ide.mdx
+++ b/docs-mintlify/docs/data-modeling/data-model-ide.mdx
@@ -9,12 +9,6 @@ Data model editor provides the code-first experience for building and enhancing
 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.
 
-<Note>
-
-Available on [all plans](https://cube.dev/pricing).
-
-</Note>
-
 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.
diff --git a/docs-mintlify/docs/data-modeling/dev-mode.mdx b/docs-mintlify/docs/data-modeling/dev-mode.mdx
index 62f12054dfb9a..5d5349a657046 100644
--- a/docs-mintlify/docs/data-modeling/dev-mode.mdx
+++ b/docs-mintlify/docs/data-modeling/dev-mode.mdx
@@ -6,12 +6,6 @@ description: Outlines development mode in Cube Cloud—branch-scoped APIs, save
 Development mode allows to test and debug the data model in an isolated
 [development environment][ref-environments-dev] before releasing any changes to production.
 
-<Note>
-
-Available on [all plans](https://cube.dev/pricing).
-
-</Note>
-
 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.
diff --git a/docs-mintlify/docs/data-modeling/sql-runner.mdx b/docs-mintlify/docs/data-modeling/sql-runner.mdx
index f6239f2a56360..4e7e0bbe97a2d 100644
--- a/docs-mintlify/docs/data-modeling/sql-runner.mdx
+++ b/docs-mintlify/docs/data-modeling/sql-runner.mdx
@@ -8,12 +8,6 @@ on your data source or Cube Store. It can be used to inform the development of
 the data model, for ad-hoc querying as well as debugging SQL queries generated
 by Cube to execute against the data source.
 
-<Note>
-
-Available on [all plans](https://cube.dev/pricing).
-
-</Note>
-
 <video width="100%" controls>
   <source
     src="https://ucarecdn.com/8cbdd639-e86b-4190-bbaa-37122c39bc01/video.mp4"
diff --git a/docs-mintlify/docs/data-modeling/visual-modeler.mdx b/docs-mintlify/docs/data-modeling/visual-modeler.mdx
index f791e060518a2..59f00c2e9f10e 100644
--- a/docs-mintlify/docs/data-modeling/visual-modeler.mdx
+++ b/docs-mintlify/docs/data-modeling/visual-modeler.mdx
@@ -23,10 +23,6 @@ feature.
 
 </Info>
 
-<Frame>
-  <img src="https://ucarecdn.com/8c6c183c-6cf5-4ee1-ab67-36e37b62a12f/" />
-</Frame>
-
 ## Prerequisites
 
 Visual Modeler integrates with the [development mode][ref-dev-mode],
diff --git a/docs-mintlify/embedding/authentication/security-context.mdx b/docs-mintlify/embedding/authentication/security-context.mdx
index d8eac76ace5c2..fd07458d26868 100644
--- a/docs-mintlify/embedding/authentication/security-context.mdx
+++ b/docs-mintlify/embedding/authentication/security-context.mdx
@@ -300,12 +300,6 @@ enrich the security context with additional attributes.
 When using Cube Cloud, you can enrich the security context with information about
 an authenticated user, obtained during their authentication.
 
-<Note>
-
-Available on [all plans](https://cube.dev/pricing).
-
-</Note>
-
 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.
 

From 7537c5e759145f89a4cf3635216173079d7d44b9 Mon Sep 17 00:00:00 2001
From: Artyom Keydunov <artyom@cube.dev>
Date: Thu, 14 May 2026 12:35:20 -0700
Subject: [PATCH 2/5] docs: fix broken links to Update channels page and broken
 HEIC image (#10881)

Fix all references to non-existent /admin/deployment/deployments page in
Mintlify docs by pointing them to /admin/deployment/index instead:
- distribution.mdx: update-channels link
- environments.mdx: cube-version and update-channels links
- auto-suspension.mdx: cube-version link
- control-plane-api.mdx: deployments link

Fix broken image on Update channels section by appending ucarecdn's
-/format/auto/ processing suffix so the CDN converts the HEIC file
to a browser-compatible format. Fixed in both Mintlify and old docs.

Fix wrong path prefix in old docs environments.mdx (/product/deployment/cloud/
-> /product/administration/deployment/).

CUB-2581

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
---
 docs-mintlify/admin/account-billing/distribution.mdx          | 2 +-
 docs-mintlify/admin/deployment/auto-suspension.mdx            | 2 +-
 docs-mintlify/admin/deployment/environments.mdx               | 4 ++--
 docs-mintlify/admin/deployment/index.mdx                      | 2 +-
 docs-mintlify/reference/control-plane-api.mdx                 | 2 +-
 .../content/product/administration/deployment/deployments.mdx | 2 +-
 .../product/administration/deployment/environments.mdx        | 4 ++--
 7 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/docs-mintlify/admin/account-billing/distribution.mdx b/docs-mintlify/admin/account-billing/distribution.mdx
index 887bcdbd8793a..9120951c2b663 100644
--- a/docs-mintlify/admin/account-billing/distribution.mdx
+++ b/docs-mintlify/admin/account-billing/distribution.mdx
@@ -124,4 +124,4 @@ open http://localhost:3000
 [ref-infrastructure]: /admin/deployment/infrastructure
 [ref-workspace]: /admin/workspace
 [ref-deployment]: /admin/deployment
-[ref-update-channels]: /admin/deployment/deployments#update-channels
\ No newline at end of file
+[ref-update-channels]: /admin/deployment/index#update-channels
\ No newline at end of file
diff --git a/docs-mintlify/admin/deployment/auto-suspension.mdx b/docs-mintlify/admin/deployment/auto-suspension.mdx
index 972865fe64012..20a8dd79de4f4 100644
--- a/docs-mintlify/admin/deployment/auto-suspension.mdx
+++ b/docs-mintlify/admin/deployment/auto-suspension.mdx
@@ -124,4 +124,4 @@ response times to be significantly longer than usual.
 [self-effects]: #effects-on-experience
 [ref-refresh-worker]: /cube-core/architecture#refresh-worker
 [ref-sls]: /docs/integrations/semantic-layer-sync#on-schedule
-[ref-cube-version]: /admin/deployment/deployments#cube-version
\ No newline at end of file
+[ref-cube-version]: /admin/deployment/index#cube-version
\ No newline at end of file
diff --git a/docs-mintlify/admin/deployment/environments.mdx b/docs-mintlify/admin/deployment/environments.mdx
index cb51403eb296c..1aa6f0150537e 100644
--- a/docs-mintlify/admin/deployment/environments.mdx
+++ b/docs-mintlify/admin/deployment/environments.mdx
@@ -114,5 +114,5 @@ credentials**][ref-credentials].
 [ref-suspend]: /docs/deployment/cloud/auto-suspension
 [ref-overview]: /docs/workspace/integrations#review-integrations
 [ref-credentials]: /docs/workspace/integrations#view-api-credentials
-[ref-version]: /docs/deployment/cloud/deployments#cube-version
-[ref-version-channel]: /docs/deployment/cloud/deployments#update-channels
\ No newline at end of file
+[ref-version]: /admin/deployment/index#cube-version
+[ref-version-channel]: /admin/deployment/index#update-channels
\ No newline at end of file
diff --git a/docs-mintlify/admin/deployment/index.mdx b/docs-mintlify/admin/deployment/index.mdx
index 512058600c136..0a9a7f73f0df1 100644
--- a/docs-mintlify/admin/deployment/index.mdx
+++ b/docs-mintlify/admin/deployment/index.mdx
@@ -147,7 +147,7 @@ You can view or change the update channel by navigating to **Settings →
 General → Cube version**:
 
 <Frame>
-  <img src="https://ucarecdn.com/3ef5fa36-4b27-437c-aa70-dbc0aa01255d/" />
+  <img src="https://ucarecdn.com/3ef5fa36-4b27-437c-aa70-dbc0aa01255d/-/format/auto/" />
 </Frame>
 
 You can select a specific version in the drop-down. Only versions that have been used by
diff --git a/docs-mintlify/reference/control-plane-api.mdx b/docs-mintlify/reference/control-plane-api.mdx
index 7eaaec75b633b..47dcd9190fb1d 100644
--- a/docs-mintlify/reference/control-plane-api.mdx
+++ b/docs-mintlify/reference/control-plane-api.mdx
@@ -260,7 +260,7 @@ curl \
 [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/deployments
+[ref-deployments]: /admin/deployment/index
 [ref-environments]: /admin/workspace/environments
 [ref-api-keys]: /admin/account-billing/api-keys
 [ref-security-context]: /docs/data-modeling/access-control/context
diff --git a/docs/content/product/administration/deployment/deployments.mdx b/docs/content/product/administration/deployment/deployments.mdx
index 1f7d7e103c488..0c8f5cfe0c8c9 100644
--- a/docs/content/product/administration/deployment/deployments.mdx
+++ b/docs/content/product/administration/deployment/deployments.mdx
@@ -123,7 +123,7 @@ You can view or change the update channel by navigating to <Btn>Settings →
 General → Cube version</Btn>:
 
 <Screenshot
-  src="https://ucarecdn.com/3ef5fa36-4b27-437c-aa70-dbc0aa01255d/"
+  src="https://ucarecdn.com/3ef5fa36-4b27-437c-aa70-dbc0aa01255d/-/format/auto/"
   highlight="inset(36% 41% 34% 21% round 10px)"
 />
 
diff --git a/docs/content/product/administration/deployment/environments.mdx b/docs/content/product/administration/deployment/environments.mdx
index 9383db6e87da8..c6cd979920490 100644
--- a/docs/content/product/administration/deployment/environments.mdx
+++ b/docs/content/product/administration/deployment/environments.mdx
@@ -112,5 +112,5 @@ credentials</Btn>][ref-credentials].
 [ref-suspend]: /product/deployment/cloud/auto-suspension
 [ref-overview]: /product/workspace/integrations#review-integrations
 [ref-credentials]: /product/workspace/integrations#view-api-credentials
-[ref-version]: /product/deployment/cloud/deployments#cube-version
-[ref-version-channel]: /product/deployment/cloud/deployments#update-channels
\ No newline at end of file
+[ref-version]: /product/administration/deployment/deployments#cube-version
+[ref-version-channel]: /product/administration/deployment/deployments#update-channels
\ No newline at end of file

From f292ad88043742eb2fb95b54337ddb2250e0e5af Mon Sep 17 00:00:00 2001
From: Pavel Tiunov <pavel.tiunov@gmail.com>
Date: Thu, 14 May 2026 14:13:57 -0700
Subject: [PATCH 3/5] docs: Output column types for direct kafka mode

---
 .../connect-to-data/data-sources/ksqldb.mdx   | 153 ++++++++++++++++++
 1 file changed, 153 insertions(+)

diff --git a/docs-mintlify/admin/connect-to-data/data-sources/ksqldb.mdx b/docs-mintlify/admin/connect-to-data/data-sources/ksqldb.mdx
index 72c3dd60c56b4..d4a9e450166f5 100644
--- a/docs-mintlify/admin/connect-to-data/data-sources/ksqldb.mdx
+++ b/docs-mintlify/admin/connect-to-data/data-sources/ksqldb.mdx
@@ -349,6 +349,19 @@ cubes:
               - CUBE.user_id
               - CUBE.status
         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.count
+            type: int
+          - member: CUBE.total_amount
+            type: decimal
+          - member: CUBE.failed_count
+            type: int
 ```
 
 ```javascript title="JavaScript"
@@ -514,6 +527,14 @@ cube("order_events_stream", {
         },
       },
       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.count, type: `int` },
+        { member: CUBE.total_amount, type: `decimal` },
+        { member: CUBE.failed_count, type: `int` },
+      ],
     },
   },
 });
@@ -533,6 +554,9 @@ Key properties for the streaming pre-aggregation:
   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
 
@@ -579,6 +603,135 @@ 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"
+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
+    build_range_start:
+      sql: "SELECT date_trunc('day', DATE_SUB(NOW(), INTERVAL '5 hour'))"
+    build_range_end:
+      sql: "SELECT DATE_ADD(NOW(), 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.count
+        type: int
+      - member: CUBE.total_amount
+        type: decimal
+      - member: CUBE.failed_count
+        type: int
+```
+
+```javascript title="JavaScript"
+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`,
+    build_range_start: {
+      sql: `SELECT date_trunc('day', DATE_SUB(NOW(), INTERVAL '5 hour'))`,
+    },
+    build_range_end: {
+      sql: `SELECT DATE_ADD(NOW(), 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.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.
+- `type` — the Cube Store column type. Common values: `text`, `int`,
+  `bigint`, `decimal`, `float`, `boolean`, `timestamp`.
+
+The time dimension used in `time_dimension` does not need an entry in
+`output_column_types` — its type is always `timestamp` and is set
+automatically.
+
+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

From 1b54dea1b1b2f737b895bcb2fa11bed848d8e821 Mon Sep 17 00:00:00 2001
From: Pavel Tiunov <pavel.tiunov@gmail.com>
Date: Thu, 14 May 2026 14:43:49 -0700
Subject: [PATCH 4/5] docs: Topic name matching

---
 .../connect-to-data/data-sources/ksqldb.mdx   | 29 +++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/docs-mintlify/admin/connect-to-data/data-sources/ksqldb.mdx b/docs-mintlify/admin/connect-to-data/data-sources/ksqldb.mdx
index d4a9e450166f5..c78f6d2210f83 100644
--- a/docs-mintlify/admin/connect-to-data/data-sources/ksqldb.mdx
+++ b/docs-mintlify/admin/connect-to-data/data-sources/ksqldb.mdx
@@ -581,6 +581,35 @@ 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 {#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>
+
+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

From f27717e08904fd9e7228601c743915670386f195 Mon Sep 17 00:00:00 2001
From: Alex Vasilev <alex@cube.dev>
Date: Thu, 14 May 2026 15:47:05 -0700
Subject: [PATCH 5/5] docs: document userProfile field on Generate Session API
 (#10888)

Adds a User profile section to the Generate Session reference
documenting the new userProfile.displayName and userProfile.picture
fields, including supported image formats and graceful fallback
behavior when the picture URL fails to load.
---
 .../reference/embed-apis/generate-session.mdx | 156 +++++++++++-------
 1 file changed, 96 insertions(+), 60 deletions(-)

diff --git a/docs-mintlify/reference/embed-apis/generate-session.mdx b/docs-mintlify/reference/embed-apis/generate-session.mdx
index c14a05fedb2d8..58bd4257262d4 100644
--- a/docs-mintlify/reference/embed-apis/generate-session.mdx
+++ b/docs-mintlify/reference/embed-apis/generate-session.mdx
@@ -23,30 +23,31 @@ 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 |
+| 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`. |
-| `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`. |
+| 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`.                                                                                                   |
 
 <Info>
 
-When using `internalId`, the user must already exist in Cube Cloud. You cannot specify `groups`, `userAttributes`, `groupDefinitions`, `userAttributeDefinitions`, or `securityContext` with `internalId` — the internal user's existing permissions are used instead.
+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>
 
@@ -56,6 +57,43 @@ Accounts are limited to 10,000 external users. To increase this limit, please co
 
 </Warning>
 
+## 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
+{
+  "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.
@@ -71,10 +109,10 @@ Accounts are limited to 10,000 external users. To increase this limit, please co
 }
 ```
 
-| 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. |
+| 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**:
 
@@ -96,11 +134,11 @@ Accounts are limited to 10,000 external users. To increase this limit, please co
 
 **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. |
+| 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**:
 
@@ -132,10 +170,10 @@ Both fields:
 }
 ```
 
-| 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. |
+| 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.
 
@@ -155,13 +193,13 @@ Duplicate `name` entries within the same request are rejected.
 }
 ```
 
-| 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. |
+| 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.
 
@@ -175,30 +213,30 @@ Define a group and an attribute, assign the user to both, and mint a session —
 const session = await fetch(
   `https://${ACCOUNT_NAME}.cubecloud.dev/api/v1/embed/generate-session`,
   {
-    method: 'POST',
+    method: "POST",
     headers: {
-      'Content-Type': 'application/json',
+      "Content-Type": "application/json",
       Authorization: `Api-Key ${API_KEY}`,
     },
     body: JSON.stringify({
       deploymentId: DEPLOYMENT_ID,
-      externalId: 'user-123',
-      embedTenantName: 'acme-corp',
+      externalId: "user-123",
+      embedTenantName: "acme-corp",
       creatorMode: true,
 
       // Upserted before validation runs
       groupDefinitions: [
-        { name: 'analysts', description: 'Read-only viewers' },
+        { name: "analysts", description: "Read-only viewers" },
       ],
       userAttributeDefinitions: [
-        { name: 'department', type: 'string', displayName: 'Department' },
+        { name: "department", type: "string", displayName: "Department" },
       ],
 
       // Reference the names we just defined
-      groups: ['analysts'],
-      userAttributes: [{ name: 'department', value: 'Sales' }],
+      groups: ["analysts"],
+      userAttributes: [{ name: "department", value: "Sales" }],
     }),
-  },
+  }
 );
 ```
 
@@ -227,8 +265,8 @@ The API returns a session object:
 }
 ```
 
-| Field | Type | Description |
-|-------|------|-------------|
+| 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.
@@ -264,26 +302,24 @@ session_id = response.json()['sessionId']
 ```
 
 ```javascript title="JavaScript" JavaScript
-const API_KEY = 'YOUR_API_KEY';
-const ACCOUNT_NAME = 'your-account';
+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',
+    method: "POST",
     headers: {
-      'Content-Type': 'application/json',
-      'Authorization': `Api-Key ${API_KEY}`
+      "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']
-    })
+      externalId: "user@example.com",
+      userAttributes: [{ name: "department", value: "Sales" }],
+      groups: ["analysts"],
+    }),
   }
 );