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

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

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

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

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.