Configure data locality with locational endpoints

This page describes how to configure the Firestore client libraries to use a locational endpoint.

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

  • Global endpoint: By default, the 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 locational service endpoint in a location that's different from your database location.

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

Set a locational endpoint

The following examples show how to set a locational endpoint when you initialize a Firestore client. Setting a locational endpoint other than where your data resides might result in a PermissionDeniedError error.

Java

To authenticate to Firestore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 

 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 nam5-firestore.googleapis.com:443  .setHost(endpoint)  .build();  Firestore dbWithEndpoint = firestoreOptions.getService();  return dbWithEndpoint;  } }

Python

To authenticate to Firestore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 

ENDPOINT = "nam5-firestore.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)

Locational endpoint semantics

Firestore supports locational endpoints for both region and multi-region locations.

Use the following format to define locational endpoints:

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 Firestore locations.

Restrict global API endpoint usage

To help enforce the use of 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.

What's next