canonical: https://jentic.com/apis/googleapis.com/biglake

# Google BigLake API

The BigLake API provides programmatic access to BigLake Metastore, a serverless metastore for open-source data formats - primarily Apache Iceberg tables - that can be queried from BigQuery and Spark. It exposes operations to manage catalogs, databases, and tables, including a rename operation for schema evolution. Resources are scoped to a project and location, and the metastore makes the same data discoverable to multiple compute engines without per-engine setup. The API does not run queries or process data; it manages metadata only.

## For AI agents

Manage Apache Iceberg catalogs, databases, and tables in Google Cloud BigLake Metastore for open-source data lakes.

## Scope

Does not run queries, store table data, or transform records - use for managing BigLake Metastore catalogs, databases, and Iceberg table metadata only.

## Capabilities

- Create and list catalogs in BigLake Metastore at /v1/{+parent}/catalogs
- Create and list databases inside a catalog via /v1/{+parent}/databases
- Create, get, patch, and delete Iceberg table entries scoped to a database
- Rename a metastore resource via /v1/{+name}:rename to support schema evolution
- Page through large catalog and database listings using pageToken on the list endpoints
- Patch table or database metadata to update labels and references

## Use cases

### Iceberg-Based Data Lake on Google Cloud

Run an open Iceberg-format data lake on Cloud Storage and make the tables queryable from BigQuery and Spark by registering them in BigLake Metastore. The API is the single integration surface for catalog and database management, so onboarding a new domain is a matter of creating a catalog plus the relevant databases and tables.

Example prompt: POST a catalog create request to /v1/{parent}/catalogs and then create the underlying databases for each domain.

### Schema Evolution Without Data Movement

Rename Iceberg tables and databases as schemas evolve without copying data. The dedicated rename endpoint updates the metastore reference, leaving the underlying object-storage data in place and avoiding rewrite cost. Useful during refactors that consolidate or split domains.

Example prompt: POST a new name to /v1/{name}:rename for the source resource and verify the response.

### Cross-Engine Data Discovery

Make the same Iceberg datasets discoverable to BigQuery, Dataproc Spark, and external Iceberg-aware engines from one metastore. The API exposes list endpoints suitable for building a data catalog UI or feeding lineage tools without parsing object-storage layouts.

Example prompt: List all catalogs and their databases, and feed the results into a downstream data catalog tool as a metadata sync.

### AI Agent Data Lake Hygiene via Jentic

Use an AI agent to keep BigLake catalogs tidy by listing resources, identifying stale entries, and renaming or deleting them on a schedule. Through Jentic the agent finds the rename and delete operations by intent and runs them with project credentials supplied at execute time, removing the need for SDK setup in the agent.

Example prompt: Use Jentic search for 'rename a table in BigLake Metastore', load the schema for /v1/{name}:rename, and execute it with the new name.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /v1/{+name} | Get a catalog, database, or table by resource name |
| PATCH | /v1/{+name} | Update a database or table's mutable fields |
| DELETE | /v1/{+name} | Delete a catalog, database, or table |
| POST | /v1/{+name}:rename | Rename a metastore resource |
| GET | /v1/{+parent}/catalogs | List catalogs in a project and location |
| POST | /v1/{+parent}/catalogs | Create a catalog |
| GET | /v1/{+parent}/databases | List databases in a catalog |
| POST | /v1/{+parent}/databases | Create a database |

## Key resources

- **catalogs** — Top-level metastore containers grouping databases
- **databases** — Logical namespaces for Iceberg tables within a catalog
- **tables** — Iceberg table metadata entries

## Why Jentic

- **Setup:** Wiring the BigLake API by hand means setting up Google OAuth2, scoping a service account for Metastore access, and minting short-lived access tokens for each catalog and database call yourself. Through Jentic you install once, import the BigLake API from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** This API puts the catalog and database name in the URL path (/v1/{parent}/catalogs, /v1/{name}), so a rule can pin your agent to one catalog: it can list and create catalogs and databases there and nothing else. You choose the operations it may call, so actions like deleting or renaming a resource are not included unless you add them.
- **Credential handling:** Your Google Cloud OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a BigLake catalog' or 'rename an Iceberg table', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without reading the full reference.

## Related APIs

- **BigQuery API** — Query engine that reads BigLake Metastore tables natively
- **Data Catalog API** — Discovery and tagging for data assets across Google Cloud
- **Dataproc API** — Managed Spark and Hadoop engines that read BigLake Iceberg tables

## FAQ

### What authentication does the BigLake API use?

The API uses Google OAuth 2.0 with cloud-platform scope. Service accounts must hold the roles/biglake.* IAM role on the project. Through Jentic the service account credential is encrypted in the vault and only short-lived access tokens reach the agent.

### Can I rename an Iceberg table through the BigLake API?

Yes. POST a new name to /v1/{name}:rename on the table, database, or catalog resource. Renaming updates the metastore reference without moving the underlying object-storage data.

### How do I create a new catalog through Jentic?

Search Jentic for 'create a BigLake catalog'. Jentic returns POST /v1/{parent}/catalogs with the input schema; execute it with the catalog name and Jentic supplies the credential from the vault. The catalog is then ready for databases.

### What are the rate limits for the BigLake API?

Numeric limits are not declared in the spec; quotas are enforced per project on biglake.googleapis.com. Review the project's quota dashboard before driving large numbers of metadata changes.

### Does BigLake run queries against the data?

No. BigLake is a metastore. Queries run in BigQuery, Dataproc Spark, or another Iceberg-aware engine pointed at the same metastore. This API exposes only the metadata surface.

### Can I list catalogs across multiple projects in one call?

No. The list endpoint is scoped to a parent in the form projects/{project}/locations/{location}. Iterate the projects you care about and call the list endpoint for each.

### Can I limit what my agent is allowed to do with the BigLake API?

Yes. Because BigLake puts the catalog and database name in the URL path (like /v1/{parent}/catalogs and /v1/{name}), your self-hosted Jentic One instance lets you write a rule that pins the agent to a single catalog, where it can only list and create catalogs and databases and nothing else. You decide which operations the agent may call, so destructive actions such as deleting or renaming a metastore resource via /v1/{name}:rename stay out of reach unless you explicitly add them. The agent runs with the project credential your own instance supplies at execution time, under the rules you set.