@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
@@ -3,7 +3,7 @@ name: dax-authoring
3
3
  description: >
4
4
  Write and test DAX queries against Power BI semantic models.
5
5
  Covers DAX syntax rules, query patterns, time intelligence,
6
- and an iterative test workflow using `npx rayfin connector invoke`.
6
+ and an iterative test workflow using `npx fabric-app-semantic-model-tools run-dax-query --dax <file> --alias <name>`.
7
7
  ---
8
8
 
9
9
  # DAX Authoring
@@ -17,7 +17,7 @@ description: >
17
17
  | DAX Query Structure & Syntax | [dax-query-patterns.md: Query Structure](./references/dax-query-patterns.md#query-structure) | DEFINE / EVALUATE / ORDER BY / START AT |
18
18
  | DAX Query Key Components | [dax-query-patterns.md: Key Components](./references/dax-query-patterns.md#key-components) | DEFINE VAR, DEFINE MEASURE, table expressions |
19
19
  | DAX Query Worked Examples | [dax-query-patterns.md: Common Patterns](./references/dax-query-patterns.md#common-patterns) | 11 annotated examples from simple aggregation to cross-table joins |
20
- | DAX Query Anti-Patterns | [dax-query-patterns.md: Anti-Patterns](./references/dax-query-patterns.md#anti-patterns) | What to avoid in DAX queries |
20
+ | DAX Query Syntax Mistakes | [dax-query-patterns.md: Syntax Mistakes](./references/dax-query-patterns.md#syntax-mistakes) | SQL keywords, method chaining, and scalar EVALUATE |
21
21
  | CALCULATE & CALCULATETABLE | [dax-core-reference.md: CALCULATE & CALCULATETABLE](./references/dax-core-reference.md#calculate--calculatetable) | Context transition, filter types, boolean restrictions, common patterns |
22
22
  | SUMMARIZECOLUMNS | [dax-core-reference.md: SUMMARIZECOLUMNS](./references/dax-core-reference.md#summarizecolumns) | Argument order, auto-blank elimination, filter args, vs SUMMARIZE |
23
23
  | ALL & ALLEXCEPT | [dax-core-reference.md: ALL & ALLEXCEPT](./references/dax-core-reference.md#all--allexcept) | CALCULATE modifier vs table function; percentage patterns |
@@ -30,7 +30,7 @@ description: >
30
30
  | YTD / QTD / MTD | [dax-time-intelligence.md: Period-to-Date](./references/dax-time-intelligence.md#period-to-date) | TOTALYTD, DATESYTD, DATESINPERIOD patterns |
31
31
  | Year-over-Year / Period Comparisons | [dax-time-intelligence.md: Period Comparisons](./references/dax-time-intelligence.md#period-comparisons) | SAMEPERIODLASTYEAR, DATEADD, PARALLELPERIOD |
32
32
  | Rolling Windows | [dax-time-intelligence.md: Rolling Windows](./references/dax-time-intelligence.md#rolling-windows) | DATESINPERIOD rolling 12-month patterns |
33
- | Opening/Closing Balances | [dax-time-intelligence.md: Balances](./references/dax-time-intelligence.md#balances) | Semi-additive measures, LASTDATE, LASTNONBLANK |
33
+ | Opening/Closing Balances | [dax-time-intelligence.md: Opening/Closing Balance Functions](./references/dax-time-intelligence.md#openingclosing-balance-functions) | Opening and closing balance function reference |
34
34
  | TI in DAX Queries (Critical Rules) | [dax-time-intelligence.md: Critical Rules for TI in Queries](./references/dax-time-intelligence.md#critical-rules-for-ti-in-dax-queries) | CALCULATETABLE + TREATAS pattern for query context |
35
35
  | TI Common Mistakes | [dax-time-intelligence.md: Common Mistakes](./references/dax-time-intelligence.md#common-mistakes) | Missing date table, wrong granularity, fiscal calendar |
36
36
  | Testing & Iteration | [SKILL.md: Testing & Iteration](#testing--iteration) | Execute → inspect → fix → re-test workflow |
@@ -39,25 +39,32 @@ description: >
39
39
 
40
40
  ### Must
41
41
 
42
- - Always test generated DAX via `npx rayfin connector invoke <alias> executeQuery --file <query>.query.json` before using in app code
42
+ - Always test generated DAX before using it in app code. Execute each planned `.dax` file once
43
+ through `npx fabric-app-semantic-model-tools run-dax-query` and compare its report with the schema-discovery plan.
44
+ Batch independent queries for the current visual batch in one call (up to four files);
45
+ do not turn incremental UI assembly into one CLI invocation per visual.
46
+ - Run DAX through `run-dax-query`, not `npx rayfin connector invoke`; `run-dax-query` runs Rayfin CLI
47
+ calls one at a time.
43
48
  - Use fully-qualified `'Table'[Column]` for column references
44
49
  - Use simple `[Measure]` for measure references
45
50
  - Use DEFINE for VAR and local MEASURE declarations (single DEFINE block, no commas)
46
- - Prefer existing model measures over re-aggregating raw data
47
- - **Never reshape a stored measure to work around a decoding bug.** Wrapping it
48
- in `CONVERT(...)` changes the value the app reads, and `CONVERT([Measure],
49
- DOUBLE)` silently drops every row whose branch returned text. If the CLI and
50
- the app disagree by a power of ten, check that both carry a connector build
51
- with the Arrow union decoder fix — `@microsoft/rayfin-cli` bundles its own
52
- copy, and the app installs `@microsoft/rayfin-connector-fabric-semanticmodel`
53
- separately under `packages/frontend`, so upgrading one does not update the
54
- other. Fix the build, keep the measure.
51
+ - Use existing model measures for requested business metrics. Raw aggregation is allowed only when
52
+ the schema workflow established that no suitable shipped measure exists. Never replace a shipped
53
+ measure with raw `SUM`, `COUNT`, `COUNTROWS`, `AVERAGE`, `DISTINCTCOUNT`, or a local
54
+ approximation
55
+ - Generate DAX from the completed schema-discovery plan; do not rediscover or substitute model objects
56
+ - Before using a query's output in a data-backed visual, execute that query successfully and
57
+ pass its planned shape and semantic validation gates, resolving or explaining warnings.
58
+ This gate applies to the current visual batch, not layout scaffolding or the whole app.
59
+ Mount passing visuals as the batch becomes ready; do not wait for unrelated queries.
60
+ - Follow the consuming template's instructions for sequencing UI that does not depend on DAX results.
55
61
 
56
62
  ### Prefer
57
63
 
58
64
  - SUMMARIZECOLUMNS as the primary grouping function for queries
59
65
  - TREATAS for filter arguments in SUMMARIZECOLUMNS
60
66
  - Variables (VAR) to improve readability and avoid repeated calculations
67
+ - Shipped measures from measure-heavy KPI tables
61
68
 
62
69
  ### Avoid
63
70
 
@@ -134,39 +141,97 @@ Consult [dax-time-intelligence.md](./references/dax-time-intelligence.md) whenev
134
141
 
135
142
  ## Testing & Iteration
136
143
 
137
- 1. Generate the DAX query expression
138
- 2. Execute via `npx rayfin connector invoke <alias> executeQuery --file <query>.query.json`
139
- 3. Inspect results: check column names, data types, row counts, and actual data values
140
- 4. If error: consult [dax-core-reference.md](./references/dax-core-reference.md), fix, and re-test
141
- 5. Iterate until the query returns expected results
144
+ 1. Use the completed schema-discovery plan: exact shipped measures, grouping columns, filters,
145
+ relationship path, expected columns, and row shape
146
+ 2. Author one `EVALUATE` for each distinct query the plan requires, and execute each final query
147
+ once with `run-dax-query` (see [Query Execution](#query-execution))
148
+ 3. Treat an execution error as a query failure. A successful result is not by itself proof of
149
+ correctness, and an empty one is not an error. Compare the reported columns, row count, sample,
150
+ and warnings with the plan's exact output columns, row shape, filters, ordering, grain, and
151
+ value expectations
152
+ 4. Reject all-blank output, unexplained all-zero grouped output, distinct requested outputs that
153
+ repeat the same measure/value, and all-rank-1 output when comparison or ordering is expected.
154
+ These are semantic mismatches even when the command succeeds; do not build the UI from them
155
+ 5. If an error or semantic mismatch remains, inspect the output-binding map, helper or parameter
156
+ filter context, relationships, and filters; consult
157
+ [dax-core-reference.md](./references/dax-core-reference.md), make one evidence-based correction
158
+ to only the failing query, and re-test it
159
+ 6. Stop each distinct planned query after it returns a structurally and semantically consistent
160
+ result. Across the task, run one optional grain diagnostic for a shared ambiguity; for each
161
+ distinct query, run one validation and at most one evidence-based corrective retry. Do not use
162
+ this allowance for exploratory model probing or repeated discovery
163
+
164
+ Preserve the selected candidate by editing the validated query rather than regenerating it.
165
+
166
+ ### Result reuse and stopping
167
+
168
+ - Before running a query, check whether a previous result already contains the answer. Never rerun
169
+ an identical or equivalent DAX query.
170
+ - A zero scalar is valid. An all-zero grouped result is not validated for a task that expects
171
+ meaningful comparison unless task or catalog evidence shows that all zeros are legitimate.
172
+ - For a blank or empty result, inspect the shipped measure, relationship path, grouping dimension,
173
+ helper-table filter context, and filters. Make one correction; accept a corrected blank only when
174
+ the requested semantics allow no data.
175
+ - If every grouped row returns the same measure value, first investigate a disconnected grouping
176
+ table or ineffective filter propagation. Do not rewrite or replace the measure to manufacture
177
+ variation.
178
+ - If every row ranks 1, verify that the rank expression evaluates over the intended comparison set
179
+ and that filters did not collapse that set before accepting the result.
180
+ - On timeout, narrow filters, reduce grouping cardinality, apply `TOPN`, or simplify only the
181
+ failing planned query. Never retry the same query unchanged.
182
+ - Preserve successful batched outputs. Correct only failed or semantically inconsistent files.
183
+ - Reuse grounded model mappings across visuals. A new spec, layout, or metadata alias does not
184
+ require another schema discovery or `run-dax-query` call for unchanged DAX and source context.
185
+ Run the consuming app's visual validator for affected specs/metadata.
142
186
 
143
187
  ## Query Execution
144
188
 
145
- Use `npx rayfin connector invoke <alias> executeQuery --file <query>.query.json` to run queries. This uses the same SDK pipeline as the running app, so results are identical to what the app produces at runtime. `--file` takes the operation's JSON input envelope — `{"query":"EVALUATE …"}` — not a bare `.dax` file, which is `JSON.parse`d and fails. Prefer it over `--input` for anything non-trivial: DAX is full of quotes and brackets that a shell reads as syntax. For full CLI options, see `npx rayfin connector invoke --help`.
189
+ Use:
146
190
 
147
- **There is no row cap.** A query with no `resultSetRowCountLimit` returns every
148
- row it matches, on the CLI and in the app alike, so an unbounded `EVALUATE` over
149
- a large table is a real hazard rather than a truncated preview. Bound it
150
- yourself — either in the DAX with an aggregation or `TOPN(...)`, or by adding the
151
- field to the input envelope:
191
+ ```bash
192
+ npx fabric-app-semantic-model-tools run-dax-query \
193
+ --dax src/queries/revenue.dax \
194
+ --alias <alias>
195
+ ```
196
+
197
+ Each `.dax` file must contain one `EVALUATE`; otherwise nothing executes. For two to four planned
198
+ queries, repeat `--dax` in one call:
152
199
 
153
- ```json
154
- { "query": "EVALUATE Sales", "resultSetRowCountLimit": 500 }
200
+ ```bash
201
+ npx fabric-app-semantic-model-tools run-dax-query --dax src/queries/a.dax --dax src/queries/b.dax --alias <alias>
155
202
  ```
156
203
 
157
- Prefer the field over `TOPN` when you want a guard rather than a deliberately
158
- ranked subset: exceeding it **fails** the query with an `overflow` error, so a
159
- bound that was too tight announces itself, where `TOPN` returns a
160
- complete-looking partial answer. A value that is not a positive integer is
161
- dropped silently and the query runs unbounded.
204
+ The queries run one at a time, through the same connector operation as the running app. For each
205
+ query the command prints its status, output column names, row count, first rows
206
+ (`--sample <n>`, default 5), and warnings, not the full result. Warnings flag no rows, an all-blank
207
+ column, or a measure output (not a `Table[Column]` grouping column) that is all zero, constant, all
208
+ rank 1, or identical to another output; identical outputs are reported as one group. Warnings are
209
+ nonfatal prompts for review, not proof of correctness. A shortened preview is not complete shape
210
+ evidence.
211
+
212
+ A failed query keeps its own entry beside the successful ones, and the call exits 2: correct only
213
+ the failed queries. Missing, malformed, unreadable, or overflowed results never pass, and input or
214
+ read failures also exit nonzero; an error message alone does not show that a query ran. An
215
+ `overflow` result has no table; see
216
+ [analytics](../analytics/SKILL.md#runtime-contract).
217
+
218
+ **Row count:** a query returns every row unless you bound it. Bound it with the aggregation the plan
219
+ calls for, and use `TOPN(...)` only when the request asks for a ranked subset or to bound a query
220
+ that timed out. `--limit <n>` is a guard, not a cap: validation fails when more than `n` rows come
221
+ back.
222
+
223
+
224
+ `resultSetRowCountLimit` silently truncates, so exactly that many returned rows may
225
+ be incomplete. `withValidatedRowLimit` drops values that are not positive integers,
226
+ leaving no explicit limit on the request. This SDK option is separate from the
227
+ tools command's `--limit` validation guard and numeric `overflow` errors.
162
228
 
163
229
  ## Troubleshooting
164
230
 
165
231
  | Problem | Solution |
166
232
  |---------|----------|
167
- | `connector invoke` fails with "not signed in" | Run `npx rayfin login` |
168
- | `connector invoke` fails with "alias not found" | Run `npx rayfin connector list` to check available aliases, then `npx rayfin connector add --type fabric-semanticmodel` to register |
169
- | `connector invoke` fails with "Do not know how to serialize a BigInt" | A measure whose branches return different types decodes as an Arrow union; connector builds without the union decoder fix leave some of its cells unconverted. Update the connector build — do not reshape the stored measure (see Must) |
233
+ | A connector query fails because no Power BI token can be acquired without a sign-in prompt | Follow the recovery text printed with the error; re-running `npx rayfin login` does not fix it. |
234
+ | `query-schema` cannot resolve the connector, or a query names a connector that `rayfin.yml` does not declare | Run `npx rayfin connector list --json` to check declared connectors, then `npx rayfin connector add` to register the intended model |
170
235
  | DAX syntax errors | Consult [dax-core-reference.md](./references/dax-core-reference.md) — check reserved keywords, quoting rules, EVALUATE/scalar mistakes |
171
236
  | Unexpected query results | Check filter context, relationship direction, BLANK handling in [dax-core-reference.md](./references/dax-core-reference.md#blank-semantics) |
172
237
  | Time intelligence returns wrong values | Check date table prerequisites and critical rules in [dax-time-intelligence.md](./references/dax-time-intelligence.md) |
@@ -3,8 +3,7 @@ name: query-design
3
3
  description: >
4
4
  Separates DAX data-fetching from TypeScript presentation. Guides when to use
5
5
  DAX vs. TypeScript vs. Vega-Lite for aggregation, total rows, FORMAT(), SELECTCOLUMNS,
6
- BLANK handling, filtering, multi-grain queries, cross-filtering and
7
- cross-highlight subset/overlay queries, and format strings.
6
+ BLANK handling, fixed filters, multi-grain queries, and format strings.
8
7
  ---
9
8
 
10
9
  # Query Design — Separation of Data and Presentation
@@ -18,17 +17,20 @@ Aggregate in DAX to the visual's grain — never fetch lower-grain rows to roll
18
17
  | Concern | Owner |
19
18
  |---|---|
20
19
  | Semantic measures (SUM, DISTINCTCOUNT, etc.) | DAX |
21
- | Filters and slicers | DAX or TypeScript ([see Filter Strategy](references/filter-strategy.md)) |
20
+ | Fixed model/page filters | DAX |
21
+ | User-controlled visual filters | [visual-interactivity](../visual-interactivity/SKILL.md) + DAX query factories |
22
22
  | Grouping grain (SUMMARIZECOLUMNS) | DAX |
23
23
  | Time intelligence (YTD, YoY) | DAX |
24
24
  | TopN / payload reduction | DAX |
25
25
  | Deterministic row ordering (ORDER BY) | DAX (for debugging — not presentation sort) |
26
- | Merging multiple result sets | TypeScript |
27
- | Server-provided grand totals (preferred, supports all aggregation types) | DAX |
26
+ | Partitioning a flagged result table | TypeScript |
27
+ | Coordinating separate query results | Managed target loaders for interacting visuals; matched result sets for independent tables |
28
+ | Server-provided grand totals (preferred, supports all aggregation types) | DAX + TypeScript row partitioning |
28
29
  | DataGrid-computed grand totals | DataGrid (alternative only for additive `sum` values or a count of fetched leaf rows) |
29
30
  | Filling dimension gaps | TypeScript (stitch dimension list into sparse results) |
30
31
  | Reshaping (pivot, unpivot) | TypeScript |
31
32
  | Column display names | `columnMetadata` in factory file |
33
+ | Vega-Lite / DataGrid field identifiers | `columnMetadata.name` (bracket-free alias) |
32
34
  | Number/date formatting | `columnMetadata.format` / Vega-Lite spec |
33
35
  | User-facing sort order | TypeScript / Vega-Lite `sort` / DataGrid `sort` |
34
36
  | Decorative labels, icons | DataGrid `cellRenderer` or Vega-Lite condition |
@@ -39,23 +41,24 @@ Aggregate in DAX to the visual's grain — never fetch lower-grain rows to roll
39
41
  ### Must
40
42
 
41
43
  - Aggregate in DAX to the visual's grain — never fetch lower-grain rows just to roll them up to that grain in TypeScript
42
- - One grain per `.dax` file (one `EVALUATE` per file); separate grains → separate files + separate `useSemanticModelQuery` calls
44
+ - One `EVALUATE` per `.dax` file; use `ROLLUPADDISSUBTOTAL` when DataGrid body and grand-total grains share one result table
43
45
  - `ORDER BY` in DAX for stable, diffable results — not presentation sort
44
46
  - Same filters/measures across related split-grain queries to prevent drift
45
47
 
46
48
  ### Prefer
47
49
 
48
50
  - `SUMMARIZECOLUMNS` for grouped aggregation — it also drops BLANK-measure rows, keeping payloads small
49
- - DAX's natural column names (`'Table'[Column]`, `[Measure]`) mapped via `columnMetadata.displayName`
51
+ - Exact raw output column names (`Table[Column]`, `[Measure]`) as `columnMetadata` **keys**, mapped to a bracket-free `name` and a human-readable `displayName`
50
52
  - Raw typed values from DAX — format via `columnMetadata.format` or Vega-Lite, never `FORMAT()`
51
53
  - Model-defined format strings (from `INFO.VIEW.MEASURES()`) over invented ones
52
- - Multiple lightweight queries over one monolithic query
54
+ - Multiple lightweight queries for independently shaped datasets; one flagged rollup query for a DataGrid body and grand total
53
55
  - User-facing sort in TypeScript / Vega-Lite / DataGrid — never re-query for sort
54
56
 
55
57
  ### Avoid
56
58
 
57
- - `SELECTCOLUMNS` solely for renaming — use `columnMetadata.displayName` instead
58
- - `UNION` to mix different grains (detail + total) — use separate queries
59
+ - `SELECTCOLUMNS` solely for renaming — use `columnMetadata` (`name` + `displayName`) instead
60
+ - Reusing the raw DAX column name as `columnMetadata.name` — `[` `]` `.` make the visual read `undefined`
61
+ - `UNION` to mix body and total grains — use `ROLLUPADDISSUBTOTAL` and partition its flagged rows
59
62
  - `FORMAT()` in DAX — converts to text, breaks sorting and charting
60
63
  - Converting BLANK to `0` / `""` / `"N/A"` in DAX — causes result-set explosion
61
64
  - `CONCATENATEX`, `UNICHAR`, emoji prefixes — decorative text belongs in `cellRenderer` or Vega-Lite
@@ -63,16 +66,16 @@ Aggregate in DAX to the visual's grain — never fetch lower-grain rows to roll
63
66
 
64
67
  ## Decision Flowchart
65
68
 
66
- ```text
69
+ ```
67
70
  Need to add something to the query result?
68
- |-- Calculation / aggregation / filter?
71
+ |-- Calculation / aggregation / fixed scope filter?
69
72
  | -> DAX (measures, CALCULATE, SUMMARIZECOLUMNS)
70
73
  |-- Interactive filter the user controls?
71
- | -> Low-cardinality: widen grain, filter in TypeScript or Vega-Lite transform
72
- | -> High-cardinality: push filter to DAX, re-query
74
+ | -> Use the visual-interactivity skill
73
75
  |-- Adding a DataGrid grand total?
74
- | -> DAX summary query: pass its one-row DataTable via grandTotals.data
75
- | -> DataGrid-computed sum/count: set defaultAggregation, omit grandTotals.data
76
+ | -> DAX rollup query: split body and total rows with toRollupDataTables
77
+ | and always pass the returned grandTotalTable via grandTotals.data
78
+ | -> DataGrid-computed sum/count: pass grandTotals without data and set defaultAggregation
76
79
  |-- Merging datasets or adding other synthetic rows?
77
80
  | -> Charts: pass multiple DataTables to VegaVisual, layer in spec
78
81
  | -> Grids: append rows in TypeScript, style via cellRenderer
@@ -88,27 +91,17 @@ Need to add something to the query result?
88
91
  Still unclear? -> Read the relevant reference above
89
92
  ```
90
93
 
91
- ## Interactivity
92
-
93
- Reports coordinate multiple visuals: a selection in one changes what the others show. Two distinct behaviors, with different data work behind them:
94
-
95
- - **Cross-filtering** — a selection in one visual constrains the data shown in another, removing or narrowing the non-matching rows from the target's view. The target shows *less*. Applying that constraint is a cost/cardinality tradeoff — widen the grain and filter client-side, or push the filter into DAX and re-query. See [Filter strategy](references/filter-strategy.md).
96
- - **Cross-highlighting** — a selection in one visual emphasizes the matching subset *within* another while the full context stays visible. The target keeps its baseline (dimmed) and draws the selected subset bright on top. The subset is a separate aggregation aligned to the baseline's grouping, measures, and row set — not a client-side filter of the baseline. See [Highlight queries](references/highlight-queries.md).
97
-
98
- Both consume the predicate-based selection events the visual components emit (`onInteraction`). The components render only the `DataTable`s they are handed; this skill produces those tables. For how a spec binds and layers multiple datasets, see the visuals skill's [multi-data input](../visuals/references/multi-data-input.md) reference.
99
-
100
94
  ## Reference Materials
101
95
 
102
96
  Read these when working on a specific topic:
103
97
 
104
98
  - **[Anti-patterns and corrections](references/anti-patterns.md)** — Open when reviewing a query that uses `UNION` for totals, `FORMAT()`, `SELECTCOLUMNS` for renaming, `CONCATENATEX`/emoji decoration, BLANK-to-`0` conversion, or `GENERATE`/`CROSSJOIN` for gap-filling.
105
- - **[Multi-grain patterns](references/multi-grain-patterns.md)** — Open when a single visualization needs data at two grains (e.g., bars + grand-total reference line, region detail + total row, monthly trend + YTD).
106
- - **[Filter strategy](references/filter-strategy.md)** — Open when adding a user-controlled filter or implementing cross-filtering, and deciding whether to widen the grain (filter client-side) or push the filter into DAX (re-query on each change).
107
- - **[Highlight queries](references/highlight-queries.md)** — Open when writing the "selected subset" overlay query for a cross-highlight visual: an aligned `CALCULATETABLE` / `TREATAS` query whose rows match the baseline.
99
+ - **[Multi-grain patterns](references/multi-grain-patterns.md)** — Open when a single visualization needs data at multiple grains (e.g., bars + reference line, region detail + total row, monthly trend + YTD), to choose between one flagged rollup result and separate queries while keeping related factories, hooks, and `DataTable`s aligned.
108
100
  - **[Format strings](references/format-strings.md)** — Open when picking a `columnMetadata.format` value, when a measure has a dynamic format string, or when formatting needs to flow into a Vega-Lite axis.
109
101
 
110
102
  ## Integration with Sibling Skills
111
103
 
112
- - **[schema-discovery](../schema-discovery/SKILL.md)** — Schema exploration; discover tables, columns, and relationships before writing queries.
104
+ - **[schema-discovery](../schema-discovery/SKILL.md)** — Query exact tables, columns, measures, and relationships before writing queries.
113
105
  - **[dax-authoring](../dax-authoring/SKILL.md)** — DAX syntax, query patterns, and testing workflow. Apply this skill's principles when deciding what DAX should compute.
114
106
  - **[visuals](../visuals/SKILL.md)** — Vega-Lite specs and DataGrid configuration. Push formatting and labels into specs, not DAX.
107
+ - **[visual-interactivity](../visual-interactivity/SKILL.md)** — Managed selections, complete compiled DAX filters, target loading, aligned highlights, filter-aware totals and refresh/error states.
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## Contents
4
4
 
5
- 1. [UNION to mix grains](#anti-pattern-1-union-to-mix-grains) — combining detail rows + a total row in one query
5
+ 1. [UNION to mix grains](#anti-pattern-1-union-to-mix-grains) — manually combining body rows + a total row
6
6
  2. [FORMAT() for display labels](#anti-pattern-2-format-for-display-labels) — converting numbers to formatted strings in DAX
7
7
  3. [Stringified dates](#anti-pattern-3-stringified-dates) — turning dates into month-name strings in DAX
8
8
  4. [Complex DAX for dimension completeness](#anti-pattern-4-complex-dax-for-dimension-completeness) — GENERATE/CROSSJOIN to force-include empty dimension members
@@ -12,7 +12,7 @@
12
12
 
13
13
  ## Anti-Pattern 1: UNION to mix grains
14
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.
15
+ **Problem:** `UNION` manually combines body rows and a total row without a standard grain discriminator.
16
16
 
17
17
  ```dax
18
18
  // ❌ Avoid
@@ -26,14 +26,14 @@ EVALUATE
26
26
  UNION(AllRegions, RegionBreakdown)
27
27
  ```
28
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.
29
+ **Fix — flagged rollup:** Use `ROLLUPADDISSUBTOTAL` so DAX evaluates the same expressions at the body and grand-total grains. Return one result table, split it with `toRollupDataTables()`, and pass the returned `grandTotalTable` through `grandTotals.data`. See [Multi-grain patterns](multi-grain-patterns.md) for the filter-aware query and wiring.
30
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`.
31
+ **Alternative — DataGrid-computed SUM or COUNT:** Choose this when the user requests computed totals or a rollup query is infeasible, but only for additive sums or a count of fetched leaf rows. Omit `grandTotals.data` and set `defaultAggregation` in the body metadata.
32
32
 
33
33
  ```typescript
34
34
  // ✅ Factory metadata: DataGrid computed totals currently support only sum and count
35
35
  export const columnMetadata: ColumnMetadataMap = {
36
- "'Region'[Name]": { name: "RegionName", displayName: "Region" },
36
+ "Region[Name]": { name: "RegionName", displayName: "Region" },
37
37
  "[Revenue]": {
38
38
  name: "Revenue",
39
39
  displayName: "Revenue",
@@ -44,16 +44,16 @@ export const columnMetadata: ColumnMetadataMap = {
44
44
  ```
45
45
 
46
46
  ```tsx
47
- const detailTable = toDataTable(detail.data.table, columnMetadata);
47
+ const bodyTable = toDataTable(body.data.table, columnMetadata);
48
48
 
49
49
  <DataGrid
50
- data={detailTable}
50
+ data={bodyTable}
51
51
  grandTotals={{ position: "bottom" }}
52
52
  theme={theme}
53
53
  />
54
54
  ```
55
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.
56
+ > **Rule of thumb:** Never sum grouped `DISTINCTCOUNT`, ratios, averages, or other non-additive results. Let the rollup query evaluate them at grand-total context, and never append the resulting total to the body data.
57
57
 
58
58
  ## Anti-Pattern 2: FORMAT() for display labels
59
59
 
@@ -77,7 +77,7 @@ ORDER BY 'Calendar'[Month]
77
77
  ```typescript
78
78
  // ✅ Factory file: declare format in metadata (VBA/ECMA-376 format string)
79
79
  export const columnMetadata: ColumnMetadataMap = {
80
- "'Calendar'[Month]": { name: "CalendarMonth", displayName: "Month" },
80
+ "Calendar[Month]": { name: "CalendarMonth", displayName: "Month" },
81
81
  "[Revenue]": { name: "Revenue", displayName: "Revenue", format: "$#,##0.00" },
82
82
  };
83
83
  ```
@@ -222,14 +222,16 @@ ORDER BY 'Region'[Region Name], 'Product'[Category]
222
222
  ```typescript
223
223
  // ✅ Factory file: columnMetadata maps query schema → presentation
224
224
  export const columnMetadata: ColumnMetadataMap = {
225
- "'Region'[Region Name]": { name: "RegionRegion Name", displayName: "Region" },
226
- "'Product'[Category]": { name: "ProductCategory", displayName: "Category" },
225
+ "Region[Region Name]": { name: "RegionName", displayName: "Region" },
226
+ "Product[Category]": { name: "ProductCategory", displayName: "Category" },
227
227
  "[Total Revenue]": { name: "Total Revenue", displayName: "Revenue", format: "$#,##0.00" },
228
228
  };
229
229
  ```
230
230
 
231
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
232
 
233
+ > **`name` must be bracket-free.** Never copy the raw DAX column name into `name`. Vega-Lite reads `.`, `[`, and `]` in a field reference as property/array accessors, so `Store[StoreNumberName]` silently resolves to `undefined` and the visual renders empty. See [Vega-Lite field names](../../visuals/references/vega-lite-visual.md#field-names).
234
+
233
235
  > **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
236
 
235
237
  ## Anti-Pattern 7: Converting BLANK to placeholder values
@@ -6,15 +6,9 @@ Power BI semantic models store format strings on columns and measures (`FormatSt
6
6
 
7
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
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]
9
+ ```bash
10
+ # Discovery: read measure format strings from the catalog
11
+ npx fabric-app-semantic-model-tools query-schema "SELECT [Name], [FormatString] FROM info_view_measures WHERE [Table] = 'Sales'"
18
12
  ```
19
13
 
20
14
  ```typescript
@@ -22,7 +16,7 @@ ORDER BY [Measure]
22
16
  export const columnMetadata: ColumnMetadataMap = {
23
17
  "[Total Revenue]": { name: "Total Revenue", displayName: "Revenue", format: "$#,##0.00" },
24
18
  "[Margin %]": { name: "Margin", displayName: "Margin", format: "0.00%" },
25
- "'Calendar'[Date]": { name: "CalendarDate", displayName: "Date", format: "yyyy-mm-dd" },
19
+ "Calendar[Date]": { name: "CalendarDate", displayName: "Date", format: "yyyy-mm-dd" },
26
20
  };
27
21
  ```
28
22
 
@@ -49,9 +43,9 @@ The resolved format string arrives as a per-row VBA/ECMA-376 string. Because the
49
43
 
50
44
  ## Pipeline Summary
51
45
 
52
- ```text
46
+ ```
53
47
  Semantic Model (FormatString)
54
- ├── static: read at discovery time via INFO.VIEW.*
48
+ ├── static: read from the catalog's [FormatString] with query-schema
55
49
  └── dynamic: query alongside measure values via IGNORE()
56
50
  ↓
57
51
  Factory file (columnMetadata.format) — or per-row format values for dynamic