@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.
Files changed (29) hide show
  1. package/CHANGELOG +10 -0
  2. package/LICENSE +21 -0
  3. package/README.md +65 -2
  4. package/package.json +10 -3
  5. package/skills/analytics/SKILL.md +460 -0
  6. package/skills/analytics/kit/hooks/use-semantic-model-query.spec.ts +342 -0
  7. package/skills/analytics/kit/hooks/use-semantic-model-query.ts +229 -0
  8. package/skills/analytics/kit/lib/connectors.ts +94 -0
  9. package/skills/analytics/kit/scripts/rayfin-connector.mjs +265 -0
  10. package/skills/analytics/kit/scripts/rayfin-connector.test.mjs +243 -0
  11. package/skills/analytics/kit/scripts/schema-sql-batch.test.mjs +2097 -0
  12. package/skills/analytics/kit/scripts/schema-sql-cli.test.mjs +488 -0
  13. package/skills/analytics/kit/scripts/schema-sql.mjs +2650 -0
  14. package/skills/analytics/kit/scripts/schema-sql.test.mjs +1387 -0
  15. package/skills/analytics/kit/scripts/schema.mjs +166 -0
  16. package/skills/analytics/kit/scripts/schema.test.mjs +271 -0
  17. package/skills/analytics/pack.json +49 -0
  18. package/skills/dax-authoring/SKILL.md +172 -0
  19. package/skills/dax-authoring/references/dax-core-reference.md +862 -0
  20. package/skills/dax-authoring/references/dax-query-patterns.md +396 -0
  21. package/skills/dax-authoring/references/dax-time-intelligence.md +347 -0
  22. package/skills/query-design/SKILL.md +114 -0
  23. package/skills/query-design/references/anti-patterns.md +285 -0
  24. package/skills/query-design/references/filter-strategy.md +68 -0
  25. package/skills/query-design/references/format-strings.md +62 -0
  26. package/skills/query-design/references/highlight-queries.md +122 -0
  27. package/skills/query-design/references/multi-grain-patterns.md +159 -0
  28. package/skills/schema-discovery/SKILL.md +382 -0
  29. package/skills/schema-discovery/references/discovery-queries.md +153 -0
