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.

CRITICAL NOTES

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).

The search text matches against item display name, description, and workspace name.

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)

Task	Reference	Notes
Search for an Item	SKILL.md § Search for an Item	By name, description, or workspace name
List All Items of a Type	SKILL.md § List All Items of a Type	Empty search + type filter
Pagination	SKILL.md § Pagination	Continuation token pattern
Agentic Workflow	SKILL.md § Agentic Workflow
Examples	SKILL.md § Examples
Gotchas and Troubleshooting	SKILL.md § Gotchas and Troubleshooting

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-cli, spark-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

Goal	Filter
Only lakehouses	`Type eq 'Lakehouse'`
Reports or semantic models	`Type eq 'Report' or Type eq 'SemanticModel'`
Exclude notebooks	`Type ne 'Notebook'`

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

Ask — user provides an item name, type, or description keywords.
Search — call Catalog Search with the user's input and optional type filter.
Disambiguate — if multiple matches, present results (name, type, workspace) and ask the user to pick.
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

Symptom	Cause	Fix
`401 Unauthorized`	Wrong token audience or expired session	Verify `--resource "https://api.fabric.microsoft.com"`. Run `az login`.
`InvalidPageSize`	`pageSize` outside 1–1000	Use a value between 1 and 1000.
`InvalidFilter`	Bad filter syntax	Only `eq`, `ne`, `or`, and parentheses. Don't mix `eq` with `and`, or `ne` with `or`. Don't mix `eq` and `ne` in the same filter.
`TypeNotFound`	Unrecognized item type in filter	Check spelling (case-sensitive). See API reference for valid types.
`FilterTooManyValues`	Filter has more than 500 values	Reduce the number of type values in the filter.
`InvalidRequest`	Missing request body	Ensure `--body` points to a valid JSON file.
Empty results for known item	Item type not supported	Dataflow Gen1/Gen2 are excluded. Use `GET /v1/workspaces/{id}/items` instead.
New item not found	Catalog index propagation delay	Indexing lag is variable and not yet near-real-time — usually minutes, but not guaranteed. A just-created item may not appear in search results yet; verify it exists via `GET /v1/workspaces/{id}/items` instead.
Too many results	Search text too broad	Add a type filter or use more specific search text.

About this skill