- [Resource: IcebergCatalog](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#IcebergCatalog)
  - [JSON representation](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#IcebergCatalog.SCHEMA_REPRESENTATION)
- [CredentialMode](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#CredentialMode)
- [CatalogType](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#CatalogType)
- [Replica](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#Replica)
  - [JSON representation](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#Replica.SCHEMA_REPRESENTATION)
- [State](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#State)
- [RestrictedLocationsConfig](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RestrictedLocationsConfig)
  - [JSON representation](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RestrictedLocationsConfig.SCHEMA_REPRESENTATION)
- [FederatedCatalogOptions](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#FederatedCatalogOptions)
  - [JSON representation](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#FederatedCatalogOptions.SCHEMA_REPRESENTATION)
- [UnityCatalogInfo](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#UnityCatalogInfo)
  - [JSON representation](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#UnityCatalogInfo.SCHEMA_REPRESENTATION)
- [GlueCatalogInfo](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#GlueCatalogInfo)
  - [JSON representation](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#GlueCatalogInfo.SCHEMA_REPRESENTATION)
- [SnowflakeCatalogInfo](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#SnowflakeCatalogInfo)
  - [JSON representation](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#SnowflakeCatalogInfo.SCHEMA_REPRESENTATION)
- [RefreshOptions](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshOptions)
  - [JSON representation](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshOptions.SCHEMA_REPRESENTATION)
- [RefreshSchedule](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshSchedule)
  - [JSON representation](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshSchedule.SCHEMA_REPRESENTATION)
- [RefreshScope](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshScope)
  - [JSON representation](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshScope.SCHEMA_REPRESENTATION)
- [RefreshStatus](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshStatus)
  - [JSON representation](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshStatus.SCHEMA_REPRESENTATION)
- [Methods](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#METHODS_SUMMARY)

## Resource: IcebergCatalog

The Iceberg REST Catalog information.

| JSON representation |
|---|
| ``` { "name": string, "credential-mode": enum (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#CredentialMode`), "biglake-service-account": string, "biglake-service-account-id": string, "catalog-type": enum (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#CatalogType`), "default-location": string, "storage-regions": [ string ], "create-time": string, "update-time": string, "replicas": [ { object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#Replica`) } ], "description": string, "restricted-locations-config": { object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RestrictedLocationsConfig`) }, "federated-catalog-options": { object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#FederatedCatalogOptions`) } } ``` |

| Fields ||
|---|---|
| `name` | `string` Identifier. The catalog name, `projects/my-project/catalogs/my-catalog`. This field is immutable. This field is ignored for catalogs.create. |
| `credential-mode` | ``enum (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#CredentialMode`)`` Optional. The credential mode for the catalog. |
| `biglake-service-account` | `string` Output only. The service account used for credential vending, output only. Might be empty if Credential vending was never enabled for the catalog. For federated catalogs, the service account will be always provisioned and will be used to access the remote Iceberg REST Catalog using access to Secret Manager secret or identity federation. |
| `biglake-service-account-id` | `string` Output only. The unique ID of the service account. This is used for federation scenarios. |
| `catalog-type` | ``enum (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#CatalogType`)`` Required. The catalog type. Required for catalogs.create. Catalog type is immutable, except for the case of conversion from CATALOG_TYPE_GCS_BUCKET to CATALOG_TYPE_BIGLAKE. |
| `default-location` | `string` Optional. The default storage location for the catalog, e.g., `gs://my-bucket`. For Google Cloud Storage bucket catalogs, this is output only. For BigLake catalogs, this field must be provided and point to a Google Cloud Storage bucket or a path within that bucket. This path serves as the base directory for constructing the full path to a table's data and metadata directories when a location is not specified at the namespace or table level. The full path is formed by appending the namespace and table identifiers to the default location. |
| `storage-regions[]` | `string` Output only. The Google Cloud region(s) of the default location's bucket, e.g. `us-central1`, `nam4` or `us`. This will contain one value for all locations, except for the catalogs that are configured to use custom dual region buckets, in which case it will contain the two regions of the bucket. The region(s) of this field should be in the jurisdiction of or nearby the primary location of the catalog. |
| `create-time` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. When the catalog was created. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `update-time` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. When the catalog was last updated. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `replicas[]` | ``object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#Replica`)`` Output only. The replicas for the catalog metadata. |
| `description` | `string` Optional. A user-provided description of the catalog. The description must be a UTF-8 string with a maximum length of 1024 characters. |
| `restricted-locations-config` | ``object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RestrictedLocationsConfig`)`` Optional. Restricted locations configuration. This field is currently only used for BigLake catalogs. If this field is unset, or if `restrictedLocationsConfig.restricted_locations` is empty, all accessible locations are allowed. If `restrictedLocationsConfig.restricted_locations` is not empty, only locations in `defaultLocation` and `restrictedLocationsConfig.restricted_locations` are allowed. |
| `federated-catalog-options` | ``object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#FederatedCatalogOptions`)`` Optional. Configuration options for federated catalogs. |

## CredentialMode

The credential mode used for the catalog.

| Enums ||
|---|---|
| `CREDENTIAL_MODE_UNSPECIFIED` | Default value. This value is unused. |
| `CREDENTIAL_MODE_END_USER` | End user credentials, default. The authenticating user must have access to the catalog resources and the corresponding Google Cloud Storage files. |
| `CREDENTIAL_MODE_VENDED_CREDENTIALS` | Use credential vending. The authenticating user must have access to the catalog resources and the system will provide the caller with downscoped credentials to access the Google Cloud Storage files. All table operations in this mode would require `X-Iceberg-Access-Delegation` header with `vended-credentials` value included. System will generate a service account and the catalog administrator must grant the service account appropriate permissions. See: <https://github.com/apache/iceberg/blob/931865ecaf40a827f9081dddb675bf1c95c05461/open-api/rest-catalog-open-api.yaml#L1854> for more details. |

## CatalogType

Determines the catalog type.

| Enums ||
|---|---|
| `CATALOG_TYPE_UNSPECIFIED` | Default value. This value is unused. |
| `CATALOG_TYPE_GCS_BUCKET` | Google Cloud Storage bucket catalog type. |
| `CATALOG_TYPE_BIGLAKE` | BigLake catalog type. |
| `CATALOG_TYPE_FEDERATED` | Federated catalog type. |

## Replica

The replica of the Catalog.

| JSON representation |
|---|
| ``` { "region": string, "state": enum (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#State`) } ``` |

| Fields ||
|---|---|
| `region` | `string` Output only. The region of the replica. For example "us-east1" |
| `state` | ``enum (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#State`)`` Output only. The current state of the replica. |

## State

If the catalog is replicated to multiple regions, this enum describes the current state of the replica.

| Enums ||
|---|---|
| `STATE_UNKNOWN` | The replica state is unknown. |
| `STATE_PRIMARY` | The replica is the writable primary. |
| `STATE_PRIMARY_IN_PROGRESS` | The replica has been recently assigned as the primary, but not all namespaces are writeable yet. |
| `STATE_SECONDARY` | The replica is a read-only secondary replica. |

## RestrictedLocationsConfig

Configuration of location restrictions.

| JSON representation |
|---|
| ``` { "restricted-locations": [ string ] } ``` |

| Fields ||
|---|---|
| `restricted-locations[]` | `string` Optional. Additional Google Cloud Storage buckets and locations (e.g., `gs://my-other-bucket/...`) that are permitted for use by resources within a catalog. This field is currently only used for BigLake catalogs. If `restrictedLocations` is empty and unrestricted catalog creation is enabled, all accessible locations are allowed. Otherwise, only `defaultLocation` and locations in this list are allowed. |

## FederatedCatalogOptions

Configuration options for a federated catalog.

| JSON representation |
|---|
| ``` { "refresh-options": { object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshOptions`) }, "refresh-status": { object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshStatus`) }, // Union field `remote_catalog_info` can be only one of the following: "unity-catalog-info": { object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#UnityCatalogInfo`) }, "glue-catalog-info": { object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#GlueCatalogInfo`) }, "snowflake-catalog-info": { object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#SnowflakeCatalogInfo`) } // End of list of possible types for union field `remote_catalog_info`. "secret-name": string, "service-directory-name": string } ``` |

| Fields ||
|---|---|
| `refresh-options` | ``object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshOptions`)`` Optional. Refresh configuration. |
| `refresh-status` | ``object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshStatus`)`` Output only. The status of the background refresh operations. |
| Union field `remote_catalog_info`. Info specific to a remote Iceberg REST catalog. `remote_catalog_info` can be only one of the following: ||
| `unity-catalog-info` | ``object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#UnityCatalogInfo`)`` Optional. Info specific to a Unity Catalog by Databricks. |
| `glue-catalog-info` | ``object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#GlueCatalogInfo`)`` Optional. Info specific to an AWS Glue Catalog. |
| `snowflake-catalog-info` | ``object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#SnowflakeCatalogInfo`)`` Optional. Info specific to a Snowflake Catalog. |
| `secret-name` | `string` Optional. The secret resource name in Secret Manager, in the format `projects/{projectId}/locations/{location}/secrets/{secret_id}` or `projects/{projectId}/locations/{location}/secrets/{secret_id}/versions/{version_id}`. The project ID must match the catalog's project and location must match the catalog's location. If the version is not specified, the latest version will be used. This field is not used when `google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.UnityCatalogInfo.service_principal_application_id` or `google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.SnowflakeCatalogInfo.snowflake_role` is set. |
| `service-directory-name` | `string` Optional. The service directory resource name for routing traffic over a private network connection through Cross-Cloud Interconnect, in the format `projects/{projectId}/locations/{locationId}/namespaces/{namespace_id}/services/{serviceId}`. |

## UnityCatalogInfo

Unity Catalog info.

| JSON representation |
|---|
| ``` { "instance-name": string, "catalog-name": string, "service-principal-application-id": string } ``` |

| Fields ||
|---|---|
| `instance-name` | `string` Required. The instance name is the first part of the URL when logging into the Databricks deployment. For example, for a Databricks on Google Cloud workspace URL <https://1.1.Google Cloud.databricks.com>, the instance name is 1.1.Google Cloud.databricks.com. |
| `catalog-name` | `string` Required. The catalog name in Unity Catalog. |
| `service-principal-application-id` | `string` Optional. The application ID of the Databricks service principal that will be used to access the Unity Catalog in the OIDC authentication flow. |

## GlueCatalogInfo

AWS Glue Catalog info. We support regional AWS Glue default account catalog and S3 Table Buckets.

| JSON representation |
|---|
| ``` { "warehouse": string, "aws-region": string, "aws-role-arn": string } ``` |

| Fields ||
|---|---|
| `warehouse` | `string` Required. Immutable. The warehouse to connect to a regional AWS Glue Iceberg REST Catalog. For top level access, use the AWS account ID (e.g. 111222333444). For an S3 table bucket, the warehouse is of the form: 111222333444:s3tablescatalog/. The URL to access catalog will be <https://glue.{awsRegion}.amazonaws.com/iceberg/v1?warehouse=%7Bwarehouse%7D>. Must be non-empty and is immutable. |
| `aws-region` | `string` Required. Immutable. The AWS region of the Glue catalog to connect to. The region should be in the same geographical region and jurisdiction as the federated catalog. Must be non-empty and is immutable. |
| `aws-role-arn` | `string` Required. The AWS role ARN of the Glue catalog that the federated catalog will assume to access the catalog. Must be non-empty. Can be updated. |

## SnowflakeCatalogInfo

Snowflake Catalog info.

| JSON representation |
|---|
| ``` { "account-identifier": string, "warehouse": string, "snowflake-role": string } ``` |

| Fields ||
|---|---|
| `account-identifier` | `string` Required. The account identifier in Snowflake (See: <https://docs.snowflake.com/en/user-guide/admin-account-identifier)>. It is the prefix to log into your Snowflake deployment URL. For example: https://.snowflakecomputing.com. |
| `warehouse` | `string` Required. The warehouse to connect to in Snowflake REST Catalog. https://.snowflakecomputing.com/polaris/api/catalog/v1/config?warehouse=. This is the Snowflake database name containing the Iceberg metadata to be federated. Must be non-empty. |
| `snowflake-role` | `string` Optional. The specific Snowflake role name to request in the OAuth token scope (via session:role:$ROLE) for the Iceberg REST Catalog session. This role grants the Google Cloud BigLake service account the necessary permissions to interact with the Iceberg catalog, namespaces, and tables. Note: The role provided here must be the DEFAULT_ROLE or be granted to, the Snowflake service user mapped to the BigLake service account. |

## RefreshOptions

Refresh configuration.

| JSON representation |
|---|
| ``` { "refresh-schedule": { object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshSchedule`) }, "refresh-scope": { object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshScope`) } } ``` |

| Fields ||
|---|---|
| `refresh-schedule` | ``object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshSchedule`)`` Optional. Schedule defines if and when metadata refresh should be scheduled. |
| `refresh-scope` | ``object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs#RefreshScope`)`` Optional. Refresh scope configurations. |

## RefreshSchedule

Schedule defines if and when metadata refresh should be scheduled.

| JSON representation |
|---|
| ``` { "refresh-interval": string } ``` |

| Fields ||
|---|---|
| `refresh-interval` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#duration` format)`` Optional. The interval for refreshing metadata from the remote catalog. If unset or if the value is \<= 0, the background refresh will be disabled. If this field is updated for an existing federated catalog, the previous background refresh must complete before the new refresh interval will take effect. A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`. |

## RefreshScope

The scope defines a subset of namespaces to be refreshed.

| JSON representation |
|---|
| ``` { "namespace-filters": [ string ] } ``` |

| Fields ||
|---|---|
| `namespace-filters[]` | `string` Optional. Filters to determine which namespaces are included in the refresh process. - empty list means include all namespaces. - "\[namespaces\]" means include the specified namespaces. \['ns1', 'ns2'\] : Discover only namespaces 'ns1' and 'ns2'. The maximum number of namespace filters allowed is 32. |

## RefreshStatus

Remote catalog background refresh status.

| JSON representation |
|---|
| ``` { "start-time": string, "end-time": string, "status": { object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/Status`) } } ``` |

| Fields ||
|---|---|
| `start-time` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. When the catalog refresh has started, including in-progress refreshes. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `end-time` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. When the catalog refresh has ended, unset for in-progress refreshes. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `status` | ``object (`https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/Status`)`` Output only. The status of the last background refresh operation, unset for in-progress refreshes. |

| ## Methods ||
|---|---|
| ### `https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs/create` | Creates the Iceberg REST Catalog. |
| ### `https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs/delete` | Deletes the Iceberg REST Catalog. |
| ### `https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs/failover` | Failover the catalog to a new primary replica region. |
| ### `https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs/get` | Returns the Iceberg REST Catalog configuration options. |
| ### `https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs/list` | Lists the Iceberg REST Catalogs. |
| ### `https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs/patch` | Update the Iceberg REST Catalog configuration options. |