Configure data locality with regional endpoints

This page describes how to configure the Cloud Firestore client libraries to use a regional or multi-regional endpoint.

When you use Cloud Firestore client libraries, you can use any of the following endpoints:

  • Global endpoint: By default, the Cloud Firestore client libraries send API requests to a global service endpoint named firestore.googleapis.com. The global service endpoint routes the request to your database. During routing, a request might pass through a server in a location that's different from your database location.

  • Regional endpoint: A regional endpoint enforces restrictions ensuring that data is transmitted, stored and processed in a specified Google Cloud region. To ensure that the service endpoint processes your app's Cloud Firestore requests in the same region as your database, specify a regional endpoint in the client library.

  • Multi-regional endpoint: A multi-regional endpoint enforces restrictions ensuring that data is stored and processed in a specified multi-region. To ensure that the service endpoint processes your app's Cloud Firestore requests in the same multi-region as your database, specify a multi-regional endpoint in the client library.

Set a regional or multi-regional endpoint

The method for configuring a regional or multi-regional endpoint is the same: you provide the endpoint string when initializing the client library. The following examples show how to set the endpoint string using a regional endpoint (firestore.us-central1.rep.googleapis.com). To use a multi-regional endpoint, provide a multi-regional endpoint string corresponding to your database's location (for example, firestore.us.rep.googleapis.com for nam5).

Java


import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.firestore.Firestore;
import com.google.cloud.firestore.FirestoreOptions;


/**
 * Demonstrate how to set a regional endpoint.
 */
public class RegionalEndpointSnippets {

  /**
   * Create a client with a regional endpoint.
   **/
  public Firestore regionalEndpoint(String projectId, String endpoint) throws Exception {
    FirestoreOptions firestoreOptions =
        FirestoreOptions.newBuilder()
            .setProjectId(projectId)
            .setCredentials(GoogleCredentials.getApplicationDefault())
            // set endpoint like firestore.us-central1.rep.googleapis.com:443
            .setHost(endpoint)
            .build();
    Firestore dbWithEndpoint = firestoreOptions.getService();

    return dbWithEndpoint;
  }

}
RegionalEndpointSnippets.java

Python

ENDPOINT = "firestore.africa-south1.rep.googleapis.com"
client_options = ClientOptions(api_endpoint=ENDPOINT)
db = firestore.Client(client_options=client_options)

cities_query = db.collection("cities").limit(2).get()
for r in cities_query:
    print(r)
snippets.py

Regional and multi-regional endpoint semantics

Regional Endpoints (REP):

Cloud Firestore supports regional endpoints for the regional locations listed here Cloud Firestore locations.

Use the following format to define regional endpoints:

Java

  firestore.REGION_NAME.rep.googleapis.com:443

Make sure that the port number is defined along with the endpoint.

Python

  firestore.REGION_NAME.rep.googleapis.com

Go

  firestore.REGION_NAME.rep.googleapis.com:443

Make sure that the port number is defined along with the endpoint.

Replace REGION_NAME with the name of a regional hostname.

Some examples of hostnames are:

  • firestore.us-central1.rep.googleapis.com
  • firestore.europe-west1.rep.googleapis.com

Multi-regional Endpoints (MREP)

For multi-regional endpoints, use us for locations nam5 and nam7, and eu for location eur3 (see Multi-regional locations).

Java

  firestore.us.rep.googleapis.com:443
  firestore.eu.rep.googleapis.com:443

Make sure that the port number is defined along with the endpoint.

Python

  firestore.us.rep.googleapis.com
  firestore.eu.rep.googleapis.com

Go

  firestore.us.rep.googleapis.com:443
  firestore.eu.rep.googleapis.com:443

Make sure that the port number is defined along with the endpoint.

Limitations

Locational Endpoints (Deprecated)

Locational endpoints are now deprecated. Use regional or multi-regional endpoints instead.

Cloud Firestore previously supported locational endpoints with the following format:

Java

  REGION_NAME-firestore.googleapis.com:443

Make sure that the port number is defined along with the endpoint.

Python

  REGION_NAME-firestore.googleapis.com

Go

  REGION_NAME-firestore.googleapis.com:443

Make sure that the port number is defined along with the endpoint.

Replace REGION_NAME with the name of a regional or multi-regional hostnames.

Some examples of hostnames are:

  • eur3-firestore.googleapis.com
  • nam5-firestore.googleapis.com
  • europe-west6-firestore.googleapis.com
  • asia-northeast2-firestore.googleapis.com

For a complete list of multi-regional and regional hostnames, see Cloud Firestore locations.

Restrict global API endpoint usage

To help enforce the use of regional and multi-regional endpoints, use the constraints/gcp.restrictEndpointUsage organization policy constraint to block requests to the global API endpoint. For more information, see Restricting endpoint usage.