@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.
@@ -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
+ ```