Search Consumption CLI Agent Skill

> 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

| 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-consumption-cli, spark-consumption-cli, eventhouse-consumption-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. |