/search-consumption-cli

name: search-consumption-cli
description: "Finds Fabric items across every workspace with the Catalog Search API when the workspace is unknown, locating an item by display name, inventorying one item type tenant-wide, and returning the workspace and item IDs later calls need. Dataflow Gen1 and Gen2 items are not supported. Use only to locate items; once found, query them with the owning item skill such as sqldw-cli, spark-cli, eventhouse-cli or fabriciq."

> **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](../../common/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](../../common/COMMON-CORE.md) — Fabric REST API patterns, auth
• [COMMON-CLI.md](../../common/COMMON-CLI.md) — CLI implementation (az, curl, jq)

Table of Contents

| Task | Reference | Notes | |---|---|---| | Search for an Item | [SKILL.md § Search for an Item](#search-for-an-item) | By name, description, or workspace name | | List All Items of a Type | [SKILL.md § List All Items of a Type](#list-all-items-of-a-type) | Empty search + type filter | | Pagination | [SKILL.md § Pagination](#pagination) | Continuation token pattern | | Agentic Workflow | [SKILL.md § Agentic Workflow](#agentic-workflow) | | | Examples | [SKILL.md § Examples](#examples) | | | Gotchas and Troubleshooting | [SKILL.md § Gotchas and Troubleshooting](#gotchas-and-troubleshooting) | |

---

Must/Prefer/Avoid

MUST DO

• **Authenticate first** — see [COMMON-CORE.md § Authentication & Token Acquisition](../../common/COMMON-CORE.md#authentication--token-acquisition) and [COMMON-CLI.md § Authentication Recipes](../../common/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](../../common/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](https://learn.microsoft.com/en-us/rest/api/fabric/core/catalog/search).

---

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