---
title: "CREATE TABLESPACE"
url: "https://docs.yugabyte.com/stable/api/ysql/the-sql-language/statements/ddl_create_tablespace/"
---

# CREATE TABLESPACE

Use the CREATE TABLESPACE statement to create a tablespace in the cluster.

## Synopsis

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

## Syntax

- [![Grammar Icon](/icons/file-lines.svg)Grammar](#grammar-1)
- [![Diagram Icon](/icons/diagram.svg)Diagram](#diagram-1)

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

#### create\_tablespace

CREATETABLESPACE[tablespace\_name](/stable/api/ysql/syntax_resources/grammar_diagrams#tablespace-name)WITH(tablespace\_option=[value](/stable/api/ysql/syntax_resources/grammar_diagrams#value),tablespace\_option=[value](/stable/api/ysql/syntax_resources/grammar_diagrams#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`.

<!--THE END-->

- `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](/stable/releases/versioning/#feature-maturity) `read_replica_placement` is a JSON object for copies on a [read replica](/stable/explore/multi-region-deployments/read-replicas-ysql/ "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](/stable/admin/yb-admin/#add-read-replica-placement-info "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](/stable/admin/yb-admin/#get-universe-config "get-universe-config").

## Examples

See [Tablespaces](/stable/explore/going-beyond-sql/tablespaces/ "Tablespaces") and [Row Level Geo Partitioning](/stable/explore/multi-region-deployments/row-level-geo-partitioning/ "Row Level Geo Partitioning") for full guides.

## See also

- [ALTER TABLESPACE](/stable/api/ysql/the-sql-language/statements/ddl_alter_tablespace "ALTER TABLESPACE")
- [DROP TABLESPACE](/stable/api/ysql/the-sql-language/statements/ddl_drop_tablespace "DROP TABLESPACE")
- [CREATE TABLE](/stable/api/ysql/the-sql-language/statements/ddl_create_table "CREATE TABLE")
- [ALTER TABLE](/stable/api/ysql/the-sql-language/statements/ddl_alter_table "ALTER TABLE")