Add documentation for CREATE OR REPLACE

docs/src/main/sphinx/connector/iceberg.md

@@ -1276,6 +1276,35 @@ FROM example.testdb."customer_orders$snapshots"
 ORDER BY committed_at DESC
 ```
 
+(iceberg-create-or-replace)=
+
+#### Replacing tables
+
+The connector supports replacing a table as an atomic operation. Atomic table
+replacement creates a new snapshot with the new table definition (see
+{doc}`/sql/create-table` and {doc}`/sql/create-table-as`), but keeps table history.
+
+The new table after replacement is completely new and separate from the old table.
+Only the name of the table remains identical. Earlier snapshots can be retrieved 
+through Iceberg's [time travel](iceberg-time-travel).
+
+For example a partitioned table `my_table` can be replaced by completely new
+definition.
+
+```
+CREATE TABLE my_table (
+    a BIGINT,
+    b DATE,
+    c BIGINT)
+WITH (partitioning = ARRAY['a']);
+
+CREATE OR REPLACE TABLE my_table
+WITH (sorted_by = ARRAY['a'])
+AS SELECT * from another_table;
+```
+
+Earlier snapshots can be retrieved through Iceberg's [time travel](iceberg-time-travel).
+
 (iceberg-time-travel)=
 
 ##### Time travel queries
@@ -1302,6 +1331,14 @@ SELECT *
 FROM example.testdb.customer_orders FOR TIMESTAMP AS OF TIMESTAMP '2022-03-23 09:59:29.803 Europe/Vienna'
 ```
 
+The connector allows to create a new snapshot through Iceberg's [replace table](iceberg-create-or-replace).
+
+```
+CREATE OR REPLACE TABLE example.testdb.customer_orders AS 
+SELECT *
+FROM example.testdb.customer_orders FOR TIMESTAMP AS OF TIMESTAMP '2022-03-23 09:59:29.803 Europe/Vienna'
+```
+
 You can use a date to specify a point a time in the past for using a snapshot of a table in a query.
 Assuming that the session time zone is `Europe/Vienna` the following queries are equivalent:
 

docs/src/main/sphinx/sql/create-table-as.md

@@ -3,7 +3,7 @@
 ## Synopsis
 
 ```text
-CREATE TABLE [ IF NOT EXISTS ] table_name [ ( column_alias, ... ) ]
+CREATE [ OR REPLACE ] TABLE [ IF NOT EXISTS ] table_name [ ( column_alias, ... ) ]
 [ COMMENT table_comment ]
 [ WITH ( property_name = expression [, ...] ) ]
 AS query
@@ -15,9 +15,16 @@ AS query
 Create a new table containing the result of a {doc}`select` query.
 Use {doc}`create-table` to create an empty table.
 
+The optional `OR REPLACE` clause causes an existing table with the
+specified name to be replaced with the new table definition. Support
+for table replacement varies across connectors. Refer to the
+connector documentation for details.
+
 The optional `IF NOT EXISTS` clause causes the error to be
 suppressed if the table already exists.
 
+`OR REPLACE` and `IF NOT EXISTS` cannot be used together.
+
 The optional `WITH` clause can be used to set properties
 on the newly created table.  To list all available table
 properties, run the following query:

docs/src/main/sphinx/sql/create-table.md

@@ -3,7 +3,7 @@
 ## Synopsis
 
 ```text
-CREATE TABLE [ IF NOT EXISTS ]
+CREATE [ OR REPLACE ] TABLE [ IF NOT EXISTS ]
 table_name (
   { column_name data_type [ NOT NULL ]
       [ COMMENT comment ]
@@ -22,9 +22,16 @@ table_name (
 Create a new, empty table with the specified columns.
 Use {doc}`create-table-as` to create a table with data.
 
+The optional `OR REPLACE` clause causes an existing table with the
+specified name to be replaced with the new table definition. Support
+for table replacement varies across connectors. Refer to the
+connector documentation for details.
+
 The optional `IF NOT EXISTS` clause causes the error to be
 suppressed if the table already exists.
 
+`OR REPLACE` and `IF NOT EXISTS` cannot be used together.
+
 The optional `WITH` clause can be used to set properties
 on the newly created table or on single columns.  To list all available table
 properties, run the following query: