@microsoft/rayfin-semantic-model-pack 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,285 @@
1
+ # Anti-Patterns and Corrections
2
+
3
+ ## Contents
4
+
5
+ 1. [UNION to mix grains](#anti-pattern-1-union-to-mix-grains) — combining detail rows + a total row in one query
6
+ 2. [FORMAT() for display labels](#anti-pattern-2-format-for-display-labels) — converting numbers to formatted strings in DAX
7
+ 3. [Stringified dates](#anti-pattern-3-stringified-dates) — turning dates into month-name strings in DAX
8
+ 4. [Complex DAX for dimension completeness](#anti-pattern-4-complex-dax-for-dimension-completeness) — GENERATE/CROSSJOIN to force-include empty dimension members
9
+ 5. [Decorative text in DAX](#anti-pattern-5-decorative-text-in-dax) — emoji, prefixes, concatenated UI strings
10
+ 6. [SELECTCOLUMNS for friendly names](#anti-pattern-6-selectcolumns-for-friendly-names) — wrapping queries solely for renaming
11
+ 7. [Converting BLANK to placeholder values](#anti-pattern-7-converting-blank-to-placeholder-values) — replacing BLANK with `0` / `""` / `"N/A"` in DAX
12
+
13
+ ## Anti-Pattern 1: UNION to mix grains
14
+
15
+ **Problem:** `UNION` to combine detail rows and a total row into one result set. Mixes grains in one query — downstream code must detect which rows are totals vs. detail.
16
+
17
+ ```dax
18
+ // ❌ Avoid
19
+ DEFINE
20
+ VAR RegionBreakdown =
21
+ SUMMARIZECOLUMNS('Region'[Name], "Revenue", [Total Revenue])
22
+ VAR AllRegions =
23
+ ROW("Region[Name]", "All regions", "Revenue", CALCULATE([Total Revenue], ALL('Region')))
24
+
25
+ EVALUATE
26
+ UNION(AllRegions, RegionBreakdown)
27
+ ```
28
+
29
+ **Fix — separate grains:** Query the detail and summary grains separately, then pass the one-row summary table through `grandTotals.data`. See [Multi-grain patterns](multi-grain-patterns.md) for the filter-aware wiring.
30
+
31
+ **Alternative — DataGrid-computed SUM or COUNT:** Choose this when the user requests computed totals or a summary query is infeasible, but only for additive sums or a count of fetched leaf rows. Set `defaultAggregation` in the detail metadata and omit `grandTotals.data`.
32
+
33
+ ```typescript
34
+ // ✅ Factory metadata: DataGrid computed totals currently support only sum and count
35
+ export const columnMetadata: ColumnMetadataMap = {
36
+ "'Region'[Name]": { name: "RegionName", displayName: "Region" },
37
+ "[Revenue]": {
38
+ name: "Revenue",
39
+ displayName: "Revenue",
40
+ format: "$#,##0.00",
41
+ defaultAggregation: "sum",
42
+ },
43
+ };
44
+ ```
45
+
46
+ ```tsx
47
+ const detailTable = toDataTable(detail.data.table, columnMetadata);
48
+
49
+ <DataGrid
50
+ data={detailTable}
51
+ grandTotals={{ position: "bottom" }}
52
+ theme={theme}
53
+ />
54
+ ```
55
+
56
+ > **Rule of thumb:** Never sum grouped `DISTINCTCOUNT`, ratios, averages, or other non-additive results. Use a provided one-row `DataTable` for those totals, and never append it to the body data.
57
+
58
+ ## Anti-Pattern 2: FORMAT() for display labels
59
+
60
+ **Problem:** Converting numbers/dates to formatted strings in DAX.
61
+
62
+ ```dax
63
+ // ❌ Avoid — produces text that cannot be sorted or charted
64
+ EVALUATE
65
+ SUMMARIZECOLUMNS('Calendar'[Month], "Revenue", FORMAT([Total Revenue], "$#,##0"))
66
+ ```
67
+
68
+ **Fix:** Return raw values. Format via `columnMetadata` or Vega-Lite spec.
69
+
70
+ ```dax
71
+ // ✅ DAX: raw numeric value
72
+ EVALUATE
73
+ SUMMARIZECOLUMNS('Calendar'[Month], "Revenue", [Total Revenue])
74
+ ORDER BY 'Calendar'[Month]
75
+ ```
76
+
77
+ ```typescript
78
+ // ✅ Factory file: declare format in metadata (VBA/ECMA-376 format string)
79
+ export const columnMetadata: ColumnMetadataMap = {
80
+ "'Calendar'[Month]": { name: "CalendarMonth", displayName: "Month" },
81
+ "[Revenue]": { name: "Revenue", displayName: "Revenue", format: "$#,##0.00" },
82
+ };
83
+ ```
84
+
85
+ ## Anti-Pattern 3: Stringified dates
86
+
87
+ **Problem:** `FORMAT()` to turn dates into month-name strings.
88
+
89
+ ```dax
90
+ // ❌ Avoid — text values lose sort order and date semantics
91
+ EVALUATE
92
+ SUMMARIZECOLUMNS("Month Label", FORMAT('Calendar'[Date], "MMM YYYY"), "Sales", [Total Sales])
93
+ ```
94
+
95
+ **Fix:** Return sortable date. Let Vega-Lite format it.
96
+
97
+ ```dax
98
+ // ✅ DAX: return the date
99
+ EVALUATE
100
+ SUMMARIZECOLUMNS('Calendar'[Date], "Sales", [Total Sales])
101
+ ORDER BY 'Calendar'[Date]
102
+ ```
103
+
104
+ ```json
105
+ {
106
+ "encoding": {
107
+ "x": { "field": "CalendarDate", "type": "temporal", "axis": { "format": "%b %Y", "title": "Month" } }
108
+ }
109
+ }
110
+ ```
111
+
112
+ ## Anti-Pattern 4: Complex DAX for dimension completeness
113
+
114
+ **Problem:** Elaborate `GENERATE` / `CROSSJOIN` / `ADDMISSINGITEMS` to include dimension members with no data.
115
+
116
+ ```dax
117
+ // ❌ Avoid — hard to read, test, and maintain
118
+ EVALUATE
119
+ VAR AllRegions = ALL('Region'[Name])
120
+ VAR WithSales = SUMMARIZECOLUMNS('Region'[Name], "Sales", [Total Sales])
121
+ RETURN NATURALLEFTOUTERJOIN(AllRegions, WithSales)
122
+ ```
123
+
124
+ **Fix:** Two simple queries, stitched in TypeScript.
125
+
126
+ ```dax
127
+ // ✅ Query 1: detail data (only regions with sales)
128
+ EVALUATE SUMMARIZECOLUMNS('Region'[Name], "Sales", [Total Sales])
129
+ ORDER BY 'Region'[Name]
130
+ ```
131
+
132
+ ```dax
133
+ // ✅ Query 2: complete dimension list
134
+ EVALUATE ALL('Region'[Name])
135
+ ORDER BY 'Region'[Name]
136
+ ```
137
+
138
+ ```typescript
139
+ // ✅ TypeScript: merge into a DataTable
140
+ const detailTable = toDataTable(detail.data.table, detailMeta);
141
+ const dimsTable = toDataTable(dims.data.table, dimsMeta);
142
+ const salesMap = new Map(detailTable.rows.map(r => [r[0], r[1]]));
143
+ const filledRows = dimsTable.rows.map(r => [r[0], salesMap.get(r[0] as string) ?? 0]);
144
+ const filledTable: DataTable = { columns: detailTable.columns, rows: filledRows };
145
+ ```
146
+
147
+ **Alternative — Vega-Lite lookup transform:** Pass both tables to VegaVisual and join in the spec:
148
+
149
+ ```tsx
150
+ <VegaVisual spec={vegaLiteSpec} data={{ regions: dimsTable, sales: detailTable }} theme={theme} />
151
+ ```
152
+
153
+ ```json
154
+ {
155
+ "data": { "name": "regions" },
156
+ "transform": [
157
+ { "lookup": "RegionName", "from": { "data": { "name": "sales" }, "key": "RegionName", "fields": ["Sales"] } },
158
+ { "calculate": "datum.Sales ?? 0", "as": "Sales" }
159
+ ],
160
+ "mark": "bar",
161
+ "encoding": { "x": { "field": "RegionName" }, "y": { "field": "Sales", "type": "quantitative" } }
162
+ }
163
+ ```
164
+
165
+ > **Cardinality guardrail:** This pattern is for bounded axis dimensions (categories, regions, statuses) — not high-cardinality dimensions like customers or transaction IDs.
166
+
167
+ ## Anti-Pattern 5: Decorative text in DAX
168
+
169
+ **Problem:** Emoji, prefixes, or concatenated UI strings in DAX results.
170
+
171
+ ```dax
172
+ // ❌ Avoid — presentation logic in the data layer
173
+ EVALUATE
174
+ SUMMARIZECOLUMNS("Status", "✅ " & 'Order'[Status], "Count", COUNTROWS('Order'))
175
+ ```
176
+
177
+ **Fix:** Return raw data. Decorate via DataGrid `cellRenderer`.
178
+
179
+ ```dax
180
+ // ✅ DAX: raw status values
181
+ EVALUATE SUMMARIZECOLUMNS('Order'[Status], "Count", COUNTROWS('Order'))
182
+ ORDER BY 'Order'[Status]
183
+ ```
184
+
185
+ ```tsx
186
+ // ✅ DataGrid: decorate via cellRenderer
187
+ const columns: GridColumnDef[] = [
188
+ {
189
+ id: "OrderStatus",
190
+ header: "Status",
191
+ cellRenderer: (value) => (
192
+ <span>{value === "Complete" ? "✅" : "⏳"} {value as string}</span>
193
+ ),
194
+ },
195
+ { id: "Count", header: "Count" },
196
+ ];
197
+
198
+ <DataGrid columns={columns} data={dataTable} theme={theme} />
199
+ ```
200
+
201
+ ## Anti-Pattern 6: SELECTCOLUMNS for friendly names
202
+
203
+ **Problem:** Wrapping a query in SELECTCOLUMNS solely to rename columns. Adds complexity, breaks `ORDER BY` references, duplicates `columnMetadata`.
204
+
205
+ ```dax
206
+ // ❌ Avoid — SELECTCOLUMNS used only for renaming
207
+ DEFINE
208
+ VAR _Core = SUMMARIZECOLUMNS('Region'[Region Name], 'Product'[Category], "Total Revenue", [Total Revenue])
209
+ EVALUATE
210
+ SELECTCOLUMNS(_Core, "Region", 'Region'[Region Name], "Category", 'Product'[Category], "Revenue", [Total Revenue])
211
+ ```
212
+
213
+ **Fix:** Let DAX return natural column names. Map in `columnMetadata`.
214
+
215
+ ```dax
216
+ // ✅ Natural column names
217
+ EVALUATE
218
+ SUMMARIZECOLUMNS('Region'[Region Name], 'Product'[Category], "Total Revenue", [Total Revenue])
219
+ ORDER BY 'Region'[Region Name], 'Product'[Category]
220
+ ```
221
+
222
+ ```typescript
223
+ // ✅ Factory file: columnMetadata maps query schema → presentation
224
+ export const columnMetadata: ColumnMetadataMap = {
225
+ "'Region'[Region Name]": { name: "RegionRegion Name", displayName: "Region" },
226
+ "'Product'[Category]": { name: "ProductCategory", displayName: "Category" },
227
+ "[Total Revenue]": { name: "Total Revenue", displayName: "Revenue", format: "$#,##0.00" },
228
+ };
229
+ ```
230
+
231
+ The `columnMetadata` provides: `name` (cleaned identifier for Vega-Lite field references), `displayName` (human-readable caption for headers/axes), `format` (VBA/ECMA-376 format string for rendering — same syntax as the model's `FormatString`).
232
+
233
+ > **When SELECTCOLUMNS is appropriate:** Use it to project a subset of columns, compute derived columns (`RELATED(...)`), or reshape table structure — not as a cosmetic renaming layer.
234
+
235
+ ## Anti-Pattern 7: Converting BLANK to placeholder values
236
+
237
+ **Problem:** Replacing BLANK with `0` / `""` / `"N/A"` in DAX. `SUMMARIZECOLUMNS` auto-eliminates rows where all measures are BLANK. Converting BLANK to non-BLANK defeats this, causing result set explosion.
238
+
239
+ ```dax
240
+ // ❌ Avoid — alternate value 0 defeats BLANK elimination
241
+ EVALUATE
242
+ SUMMARIZECOLUMNS(
243
+ 'Product'[Category], 'Calendar'[Year],
244
+ "YoY Change", DIVIDE([Sales This Year] - [Sales Last Year], [Sales Last Year], 0),
245
+ "Sales", IF(ISBLANK([Total Sales]), 0, [Total Sales])
246
+ )
247
+ ```
248
+
249
+ **Fix:** Let BLANKs flow through. Handle at the component layer.
250
+
251
+ ```dax
252
+ // ✅ DAX: let BLANK remain BLANK — minimal result set
253
+ EVALUATE
254
+ SUMMARIZECOLUMNS(
255
+ 'Product'[Category], 'Calendar'[Year],
256
+ "YoY Change", DIVIDE([Sales This Year] - [Sales Last Year], [Sales Last Year]),
257
+ "Sales", [Total Sales]
258
+ )
259
+ ORDER BY 'Product'[Category], 'Calendar'[Year]
260
+ ```
261
+
262
+ ```tsx
263
+ // ✅ DataGrid: cellRenderer handles null values
264
+ const columns: GridColumnDef[] = [
265
+ { id: "ProductCategory", header: "Category" },
266
+ { id: "CalendarYear", header: "Year" },
267
+ {
268
+ id: "YoY Change",
269
+ header: "YoY Change",
270
+ cellRenderer: (value) =>
271
+ value == null ? <span className="text-muted-foreground">—</span>
272
+ : <span>{`${((value as number) * 100).toFixed(1)}%`}</span>,
273
+ },
274
+ {
275
+ id: "Sales",
276
+ header: "Sales",
277
+ cellRenderer: (value) =>
278
+ value == null ? <span className="text-muted-foreground">N/A</span> : undefined,
279
+ },
280
+ ];
281
+ ```
282
+
283
+ VegaVisual handles nulls natively — missing values become gaps in line charts or absent bars. No special handling needed unless you want custom tooltip/label behavior via Vega-Lite `condition` or `calculate` transforms.
284
+
285
+ > **Key insight:** `SUMMARIZECOLUMNS` skips rows where all measures are BLANK but not where they are `0` or `""`. Every BLANK-to-value conversion is a potential row-count multiplier. Use `DIVIDE(num, den)` without a third argument (defaults to BLANK).
@@ -0,0 +1,68 @@
1
+ # Filter Strategy
2
+
3
+ Interactive reports let users filter data by selecting values. Where filtering happens — in DAX or in TypeScript — is a trade-off between query cost and interaction speed.
4
+
5
+ ## Two Approaches
6
+
7
+ | Approach | How it works | Best when |
8
+ |---|---|---|
9
+ | **Widen the grain** | Include filter dimension as a group-by column, fetch all values upfront, filter client-side | Dimension is low-cardinality (a small set — roughly a few dozen values) and extra rows don't significantly increase result size |
10
+ | **Push filter to DAX** | Pass user's selection as a filter parameter, re-execute on each change | Dimension is high-cardinality (dates, customers) or including it forces expensive measure computation |
11
+
12
+ ## Widen the Grain (client-side filtering)
13
+
14
+ Fetching data broken down by the filter dimension makes interactions instant — no server round-trip.
15
+
16
+ ```dax
17
+ // Fetch data by region × category — filter by region client-side
18
+ EVALUATE
19
+ SUMMARIZECOLUMNS(
20
+ 'Region'[Name],
21
+ 'Product'[Category],
22
+ "Revenue", [Total Revenue]
23
+ )
24
+ ORDER BY 'Region'[Name], 'Product'[Category]
25
+ ```
26
+
27
+ ```typescript
28
+ // TypeScript: instant client-side filtering, producing a filtered DataTable
29
+ const dataTable = toDataTable(data.table, columnMetadata);
30
+ const regionIdx = dataTable.columns.findIndex(c => c.name === "RegionName");
31
+ const filteredTable: DataTable = {
32
+ columns: dataTable.columns,
33
+ rows: dataTable.rows.filter(row => row[regionIdx] === selectedRegion),
34
+ };
35
+
36
+ // Pass the filtered DataTable directly to VegaVisual or DataGrid
37
+ <VegaVisual spec={vegaLiteSpec} data={filteredTable} theme={theme} />
38
+ ```
39
+
40
+ **Alternative — Vega-Lite signal filtering:** Pass the full DataTable to VegaVisual and use a `transform.filter` or `selection` parameter for interactive filtering within the chart. This enables Vega-Lite's built-in features (click-to-select, linked highlighting across layers) without TypeScript involvement.
41
+
42
+ ## Push Filter to DAX (server-side filtering)
43
+
44
+ When the filter dimension would make the query too expensive — e.g., a date column forcing measure computation across hundreds of dates — push the filter into DAX and re-execute on each change.
45
+
46
+ ```dax
47
+ // Re-executed when selectedDate changes
48
+ DEFINE
49
+ VAR _DateFilter = TREATAS({DATE(2024, 3, 15)}, 'Calendar'[Date])
50
+
51
+ EVALUATE
52
+ SUMMARIZECOLUMNS(
53
+ 'Product'[Category],
54
+ _DateFilter,
55
+ "Revenue", [Total Revenue],
56
+ "Units Sold", [Total Quantity]
57
+ )
58
+ ORDER BY 'Product'[Category]
59
+ ```
60
+
61
+ The query is lighter (computes for one date only), but each filter change requires a server round-trip.
62
+
63
+ ## Choosing the Right Approach
64
+
65
+ - **Dimension cardinality** — low (a small set, e.g., a few dozen values) favors widening; high (dates, customers) favors pushing
66
+ - **Measure cost** — cheap measures (SUM) tolerate wider grains; expensive measures (DISTINCTCOUNT) favor pushing
67
+ - **Interaction frequency** — rapid filter changes (date slider scrubbing) favor client-side from pre-fetched wider grain
68
+ - **Result set size** — estimate rows × columns; if widening multiplies beyond what the browser can hold, push instead
@@ -0,0 +1,62 @@
1
+ # Format Strings
2
+
3
+ Power BI semantic models store format strings on columns and measures (`FormatString` in `INFO.VIEW.COLUMNS()` and `INFO.VIEW.MEASURES()`). Honor these model-defined formats rather than inventing your own.
4
+
5
+ ## Static Format Strings
6
+
7
+ Most model format strings are static (e.g., `"$#,##0.00"`, `"0.0%"`, `"yyyy-MM-dd"`). The `ColumnDef.format` field in `@microsoft/fabric-visuals-core` accepts VBA/ECMA-376 format strings — the same syntax used in Power BI semantic models. **No translation is needed**: copy the model's `FormatString` value directly into `columnMetadata.format`.
8
+
9
+ ```dax
10
+ // Discovery: fetch measure format strings
11
+ EVALUATE
12
+ SELECTCOLUMNS(
13
+ FILTER(INFO.VIEW.MEASURES(), [Table] = "Sales"),
14
+ "Measure", [Name],
15
+ "Format", [FormatString]
16
+ )
17
+ ORDER BY [Measure]
18
+ ```
19
+
20
+ ```typescript
21
+ // Factory file: use the model's FormatString directly (no conversion)
22
+ export const columnMetadata: ColumnMetadataMap = {
23
+ "[Total Revenue]": { name: "Total Revenue", displayName: "Revenue", format: "$#,##0.00" },
24
+ "[Margin %]": { name: "Margin", displayName: "Margin", format: "0.00%" },
25
+ "'Calendar'[Date]": { name: "CalendarDate", displayName: "Date", format: "yyyy-mm-dd" },
26
+ };
27
+ ```
28
+
29
+ VegaVisual and DataGrid each handle their own VBA→d3 conversion internally at ingestion time, so authors only ever work in VBA format.
30
+
31
+ ## Dynamic Format Strings
32
+
33
+ Some models use dynamic format strings — DAX expressions that produce different format strings depending on context (e.g., switching between "0.0 M" and "0.0 K" based on magnitude).
34
+
35
+ Fetch the resolved format string alongside the measure value using `IGNORE()`:
36
+
37
+ ```dax
38
+ // Fetch measure value + resolved dynamic format string
39
+ EVALUATE
40
+ SUMMARIZECOLUMNS(
41
+ 'Region'[Name],
42
+ "Revenue", [Total Revenue],
43
+ "Revenue Format", IGNORE([Total Revenue Format String])
44
+ )
45
+ ORDER BY 'Region'[Name]
46
+ ```
47
+
48
+ The resolved format string arrives as a per-row VBA/ECMA-376 string. Because the visual components expect VBA format strings, the per-row value can be passed through directly — no translation needed. Components that don't natively accept per-row formats (e.g., when injecting into a Vega-Lite axis spec) may require converting to d3 syntax at render time using helpers from `@microsoft/fabric-visuals-core`.
49
+
50
+ ## Pipeline Summary
51
+
52
+ ```text
53
+ Semantic Model (FormatString)
54
+ ├── static: read at discovery time via INFO.VIEW.*
55
+ └── dynamic: query alongside measure values via IGNORE()
56
+ ↓
57
+ Factory file (columnMetadata.format) — or per-row format values for dynamic
58
+ ↓
59
+ TypeScript / Vega-Lite spec — render formatted output
60
+ ```
61
+
62
+ > **Key principle:** DAX returns raw typed values. Format strings travel separately — either as static metadata in `columnMetadata` or as per-row data values for dynamic formats. Never use the `FORMAT()` DAX function to pre-render formatted strings in query results.
@@ -0,0 +1,122 @@
1
+ # Highlight Queries — Aligned Subsets for Cross-Highlight Overlays
2
+
3
+ A cross-highlight overlay layers a bright "selected subset" on a dimmed baseline. The subset comes from a fresh DAX query scoped by the selection — not from filtering the baseline result client-side.
4
+
5
+ For how the spec binds the two tables to two layers, see the visuals skill's [multi-data input](../../visuals/references/multi-data-input.md) reference. This page covers producing the subset table.
6
+
7
+ ## When you need this
8
+
9
+ A chart layers two datasets at the same axis grain (dimmed baseline + bright subset), and the bright layer reflects a selection made elsewhere on the page.
10
+
11
+ If the selection column is one of the chart's own encoding fields and you only need to dim non-matching rows, use Vega-Lite native selection in the spec — no query needed.
12
+
13
+ ## Re-aggregate, don't filter
14
+
15
+ The baseline and the subset are two separate queries. The subset query has:
16
+
17
+ - The **same grouping columns** as the baseline.
18
+ - The **same measure expressions** as the baseline.
19
+ - An **added filter** from the selection's predicates, via `CALCULATETABLE` + `TREATAS` / `KEEPFILTERS`.
20
+
21
+ Wrap the baseline aggregation in `CALCULATETABLE`:
22
+
23
+ ```dax
24
+ // Baseline
25
+ EVALUATE
26
+ SUMMARIZECOLUMNS('Product'[Category], "Sales", [Total Sales])
27
+ ORDER BY 'Product'[Category]
28
+ ```
29
+
30
+ ```dax
31
+ // Subset — selection: Rating ∈ {PG, PG-13}
32
+ EVALUATE
33
+ CALCULATETABLE(
34
+ SUMMARIZECOLUMNS('Product'[Category], "Sales", [Total Sales]),
35
+ TREATAS({"PG", "PG-13"}, 'Movie'[Rating])
36
+ )
37
+ ORDER BY 'Product'[Category]
38
+ ```
39
+
40
+ The model re-evaluates `[Total Sales]` under the added filter. `Movie[Rating]` doesn't appear in the result; the chart doesn't project it.
41
+
42
+ ## Match the baseline's row set
43
+
44
+ The two layers register by axis key. Every baseline row needs a counterpart in the subset, even when the selection matches no fact rows for that group.
45
+
46
+ `SUMMARIZECOLUMNS` drops groups where every measure is BLANK, which leaves gaps under baseline bars. Keep all rows one of two ways:
47
+
48
+ **Option A — coalesce the measure to zero:**
49
+
50
+ ```dax
51
+ EVALUATE
52
+ CALCULATETABLE(
53
+ SUMMARIZECOLUMNS('Product'[Category], "Sales", COALESCE([Total Sales], 0)),
54
+ TREATAS({"PG", "PG-13"}, 'Movie'[Rating])
55
+ )
56
+ ORDER BY 'Product'[Category]
57
+ ```
58
+
59
+ **Option B — left-join the baseline's group list** (use when zero is wrong, e.g. a ratio that must stay BLANK):
60
+
61
+ ```dax
62
+ EVALUATE
63
+ VAR Categories = SUMMARIZECOLUMNS('Product'[Category])
64
+ VAR Filtered =
65
+ CALCULATETABLE(
66
+ SUMMARIZECOLUMNS('Product'[Category], "Sales", [Total Sales]),
67
+ TREATAS({"PG", "PG-13"}, 'Movie'[Rating])
68
+ )
69
+ RETURN NATURALLEFTOUTERJOIN(Categories, Filtered)
70
+ ORDER BY 'Product'[Category]
71
+ ```
72
+
73
+ ## Build the filter from a selection
74
+
75
+ `DataPointSelection[]` is a disjunction (OR) of conjunctions (AND) of predicates:
76
+
77
+ - `SetPredicate` (`{ type: 'set', name, values }`) → `TREATAS(<values>, '<Table>'[<Column>])`.
78
+ - `RangePredicate` (`{ type: 'range', name, min, max }`) → `FILTER('<Table>', '<Table>'[<Column>] >= min && '<Table>'[<Column>] <= max)`.
79
+ - Multiple predicates in one selection → multiple filter arguments to the same `CALCULATETABLE` (AND).
80
+ - Multiple selections → `UNION` the per-selection filter tables inside one `KEEPFILTERS` argument (OR).
81
+
82
+ Assemble the query string in TypeScript and pass it to `useSemanticModelQuery`. Identical selections reuse the SDK's cache.
83
+
84
+ ## Wiring it in the component
85
+
86
+ The host component holds the selection (from another visual's `onInteraction`), fetches the aligned subset, and swaps the second named dataset on each change. Pass `{ all }` alone when there's no selection, `{ all, highlighted }` once a subset is fetched.
87
+
88
+ ```tsx
89
+ function SalesByCategoryChart({ selections }: { selections: DataPointSelection[] | null }) {
90
+ const theme = useCssTheme();
91
+ const all = useBaselineTable();
92
+ const highlighted = useHighlightedTable(selections); // scoped CALCULATETABLE query; null when no selection
93
+
94
+ return (
95
+ <VegaVisual
96
+ spec={vegaLiteSpec}
97
+ data={highlighted ? { all, highlighted } : { all }}
98
+ theme={theme}
99
+ />
100
+ );
101
+ }
102
+ ```
103
+
104
+ `useHighlightedTable` builds the scoped query from the selection's predicates (above) and runs it through `useSemanticModelQuery` — it does **not** filter `all` client-side. See the visuals [multi-data input](../../visuals/references/multi-data-input.md) reference for how the spec layers `all` and `highlighted`.
105
+
106
+ ## Keep baseline and subset in sync
107
+
108
+ When the baseline query changes, keep the subset query in sync with it:
109
+
110
+ - Same grouping columns, same order.
111
+ - Same measure name and expression — the spec's field reference (`y: { field: "Sales" }`) is shared by both layers.
112
+ - Same outer time / scope filters; the selection adds to them, it doesn't replace them.
113
+
114
+ Derive both from the same factory: the baseline query is the source; the subset query is `CALCULATETABLE(<baseline aggregation>, <selection predicates>)`.
115
+
116
+ ## Anti-patterns
117
+
118
+ - ❌ **Filtering the baseline DataTable client-side.** Cannot re-aggregate measures, apply RLS, or resolve selections on unprojected columns. Wrong subtotals for any non-SUM measure (DISTINCTCOUNT, ratios, AVERAGEX, complex measures).
119
+ - ❌ **`FILTER('FactTable', …)` instead of `TREATAS` on the dimension column.** Targets the wrong table, ignores relationships, slower.
120
+ - ❌ **Letting `SUMMARIZECOLUMNS` drop empty groups.** Causes axis-key gaps. Use `COALESCE` or a left-join.
121
+ - ❌ **Changing grain or column shape in the subset query.** The layers no longer share an axis.
122
+ - ❌ **`FORMAT()` in the subset query.** Stringified measures break the shared field encoding. Return raw types.