aidp-catalog-explore

# `aidp-catalog-explore` — live catalog browsing Browse and inspect the AIDP catalog directly via the control-plane — no SQL, no compute, no MCP required. Complements `aidp-catalog-init`: use this for ad-hoc, live lookups; use `catalog-init` to build the cached grounding file. ## When to use - "What catalogs/schemas/tables are there?" · "describe / show columns of <table>" · "find tables about X" - You need a catalog/schema/table **key** to feed another skill. ## Engine — official `aidp` CLI (control-plane, read-only) Preferred engine is the official Oracle `aidp` CLI; `oci raw-request` is the fallback when the CLI isn't installed. Both hit the same data-plane REST API with the same auth — see [references/aidp-cli-map.md](../../references/aidp-cli-map.md) for the full command map and [references/oci-raw-request.md](../../references/oci-raw-request.md) for base URL + auth ladder. | Goal | CLI (preferred) | REST fallback (verified) | |---|---|---| | List catalogs | `aidp catalog list` | `GET /catalogs` | | Describe a catalog | `aidp catalog get --catalog-key <cat>` | (in list output) | | List schemas in a catalog | `aidp schema list --catalog-key <cat>` | `GET /schemas?catalogKey=<cat>` | | List tables in a schema | `aidp schema list-tables --catalog-key <cat> --schema-key <cat.schema>` | `GET /tables?catalogKey=<cat>&schemaKey=<cat.schema>` | | Describe a single table | `aidp schema get-table --catalog-key <cat> --schema-key <cat.schema> --table-key <t>` | `GET /tables?…` then filter by table key client-side | | List volumes | `aidp volume list --catalog-key <cat>` | `GET /volumes?catalogKey=<cat>` (param shape TBD — if `400`, the error names the required param) | All CLI calls take `--instance-id <DATALAKE_OCID> --auth api_key --profile DEFAULT --region <r>`. ```bash # CLI (preferred): list tables in cat.schema aidp schema list-tables --catalog-key default --schema-key default.default \ --instance-id <DATALAKE_OCID> --auth api_key --profile DEFAULT --region us-ashburn-1 # Fallback (no CLI installed): oci raw-request, --profile DEFAULT (api_key) oci raw-request --http-method GET \ --target-uri "https://aidp.us-ashburn-1.oci.oraclecloud.com/20240831/dataLakes/<OCID>/tables?catalogKey=default&schemaKey=default.default" \ --profile DEFAULT ``` On `401/403/"Security Token"` follow the auth ladder. Per-endpoint REST params are **required** — a bare path returns `400 InvalidParameter: query param X must not be null`, which names the missing param. REST output is JSON: `{ "data": …, "headers": …, "status": <int> }`. ## Patterns - **Browse down the tree:** `aidp catalog list` → `aidp schema list --catalog-key <cat>` → `aidp schema list-tables --catalog-key <cat> --schema-key <cat.schema>` → `aidp schema get-table` (or the REST fallback `GET /catalogs` → `GET /schemas?catalogKey=` → `GET /tables?…` → filter for the table). - **Describe a table:** list tables for the schema, then filter the response by table key; present columns, types, properties, and any declared keys from that table object. - **Find by concept:** check `.aidp/catalog.md` Quick Reference first (instant); fall back to scanning `/tables` names + table objects for the concept. - **Resolve name→key:** downstream skills need keys, not display names — use these list calls to translate. ## Notes - Workspace/DataLake-scoped — confirm the region + DataLake OCID first. - Prefer the cached `.aidp/catalog.md` for repeated lookups; this skill is for live/uncached inspection or when the cache may be stale (then suggest `aidp-catalog-init --refresh`). - If an `aidp` MCP is configured, its `list_catalogs` / `list_schemas` / `list_tables` / `get_table` / `list_volumes` tools are an optional accelerator — not required. ## References - [references/aidp-cli-map.md](../../references/aidp-cli-map.md) — skill → official `aidp` CLI command map (primary engine) - [references/oci-raw-request.md](../../references/oci-raw-request.md) · [references/no-mcp-rest-map.md](../../references/no-mcp-rest-map.md)