@microsoft/rayfin-semantic-model-pack 0.0.0-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG +14 -0
- package/LICENSE +21 -0
- package/README.md +78 -2
- package/kit/hooks/use-semantic-model-query.spec.ts +361 -0
- package/kit/hooks/use-semantic-model-query.ts +224 -0
- package/kit/scripts/rayfin-connector.mjs +265 -0
- package/kit/scripts/rayfin-connector.test.mjs +243 -0
- package/kit/scripts/schema-sql-batch.test.mjs +2097 -0
- package/kit/scripts/schema-sql-cli.test.mjs +488 -0
- package/kit/scripts/schema-sql.mjs +2650 -0
- package/kit/scripts/schema-sql.test.mjs +1387 -0
- package/kit/scripts/schema.mjs +166 -0
- package/kit/scripts/schema.test.mjs +271 -0
- package/pack.json +44 -0
- package/package.json +12 -3
- package/skills/analytics/SKILL.md +461 -0
- package/skills/dax-authoring/SKILL.md +170 -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,347 @@
|
|
|
1
|
+
# DAX Time Intelligence
|
|
2
|
+
|
|
3
|
+
Time intelligence functions enable period-based analysis by shifting or filtering date ranges relative to the current filter context. They require a properly configured Date table.
|
|
4
|
+
|
|
5
|
+
## Prerequisites
|
|
6
|
+
|
|
7
|
+
### Date Table Requirements
|
|
8
|
+
|
|
9
|
+
Time intelligence functions require a Date table with:
|
|
10
|
+
|
|
11
|
+
1. **Contiguous dates**: No gaps in the date sequence
|
|
12
|
+
2. **Unique dates**: One row per day
|
|
13
|
+
3. **Marked as Date Table**: In Power BI, right-click the table and select "Mark as date table"
|
|
14
|
+
4. **Active relationship**: Single active relationship between Date table and fact tables
|
|
15
|
+
|
|
16
|
+
## Function Categories
|
|
17
|
+
|
|
18
|
+
| Category | Purpose | Key Functions |
|
|
19
|
+
|----------|---------|---------------|
|
|
20
|
+
| Period-to-Date | Cumulative from period start | DATESYTD, DATESQTD, DATESMTD, DATESWTD |
|
|
21
|
+
| Period Shifting | Move dates by interval | DATEADD, SAMEPERIODLASTYEAR, PARALLELPERIOD |
|
|
22
|
+
| Opening/Closing Balance | Values at period boundaries | OPENINGBALANCEYEAR, CLOSINGBALANCEMONTH |
|
|
23
|
+
| Total-to-Date | Aggregate to period end | TOTALYTD, TOTALQTD, TOTALMTD, TOTALWTD |
|
|
24
|
+
| Period Navigation | First/last dates | FIRSTDATE, LASTDATE, STARTOFMONTH, ENDOFYEAR |
|
|
25
|
+
| Date Ranges | Custom date sets | DATESINPERIOD, DATESBETWEEN |
|
|
26
|
+
|
|
27
|
+
## Period-to-Date
|
|
28
|
+
|
|
29
|
+
### Using DATESYTD / DATESQTD / DATESMTD
|
|
30
|
+
|
|
31
|
+
```dax
|
|
32
|
+
Sales YTD = CALCULATE([Total Sales], DATESYTD('Date'[Date]))
|
|
33
|
+
Sales QTD = CALCULATE([Total Sales], DATESQTD('Date'[Date]))
|
|
34
|
+
Sales MTD = CALCULATE([Total Sales], DATESMTD('Date'[Date]))
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### Using TOTALYTD / TOTALQTD / TOTALMTD (Shorthand)
|
|
38
|
+
|
|
39
|
+
```dax
|
|
40
|
+
// Equivalent to CALCULATE with DATESYTD
|
|
41
|
+
Sales YTD = TOTALYTD([Total Sales], 'Date'[Date])
|
|
42
|
+
|
|
43
|
+
// With fiscal year ending June 30
|
|
44
|
+
Sales FY YTD = TOTALYTD([Total Sales], 'Date'[Date], "6/30")
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Period Comparisons
|
|
48
|
+
|
|
49
|
+
### Year-over-Year Using SAMEPERIODLASTYEAR
|
|
50
|
+
|
|
51
|
+
```dax
|
|
52
|
+
Sales PY =
|
|
53
|
+
CALCULATE([Total Sales], SAMEPERIODLASTYEAR('Date'[Date]))
|
|
54
|
+
|
|
55
|
+
Sales YoY Change =
|
|
56
|
+
VAR CurrentSales = [Total Sales]
|
|
57
|
+
VAR PYSales = [Sales PY]
|
|
58
|
+
RETURN CurrentSales - PYSales
|
|
59
|
+
|
|
60
|
+
Sales YoY % =
|
|
61
|
+
VAR CurrentSales = [Total Sales]
|
|
62
|
+
VAR PYSales = [Sales PY]
|
|
63
|
+
RETURN DIVIDE(CurrentSales - PYSales, PYSales)
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Flexible Period Shift Using DATEADD
|
|
67
|
+
|
|
68
|
+
```dax
|
|
69
|
+
// Previous month
|
|
70
|
+
Sales PM = CALCULATE([Total Sales], DATEADD('Date'[Date], -1, MONTH))
|
|
71
|
+
|
|
72
|
+
// Previous quarter
|
|
73
|
+
Sales PQ = CALCULATE([Total Sales], DATEADD('Date'[Date], -1, QUARTER))
|
|
74
|
+
|
|
75
|
+
// Same period 2 years ago
|
|
76
|
+
Sales 2YA = CALCULATE([Total Sales], DATEADD('Date'[Date], -2, YEAR))
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### PARALLELPERIOD vs DATEADD
|
|
80
|
+
|
|
81
|
+
```dax
|
|
82
|
+
// PARALLELPERIOD: Returns complete parallel period
|
|
83
|
+
// If March is selected, returns all of February
|
|
84
|
+
Sales Parallel Month =
|
|
85
|
+
CALCULATE([Total Sales], PARALLELPERIOD('Date'[Date], -1, MONTH))
|
|
86
|
+
|
|
87
|
+
// DATEADD: Shifts each date individually
|
|
88
|
+
// If March 1-15 is selected, returns Feb 1-15
|
|
89
|
+
Sales Shifted Month =
|
|
90
|
+
CALCULATE([Total Sales], DATEADD('Date'[Date], -1, MONTH))
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
**Key difference**: PARALLELPERIOD returns the complete period, DATEADD shifts individual dates.
|
|
94
|
+
|
|
95
|
+
## Rolling Windows
|
|
96
|
+
|
|
97
|
+
### Using DATESINPERIOD
|
|
98
|
+
|
|
99
|
+
```dax
|
|
100
|
+
// Rolling 12 months
|
|
101
|
+
Sales Rolling 12M =
|
|
102
|
+
CALCULATE(
|
|
103
|
+
[Total Sales],
|
|
104
|
+
DATESINPERIOD('Date'[Date], MAX('Date'[Date]), -12, MONTH)
|
|
105
|
+
)
|
|
106
|
+
|
|
107
|
+
// Last 30 days
|
|
108
|
+
Sales Last 30 Days =
|
|
109
|
+
CALCULATE(
|
|
110
|
+
[Total Sales],
|
|
111
|
+
DATESINPERIOD('Date'[Date], MAX('Date'[Date]), -30, DAY)
|
|
112
|
+
)
|
|
113
|
+
|
|
114
|
+
// Rolling 4 quarters
|
|
115
|
+
Sales Rolling 4Q =
|
|
116
|
+
CALCULATE(
|
|
117
|
+
[Total Sales],
|
|
118
|
+
DATESINPERIOD('Date'[Date], MAX('Date'[Date]), -4, QUARTER)
|
|
119
|
+
)
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Using DATESBETWEEN for Custom Ranges
|
|
123
|
+
|
|
124
|
+
```dax
|
|
125
|
+
// Custom date range
|
|
126
|
+
Sales Custom Range =
|
|
127
|
+
CALCULATE(
|
|
128
|
+
[Total Sales],
|
|
129
|
+
DATESBETWEEN('Date'[Date], DATE(2024, 1, 1), DATE(2024, 6, 30))
|
|
130
|
+
)
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Period Navigation
|
|
134
|
+
|
|
135
|
+
```dax
|
|
136
|
+
First Sale Date = FIRSTDATE('Date'[Date])
|
|
137
|
+
Last Sale Date = LASTDATE('Date'[Date])
|
|
138
|
+
Start of Current Month = STARTOFMONTH('Date'[Date])
|
|
139
|
+
End of Current Year = ENDOFYEAR('Date'[Date])
|
|
140
|
+
Previous Month Dates = PREVIOUSMONTH('Date'[Date])
|
|
141
|
+
Next Quarter Dates = NEXTQUARTER('Date'[Date])
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## Combined Patterns
|
|
145
|
+
|
|
146
|
+
### YTD for Previous Year
|
|
147
|
+
|
|
148
|
+
```dax
|
|
149
|
+
Sales PY YTD =
|
|
150
|
+
CALCULATE([Total Sales], DATESYTD(SAMEPERIODLASTYEAR('Date'[Date])))
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### YoY Comparison of YTD Values
|
|
154
|
+
|
|
155
|
+
```dax
|
|
156
|
+
Sales YTD YoY =
|
|
157
|
+
VAR CurrentYTD = [Sales YTD]
|
|
158
|
+
VAR PYYTD = [Sales PY YTD]
|
|
159
|
+
RETURN DIVIDE(CurrentYTD - PYYTD, PYYTD)
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### Rolling Average
|
|
163
|
+
|
|
164
|
+
```dax
|
|
165
|
+
Sales 3M Moving Avg =
|
|
166
|
+
DIVIDE(
|
|
167
|
+
CALCULATE(
|
|
168
|
+
[Total Sales],
|
|
169
|
+
DATESINPERIOD('Date'[Date], MAX('Date'[Date]), -3, MONTH)
|
|
170
|
+
),
|
|
171
|
+
3
|
|
172
|
+
)
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## Critical Rules for TI in DAX Queries
|
|
176
|
+
|
|
177
|
+
When generating DAX queries that use time intelligence functions, follow these rules:
|
|
178
|
+
|
|
179
|
+
### Establishing Date Context
|
|
180
|
+
|
|
181
|
+
Time intelligence functions require a clear "current date" reference in the filter context.
|
|
182
|
+
|
|
183
|
+
**Rule**: Always establish a valid date context by either:
|
|
184
|
+
1. Including groupby columns from the date table, OR
|
|
185
|
+
2. Applying filters on date columns
|
|
186
|
+
|
|
187
|
+
```dax
|
|
188
|
+
// Wrong: ROW with TI but no date context
|
|
189
|
+
EVALUATE
|
|
190
|
+
ROW(
|
|
191
|
+
"Sales YTD", TOTALYTD([Total Sales], 'Date'[Date])
|
|
192
|
+
)
|
|
193
|
+
|
|
194
|
+
// Correct: Use CALCULATETABLE to establish date context
|
|
195
|
+
EVALUATE
|
|
196
|
+
CALCULATETABLE(
|
|
197
|
+
ROW(
|
|
198
|
+
"Sales YTD", TOTALYTD([Total Sales], 'Date'[Date])
|
|
199
|
+
),
|
|
200
|
+
'Date'[Year] = 2024,
|
|
201
|
+
TREATAS({ MAX(Sales[OrderDate]) }, 'Date'[Date])
|
|
202
|
+
)
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### Using TREATAS to Set Reference Date
|
|
206
|
+
|
|
207
|
+
```dax
|
|
208
|
+
// Calculate TI measures with a reference date from Sales
|
|
209
|
+
EVALUATE
|
|
210
|
+
CALCULATETABLE(
|
|
211
|
+
ROW(
|
|
212
|
+
"Total Sales Amount YTD", TOTALYTD([Total Sales], 'Date'[Date]),
|
|
213
|
+
"14-Day Moving Avg", AVERAGEX(
|
|
214
|
+
DATESINPERIOD('Date'[Date], MAX('Date'[Date]), -14, DAY),
|
|
215
|
+
[Total Sales]
|
|
216
|
+
)
|
|
217
|
+
),
|
|
218
|
+
'Product'[Category] = "Electronics",
|
|
219
|
+
TREATAS({ MAX(Sales[OrderDate]) }, 'Date'[Date])
|
|
220
|
+
)
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
### Combining TI with SUMMARIZECOLUMNS
|
|
224
|
+
|
|
225
|
+
Include date columns as groupby columns to provide context:
|
|
226
|
+
|
|
227
|
+
```dax
|
|
228
|
+
// Year and Month provide the date context for YTD calculation
|
|
229
|
+
EVALUATE
|
|
230
|
+
SUMMARIZECOLUMNS(
|
|
231
|
+
'Date'[Year],
|
|
232
|
+
'Date'[Month],
|
|
233
|
+
'Date'[MonthNumberOfYear],
|
|
234
|
+
"Sales YTD", TOTALYTD([Total Sales], 'Date'[Date]),
|
|
235
|
+
"Sales PY", CALCULATE([Total Sales], SAMEPERIODLASTYEAR('Date'[Date]))
|
|
236
|
+
)
|
|
237
|
+
ORDER BY 'Date'[Year] ASC, 'Date'[MonthNumberOfYear] ASC
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
### Determining "Last Year" Dynamically
|
|
241
|
+
|
|
242
|
+
Avoid hardcoding years. Use MAX on the fact table's date column:
|
|
243
|
+
|
|
244
|
+
```dax
|
|
245
|
+
DEFINE
|
|
246
|
+
// Last year based on actual sales, not calendar table
|
|
247
|
+
VAR _LastYear = YEAR(MAX(Sales[OrderDate]))
|
|
248
|
+
|
|
249
|
+
EVALUATE
|
|
250
|
+
SUMMARIZECOLUMNS(
|
|
251
|
+
'Customer'[Name],
|
|
252
|
+
'Date'[Year],
|
|
253
|
+
TREATAS({ _LastYear, _LastYear - 1, _LastYear - 2 }, 'Date'[Year]),
|
|
254
|
+
"Total Sales", [Total Sales],
|
|
255
|
+
"Sales PY", CALCULATE([Total Sales], SAMEPERIODLASTYEAR('Date'[Date]))
|
|
256
|
+
)
|
|
257
|
+
ORDER BY 'Customer'[Name] ASC, 'Date'[Year] ASC
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
## Common Mistakes
|
|
261
|
+
|
|
262
|
+
### Missing Date Table Relationship
|
|
263
|
+
|
|
264
|
+
```dax
|
|
265
|
+
// Wrong: No relationship to Date table
|
|
266
|
+
Sales YTD = TOTALYTD(SUM(Sales[Amount]), Sales[OrderDate])
|
|
267
|
+
|
|
268
|
+
// Correct: Use Date table column
|
|
269
|
+
Sales YTD = TOTALYTD(SUM(Sales[Amount]), 'Date'[Date])
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
### Gaps in Date Table
|
|
273
|
+
|
|
274
|
+
Time intelligence functions may return unexpected results with non-contiguous dates. Ensure your Date table has every day, even if no transactions occurred.
|
|
275
|
+
|
|
276
|
+
### Using CALCULATE with FILTER on Dates
|
|
277
|
+
|
|
278
|
+
```dax
|
|
279
|
+
// Inefficient: FILTER iterates all dates
|
|
280
|
+
Sales YTD =
|
|
281
|
+
CALCULATE(
|
|
282
|
+
[Total Sales],
|
|
283
|
+
FILTER(ALL('Date'), 'Date'[Date] <= MAX('Date'[Date]) && YEAR('Date'[Date]) = YEAR(MAX('Date'[Date])))
|
|
284
|
+
)
|
|
285
|
+
|
|
286
|
+
// Efficient: Use built-in function
|
|
287
|
+
Sales YTD = CALCULATE([Total Sales], DATESYTD('Date'[Date]))
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
## Performance Considerations
|
|
291
|
+
|
|
292
|
+
1. **Use TOTALYTD/TOTALQTD/TOTALMTD** for simple aggregations (slightly more efficient)
|
|
293
|
+
2. **Use DATESYTD/DATESQTD/DATESMTD** when you need to nest or combine with other functions
|
|
294
|
+
3. **Store base measures** in variables when combining multiple time intelligence calculations
|
|
295
|
+
4. **Avoid nested time intelligence** when possible; use intermediate measures
|
|
296
|
+
|
|
297
|
+
## Complete Function Reference
|
|
298
|
+
|
|
299
|
+
### Period-to-Date Functions
|
|
300
|
+
|
|
301
|
+
| Function | Description |
|
|
302
|
+
|----------|-------------|
|
|
303
|
+
| DATESYTD | Year-to-date dates |
|
|
304
|
+
| DATESQTD | Quarter-to-date dates |
|
|
305
|
+
| DATESMTD | Month-to-date dates |
|
|
306
|
+
| DATESWTD | Week-to-date dates (calendar-based) |
|
|
307
|
+
|
|
308
|
+
### Total-to-Date Functions
|
|
309
|
+
|
|
310
|
+
| Function | Description |
|
|
311
|
+
|----------|-------------|
|
|
312
|
+
| TOTALYTD | Year-to-date total |
|
|
313
|
+
| TOTALQTD | Quarter-to-date total |
|
|
314
|
+
| TOTALMTD | Month-to-date total |
|
|
315
|
+
| TOTALWTD | Week-to-date total (calendar-based) |
|
|
316
|
+
|
|
317
|
+
### Period Shifting Functions
|
|
318
|
+
|
|
319
|
+
| Function | Description |
|
|
320
|
+
|----------|-------------|
|
|
321
|
+
| DATEADD | Flexible shift by days, months, quarters, years |
|
|
322
|
+
| SAMEPERIODLASTYEAR | Same dates in previous year |
|
|
323
|
+
| PARALLELPERIOD | Complete parallel period |
|
|
324
|
+
|
|
325
|
+
### Opening/Closing Balance Functions
|
|
326
|
+
|
|
327
|
+
| Function | Description |
|
|
328
|
+
|----------|-------------|
|
|
329
|
+
| OPENINGBALANCEMONTH / QUARTER / YEAR | Value at period start |
|
|
330
|
+
| CLOSINGBALANCEMONTH / QUARTER / YEAR | Value at period end |
|
|
331
|
+
|
|
332
|
+
### Period Navigation Functions
|
|
333
|
+
|
|
334
|
+
| Function | Description |
|
|
335
|
+
|----------|-------------|
|
|
336
|
+
| FIRSTDATE / LASTDATE | First/last date in context |
|
|
337
|
+
| STARTOFMONTH / STARTOFQUARTER / STARTOFYEAR | Period start date |
|
|
338
|
+
| ENDOFMONTH / ENDOFQUARTER / ENDOFYEAR | Period end date |
|
|
339
|
+
| PREVIOUSDAY / MONTH / QUARTER / YEAR | Prior period dates |
|
|
340
|
+
| NEXTDAY / MONTH / QUARTER / YEAR | Next period dates |
|
|
341
|
+
|
|
342
|
+
### Custom Range Functions
|
|
343
|
+
|
|
344
|
+
| Function | Description |
|
|
345
|
+
|----------|-------------|
|
|
346
|
+
| DATESINPERIOD | Dates within interval from start date |
|
|
347
|
+
| DATESBETWEEN | Dates between two specific dates |
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: query-design
|
|
3
|
+
description: >
|
|
4
|
+
Separates DAX data-fetching from TypeScript presentation. Guides when to use
|
|
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.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Query Design — Separation of Data and Presentation
|
|
11
|
+
|
|
12
|
+
**DAX computes and fetches data. TypeScript shapes it for display. VegaVisual and DataGrid render it.**
|
|
13
|
+
|
|
14
|
+
Aggregate in DAX to the visual's grain — never fetch lower-grain rows to roll up client-side. When a visual layout changes, only the TypeScript or spec layer should change — not the DAX query.
|
|
15
|
+
|
|
16
|
+
## Responsibility Matrix
|
|
17
|
+
|
|
18
|
+
| Concern | Owner |
|
|
19
|
+
|---|---|
|
|
20
|
+
| Semantic measures (SUM, DISTINCTCOUNT, etc.) | DAX |
|
|
21
|
+
| Filters and slicers | DAX or TypeScript ([see Filter Strategy](references/filter-strategy.md)) |
|
|
22
|
+
| Grouping grain (SUMMARIZECOLUMNS) | DAX |
|
|
23
|
+
| Time intelligence (YTD, YoY) | DAX |
|
|
24
|
+
| TopN / payload reduction | DAX |
|
|
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 |
|
|
28
|
+
| DataGrid-computed grand totals | DataGrid (alternative only for additive `sum` values or a count of fetched leaf rows) |
|
|
29
|
+
| Filling dimension gaps | TypeScript (stitch dimension list into sparse results) |
|
|
30
|
+
| Reshaping (pivot, unpivot) | TypeScript |
|
|
31
|
+
| Column display names | `columnMetadata` in factory file |
|
|
32
|
+
| Number/date formatting | `columnMetadata.format` / Vega-Lite spec |
|
|
33
|
+
| User-facing sort order | TypeScript / Vega-Lite `sort` / DataGrid `sort` |
|
|
34
|
+
| Decorative labels, icons | DataGrid `cellRenderer` or Vega-Lite condition |
|
|
35
|
+
| Axis titles, legends, color encoding | Vega-Lite spec |
|
|
36
|
+
|
|
37
|
+
## Rules
|
|
38
|
+
|
|
39
|
+
### Must
|
|
40
|
+
|
|
41
|
+
- 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
|
|
43
|
+
- `ORDER BY` in DAX for stable, diffable results — not presentation sort
|
|
44
|
+
- Same filters/measures across related split-grain queries to prevent drift
|
|
45
|
+
|
|
46
|
+
### Prefer
|
|
47
|
+
|
|
48
|
+
- `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`
|
|
50
|
+
- Raw typed values from DAX — format via `columnMetadata.format` or Vega-Lite, never `FORMAT()`
|
|
51
|
+
- Model-defined format strings (from `INFO.VIEW.MEASURES()`) over invented ones
|
|
52
|
+
- Multiple lightweight queries over one monolithic query
|
|
53
|
+
- User-facing sort in TypeScript / Vega-Lite / DataGrid — never re-query for sort
|
|
54
|
+
|
|
55
|
+
### Avoid
|
|
56
|
+
|
|
57
|
+
- `SELECTCOLUMNS` solely for renaming — use `columnMetadata.displayName` instead
|
|
58
|
+
- `UNION` to mix different grains (detail + total) — use separate queries
|
|
59
|
+
- `FORMAT()` in DAX — converts to text, breaks sorting and charting
|
|
60
|
+
- Converting BLANK to `0` / `""` / `"N/A"` in DAX — causes result-set explosion
|
|
61
|
+
- `CONCATENATEX`, `UNICHAR`, emoji prefixes — decorative text belongs in `cellRenderer` or Vega-Lite
|
|
62
|
+
- Fetching all members of high-cardinality dimensions just to fill gaps
|
|
63
|
+
|
|
64
|
+
## Decision Flowchart
|
|
65
|
+
|
|
66
|
+
```text
|
|
67
|
+
Need to add something to the query result?
|
|
68
|
+
|-- Calculation / aggregation / filter?
|
|
69
|
+
| -> DAX (measures, CALCULATE, SUMMARIZECOLUMNS)
|
|
70
|
+
|-- 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
|
|
73
|
+
|-- 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
|
+
|-- Merging datasets or adding other synthetic rows?
|
|
77
|
+
| -> Charts: pass multiple DataTables to VegaVisual, layer in spec
|
|
78
|
+
| -> Grids: append rows in TypeScript, style via cellRenderer
|
|
79
|
+
|-- Renaming a column for display?
|
|
80
|
+
| -> columnMetadata in the factory file (displayName)
|
|
81
|
+
|-- Formatting, labeling, or encoding?
|
|
82
|
+
| -> Vega-Lite spec or DataGrid cellRenderer
|
|
83
|
+
|-- Decorating values (icons, status badges, null placeholders)?
|
|
84
|
+
| -> DataGrid cellRenderer or Vega-Lite condition encoding
|
|
85
|
+
|-- Not sure?
|
|
86
|
+
-> Does it change what the data *means* (filter, measure, grain)? -> DAX
|
|
87
|
+
Does it change only how data is *rendered* (labels, icons, layout)? -> TypeScript / Vega-Lite spec / DataGrid cellRenderer
|
|
88
|
+
Still unclear? -> Read the relevant reference above
|
|
89
|
+
```
|
|
90
|
+
|
|
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
|
+
## Reference Materials
|
|
101
|
+
|
|
102
|
+
Read these when working on a specific topic:
|
|
103
|
+
|
|
104
|
+
- **[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.
|
|
108
|
+
- **[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
|
+
|
|
110
|
+
## Integration with Sibling Skills
|
|
111
|
+
|
|
112
|
+
- **[schema-discovery](../schema-discovery/SKILL.md)** — Schema exploration; discover tables, columns, and relationships before writing queries.
|
|
113
|
+
- **[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
|
+
- **[visuals](../visuals/SKILL.md)** — Vega-Lite specs and DataGrid configuration. Push formatting and labels into specs, not DAX.
|