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