Geo-partitioning overview

This page introduces and explains how geo-partitioning work in Spanner.

Spanner offers regional and multi-regional instance configurations , which let you replicate your data across geographic locations. Geo-partitioning lets you further segment and store rows in your database table across different instance configurations.

Benefits and use cases

The benefits of geo-partitioning include the following:

  • Reduces write and strong read latency by letting you store your data in the same geographical location as your query.

  • Optimizes costs for asymmetrical global workloads (for example, using a us-central1 partition with 10 nodes and a asia-south1 partition with 2 nodes).

The following are common use cases:

  • User-related data: Geo-partitioning user-related data to process and store data in a region that is closest to the user.

  • Localized data: Location-specific information like traffic and special events.

How geo-partitioning works

All Spanner instances have a main instance partition that is called the default partition. If you don't create additional partitions, all database objects are stored in the default partition, which is in the same location as your instance configuration.

If you want to partition the data in a database, you must create additional partitions in your instance. These user-created partitions have their own configuration (either regional or multi-region) and node count. Create your database like you would normally; your database can interact with the partitions that were created in the same instance. Then, create placements in your database that are associated with the partition. Finally, you can create placement tables that have a placement key attribute. You must use the placement key in your DML statements to specify which partition the row data resides in. If you create non-placement tables in your database, Spanner stores that data in the default partition.

For instructions on how to use partitions, see create and manage partitions .

Important considerations

Consider the following before creating your partitions, placements, and placement tables:

  • Partition location: Carefully select partition regions that provide the most benefits for your application.

    Although you can create partitions in an instance with a regional instance configuration, we recommend that you create partitions in an instance with a multi-region instance configuration so that the default partition location is also in a multi-region configuration.

    Moreover, select a multi-region default partition location that has read-write and read-only regions that cover all jurisdictions required by your application. Then, create additional partitions (which can be regional) with leader regions that match the regions in the multi-region default partition.

  • Number of partitions: Too many partitions can lead to overhead, while too few might not offer enough benefits. You can create a maximum of ten partitions per instance.

Limitations

The following limitations apply during the Preview release and are subject to change or removal upon the GA release or after:

  • You can't create an instance partition using a dual-region configuration .
  • For each partition, the compute capacity must be at least one node (1000 processing units).
  • For a given instance, you can't create more than one instance partition that uses the same base instance configuration. For example, within test-instance , you can't create two partitions, partition-1 and partition-2 that both use us-central1 as the partition configuration.
  • For every node in your partition, you can place a maximum of 100 million placement rows. You can view the number of placement rows that have been placed in each of your partitions on the Partitions page of the Google Cloud console.
  • For every node in your destination instance partition, Spanner can move around 10 placement rows per second.
  • You can't create partitions in free trial instances or granular-sized instances smaller than one node (1000 processing units).
  • You can't create backups for instances with partitions.
  • You can't use customer-managed encryption keys for instances with partitions.
  • You can't create instance partitions in an instance with managed autoscaler enabled.
  • You can't move the partition to a different instance configuration.
  • You can't move an instance that has partitions. (You can move individual rows into different partitions so you don't need to move the instance.)
  • Using partitions doesn't guarantee compliance and regulatory requirements.
  • Change streams don't support partitioned data.
  • To use geo-partitioning, you must create a new, empty database and set the opt_in_dataplacement_preview option to true . For more information, see Create and manage partitions .
  • If you use an INSERT or DELETE DML statement for a placement table, that statement must be the only statement in the transaction .

Access control with IAM

You need to have the spanner.instancePartitions.create , spanner.instancePartitions.update , and spanner.instancePartitions.delete permissions to create and manage partitions. If you only need to view the partitions, you need to have the spanner.instancePartitions.list or spanner.instancePartitions.get permission. For more information, see IAM overview .

For information on how to grant Spanner IAM permissions, see Apply IAM permissions .

Monitoring

Spanner provides several metrics to help you monitor your partitions. After you've created an additional partition, you see an additional drop-down filter for Partitions on the System insights page in the Google Cloud console. The default selection is to show metrics for All partitions. You can use the drop-down to filter the metrics for a specific partition.

To learn more about monitoring your Spanner resources, see Monitor instances with Cloud Monitoring .

Pricing

There is no additional charge for using geo-partitioning. You are charged the standard Spanner pricing for the amount of compute capacity that your instance uses and the amount of storage that your database uses.

For more information, see Spanner pricing .

What's next