@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,342 @@
|
|
|
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
|
+
// Runs once the pack has copied this kit into an app: the template's vitest
|
|
9
|
+
// `include` is `src/**/*.spec.ts`, and these imports resolve against the copied
|
|
10
|
+
// locations rather than the kit.
|
|
11
|
+
//
|
|
12
|
+
// Only the Rayfin client is mocked, so the connector's own `toQueryResult` runs
|
|
13
|
+
// for real against wire-shaped responses.
|
|
14
|
+
|
|
15
|
+
import { renderHook, act, waitFor } from '@testing-library/react';
|
|
16
|
+
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
|
17
|
+
|
|
18
|
+
import { useSemanticModelQuery } from '@/hooks/use-semantic-model-query';
|
|
19
|
+
|
|
20
|
+
const executeQuery = vi.fn();
|
|
21
|
+
const connectors: Record<string, unknown> = {};
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Stands in for the SDK's connectors proxy, which **throws**
|
|
25
|
+
* `ConnectorsError('UNKNOWN_CONNECTOR')` for an unconfigured name rather than
|
|
26
|
+
* returning `undefined`.
|
|
27
|
+
*/
|
|
28
|
+
const connectorsProxy = new Proxy(connectors, {
|
|
29
|
+
get(target, key: string) {
|
|
30
|
+
if (!(key in target)) {
|
|
31
|
+
throw Object.assign(
|
|
32
|
+
new Error(`Connector "${key}" was accessed but has no configuration.`),
|
|
33
|
+
{ code: 'UNKNOWN_CONNECTOR' }
|
|
34
|
+
);
|
|
35
|
+
}
|
|
36
|
+
return target[key];
|
|
37
|
+
},
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
let clientHasConnectors = true;
|
|
41
|
+
|
|
42
|
+
vi.mock('@/lib/rayfin-client', () => ({
|
|
43
|
+
// Async, matching this template's client: the hook has to await it rather
|
|
44
|
+
// than index a synchronous singleton.
|
|
45
|
+
getRayfinClient: () =>
|
|
46
|
+
Promise.resolve(clientHasConnectors ? { connectors: connectorsProxy } : {}),
|
|
47
|
+
}));
|
|
48
|
+
|
|
49
|
+
/** A wire-shaped success, as the FuncSet adapter returns it. */
|
|
50
|
+
const wireSuccess = (total: number) => ({
|
|
51
|
+
status: 'Succeeded',
|
|
52
|
+
output: {
|
|
53
|
+
tables: [{ rows: [{ 'Sales[Total]': total }] }],
|
|
54
|
+
requestId: 'r1',
|
|
55
|
+
},
|
|
56
|
+
errors: [],
|
|
57
|
+
});
|
|
58
|
+
|
|
59
|
+
describe('useSemanticModelQuery', () => {
|
|
60
|
+
beforeEach(() => {
|
|
61
|
+
vi.clearAllMocks();
|
|
62
|
+
for (const key of Object.keys(connectors)) delete connectors[key];
|
|
63
|
+
connectors.model = { executeQuery };
|
|
64
|
+
clientHasConnectors = true;
|
|
65
|
+
});
|
|
66
|
+
|
|
67
|
+
const render = (connection = 'model', query = 'EVALUATE ROW()') =>
|
|
68
|
+
renderHook(() => useSemanticModelQuery({ connection, query }));
|
|
69
|
+
|
|
70
|
+
it('starts in the loading state', () => {
|
|
71
|
+
executeQuery.mockReturnValue(new Promise(() => {}));
|
|
72
|
+
|
|
73
|
+
const { result } = render();
|
|
74
|
+
|
|
75
|
+
expect(result.current.isLoading).toBe(true);
|
|
76
|
+
expect(result.current.data).toBeUndefined();
|
|
77
|
+
expect(result.current.error).toBeUndefined();
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
it('normalises a successful response into column-aligned rows', async () => {
|
|
81
|
+
executeQuery.mockResolvedValue(wireSuccess(42));
|
|
82
|
+
|
|
83
|
+
const { result } = render();
|
|
84
|
+
|
|
85
|
+
await waitFor(() => expect(result.current.isLoading).toBe(false));
|
|
86
|
+
expect(result.current.data).toEqual({
|
|
87
|
+
status: 'success',
|
|
88
|
+
table: {
|
|
89
|
+
columns: [{ name: 'Sales[Total]', dataType: 'unknown' }],
|
|
90
|
+
rows: [[42]],
|
|
91
|
+
},
|
|
92
|
+
requestId: 'r1',
|
|
93
|
+
});
|
|
94
|
+
expect(result.current.error).toBeUndefined();
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
it('publishes an already-normalised result unchanged', async () => {
|
|
98
|
+
// A registered runtime normalises internally, so this arrives as the union
|
|
99
|
+
// rather than the wire shape. A connector missing from `connectorRuntimes`
|
|
100
|
+
// falls through to raw JSON and does arrive in the wire shape, so this
|
|
101
|
+
// pins that both paths agree.
|
|
102
|
+
executeQuery.mockResolvedValue({
|
|
103
|
+
status: 'success',
|
|
104
|
+
table: {
|
|
105
|
+
columns: [{ name: 'Sales[Total]', dataType: 'unknown' }],
|
|
106
|
+
rows: [[7]],
|
|
107
|
+
},
|
|
108
|
+
requestId: 'r9',
|
|
109
|
+
});
|
|
110
|
+
|
|
111
|
+
const { result } = render();
|
|
112
|
+
|
|
113
|
+
await waitFor(() => expect(result.current.data).toBeDefined());
|
|
114
|
+
expect(result.current.data).toEqual({
|
|
115
|
+
status: 'success',
|
|
116
|
+
table: {
|
|
117
|
+
columns: [{ name: 'Sales[Total]', dataType: 'unknown' }],
|
|
118
|
+
rows: [[7]],
|
|
119
|
+
},
|
|
120
|
+
requestId: 'r9',
|
|
121
|
+
});
|
|
122
|
+
expect(result.current.error).toBeUndefined();
|
|
123
|
+
});
|
|
124
|
+
|
|
125
|
+
it('reports a failure Power BI returned on the data channel only', async () => {
|
|
126
|
+
executeQuery.mockResolvedValue({
|
|
127
|
+
status: 'Succeeded',
|
|
128
|
+
output: { tables: [], queryError: { message: 'bad DAX' } },
|
|
129
|
+
errors: [],
|
|
130
|
+
});
|
|
131
|
+
|
|
132
|
+
const { result } = render();
|
|
133
|
+
|
|
134
|
+
await waitFor(() => expect(result.current.data).toBeDefined());
|
|
135
|
+
expect(result.current.data?.status).toBe('error');
|
|
136
|
+
// Categorised by the connector, not invented here.
|
|
137
|
+
expect(
|
|
138
|
+
result.current.data?.status === 'error' && result.current.data.error
|
|
139
|
+
).toMatchObject({ category: 'query', message: 'bad DAX' });
|
|
140
|
+
// `error` must stay clear, or a caller checking it first never reaches the
|
|
141
|
+
// structured branch and the category is unreachable.
|
|
142
|
+
expect(result.current.error).toBeUndefined();
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
it('surfaces the thrown error itself, not a copy of its message', async () => {
|
|
146
|
+
// Re-wrapping into a fresh Error keeps only the message and drops the
|
|
147
|
+
// status and service code — exactly what separates an auth failure from a
|
|
148
|
+
// malformed query.
|
|
149
|
+
const thrown = Object.assign(new Error('401 Unauthorized'), {
|
|
150
|
+
status: 401,
|
|
151
|
+
});
|
|
152
|
+
executeQuery.mockRejectedValue(thrown);
|
|
153
|
+
|
|
154
|
+
const { result } = render();
|
|
155
|
+
|
|
156
|
+
await waitFor(() => expect(result.current.error).toBeDefined());
|
|
157
|
+
expect(result.current.error).toBe(thrown);
|
|
158
|
+
expect((result.current.error as { status?: number }).status).toBe(401);
|
|
159
|
+
});
|
|
160
|
+
|
|
161
|
+
it('clears a stale result when a later query throws', async () => {
|
|
162
|
+
// Prevents rows staying on screen under an error banner. Asserting this on
|
|
163
|
+
// the first query would pass either way - there has to be a result to lose.
|
|
164
|
+
executeQuery.mockResolvedValueOnce(wireSuccess(42));
|
|
165
|
+
const { result, rerender } = renderHook(
|
|
166
|
+
({ query }) => useSemanticModelQuery({ connection: 'model', query }),
|
|
167
|
+
{ initialProps: { query: 'EVALUATE ROW()' } }
|
|
168
|
+
);
|
|
169
|
+
await waitFor(() => expect(result.current.data).toBeDefined());
|
|
170
|
+
|
|
171
|
+
executeQuery.mockRejectedValueOnce(new Error('401 Unauthorized'));
|
|
172
|
+
rerender({ query: 'EVALUATE ROW(2)' });
|
|
173
|
+
|
|
174
|
+
await waitFor(() => expect(result.current.error).toBeDefined());
|
|
175
|
+
// A throw is not something Power BI returned, so it must not be dressed up
|
|
176
|
+
// as a result either.
|
|
177
|
+
expect(result.current.data).toBeUndefined();
|
|
178
|
+
});
|
|
179
|
+
|
|
180
|
+
it('names an unregistered connector as a wiring mistake', async () => {
|
|
181
|
+
// The proxy throws for a name with no config. Left untranslated that
|
|
182
|
+
// surfaces as a generic transport failure, sending the builder to look at
|
|
183
|
+
// Fabric instead of at their own registration.
|
|
184
|
+
delete connectors.model;
|
|
185
|
+
|
|
186
|
+
const { result } = render();
|
|
187
|
+
|
|
188
|
+
await waitFor(() => expect(result.current.error).toBeDefined());
|
|
189
|
+
expect(result.current.error?.message).toContain('connectorRuntimes');
|
|
190
|
+
// The original is kept so the SDK's own code is still recoverable.
|
|
191
|
+
expect((result.current.error?.cause as { code?: string })?.code).toBe(
|
|
192
|
+
'UNKNOWN_CONNECTOR'
|
|
193
|
+
);
|
|
194
|
+
expect(executeQuery).not.toHaveBeenCalled();
|
|
195
|
+
});
|
|
196
|
+
|
|
197
|
+
it('says so when the app never wired ConnectorsRayfinClient', async () => {
|
|
198
|
+
// The base template builds a plain RayfinClient with no `connectors`, and no
|
|
199
|
+
// pack rewrites that file. Without this the first symptom is an unrelated
|
|
200
|
+
// TypeError deep in the hook.
|
|
201
|
+
clientHasConnectors = false;
|
|
202
|
+
|
|
203
|
+
const { result } = render();
|
|
204
|
+
|
|
205
|
+
await waitFor(() => expect(result.current.error).toBeDefined());
|
|
206
|
+
expect(result.current.error?.message).toContain('ConnectorsRayfinClient');
|
|
207
|
+
expect(executeQuery).not.toHaveBeenCalled();
|
|
208
|
+
});
|
|
209
|
+
|
|
210
|
+
it('does not let a slow earlier query overwrite a newer result', async () => {
|
|
211
|
+
let resolveSlow: (value: unknown) => void = () => {};
|
|
212
|
+
executeQuery.mockReturnValueOnce(
|
|
213
|
+
new Promise((resolve) => {
|
|
214
|
+
resolveSlow = resolve;
|
|
215
|
+
})
|
|
216
|
+
);
|
|
217
|
+
|
|
218
|
+
const { result, rerender } = renderHook(
|
|
219
|
+
({ query }) => useSemanticModelQuery({ connection: 'model', query }),
|
|
220
|
+
{ initialProps: { query: 'EVALUATE ROW()' } }
|
|
221
|
+
);
|
|
222
|
+
|
|
223
|
+
executeQuery.mockResolvedValueOnce(wireSuccess(2));
|
|
224
|
+
rerender({ query: 'EVALUATE ROW(2)' });
|
|
225
|
+
await waitFor(() =>
|
|
226
|
+
expect(result.current.data?.status === 'success').toBe(true)
|
|
227
|
+
);
|
|
228
|
+
|
|
229
|
+
// The first query lands last and must not publish. A microtask is not
|
|
230
|
+
// enough to prove that: a stale publish needs several turns plus a React
|
|
231
|
+
// flush to become visible, so asserting too early passes either way.
|
|
232
|
+
await act(async () => {
|
|
233
|
+
resolveSlow(wireSuccess(999));
|
|
234
|
+
await new Promise((resolve) => setTimeout(resolve, 20));
|
|
235
|
+
});
|
|
236
|
+
|
|
237
|
+
expect(
|
|
238
|
+
result.current.data?.status === 'success' &&
|
|
239
|
+
result.current.data.table.rows
|
|
240
|
+
).toEqual([[2]]);
|
|
241
|
+
});
|
|
242
|
+
|
|
243
|
+
it('clears a previous result when it goes idle', async () => {
|
|
244
|
+
executeQuery.mockResolvedValue(wireSuccess(1));
|
|
245
|
+
|
|
246
|
+
const { result, rerender } = renderHook(
|
|
247
|
+
({ query }) => useSemanticModelQuery({ connection: 'model', query }),
|
|
248
|
+
{ initialProps: { query: 'EVALUATE ROW()' } }
|
|
249
|
+
);
|
|
250
|
+
await waitFor(() => expect(result.current.data).toBeDefined());
|
|
251
|
+
|
|
252
|
+
// Leaving the rows in place renders data for a query that no longer
|
|
253
|
+
// applies.
|
|
254
|
+
rerender({ query: '' });
|
|
255
|
+
|
|
256
|
+
await waitFor(() => expect(result.current.data).toBeUndefined());
|
|
257
|
+
expect(result.current.isLoading).toBe(false);
|
|
258
|
+
});
|
|
259
|
+
|
|
260
|
+
it('keeps the previous result while an explicit refetch is loading', async () => {
|
|
261
|
+
executeQuery.mockResolvedValueOnce(wireSuccess(1));
|
|
262
|
+
const { result } = render();
|
|
263
|
+
await waitFor(() => expect(result.current.data).toBeDefined());
|
|
264
|
+
|
|
265
|
+
let resolveNext!: (value: unknown) => void;
|
|
266
|
+
executeQuery.mockReturnValueOnce(
|
|
267
|
+
new Promise((resolve) => {
|
|
268
|
+
resolveNext = resolve;
|
|
269
|
+
})
|
|
270
|
+
);
|
|
271
|
+
let pending: Promise<void>;
|
|
272
|
+
act(() => {
|
|
273
|
+
pending = result.current.refetch();
|
|
274
|
+
});
|
|
275
|
+
expect(result.current.isLoading).toBe(true);
|
|
276
|
+
expect(
|
|
277
|
+
result.current.data?.status === 'success' &&
|
|
278
|
+
result.current.data.table.rows
|
|
279
|
+
).toEqual([[1]]);
|
|
280
|
+
|
|
281
|
+
await act(async () => {
|
|
282
|
+
resolveNext(wireSuccess(2));
|
|
283
|
+
await pending;
|
|
284
|
+
});
|
|
285
|
+
expect(result.current.isLoading).toBe(false);
|
|
286
|
+
expect(
|
|
287
|
+
result.current.data?.status === 'success' &&
|
|
288
|
+
result.current.data.table.rows
|
|
289
|
+
).toEqual([[2]]);
|
|
290
|
+
});
|
|
291
|
+
|
|
292
|
+
it('does not publish an in-flight result after the query goes idle', async () => {
|
|
293
|
+
let resolveQuery!: (value: unknown) => void;
|
|
294
|
+
executeQuery.mockReturnValueOnce(
|
|
295
|
+
new Promise((resolve) => {
|
|
296
|
+
resolveQuery = resolve;
|
|
297
|
+
})
|
|
298
|
+
);
|
|
299
|
+
const { result, rerender } = renderHook(
|
|
300
|
+
({ query }) => useSemanticModelQuery({ connection: 'model', query }),
|
|
301
|
+
{ initialProps: { query: 'EVALUATE ROW()' } }
|
|
302
|
+
);
|
|
303
|
+
rerender({ query: '' });
|
|
304
|
+
await act(async () => {
|
|
305
|
+
resolveQuery(wireSuccess(9));
|
|
306
|
+
await new Promise((resolve) => setTimeout(resolve, 20));
|
|
307
|
+
});
|
|
308
|
+
expect(result.current.data).toBeUndefined();
|
|
309
|
+
expect(result.current.error).toBeUndefined();
|
|
310
|
+
expect(result.current.isLoading).toBe(false);
|
|
311
|
+
});
|
|
312
|
+
|
|
313
|
+
it('starts loading again when revisiting a previously completed query', async () => {
|
|
314
|
+
executeQuery.mockResolvedValueOnce(wireSuccess(1));
|
|
315
|
+
const { result, rerender } = renderHook(
|
|
316
|
+
({ query }) => useSemanticModelQuery({ connection: 'model', query }),
|
|
317
|
+
{ initialProps: { query: 'EVALUATE ROW(1)' } }
|
|
318
|
+
);
|
|
319
|
+
await waitFor(() => expect(result.current.isLoading).toBe(false));
|
|
320
|
+
|
|
321
|
+
executeQuery.mockReturnValueOnce(new Promise(() => {}));
|
|
322
|
+
rerender({ query: 'EVALUATE ROW(2)' });
|
|
323
|
+
expect(result.current.isLoading).toBe(true);
|
|
324
|
+
|
|
325
|
+
let resolveRevisited!: (value: unknown) => void;
|
|
326
|
+
executeQuery.mockReturnValueOnce(
|
|
327
|
+
new Promise((resolve) => {
|
|
328
|
+
resolveRevisited = resolve;
|
|
329
|
+
})
|
|
330
|
+
);
|
|
331
|
+
rerender({ query: 'EVALUATE ROW(1)' });
|
|
332
|
+
expect(result.current.isLoading).toBe(true);
|
|
333
|
+
await act(async () => {
|
|
334
|
+
resolveRevisited(wireSuccess(3));
|
|
335
|
+
});
|
|
336
|
+
expect(result.current.isLoading).toBe(false);
|
|
337
|
+
expect(
|
|
338
|
+
result.current.data?.status === 'success' &&
|
|
339
|
+
result.current.data.table.rows
|
|
340
|
+
).toEqual([[3]]);
|
|
341
|
+
});
|
|
342
|
+
});
|
|
@@ -0,0 +1,229 @@
|
|
|
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 type {
|
|
9
|
+
ExecuteQueryInput,
|
|
10
|
+
FabricSemanticModelTabularResponse,
|
|
11
|
+
SemanticModelQueryResult,
|
|
12
|
+
} from '@microsoft/rayfin-connector-fabric-semanticmodel';
|
|
13
|
+
import { toQueryResult } from '@microsoft/rayfin-connector-fabric-semanticmodel';
|
|
14
|
+
import { useCallback, useEffect, useRef, useState } from 'react';
|
|
15
|
+
|
|
16
|
+
import { getRayfinClient } from '@/lib/rayfin-client';
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* One entry of the typed `client.connectors` proxy, narrowed to the operation
|
|
20
|
+
* this hook uses.
|
|
21
|
+
*
|
|
22
|
+
* The schema keys `client.connectors` by the exact connector names declared in
|
|
23
|
+
* `rayfin/rayfin.yml`, so it cannot be indexed by a `string` variable. This is
|
|
24
|
+
* the one place that widening happens, and the missing-connector branch below
|
|
25
|
+
* is what makes it safe.
|
|
26
|
+
*/
|
|
27
|
+
type ExecuteQueryClient = {
|
|
28
|
+
executeQuery(
|
|
29
|
+
input: ExecuteQueryInput
|
|
30
|
+
): Promise<FabricSemanticModelTabularResponse>;
|
|
31
|
+
};
|
|
32
|
+
|
|
33
|
+
interface UseSemanticModelQueryOptions {
|
|
34
|
+
/** Connector name from `rayfin/rayfin.yml` (e.g. `salesModel`). */
|
|
35
|
+
connection: string;
|
|
36
|
+
/** DAX query string. */
|
|
37
|
+
query: string;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
interface UseSemanticModelQueryResult {
|
|
41
|
+
data: SemanticModelQueryResult | undefined;
|
|
42
|
+
isLoading: boolean;
|
|
43
|
+
error: Error | undefined;
|
|
44
|
+
refetch: () => Promise<void>;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
interface QueryState {
|
|
48
|
+
connection: string;
|
|
49
|
+
query: string;
|
|
50
|
+
data: SemanticModelQueryResult | undefined;
|
|
51
|
+
isLoading: boolean;
|
|
52
|
+
error: Error | undefined;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** Message for a connector this app has not registered. Names the fix, not the symptom. */
|
|
56
|
+
function notRegistered(connection: string): string {
|
|
57
|
+
return (
|
|
58
|
+
`No connector named "${connection}". Register it in connectorConfigs and ` +
|
|
59
|
+
`connectorRuntimes (packages/frontend/src/lib/connectors.ts), and check the name matches ` +
|
|
60
|
+
`rayfin/rayfin.yml.`
|
|
61
|
+
);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Runs one DAX query through the semantic model connector and normalizes the
|
|
66
|
+
* response.
|
|
67
|
+
*
|
|
68
|
+
* Throws for wiring, transport and auth failures. A query that reached Power BI
|
|
69
|
+
* and failed there comes back as a result whose `status` is `error` instead.
|
|
70
|
+
*/
|
|
71
|
+
async function executeSemanticModelQuery(
|
|
72
|
+
connection: string,
|
|
73
|
+
query: string
|
|
74
|
+
): Promise<SemanticModelQueryResult> {
|
|
75
|
+
// Async in this template: it resolves the deployed `rayfin.config.json` first.
|
|
76
|
+
const client = await getRayfinClient();
|
|
77
|
+
const connectors = (client as { connectors?: unknown }).connectors;
|
|
78
|
+
|
|
79
|
+
if (!connectors) {
|
|
80
|
+
throw new Error(
|
|
81
|
+
`This app's Rayfin client has no "connectors". ` +
|
|
82
|
+
`packages/frontend/src/lib/rayfin-client.ts ` +
|
|
83
|
+
`builds a plain RayfinClient; querying a semantic model needs ` +
|
|
84
|
+
`ConnectorsRayfinClient constructed with connectorConfigs and ` +
|
|
85
|
+
`connectorRuntimes from packages/frontend/src/lib/connectors.ts. ` +
|
|
86
|
+
`See step 1 of the ` +
|
|
87
|
+
`analytics skill.`
|
|
88
|
+
);
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
let connector: ExecuteQueryClient | undefined;
|
|
92
|
+
try {
|
|
93
|
+
connector = (connectors as Record<string, ExecuteQueryClient | undefined>)[
|
|
94
|
+
connection
|
|
95
|
+
];
|
|
96
|
+
} catch (err) {
|
|
97
|
+
// The connectors proxy throws `UNKNOWN_CONNECTOR` for an unconfigured name
|
|
98
|
+
// rather than returning undefined, so the miss arrives here.
|
|
99
|
+
throw new Error(notRegistered(connection), { cause: err });
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
// Also checked: test doubles and any future pass-through may return undefined.
|
|
103
|
+
if (!connector) throw new Error(notRegistered(connection));
|
|
104
|
+
|
|
105
|
+
// Idempotent, and needed on both paths: a registered runtime normalizes
|
|
106
|
+
// already, but a connector missing from `connectorRuntimes` falls through to
|
|
107
|
+
// JSON pass-through and arrives in the wire shape.
|
|
108
|
+
return toQueryResult(await connector.executeQuery({ query }));
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* React hook that executes a DAX query against a Power BI semantic model
|
|
113
|
+
* through the `fabric-semanticmodel` connector.
|
|
114
|
+
*
|
|
115
|
+
* The connector name is declared in `rayfin/rayfin.yml` (managed by
|
|
116
|
+
* `rayfin connector add`). Its workspace and item are resolved server-side, so
|
|
117
|
+
* the app never sends them and they never reach the browser.
|
|
118
|
+
*
|
|
119
|
+
* @example
|
|
120
|
+
* const { data, isLoading } = useSemanticModelQuery({
|
|
121
|
+
* connection: 'salesModel',
|
|
122
|
+
* query: 'EVALUATE SUMMARIZE(Sales, Products[Name], "Total", SUM(Sales[Amount]))',
|
|
123
|
+
* });
|
|
124
|
+
*
|
|
125
|
+
* if (data?.status === 'success') {
|
|
126
|
+
* const table = data.table; // table.columns, table.rows
|
|
127
|
+
* }
|
|
128
|
+
*
|
|
129
|
+
* @example
|
|
130
|
+
* // Two disjoint error channels - check both, in either order.
|
|
131
|
+
* // `error`: what the connector threw (wiring, transport, auth). `data` is cleared.
|
|
132
|
+
* // `data.status === 'error'`: what Power BI returned, categorised by the
|
|
133
|
+
* // connector as 'query' | 'overflow' | 'api' | 'network'. `error` stays undefined.
|
|
134
|
+
* // A component that reads only one renders nothing for half its failures.
|
|
135
|
+
* if (error) console.error(error.message);
|
|
136
|
+
* else if (data?.status === 'error')
|
|
137
|
+
* console.error(data.error.category, data.error.message);
|
|
138
|
+
*
|
|
139
|
+
* @remarks
|
|
140
|
+
* An empty `connection` or `query` puts the hook idle and clears any previous
|
|
141
|
+
* result. So a `connection` wired to the wrong variable shows up as a component
|
|
142
|
+
* that never loads rather than as an error - check that first when nothing
|
|
143
|
+
* renders.
|
|
144
|
+
*/
|
|
145
|
+
export function useSemanticModelQuery(
|
|
146
|
+
options: UseSemanticModelQueryOptions
|
|
147
|
+
): UseSemanticModelQueryResult {
|
|
148
|
+
const { connection, query } = options;
|
|
149
|
+
const canExecute = Boolean(connection && query);
|
|
150
|
+
const [state, setState] = useState<QueryState>(() => ({
|
|
151
|
+
connection,
|
|
152
|
+
query,
|
|
153
|
+
data: undefined,
|
|
154
|
+
isLoading: canExecute,
|
|
155
|
+
error: undefined,
|
|
156
|
+
}));
|
|
157
|
+
|
|
158
|
+
// Input changes reset request UI during render, not from the fetch effect.
|
|
159
|
+
if (state.connection !== connection || state.query !== query) {
|
|
160
|
+
setState({
|
|
161
|
+
connection,
|
|
162
|
+
query,
|
|
163
|
+
data: canExecute ? state.data : undefined,
|
|
164
|
+
isLoading: canExecute,
|
|
165
|
+
error: undefined,
|
|
166
|
+
});
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
// Monotonic request id: only the newest run may publish, so a slow first query
|
|
170
|
+
// cannot land after a fast second one and overwrite fresher rows.
|
|
171
|
+
const latestRequest = useRef(0);
|
|
172
|
+
|
|
173
|
+
const execute = useCallback(async () => {
|
|
174
|
+
const requestId = ++latestRequest.current;
|
|
175
|
+
if (!canExecute) return;
|
|
176
|
+
|
|
177
|
+
let result: SemanticModelQueryResult | undefined;
|
|
178
|
+
let thrown: Error | undefined;
|
|
179
|
+
try {
|
|
180
|
+
result = await executeSemanticModelQuery(connection, query);
|
|
181
|
+
} catch (err) {
|
|
182
|
+
// As-is, not re-wrapped: a transport failure carries its status and
|
|
183
|
+
// service code as own properties, and a fresh Error would drop them.
|
|
184
|
+
thrown =
|
|
185
|
+
err instanceof Error ? err : new Error(String(err), { cause: err });
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
// Superseded by a newer run.
|
|
189
|
+
if (requestId !== latestRequest.current) return;
|
|
190
|
+
|
|
191
|
+
setState((current) => {
|
|
192
|
+
if (current.connection !== connection || current.query !== query) {
|
|
193
|
+
return current;
|
|
194
|
+
}
|
|
195
|
+
return {
|
|
196
|
+
connection,
|
|
197
|
+
query,
|
|
198
|
+
data: thrown ? undefined : (result ?? current.data),
|
|
199
|
+
isLoading: false,
|
|
200
|
+
error: thrown,
|
|
201
|
+
};
|
|
202
|
+
});
|
|
203
|
+
}, [connection, query, canExecute]);
|
|
204
|
+
|
|
205
|
+
const refetch = useCallback(async () => {
|
|
206
|
+
setState((current) => ({
|
|
207
|
+
...current,
|
|
208
|
+
data: canExecute ? current.data : undefined,
|
|
209
|
+
isLoading: canExecute,
|
|
210
|
+
error: undefined,
|
|
211
|
+
}));
|
|
212
|
+
await execute();
|
|
213
|
+
}, [execute, canExecute]);
|
|
214
|
+
|
|
215
|
+
useEffect(() => {
|
|
216
|
+
void execute();
|
|
217
|
+
return () => {
|
|
218
|
+
// The connector has no AbortSignal; invalidate completions on cleanup.
|
|
219
|
+
latestRequest.current += 1;
|
|
220
|
+
};
|
|
221
|
+
}, [execute]);
|
|
222
|
+
|
|
223
|
+
return {
|
|
224
|
+
data: state.data,
|
|
225
|
+
isLoading: state.isLoading,
|
|
226
|
+
error: state.error,
|
|
227
|
+
refetch,
|
|
228
|
+
};
|
|
229
|
+
}
|
|
@@ -0,0 +1,94 @@
|
|
|
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 type {
|
|
9
|
+
ConnectorConfig,
|
|
10
|
+
ConnectorsRuntime,
|
|
11
|
+
} from '@microsoft/rayfin-connectors';
|
|
12
|
+
import type { FabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Connectors this app can talk to, keyed by the connector name declared in
|
|
16
|
+
* `rayfin/rayfin.yml` under `connectors[].name`.
|
|
17
|
+
*
|
|
18
|
+
* The index signature keeps every name usable without editing this file each
|
|
19
|
+
* time you run `rayfin connector add`. Narrow it to the names you actually use
|
|
20
|
+
* if you want the compiler to catch a typo in a connection alias:
|
|
21
|
+
*
|
|
22
|
+
* @example
|
|
23
|
+
* export type AppConnectorsSchema = {
|
|
24
|
+
* salesModel: FabricSemanticModel<'executeQuery'>;
|
|
25
|
+
* };
|
|
26
|
+
*/
|
|
27
|
+
export type AppConnectorsSchema = Record<
|
|
28
|
+
string,
|
|
29
|
+
FabricSemanticModel<'executeQuery'>
|
|
30
|
+
>;
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Routing config for each connector, keyed by the same name again.
|
|
34
|
+
*
|
|
35
|
+
* `rayfin connector add` writes a `connectorConfig` constant into
|
|
36
|
+
* `rayfin/connectors/<name>/schema.ts`. Re-export that constant here rather
|
|
37
|
+
* than hand-writing the object, so this file cannot drift from `rayfin.yml`.
|
|
38
|
+
*
|
|
39
|
+
* @example
|
|
40
|
+
* import { connectorConfig as salesModel } from '../../../../rayfin/connectors/salesModel/schema';
|
|
41
|
+
*
|
|
42
|
+
* export const connectorConfigs: Record<string, ConnectorConfig> = { salesModel };
|
|
43
|
+
*/
|
|
44
|
+
export const connectorConfigs: Record<string, ConnectorConfig> = {};
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Per-connector runtime hooks, keyed by the same name again.
|
|
48
|
+
*
|
|
49
|
+
* `fabric-semanticmodel` returns an Apache Arrow stream and chooses its
|
|
50
|
+
* transport from where the app is running — embedded in the Fabric portal, or
|
|
51
|
+
* standalone — and both of those live in the runtime. A connector left out of
|
|
52
|
+
* this map falls back to the plain JSON pass-through and will not decode.
|
|
53
|
+
* Register one runtime per semantic model; the connectors layer already keys
|
|
54
|
+
* instances by name.
|
|
55
|
+
*
|
|
56
|
+
* @example
|
|
57
|
+
* import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
|
|
58
|
+
*
|
|
59
|
+
* export const connectorRuntimes: ConnectorsRuntime = {
|
|
60
|
+
* salesModel: fabricSemanticModel({}),
|
|
61
|
+
* };
|
|
62
|
+
*
|
|
63
|
+
* @remarks
|
|
64
|
+
* Do not pass a `target`. The workspace and item ids come from `rayfin.yml` and
|
|
65
|
+
* are injected by the host, so they never ship to the browser. Deriving one from
|
|
66
|
+
* a `VITE_*` variable throws at module load, because a per-model URL is not
|
|
67
|
+
* among the variables `rayfin env` emits.
|
|
68
|
+
*/
|
|
69
|
+
export const connectorRuntimes: ConnectorsRuntime = {};
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Fails when a connector is configured without a matching runtime.
|
|
73
|
+
*
|
|
74
|
+
* A config with no runtime still sends the call, falls back to JSON
|
|
75
|
+
* pass-through, and returns an Arrow stream nothing decodes — unreadable rows,
|
|
76
|
+
* far from the missing line that caused them. Call this before constructing the
|
|
77
|
+
* client to turn that into a startup error naming the connector.
|
|
78
|
+
*
|
|
79
|
+
* A runtime with no config is fine: it can be registered ahead of the
|
|
80
|
+
* `connector add` that declares it.
|
|
81
|
+
*/
|
|
82
|
+
export function assertConnectorRuntimesRegistered(): void {
|
|
83
|
+
const missing = Object.keys(connectorConfigs).filter(
|
|
84
|
+
(name) => !(name in connectorRuntimes)
|
|
85
|
+
);
|
|
86
|
+
|
|
87
|
+
if (missing.length > 0) {
|
|
88
|
+
throw new Error(
|
|
89
|
+
`Connector(s) ${missing.map((n) => `"${n}"`).join(', ')} are in connectorConfigs but have no runtime in connectorRuntimes ` +
|
|
90
|
+
`(packages/frontend/src/lib/connectors.ts). Without a runtime the response is not decoded and rows arrive unreadable. ` +
|
|
91
|
+
`Add: ${missing.map((n) => `${n}: fabricSemanticModel({})`).join(', ')}.`
|
|
92
|
+
);
|
|
93
|
+
}
|
|
94
|
+
}
|