Improve CLI describe entity detection

[kevinjqliu]

Why

pyiceberg describe currently prints namespace output before it knows whether the same identifier is also a table. This makes ambiguous identifiers look successful and leaves partial output behind.

This splits the generic describe fix from #3926. View support stays in the follow-up PR.

CLI behavior

--entity still accepts only any, namespace, and table.

Fast paths

Explicit entity selection returns directly from the matching catalog loader:

• pyiceberg describe --entity namespace sales.orders loads the multipart namespace and returns.
• pyiceberg describe --entity table sales.orders loads the table and returns.

A single-part identifier in the default any mode also keeps its existing fast path:

• pyiceberg describe sales loads sales as a namespace and returns.

Multipart identifiers in any mode

For pyiceberg describe sales.orders, the CLI must check both entity types to detect a collision:

1. Try to load sales.orders as a multipart namespace.
2. Try to load sales.orders as a table, even when the namespace exists.
3. Print output only after both checks finish.

There is intentionally no early return after the multipart namespace match. Otherwise, a namespace/table collision would be reported as a namespace instead of an ambiguity.

The final behavior is:

• Namespace only: print the namespace properties.
• Table only: print the table description.
• Neither: keep the existing combined table-or-namespace not-found error.
• Both: fail with:

Identifier sales.orders matches multiple entity types: namespace, table. Use --entity to disambiguate.

Catalog errors other than namespace/table not-found errors are surfaced unchanged.

BigQuery

BigQuery supports dataset.table identifiers but not multipart namespaces. Its namespace loader now reports a multipart namespace candidate as NoSuchNamespaceError, allowing any mode to continue to the table check. Other namespace loader implementations were audited and already follow this contract or support multipart namespaces.

Tests

• Full CLI test module: 90 passed
• BigQuery catalog test module: 6 passed
• Changed-file lint and type hooks passed

[Copilot]

🔵 Needs a closer look

BigQuery multipart table identifiers can fail auto-detection before table loading.

Pull request overview

Improves pyiceberg describe by resolving multipart namespace/table identifiers, supporting explicit entity selection, and requiring disambiguation for collisions.

Changes:

• Adds automatic namespace/table detection.
• Adds explicit --entity handling.
• Expands CLI tests for detection and ambiguity.

File summaries

File	Summary
tests/cli/test_console.py	Adds coverage for entity detection and ambiguity behavior.
pyiceberg/cli/console.py	Implements entity resolution and disambiguation.

Review details

Suppressed comments (1)

pyiceberg/cli/console.py:179

• In BigQueryMetastoreCatalog, load_namespace_properties calls identifier_to_database without an error override, so a valid multipart table identifier such as dataset.table raises ValueError for the namespace candidate. Because this path only catches NoSuchNamespaceError, auto-detection exits before trying load_table, making describe dataset.table fail for every BigQuery table unless --entity table is supplied. Treat an invalid namespace shape as a non-match during auto-detection (or use a catalog-neutral existence check).

    except NoSuchNamespaceError:
        pass

• Files reviewed: 2/2 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[kevinjqliu]

@ebyhr i took some inspiration from your original implementation in #3926. What do you think about this new describe implementation? 😄

[rambleraptor]

The logic here looks great. A couple style ideas, but they're all nits.

[rambleraptor]

nit: comment here describing that this is a namespace attempt could be good.

[rambleraptor]

same as above but with table

[rambleraptor]

Suggested change

	if entity == "namespace":
	if entity == "namespace" or (entity == "any" and len(identifier_tuple) == 1):

This will clean up the if statement at line 167, but it's a bit harder to parse. Your call.

[kevinjqliu]

i actually did this intentionally. these ifs are for the individual checks namespace / table / and view (in #3926)

starting L167 is the "any" fallback behavior. i can add a inline comment for that to be more explicit

[rambleraptor]

Yeah that would be great. I saw that's what you were trying to do, but that little bit of duplication was definitely bugging me 😂