@microsoft/rayfin-semantic-model-pack 1.0.0 → 2.0.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.
Files changed (41) hide show
  1. package/CHANGELOG +8 -0
  2. package/README.md +34 -10
  3. package/kit/hooks/use-query-factory-target.spec.ts +191 -0
  4. package/kit/hooks/use-query-factory-target.ts +123 -0
  5. package/{skills/analytics/kit → kit}/hooks/use-semantic-model-query.spec.ts +59 -23
  6. package/{skills/analytics/kit → kit}/hooks/use-semantic-model-query.ts +30 -54
  7. package/kit/lib/query-factory.spec.ts +97 -0
  8. package/kit/lib/query-factory.ts +68 -0
  9. package/kit/lib/semantic-model-errors.spec.ts +131 -0
  10. package/kit/lib/semantic-model-errors.ts +110 -0
  11. package/kit/lib/to-data-table.spec.ts +444 -0
  12. package/kit/lib/to-data-table.ts +221 -0
  13. package/pack.json +141 -0
  14. package/package.json +3 -1
  15. package/skills/analytics/SKILL.md +126 -421
  16. package/skills/dax-authoring/SKILL.md +99 -34
  17. package/skills/query-design/SKILL.md +22 -29
  18. package/skills/query-design/references/anti-patterns.md +13 -11
  19. package/skills/query-design/references/format-strings.md +6 -12
  20. package/skills/query-design/references/multi-grain-patterns.md +121 -108
  21. package/skills/schema-discovery/SKILL.md +197 -368
  22. package/skills/schema-discovery/references/discovery-queries.md +6 -8
  23. package/skills/visual-interactivity/SKILL.md +68 -0
  24. package/skills/visual-interactivity/references/advanced-query-shapes.md +155 -0
  25. package/skills/visual-interactivity/references/filter-aware-grid-totals.md +101 -0
  26. package/skills/visual-interactivity/references/highlight-queries.md +88 -0
  27. package/skills/visual-interactivity/references/interaction-manager.md +127 -0
  28. package/skills/visual-interactivity/references/native-selections.md +20 -0
  29. package/skills/visual-interactivity/references/query-factories.md +169 -0
  30. package/skills/analytics/kit/lib/connectors.ts +0 -94
  31. package/skills/analytics/kit/scripts/rayfin-connector.mjs +0 -265
  32. package/skills/analytics/kit/scripts/rayfin-connector.test.mjs +0 -243
  33. package/skills/analytics/kit/scripts/schema-sql-batch.test.mjs +0 -2097
  34. package/skills/analytics/kit/scripts/schema-sql-cli.test.mjs +0 -488
  35. package/skills/analytics/kit/scripts/schema-sql.mjs +0 -2650
  36. package/skills/analytics/kit/scripts/schema-sql.test.mjs +0 -1387
  37. package/skills/analytics/kit/scripts/schema.mjs +0 -166
  38. package/skills/analytics/kit/scripts/schema.test.mjs +0 -271
  39. package/skills/analytics/pack.json +0 -49
  40. package/skills/query-design/references/filter-strategy.md +0 -68
  41. package/skills/query-design/references/highlight-queries.md +0 -122
