Method: iceberg.v1.restcatalog.extensions.projects.catalogs.failover

Failover the catalog to a new primary replica region.

HTTP request

POST https://biglake.googleapis.com/iceberg/v1/restcatalog/extensions/{name=projects/*/catalogs/*}:failover

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The name of the catalog in the form "projects/{projectId}/catalogs/{catalogId}"

Request body

The request body contains data with the following structure:

JSON representation 
{
  "primaryReplica": string,
  "validateOnly": boolean,
  "conditionalFailoverReplicationTime": string
}
Fields
primaryReplica

string

Required. The region being assigned as the new primary replica region. For example "us-east1". This must be one of the replica regions in the catalog's list of replicas marked as a "secondary".
validateOnly

boolean

Optional. If set, only validate the request, but do not perform the update. This can be used to inspect the replicationTime at any time, including before performing a fail-over.
conditionalFailoverReplicationTime

string (Timestamp format)

Optional. If unset, wait for all data from the source region to replicate to the new primary region before completing the failover, with no data loss (also called "soft failover"). If set, failover immediately, accepting the loss of any data committed in the source region after this timestamp, that has not yet replicated. If any data committed before this time has not replicated, the failover will not be performed and an error will be returned (also called "hard failover").

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".

Response body

Response message for catalogs.failover.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "replicationTime": string
}
Fields
replicationTime

string (Timestamp format)

Output only. The min timestamp for which all namespaces and table metadata have been replicated in the region specified as the new primaryReplica. Some resources may have been replicated more recently than this timestamp. If empty, the replica has just been created and has not yet been fully initialized. NOTE: When the Cloud Storage replication watermark is available, this will represent both catalog metadata and Cloud Storage data.

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".

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.