diff --git a/docs/src/main/sphinx/sql.md b/docs/src/main/sphinx/sql.md index cc09ea93e74a..03c20b99d213 100644 --- a/docs/src/main/sphinx/sql.md +++ b/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 diff --git a/docs/src/main/sphinx/sql/alter-branch.md b/docs/src/main/sphinx/sql/alter-branch.md new file mode 100644 index 000000000000..874f2eb6a94e --- /dev/null +++ b/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` diff --git a/docs/src/main/sphinx/sql/create-branch.md b/docs/src/main/sphinx/sql/create-branch.md new file mode 100644 index 000000000000..bfed6d675d31 --- /dev/null +++ b/docs/src/main/sphinx/sql/create-branch.md @@ -0,0 +1,46 @@ +# CREATE BRANCH + +## Synopsis + +```text +CREATE [ OR REPLACE ] BRANCH [ 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 branch. + +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` diff --git a/docs/src/main/sphinx/sql/delete.md b/docs/src/main/sphinx/sql/delete.md index 622405faba92..aef7064f36f0 100644 --- a/docs/src/main/sphinx/sql/delete.md +++ b/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`. diff --git a/docs/src/main/sphinx/sql/deny.md b/docs/src/main/sphinx/sql/deny.md index d533382752db..68f12c667f5e 100644 --- a/docs/src/main/sphinx/sql/deny.md +++ b/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 to user `alice`: + +```sql +DENY INSERT ON BRANCH audit IN orders TO alice; +``` + ## Limitations The system access controls as well as the connectors provided by default diff --git a/docs/src/main/sphinx/sql/drop-branch.md b/docs/src/main/sphinx/sql/drop-branch.md new file mode 100644 index 000000000000..4d29574c6fe0 --- /dev/null +++ b/docs/src/main/sphinx/sql/drop-branch.md @@ -0,0 +1,27 @@ +# 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` diff --git a/docs/src/main/sphinx/sql/grant.md b/docs/src/main/sphinx/sql/grant.md index 269e0fd9dda0..7c37831bf787 100644 --- a/docs/src/main/sphinx/sql/grant.md +++ b/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` privilege 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`. diff --git a/docs/src/main/sphinx/sql/insert.md b/docs/src/main/sphinx/sql/insert.md index 677fc9a936fc..c4a0de948049 100644 --- a/docs/src/main/sphinx/sql/insert.md +++ b/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` diff --git a/docs/src/main/sphinx/sql/merge.md b/docs/src/main/sphinx/sql/merge.md index bec7422f2919..17e6a999816c 100644 --- a/docs/src/main/sphinx/sql/merge.md +++ b/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. diff --git a/docs/src/main/sphinx/sql/revoke.md b/docs/src/main/sphinx/sql/revoke.md index 57fad9c7c59b..b93aaa08b702 100644 --- a/docs/src/main/sphinx/sql/revoke.md +++ b/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` privilege 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`. diff --git a/docs/src/main/sphinx/sql/show-branches.md b/docs/src/main/sphinx/sql/show-branches.md new file mode 100644 index 000000000000..bc68186e4e87 --- /dev/null +++ b/docs/src/main/sphinx/sql/show-branches.md @@ -0,0 +1,19 @@ +# SHOW BRANCHES + +## Synopsis + +```text +SHOW BRANCHES ( FROM | IN ) TABLE table_name +``` + +## Description + +List the available branches. + +## Examples + +List the branches in the table `orders`: + +```sql +SHOW BRANCHES IN TABLE orders +``` diff --git a/docs/src/main/sphinx/sql/update.md b/docs/src/main/sphinx/sql/update.md index 0f6a698f13ba..0daac81dae9c 100644 --- a/docs/src/main/sphinx/sql/update.md +++ b/docs/src/main/sphinx/sql/update.md @@ -3,7 +3,8 @@ ## Synopsis ```text -UPDATE table_name SET [ ( column = expression [, ... ] ) ] [ WHERE condition ] +UPDATE table_name [ @ branch_name ] +SET [ ( column = expression [, ... ] ) ] [ WHERE condition ] ``` ## Description @@ -55,6 +56,18 @@ SET ); ``` +Update the status of all purchases that haven't been assigned a ship date +in the `audit` branch: + +```sql +UPDATE + purchases @ audit +SET + status = 'OVERDUE' +WHERE + ship_date IS NULL; +``` + ## Limitations Some connectors have limited or no support for `UPDATE`.