Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

chore(bi): reconcile catalog integration backlog (#124958)

Marius Andra030f62347091
diff --git a/docs/published/handbook/engineering/data-warehouse.md b/docs/published/handbook/engineering/data-warehouse.md
index 6bb5bb173128..10a1b600ec36 100644
--- a/docs/published/handbook/engineering/data-warehouse.md
+++ b/docs/published/handbook/engineering/data-warehouse.md
@@ -414,12 +414,50 @@ BI chart settings preserve custom scatter axes and implicit count formatting. Nu
Catalog SQL metrics can open as BI query snapshots. Opening a metric shows a loading state until its definition is ready, or an error if it cannot load. Press **Run** to query the snapshot. Their dates, grouping, and bound values come from the metric definition; shelf edits, worksheet date filters, pivots, and result drilling are unavailable. For snapshots with bound string, number, or boolean values, **Edit parameters** changes those values for the worksheet without changing the SQL or catalog definition. Number parameters require a finite number. Other parameter types remain unchanged. Apply follows the worksheet auto-update setting; with auto-update off, press **Run**. Changing the chart changes the presentation of those results. Saved snapshots do not follow later catalog edits.
-After running a worksheet, **Propose as catalog metric** sends its resolved SQL and date window through catalog review. A pending or failed query cannot be proposed. Proposing an existing metric name updates its definition for review. Direct-connection worksheets cannot be proposed as catalog metrics.
+After running a worksheet, **Propose as catalog metric** sends its resolved SQL and date window through catalog review. A pending or failed query cannot be proposed. The catalog requires explicit confirmation to overwrite an existing metric; the BI dialog currently reports the name conflict without offering that confirmation. Direct-connection worksheets cannot be proposed as catalog metrics.
-The worksheet library offers editable question starters for daily events, daily distinct people, events ranked by distinct people, and page views by referring domain. Each uses the last seven days of event data and opens as an unsaved worksheet; press **Run** to query it. The page-view starter requires captured `$pageview` events with `$referring_domain` for a useful breakdown. The worksheet library also suggests approved, non-drifted SQL metrics and certified sources. Each list requests at most three eligible candidates; drifted metrics are omitted without scanning more pages. Source context keeps certification visible and groups descriptions and relationship review status under **Catalog details**, collapsed by default to leave room for fields. Neutral catalog buttons show an external-link icon to indicate that they leave the worksheet. Relationship proposals open the catalog with the source prefilled; they become usable joins only after approval. Optional catalog suggestions do not prevent opening the worksheet library when the catalog is unavailable. Browser Back returns from a starter to the worksheet library; confirming discarded edits does not replace that history entry with an empty worksheet.
+The worksheet library offers editable question starters for daily events, daily distinct people, events ranked by distinct people, and page views by referring domain. Each uses the last seven days of event data and opens as an unsaved worksheet; press **Run** to query it. The page-view starter requires captured `$pageview` events with `$referring_domain` for a useful breakdown. The worksheet library also suggests up to three certified sources. Metric suggestions were removed in [#120111](https://github.com/PostHog/posthog/pull/120111); SQL metrics remain accessible through **Explore in BI** in the catalog. Source context keeps certification visible and groups descriptions and relationship review status under **Catalog details**, collapsed by default to leave room for fields. Neutral catalog buttons show an external-link icon to indicate that they leave the worksheet. Relationship proposals open the catalog with the source prefilled; they become usable joins only after approval. Optional catalog suggestions do not prevent opening the worksheet library when the catalog is unavailable. Browser Back returns from a starter to the worksheet library; confirming discarded edits does not replace that history entry with an empty worksheet.
The BI assistant receives the current worksheet draft, including its unsaved name, and shared catalog capabilities. Worksheet and catalog content remain untrusted context. Dismissing the saved worksheet attachment also removes its hidden draft and metric reference. Completed foreground insight tools refresh the worksheet library. Updates to the open worksheet refresh its saved version while preserving local edits. If both changed the query or name differently, saving over the worksheet is blocked until the local draft is discarded or saved as a copy. This conflict protection survives reloading a worksheet link. A failed refresh can be retried before saving.
+## BI and data catalog TODO
+
+Implementation audit, October 28, 2026. These are proposed integration contracts, not commitments from the owning teams. Business intelligence belongs to Data tools; Data catalog belongs to Data modeling. Catalog should own shared definitions and governance, the query platform should compile and execute them consistently, and BI should own interactive authoring and presentation.
+
+### Implemented foundations
+
+- [x] Worksheet-local calculated fields, groups, bins, member aliases, reusable hierarchy copies, comparisons, pivots, source previews, and SQL handoffs.
+- [x] Catalog SQL snapshots, worksheet-to-metric proposals, certified-source discovery, and relationship review handoffs.
+- [x] Dashboard cross-filtering for compatible BI worksheets on the same table and connection ([#123561](https://github.com/PostHog/posthog/pull/123561)).
+- [x] Pivot conditional formatting ([#124717](https://github.com/PostHog/posthog/pull/124717)), editable question starters ([#124730](https://github.com/PostHog/posthog/pull/124730)), and join-key investigation ([#124729](https://github.com/PostHog/posthog/pull/124729)).
+- [x] Bound string, number, and boolean parameter editing for metric snapshots ([#124721](https://github.com/PostHog/posthog/pull/124721)). This does not make grouping editable or create live catalog linkage.
+
+### BI-owned integration work
+
+- [ ] Adopt the catalog overwrite-confirmation flow for worksheet metric proposals. Preserve entered values on cancel, allow retry, and keep overwritten metrics proposed.
+- [ ] Show catalog trust context when exploring a metric: approval and drift status, unit, owner, and stable identity. Distinguish the copied definition from current catalog state; never imply a snapshot follows catalog changes.
+- [ ] Add deliberate, searchable metric discovery in BI using the existing catalog search API. Handle loading, failure, no matches, pagination, and unsupported definition kinds explicitly.
+- [ ] Surface existing field descriptions and data-quality context in the data pane. Preserve raw field identities and distinguish certification from current check health.
+
+### Shared-layer requests
+
+| Priority | Request | Acceptance boundary |
+| -------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| P0 | Composable metrics | A structured metric declares supported dimensions, date range, time grain, filters, output schema, and capabilities. BI can change these without rewriting SQL. Arbitrary SQL can remain snapshot-only. |
+| P0 | Aggregation semantics and dataset grain | Declare measure aggregation, unit/scale, entity keys, base grain, valid dimensions, and time behavior. Ratios, distinct counts, and balances have explicit rollup rules. |
+| P0 | Governed relationship cardinality | Persist expected cardinality, uniqueness and match-coverage evidence, validation time, and status. Query planning rejects, warns about, or correctly handles joins that would multiply measures. A configured join or one-off SQL check is insufficient evidence. |
+| P1 | Publish reusable semantic fields | Publish/review/reference business calculations, groups, bins, aliases, and hierarchies while retaining worksheet-local experimentation and overrides. Use existing saved warehouse expressions where appropriate. |
+| P1 | Stable references and dependency tracking | Reference immutable metric IDs and definition versions/hashes. Offer explicit pin/refresh behavior, downstream worksheet/dashboard dependencies, and changed/deleted/unapproved warnings. Names alone are insufficient because they can be reused. |
+| P1 | Shared metadata and health contract | Expose permission-aware source/field descriptions, semantic defaults, owner, certification, freshness, quality results, and lineage links. A trust mark and passing checks communicate different facts. |
+| P1/P2 | Source coverage | Define capabilities and connection-scoped identity for direct connections, native tables, saved views, and managed views. Direct-connection metric proposals and managed-view certification remain gaps. Prioritize according to the supported BI audience. |
+| P2 | Shared dimensions across datasets | Give dimensions such as Customer, Country, and Date stable identities and explicit mappings so dashboard filtering can cross compatible datasets safely. Depends on grain and relationship contracts. |
+
+Reuse the existing data-quality checks (uniqueness, non-null, relationships, freshness, and custom SQL), metric lineage, insight drift detection, warehouse column annotations, saved expressions, and server-side catalog search. Extend these contracts rather than creating parallel BI stores. BI proposals currently submit resolved SQL without the source-insight linkage used by insight drift detection.
+
+Keep chart colors, shelf placement, pane layout, current drill position, and ad hoc table calculations local to BI. Publishing a reusable business definition should be explicit.
+
+First joint acceptance scenario: define Revenue once, add it to a worksheet, break it down by customer country, switch monthly/quarterly grain, and apply dates. BI and AI use the same definition. A join that duplicates revenue is detected. Saving preserves the definition version, and subsequent definition changes are visible to the worksheet author.
+
## Connected fields in BI mode
**Check key uniqueness** opens an editable SQL check for repeated or null keys in a configured relationship's joined table. Press **Run** in the SQL editor to execute it. The check scans the full joined table, ignores worksheet filters, and returns at most 100 key groups. It does not check missing matches or prove that a join is safe for every aggregation. Expression-based keys require a custom SQL check.