Configure data locality with regional endpoints

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

When you use Firestore client libraries, you can use any 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 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 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 transmitted, stored and processed in a specified Google Cloud multi-region. To ensure that the service endpoint processes your app's 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).

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;
  }

}

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)

Regional and multi-regional endpoint semantics

Regional endpoints:

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

Use the following format to define regional endpoints:

    firestore.REGION_NAME.rep.googleapis.com:443

    firestore.REGION_NAME.rep.googleapis.com

    firestore.REGION_NAME.rep.googleapis.com:443

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

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

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

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

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

Limitations

• Regional and multi-regional endpoints don't support real-time listeners.

Locational Endpoints (Deprecated)

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

Firestore previously supported locational endpoints with the following format:

  REGION_NAME-firestore.googleapis.com:443

  REGION_NAME-firestore.googleapis.com

  REGION_NAME-firestore.googleapis.com:443

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 and multi-regional endpoints, use the constraints/gcp.restrictEndpointUsage organization policy constraint to block requests to the global API endpoint. For more information, see Restrict endpoint usage.

What's next

• Learn about the Firestore data model.
• Best practices for using Firestore.