Document branching syntax

Author: ebyhr

docs/src/main/sphinx/sql.md

@@ -11,6 +11,7 @@ Refer to the following sections for further details:
 ```{toctree}
 :maxdepth: 1
 
+sql/alter-branch
 sql/alter-materialized-view
 sql/alter-schema
 sql/alter-table
@@ -19,6 +20,7 @@ sql/analyze
 sql/call
 sql/comment
 sql/commit
+sql/create-branch
 sql/create-catalog
 sql/create-function
 sql/create-materialized-view
@@ -33,6 +35,7 @@ sql/deny
 sql/describe
 sql/describe-input
 sql/describe-output
+sql/drop-branch
 sql/drop-catalog
 sql/drop-function
 sql/drop-materialized-view
@@ -62,6 +65,7 @@ sql/set-role
 sql/set-session
 sql/set-session-authorization
 sql/set-time-zone
+sql/show-branches
 sql/show-catalogs
 sql/show-columns
 sql/show-create-function

docs/src/main/sphinx/sql/alter-branch.md

@@ -0,0 +1,26 @@
+# ALTER BRANCH
+
+## Synopsis
+
+```text
+ALTER BRANCH source_branch IN TABLE table_name FAST FORWARD TO target_branch
+```
+
+## Description
+
+Fast-forward the current snapshot of one branch to the latest snapshot of
+another.
+
+## Examples
+
+Fast-forward the `main` branch to the head of `audit` branch in the `orders`
+table:
+
+```sql
+ALTER BRANCH main IN TABLE orders FAST FORWARD TO audit
+```
+
+## See also
+
+- {doc}`create-branch`
+- {doc}`drop-branch`

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

@@ -0,0 +1,47 @@
+# CREATE BRANCH
+
+## Synopsis
+
+```text
+CREATE BRANCH [ OR REPLACE ] [ IF NOT EXISTS ] branch_name
+[ WITH ( property_name = expression [, ...] ) ]
+IN TABLE table_name
+[ FROM source_branch ]
+```
+
+## Description
+
+Create a branch.
+
+The optional `OR REPLACE` clause causes an existing branch with the
+specified name to be replaced with the new branch definition. Support
+for branch 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 branch already exists.
+
+The optional `WITH` clause can be used to set properties
+on the newly created schema. To list all available schema
+properties, run the following query:
+
+The optional `FROM` clause can be used to set the source branch from which the
+new branch is created.
+
+## Examples
+
+Create a new branch `audit` in the table `orders`:
+
+```sql
+CREATE BRANCH audit IN TABLE orders
+```
+
+Create a new branch `audit` in the table `orders` from the branch `dev`:
+
+```sql
+CREATE BRANCH audit IN TABLE orders FROM dev
+```
+
+## See also
+
+{doc}`drop-branch`

docs/src/main/sphinx/sql/delete.md

@@ -3,7 +3,7 @@
 ## Synopsis
 
 ```text
-DELETE FROM table_name [ WHERE condition ]
+DELETE FROM table_name [ @ branch_name ] [ WHERE condition ]
 ```
 
 ## Description
@@ -32,6 +32,12 @@ Delete all orders:
 DELETE FROM orders;
 ```
 
+Delete all orders in the `audit` branch:
+
+```sql
+DELETE FROM orders @ audit;
+```
+
 ## Limitations
 
 Some connectors have limited or no support for `DELETE`.

docs/src/main/sphinx/sql/deny.md

@@ -4,7 +4,7 @@
 
 ```text
 DENY ( privilege [, ...] | ( ALL PRIVILEGES ) )
-ON ( table_name | TABLE table_name | SCHEMA schema_name)
+ON [ BRANCH branch_name IN ] ( table_name | TABLE table_name | SCHEMA schema_name)
 TO ( user | USER user | ROLE role )
 ```
 
