From 048d79e438633ac0e15d1862c61aa76f483278bf Mon Sep 17 00:00:00 2001 From: BohuTANG Date: Fri, 10 Oct 2025 17:28:36 +0800 Subject: [PATCH] Add documentation for ALTER TABLE SWAP WITH - Add new documentation file for ALTER TABLE SWAP WITH command - Document syntax, usage notes, and examples - Mark as introduced in v1.2.821 - Reference PR: databendlabs/databend#18767 --- .../00-ddl/01-table/92-alter-table-swap.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 docs/en/sql-reference/10-sql-commands/00-ddl/01-table/92-alter-table-swap.md diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/92-alter-table-swap.md b/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/92-alter-table-swap.md new file mode 100644 index 0000000000..7a63418a37 --- /dev/null +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/92-alter-table-swap.md @@ -0,0 +1,48 @@ +--- +title: ALTER TABLE SWAP WITH +sidebar_position: 5 +--- +import FunctionDescription from '@site/src/components/FunctionDescription'; + + + +Swaps all table metadata and data between two tables atomically in a single transaction. This operation exchanges the table schemas, including all columns, constraints, and data, effectively making each table take on the identity of the other. + +## Syntax + +```sql +ALTER TABLE [ IF EXISTS ] SWAP WITH +``` + +| Parameter | Description | +|----------------------|------------------------------------------------| +| `source_table_name` | The name of the first table to swap | +| `target_table_name` | The name of the second table to swap with | + +## Usage Notes + +- **Engine Support**: Only available for Fuse Engine tables. External tables, system tables, and other non-Fuse tables are not supported. +- **Table Type**: Temporary tables cannot be swapped with permanent or transient tables. +- **Permissions**: The current role must be the owner of both tables to perform the swap operation. +- **Database Scope**: Both tables must be in the same database. Cross-database swapping is not supported. +- **Atomicity**: The swap operation is atomic. Either both tables are swapped successfully, or neither is changed. +- **Data Preservation**: All data and metadata are preserved during the swap. No data is lost or modified. + +## Examples + +```sql +-- Create two tables with different schemas +CREATE OR REPLACE TABLE t1(a1 INT, a2 VARCHAR, a3 DATE); +CREATE OR REPLACE TABLE t2(b1 VARCHAR); + +-- Check table schemas before swap +DESC t1; +DESC t2; + +-- Swap the tables +ALTER TABLE t1 SWAP WITH t2; + +-- After swapping, t1 now has t2's schema, and t2 has t1's schema +DESC t1; +DESC t2; +```