[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M699XK5JQ3GWA8N62FEWTWHA":3,"skill-same:01M699XK5JQ3GWA8N62FEWTWHA":84},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":31,"publishedAt":36,"linkOnly":37,"markdownContent":38,"markdownBody":39,"frontMatter":40,"refName":41,"commitSha":42,"skillDirectory":43,"forksCount":44,"repositoryHtmlUrl":45,"repositoryHomepageUrl":6,"ownerHtmlUrl":46,"ownerBlogUrl":47,"ownerDescription":48,"updatedAt":49,"install":50,"resources":63},"01M699XK5JQ3GWA8N62FEWTWHA","analytics",null,"Use when the app reads an existing Power BI semantic model — a dashboard, report, KPI, or any view over data the app does not own. Turns on the Fabric data client and the semantic-model query hook, then covers the whole workflow: pick a model, discover its schema, write and test DAX, and render it. A chart over data the app already has needs the visuals skill instead, not this one. Triggers: semantic model, dataset, Power BI, DAX, measure, \"our sales data\", \"from the model\", \"the existing report\".","microsoft\u002Frayfin","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M699VK9NEV8GH0Y5JKT1G8XG",662,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Fanalytics\u002FSKILL.md",[18,23,26],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000013","分析与可视化","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000033","数据分析师","PROFESSION","适用职业",[5,32,33,34,35],"workflow","dashboard","test","dax","2026-11-10 10:12:30",false,"---\nname: analytics\ndescription: >\n  Use when the app reads an existing Power BI semantic model — a dashboard,\n  report, KPI, or any view over data the app does not own. Turns on the Fabric\n  data client and the semantic-model query hook, then covers the whole workflow:\n  pick a model, discover its schema, write and test DAX, and render it. A chart\n  over data the app already has needs the visuals skill instead, not this one.\n  Triggers: semantic model, dataset, Power BI, DAX, measure, \"our sales data\",\n  \"from the model\", \"the existing report\".\n---\n\n# Analytics — reading a semantic model\n\n## Turn it on first\n\n```sh\nnpm run pack:add -- connectors\nnpm run pack:add -- analytics\n```\n\nThe connectors pack installs the composable client in\n`packages\u002Ffrontend\u002Fsrc\u002Flib\u002Frayfin-client.ts`.\nThe analytics pack installs the semantic-model connector packages and the\n`useSemanticModelQuery` hook.\nIt also turns the `connectors` service on in `rayfin\u002Frayfin.yml`, which unlocks\nthe `rayfin connector` commands.\nRun both before writing any code.\n\nTo chart what the queries return, add the visuals pack as well:\n\n```sh\nnpm run pack:add -- visuals\n```\n\nThat brings `VegaVisual`, `DataGrid`, `toDataTable`, and `validate:visual`.\nAnalytics does not pull it in, because reading a model and drawing one are\nseparate jobs — an app that shows a handful of figures needs no chart library.\nMost dashboards want both.\n\nRe-applying either is safe: an existing file is preserved, not overwritten, so a\n`connectors.ts` you have registered models in survives.\n\n> If `npm run dev` re-optimizes dependencies on first load, add the visual\n> packages to `optimizeDeps.include` in `packages\u002Ffrontend\u002Fvite.config.ts`. They are left out of\n> the base because a bare app does not install them.\n\nRead [`schema-discovery`](..\u002Fschema-discovery\u002FSKILL.md) next — you cannot write a\ncorrect query against a model you have not looked at. After that, pull in what\nthe job actually needs rather than all of it up front. Each row is a sibling\nskill:\n\n| Read | When |\n|---|---|\n| [`dax-authoring`](..\u002Fdax-authoring\u002FSKILL.md) | You are writing a measure or a non-trivial DAX expression |\n| [`query-design`](..\u002Fquery-design\u002FSKILL.md) | The dashboard needs more than one grain, or you are shaping a query for several visuals |\n| [`visuals`](..\u002Fvisuals\u002FSKILL.md) | You are building any chart, or configuring `DataGrid` |\n| [`app-design`](..\u002Fapp-design\u002FSKILL.md) | You are deciding layout and theming |\n| [`fabric-sdk`](..\u002Ffabric-sdk\u002FSKILL.md) | Reference material for the CLI and the runtime client |\n\nEach of those has a `references\u002F` folder that is deliberately not required\nreading; open a reference when the SKILL.md points you at it for the specific\nthing you are doing.\n\n## Recommended workflow\n\nUse these steps unless the user asks for a different sequence.\n\nThe source contract and consuming UI have one hard ordering rule: run each real query before writing code that depends on its columns or values.\nThat does not require leaving the starter\u002Fwelcome view untouched during all schema discovery.\n\n- **Foundation:** Apply the packs, identify and attach the intended model, and preserve the authentication gate.\n- **Runnable shell:** Establish the app's layout, final content regions, and honest loading states while independent schema and query discovery continues.\n- **Data integration:** Validate each query through `npx rayfin connector invoke`, then bind the exact returned shape into the corresponding component.\n- **Completion:** Add interactions and polish, then run the final validation sequence once.\n\nDo not put invented business values into the shell.\nLoading content should reserve the real layout without pretending the source has returned.\n\n### 1. Ask the user for a semantic model\n\n**Local `.pbix` files are not supported.** This app connects to semantic models published to the Power BI Service (cloud), not to local `.pbix` files on disk. If the user provides a local file path (e.g., `C:\\...\\Model.pbix`), **do not** attempt to open, upload, or search for it. Instead:\n1. Inform the user that local `.pbix` files are not supported — only models published to the Power BI Service can be used.\n2. Ask the user whether they would like to:\n   - **Search the Power BI Service** for a semantic model by name — run `npx rayfin connector search` on their behalf, or\n   - **Provide a specific online model** directly (workspace ID + dataset ID, or a Power BI \u002F Fabric URL).\n\nOnce the user confirms a published semantic model, read the [schema-discovery](..\u002Fschema-discovery\u002FSKILL.md) skill to progressively discover schema metadata as needed — do not fetch the full schema upfront.\n\nOnce the model is identified, attach it as a connector. Choose the path that matches the input the user gave you:\n\n```bash\n# Path A — user wants you to search by name.\n#   --all-workspaces is required here: this step runs before the app is\n#   deployed, so there is no deployment to infer a workspace scope from and\n#   the command would otherwise exit with \"workspace scope is required\".\n#   --json is recommended so you can reason over displayName, workspaceName\n#   and ids without parsing tables. If more than one could match, confirm the\n#   right one with the user (e.g. two same-named models in different workspaces).\nnpx rayfin connector search \"\u003Cname>\" --type fabric-semanticmodel --all-workspaces --json\n\n# Path B \u002F C — user gave a URL or explicit IDs. Take workspaceId + itemId from\n# whichever they provided and declare the connector:\nnpx rayfin connector add --type fabric-semanticmodel \\\n  --workspace-id \u003CworkspaceId> --item-id \u003CitemId> --name \u003Calias>\n```\n\n`connector add` writes the entry into `rayfin\u002Frayfin.yml`, scaffolds\n`rayfin\u002Fconnectors\u002F\u003Calias>\u002F`, and prints version-pinned package specifications.\nInstall those exact versions into the frontend workspace from the app root:\n\n```sh\nnpm install -w @rayfin-app\u002Ffrontend \u003Cprinted-packages-and-versions>\n```\n\nDo not install them at the workspace root or create a nested lockfile.\n\n`connector add` also regenerates\n`packages\u002Ffrontend\u002Fsrc\u002Flib\u002Fconnectors.ts` with the connector config, schema, and\nruntime.\nDo not hand-write those maps or replace the client installed by the connectors\npack.\nThat client composes connectors through `ExtendableRayfinClient`, and the pack\nselects the functions-aware variant automatically when functions are present.\nIf the CLI reports that the wiring file is app-owned, apply the exact manual\nsnippet it prints instead of inventing a second client recipe.\n\n### 2. Prove the connector returns data before wiring source values\n\n`fabric-semanticmodel` is the one connector type whose `invoke` runs under your\nown identity, so it works **without** a deploy. That makes this check nearly\nfree, and it is the difference between finding a dead connector now or after\nbuilding a dashboard on top of it:\n\n```bash\nnpx rayfin connector invoke \u003Calias> executeQuery --file .\u002Finspection\u002Fsmoke.query.json\n```\n\nWhere `smoke.query.json` is the operation's input envelope, not the bare query:\n\n```json\n{ \"query\": \"EVALUATE TOPN(1, Sales)\" }\n```\n\nDo not wire source-backed values if this fails.\nA connector, permission, or enablement failure must remain an error rather than an endless loading state.\nA standalone-capable layout shell may already exist, but no amount of presentation work fixes the source contract.\n\n**Pass DAX in a `--file` payload, not with `--input`.** A DAX query is full of\nquotes and brackets, and an inline `--input` string goes through a shell that\ntreats them as syntax — `EVALUATE ROW(\"it's\", 1)` breaks on the apostrophe\nalone. `--file` is `JSON.parse`d, so it must be JSON: a raw `.dax` file fails\nbefore the connector is reached. The path resolves against the project root and\nmust stay inside it.\n\n### 3. Write and test DAX queries\n\nFollow the [dax-authoring](..\u002Fdax-authoring\u002FSKILL.md) skill to write and test DAX queries. The skill covers DAX syntax rules, query patterns, time intelligence, and an iterative test workflow. Use the [schema-discovery](..\u002Fschema-discovery\u002FSKILL.md) skill to progressively discover model metadata as needed.\n\nUse `npx rayfin connector invoke \u003Calias> executeQuery --file \u003Cquery>.query.json` to test queries. This runs the query through the same connector the app uses at runtime, so the results (column names, data types, row structure) are identical to what the app will produce.\n\nIterate on queries until they return the expected columns and data shape.\n\nDelegate query exploration only when it is a substantial independent body of work with a clear result contract.\nFor a small dashboard or one tightly coupled query flow, keep discovery and component integration together.\n\nOnce queries are validated, **promote them to the app** following the [Query and spec organization](#query-and-spec-organization) conventions above.\n\n**Does this app draw a chart or a grid?** The answer decides what to build, and\nit is worth settling before writing files rather than after. `ColumnMetadataMap`,\nVega-Lite specs and `vegaLiteSpec` all come from the `visuals` pack: in an app\nthat never applied it those imports do not resolve and `typecheck` fails.\n\n*If it charts* — the usual case, and the rest of this skill assumes it:\n\n1. Save each query as a `.dax` file in `packages\u002Ffrontend\u002Fsrc\u002Fqueries\u002F` following the naming and grouping conventions.\n2. **Capture column metadata** — copy the exact column names from the query output as dictionary keys in a `columnMetadata: ColumnMetadataMap` constant. See the conventions above for the full format and rules.\n3. Create the corresponding `.json` Vega-Lite spec — refer to [visuals](..\u002Fvisuals\u002FSKILL.md). Use the cleaned `name` values from the metadata for Vega-Lite field encodings (they are already free of characters that require escaping). Use `displayName` values for axis titles, legend labels, and tooltip headers. Use `format` values for axis\u002Ftooltip formatting.\n4. Create the barrel `.ts` file with a **factory function** that returns `{ connection, query, columnMetadata, vegaLiteSpec }`.\n\n*If it does not* — figures in custom components, a summary, an export:\n\n1. Save each query as a `.dax` file exactly as above.\n2. Create the barrel `.ts` file with a factory returning `{ connection, query }`.\n   Nothing else: there is no spec and no metadata constant.\n\nRead the result off `data.table` — `columns` and `rows` — and render it however\nthe app renders anything else.\n\n### 4. UX Design for the app\n\nPrinciples for overall aesthetics, theming, layout, and accessibility requirements are outlined in [app-design](..\u002Fapp-design\u002FSKILL.md) skill - refer to it before creating or modifying any UI component, layout, page, or style.\n\n### 5. Build components with data (app code phase)\n\nUse the `useSemanticModelQuery` hook from `packages\u002Ffrontend\u002Fsrc\u002Fhooks\u002Fuse-semantic-model-query.ts`. Components call the factory functions from `packages\u002Ffrontend\u002Fsrc\u002Fqueries\u002F` and destructure what those factories return.\n\n**Without the `visuals` pack**, that is `{ connection, query }`, and `data.table`\nis the whole rendering API:\n\n```tsx\nconst { data } = useSemanticModelQuery(revenueByRegion());\nif (data?.status === \"success\") {\n  const [row] = data.table.rows;          \u002F\u002F columns and rows, nothing else\n  return \u003Cp>Revenue this quarter: {String(row?.[0])}\u003C\u002Fp>;\n}\n```\n\nEverything below is the charting path and needs `visuals` applied.\n\nFactories there return `{ connection, query, columnMetadata, vegaLiteSpec }`.\n\nUse `toDataTable()` from `packages\u002Ffrontend\u002Fsrc\u002Flib\u002Fto-data-table.ts` to convert the SDK's `QueryTable` (from `data.table`) into a `DataTable` by merging it with the `columnMetadata` from the factory function result. It ships with the `visuals` pack. This applies everywhere the data is consumed like rendering in `VegaVisual` or `DataGrid` (pass the `DataTable` via their `data` prop), displaying values in custom components, or any other usage.\n\n`VegaVisual` and `DataGrid` should consume factory-produced query, spec, and column metadata together so static specs remain checkable. Runtime-built specs are allowed but require browser validation. Partial static coverage exits normally; use the preview command only when coverage is zero. Follow the [visuals](..\u002Fvisuals\u002FSKILL.md) validation guidance before completion.\n\n`App.tsx` ships with the starter\u002Fwelcome view behind the\n`packages\u002Ffrontend\u002Fsrc\u002FEmptyStatePreview.tsx` module.\nReplace what the app renders for the real dashboard, but preserve that module and its existing named `EmptyStatePreview` export so the starter view can evolve independently.\nDo not couple application guidance to the view's artwork, animation, or other internal implementation.\n\n#### Example\n\nCharting path — this one needs `visuals`:\n\n```tsx\nimport { revenueByRegion } from \"@\u002Fqueries\u002Fsales\u002Frevenue-by-region\";\nimport { useSemanticModelQuery } from \"@\u002Fhooks\u002Fuse-semantic-model-query\";\nimport { toDataTable } from \"@\u002Flib\u002Fto-data-table\";\nimport { VegaVisual, useCssTheme } from \"@microsoft\u002Ffabric-visuals\";\nimport { DataGrid } from \"@microsoft\u002Ffabric-datagrid\";\n\nfunction RevenueByRegionChart() {\n  const theme = useCssTheme();\n  const { connection, query, columnMetadata, vegaLiteSpec } = revenueByRegion({\n    categories: [\"Category A\"],\n  });\n\n  const { data, isLoading, error } = useSemanticModelQuery({\n    connection,\n    query,\n  });\n\n  if (isLoading) return \u003CLoadingSpinner \u002F>;\n\n  \u002F\u002F Two disjoint channels, so both are checked. `error` is what the connector\n  \u002F\u002F threw — a wiring mistake, transport, or auth — and it clears `data`, so\n  \u002F\u002F skipping it renders nothing at all for those failures.\n  if (error) return \u003CErrorMessage message={error.message} \u002F>;\n\n  \u002F\u002F `data.status === \"error\"` is a failure Power BI reported inside a successful\n  \u002F\u002F response: invalid DAX, a permission refusal, an overflow.\n  if (data?.status === \"error\") {\n    return \u003CErrorMessage message={data.error.message} \u002F>;\n  }\n\n  if (data?.status !== \"success\") return null;\n\n  \u002F\u002F Convert the SDK's QueryTable into a DataTable enriched with column metadata.\n  \u002F\u002F toDataTable merges data.table with columnMetadata so that display names,\n  \u002F\u002F format strings, and cleaned field names are available to visuals.\n  const dataTable = toDataTable(data.table, columnMetadata);\n\n  \u002F\u002F Pass the DataTable to VegaVisual (chart) or DataGrid (table) via the data prop.\n  return (\n    \u003Cdiv>\n      \u003CVegaVisual spec={vegaLiteSpec} data={dataTable} theme={theme} \u002F>\n      \u003CDataGrid data={dataTable} theme={theme} \u002F>\n    \u003C\u002Fdiv>\n  );\n}\n```\n\n**Caching:** There is none. Every call to `useSemanticModelQuery` reaches Power BI.\nIf a screen re-queries more than you want, hold the result in state or memoize at\nthe call site — do not reintroduce a shared cache here without a per-principal key\nand a TTL, because a process-global one serves another user's rows after a sign-in\nchange and stale rows after a model refresh.\n\n**Error handling:** Two channels, and they are **disjoint** — a component that\nreads only one renders nothing for half its failures.\n\n- `error` carries what the connector **threw** — a wiring mistake, transport, or\n  auth. It is the original error, so its status and service code survive. `data`\n  is cleared when this is set.\n- `data.status === \"error\"` carries what Power BI **returned**, already\n  categorised by the connector as `\"query\"` (bad DAX), `\"overflow\"` (row\u002Fbyte cap\n  — the rows are truncated), `\"api\"` (dataset-level or auth), or `\"network\"`.\n  `error` stays `undefined` for these, so the category is always reachable.\n\nCheck both, in either order; they never both apply. Then check `data.status`\nbefore reading `data.table`.\n\nRetry only a known transient network or service-starting condition, and cap the attempts.\nAuthentication, permission, connector configuration, and query errors are permanent until something changes, so surface them immediately.\n\nFor the connector client, the response shapes, and advanced query options, refer to\nthe [fabric-sdk](..\u002Ffabric-sdk\u002FSKILL.md) skill.\n\n### 6. Final validation\n\nFollow the [app-validation](..\u002Fapp-validation\u002FSKILL.md) skill to\nrun targeted checks during implementation and the required final sequence once.\nRerun only a failed gate and later checks invalidated by its fix.\nComplete the browser check through the Fabric portal embed.\n\n---\n\n## Query and spec organization\n\nThis section describes an app that charts its results, so it assumes the\n`visuals` pack. Without it there are no specs: keep the `.dax` files and the\nfactory, and drop the `.json` and `vegaLiteSpec` from both.\n\nDAX queries and Vega-Lite specs live in `packages\u002Ffrontend\u002Fsrc\u002Fqueries\u002F`, grouped by dashboard page or domain. Each visualization gets files sharing the same kebab-case base name: one or more `.dax` files for queries, a `.json` file for the Vega-Lite spec, and a `.ts` factory file that imports them and exports `{ connection, query, columnMetadata, vegaLiteSpec }`. The factory function accepts optional parameters to select between query variants or modify the spec:\n\n```text\npackages\u002Ffrontend\u002Fsrc\u002Fqueries\u002F\n├── index.ts                            # Re-exports all query modules\n├── {page-or-domain}\u002F                   # Group by dashboard page or domain\n│   ├── {visualization-name}.dax        # DAX query (plain text)\n│   ├── {visualization-name}-{variant}.dax  # Additional query variants (optional)\n│   ├── {visualization-name}.json       # Vega-Lite spec (JSON)\n│   ├── {visualization-name}.ts         # Factory function: imports .dax + .json, exports { connection, query, vegaLiteSpec, columnMetadata }\n│   └── index.ts                        # Re-exports all visualizations in this group\n```\n\n### Example TS File\n\n**`revenue-by-region.ts`** — the factory function accepts use-case-specific parameters and uses them to modify the DAX query and\u002For Vega-Lite spec as appropriate:\n\n```ts\nimport type { VisualizationSpec } from \"@microsoft\u002Ffabric-visuals\";\nimport type { ColumnMetadataMap } from \"@\u002Flib\u002Fto-data-table\";\nimport baseQuery from \".\u002Frevenue-by-region.dax?raw\";\nimport spec from \".\u002Frevenue-by-region.json\";\n\nconst connection = \"{connection-alias}\";  \u002F\u002F from rayfin\u002Frayfin.yml\n\n\u002F** Column metadata keyed by original DAX column name. *\u002F\nconst columnMetadata: ColumnMetadataMap = {\n  \"Products[Region]\": { name: \"ProductsRegion\", displayName: \"Region\" },\n  \"[Total Revenue]\": { name: \"Total Revenue\", displayName: \"Total Revenue\", format: \"$#,0.00\" },\n};\n\ninterface RevenueByRegionParams {\n  \u002F** Filter to specific product categories (modifies the DAX query). *\u002F\n  categories?: string[];\n  \u002F** Only show regions with revenue above this threshold (modifies the Vega-Lite spec). *\u002F\n  minRevenue?: number;\n}\n\nexport function revenueByRegion(params?: RevenueByRegionParams) {\n  let query = baseQuery;\n  let vegaLiteSpec = spec; \u002F\u002F Should clone if modifying\n\n  if (params?.categories?.length) {\n    \u002F\u002F make changes to the DAX query to filter by the specified categories and update the query variable\n  }\n\n  if (params?.minRevenue != null) {\n    \u002F\u002F Clone spec and append a client-side filter transform to the Vega-Lite spec\n  }\n\n  return { connection, query, columnMetadata, vegaLiteSpec };\n}\n```\n\nThe parameters, their types, and how they modify the query or spec are **entirely use-case-specific**. Some visualizations may need no parameters at all; others may accept date ranges, top-N limits, grouping dimensions, or string search terms. The factory function is the single place that translates caller intent into DAX and\u002For Vega-Lite modifications.\n\n#### Query variants with multiple `.dax` files\n\nWhen a parameter changes the **structure** of the query (e.g. different GROUP BY columns, different aggregations), use separate `.dax` files for each variant. The factory function selects the right one:\n\n```text\nrevenue-trend\u002F\n  revenue-trend-yearly.dax\n  revenue-trend-quarterly.dax\n  revenue-trend-monthly.dax\n  revenue-trend.json\n  revenue-trend.ts\n```\n\n```ts\nimport yearlyQuery from \".\u002Frevenue-trend-yearly.dax?raw\";\nimport quarterlyQuery from \".\u002Frevenue-trend-quarterly.dax?raw\";\nimport monthlyQuery from \".\u002Frevenue-trend-monthly.dax?raw\";\n\ntype Granularity = \"yearly\" | \"quarterly\" | \"monthly\";\n\nconst queryByGranularity: Record\u003CGranularity, string> = {\n  yearly: yearlyQuery,\n  quarterly: quarterlyQuery,\n  monthly: monthlyQuery,\n};\n\nexport function revenueTrend(params?: { granularity?: Granularity }) {\n  const query = queryByGranularity[params?.granularity ?? \"monthly\"];\n  return { connection, query, columnMetadata, vegaLiteSpec };\n}\n```\n\n#### Column Metadata\n\nMetadata is part of the charting path — it exists to feed `toDataTable`, and both `ColumnMetadataMap` and `ColumnDef` come from the `visuals` pack. An app with no chart in it skips this section.\n\nCapture column metadata in the barrel `.ts` file as a `columnMetadata: ColumnMetadataMap` constant (import `ColumnMetadataMap` from `@\u002Flib\u002Fto-data-table`). The dictionary **must be keyed by the exact column name from the CLI query output** (the `name` field in `table.columns`). Do not guess or clean these keys — copy them verbatim from the query result. Each value is a `ColumnDef` (from `@microsoft\u002Ffabric-visuals-core`) containing:\n  - `name` — a cleaned-up identifier derived from the original column name by removing `.`, `[`, `]`, `\\`, `\"`, and `'` characters. E.g., `\"Products[Region]\"` → `\"ProductsRegion\"`, `\"[Total Revenue]\"` → `\"Total Revenue\"` — to be used when building visual specs.\n  - `displayName` — a human-readable label sourced from the semantic model schema (e.g., `\"Region\"`, `\"Total Revenue\"`). Used for axis titles, grid headers, and tooltips.\n  - `format` — a VBA\u002FECMA-376 format string for number\u002Fdate formatting (e.g., `#,##0.00`, `0.00%`, and `mm\u002Fdd\u002Fyyyy`). Omit for text type columns.\n\n**Example workflow:** Run `npx rayfin connector invoke myModel executeQuery --file .\u002Finspection\u002Fprobe.query.json`, observe the output columns are `[SalesPersonID]` and `[Name]`, then use those exact strings as metadata keys:\n\n```ts\nexport const columnMetadata: ColumnMetadataMap = {\n  \"[SalesPersonID]\": { name: \"SalesPersonID\", displayName: \"Sales Person ID\" },\n  \"[Name]\": { name: \"Name\", displayName: \"Name\" },\n};\n```\n\n#### Key rules\n\n- **All DAX lives in `.dax` files.** Never inline full DAX query strings in `.ts` factory files. If a parameter changes the query structure, create a separate `.dax` file for each variant and select the right one in the factory function. Small modifications — such as replacing filter value placeholders, wrapping the query with `CALCULATETABLE` to apply filters, or substituting a column reference — are acceptable in `.ts`, but the base query must always come from a `.dax` import.\n- **Name files after the visualization they drive.** Use kebab-case base names (e.g., `revenue-by-region.dax`, `revenue-by-region.json`, `revenue-by-region.ts`). Variant `.dax` files append a suffix (e.g., `revenue-trend-yearly.dax`, `revenue-trend-quarterly.dax`).\n- **Use `.dax` for queries.** Plain-text DAX files keep queries readable and diff-friendly. Import them with Vite's `?raw` suffix.\n- **Use `.json` for specs.** JSON files get free schema validation in editors and are importable as modules by default in Vite.\n- **Barrel `.ts` exports a factory function.** The function name is the camelCase version of the kebab-case file name (e.g., `revenueByRegion` for `revenue-by-region.ts`). It accepts optional parameters (typed per use case) and returns `{ connection, query, columnMetadata, vegaLiteSpec }` — or just `{ connection, query }` when the app draws no charts.\n- **Group by page\u002Fdomain.** Use subfolders when the dashboard has multiple pages or logical sections. For simple single-page dashboards, a flat structure under `packages\u002Ffrontend\u002Fsrc\u002Fqueries\u002F` is fine.\n- **Re-export via `index.ts`.** Each subfolder and the root `packages\u002Ffrontend\u002Fsrc\u002Fqueries\u002Findex.ts` should re-export all modules for clean imports.\n","# Analytics — reading a semantic model\n\n## Turn it on first\n\n```sh\nnpm run pack:add -- connectors\nnpm run pack:add -- analytics\n```\n\nThe connectors pack installs the composable client in\n`packages\u002Ffrontend\u002Fsrc\u002Flib\u002Frayfin-client.ts`.\nThe analytics pack installs the semantic-model connector packages and the\n`useSemanticModelQuery` hook.\nIt also turns the `connectors` service on in `rayfin\u002Frayfin.yml`, which unlocks\nthe `rayfin connector` commands.\nRun both before writing any code.\n\nTo chart what the queries return, add the visuals pack as well:\n\n```sh\nnpm run pack:add -- visuals\n```\n\nThat brings `VegaVisual`, `DataGrid`, `toDataTable`, and `validate:visual`.\nAnalytics does not pull it in, because reading a model and drawing one are\nseparate jobs — an app that shows a handful of figures needs no chart library.\nMost dashboards want both.\n\nRe-applying either is safe: an existing file is preserved, not overwritten, so a\n`connectors.ts` you have registered models in survives.\n\n> If `npm run dev` re-optimizes dependencies on first load, add the visual\n> packages to `optimizeDeps.include` in `packages\u002Ffrontend\u002Fvite.config.ts`. They are left out of\n> the base because a bare app does not install them.\n\nRead [`schema-discovery`](..\u002Fschema-discovery\u002FSKILL.md) next — you cannot write a\ncorrect query against a model you have not looked at. After that, pull in what\nthe job actually needs rather than all of it up front. Each row is a sibling\nskill:\n\n| Read | When |\n|---|---|\n| [`dax-authoring`](..\u002Fdax-authoring\u002FSKILL.md) | You are writing a measure or a non-trivial DAX expression |\n| [`query-design`](..\u002Fquery-design\u002FSKILL.md) | The dashboard needs more than one grain, or you are shaping a query for several visuals |\n| [`visuals`](..\u002Fvisuals\u002FSKILL.md) | You are building any chart, or configuring `DataGrid` |\n| [`app-design`](..\u002Fapp-design\u002FSKILL.md) | You are deciding layout and theming |\n| [`fabric-sdk`](..\u002Ffabric-sdk\u002FSKILL.md) | Reference material for the CLI and the runtime client |\n\nEach of those has a `references\u002F` folder that is deliberately not required\nreading; open a reference when the SKILL.md points you at it for the specific\nthing you are doing.\n\n## Recommended workflow\n\nUse these steps unless the user asks for a different sequence.\n\nThe source contract and consuming UI have one hard ordering rule: run each real query before writing code that depends on its columns or values.\nThat does not require leaving the starter\u002Fwelcome view untouched during all schema discovery.\n\n- **Foundation:** Apply the packs, identify and attach the intended model, and preserve the authentication gate.\n- **Runnable shell:** Establish the app's layout, final content regions, and honest loading states while independent schema and query discovery continues.\n- **Data integration:** Validate each query through `npx rayfin connector invoke`, then bind the exact returned shape into the corresponding component.\n- **Completion:** Add interactions and polish, then run the final validation sequence once.\n\nDo not put invented business values into the shell.\nLoading content should reserve the real layout without pretending the source has returned.\n\n### 1. Ask the user for a semantic model\n\n**Local `.pbix` files are not supported.** This app connects to semantic models published to the Power BI Service (cloud), not to local `.pbix` files on disk. If the user provides a local file path (e.g., `C:\\...\\Model.pbix`), **do not** attempt to open, upload, or search for it. Instead:\n1. Inform the user that local `.pbix` files are not supported — only models published to the Power BI Service can be used.\n2. Ask the user whether they would like to:\n   - **Search the Power BI Service** for a semantic model by name — run `npx rayfin connector search` on their behalf, or\n   - **Provide a specific online model** directly (workspace ID + dataset ID, or a Power BI \u002F Fabric URL).\n\nOnce the user confirms a published semantic model, read the [schema-discovery](..\u002Fschema-discovery\u002FSKILL.md) skill to progressively discover schema metadata as needed — do not fetch the full schema upfront.\n\nOnce the model is identified, attach it as a connector. Choose the path that matches the input the user gave you:\n\n```bash\n# Path A — user wants you to search by name.\n#   --all-workspaces is required here: this step runs before the app is\n#   deployed, so there is no deployment to infer a workspace scope from and\n#   the command would otherwise exit with \"workspace scope is required\".\n#   --json is recommended so you can reason over displayName, workspaceName\n#   and ids without parsing tables. If more than one could match, confirm the\n#   right one with the user (e.g. two same-named models in different workspaces).\nnpx rayfin connector search \"\u003Cname>\" --type fabric-semanticmodel --all-workspaces --json\n\n# Path B \u002F C — user gave a URL or explicit IDs. Take workspaceId + itemId from\n# whichever they provided and declare the connector:\nnpx rayfin connector add --type fabric-semanticmodel \\\n  --workspace-id \u003CworkspaceId> --item-id \u003CitemId> --name \u003Calias>\n```\n\n`connector add` writes the entry into `rayfin\u002Frayfin.yml`, scaffolds\n`rayfin\u002Fconnectors\u002F\u003Calias>\u002F`, and prints version-pinned package specifications.\nInstall those exact versions into the frontend workspace from the app root:\n\n```sh\nnpm install -w @rayfin-app\u002Ffrontend \u003Cprinted-packages-and-versions>\n```\n\nDo not install them at the workspace root or create a nested lockfile.\n\n`connector add` also regenerates\n`packages\u002Ffrontend\u002Fsrc\u002Flib\u002Fconnectors.ts` with the connector config, schema, and\nruntime.\nDo not hand-write those maps or replace the client installed by the connectors\npack.\nThat client composes connectors through `ExtendableRayfinClient`, and the pack\nselects the functions-aware variant automatically when functions are present.\nIf the CLI reports that the wiring file is app-owned, apply the exact manual\nsnippet it prints instead of inventing a second client recipe.\n\n### 2. Prove the connector returns data before wiring source values\n\n`fabric-semanticmodel` is the one connector type whose `invoke` runs under your\nown identity, so it works **without** a deploy. That makes this check nearly\nfree, and it is the difference between finding a dead connector now or after\nbuilding a dashboard on top of it:\n\n```bash\nnpx rayfin connector invoke \u003Calias> executeQuery --file .\u002Finspection\u002Fsmoke.query.json\n```\n\nWhere `smoke.query.json` is the operation's input envelope, not the bare query:\n\n```json\n{ \"query\": \"EVALUATE TOPN(1, Sales)\" }\n```\n\nDo not wire source-backed values if this fails.\nA connector, permission, or enablement failure must remain an error rather than an endless loading state.\nA standalone-capable layout shell may already exist, but no amount of presentation work fixes the source contract.\n\n**Pass DAX in a `--file` payload, not with `--input`.** A DAX query is full of\nquotes and brackets, and an inline `--input` string goes through a shell that\ntreats them as syntax — `EVALUATE ROW(\"it's\", 1)` breaks on the apostrophe\nalone. `--file` is `JSON.parse`d, so it must be JSON: a raw `.dax` file fails\nbefore the connector is reached. The path resolves against the project root and\nmust stay inside it.\n\n### 3. Write and test DAX queries\n\nFollow the [dax-authoring](..\u002Fdax-authoring\u002FSKILL.md) skill to write and test DAX queries. The skill covers DAX syntax rules, query patterns, time intelligence, and an iterative test workflow. Use the [schema-discovery](..\u002Fschema-discovery\u002FSKILL.md) skill to progressively discover model metadata as needed.\n\nUse `npx rayfin connector invoke \u003Calias> executeQuery --file \u003Cquery>.query.json` to test queries. This runs the query through the same connector the app uses at runtime, so the results (column names, data types, row structure) are identical to what the app will produce.\n\nIterate on queries until they return the expected columns and data shape.\n\nDelegate query exploration only when it is a substantial independent body of work with a clear result contract.\nFor a small dashboard or one tightly coupled query flow, keep discovery and component integration together.\n\nOnce queries are validated, **promote them to the app** following the [Query and spec organization](#query-and-spec-organization) conventions above.\n\n**Does this app draw a chart or a grid?** The answer decides what to build, and\nit is worth settling before writing files rather than after. `ColumnMetadataMap`,\nVega-Lite specs and `vegaLiteSpec` all come from the `visuals` pack: in an app\nthat never applied it those imports do not resolve and `typecheck` fails.\n\n*If it charts* — the usual case, and the rest of this skill assumes it:\n\n1. Save each query as a `.dax` file in `packages\u002Ffrontend\u002Fsrc\u002Fqueries\u002F` following the naming and grouping conventions.\n2. **Capture column metadata** — copy the exact column names from the query output as dictionary keys in a `columnMetadata: ColumnMetadataMap` constant. See the conventions above for the full format and rules.\n3. Create the corresponding `.json` Vega-Lite spec — refer to [visuals](..\u002Fvisuals\u002FSKILL.md). Use the cleaned `name` values from the metadata for Vega-Lite field encodings (they are already free of characters that require escaping). Use `displayName` values for axis titles, legend labels, and tooltip headers. Use `format` values for axis\u002Ftooltip formatting.\n4. Create the barrel `.ts` file with a **factory function** that returns `{ connection, query, columnMetadata, vegaLiteSpec }`.\n\n*If it does not* — figures in custom components, a summary, an export:\n\n1. Save each query as a `.dax` file exactly as above.\n2. Create the barrel `.ts` file with a factory returning `{ connection, query }`.\n   Nothing else: there is no spec and no metadata constant.\n\nRead the result off `data.table` — `columns` and `rows` — and render it however\nthe app renders anything else.\n\n### 4. UX Design for the app\n\nPrinciples for overall aesthetics, theming, layout, and accessibility requirements are outlined in [app-design](..\u002Fapp-design\u002FSKILL.md) skill - refer to it before creating or modifying any UI component, layout, page, or style.\n\n### 5. Build components with data (app code phase)\n\nUse the `useSemanticModelQuery` hook from `packages\u002Ffrontend\u002Fsrc\u002Fhooks\u002Fuse-semantic-model-query.ts`. Components call the factory functions from `packages\u002Ffrontend\u002Fsrc\u002Fqueries\u002F` and destructure what those factories return.\n\n**Without the `visuals` pack**, that is `{ connection, query }`, and `data.table`\nis the whole rendering API:\n\n```tsx\nconst { data } = useSemanticModelQuery(revenueByRegion());\nif (data?.status === \"success\") {\n  const [row] = data.table.rows;          \u002F\u002F columns and rows, nothing else\n  return \u003Cp>Revenue this quarter: {String(row?.[0])}\u003C\u002Fp>;\n}\n```\n\nEverything below is the charting path and needs `visuals` applied.\n\nFactories there return `{ connection, query, columnMetadata, vegaLiteSpec }`.\n\nUse `toDataTable()` from `packages\u002Ffrontend\u002Fsrc\u002Flib\u002Fto-data-table.ts` to convert the SDK's `QueryTable` (from `data.table`) into a `DataTable` by merging it with the `columnMetadata` from the factory function result. It ships with the `visuals` pack. This applies everywhere the data is consumed like rendering in `VegaVisual` or `DataGrid` (pass the `DataTable` via their `data` prop), displaying values in custom components, or any other usage.\n\n`VegaVisual` and `DataGrid` should consume factory-produced query, spec, and column metadata together so static specs remain checkable. Runtime-built specs are allowed but require browser validation. Partial static coverage exits normally; use the preview command only when coverage is zero. Follow the [visuals](..\u002Fvisuals\u002FSKILL.md) validation guidance before completion.\n\n`App.tsx` ships with the starter\u002Fwelcome view behind the\n`packages\u002Ffrontend\u002Fsrc\u002FEmptyStatePreview.tsx` module.\nReplace what the app renders for the real dashboard, but preserve that module and its existing named `EmptyStatePreview` export so the starter view can evolve independently.\nDo not couple application guidance to the view's artwork, animation, or other internal implementation.\n\n#### Example\n\nCharting path — this one needs `visuals`:\n\n```tsx\nimport { revenueByRegion } from \"@\u002Fqueries\u002Fsales\u002Frevenue-by-region\";\nimport { useSemanticModelQuery } from \"@\u002Fhooks\u002Fuse-semantic-model-query\";\nimport { toDataTable } from \"@\u002Flib\u002Fto-data-table\";\nimport { VegaVisual, useCssTheme } from \"@microsoft\u002Ffabric-visuals\";\nimport { DataGrid } from \"@microsoft\u002Ffabric-datagrid\";\n\nfunction RevenueByRegionChart() {\n  const theme = useCssTheme();\n  const { connection, query, columnMetadata, vegaLiteSpec } = revenueByRegion({\n    categories: [\"Category A\"],\n  });\n\n  const { data, isLoading, error } = useSemanticModelQuery({\n    connection,\n    query,\n  });\n\n  if (isLoading) return \u003CLoadingSpinner \u002F>;\n\n  \u002F\u002F Two disjoint channels, so both are checked. `error` is what the connector\n  \u002F\u002F threw — a wiring mistake, transport, or auth — and it clears `data`, so\n  \u002F\u002F skipping it renders nothing at all for those failures.\n  if (error) return \u003CErrorMessage message={error.message} \u002F>;\n\n  \u002F\u002F `data.status === \"error\"` is a failure Power BI reported inside a successful\n  \u002F\u002F response: invalid DAX, a permission refusal, an overflow.\n  if (data?.status === \"error\") {\n    return \u003CErrorMessage message={data.error.message} \u002F>;\n  }\n\n  if (data?.status !== \"success\") return null;\n\n  \u002F\u002F Convert the SDK's QueryTable into a DataTable enriched with column metadata.\n  \u002F\u002F toDataTable merges data.table with columnMetadata so that display names,\n  \u002F\u002F format strings, and cleaned field names are available to visuals.\n  const dataTable = toDataTable(data.table, columnMetadata);\n\n  \u002F\u002F Pass the DataTable to VegaVisual (chart) or DataGrid (table) via the data prop.\n  return (\n    \u003Cdiv>\n      \u003CVegaVisual spec={vegaLiteSpec} data={dataTable} theme={theme} \u002F>\n      \u003CDataGrid data={dataTable} theme={theme} \u002F>\n    \u003C\u002Fdiv>\n  );\n}\n```\n\n**Caching:** There is none. Every call to `useSemanticModelQuery` reaches Power BI.\nIf a screen re-queries more than you want, hold the result in state or memoize at\nthe call site — do not reintroduce a shared cache here without a per-principal key\nand a TTL, because a process-global one serves another user's rows after a sign-in\nchange and stale rows after a model refresh.\n\n**Error handling:** Two channels, and they are **disjoint** — a component that\nreads only one renders nothing for half its failures.\n\n- `error` carries what the connector **threw** — a wiring mistake, transport, or\n  auth. It is the original error, so its status and service code survive. `data`\n  is cleared when this is set.\n- `data.status === \"error\"` carries what Power BI **returned**, already\n  categorised by the connector as `\"query\"` (bad DAX), `\"overflow\"` (row\u002Fbyte cap\n  — the rows are truncated), `\"api\"` (dataset-level or auth), or `\"network\"`.\n  `error` stays `undefined` for these, so the category is always reachable.\n\nCheck both, in either order; they never both apply. Then check `data.status`\nbefore reading `data.table`.\n\nRetry only a known transient network or service-starting condition, and cap the attempts.\nAuthentication, permission, connector configuration, and query errors are permanent until something changes, so surface them immediately.\n\nFor the connector client, the response shapes, and advanced query options, refer to\nthe [fabric-sdk](..\u002Ffabric-sdk\u002FSKILL.md) skill.\n\n### 6. Final validation\n\nFollow the [app-validation](..\u002Fapp-validation\u002FSKILL.md) skill to\nrun targeted checks during implementation and the required final sequence once.\nRerun only a failed gate and later checks invalidated by its fix.\nComplete the browser check through the Fabric portal embed.\n\n---\n\n## Query and spec organization\n\nThis section describes an app that charts its results, so it assumes the\n`visuals` pack. Without it there are no specs: keep the `.dax` files and the\nfactory, and drop the `.json` and `vegaLiteSpec` from both.\n\nDAX queries and Vega-Lite specs live in `packages\u002Ffrontend\u002Fsrc\u002Fqueries\u002F`, grouped by dashboard page or domain. Each visualization gets files sharing the same kebab-case base name: one or more `.dax` files for queries, a `.json` file for the Vega-Lite spec, and a `.ts` factory file that imports them and exports `{ connection, query, columnMetadata, vegaLiteSpec }`. The factory function accepts optional parameters to select between query variants or modify the spec:\n\n```text\npackages\u002Ffrontend\u002Fsrc\u002Fqueries\u002F\n├── index.ts                            # Re-exports all query modules\n├── {page-or-domain}\u002F                   # Group by dashboard page or domain\n│   ├── {visualization-name}.dax        # DAX query (plain text)\n│   ├── {visualization-name}-{variant}.dax  # Additional query variants (optional)\n│   ├── {visualization-name}.json       # Vega-Lite spec (JSON)\n│   ├── {visualization-name}.ts         # Factory function: imports .dax + .json, exports { connection, query, vegaLiteSpec, columnMetadata }\n│   └── index.ts                        # Re-exports all visualizations in this group\n```\n\n### Example TS File\n\n**`revenue-by-region.ts`** — the factory function accepts use-case-specific parameters and uses them to modify the DAX query and\u002For Vega-Lite spec as appropriate:\n\n```ts\nimport type { VisualizationSpec } from \"@microsoft\u002Ffabric-visuals\";\nimport type { ColumnMetadataMap } from \"@\u002Flib\u002Fto-data-table\";\nimport baseQuery from \".\u002Frevenue-by-region.dax?raw\";\nimport spec from \".\u002Frevenue-by-region.json\";\n\nconst connection = \"{connection-alias}\";  \u002F\u002F from rayfin\u002Frayfin.yml\n\n\u002F** Column metadata keyed by original DAX column name. *\u002F\nconst columnMetadata: ColumnMetadataMap = {\n  \"Products[Region]\": { name: \"ProductsRegion\", displayName: \"Region\" },\n  \"[Total Revenue]\": { name: \"Total Revenue\", displayName: \"Total Revenue\", format: \"$#,0.00\" },\n};\n\ninterface RevenueByRegionParams {\n  \u002F** Filter to specific product categories (modifies the DAX query). *\u002F\n  categories?: string[];\n  \u002F** Only show regions with revenue above this threshold (modifies the Vega-Lite spec). *\u002F\n  minRevenue?: number;\n}\n\nexport function revenueByRegion(params?: RevenueByRegionParams) {\n  let query = baseQuery;\n  let vegaLiteSpec = spec; \u002F\u002F Should clone if modifying\n\n  if (params?.categories?.length) {\n    \u002F\u002F make changes to the DAX query to filter by the specified categories and update the query variable\n  }\n\n  if (params?.minRevenue != null) {\n    \u002F\u002F Clone spec and append a client-side filter transform to the Vega-Lite spec\n  }\n\n  return { connection, query, columnMetadata, vegaLiteSpec };\n}\n```\n\nThe parameters, their types, and how they modify the query or spec are **entirely use-case-specific**. Some visualizations may need no parameters at all; others may accept date ranges, top-N limits, grouping dimensions, or string search terms. The factory function is the single place that translates caller intent into DAX and\u002For Vega-Lite modifications.\n\n#### Query variants with multiple `.dax` files\n\nWhen a parameter changes the **structure** of the query (e.g. different GROUP BY columns, different aggregations), use separate `.dax` files for each variant. The factory function selects the right one:\n\n```text\nrevenue-trend\u002F\n  revenue-trend-yearly.dax\n  revenue-trend-quarterly.dax\n  revenue-trend-monthly.dax\n  revenue-trend.json\n  revenue-trend.ts\n```\n\n```ts\nimport yearlyQuery from \".\u002Frevenue-trend-yearly.dax?raw\";\nimport quarterlyQuery from \".\u002Frevenue-trend-quarterly.dax?raw\";\nimport monthlyQuery from \".\u002Frevenue-trend-monthly.dax?raw\";\n\ntype Granularity = \"yearly\" | \"quarterly\" | \"monthly\";\n\nconst queryByGranularity: Record\u003CGranularity, string> = {\n  yearly: yearlyQuery,\n  quarterly: quarterlyQuery,\n  monthly: monthlyQuery,\n};\n\nexport function revenueTrend(params?: { granularity?: Granularity }) {\n  const query = queryByGranularity[params?.granularity ?? \"monthly\"];\n  return { connection, query, columnMetadata, vegaLiteSpec };\n}\n```\n\n#### Column Metadata\n\nMetadata is part of the charting path — it exists to feed `toDataTable`, and both `ColumnMetadataMap` and `ColumnDef` come from the `visuals` pack. An app with no chart in it skips this section.\n\nCapture column metadata in the barrel `.ts` file as a `columnMetadata: ColumnMetadataMap` constant (import `ColumnMetadataMap` from `@\u002Flib\u002Fto-data-table`). The dictionary **must be keyed by the exact column name from the CLI query output** (the `name` field in `table.columns`). Do not guess or clean these keys — copy them verbatim from the query result. Each value is a `ColumnDef` (from `@microsoft\u002Ffabric-visuals-core`) containing:\n  - `name` — a cleaned-up identifier derived from the original column name by removing `.`, `[`, `]`, `\\`, `\"`, and `'` characters. E.g., `\"Products[Region]\"` → `\"ProductsRegion\"`, `\"[Total Revenue]\"` → `\"Total Revenue\"` — to be used when building visual specs.\n  - `displayName` — a human-readable label sourced from the semantic model schema (e.g., `\"Region\"`, `\"Total Revenue\"`). Used for axis titles, grid headers, and tooltips.\n  - `format` — a VBA\u002FECMA-376 format string for number\u002Fdate formatting (e.g., `#,##0.00`, `0.00%`, and `mm\u002Fdd\u002Fyyyy`). Omit for text type columns.\n\n**Example workflow:** Run `npx rayfin connector invoke myModel executeQuery --file .\u002Finspection\u002Fprobe.query.json`, observe the output columns are `[SalesPersonID]` and `[Name]`, then use those exact strings as metadata keys:\n\n```ts\nexport const columnMetadata: ColumnMetadataMap = {\n  \"[SalesPersonID]\": { name: \"SalesPersonID\", displayName: \"Sales Person ID\" },\n  \"[Name]\": { name: \"Name\", displayName: \"Name\" },\n};\n```\n\n#### Key rules\n\n- **All DAX lives in `.dax` files.** Never inline full DAX query strings in `.ts` factory files. If a parameter changes the query structure, create a separate `.dax` file for each variant and select the right one in the factory function. Small modifications — such as replacing filter value placeholders, wrapping the query with `CALCULATETABLE` to apply filters, or substituting a column reference — are acceptable in `.ts`, but the base query must always come from a `.dax` import.\n- **Name files after the visualization they drive.** Use kebab-case base names (e.g., `revenue-by-region.dax`, `revenue-by-region.json`, `revenue-by-region.ts`). Variant `.dax` files append a suffix (e.g., `revenue-trend-yearly.dax`, `revenue-trend-quarterly.dax`).\n- **Use `.dax` for queries.** Plain-text DAX files keep queries readable and diff-friendly. Import them with Vite's `?raw` suffix.\n- **Use `.json` for specs.** JSON files get free schema validation in editors and are importable as modules by default in Vite.\n- **Barrel `.ts` exports a factory function.** The function name is the camelCase version of the kebab-case file name (e.g., `revenueByRegion` for `revenue-by-region.ts`). It accepts optional parameters (typed per use case) and returns `{ connection, query, columnMetadata, vegaLiteSpec }` — or just `{ connection, query }` when the app draws no charts.\n- **Group by page\u002Fdomain.** Use subfolders when the dashboard has multiple pages or logical sections. For simple single-page dashboards, a flat structure under `packages\u002Ffrontend\u002Fsrc\u002Fqueries\u002F` is fine.\n- **Re-export via `index.ts`.** Each subfolder and the root `packages\u002Ffrontend\u002Fsrc\u002Fqueries\u002Findex.ts` should re-export all modules for clean imports.\n",{"name":5,"description":7},"main","0979439a7a0806abd0ee48c2619b37f297ae1324","samples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Fanalytics",77,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-12 01:21:10",{"source":8,"skillName":5,"commands":51,"prompt":61,"zipAvailable":62},[52,55,58],{"tool":53,"command":54},"npx","npx skills add microsoft\u002Frayfin --skill analytics",{"tool":56,"command":57},"bunx","bunx skills add microsoft\u002Frayfin --skill analytics",{"tool":59,"command":60},"pnpm","pnpm dlx skills add microsoft\u002Frayfin --skill analytics","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Fanalytics\u002FSKILL.md",true,[64,70,74,78],{"path":65,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":68,"sourceHtmlUrl":69},"kit\u002Fhooks\u002Fuse-semantic-model-query.spec.ts","SCRIPT","脚本",12219,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Fanalytics\u002Fkit\u002Fhooks\u002Fuse-semantic-model-query.spec.ts",{"path":71,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":72,"sourceHtmlUrl":73},"kit\u002Fhooks\u002Fuse-semantic-model-query.ts",7846,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Fanalytics\u002Fkit\u002Fhooks\u002Fuse-semantic-model-query.ts",{"path":75,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":76,"sourceHtmlUrl":77},"kit\u002Flib\u002Fconnectors.ts",3831,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Fanalytics\u002Fkit\u002Flib\u002Fconnectors.ts",{"path":79,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":82,"sourceHtmlUrl":83},"pack.json","REFERENCE","参考文档",798,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Fanalytics\u002Fpack.json",[85,98,109,117,136,144],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":36},"01M699YEY2QDVPKTZS3HR9AX84","rayfin-getting-started","Use when starting or creating a NEW Rayfin app, or when a Rayfin task comes up and you are not yet inside a Rayfin project. Gets you into a project with the Rayfin CLI, then hands off to the authoritative, version-locked in-project rayfin skill\u002Fdocs that own all in-project work. Triggers: build a Rayfin app, start a Rayfin project, create a new Rayfin app, create-rayfin, npm create @microsoft\u002Frayfin, rayfin init, scaffold rayfin, rayfin CLI, rayfin template, universal app, awesome-rayfin gallery, get started with Rayfin","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fskills\u002Frayfin-getting-started\u002FSKILL.md",[],[92,93,94,95,9,96,97],"rayfin getting started","rayfin","scaffold","init","docs","cli",{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":106,"publishedAt":36},"01M699YCN4ZDW2AMDP4NVJ2QGC","visuals","Use when user wants to incorporate charts, graphs, data grid,  or other visual representations of data into their project. Use VegaVisual and DataGrid components to create these visuals,  utilizing the shared DataTable input, formatting, theme, and interactivity. Covers the onInteraction selection\u002Fclick events host apps consume, named multi-table data input for layered overlays and reference lines, and Vega-Lite native selections. Triggers: chart, graph, plot, dashboard, KPI, metric, trend, scorecard, data grid, visualize.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Fvisuals\u002FSKILL.md",[104,105],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},[100,107,33,108],"components","visualize",{"skillNo":110,"name":111,"nameZh":6,"description":112,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":113,"categories":114,"keywords":115,"publishedAt":36},"01M699YBEP146MJZJNN8YEBZ2G","schema-discovery","Explore Power BI semantic model schemas using DAX INFO functions. Progressive metadata discovery strategy, scope estimation, and narrowing techniques for tables, columns, measures, and relationships.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Fschema-discovery\u002FSKILL.md",[],[116,35],"schema discovery",{"skillNo":118,"name":119,"nameZh":6,"description":120,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":121,"categories":122,"keywords":132,"publishedAt":36},"01M699Y9E80WYFKD1S4MT4B1CS","query-design","Separates DAX data-fetching from TypeScript presentation. Guides when to use  DAX vs. TypeScript vs. Vega-Lite for aggregation, total rows, FORMAT(), SELECTCOLUMNS,  BLANK handling, filtering, multi-grain queries, cross-filtering and cross-highlight subset\u002Foverlay queries, and format strings.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Fquery-design\u002FSKILL.md",[123,126,129],{"categoryNo":124,"categoryName":125,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000003","演示文稿",{"categoryNo":127,"categoryName":128,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":130,"categoryName":131,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000032","设计师",[133,134,35,135],"query design","design","typescript",{"skillNo":137,"name":138,"nameZh":6,"description":139,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":140,"categories":141,"keywords":142,"publishedAt":36},"01M699Y7CKZ55QSYFE827RRVJE","functions-capability","Apply and build the Universal App functions capability. Use for trusted server-side logic, secrets, external APIs, custom model endpoints, published Fabric data agents, webhooks, or privileged operations.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Ffunctions-capability\u002FSKILL.md",[],[143],"functions capability",{"skillNo":145,"name":146,"nameZh":6,"description":147,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":148,"categories":149,"keywords":150,"publishedAt":36},"01M699Y5R87YE620T78Z30KQSA","fabric-sdk","How to query Fabric data from a running app through the Rayfin connectors client. Use getRayfinClient().connectors.\u003Cname>.executeQuery to run DAX against a semantic model, and toQueryResult to normalize the response.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Ffabric-sdk\u002FSKILL.md",[],[151,152,35,153,93,154],"sdk","fabric sdk","rayfin connectors","connectors"]