@microsoft/rayfin-semantic-model-pack 1.1.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.
- package/CHANGELOG +4 -0
- package/README.md +16 -5
- package/kit/hooks/use-query-factory-target.spec.ts +191 -0
- package/kit/hooks/use-query-factory-target.ts +123 -0
- package/kit/hooks/use-semantic-model-query.spec.ts +51 -34
- package/kit/hooks/use-semantic-model-query.ts +30 -49
- package/kit/lib/query-factory.spec.ts +97 -0
- package/kit/lib/query-factory.ts +68 -0
- package/kit/lib/semantic-model-errors.spec.ts +131 -0
- package/kit/lib/semantic-model-errors.ts +110 -0
- package/kit/lib/to-data-table.spec.ts +444 -0
- package/kit/lib/to-data-table.ts +221 -0
- package/pack.json +122 -25
- package/package.json +1 -1
- package/skills/analytics/SKILL.md +126 -422
- package/skills/dax-authoring/SKILL.md +98 -31
- package/skills/query-design/SKILL.md +22 -29
- package/skills/query-design/references/anti-patterns.md +13 -11
- package/skills/query-design/references/format-strings.md +6 -12
- package/skills/query-design/references/multi-grain-patterns.md +121 -108
- package/skills/schema-discovery/SKILL.md +197 -368
- package/skills/schema-discovery/references/discovery-queries.md +6 -8
- package/skills/visual-interactivity/SKILL.md +68 -0
- package/skills/visual-interactivity/references/advanced-query-shapes.md +155 -0
- package/skills/visual-interactivity/references/filter-aware-grid-totals.md +101 -0
- package/skills/visual-interactivity/references/highlight-queries.md +88 -0
- package/skills/visual-interactivity/references/interaction-manager.md +127 -0
- package/skills/visual-interactivity/references/native-selections.md +20 -0
- package/skills/visual-interactivity/references/query-factories.md +169 -0
- package/kit/scripts/rayfin-connector.mjs +0 -265
- package/kit/scripts/rayfin-connector.test.mjs +0 -243
- package/kit/scripts/schema-sql-batch.test.mjs +0 -2097
- package/kit/scripts/schema-sql-cli.test.mjs +0 -488
- package/kit/scripts/schema-sql.mjs +0 -2650
- package/kit/scripts/schema-sql.test.mjs +0 -1387
- package/kit/scripts/schema.mjs +0 -166
- package/kit/scripts/schema.test.mjs +0 -271
- package/skills/query-design/references/filter-strategy.md +0 -68
- 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
|
|
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
|
|
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:
|
|
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
|
|
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
|
-
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
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,37 +141,97 @@ Consult [dax-time-intelligence.md](./references/dax-time-intelligence.md) whenev
|
|
|
134
141
|
|
|
135
142
|
## Testing & Iteration
|
|
136
143
|
|
|
137
|
-
1.
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
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
|
|
189
|
+
Use:
|
|
146
190
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
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
|
-
```
|
|
154
|
-
|
|
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
|
-
|
|
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
|
+
|
|
158
223
|
|
|
159
|
-
|
|
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.
|
|
160
228
|
|
|
161
229
|
## Troubleshooting
|
|
162
230
|
|
|
163
231
|
| Problem | Solution |
|
|
164
232
|
|---------|----------|
|
|
165
|
-
|
|
|
166
|
-
| `connector
|
|
167
|
-
| `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 |
|
|
168
235
|
| DAX syntax errors | Consult [dax-core-reference.md](./references/dax-core-reference.md) — check reserved keywords, quoting rules, EVALUATE/scalar mistakes |
|
|
169
236
|
| Unexpected query results | Check filter context, relationship direction, BLANK handling in [dax-core-reference.md](./references/dax-core-reference.md#blank-semantics) |
|
|
170
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,
|
|
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
|
-
|
|
|
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
|
-
|
|
|
27
|
-
|
|
|
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
|
|
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
|
-
-
|
|
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
|
|
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
|
|
58
|
-
-
|
|
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
|
-
```
|
|
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
|
-
| ->
|
|
72
|
-
| -> High-cardinality: push filter to DAX, re-query
|
|
74
|
+
| -> Use the visual-interactivity skill
|
|
73
75
|
|-- Adding a DataGrid grand total?
|
|
74
|
-
| -> DAX
|
|
75
|
-
|
|
|
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
|
|
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)** —
|
|
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
|
|
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`
|
|
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 —
|
|
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
|
|
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
|
-
"
|
|
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
|
|
47
|
+
const bodyTable = toDataTable(body.data.table, columnMetadata);
|
|
48
48
|
|
|
49
49
|
<DataGrid
|
|
50
|
-
data={
|
|
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.
|
|
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
|
-
"
|
|
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
|
-
"
|
|
226
|
-
"
|
|
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
|
-
```
|
|
10
|
-
|
|
11
|
-
|
|
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
|
-
"
|
|
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
|
-
```
|
|
46
|
+
```
|
|
53
47
|
Semantic Model (FormatString)
|
|
54
|
-
├── static: read
|
|
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
|