Repository: pg-sharding/spqr
Pull request #1102: Add reference and replicated table docs
Author: login: Denchick
Created: 2025-03-28T11:37:54Z | Merged: 2025-03-28T13:23:12Z



Diff:
diff --git a/docs/mint.json b/docs/mint.json
index 85327e350..308f966d5 100644
--- a/docs/mint.json
+++ b/docs/mint.json
@@ -90,6 +90,8 @@
                         "welcome/get_started",
                         "sharding/ranged",
                         "sharding/hashed",
+                        "sharding/sharded_tables",
+                        "sharding/reference_tables",
                         {
                             "group": "Cluster Components",
                             "pages": [
diff --git a/docs/sharding/reference_tables.mdx b/docs/sharding/reference_tables.mdx
new file mode 100644
index 000000000..cb5f89bba
--- /dev/null
+++ b/docs/sharding/reference_tables.mdx
@@ -0,0 +1,79 @@
+---
+title: 'Reference Tables'
+---
+
+A reference table is a table that is fully replicated across all shards instead of being divided into separate partitions. This allows **every shard to have a local copy of the table**, reducing network overhead and ensuring fast access to frequently used data.
+
+Reference tables are useful when you need:
+
+- Consistent access to shared data across all shards.
+- Fast lookups without cross-shard queries.
+- Integrity constraints on small tables used across different parts of an application.
+
+## Examples
+
+Some typical use cases for reference tables include:
+
+- **eCommerce**: Sales tax rates apply to all stores.
+- **Common codes**: A table with country codes and region names.
+- **Roles**: A system-wide list of roles and permissions.
+- **Finance**: Exchange rates.
+- **Global settings**: Settings or feature flags.
+- **SaaS**: A table defining different subscription tiers, their pricing, and feature sets.
+
+## How to use it?
+
+To create a reference table, use the SPQR administrative console:
+
+```sql
+\c spqr-console
+CREATE REFERENCE TABLE tax_rates;
+         attach table          
+-------------------------------
+ relation name   -> tax_rates
+ distribution id -> REPLICATED
+(2 rows)
+```
+
+Then, create the table and insert data:
+
+```sql
+\c ordersdb
+CREATE TABLE tax_rates (
+    country_code VARCHAR(2),
+    state_code VARCHAR(2),
+    tax_rate NUMERIC(5, 2),
+    tax_category VARCHAR(50)
+);
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+COPY tax_rates FROM 'test_tax_rates.csv' DELIMITER '\t';
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+```
+
+Verify replication:
+
+```sql
+SELECT * FROM tax_rates /* __spqr__execute_on: sh1 */;
+NOTICE: send query to shard(s) : sh1
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
+ AU           |            |   10.00  | GST
+ IN           |            |   18.00  | GST
+(6 rows)
+
+SELECT * FROM tax_rates /* __spqr__execute_on: sh2 */;
+NOTICE: send query to shard(s) : sh2
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
+ AU           |            |   10.00  | GST
+ IN           |            |   18.00  | GST
+(6 rows)
+```
\ No newline at end of file
diff --git a/docs/sharding/sharded_tables.mdx b/docs/sharding/sharded_tables.mdx
new file mode 100644
index 000000000..49e80bd92
--- /dev/null
+++ b/docs/sharding/sharded_tables.mdx
@@ -0,0 +1,26 @@
+---
+title: 'Sharded Tables'
+---
+
+Sharded tables, also known as **replicated tables** or **distributed tables**, are tables that are distributed across multiple shards, allowing each shard to store a portion of the data.
+
+Sharded tables are useful when you need or have:
+
+- Distributed data across multiple shards for performance and scalability.
+- Large datasets that need to be partitioned.
+- High availability and fault tolerance by spreading data across multiple servers.
+- Certain types of queries isolated to specific shards, reducing the query load on other parts of the system.
+
+## Examples
+
+Some typical use cases for sharded tables include:
+
+- **eCommerce**: Product catalogs, where each product has information about categories, descriptions, and prices, which can be sharded based on product IDs.
+- **Social Media**: User data and posts, sharded by user ID.
+- **Finance**: Transaction records, sharded by account number or transaction ID.
+- **IoT**: Data from devices, sharded by device ID or geographical region.
+- **Logs and Analytics**: Event logs and analytics data, sharded by date or region.
+
+## How to use it?
+
+See the [Get Started](/welcome/get_started) guide.
\ No newline at end of file


Reviews:
user: login: github-advanced-security[bot]
state: COMMENTED
author_association: NONE
submitted_at: 2025-03-28T11:39:06Z
user: login: github-advanced-security[bot]
state: COMMENTED
author_association: NONE
submitted_at: 2025-03-28T13:19:35Z
user: login: rkhapov
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-28T13:21:53Z

Review comments:
diff_hunk: @@ -0,0 +1,74 @@
+---
+title: 'Reference Tables'
+---
+
+A reference table is a table that is fully replicated across all shards instead of being divided into separate partitions. This allows **every shard to have a local copy of the table**, reducing network overhead and ensuring fast access to frequently used data.
+
+Reference tables are useful when you need:
+
+- Consistent access to shared data across all shards.
+- Fast lookups without cross-shard queries.
+- Integrity constraints on small tables used across different parts of an application.
+
+## Examples
+
+Some typical use cases for reference tables include:
+
+- **eCommerce**: sales tax rates apply to all stores.
+- **Common codes**: a table with country codes and region names.
+- **Roles**: a system-wide list of roles and permissions.
+- **Finance**: Exchange rates.
+- **Global settings**: settings or feature flags.
+- **A SaaS platform**: a table defining different subscription tiers, their pricing, and feature sets.
+
+## How to use it?
+
+To create a reference table, use the SPQR administrative console:
+
+```sql
+\c spqr-console
+CREATE REFERENCE TABLE tax_rates;
+         attach table          
+-------------------------------
+ relation name   -> tax_rates
+ distribution id -> REPLICATED
+(2 rows)
+```
+
+Then, create the table and insert data:
+
+```sql
+\c ordersdb
path: docs/sharding/reference.mdx
user: login: github-advanced-security[bot]
body: ## Unrecognized Spelling

[ordersdb](#security-tab) is not a recognized word. \(unrecognized-spelling\)

[Show more details](https://github.com/pg-sharding/spqr/security/code-scanning/6680)
created_at: 2025-03-28T11:39:05Z
author_association: NONE
diff_hunk: @@ -0,0 +1,74 @@
+---
+title: 'Reference Tables'
+---
+
+A reference table is a table that is fully replicated across all shards instead of being divided into separate partitions. This allows **every shard to have a local copy of the table**, reducing network overhead and ensuring fast access to frequently used data.
+
+Reference tables are useful when you need:
+
+- Consistent access to shared data across all shards.
+- Fast lookups without cross-shard queries.
+- Integrity constraints on small tables used across different parts of an application.
+
+## Examples
+
+Some typical use cases for reference tables include:
+
+- **eCommerce**: sales tax rates apply to all stores.
+- **Common codes**: a table with country codes and region names.
+- **Roles**: a system-wide list of roles and permissions.
+- **Finance**: Exchange rates.
+- **Global settings**: settings or feature flags.
+- **A SaaS platform**: a table defining different subscription tiers, their pricing, and feature sets.
+
+## How to use it?
+
+To create a reference table, use the SPQR administrative console:
+
+```sql
+\c spqr-console
+CREATE REFERENCE TABLE tax_rates;
+         attach table          
+-------------------------------
+ relation name   -> tax_rates
+ distribution id -> REPLICATED
+(2 rows)
+```
+
+Then, create the table and insert data:
+
+```sql
+\c ordersdb
+CREATE TABLE tax_rates(i int, j int);
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+COPY tax_rates FROM 'test_tax_rates.csv' DELIMITER '\t';
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+```
+
+Verify replication:
+
+```sql
+TABLE tax_rates /* __spqr__execute_on: sh1 */;
+NOTICE: send query to shard(s) : sh1
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
path: docs/sharding/reference.mdx
user: login: github-advanced-security[bot]
body: ## Unrecognized Spelling

[GST](#security-tab) is not a recognized word. \(unrecognized-spelling\)

[Show more details](https://github.com/pg-sharding/spqr/security/code-scanning/6681)
created_at: 2025-03-28T11:39:05Z
author_association: NONE
diff_hunk: @@ -0,0 +1,74 @@
+---
+title: 'Reference Tables'
+---
+
+A reference table is a table that is fully replicated across all shards instead of being divided into separate partitions. This allows **every shard to have a local copy of the table**, reducing network overhead and ensuring fast access to frequently used data.
+
+Reference tables are useful when you need:
+
+- Consistent access to shared data across all shards.
+- Fast lookups without cross-shard queries.
+- Integrity constraints on small tables used across different parts of an application.
+
+## Examples
+
+Some typical use cases for reference tables include:
+
+- **eCommerce**: sales tax rates apply to all stores.
+- **Common codes**: a table with country codes and region names.
+- **Roles**: a system-wide list of roles and permissions.
+- **Finance**: Exchange rates.
+- **Global settings**: settings or feature flags.
+- **A SaaS platform**: a table defining different subscription tiers, their pricing, and feature sets.
+
+## How to use it?
+
+To create a reference table, use the SPQR administrative console:
+
+```sql
+\c spqr-console
+CREATE REFERENCE TABLE tax_rates;
+         attach table          
+-------------------------------
+ relation name   -> tax_rates
+ distribution id -> REPLICATED
+(2 rows)
+```
+
+Then, create the table and insert data:
+
+```sql
+\c ordersdb
+CREATE TABLE tax_rates(i int, j int);
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+COPY tax_rates FROM 'test_tax_rates.csv' DELIMITER '\t';
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+```
+
+Verify replication:
+
+```sql
+TABLE tax_rates /* __spqr__execute_on: sh1 */;
+NOTICE: send query to shard(s) : sh1
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
+ AU           |            |   10.00  | GST
path: docs/sharding/reference.mdx
user: login: github-advanced-security[bot]
body: ## Unrecognized Spelling

[GST](#security-tab) is not a recognized word. \(unrecognized-spelling\)

[Show more details](https://github.com/pg-sharding/spqr/security/code-scanning/6682)
created_at: 2025-03-28T11:39:05Z
author_association: NONE
diff_hunk: @@ -0,0 +1,74 @@
+---
+title: 'Reference Tables'
+---
+
+A reference table is a table that is fully replicated across all shards instead of being divided into separate partitions. This allows **every shard to have a local copy of the table**, reducing network overhead and ensuring fast access to frequently used data.
+
+Reference tables are useful when you need:
+
+- Consistent access to shared data across all shards.
+- Fast lookups without cross-shard queries.
+- Integrity constraints on small tables used across different parts of an application.
+
+## Examples
+
+Some typical use cases for reference tables include:
+
+- **eCommerce**: sales tax rates apply to all stores.
+- **Common codes**: a table with country codes and region names.
+- **Roles**: a system-wide list of roles and permissions.
+- **Finance**: Exchange rates.
+- **Global settings**: settings or feature flags.
+- **A SaaS platform**: a table defining different subscription tiers, their pricing, and feature sets.
+
+## How to use it?
+
+To create a reference table, use the SPQR administrative console:
+
+```sql
+\c spqr-console
+CREATE REFERENCE TABLE tax_rates;
+         attach table          
+-------------------------------
+ relation name   -> tax_rates
+ distribution id -> REPLICATED
+(2 rows)
+```
+
+Then, create the table and insert data:
+
+```sql
+\c ordersdb
+CREATE TABLE tax_rates(i int, j int);
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+COPY tax_rates FROM 'test_tax_rates.csv' DELIMITER '\t';
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+```
+
+Verify replication:
+
+```sql
+TABLE tax_rates /* __spqr__execute_on: sh1 */;
+NOTICE: send query to shard(s) : sh1
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
+ AU           |            |   10.00  | GST
+ IN           |            |   18.00  | GST
path: docs/sharding/reference.mdx
user: login: github-advanced-security[bot]
body: ## Unrecognized Spelling

[GST](#security-tab) is not a recognized word. \(unrecognized-spelling\)

[Show more details](https://github.com/pg-sharding/spqr/security/code-scanning/6683)
created_at: 2025-03-28T11:39:05Z
author_association: NONE
diff_hunk: @@ -0,0 +1,74 @@
+---
+title: 'Reference Tables'
+---
+
+A reference table is a table that is fully replicated across all shards instead of being divided into separate partitions. This allows **every shard to have a local copy of the table**, reducing network overhead and ensuring fast access to frequently used data.
+
+Reference tables are useful when you need:
+
+- Consistent access to shared data across all shards.
+- Fast lookups without cross-shard queries.
+- Integrity constraints on small tables used across different parts of an application.
+
+## Examples
+
+Some typical use cases for reference tables include:
+
+- **eCommerce**: sales tax rates apply to all stores.
+- **Common codes**: a table with country codes and region names.
+- **Roles**: a system-wide list of roles and permissions.
+- **Finance**: Exchange rates.
+- **Global settings**: settings or feature flags.
+- **A SaaS platform**: a table defining different subscription tiers, their pricing, and feature sets.
+
+## How to use it?
+
+To create a reference table, use the SPQR administrative console:
+
+```sql
+\c spqr-console
+CREATE REFERENCE TABLE tax_rates;
+         attach table          
+-------------------------------
+ relation name   -> tax_rates
+ distribution id -> REPLICATED
+(2 rows)
+```
+
+Then, create the table and insert data:
+
+```sql
+\c ordersdb
+CREATE TABLE tax_rates(i int, j int);
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+COPY tax_rates FROM 'test_tax_rates.csv' DELIMITER '\t';
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+```
+
+Verify replication:
+
+```sql
+TABLE tax_rates /* __spqr__execute_on: sh1 */;
+NOTICE: send query to shard(s) : sh1
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
+ AU           |            |   10.00  | GST
+ IN           |            |   18.00  | GST
+(6 rows)
+
+TABLE tax_rates /* __spqr__execute_on: sh2 */;
+NOTICE: send query to shard(s) : sh2
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
path: docs/sharding/reference.mdx
user: login: github-advanced-security[bot]
body: ## Unrecognized Spelling

[GST](#security-tab) is not a recognized word. \(unrecognized-spelling\)

[Show more details](https://github.com/pg-sharding/spqr/security/code-scanning/6684)
created_at: 2025-03-28T11:39:05Z
author_association: NONE
diff_hunk: @@ -0,0 +1,74 @@
+---
+title: 'Reference Tables'
+---
+
+A reference table is a table that is fully replicated across all shards instead of being divided into separate partitions. This allows **every shard to have a local copy of the table**, reducing network overhead and ensuring fast access to frequently used data.
+
+Reference tables are useful when you need:
+
+- Consistent access to shared data across all shards.
+- Fast lookups without cross-shard queries.
+- Integrity constraints on small tables used across different parts of an application.
+
+## Examples
+
+Some typical use cases for reference tables include:
+
+- **eCommerce**: sales tax rates apply to all stores.
+- **Common codes**: a table with country codes and region names.
+- **Roles**: a system-wide list of roles and permissions.
+- **Finance**: Exchange rates.
+- **Global settings**: settings or feature flags.
+- **A SaaS platform**: a table defining different subscription tiers, their pricing, and feature sets.
+
+## How to use it?
+
+To create a reference table, use the SPQR administrative console:
+
+```sql
+\c spqr-console
+CREATE REFERENCE TABLE tax_rates;
+         attach table          
+-------------------------------
+ relation name   -> tax_rates
+ distribution id -> REPLICATED
+(2 rows)
+```
+
+Then, create the table and insert data:
+
+```sql
+\c ordersdb
+CREATE TABLE tax_rates(i int, j int);
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+COPY tax_rates FROM 'test_tax_rates.csv' DELIMITER '\t';
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+```
+
+Verify replication:
+
+```sql
+TABLE tax_rates /* __spqr__execute_on: sh1 */;
+NOTICE: send query to shard(s) : sh1
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
+ AU           |            |   10.00  | GST
+ IN           |            |   18.00  | GST
+(6 rows)
+
+TABLE tax_rates /* __spqr__execute_on: sh2 */;
+NOTICE: send query to shard(s) : sh2
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
+ AU           |            |   10.00  | GST
path: docs/sharding/reference.mdx
user: login: github-advanced-security[bot]
body: ## Unrecognized Spelling

[GST](#security-tab) is not a recognized word. \(unrecognized-spelling\)

[Show more details](https://github.com/pg-sharding/spqr/security/code-scanning/6685)
created_at: 2025-03-28T11:39:06Z
author_association: NONE
diff_hunk: @@ -0,0 +1,74 @@
+---
+title: 'Reference Tables'
+---
+
+A reference table is a table that is fully replicated across all shards instead of being divided into separate partitions. This allows **every shard to have a local copy of the table**, reducing network overhead and ensuring fast access to frequently used data.
+
+Reference tables are useful when you need:
+
+- Consistent access to shared data across all shards.
+- Fast lookups without cross-shard queries.
+- Integrity constraints on small tables used across different parts of an application.
+
+## Examples
+
+Some typical use cases for reference tables include:
+
+- **eCommerce**: sales tax rates apply to all stores.
+- **Common codes**: a table with country codes and region names.
+- **Roles**: a system-wide list of roles and permissions.
+- **Finance**: Exchange rates.
+- **Global settings**: settings or feature flags.
+- **A SaaS platform**: a table defining different subscription tiers, their pricing, and feature sets.
+
+## How to use it?
+
+To create a reference table, use the SPQR administrative console:
+
+```sql
+\c spqr-console
+CREATE REFERENCE TABLE tax_rates;
+         attach table          
+-------------------------------
+ relation name   -> tax_rates
+ distribution id -> REPLICATED
+(2 rows)
+```
+
+Then, create the table and insert data:
+
+```sql
+\c ordersdb
path: docs/sharding/reference_tables.mdx
user: login: github-advanced-security[bot]
body: ## Unrecognized Spelling

[ordersdb](#security-tab) is not a recognized word. \(unrecognized-spelling\)

[Show more details](https://github.com/pg-sharding/spqr/security/code-scanning/6690)
created_at: 2025-03-28T13:19:34Z
author_association: NONE
diff_hunk: @@ -0,0 +1,74 @@
+---
+title: 'Reference Tables'
+---
+
+A reference table is a table that is fully replicated across all shards instead of being divided into separate partitions. This allows **every shard to have a local copy of the table**, reducing network overhead and ensuring fast access to frequently used data.
+
+Reference tables are useful when you need:
+
+- Consistent access to shared data across all shards.
+- Fast lookups without cross-shard queries.
+- Integrity constraints on small tables used across different parts of an application.
+
+## Examples
+
+Some typical use cases for reference tables include:
+
+- **eCommerce**: sales tax rates apply to all stores.
+- **Common codes**: a table with country codes and region names.
+- **Roles**: a system-wide list of roles and permissions.
+- **Finance**: Exchange rates.
+- **Global settings**: settings or feature flags.
+- **A SaaS platform**: a table defining different subscription tiers, their pricing, and feature sets.
+
+## How to use it?
+
+To create a reference table, use the SPQR administrative console:
+
+```sql
+\c spqr-console
+CREATE REFERENCE TABLE tax_rates;
+         attach table          
+-------------------------------
+ relation name   -> tax_rates
+ distribution id -> REPLICATED
+(2 rows)
+```
+
+Then, create the table and insert data:
+
+```sql
+\c ordersdb
+CREATE TABLE tax_rates(i int, j int);
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+COPY tax_rates FROM 'test_tax_rates.csv' DELIMITER '\t';
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+```
+
+Verify replication:
+
+```sql
+TABLE tax_rates /* __spqr__execute_on: sh1 */;
+NOTICE: send query to shard(s) : sh1
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
path: docs/sharding/reference_tables.mdx
user: login: github-advanced-security[bot]
body: ## Unrecognized Spelling

[GST](#security-tab) is not a recognized word. \(unrecognized-spelling\)

[Show more details](https://github.com/pg-sharding/spqr/security/code-scanning/6691)
created_at: 2025-03-28T13:19:34Z
author_association: NONE
diff_hunk: @@ -0,0 +1,74 @@
+---
+title: 'Reference Tables'
+---
+
+A reference table is a table that is fully replicated across all shards instead of being divided into separate partitions. This allows **every shard to have a local copy of the table**, reducing network overhead and ensuring fast access to frequently used data.
+
+Reference tables are useful when you need:
+
+- Consistent access to shared data across all shards.
+- Fast lookups without cross-shard queries.
+- Integrity constraints on small tables used across different parts of an application.
+
+## Examples
+
+Some typical use cases for reference tables include:
+
+- **eCommerce**: sales tax rates apply to all stores.
+- **Common codes**: a table with country codes and region names.
+- **Roles**: a system-wide list of roles and permissions.
+- **Finance**: Exchange rates.
+- **Global settings**: settings or feature flags.
+- **A SaaS platform**: a table defining different subscription tiers, their pricing, and feature sets.
+
+## How to use it?
+
+To create a reference table, use the SPQR administrative console:
+
+```sql
+\c spqr-console
+CREATE REFERENCE TABLE tax_rates;
+         attach table          
+-------------------------------
+ relation name   -> tax_rates
+ distribution id -> REPLICATED
+(2 rows)
+```
+
+Then, create the table and insert data:
+
+```sql
+\c ordersdb
+CREATE TABLE tax_rates(i int, j int);
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+COPY tax_rates FROM 'test_tax_rates.csv' DELIMITER '\t';
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+```
+
+Verify replication:
+
+```sql
+TABLE tax_rates /* __spqr__execute_on: sh1 */;
+NOTICE: send query to shard(s) : sh1
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
+ AU           |            |   10.00  | GST
path: docs/sharding/reference_tables.mdx
user: login: github-advanced-security[bot]
body: ## Unrecognized Spelling

[GST](#security-tab) is not a recognized word. \(unrecognized-spelling\)

[Show more details](https://github.com/pg-sharding/spqr/security/code-scanning/6692)
created_at: 2025-03-28T13:19:35Z
author_association: NONE
diff_hunk: @@ -0,0 +1,74 @@
+---
+title: 'Reference Tables'
+---
+
+A reference table is a table that is fully replicated across all shards instead of being divided into separate partitions. This allows **every shard to have a local copy of the table**, reducing network overhead and ensuring fast access to frequently used data.
+
+Reference tables are useful when you need:
+
+- Consistent access to shared data across all shards.
+- Fast lookups without cross-shard queries.
+- Integrity constraints on small tables used across different parts of an application.
+
+## Examples
+
+Some typical use cases for reference tables include:
+
+- **eCommerce**: sales tax rates apply to all stores.
+- **Common codes**: a table with country codes and region names.
+- **Roles**: a system-wide list of roles and permissions.
+- **Finance**: Exchange rates.
+- **Global settings**: settings or feature flags.
+- **A SaaS platform**: a table defining different subscription tiers, their pricing, and feature sets.
+
+## How to use it?
+
+To create a reference table, use the SPQR administrative console:
+
+```sql
+\c spqr-console
+CREATE REFERENCE TABLE tax_rates;
+         attach table          
+-------------------------------
+ relation name   -> tax_rates
+ distribution id -> REPLICATED
+(2 rows)
+```
+
+Then, create the table and insert data:
+
+```sql
+\c ordersdb
+CREATE TABLE tax_rates(i int, j int);
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+COPY tax_rates FROM 'test_tax_rates.csv' DELIMITER '\t';
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+```
+
+Verify replication:
+
+```sql
+TABLE tax_rates /* __spqr__execute_on: sh1 */;
+NOTICE: send query to shard(s) : sh1
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
+ AU           |            |   10.00  | GST
+ IN           |            |   18.00  | GST
path: docs/sharding/reference_tables.mdx
user: login: github-advanced-security[bot]
body: ## Unrecognized Spelling

[GST](#security-tab) is not a recognized word. \(unrecognized-spelling\)

[Show more details](https://github.com/pg-sharding/spqr/security/code-scanning/6693)
created_at: 2025-03-28T13:19:35Z
author_association: NONE
diff_hunk: @@ -0,0 +1,74 @@
+---
+title: 'Reference Tables'
+---
+
+A reference table is a table that is fully replicated across all shards instead of being divided into separate partitions. This allows **every shard to have a local copy of the table**, reducing network overhead and ensuring fast access to frequently used data.
+
+Reference tables are useful when you need:
+
+- Consistent access to shared data across all shards.
+- Fast lookups without cross-shard queries.
+- Integrity constraints on small tables used across different parts of an application.
+
+## Examples
+
+Some typical use cases for reference tables include:
+
+- **eCommerce**: sales tax rates apply to all stores.
+- **Common codes**: a table with country codes and region names.
+- **Roles**: a system-wide list of roles and permissions.
+- **Finance**: Exchange rates.
+- **Global settings**: settings or feature flags.
+- **A SaaS platform**: a table defining different subscription tiers, their pricing, and feature sets.
+
+## How to use it?
+
+To create a reference table, use the SPQR administrative console:
+
+```sql
+\c spqr-console
+CREATE REFERENCE TABLE tax_rates;
+         attach table          
+-------------------------------
+ relation name   -> tax_rates
+ distribution id -> REPLICATED
+(2 rows)
+```
+
+Then, create the table and insert data:
+
+```sql
+\c ordersdb
+CREATE TABLE tax_rates(i int, j int);
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+COPY tax_rates FROM 'test_tax_rates.csv' DELIMITER '\t';
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+```
+
+Verify replication:
+
+```sql
+TABLE tax_rates /* __spqr__execute_on: sh1 */;
+NOTICE: send query to shard(s) : sh1
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
+ AU           |            |   10.00  | GST
+ IN           |            |   18.00  | GST
+(6 rows)
+
+TABLE tax_rates /* __spqr__execute_on: sh2 */;
+NOTICE: send query to shard(s) : sh2
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
path: docs/sharding/reference_tables.mdx
user: login: github-advanced-security[bot]
body: ## Unrecognized Spelling

[GST](#security-tab) is not a recognized word. \(unrecognized-spelling\)

[Show more details](https://github.com/pg-sharding/spqr/security/code-scanning/6694)
created_at: 2025-03-28T13:19:35Z
author_association: NONE
diff_hunk: @@ -0,0 +1,74 @@
+---
+title: 'Reference Tables'
+---
+
+A reference table is a table that is fully replicated across all shards instead of being divided into separate partitions. This allows **every shard to have a local copy of the table**, reducing network overhead and ensuring fast access to frequently used data.
+
+Reference tables are useful when you need:
+
+- Consistent access to shared data across all shards.
+- Fast lookups without cross-shard queries.
+- Integrity constraints on small tables used across different parts of an application.
+
+## Examples
+
+Some typical use cases for reference tables include:
+
+- **eCommerce**: sales tax rates apply to all stores.
+- **Common codes**: a table with country codes and region names.
+- **Roles**: a system-wide list of roles and permissions.
+- **Finance**: Exchange rates.
+- **Global settings**: settings or feature flags.
+- **A SaaS platform**: a table defining different subscription tiers, their pricing, and feature sets.
+
+## How to use it?
+
+To create a reference table, use the SPQR administrative console:
+
+```sql
+\c spqr-console
+CREATE REFERENCE TABLE tax_rates;
+         attach table          
+-------------------------------
+ relation name   -> tax_rates
+ distribution id -> REPLICATED
+(2 rows)
+```
+
+Then, create the table and insert data:
+
+```sql
+\c ordersdb
+CREATE TABLE tax_rates(i int, j int);
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+COPY tax_rates FROM 'test_tax_rates.csv' DELIMITER '\t';
+NOTICE: send query to shard(s) : sh1,sh2,sh3,sh4
+```
+
+Verify replication:
+
+```sql
+TABLE tax_rates /* __spqr__execute_on: sh1 */;
+NOTICE: send query to shard(s) : sh1
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
+ AU           |            |   10.00  | GST
+ IN           |            |   18.00  | GST
+(6 rows)
+
+TABLE tax_rates /* __spqr__execute_on: sh2 */;
+NOTICE: send query to shard(s) : sh2
+ country_code | state_code | tax_rate | tax_category
+--------------+------------+----------+--------------
+ US           | CA         |   7.25   | Sales
+ US           | NY         |   8.875  | Sales
+ GB           |            |   20.00  | VAT
+ CA           |            |   5.00   | GST
+ AU           |            |   10.00  | GST
path: docs/sharding/reference_tables.mdx
user: login: github-advanced-security[bot]
body: ## Unrecognized Spelling

[GST](#security-tab) is not a recognized word. \(unrecognized-spelling\)

[Show more details](https://github.com/pg-sharding/spqr/security/code-scanning/6695)
created_at: 2025-03-28T13:19:35Z
author_association: NONE

PR comments:
user: login: github-actions[bot]
created_at: 2025-03-28T11:39:23Z
body: 
# @check-spelling-bot Report
## :red_circle: Please review
### See the [:open_file_folder: files](https://github.com/pg-sharding/spqr/pull/1102/files/) view, the [:scroll:action log](https://github.com/pg-sharding/spqr/actions/runs/14128112407),  or :memo: job summary for details.

### Unrecognized words (2)

GST
ordersdb

<details><summary>These words are not needed and should be removed
</summary>dbe HEAD pquery spelling tcop 
</details><p></p>

<details><summary>To accept these unrecognized words as correct and remove the previously acknowledged and now absent words,
you could run the following commands</summary>

... in a clone of the [git@github.com:pg-sharding/spqr.git](https://github.com/pg-sharding/spqr.git) repository
on the `add-table-types` branch ([:information_source: how do I use this?](
https://docs.check-spelling.dev/Accepting-Suggestions)):

``` sh
curl -s -S -L 'https://raw.githubusercontent.com/check-spelling/check-spelling/main/apply.pl' |
perl - 'https://github.com/pg-sharding/spqr/actions/runs/14128112407/attempts/1'

```
</details>


**OR**

To have the bot accept them for you, comment in the PR quoting the following line:
@check-spelling-bot apply [updates](https://github.com/pg-sharding/spqr/actions/runs/14128112407/attempts/1).


<details><summary>Available :books: dictionaries could cover words (expected and unrecognized) not in the :blue_book: dictionary</summary>

This includes both **expected items** (620) from .github/actions/spelling/expect.txt and **unrecognized words** (2)

Dictionary | Entries | Covers | Uniquely
-|-|-|-
[cspell:cpp/src/ecosystem.txt](https://raw.githubusercontent.com/check-spelling/cspell-dicts/v20230509/dictionaries/cpp/src/ecosystem.txt)|51|1|1|
[cspell:sql/src/sql.txt](https://raw.githubusercontent.com/check-spelling/cspell-dicts/v20230509/dictionaries/sql/src/sql.txt)|190|1|1|
[cspell:mnemonics/src/mnemonics.txt](https://raw.githubusercontent.com/check-spelling/cspell-dicts/v20230509/dictionaries/mnemonics/src/mnemonics.txt)|800|1|1|

Consider adding them (in `.github/workflows/spelling.yaml`) in `jobs:`/`spelling:` for `uses: check-spelling/check-spelling@main` in its `with`:
``` yml
      with:
        extra_dictionaries: |
          cspell:cpp/src/ecosystem.txt
          cspell:sql/src/sql.txt
          cspell:mnemonics/src/mnemonics.txt
```
To stop checking additional dictionaries, add (in `.github/workflows/spelling.yaml`) for `uses: check-spelling/check-spelling@main` in its `with`:
``` yml
check_extra_dictionaries: ''
```

</details>
<details><summary>Warnings (1)</summary>

#### See the [:open_file_folder: files](https://github.com/pg-sharding/spqr/pull/1102/files/) view, the [:scroll:action log](https://github.com/pg-sharding/spqr/actions/runs/14128112407),  or :memo: job summary for details.

[:warning: Warnings](https://docs.check-spelling.dev/Event-descriptions) | Count
-|-
[:warning: non-alpha-in-dictionary](https://docs.check-spelling.dev/Event-descriptions#non-alpha-in-dictionary) | 2

See [:warning: Event descriptions](https://docs.check-spelling.dev/Event-descriptions) for more information.

</details>

author_association: NONE
user: login: github-actions[bot]
created_at: 2025-03-28T13:24:51Z
body: 
# @check-spelling-bot Report
## :red_circle: Please review
### See the [:open_file_folder: files](https://github.com/pg-sharding/spqr/pull/1102/files/) view, the [:scroll:action log](https://github.com/pg-sharding/spqr/actions/runs/14129735691),  or :memo: job summary for details.

### Unrecognized words (2)

GST
ordersdb

<details><summary>These words are not needed and should be removed
</summary>dbe HEAD pquery spelling tcop 
</details><p></p>

<details><summary>To accept these unrecognized words as correct and remove the previously acknowledged and now absent words,
you could run the following commands</summary>

... in a clone of the [git@github.com:pg-sharding/spqr.git](https://github.com/pg-sharding/spqr.git) repository
on the `add-table-types` branch ([:information_source: how do I use this?](
https://docs.check-spelling.dev/Accepting-Suggestions)):

``` sh
curl -s -S -L 'https://raw.githubusercontent.com/check-spelling/check-spelling/main/apply.pl' |
perl - 'https://github.com/pg-sharding/spqr/actions/runs/14129735691/attempts/1'

```
</details>


**OR**

To have the bot accept them for you, comment in the PR quoting the following line:
@check-spelling-bot apply [updates](https://github.com/pg-sharding/spqr/actions/runs/14129735691/attempts/1).


<details><summary>Available :books: dictionaries could cover words (expected and unrecognized) not in the :blue_book: dictionary</summary>

This includes both **expected items** (620) from .github/actions/spelling/expect.txt and **unrecognized words** (2)

Dictionary | Entries | Covers | Uniquely
-|-|-|-
[cspell:cpp/src/ecosystem.txt](https://raw.githubusercontent.com/check-spelling/cspell-dicts/v20230509/dictionaries/cpp/src/ecosystem.txt)|51|1|1|
[cspell:sql/src/sql.txt](https://raw.githubusercontent.com/check-spelling/cspell-dicts/v20230509/dictionaries/sql/src/sql.txt)|190|1|1|
[cspell:mnemonics/src/mnemonics.txt](https://raw.githubusercontent.com/check-spelling/cspell-dicts/v20230509/dictionaries/mnemonics/src/mnemonics.txt)|800|1|1|

Consider adding them (in `.github/workflows/spelling.yaml`) in `jobs:`/`spelling:` for `uses: check-spelling/check-spelling@main` in its `with`:
``` yml
      with:
        extra_dictionaries: |
          cspell:cpp/src/ecosystem.txt
          cspell:sql/src/sql.txt
          cspell:mnemonics/src/mnemonics.txt
```
To stop checking additional dictionaries, add (in `.github/workflows/spelling.yaml`) for `uses: check-spelling/check-spelling@main` in its `with`:
``` yml
check_extra_dictionaries: ''
```

</details>
<details><summary>Warnings (1)</summary>

#### See the [:open_file_folder: files](https://github.com/pg-sharding/spqr/pull/1102/files/) view, the [:scroll:action log](https://github.com/pg-sharding/spqr/actions/runs/14129735691),  or :memo: job summary for details.

[:warning: Warnings](https://docs.check-spelling.dev/Event-descriptions) | Count
-|-
[:warning: non-alpha-in-dictionary](https://docs.check-spelling.dev/Event-descriptions#non-alpha-in-dictionary) | 2

See [:warning: Event descriptions](https://docs.check-spelling.dev/Event-descriptions) for more information.

</details>

author_association: NONE
user: login: github-actions[bot]
created_at: 2025-03-28T13:27:51Z
body: 
# @check-spelling-bot Report
## :red_circle: Please review
### See the [:open_file_folder: files](https://github.com/pg-sharding/spqr/pull/1102/files/) view, the [:scroll:action log](https://github.com/pg-sharding/spqr/actions/runs/14129887822),  or :memo: job summary for details.

### Unrecognized words (2)

GST
ordersdb

<details><summary>These words are not needed and should be removed
</summary>dbe HEAD pquery spelling tcop 
</details><p></p>

<details><summary>To accept these unrecognized words as correct and remove the previously acknowledged and now absent words,
you could run the following commands</summary>

... in a clone of the [git@github.com:pg-sharding/spqr.git](https://github.com/pg-sharding/spqr.git) repository
on the `add-table-types` branch ([:information_source: how do I use this?](
https://docs.check-spelling.dev/Accepting-Suggestions)):

``` sh
curl -s -S -L 'https://raw.githubusercontent.com/check-spelling/check-spelling/main/apply.pl' |
perl - 'https://github.com/pg-sharding/spqr/actions/runs/14129887822/attempts/1'

```
</details>


**OR**

To have the bot accept them for you, comment in the PR quoting the following line:
@check-spelling-bot apply [updates](https://github.com/pg-sharding/spqr/actions/runs/14129887822/attempts/1).


<details><summary>Available :books: dictionaries could cover words (expected and unrecognized) not in the :blue_book: dictionary</summary>

This includes both **expected items** (620) from .github/actions/spelling/expect.txt and **unrecognized words** (2)

Dictionary | Entries | Covers | Uniquely
-|-|-|-
[cspell:cpp/src/ecosystem.txt](https://raw.githubusercontent.com/check-spelling/cspell-dicts/v20230509/dictionaries/cpp/src/ecosystem.txt)|51|1|1|
[cspell:sql/src/sql.txt](https://raw.githubusercontent.com/check-spelling/cspell-dicts/v20230509/dictionaries/sql/src/sql.txt)|190|1|1|
[cspell:mnemonics/src/mnemonics.txt](https://raw.githubusercontent.com/check-spelling/cspell-dicts/v20230509/dictionaries/mnemonics/src/mnemonics.txt)|800|1|1|

Consider adding them (in `.github/workflows/spelling.yaml`) in `jobs:`/`spelling:` for `uses: check-spelling/check-spelling@main` in its `with`:
``` yml
      with:
        extra_dictionaries: |
          cspell:cpp/src/ecosystem.txt
          cspell:sql/src/sql.txt
          cspell:mnemonics/src/mnemonics.txt
```
To stop checking additional dictionaries, add (in `.github/workflows/spelling.yaml`) for `uses: check-spelling/check-spelling@main` in its `with`:
``` yml
check_extra_dictionaries: ''
```

</details>
<details><summary>Warnings (1)</summary>

#### See the [:open_file_folder: files](https://github.com/pg-sharding/spqr/pull/1102/files/) view, the [:scroll:action log](https://github.com/pg-sharding/spqr/actions/runs/14129887822),  or :memo: job summary for details.

[:warning: Warnings](https://docs.check-spelling.dev/Event-descriptions) | Count
-|-
[:warning: non-alpha-in-dictionary](https://docs.check-spelling.dev/Event-descriptions#non-alpha-in-dictionary) | 2

See [:warning: Event descriptions](https://docs.check-spelling.dev/Event-descriptions) for more information.

</details>

author_association: NONE