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