@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,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) |
|