diff --git a/src/backend/distributed/README.md b/src/backend/distributed/README.md index ff92e94c3..437ae76b1 100644 --- a/src/backend/distributed/README.md +++ b/src/backend/distributed/README.md @@ -14,7 +14,7 @@ The purpose of this document is to provide comprehensive technical documentation There are several types of Citus tables: -**Distributed tables** are created using SELECT create_distributed_table(..). They have a distribution column and for each row the value in the distribution column determines which to shard the row is assigned. There are 3 different partitioning schemes for distributed tables, though only the first is supported: +**Distributed tables** are created using `SELECT create_distributed_table('table_name', 'distribution_column')`. They have a distribution column and for each row the value in the distribution column determines which to shard the row is assigned. There are 3 different partitioning schemes for distributed tables, though only the first is supported: - Hash-distributed tables have a range of hash values in shardminvalue/shardmaxvalue in pg_dist_shard - Range-distributed tables (deprecated) have shards with a distinct range of values in pg_dist_shard @@ -28,9 +28,9 @@ Shards can be replicated (deprecated), in which case they have multiple shard pl Writes to a reference table are performed using 2PC and use aggressive locking to avoid diverging. -**Single shard tables** are a special type of distributed table without a distribution column and with a single shard. When using schema-based sharding, tables created in a distributed schema automatically become single shard tables. Single shard tables can be co-located with each other, but not replicated. +**Single shard tables** are a special type of distributed table without a distribution column and with a single shard. When using schema-based sharding, tables created in a distributed schema automatically become single shard tables. Single shard tables can be co-located with each other, but not replicated. Single shard tables can be explicitly created using `SELECT create_distributed_table('table_name', NULL);`, though are meant to be auto-generated by schema-based sharding. -**Citus local tables**: A single shard table that can only be placed on the coordinator and are primarily used as a drop-in replacement for regular PostgreSQL tables when creating foreign keys to/from reference tables. All Citus local tables are implicitly co-located with each other, but do not have a co-location ID. +**Citus local tables**: A single shard table that can only be placed on the coordinator and are primarily used as a drop-in replacement for regular PostgreSQL tables when creating foreign keys to/from reference tables. All Citus local tables are implicitly co-located with each other, but do not have a co-location ID. Citus local tables can be explicitly created using `SELECT citus_add_local_table_to_metadata('table_name');`, though are meant to be auto-generated by foreign keys. All Citus table types have the notion of a “shard”, though in many cases there is only a single shard. @@ -42,7 +42,7 @@ All Citus table types have the notion of a “shard”, though in many cases the **Shard placement**: The assignment of a shard to a node group. There can be multiple placements of the same shard if the table is replicated (e.g. reference tables). -**Shard placement group**: The assignment of a shard to a node group must be the same for all shards in a shard group, since those are always co-located. We’ll refer to the group of placements of a shard group as a shard placement group. A single shard group can have multiple shard placement groups. +**Shard group placement**: The assignment of a shard to a node group must be the same for all shards in a shard group, since those are always co-located. We’ll refer to the group of placements of a shard group as a shard group placement. **Node**: A single PostgreSQL/Citus server listed in pg_dist_node and added via SELECT citus_add_node(..).