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 " · "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 for the full command map and 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>.

# 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 — skill → official aidp CLI command map (primary engine)
• references/oci-raw-request.md · references/no-mcp-rest-map.md