v2026.1 STS Stable release with standard-term support v2025.2 LTS Stable release with long-term support v2025.1 STS Stable release with standard-term support v2024.2 LTS Stable release with long-term support Unsupported versions

CREATE TABLESPACE

Synopsis

Use the CREATE TABLESPACE statement to create a tablespace in the cluster. It defines the tablespace name and tablespace properties.

Syntax

create_tablespace ::= CREATE TABLESPACE tablespace_name 
                      [ WITH ( 
                        { 'tablespace_option' = value 
                        [ ,'tablespace_option'= ... ] } ) ]

create_tablespace

CREATETABLESPACEtablespace_nameWITH(tablespace_option=value,tablespace_option=value)

Semantics

  • Create a tablespace with tablespace_name. If qualified_name already exists in the cluster, an error will be raised.
  • YSQL tablespaces allow administrators to specify the number of replicas for a table or index, and how they can be distributed across a set of clouds, regions, and zones in a geo-distributed deployment.

tablespace_option

replica_placement

replica_placement is a JSON object that places the replicas of tables and indexes in this tablespace.

  • num_replicas is the replication factor. It is required and must be a positive integer.
  • placement_blocks is an array of placement blocks. Each block requires cloud, region, zone, and min_num_replicas. No two blocks may name the same cloud, region, and zone. CREATE TABLESPACE rejects a duplicate block.
    • min_num_replicas is the minimum number of replicas in that cloud, region, and zone. It must be greater than 0. The sum across blocks cannot exceed num_replicas.
  • region and zone accept * for any region or any zone. A * region requires a * zone. cloud must name a cloud.
  • leader_preference is an optional positive integer. 1 is the most preferred zone for tablet leaders. Values that are set must form a contiguous sequence starting at 1. Zones that share a value split leaders evenly. Zones that omit the field are least preferred.

read_replica_placement

EA read_replica_placement is a JSON object for copies on a read replica cluster. It uses the same fields as replica_placement. A tablespace has one read-replica placement. leader_preference applies only to replica_placement.

placement_uuid is the placement ID of the read replica cluster. When the cluster has one read-replica cluster, omit placement_uuid and that cluster's placement ID is used. When the cluster has more than one, set placement_uuid to the cluster you want. If you omit it, CREATE TABLESPACE still succeeds, and tablets in the tablespace follow the cluster placement policy. Obtain the ID with get-universe-config.

Examples

See Tablespaces and Row Level Geo Partitioning for full guides.

See also