search-consumption-cli

---
name: "search-consumption-cli"
description: "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."
license: "MIT"
---

> **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

```bash
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

```bash
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):

```bash
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:

```bash
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
```bash
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
```bash
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
```bash
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](https://learn.microsoft.com/en-us/rest/api/fabric/core/catalog/search) 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. |