@@ -1,166 +0,0 @@
1
- //-----------------------------------------------------------------------
2
- // <copyright company="Microsoft Corporation">
3
- // Copyright (c) Microsoft Corporation. All rights reserved.
4
- // Licensed under the MIT license. See LICENSE file in the project root for full license information.
5
- // </copyright>
6
- //-----------------------------------------------------------------------
7
-
8
- import {
9
- invokeConnector,
10
- listConfiguredConnectors,
11
- } from './rayfin-connector.mjs';
12
-
13
- export function normalizeColName(name) {
14
- const match = String(name).match(/\[([^\]]+)\]\s*$/);
15
- return match ? match[1] : String(name);
16
- }
17
-
18
- export function isFabricGuid(value) {
19
- return /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/iu.test(String(value));
20
- }
21
-
22
- export function parseQueryOutput(value) {
23
- if (!value) {
24
- return { ok: false, error: 'No output from query.' };
25
- }
26
- if (value.status === 'error') {
27
- const message = value.error?.message ?? value.error;
28
- return {
29
- ok: false,
30
- error: String(message || 'Unknown query error.'),
31
- };
32
- }
33
- const table =
34
- value.table ?? (Array.isArray(value.tables) ? value.tables[0] : undefined);
35
- if (!table || !Array.isArray(table.columns) || !Array.isArray(table.rows)) {
36
- return {
37
- ok: false,
38
- error: 'Query result did not contain a table.',
39
- };
40
- }
41
- const columns = table.columns.map((column) => ({
42
- name: normalizeColName(column?.name),
43
- dataType:
44
- typeof column?.dataType === 'string' ? column.dataType : 'unknown',
45
- }));
46
- const rows = table.rows.map((row) => {
47
- const record = {};
48
- columns.forEach((column, index) => {
49
- record[column.name] = Array.isArray(row) ? row[index] : undefined;
50
- });
51
- return record;
52
- });
53
- return { ok: true, columns, rows };
54
- }
55
-
56
- export async function runFabricQuery(dax, options = {}) {
57
- const {
58
- alias,
59
- limit,
60
- cwd = process.cwd(),
61
- invoke = invokeConnector,
62
- } = options;
63
- const result = await invoke({
64
- connector: alias,
65
- query: dax,
66
- limit,
67
- cwd,
68
- });
69
- if (!result.ok) {
70
- return { ok: false, error: result.error };
71
- }
72
- return parseQueryOutput(result.output);
73
- }
74
-
75
- async function semanticModelConnectors(options = {}) {
76
- const result = await listConfiguredConnectors(options);
77
- if (!result.ok) {
78
- return result;
79
- }
80
- return {
81
- ok: true,
82
- connectors: result.connectors.filter(
83
- (connector) =>
84
- connector?.type === 'fabric-semanticmodel' &&
85
- typeof connector.name === 'string' &&
86
- connector.name.length > 0
87
- ),
88
- };
89
- }
90
-
91
- export async function resolveAlias(cwd, explicit, options = {}) {
92
- if (explicit) {
93
- return { alias: explicit };
94
- }
95
- const result = await semanticModelConnectors({ cwd, ...options });
96
- if (!result.ok) {
97
- return { error: result.error };
98
- }
99
- const aliases = result.connectors.map((connector) => connector.name);
100
- if (aliases.length === 0) {
101
- return {
102
- error:
103
- 'No semantic model connector is configured. Connect one first:\n\n' +
104
- ' npx rayfin connector add --type fabric-semanticmodel ' +
105
- '--workspace-id <workspace-id> --item-id <item-id> --name model',
106
- };
107
- }
108
- if (aliases.length > 1) {
109
- return {
110
- error:
111
- `This app is connected to ${aliases.length} semantic models: ` +
112
- `${aliases.join(', ')}.\n\n` +
113
- ` npm run --silent schema:sql -- --alias ${aliases[0]} "SELECT ..."`,
114
- };
115
- }
116
- // Hand back the connector too: resolveIdentity needs the same record, and
117
- // re-listing costs another CLI spawn on every command.
118
- return { alias: aliases[0], connector: result.connectors[0] };
119
- }
120
-
121
- export async function resolveIdentity(options = {}) {
122
- const {
123
- alias,
124
- connector: known,
125
- cwd = process.cwd(),
126
- list = listConfiguredConnectors,
127
- } = options;
128
- if (!alias) {
129
- return {};
130
- }
131
- let connector = known;
132
- if (!connector) {
133
- const result = await list({ cwd });
134
- if (!result.ok) {
135
- return { error: result.error };
136
- }
137
- connector = result.connectors.find(
138
- (entry) =>
139
- entry?.type === 'fabric-semanticmodel' &&
140
- typeof entry.name === 'string' &&
141
- entry.name.toLocaleLowerCase() === String(alias).toLocaleLowerCase()
142
- );
143
- }
144
- if (!connector) {
145
- return {
146
- error:
147
- `Semantic model connector "${alias}" was not found. ` +
148
- 'Run `npx rayfin connector list --json` from the app root.',
149
- };
150
- }
151
- const datasetId = connector.config?.itemId;
152
- if (!isFabricGuid(datasetId)) {
153
- return {
154
- error:
155
- `Semantic model connector "${alias}" has an invalid itemId. ` +
156
- 'Reconnect it with `npx rayfin connector add`.',
157
- };
158
- }
159
- return {
160
- datasetId,
161
- workspaceId:
162
- typeof connector.config?.workspaceId === 'string'
163
- ? connector.config.workspaceId
164
- : null,
165
- };
166
- }
@@ -1,271 +0,0 @@
1
- //-----------------------------------------------------------------------
2
- // <copyright company="Microsoft Corporation">
3
- // Copyright (c) Microsoft Corporation. All rights reserved.
4
- // Licensed under the MIT license. See LICENSE file in the project root for full license information.
5
- // </copyright>
6
- //-----------------------------------------------------------------------
7
-
8
- import assert from 'node:assert/strict';
9
- import { EventEmitter } from 'node:events';
10
- import test from 'node:test';
11
-
12
- import {
13
- isFabricGuid,
14
- normalizeColName,
15
- parseQueryOutput,
16
- resolveAlias,
17
- resolveIdentity,
18
- runFabricQuery,
19
- } from './schema.mjs';
20
-
21
- const DATASET_ID = '11111111-2222-3333-4444-555555555555';
22
- const WORKSPACE_ID = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';
23
-
24
- const connectors = [
25
- {
26
- name: 'sales',
27
- type: 'fabric-semanticmodel',
28
- config: { workspaceId: WORKSPACE_ID, itemId: DATASET_ID },
29
- },
30
- {
31
- name: 'sql',
32
- type: 'fabric-sql',
33
- config: { workspaceId: 'ws-2', itemId: 'wh-1' },
34
- },
35
- ];
36
-
37
- test('resolveIdentity uses connector list output instead of parsing rayfin.yml', async () => {
38
- const identity = await resolveIdentity({
39
- alias: 'SALES',
40
- list: async () => ({ ok: true, connectors }),
41
- });
42
- assert.deepEqual(identity, {
43
- datasetId: DATASET_ID,
44
- workspaceId: WORKSPACE_ID,
45
- });
46
- });
47
-
48
- test('resolveIdentity rejects a connector itemId that is not a GUID', async () => {
49
- const identity = await resolveIdentity({
50
- alias: 'sales',
51
- list: async () => ({
52
- ok: true,
53
- connectors: [
54
- {
55
- name: 'sales',
56
- type: 'fabric-semanticmodel',
57
- config: { itemId: '../outside' },
58
- },
59
- ],
60
- }),
61
- });
62
- assert.match(identity.error, /invalid itemId/i);
63
- assert.equal(isFabricGuid('../outside'), false);
64
- assert.equal(isFabricGuid(DATASET_ID), true);
65
- });
66
-
67
- test('resolveIdentity returns a readable resolution error', async () => {
68
- const identity = await resolveIdentity({
69
- alias: 'sales',
70
- list: async () => ({
71
- ok: false,
72
- error:
73
- 'Could not resolve connectors because connector list returned empty stdout.',
74
- }),
75
- });
76
- assert.match(identity.error, /Could not resolve connectors/i);
77
- });
78
-
79
- test('resolveAlias treats a list launch failure as a resolution error', async () => {
80
- const out = await resolveAlias('.', undefined, {
81
- cliEntry: 'rayfin-entry',
82
- spawnImpl: () => {
83
- throw new Error('This test injects at the list boundary instead.');
84
- },
85
- });
86
- assert.match(
87
- out.error,
88
- /Could not run the Rayfin CLI/i,
89
- 'a failed list command must be a resolution error, not zero connectors'
90
- );
91
- });
92
-
93
- test('resolveAlias selects the only semantic-model connector', async () => {
94
- const out = await resolveAlias('.', undefined, {
95
- cliEntry: 'rayfin-entry',
96
- spawnImpl: () => {
97
- const child = new EventEmitter();
98
- child.stdout = new EventEmitter();
99
- child.stderr = new EventEmitter();
100
- queueMicrotask(() => {
101
- child.stdout.emit('data', JSON.stringify(connectors));
102
- child.emit('close', 0, null);
103
- });
104
- return child;
105
- },
106
- });
107
- assert.equal(out.alias, 'sales');
108
- assert.equal(out.connector?.name, 'sales');
109
- });
110
-
111
- test('resolveAlias gives a valid connector add command when none exist', async () => {
112
- const out = await resolveAlias('.', undefined, {
113
- cliEntry: 'rayfin-entry',
114
- spawnImpl: () => {
115
- const child = new EventEmitter();
116
- child.stdout = new EventEmitter();
117
- child.stderr = new EventEmitter();
118
- queueMicrotask(() => {
119
- child.stdout.emit('data', '[]');
120
- child.emit('close', 0, null);
121
- });
122
- return child;
123
- },
124
- });
125
- assert.match(out.error, /--type fabric-semanticmodel/u);
126
- assert.match(out.error, /--workspace-id <workspace-id>/u);
127
- assert.match(out.error, /--item-id <item-id>/u);
128
- assert.doesNotMatch(out.error, /--url/u);
129
- });
130
-
131
- test('resolveAlias honors an explicit alias without running the CLI', async () => {
132
- assert.deepEqual(await resolveAlias('.', 'sales'), { alias: 'sales' });
133
- });
134
-
135
- test('parseQueryOutput preserves Rayfin column names', () => {
136
- const result = parseQueryOutput({
137
- status: 'success',
138
- table: {
139
- columns: [{ name: '[Table]' }, { name: '[Max Length]' }],
140
- rows: [['Sales', 12]],
141
- },
142
- });
143
- assert.deepEqual(result, {
144
- ok: true,
145
- columns: [
146
- { name: 'Table', dataType: 'unknown' },
147
- { name: 'Max Length', dataType: 'unknown' },
148
- ],
149
- rows: [{ Table: 'Sales', 'Max Length': 12 }],
150
- });
151
- assert.equal(normalizeColName('plain'), 'plain');
152
- });
153
-
154
- test('parseQueryOutput does not implement the dead _cliWarning branch', () => {
155
- const result = parseQueryOutput({
156
- status: 'success',
157
- _cliWarning: 'Result trimmed to first 1000 of 1492 rows',
158
- table: {
159
- columns: [{ name: '[Name]' }],
160
- rows: [['Sales']],
161
- },
162
- });
163
- assert.deepEqual(result, {
164
- ok: true,
165
- columns: [{ name: 'Name', dataType: 'unknown' }],
166
- rows: [{ Name: 'Sales' }],
167
- });
168
- assert.equal(
169
- Object.hasOwn(result, 'truncated'),
170
- false,
171
- 'Rayfin reports query overflow as a hard error, not _cliWarning'
172
- );
173
- });
174
-
175
- test('runFabricQuery imports invokeConnector directly and makes one invoke', async () => {
176
- const calls = [];
177
- const result = await runFabricQuery('EVALUATE INFO.VIEW.TABLES()', {
178
- alias: 'sales',
179
- cwd: 'C:\\app',
180
- invoke: async (options) => {
181
- calls.push(options);
182
- return {
183
- ok: true,
184
- output: {
185
- status: 'success',
186
- table: {
187
- columns: [{ name: '[Name]', dataType: 'String' }],
188
- rows: [['Sales']],
189
- },
190
- },
191
- };
192
- },
193
- });
194
- assert.equal(calls.length, 1);
195
- assert.deepEqual(calls[0], {
196
- connector: 'sales',
197
- query: 'EVALUATE INFO.VIEW.TABLES()',
198
- limit: undefined,
199
- cwd: 'C:\\app',
200
- });
201
- assert.deepEqual(result.columns, [{ name: 'Name', dataType: 'String' }]);
202
- assert.deepEqual(result.rows, [{ Name: 'Sales' }]);
203
- });
204
-
205
- test('one CLI spawn resolves both the alias and the dataset id', async () => {
206
- // resolveAlias already holds the connector record; re-listing it in
207
- // resolveIdentity doubled the spawn count on every schema:sql call.
208
- const connectors = [
209
- {
210
- name: 'model',
211
- type: 'fabric-semanticmodel',
212
- config: { itemId: '11111111-2222-3333-4444-555555555555' },
213
- },
214
- ];
215
- let spawns = 0;
216
- const spawnImpl = () => {
217
- spawns += 1;
218
- const child = new EventEmitter();
219
- child.stdout = new EventEmitter();
220
- child.stderr = new EventEmitter();
221
- queueMicrotask(() => {
222
- child.stdout.emit('data', JSON.stringify(connectors));
223
- child.emit('close', 0, null);
224
- });
225
- return child;
226
- };
227
- const cli = { cliEntry: 'rayfin-entry', spawnImpl };
228
-
229
- const resolved = await resolveAlias('.', undefined, cli);
230
- assert.equal(resolved.alias, 'model');
231
- assert.equal(spawns, 1);
232
-
233
- const identity = await resolveIdentity({
234
- alias: resolved.alias,
235
- connector: resolved.connector,
236
- ...cli,
237
- });
238
- assert.equal(identity.datasetId, '11111111-2222-3333-4444-555555555555');
239
- assert.equal(spawns, 1, 'the second lookup reuses the first result');
240
- });
241
-
242
- test('an explicit --alias still resolves its dataset id', async () => {
243
- // resolveAlias returns early for an explicit alias and has no record to
244
- // pass on, so resolveIdentity falls back to its own lookup.
245
- let calls = 0;
246
- const list = async () => {
247
- calls += 1;
248
- return {
249
- ok: true,
250
- connectors: [
251
- {
252
- name: 'model',
253
- type: 'fabric-semanticmodel',
254
- config: { itemId: '11111111-2222-3333-4444-555555555555' },
255
- },
256
- ],
257
- };
258
- };
259
-
260
- const resolved = await resolveAlias('.', 'model');
261
- assert.equal(resolved.alias, 'model');
262
- assert.equal(resolved.connector, undefined);
263
-
264
- const identity = await resolveIdentity({
265
- alias: resolved.alias,
266
- connector: resolved.connector,
267
- list,
268
- });
269
- assert.equal(identity.datasetId, '11111111-2222-3333-4444-555555555555');
270
- assert.equal(calls, 1);
271
- });
@@ -1,49 +0,0 @@
1
- {
2
- "name": "analytics",
3
- "description": "Power BI / semantic-model analytics: the `fabric-semanticmodel` connector and the semantic-model query hook. Add the visuals pack alongside it to chart what the queries return.",
4
- "packageJson": "packages/frontend/package.json",
5
- "rayfin": {
6
- "services": {
7
- "connectors": {
8
- "enabled": true
9
- }
10
- }
11
- },
12
- "dependencies": {
13
- "@microsoft/rayfin-connectors": "match:@microsoft/rayfin-core",
14
- "@microsoft/rayfin-connector-fabric-semanticmodel": "match:@microsoft/rayfin-core"
15
- },
16
- "scripts": {
17
- "schema:sql": "node --disable-warning=ExperimentalWarning scripts/schema-sql.mjs",
18
- "schema:refresh": "node --disable-warning=ExperimentalWarning scripts/schema-sql.mjs --refresh"
19
- },
20
- "scriptFlags": {
21
- "schema:sql": "schema-sqlite",
22
- "schema:refresh": "schema-sqlite"
23
- },
24
- "gitignore": [".schema/", ".rayfin-schema-query-*/"],
25
- "copy": [
26
- { "from": "kit/hooks", "to": "packages/frontend/src/hooks" },
27
- {
28
- "from": "kit/lib/connectors.ts",
29
- "to": "packages/frontend/src/lib/connectors.ts",
30
- "initializationOnly": true
31
- },
32
- {
33
- "from": "kit/scripts/rayfin-connector.mjs",
34
- "to": "scripts/rayfin-connector.mjs",
35
- "whenFlag": "schema-sqlite"
36
- },
37
- {
38
- "from": "kit/scripts/schema.mjs",
39
- "to": "scripts/schema.mjs",
40
- "whenFlag": "schema-sqlite"
41
- },
42
- {
43
- "from": "kit/scripts/schema-sql.mjs",
44
- "to": "scripts/schema-sql.mjs",
45
- "whenFlag": "schema-sqlite"
46
- }
47
- ],
48
- "next": ["analytics"]
49
- }
@@ -1,68 +0,0 @@
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
@@ -1,122 +0,0 @@
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.