@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,396 @@
|
|
|
1
|
+
# DAX Query Patterns
|
|
2
|
+
|
|
3
|
+
Complete guide for writing DAX queries — structure, syntax rules, worked examples, and anti-patterns.
|
|
4
|
+
|
|
5
|
+
## Query Structure
|
|
6
|
+
|
|
7
|
+
```dax
|
|
8
|
+
[DEFINE
|
|
9
|
+
VAR <variable_name> = <expression>
|
|
10
|
+
MEASURE <table>[<measure_name>] = <expression>
|
|
11
|
+
]
|
|
12
|
+
|
|
13
|
+
EVALUATE
|
|
14
|
+
<table expression>
|
|
15
|
+
|
|
16
|
+
[ORDER BY
|
|
17
|
+
<column> [ASC|DESC], ...]
|
|
18
|
+
|
|
19
|
+
[START AT
|
|
20
|
+
<value>, ...]
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Key Components
|
|
24
|
+
|
|
25
|
+
**DEFINE (Optional)**
|
|
26
|
+
- Declare variables (VAR) and measures (MEASURE)
|
|
27
|
+
- Variables can store table expressions, filters, or scalar values
|
|
28
|
+
- Only ONE DEFINE block per query
|
|
29
|
+
- Separate VARs/MEASUREs with newlines (no commas)
|
|
30
|
+
|
|
31
|
+
**EVALUATE (Required)**
|
|
32
|
+
- Must precede a table expression
|
|
33
|
+
- Returns a table of results
|
|
34
|
+
- Cannot use scalar functions directly (SUMX, DISTINCTCOUNT, etc.)
|
|
35
|
+
|
|
36
|
+
**ORDER BY (Strongly Recommended)**
|
|
37
|
+
- Always include for queries returning multiple rows
|
|
38
|
+
- Ensures consistent, predictable results
|
|
39
|
+
- When using SELECTCOLUMNS, reference the NEW column names
|
|
40
|
+
|
|
41
|
+
**START AT (Optional)**
|
|
42
|
+
- For paging results
|
|
43
|
+
|
|
44
|
+
## Essential Syntax Rules
|
|
45
|
+
|
|
46
|
+
### Naming Conventions
|
|
47
|
+
|
|
48
|
+
- **Columns**: `'Table'[Column]` (fully-qualified)
|
|
49
|
+
- **Measures**: `[Measure]` (simple name, never qualify)
|
|
50
|
+
|
|
51
|
+
### DEFINE Rules
|
|
52
|
+
|
|
53
|
+
```dax
|
|
54
|
+
// Correct — Single DEFINE, no commas
|
|
55
|
+
DEFINE
|
|
56
|
+
VAR _X = 1
|
|
57
|
+
VAR _Y = 2
|
|
58
|
+
MEASURE 'Sales'[Temp] = COUNTROWS()
|
|
59
|
+
|
|
60
|
+
// Wrong — Multiple DEFINEs
|
|
61
|
+
DEFINE VAR _X = 1
|
|
62
|
+
DEFINE VAR _Y = 2
|
|
63
|
+
|
|
64
|
+
// Wrong — Commas between VARs
|
|
65
|
+
DEFINE
|
|
66
|
+
VAR _X = 1,
|
|
67
|
+
VAR _Y = 2
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Critical DAX Query Rules
|
|
71
|
+
|
|
72
|
+
### 1. EVALUATE Must Use Table Expressions
|
|
73
|
+
|
|
74
|
+
Correct:
|
|
75
|
+
|
|
76
|
+
```dax
|
|
77
|
+
EVALUATE 'Product'
|
|
78
|
+
ORDER BY 'Product'[Name]
|
|
79
|
+
|
|
80
|
+
EVALUATE ROW("Total", [Total Sales])
|
|
81
|
+
|
|
82
|
+
EVALUATE SUMMARIZECOLUMNS('Product'[Category], "Sales", [Total Sales])
|
|
83
|
+
ORDER BY [Sales] DESC
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Wrong:
|
|
87
|
+
|
|
88
|
+
```dax
|
|
89
|
+
EVALUATE [Total Sales] // Scalar value, not a table
|
|
90
|
+
EVALUATE SUMX('Sales', Sales[Amount]) // Scalar function, not a table
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Column Selection Functions
|
|
94
|
+
|
|
95
|
+
| Function | Use For | Duplicates? | Example |
|
|
96
|
+
|----------|---------|-------------|---------|
|
|
97
|
+
| **VALUES** | Single column distinct | No | `VALUES('Product'[Category])` |
|
|
98
|
+
| **SUMMARIZE** | Multiple columns distinct | No | `SUMMARIZE('Sales', 'Product'[Cat], 'Product'[Color])` |
|
|
99
|
+
| **SELECTCOLUMNS** | Projection with rename | Yes | `SELECTCOLUMNS('Sales', "Prod", RELATED('Product'[Name]))` |
|
|
100
|
+
|
|
101
|
+
## Common Patterns
|
|
102
|
+
|
|
103
|
+
### Sample Schema (for reference)
|
|
104
|
+
|
|
105
|
+
These examples use the following hypothetical data model:
|
|
106
|
+
|
|
107
|
+
```yaml
|
|
108
|
+
Tables:
|
|
109
|
+
- Name: Sales
|
|
110
|
+
Measures:
|
|
111
|
+
- Name: Total Discount (Type: Decimal)
|
|
112
|
+
- Name: Total Amount (Type: Decimal)
|
|
113
|
+
- Name: Total Quantity (Type: Integer)
|
|
114
|
+
Columns: CustomerKey (Text), Order Quantity (Integer), ProductKey (Text), OrderDate (Date), Sales Amount (Decimal)
|
|
115
|
+
- Name: Product
|
|
116
|
+
Measures:
|
|
117
|
+
- Name: Median List Price (Type: Decimal)
|
|
118
|
+
Columns: Category (Text), Color (Text), List Price (Decimal), Name (Text), ProductKey (Text)
|
|
119
|
+
- Name: Customer
|
|
120
|
+
Columns: CustomerKey (Text), Name (Text)
|
|
121
|
+
- Name: Calendar
|
|
122
|
+
Columns: Date (Date), Month (Integer), Year (Integer)
|
|
123
|
+
Active Relationships:
|
|
124
|
+
- PK: 'Product'[ProductKey] -> FK: 'Sales'[ProductKey] (Unidirectional: Product filters Sales)
|
|
125
|
+
- PK: 'Customer'[CustomerKey] -> FK: 'Sales'[CustomerKey] (Unidirectional: Customer filters Sales)
|
|
126
|
+
- PK: 'Calendar'[Date] -> FK: 'Sales'[OrderDate] (Unidirectional: Calendar filters Sales)
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Pattern 1: Simple Filtered Aggregation
|
|
130
|
+
|
|
131
|
+
```dax
|
|
132
|
+
// Total sales for red products
|
|
133
|
+
EVALUATE
|
|
134
|
+
CALCULATETABLE(
|
|
135
|
+
ROW("Total Sales Amount", [Total Amount]),
|
|
136
|
+
'Product'[Color] == "Red"
|
|
137
|
+
)
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Pattern 2: Multi-Dimensional Summary
|
|
141
|
+
|
|
142
|
+
```dax
|
|
143
|
+
DEFINE
|
|
144
|
+
VAR _CategoryFilter = TREATAS({"Consumer Electronics"}, 'Product'[Category])
|
|
145
|
+
VAR _YearFilter = FILTER(ALL('Calendar'[Year]), 'Calendar'[Year] >= 2022)
|
|
146
|
+
|
|
147
|
+
EVALUATE
|
|
148
|
+
SUMMARIZECOLUMNS(
|
|
149
|
+
'Calendar'[Year],
|
|
150
|
+
_CategoryFilter,
|
|
151
|
+
_YearFilter,
|
|
152
|
+
"Total Quantity", SUM('Sales'[Order Quantity])
|
|
153
|
+
)
|
|
154
|
+
ORDER BY 'Calendar'[Year] DESC
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### Pattern 3: Monthly Summary with Multiple Filters
|
|
158
|
+
|
|
159
|
+
```dax
|
|
160
|
+
DEFINE
|
|
161
|
+
// Filters for products in electronics category
|
|
162
|
+
VAR _Filter1 = TREATAS(
|
|
163
|
+
{
|
|
164
|
+
"Consumer Electronics"
|
|
165
|
+
},
|
|
166
|
+
'Product'[Category]
|
|
167
|
+
)
|
|
168
|
+
// Filters to years 2022 and 2023
|
|
169
|
+
VAR _Filter2 = FILTER(
|
|
170
|
+
ALL('Calendar'[Year]),
|
|
171
|
+
'Calendar'[Year] >= 2022 && 'Calendar'[Year] <= 2023
|
|
172
|
+
)
|
|
173
|
+
|
|
174
|
+
// Quantity and discount filtered to electronics products for years 2022 and 2023, grouped by month
|
|
175
|
+
EVALUATE
|
|
176
|
+
SUMMARIZECOLUMNS(
|
|
177
|
+
'Calendar'[Year],
|
|
178
|
+
'Calendar'[Month],
|
|
179
|
+
_Filter1,
|
|
180
|
+
_Filter2,
|
|
181
|
+
"Total Quantity", SUM('Sales'[Order Quantity]),
|
|
182
|
+
"Discount", [Total Discount]
|
|
183
|
+
)
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Pattern 4: Filter and Select with Threshold
|
|
187
|
+
|
|
188
|
+
```dax
|
|
189
|
+
DEFINE
|
|
190
|
+
// Red or Black product filter
|
|
191
|
+
VAR _Filter = TREATAS(
|
|
192
|
+
{
|
|
193
|
+
"Red",
|
|
194
|
+
"Black"
|
|
195
|
+
},
|
|
196
|
+
'Product'[Color]
|
|
197
|
+
)
|
|
198
|
+
// Sales of Red or Black products
|
|
199
|
+
VAR _Core = SUMMARIZECOLUMNS(
|
|
200
|
+
'Product'[Name],
|
|
201
|
+
_Filter,
|
|
202
|
+
"Total Sales", [Total Amount]
|
|
203
|
+
)
|
|
204
|
+
|
|
205
|
+
// Products with total sales above $1,000,000
|
|
206
|
+
EVALUATE
|
|
207
|
+
SELECTCOLUMNS(
|
|
208
|
+
FILTER(
|
|
209
|
+
_Core,
|
|
210
|
+
[Total Sales] > 1000000
|
|
211
|
+
),
|
|
212
|
+
'Product'[Name]
|
|
213
|
+
)
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
### Pattern 5: Distinct Values Without Duplicates
|
|
217
|
+
|
|
218
|
+
```dax
|
|
219
|
+
// Product color, category and key for products sold in 2022
|
|
220
|
+
EVALUATE
|
|
221
|
+
CALCULATETABLE(
|
|
222
|
+
// SUMMARIZE is used to remove duplicate rows
|
|
223
|
+
SUMMARIZE(
|
|
224
|
+
'Sales',
|
|
225
|
+
'Product'[Color],
|
|
226
|
+
'Product'[Category],
|
|
227
|
+
'Sales'[ProductKey]
|
|
228
|
+
),
|
|
229
|
+
'Calendar'[Year] == 2022
|
|
230
|
+
)
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
### Pattern 6: Cross-Table Selection With Duplicates
|
|
234
|
+
|
|
235
|
+
```dax
|
|
236
|
+
// Product color, category and key for products sold in 2022
|
|
237
|
+
EVALUATE
|
|
238
|
+
CALCULATETABLE(
|
|
239
|
+
SELECTCOLUMNS(
|
|
240
|
+
'Sales',
|
|
241
|
+
"Color",
|
|
242
|
+
RELATED('Product'[Color]),
|
|
243
|
+
"Category",
|
|
244
|
+
RELATED('Product'[Category]),
|
|
245
|
+
'Sales'[ProductKey]
|
|
246
|
+
),
|
|
247
|
+
'Calendar'[Year] == 2022
|
|
248
|
+
)
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### Pattern 7: Finding Items With No Matches
|
|
252
|
+
|
|
253
|
+
```dax
|
|
254
|
+
DEFINE
|
|
255
|
+
// Sale row count
|
|
256
|
+
MEASURE 'Sales'[Row Count] = COUNTROWS()
|
|
257
|
+
|
|
258
|
+
// Products with no sales
|
|
259
|
+
EVALUATE
|
|
260
|
+
FILTER(
|
|
261
|
+
'Product',
|
|
262
|
+
ISBLANK([Row Count])
|
|
263
|
+
)
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
### Pattern 8: Comparison Against Aggregate
|
|
267
|
+
|
|
268
|
+
```dax
|
|
269
|
+
DEFINE
|
|
270
|
+
// Pre-calculate Median List Price before the query so it applies to all rows
|
|
271
|
+
VAR _MedianListPrice = [Median List Price]
|
|
272
|
+
|
|
273
|
+
// Products with list price over the median.
|
|
274
|
+
EVALUATE
|
|
275
|
+
CALCULATETABLE(
|
|
276
|
+
VALUES('Product'[Name]),
|
|
277
|
+
'Product'[List Price] > _MedianListPrice
|
|
278
|
+
)
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
### Pattern 9: Complex Multi-Step (TopN + Related Data)
|
|
282
|
+
|
|
283
|
+
```dax
|
|
284
|
+
DEFINE
|
|
285
|
+
// To make query more readable, a filter can be defined separately.
|
|
286
|
+
VAR _Filter = FILTER(
|
|
287
|
+
ALL('Calendar'[Year]),
|
|
288
|
+
'Calendar'[Year] > 2020
|
|
289
|
+
)
|
|
290
|
+
// Get the product with the maximum Total Quantity
|
|
291
|
+
VAR _TopProduct = TOPN(
|
|
292
|
+
1,
|
|
293
|
+
SUMMARIZECOLUMNS(
|
|
294
|
+
'Product'[Name],
|
|
295
|
+
_Filter,
|
|
296
|
+
"Total Quantity", [Total Quantity]
|
|
297
|
+
),
|
|
298
|
+
[Total Quantity],
|
|
299
|
+
DESC
|
|
300
|
+
)
|
|
301
|
+
|
|
302
|
+
// Name and order date for sales of the top product
|
|
303
|
+
EVALUATE
|
|
304
|
+
SELECTCOLUMNS(
|
|
305
|
+
CALCULATETABLE(
|
|
306
|
+
'Sales',
|
|
307
|
+
_TopProduct
|
|
308
|
+
),
|
|
309
|
+
// Column name is needed because it is not part of the original table
|
|
310
|
+
"Product Name",
|
|
311
|
+
RELATED('Product'[Name]),
|
|
312
|
+
'Sales'[OrderDate]
|
|
313
|
+
)
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
### Pattern 10: Simple Lookup
|
|
317
|
+
|
|
318
|
+
```dax
|
|
319
|
+
// Products sold in 2022
|
|
320
|
+
EVALUATE
|
|
321
|
+
CALCULATETABLE(
|
|
322
|
+
SUMMARIZE(
|
|
323
|
+
'Sales',
|
|
324
|
+
'Product'[Name]
|
|
325
|
+
),
|
|
326
|
+
'Calendar'[Year] == 2022
|
|
327
|
+
)
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
### Pattern 11: Cross-Table with Sorting
|
|
331
|
+
|
|
332
|
+
```dax
|
|
333
|
+
// Sorted product and customer names for all sales
|
|
334
|
+
EVALUATE
|
|
335
|
+
SELECTCOLUMNS(
|
|
336
|
+
'Sales',
|
|
337
|
+
// Since product and customer are not in the sales table, SELECTCOLUMNS requires a name for those columns
|
|
338
|
+
"Product Name",
|
|
339
|
+
RELATED('Product'[Name]),
|
|
340
|
+
"Customer Name",
|
|
341
|
+
RELATED('Customer'[Name])
|
|
342
|
+
)
|
|
343
|
+
// ORDER BY needs to use the renamed column names
|
|
344
|
+
ORDER BY
|
|
345
|
+
[Product Name] ASC,
|
|
346
|
+
[Customer Name] ASC
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
## Code Quality Standards
|
|
350
|
+
|
|
351
|
+
- Comments explain purpose
|
|
352
|
+
- DEFINE with well-named variables (prefix with `_` to avoid keywords)
|
|
353
|
+
- Filters defined separately
|
|
354
|
+
- Intermediate calculations in variables
|
|
355
|
+
- Simple, readable EVALUATE statement
|
|
356
|
+
- Appropriate ORDER BY
|
|
357
|
+
|
|
358
|
+
## Syntax Mistakes
|
|
359
|
+
|
|
360
|
+
### SQL Keywords
|
|
361
|
+
|
|
362
|
+
```dax
|
|
363
|
+
// Wrong
|
|
364
|
+
SELECT * FROM Product WHERE Category = 'Electronics'
|
|
365
|
+
|
|
366
|
+
// Correct
|
|
367
|
+
EVALUATE
|
|
368
|
+
FILTER('Product', 'Product'[Category] = "Electronics")
|
|
369
|
+
ORDER BY 'Product'[Name]
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
### Method Chaining
|
|
373
|
+
|
|
374
|
+
```dax
|
|
375
|
+
// Wrong (like Python/JavaScript)
|
|
376
|
+
Product.FILTER(...).SELECTCOLUMNS(...)
|
|
377
|
+
|
|
378
|
+
// Correct — Use variables
|
|
379
|
+
DEFINE
|
|
380
|
+
VAR _Filtered = FILTER('Product', ...)
|
|
381
|
+
VAR _Projected = SELECTCOLUMNS(_Filtered, ...)
|
|
382
|
+
EVALUATE
|
|
383
|
+
_Projected
|
|
384
|
+
ORDER BY [Name]
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
### Scalar After EVALUATE
|
|
388
|
+
|
|
389
|
+
```dax
|
|
390
|
+
// Wrong
|
|
391
|
+
EVALUATE [Total Sales]
|
|
392
|
+
EVALUATE SUMX('Sales', Sales[Amount])
|
|
393
|
+
|
|
394
|
+
// Correct — Wrap in ROW or table function
|
|
395
|
+
EVALUATE ROW("Total", [Total Sales])
|
|
396
|
+
```
|