This is an automated email from the ASF dual-hosted git repository.
kevinjqliu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-python.git
The following commit(s) were added to refs/heads/main by this push:
new f2131e6ee docs: add GCP BigLake Metastore Catalog configuration
example (#2740)
f2131e6ee is described below
commit f2131e6eea6fdd1158471e163e21c29dd23a3849
Author: Kyle Heath <[email protected]>
AuthorDate: Thu Nov 13 10:29:16 2025 -0800
docs: add GCP BigLake Metastore Catalog configuration example (#2740)
- Adds documentation example for configuring Google BigLake Metastore as
a REST catalog
- Includes configuration example with proper authentication setup
# Rationale for this change
GCP had the GA release of the BigLake Metastore Catalog Iceberg REST api
Nov 30 (see [release
notes](https://docs.cloud.google.com/bigquery/docs/release-notes#October_30_2025)).
There are few GCP docs available how to set this up in general, and with
pyiceberg specifically. Ray Data and probably many other tools use
pyiceberg under the hood, so documenting this would make it much easier
for folks in the GCP cloud to use pyiceberg at scale.
# Are these changes tested?
Yes, using the following test plan:
- [x] Configuration tested to work with pyiceberg 0.10.0 and Google
BigLake Metastore (Nov 11, 2025)
- [x] Documentation builds successfully
- [x] Configuration example follows existing format and style
- [x] Added links are valid
# Are there any user-facing changes?
Would add a new section in the docs when docs are published.
---------
Co-authored-by: Kyle <[email protected]>
---
mkdocs/docs/configuration.md | 22 ++++++++++++++++++++++
1 file changed, 22 insertions(+)
diff --git a/mkdocs/docs/configuration.md b/mkdocs/docs/configuration.md
index 3eb6869d8..521901027 100644
--- a/mkdocs/docs/configuration.md
+++ b/mkdocs/docs/configuration.md
@@ -551,6 +551,28 @@ catalog:
type: noop
```
+##### GCP BigLake Metastore Catalog REST
+
+```yaml
+catalog:
+ biglake_catalog:
+ type: rest
+ uri: https://biglake.googleapis.com/iceberg/v1/restcatalog
+ warehouse: gs://<bucket-name> # Use bq://projects/<gcp-project-id> for
federation option (see docs)
+ auth:
+ type: google
+ header.x-goog-user-project: <gcp-project-id>
+ header.X-Iceberg-Access-Delegation: "" # For user-credentials
authentication, set to empty string.
+```
+
+<!-- prettier-ignore-start -->
+
+!!! Note "Metastore Authentication Models"
+ If your BigLake Metastore catalog is configured for "user credentials"
authentication instead of "vendor credentials", set the
`header.X-Iceberg-Access-Delegation` header to an empty string as shown above.
Standard GCP Application Default Credentials (ADC) will be used to authenticate
requests to the BigLake Metastore REST API.
+ You can retrieve the configuration details for your BigLake Iceberg
catalog at the [GCP Console BigLake Metastore
page](https://console.cloud.google.com/biglake/metastore/catalogs). Select your
catalog, then find the necessary parameters such as `uri`, `warehouse`, and
authentication method (e.g. user-creds or vendor).
+
+<!-- prettier-ignore-end -->
+
### SQL Catalog
The SQL catalog requires a database for its backend. PyIceberg supports
PostgreSQL and SQLite through psycopg2. The database connection has to be
configured using the `uri` property. The init_catalog_tables is optional and
defaults to True. If it is set to False, the catalog tables will not be created
when the SQLCatalog is initialized. See SQLAlchemy's [documentation for URL
format](https://docs.sqlalchemy.org/en/20/core/engines.html#backend-specific-urls):