@@ -39,6 +39,12 @@ Deny `SELECT` privilege on the table `orders` to everyone:
 DENY SELECT ON orders TO ROLE PUBLIC;
 ```
 
+Deny `INSERT` privilege on the `audit` branch of the `orders` table:
+
+```sql
+DENY INSERT ON BRANCH audit IN orders TO alice;
+```
+
 ## Limitations
 
 The system access controls as well as the connectors provided by default

docs/src/main/sphinx/sql/drop-branch.md

@@ -0,0 +1,28 @@
+# DROP BRANCH
+
+## Synopsis
+
+```text
+DROP BRANCH [ IF EXISTS ] branch_name
+IN TABLE table_name
+```
+
+## Description
+
+Drops an existing branch.
+
+The optional `IF EXISTS` clause causes the error to be suppressed if the branch
+does not exist.
+
+## Examples
+
+Drop the branch `audit` in the table `orders`:
+
+```sql
+DROP BRANCH audit
+IN TABLE orders
+```
+
+## See also
+
+{doc}`create-branch`

docs/src/main/sphinx/sql/grant.md

@@ -4,7 +4,7 @@
 
 ```text
 GRANT ( privilege [, ...] | ( ALL PRIVILEGES ) )
-ON ( table_name | TABLE table_name | SCHEMA schema_name)
+ON [ BRANCH branch_name IN ] ( table_name | TABLE table_name | SCHEMA schema_name)
 TO ( user | USER user | ROLE role )
 [ WITH GRANT OPTION ]
 ```
@@ -51,6 +51,13 @@ Grant `SELECT` privilege on the table `orders` to everyone:
 GRANT SELECT ON orders TO ROLE PUBLIC;
 ```
 
+Grant `INSERT` privileges on the `audit` branch of the `orders` table to user 
+`alice`:
+
+```sql
+GRANT INSERT ON BRANCH audit IN orders TO alice;
+```
+
 ## Limitations
 
 Some connectors have no support for `GRANT`.

docs/src/main/sphinx/sql/insert.md

@@ -3,7 +3,7 @@
 ## Synopsis
 
 ```text
-INSERT INTO table_name [ ( column [, ... ] ) ] query
+INSERT INTO table_name [ @ branch_name ] [ ( column [, ... ] ) ] query
 ```
 
 ## Description
@@ -52,6 +52,12 @@ INSERT INTO nation (nationkey, name, regionkey)
 VALUES (26, 'POLAND', 3);
 ```
 
+Insert a single row into `audit` branch of the `cities` table:
+
+```sql
+INSERT INTO cities @ audit VALUES (1, 'San Francisco');
+```
+
 ## See also
 
 {doc}`values`

docs/src/main/sphinx/sql/merge.md

@@ -3,7 +3,7 @@
 ## Synopsis
 
 ```text
-MERGE INTO target_table [ [ AS ]  target_alias ]
+MERGE INTO target_table [ @ branch_name ] [ [ AS ]  target_alias ]
 USING { source_table | query } [ [ AS ] source_alias ]
 ON search_condition
 when_clause [...]
@@ -98,6 +98,15 @@ MERGE INTO accounts t USING monthly_accounts_update s
               VALUES(s.customer, s.purchases, s.address)
 ```
 
+Delete all customers mentioned in `audit` branch of the source table:
+
+```sql
+MERGE INTO accounts @ audit t USING monthly_accounts_update s
+    ON t.customer = s.customer
+    WHEN MATCHED
+        THEN DELETE
+```
+
 ## Limitations
 
 Any connector can be used as a source table for a `MERGE` statement.

docs/src/main/sphinx/sql/revoke.md

@@ -5,7 +5,7 @@
 ```text
 REVOKE [ GRANT OPTION FOR ]
 ( privilege [, ...] | ALL PRIVILEGES )
-ON ( table_name | TABLE table_name | SCHEMA schema_name )
+ON [ BRANCH branch_name IN ] ( table_name | TABLE table_name | SCHEMA schema_name )
 FROM ( user | USER user | ROLE role )
 ```
 
@@ -52,6 +52,13 @@ Revoke all privileges on the table `test` from user `alice`:
 REVOKE ALL PRIVILEGES ON test FROM alice;
 ```
 
+Revoke `INSERT` privileges on the `audit` branch of the `orders` table from user
+`alice`:
+
+```sql
+REVOKE INSERT ON BRANCH audit IN orders FROM alice;
+```
+
 ## Limitations
 
 Some connectors have no support for `REVOKE`.