@@ -0,0 +1,166 @@
1
+ //-----------------------------------------------------------------------
2
+ // <copyright company="Microsoft Corporation">
3
+ // Copyright (c) Microsoft Corporation. All rights reserved.
4
+ // Licensed under the MIT license. See LICENSE file in the project root for full license information.
5
+ // </copyright>
6
+ //-----------------------------------------------------------------------
7
+
8
+ import {
9
+ invokeConnector,
10
+ listConfiguredConnectors,
11
+ } from './rayfin-connector.mjs';
12
+
13
+ export function normalizeColName(name) {
14
+ const match = String(name).match(/\[([^\]]+)\]\s*$/);
15
+ return match ? match[1] : String(name);
16
+ }
17
+
18
+ export function isFabricGuid(value) {
19
+ return /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/iu.test(String(value));
20
+ }
21
+
22
+ export function parseQueryOutput(value) {
23
+ if (!value) {
24
+ return { ok: false, error: 'No output from query.' };
25
+ }
26
+ if (value.status === 'error') {
27
+ const message = value.error?.message ?? value.error;
28
+ return {
29
+ ok: false,
30
+ error: String(message || 'Unknown query error.'),
31
+ };
32
+ }
33
+ const table =
34
+ value.table ?? (Array.isArray(value.tables) ? value.tables[0] : undefined);
35
+ if (!table || !Array.isArray(table.columns) || !Array.isArray(table.rows)) {
36
+ return {
37
+ ok: false,
38
+ error: 'Query result did not contain a table.',
39
+ };
40
+ }
41
+ const columns = table.columns.map((column) => ({
42
+ name: normalizeColName(column?.name),
43
+ dataType:
44
+ typeof column?.dataType === 'string' ? column.dataType : 'unknown',
45
+ }));
46
+ const rows = table.rows.map((row) => {
47
+ const record = {};
48
+ columns.forEach((column, index) => {
49
+ record[column.name] = Array.isArray(row) ? row[index] : undefined;
50
+ });
51
+ return record;
52
+ });
53
+ return { ok: true, columns, rows };
54
+ }
55
+
56
+ export async function runFabricQuery(dax, options = {}) {
57
+ const {
58
+ alias,
59
+ limit,
60
+ cwd = process.cwd(),
61
+ invoke = invokeConnector,
62
+ } = options;
63
+ const result = await invoke({
64
+ connector: alias,
65
+ query: dax,
66
+ limit,
67
+ cwd,
68
+ });
69
+ if (!result.ok) {
70
+ return { ok: false, error: result.error };
71
+ }
72
+ return parseQueryOutput(result.output);
73
+ }
74
+
75
+ async function semanticModelConnectors(options = {}) {
76
+ const result = await listConfiguredConnectors(options);
77
+ if (!result.ok) {
78
+ return result;
79
+ }
80
+ return {
81
+ ok: true,
82
+ connectors: result.connectors.filter(
83
+ (connector) =>
84
+ connector?.type === 'fabric-semanticmodel' &&
85
+ typeof connector.name === 'string' &&
86
+ connector.name.length > 0
87
+ ),
88
+ };
89
+ }
90
+
91
+ export async function resolveAlias(cwd, explicit, options = {}) {
92
+ if (explicit) {
93
+ return { alias: explicit };
94
+ }
95
+ const result = await semanticModelConnectors({ cwd, ...options });
96
+ if (!result.ok) {
97
+ return { error: result.error };
98
+ }
99
+ const aliases = result.connectors.map((connector) => connector.name);
100
+ if (aliases.length === 0) {
101
+ return {
102
+ error:
103
+ 'No semantic model connector is configured. Connect one first:\n\n' +
104
+ ' npx rayfin connector add --type fabric-semanticmodel ' +
105
+ '--workspace-id <workspace-id> --item-id <item-id> --name model',
106
+ };
107
+ }
108
+ if (aliases.length > 1) {
109
+ return {
110
+ error:
111
+ `This app is connected to ${aliases.length} semantic models: ` +
112
+ `${aliases.join(', ')}.\n\n` +
113
+ ` npm run --silent schema:sql -- --alias ${aliases[0]} "SELECT ..."`,
114
+ };
115
+ }
116
+ // Hand back the connector too: resolveIdentity needs the same record, and
117
+ // re-listing costs another CLI spawn on every command.
118
+ return { alias: aliases[0], connector: result.connectors[0] };
119
+ }
120
+
121
+ export async function resolveIdentity(options = {}) {
122
+ const {
123
+ alias,
124
+ connector: known,
125
+ cwd = process.cwd(),
126
+ list = listConfiguredConnectors,
127
+ } = options;
128
+ if (!alias) {
129
+ return {};
130
+ }
131
+ let connector = known;
132
+ if (!connector) {
133
+ const result = await list({ cwd });
134
+ if (!result.ok) {
135
+ return { error: result.error };
136
+ }
137
+ connector = result.connectors.find(
138
+ (entry) =>
139
+ entry?.type === 'fabric-semanticmodel' &&
140
+ typeof entry.name === 'string' &&
141
+ entry.name.toLocaleLowerCase() === String(alias).toLocaleLowerCase()
142
+ );
143
+ }
144
+ if (!connector) {
145
+ return {
146
+ error:
147
+ `Semantic model connector "${alias}" was not found. ` +
148
+ 'Run `npx rayfin connector list --json` from the app root.',
149
+ };
150
+ }
151
+ const datasetId = connector.config?.itemId;
152
+ if (!isFabricGuid(datasetId)) {
153
+ return {
154
+ error:
155
+ `Semantic model connector "${alias}" has an invalid itemId. ` +
156
+ 'Reconnect it with `npx rayfin connector add`.',
157
+ };
158
+ }
159
+ return {
160
+ datasetId,
161
+ workspaceId:
162
+ typeof connector.config?.workspaceId === 'string'
163
+ ? connector.config.workspaceId
164
+ : null,
165
+ };
166
+ }
@@ -0,0 +1,271 @@
1
+ //-----------------------------------------------------------------------
2
+ // <copyright company="Microsoft Corporation">
3
+ // Copyright (c) Microsoft Corporation. All rights reserved.
4
+ // Licensed under the MIT license. See LICENSE file in the project root for full license information.
5
+ // </copyright>
6
+ //-----------------------------------------------------------------------
7
+
8
+ import assert from 'node:assert/strict';
9
+ import { EventEmitter } from 'node:events';
10
+ import test from 'node:test';
11
+
12
+ import {
13
+ isFabricGuid,
14
+ normalizeColName,
15
+ parseQueryOutput,
16
+ resolveAlias,
17
+ resolveIdentity,
18
+ runFabricQuery,
19
+ } from './schema.mjs';
20
+
21
+ const DATASET_ID = '11111111-2222-3333-4444-555555555555';
22
+ const WORKSPACE_ID = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';
23
+
24
+ const connectors = [
25
+ {
26
+ name: 'sales',
27
+ type: 'fabric-semanticmodel',
28
+ config: { workspaceId: WORKSPACE_ID, itemId: DATASET_ID },
29
+ },
30
+ {
31
+ name: 'sql',
32
+ type: 'fabric-sql',
33
+ config: { workspaceId: 'ws-2', itemId: 'wh-1' },
34
+ },
35
+ ];
36
+
37
+ test('resolveIdentity uses connector list output instead of parsing rayfin.yml', async () => {
38
+ const identity = await resolveIdentity({
39
+ alias: 'SALES',
40
+ list: async () => ({ ok: true, connectors }),
41
+ });
42
+ assert.deepEqual(identity, {
43
+ datasetId: DATASET_ID,
44
+ workspaceId: WORKSPACE_ID,
45
+ });
46
+ });
47
+
48
+ test('resolveIdentity rejects a connector itemId that is not a GUID', async () => {
49
+ const identity = await resolveIdentity({
50
+ alias: 'sales',
51
+ list: async () => ({
52
+ ok: true,
53
+ connectors: [
54
+ {
55
+ name: 'sales',
56
+ type: 'fabric-semanticmodel',
57
+ config: { itemId: '../outside' },
58
+ },
59
+ ],
60
+ }),
61
+ });
62
+ assert.match(identity.error, /invalid itemId/i);
63
+ assert.equal(isFabricGuid('../outside'), false);
64
+ assert.equal(isFabricGuid(DATASET_ID), true);
65
+ });
66
+
67
+ test('resolveIdentity returns a readable resolution error', async () => {
68
+ const identity = await resolveIdentity({
69
+ alias: 'sales',
70
+ list: async () => ({
71
+ ok: false,
72
+ error:
73
+ 'Could not resolve connectors because connector list returned empty stdout.',
74
+ }),
75
+ });
76
+ assert.match(identity.error, /Could not resolve connectors/i);
77
+ });
78
+
79
+ test('resolveAlias treats a list launch failure as a resolution error', async () => {
80
+ const out = await resolveAlias('.', undefined, {
81
+ cliEntry: 'rayfin-entry',
82
+ spawnImpl: () => {
83
+ throw new Error('This test injects at the list boundary instead.');
84
+ },
85
+ });
86
+ assert.match(
87
+ out.error,
88
+ /Could not run the Rayfin CLI/i,
89
+ 'a failed list command must be a resolution error, not zero connectors'
90
+ );
91
+ });
92
+
93
+ test('resolveAlias selects the only semantic-model connector', async () => {
94
+ const out = await resolveAlias('.', undefined, {
95
+ cliEntry: 'rayfin-entry',
96
+ spawnImpl: () => {
97
+ const child = new EventEmitter();
98
+ child.stdout = new EventEmitter();
99
+ child.stderr = new EventEmitter();
100
+ queueMicrotask(() => {
101
+ child.stdout.emit('data', JSON.stringify(connectors));
102
+ child.emit('close', 0, null);
103
+ });
104
+ return child;
105
+ },
106
+ });
107
+ assert.equal(out.alias, 'sales');
108
+ assert.equal(out.connector?.name, 'sales');
109
+ });
110
+
111
+ test('resolveAlias gives a valid connector add command when none exist', async () => {
112
+ const out = await resolveAlias('.', undefined, {
113
+ cliEntry: 'rayfin-entry',
114
+ spawnImpl: () => {
115
+ const child = new EventEmitter();
116
+ child.stdout = new EventEmitter();
117
+ child.stderr = new EventEmitter();
118
+ queueMicrotask(() => {
119
+ child.stdout.emit('data', '[]');
120
+ child.emit('close', 0, null);
121
+ });
122
+ return child;
123
+ },
124
+ });
125
+ assert.match(out.error, /--type fabric-semanticmodel/u);
126
+ assert.match(out.error, /--workspace-id <workspace-id>/u);
127
+ assert.match(out.error, /--item-id <item-id>/u);
128
+ assert.doesNotMatch(out.error, /--url/u);
129
+ });
130
+
131
+ test('resolveAlias honors an explicit alias without running the CLI', async () => {
132
+ assert.deepEqual(await resolveAlias('.', 'sales'), { alias: 'sales' });
133
+ });
134
+
135
+ test('parseQueryOutput preserves Rayfin column names', () => {
136
+ const result = parseQueryOutput({
137
+ status: 'success',
138
+ table: {
139
+ columns: [{ name: '[Table]' }, { name: '[Max Length]' }],
140
+ rows: [['Sales', 12]],
141
+ },
142
+ });
143
+ assert.deepEqual(result, {
144
+ ok: true,
145
+ columns: [
146
+ { name: 'Table', dataType: 'unknown' },
147
+ { name: 'Max Length', dataType: 'unknown' },
148
+ ],
149
+ rows: [{ Table: 'Sales', 'Max Length': 12 }],
150
+ });
151
+ assert.equal(normalizeColName('plain'), 'plain');
152
+ });
153
+
154
+ test('parseQueryOutput does not implement the dead _cliWarning branch', () => {
155
+ const result = parseQueryOutput({
156
+ status: 'success',
157
+ _cliWarning: 'Result trimmed to first 1000 of 1492 rows',
158
+ table: {
159
+ columns: [{ name: '[Name]' }],
160
+ rows: [['Sales']],
161
+ },
162
+ });
163
+ assert.deepEqual(result, {
164
+ ok: true,
165
+ columns: [{ name: 'Name', dataType: 'unknown' }],
166
+ rows: [{ Name: 'Sales' }],
167
+ });
168
+ assert.equal(
169
+ Object.hasOwn(result, 'truncated'),
170
+ false,
171
+ 'Rayfin reports query overflow as a hard error, not _cliWarning'
172
+ );
173
+ });
174
+
175
+ test('runFabricQuery imports invokeConnector directly and makes one invoke', async () => {
176
+ const calls = [];
177
+ const result = await runFabricQuery('EVALUATE INFO.VIEW.TABLES()', {
178
+ alias: 'sales',
179
+ cwd: 'C:\\app',
180
+ invoke: async (options) => {
181
+ calls.push(options);
182
+ return {
183
+ ok: true,
184
+ output: {
185
+ status: 'success',
186
+ table: {
187
+ columns: [{ name: '[Name]', dataType: 'String' }],
188
+ rows: [['Sales']],
189
+ },
190
+ },
191
+ };
192
+ },
193
+ });
194
+ assert.equal(calls.length, 1);
195
+ assert.deepEqual(calls[0], {
196
+ connector: 'sales',
197
+ query: 'EVALUATE INFO.VIEW.TABLES()',
198
+ limit: undefined,
199
+ cwd: 'C:\\app',
200
+ });
201
+ assert.deepEqual(result.columns, [{ name: 'Name', dataType: 'String' }]);
202
+ assert.deepEqual(result.rows, [{ Name: 'Sales' }]);
203
+ });
204
+
205
+ test('one CLI spawn resolves both the alias and the dataset id', async () => {
206
+ // resolveAlias already holds the connector record; re-listing it in
207
+ // resolveIdentity doubled the spawn count on every schema:sql call.
208
+ const connectors = [
209
+ {
210
+ name: 'model',
211
+ type: 'fabric-semanticmodel',
212
+ config: { itemId: '11111111-2222-3333-4444-555555555555' },
213
+ },
214
+ ];
215
+ let spawns = 0;
216
+ const spawnImpl = () => {
217
+ spawns += 1;
218
+ const child = new EventEmitter();
219
+ child.stdout = new EventEmitter();
220
+ child.stderr = new EventEmitter();
221
+ queueMicrotask(() => {
222
+ child.stdout.emit('data', JSON.stringify(connectors));
223
+ child.emit('close', 0, null);
224
+ });
225
+ return child;
226
+ };
227
+ const cli = { cliEntry: 'rayfin-entry', spawnImpl };
228
+
229
+ const resolved = await resolveAlias('.', undefined, cli);
230
+ assert.equal(resolved.alias, 'model');
231
+ assert.equal(spawns, 1);
232
+
233
+ const identity = await resolveIdentity({
234
+ alias: resolved.alias,
235
+ connector: resolved.connector,
236
+ ...cli,
237
+ });
238
+ assert.equal(identity.datasetId, '11111111-2222-3333-4444-555555555555');
239
+ assert.equal(spawns, 1, 'the second lookup reuses the first result');
240
+ });
241
+
242
+ test('an explicit --alias still resolves its dataset id', async () => {
243
+ // resolveAlias returns early for an explicit alias and has no record to
244
+ // pass on, so resolveIdentity falls back to its own lookup.
245
+ let calls = 0;
246
+ const list = async () => {
247
+ calls += 1;
248
+ return {
249
+ ok: true,
250
+ connectors: [
251
+ {
252
+ name: 'model',
253
+ type: 'fabric-semanticmodel',
254
+ config: { itemId: '11111111-2222-3333-4444-555555555555' },
255
+ },
256
+ ],
257
+ };
258
+ };
259
+
260
+ const resolved = await resolveAlias('.', 'model');
261
+ assert.equal(resolved.alias, 'model');
262
+ assert.equal(resolved.connector, undefined);
263
+
264
+ const identity = await resolveIdentity({
265
+ alias: resolved.alias,
266
+ connector: resolved.connector,
267
+ list,
268
+ });
269
+ assert.equal(identity.datasetId, '11111111-2222-3333-4444-555555555555');
270
+ assert.equal(calls, 1);
271
+ });
@@ -0,0 +1,49 @@
1
+ {
2
+ "name": "analytics",
3
+ "description": "Power BI / semantic-model analytics: the `fabric-semanticmodel` connector and the semantic-model query hook. Add the visuals pack alongside it to chart what the queries return.",
4
+ "packageJson": "packages/frontend/package.json",
5
+ "rayfin": {
6
+ "services": {
7
+ "connectors": {
8
+ "enabled": true
9
+ }
10
+ }
11
+ },
12
+ "dependencies": {
13
+ "@microsoft/rayfin-connectors": "match:@microsoft/rayfin-core",
14
+ "@microsoft/rayfin-connector-fabric-semanticmodel": "match:@microsoft/rayfin-core"
15
+ },
16
+ "scripts": {
17
+ "schema:sql": "node --disable-warning=ExperimentalWarning scripts/schema-sql.mjs",
18
+ "schema:refresh": "node --disable-warning=ExperimentalWarning scripts/schema-sql.mjs --refresh"
19
+ },
20
+ "scriptFlags": {
21
+ "schema:sql": "schema-sqlite",
22
+ "schema:refresh": "schema-sqlite"
23
+ },
24
+ "gitignore": [".schema/", ".rayfin-schema-query-*/"],
25
+ "copy": [
26
+ { "from": "kit/hooks", "to": "packages/frontend/src/hooks" },
27
+ {
28
+ "from": "kit/lib/connectors.ts",
29
+ "to": "packages/frontend/src/lib/connectors.ts",
30
+ "initializationOnly": true
31
+ },
32
+ {
33
+ "from": "kit/scripts/rayfin-connector.mjs",
34
+ "to": "scripts/rayfin-connector.mjs",
35
+ "whenFlag": "schema-sqlite"
36
+ },
37
+ {
38
+ "from": "kit/scripts/schema.mjs",
39
+ "to": "scripts/schema.mjs",
40
+ "whenFlag": "schema-sqlite"
41
+ },
42
+ {
43
+ "from": "kit/scripts/schema-sql.mjs",
44
+ "to": "scripts/schema-sql.mjs",
45
+ "whenFlag": "schema-sqlite"
46
+ }
47
+ ],
48
+ "next": ["analytics"]
49
+ }
@@ -0,0 +1,172 @@
1
+ ---
2
+ name: dax-authoring
3
+ description: >
4
+ Write and test DAX queries against Power BI semantic models.
5
+ Covers DAX syntax rules, query patterns, time intelligence,
6
+ and an iterative test workflow using `npx rayfin connector invoke`.
7
+ ---
8
+
9
+ # DAX Authoring
10
+
11
+ ## Table of Contents
12
+
13
+ | Task | Reference | Notes |
14
+ |---|---|---|
15
+ | Must/Prefer/Avoid | [SKILL.md: Must/Prefer/Avoid](#must--prefer--avoid) | Guardrails for DAX query generation |
16
+ | Generating DAX Queries | [SKILL.md: Generating DAX Queries](#generating-dax-queries) | Core rules, inline examples, EVALUATE/DEFINE patterns |
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
+ | DAX Query Key Components | [dax-query-patterns.md: Key Components](./references/dax-query-patterns.md#key-components) | DEFINE VAR, DEFINE MEASURE, table expressions |
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 Anti-Patterns | [dax-query-patterns.md: Anti-Patterns](./references/dax-query-patterns.md#anti-patterns) | What to avoid in DAX queries |
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
+ | SUMMARIZECOLUMNS | [dax-core-reference.md: SUMMARIZECOLUMNS](./references/dax-core-reference.md#summarizecolumns) | Argument order, auto-blank elimination, filter args, vs SUMMARIZE |
23
+ | ALL & ALLEXCEPT | [dax-core-reference.md: ALL & ALLEXCEPT](./references/dax-core-reference.md#all--allexcept) | CALCULATE modifier vs table function; percentage patterns |
24
+ | TREATAS | [dax-core-reference.md: TREATAS](./references/dax-core-reference.md#treatas) | Virtual relationships, multi-column filtering |
25
+ | DAX Syntax Rules | [dax-core-reference.md: DAX Syntax Rules](./references/dax-core-reference.md#dax-syntax-rules) | EVALUATE, CALCULATE, naming, SQL keywords, DEFINE rules |
26
+ | Common Mistakes | [dax-core-reference.md: Common Mistakes](./references/dax-core-reference.md#common-mistakes) | Variable naming, quoting, escaping, scalar EVALUATE, multi-table SUMMARIZECOLUMNS |
27
+ | BLANK Semantics | [dax-core-reference.md: BLANK Semantics](./references/dax-core-reference.md#blank-semantics) | BLANK vs NULL, propagation, equality, ISBLANK, DIVIDE, non-empty semantics |
28
+ | Time Intelligence Patterns | [SKILL.md: Time Intelligence](#time-intelligence) | When to consult TI reference |
29
+ | Date Table Prerequisites | [dax-time-intelligence.md: Prerequisites](./references/dax-time-intelligence.md#prerequisites) | Date table requirements, mark as date table |
30
+ | YTD / QTD / MTD | [dax-time-intelligence.md: Period-to-Date](./references/dax-time-intelligence.md#period-to-date) | TOTALYTD, DATESYTD, DATESINPERIOD patterns |
31
+ | Year-over-Year / Period Comparisons | [dax-time-intelligence.md: Period Comparisons](./references/dax-time-intelligence.md#period-comparisons) | SAMEPERIODLASTYEAR, DATEADD, PARALLELPERIOD |
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: Balances](./references/dax-time-intelligence.md#balances) | Semi-additive measures, LASTDATE, LASTNONBLANK |
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
+ | TI Common Mistakes | [dax-time-intelligence.md: Common Mistakes](./references/dax-time-intelligence.md#common-mistakes) | Missing date table, wrong granularity, fiscal calendar |
36
+ | Testing & Iteration | [SKILL.md: Testing & Iteration](#testing--iteration) | Execute → inspect → fix → re-test workflow |
37
+
38
+ ## Must / Prefer / Avoid
39
+
40
+ ### Must
41
+
42
+ - Always test generated DAX via `npx rayfin connector invoke <alias> executeQuery --file <query>.query.json` before using in app code
43
+ - Use fully-qualified `'Table'[Column]` for column references
44
+ - Use simple `[Measure]` for measure references
45
+ - Use DEFINE for VAR and local MEASURE declarations (single DEFINE block, no commas)
46
+ - Prefer existing model measures over re-aggregating raw data
47
+ - **Never reshape a stored measure to work around a decoding bug.** Wrapping it
48
+ in `CONVERT(...)` changes the value the app reads, and `CONVERT([Measure],
49
+ DOUBLE)` silently drops every row whose branch returned text. If the CLI and
50
+ the app disagree by a power of ten, check that both carry a connector build
51
+ with the Arrow union decoder fix — `@microsoft/rayfin-cli` bundles its own
52
+ copy, and the app installs `@microsoft/rayfin-connector-fabric-semanticmodel`
53
+ separately under `packages/frontend`, so upgrading one does not update the
54
+ other. Fix the build, keep the measure.
55
+
56
+ ### Prefer
57
+
58
+ - SUMMARIZECOLUMNS as the primary grouping function for queries
59
+ - TREATAS for filter arguments in SUMMARIZECOLUMNS
60
+ - Variables (VAR) to improve readability and avoid repeated calculations
61
+
62
+ ### Avoid
63
+
64
+ - SQL keywords (SELECT, WHERE, HAVING, etc.) within DAX expressions
65
+ - EVALUATE with scalar functions directly (wrap in ROW or table function)
66
+
67
+ ## Generating DAX Queries
68
+
69
+ ### DAX Syntax Rules
70
+
71
+ - Measures are named objects in the semantic model. They specify how to aggregate data. **Measures should be used first** to answer user requests before a new DAX formula is used to aggregate data.
72
+ - **EVALUATE Statement**: Not a function but a statement. It must always precede a table expression. Avoid pairing EVALUATE with scalar functions like CONCATENATEX, SUMX, DISTINCTCOUNT, etc.
73
+ - Use the fully-qualified name `'Table'[Column]` for column references, and the simple name `[Measure]` for measure references.
74
+ - CALCULATE takes a scalar expression as its first argument. CALCULATETABLE takes a table expression as its first argument.
75
+ - SUMMARIZECOLUMNS requires a specific order: groupby columns, then filters, then aggregations/measures.
76
+ - Do not use SUMMARIZECOLUMNS when there is no aggregation and the groupby columns belong to more than one table; use VALUES, SUMMARIZE, or SELECTCOLUMNS instead.
77
+ - When using SELECTCOLUMNS or CALCULATETABLE, include any columns needed downstream (ORDER BY, FILTER).
78
+ - Filters propagate across relationships based on unidirectional or bidirectional settings.
79
+ - INTERSECT, UNION, EXCEPT require identical column counts in both inputs.
80
+ - For current date/time, use TODAY() or NOW().
81
+
82
+ ### Inline Examples
83
+
84
+ **Simple filtered aggregation:**
85
+
86
+ ```dax
87
+ // Total sales for red products
88
+ EVALUATE
89
+ ROW("Total Sales Amount", CALCULATE([Total Amount], 'Product'[Color] == "Red"))
90
+ ```
91
+
92
+ **Multi-filter grouping with SUMMARIZECOLUMNS:**
93
+
94
+ ```dax
95
+ DEFINE
96
+ VAR _Filter1 = TREATAS({"Consumer Electronics"}, 'Product'[Category])
97
+ VAR _Filter2 = FILTER(ALL('Calendar'[Year]), 'Calendar'[Year] >= 2022 && 'Calendar'[Year] <= 2023)
98
+
99
+ EVALUATE
100
+ SUMMARIZECOLUMNS(
101
+ 'Calendar'[Year],
102
+ 'Calendar'[Month],
103
+ _Filter1,
104
+ _Filter2,
105
+ "Total Quantity", SUM('Sales'[Order Quantity]),
106
+ "Discount", [Total Discount]
107
+ )
108
+ ```
109
+
110
+ **TopN with filtering:**
111
+
112
+ ```dax
113
+ DEFINE
114
+ VAR _Filter = TREATAS({"Red", "Black"}, 'Product'[Color])
115
+ VAR _Core = SUMMARIZECOLUMNS('Product'[Name], _Filter, "Total Sales", [Total Amount])
116
+
117
+ EVALUATE
118
+ TOPN(10, _Core, [Total Sales], DESC)
119
+ ```
120
+
121
+ For full syntax reference, worked examples, and anti-patterns, see [dax-query-patterns.md](./references/dax-query-patterns.md).
122
+ For function details, see [dax-core-reference.md](./references/dax-core-reference.md).
123
+
124
+ ## Time Intelligence
125
+
126
+ Time intelligence functions enable period-based analysis (YTD, YoY, rolling windows, etc.). They require a properly configured Date table.
127
+
128
+ Consult [dax-time-intelligence.md](./references/dax-time-intelligence.md) whenever the user's request involves:
129
+ - Period-to-date calculations (YTD, QTD, MTD)
130
+ - Period comparisons (Year-over-Year, Month-over-Month)
131
+ - Rolling windows (last 12 months, last 30 days)
132
+ - Opening/closing balances
133
+ - Custom date ranges
134
+
135
+ ## Testing & Iteration
136
+
137
+ 1. Generate the DAX query expression
138
+ 2. Execute via `npx rayfin connector invoke <alias> executeQuery --file <query>.query.json`
139
+ 3. Inspect results: check column names, data types, row counts, and actual data values
140
+ 4. If error: consult [dax-core-reference.md](./references/dax-core-reference.md), fix, and re-test
141
+ 5. Iterate until the query returns expected results
142
+
143
+ ## Query Execution
144
+
145
+ Use `npx rayfin connector invoke <alias> executeQuery --file <query>.query.json` to run queries. This uses the same SDK pipeline as the running app, so results are identical to what the app produces at runtime. `--file` takes the operation's JSON input envelope — `{"query":"EVALUATE …"}` — not a bare `.dax` file, which is `JSON.parse`d and fails. Prefer it over `--input` for anything non-trivial: DAX is full of quotes and brackets that a shell reads as syntax. For full CLI options, see `npx rayfin connector invoke --help`.
146
+
147
+ **There is no row cap.** A query with no `resultSetRowCountLimit` returns every
148
+ row it matches, on the CLI and in the app alike, so an unbounded `EVALUATE` over
149
+ a large table is a real hazard rather than a truncated preview. Bound it
150
+ yourself — either in the DAX with an aggregation or `TOPN(...)`, or by adding the
151
+ field to the input envelope:
152
+
153
+ ```json
154
+ { "query": "EVALUATE Sales", "resultSetRowCountLimit": 500 }
155
+ ```
156
+
157
+ Prefer the field over `TOPN` when you want a guard rather than a deliberately
158
+ ranked subset: exceeding it **fails** the query with an `overflow` error, so a
159
+ bound that was too tight announces itself, where `TOPN` returns a
160
+ complete-looking partial answer. A value that is not a positive integer is
161
+ dropped silently and the query runs unbounded.
162
+
163
+ ## Troubleshooting
164
+
165
+ | Problem | Solution |
166
+ |---------|----------|
167
+ | `connector invoke` fails with "not signed in" | Run `npx rayfin login` |
168
+ | `connector invoke` fails with "alias not found" | Run `npx rayfin connector list` to check available aliases, then `npx rayfin connector add --type fabric-semanticmodel` to register |
169
+ | `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) |
170
+ | DAX syntax errors | Consult [dax-core-reference.md](./references/dax-core-reference.md) — check reserved keywords, quoting rules, EVALUATE/scalar mistakes |
171
+ | Unexpected query results | Check filter context, relationship direction, BLANK handling in [dax-core-reference.md](./references/dax-core-reference.md#blank-semantics) |
172
+ | Time intelligence returns wrong values | Check date table prerequisites and critical rules in [dax-time-intelligence.md](./references/dax-time-intelligence.md) |