search-consumption-cli

Telemetry — MANDATORY. Every api.fabric.microsoft.com call must carry x-ms-fabric-skill: search-consumption-cli (az rest: --headers "x-ms-fabric-skill=search-consumption-cli"), including every LRO poll, fabric_lro and retry. Snippets omit it — add it anyway.

Update Check — ONCE PER SESSION (mandatory) The first time this skill is used in a session, run the check-updates skill before proceeding.

• GitHub Copilot CLI / VS Code: invoke the check-updates skill (e.g., /fabric-skills:check-updates).
• Claude Code / Cowork / Cursor / Windsurf / Codex: read the local package.json version, then compare it against the remote version via git fetch origin main --quiet && git show origin/main:package.json (or the GitHub API). If the remote version is newer, show the changelog and update instructions.
• Skip if the check was already performed earlier in this session.

CRITICAL NOTES

1. The Catalog Search API finds items, not workspaces. To find a workspace by name, use GET /v1/workspaces (see COMMON-CLI.md § Resolve Workspace Properties by Name).
2. The search text matches against item display name, description, and workspace name.
3. Dataflow (Gen1) and Dataflow (Gen2) are not supported.

Catalog Search — CLI Skill

Prerequisite Knowledge

• COMMON-CORE.md — Fabric REST API patterns, auth
• COMMON-CLI.md — CLI implementation (az, curl, jq)

Table of Contents

Must/Prefer/Avoid

MUST DO

• Authenticate first — see COMMON-CORE.md § Authentication & Token Acquisition and COMMON-CLI.md § Authentication Recipes. The Catalog Search API requires Catalog.Read.All scope.
• Write the JSON body to a temp file — avoids shell quoting issues with filter strings.
• Disambiguate — if multiple results match, present display name, type, and workspace name and ask the user to confirm.

PREFER

• Catalog Search over list-and-filter — single cross-workspace call, no need to resolve workspace first.
• Type filters — narrow results with "filter": "Type eq 'Lakehouse'" to reduce noise.
• Empty search with type filter — to list all items of a type across workspaces.
• jq for extracting IDs from the response — cleaner than JMESPath for nested hierarchy.workspace.

AVOID

• Searching for workspaces — the Catalog Search API returns items, not workspaces. Use GET /v1/workspaces instead (see COMMON-CLI.md § Resolve Workspace Properties by Name).
• Querying source data after the workspace/item is known — route to the workload-specific consumption skill (sqldw-consumption-cli, spark-consumption-cli, eventhouse-cli, or fabriciq) instead of Catalog Search.
• Inventing filter syntax — only eq, ne, or, and parentheses are supported.
• Assuming all item types are supported — Dataflow (Gen1) and Dataflow (Gen2) are not returned yet.

Search for an Item

cat > /tmp/body.json << 'EOF'
{"search": "SalesLakehouse", "filter": "Type eq 'Lakehouse'", "pageSize": 10}
EOF
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/catalog/search" \
  --body @/tmp/body.json

The search text matches against item display name, description and workspace name. Type filtering is optional. The response includes id, type, displayName, description, and hierarchy.workspace (with id and displayName) for each match.

Extract item and workspace IDs

az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/catalog/search" \
  --body @/tmp/body.json \
  --query "value[0].{itemId:id, workspaceId:hierarchy.workspace.id, name:displayName}" \
  --output json

Filter Examples

For the full list of supported item types, see the Catalog Search API reference.

List All Items of a Type

Use an empty search string with a type filter (pageSize max is 1000):

cat > /tmp/body.json << 'EOF'
{"search": "", "filter": "Type eq 'Lakehouse'", "pageSize": 100}
EOF
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/catalog/search" \
  --body @/tmp/body.json

Pagination

If the response includes a non-null continuationToken, pass it in the next request:

cat > /tmp/body.json << 'EOF'
{"search": "", "filter": "Type eq 'Lakehouse'", "pageSize": 100, "continuationToken": "<token>"}
EOF
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/catalog/search" \
  --body @/tmp/body.json

Continue until continuationToken is null.

Agentic Workflow

1. Ask — user provides an item name, type, or description keywords.
2. Search — call Catalog Search with the user's input and optional type filter.
3. Disambiguate — if multiple matches, present results (name, type, workspace) and ask the user to pick.
4. Return — provide the search results, include the item id and hierarchy.workspace.id for downstream use.

Examples

Find a specific report

cat > /tmp/body.json << 'EOF'
{"search": "Monthly Sales Revenue", "filter": "Type eq 'Report'", "pageSize": 10}
EOF
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/catalog/search" \
  --body @/tmp/body.json \
  --query "value[].{name:displayName, type:type, workspace:hierarchy.workspace.displayName}" \
  --output table

List all semantic models across workspaces

cat > /tmp/body.json << 'EOF'
{"search": "", "filter": "Type eq 'SemanticModel'", "pageSize": 1000}
EOF
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/catalog/search" \
  --body @/tmp/body.json

Save search results to file

cat > /tmp/body.json << 'EOF'
{"search": "", "filter": "Type eq 'Lakehouse'", "pageSize": 1000}
EOF
az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/catalog/search" \
  --body @/tmp/body.json \
  --query "value[].{name:displayName, type:type, workspace:hierarchy.workspace.displayName, id:id}" \
  --output json > /tmp/search_results.json

Gotchas and Troubleshooting