You can diagnose and resolve errors in borderless Lakehouse and its
associated resources, including issues with metadata table queries,
metadata.json file size limits, and multi-region catalog configurations.
Addressing these issues helps you restore table operations and query execution
across your lakehouse workloads.
Cannot query metadata tables
This issue occurs when you query metadata tables, such as .snapshots or
.files, for your Apache Iceberg tables supported by the
Lakehouse runtime catalog in BigQuery using a five-part
name identifier.
To resolve this issue, query these tables using Apache Spark.
metadata.json file size limit
The Apache Iceberg metadata.json file size is limited to 1 MB. This limit
applies to the metadata file that tracks table snapshots, schemas, and partition
specs. If your metadata file exceeds this size, you might encounter errors when
performing table operations through the Apache Iceberg REST catalog endpoint.
To resolve this issue, request a limit increase by contacting your Google account team.
NOT_FOUND errors when querying multi-region catalogs
This issue occurs when you create a catalog in the Lakehouse runtime catalog
using a multi-region Cloud Storage bucket without specifying a primary
location, and then attempt to query the catalog by specifying a
BigQuery virtual region (such as US or EU).
When a catalog is created with a multi-region bucket, its metadata is stored in
specific regional locations within the geographic scope of the multi-region
rather than in the corresponding BigQuery virtual region. If you
force a query to run in a virtual region where the metadata is not present, the
query fails with a NOT_FOUND error.
To resolve this issue, specify the primary location (for example, US or EU)
when you create the catalog. For more information, see Specify primary regions
for US and EU multi-regions.
Storage optimization jobs don't appear in INFORMATION_SCHEMA.JOBS
This issue occurs when you enable table management on an Apache Iceberg table
and perform data mutations (such as inserts or DML statements), but no storage
optimization jobs (such as CALL BQ.OPTIMIZE_STORAGE) appear in the
INFORMATION_SCHEMA.JOBS view. For more information about querying these jobs,
see Get Iceberg storage optimization
jobs.
This behavior is expected when storage optimization is skipped. Table management assesses the table layout after data mutations and only runs optimization jobs when data files require compaction or restructuring. Because background table management jobs run in your project and consume compute resources, BigQuery doesn't rewrite data when the table layout is already optimized. Optimization is skipped under the following conditions:
- Files are already optimal: Existing data files are already near or above the target file size (average uncompressed size is at least 50% of 256 MB).
- Thresholds aren't met: The table hasn't accumulated enough small files or doesn't meet the size threshold (such as a total table size exceeding 1 GB) required for compaction.
When storage optimization is skipped, no background job is executed, and no
entry is logged in INFORMATION_SCHEMA.JOBS.
If query performance meets your requirements and files are already appropriately sized, no action is needed. Storage optimization runs automatically when future writes cause sufficient file fragmentation.
To observe storage optimization jobs in a test environment, simulate file fragmentation by inserting multiple small batches of data over time into a table exceeding 1 GB in size.