From a64656452ba70cf014fadc8b2cbb89108df0fb6a Mon Sep 17 00:00:00 2001 From: IgGusev Date: Wed, 29 Dec 2021 11:56:50 +0300 Subject: [PATCH 1/4] Initial commit for DDL --- docs/_docs/sql/calcite-based-sql-engine.adoc | 100 +++++++++++++++++++ 1 file changed, 100 insertions(+) diff --git a/docs/_docs/sql/calcite-based-sql-engine.adoc b/docs/_docs/sql/calcite-based-sql-engine.adoc index 0c3a60f2722..4d1c6d33b3e 100644 --- a/docs/_docs/sql/calcite-based-sql-engine.adoc +++ b/docs/_docs/sql/calcite-based-sql-engine.adoc @@ -25,6 +25,106 @@ Replacing H2 SQL engine with Apache Calcite incorporates the following general i * *Better optimization algorithms*: Apache Calcite optimizes queries by repeatedly applying planner rules to a relational expression; * *Higher overall performance*: Calcite offers much higher levels of execution flexibility, as well as higher efficiency in terms of both memory and CPU consumption. +== Data Definition Language (DDL) + +== CREATE TABLE + +Create a new table and an underlying cache. + +[source,sql] +---- +CREATE TABLE [IF NOT EXISTS] tableName (tableColumn [, tableColumn]... + +tableColumn := columnName columnType [DEFAULT defaultValue] +---- + + +Parameters: + +* `tableName` - name of the table. +* `tableColumn` - name and type of a column to be created in the new table. +* `columnName` - name of a previously defined column. +* `DEFAULT` - specifies a default value for the column. Only constant values are accepted. +* `IF NOT EXISTS` - create the table only if a table with the same name does not exist. + +Examples: + +Create Person table: + +[source,sql] +---- +CREATE TABLE IF NOT EXISTS Person ( + id int, + city_id int, + name varchar, + age int, + company varchar, +) +---- + + +== CREATE INDEX + +Create an index on the specified table. + +[source,sql] +---- +CREATE INDEX [[IF NOT EXISTS] indexName] ON tableName (columnName [ASC|DESC] [,...]) +---- + +Parameters: + +* `indexName` - the name of the index to be created. +* `ASC` - specifies ascending sort order (default). +* `DESC` - specifies descending sort order. +* `IF NOT EXISTS` - do not throw an error if an index with the same name already exists. The database checks indexes' names only, and does not consider columns types or count. + + +Examples: + +Create a regular index: + +[source,sql] +---- +CREATE INDEX title_idx ON books (title); +---- + +Create a descending index only if it does not exist: + +[source,sql] +---- +CREATE INDEX IF NOT EXISTS name_idx ON persons (firstName DESC); +---- + + +== DROP INDEX + +`DROP INDEX` deletes an existing index. + + +[source,sql] +---- +DROP INDEX [IF EXISTS] indexName +---- + +Parameters: + +* `indexName` - the name of the index to drop. +* `IF EXISTS` - do not throw an error if an index with the specified name does not exist. The database checks indexes' names only not considering column types or count. + + +DDL commands targeting the same table are blocked until `DROP INDEX` is in progress. DML command execution is not affected and can be performed in parallel. + +=== Examples + +Drop an index: + +[source,sql] +---- +DROP INDEX idx_person_name; +---- + + == Data Manipulation Language (DML) This section walks you through all data manipulation language (DML) commands supported by Apache Ignite Alpha 3. From 5937da0cfb2f2a830ca207e6934548e78a3ae293 Mon Sep 17 00:00:00 2001 From: IgGusev Date: Wed, 29 Dec 2021 13:09:21 +0300 Subject: [PATCH 2/4] Updated doc based on review step 1 --- docs/_docs/images/svg/create_table.svg | 217 +++++++++++++++++++ docs/_docs/sql/calcite-based-sql-engine.adoc | 12 +- 2 files changed, 228 insertions(+), 1 deletion(-) create mode 100644 docs/_docs/images/svg/create_table.svg diff --git a/docs/_docs/images/svg/create_table.svg b/docs/_docs/images/svg/create_table.svg new file mode 100644 index 00000000000..f34d93f9e73 --- /dev/null +++ b/docs/_docs/images/svg/create_table.svg @@ -0,0 +1,217 @@ + + + + + + + + + + + + + + CREATE + + + + + + + + TABLE + + + + + + + + + + + + + + + + IF NOT EXISTS + + + + + + + + + table_name + + + + + + + + ( + + + + + + + + + + + + + + + + pk_constraint + + + + + + + + columns_definition + + + + + + + + + + , + + + + + + + + + + ) + + + + + + + + + + + + + + + + + + + WITH + + + + + + + + + + + + + + + param_name + + + + + + + + = + + + + + + + + param_value + + + + + + + + + , + + + + + + + + + + + + diff --git a/docs/_docs/sql/calcite-based-sql-engine.adoc b/docs/_docs/sql/calcite-based-sql-engine.adoc index 4d1c6d33b3e..ba708c581a8 100644 --- a/docs/_docs/sql/calcite-based-sql-engine.adoc +++ b/docs/_docs/sql/calcite-based-sql-engine.adoc @@ -34,8 +34,10 @@ Create a new table and an underlying cache. [source,sql] ---- CREATE TABLE [IF NOT EXISTS] tableName (tableColumn [, tableColumn]... +[, PRIMARY KEY (columnName [,columnName]...)]) +[WITH "paramName=paramValue [,paramName=paramValue]..."] -tableColumn := columnName columnType [DEFAULT defaultValue] +tableColumn := columnName columnType [DEFAULT defaultValue] [PRIMARY KEY] ---- @@ -46,6 +48,14 @@ Parameters: * `columnName` - name of a previously defined column. * `DEFAULT` - specifies a default value for the column. Only constant values are accepted. * `IF NOT EXISTS` - create the table only if a table with the same name does not exist. +* `PRIMARY KEY` - specifies a primary key for the table that can consist of a single column or multiple columns. +* `WITH` - accepts additional parameters not defined by ANSI-99 SQL: + +** `Replicas` - sets the number of partition copies, including the master copy. +** `Partitions` - sets the number of table partitions. + +image::images/svg/create_table.svg[Embedded,opts=inline] + Examples: From 42ab97f5abecaead573dc0d1d553b6a4309c11ce Mon Sep 17 00:00:00 2001 From: IgGusev Date: Wed, 29 Dec 2021 15:51:29 +0300 Subject: [PATCH 3/4] Updated SQL doc after review --- docs/_docs/sql/calcite-based-sql-engine.adoc | 76 +++++++++++++++++--- 1 file changed, 68 insertions(+), 8 deletions(-) diff --git a/docs/_docs/sql/calcite-based-sql-engine.adoc b/docs/_docs/sql/calcite-based-sql-engine.adoc index ba708c581a8..ff684f20dad 100644 --- a/docs/_docs/sql/calcite-based-sql-engine.adoc +++ b/docs/_docs/sql/calcite-based-sql-engine.adoc @@ -29,15 +29,14 @@ Replacing H2 SQL engine with Apache Calcite incorporates the following general i == CREATE TABLE -Create a new table and an underlying cache. +Creates a new table. [source,sql] ---- -CREATE TABLE [IF NOT EXISTS] tableName (tableColumn [, tableColumn]... -[, PRIMARY KEY (columnName [,columnName]...)]) +CREATE TABLE [IF NOT EXISTS] [simpleName | schemaName.simpleName] (tableColumn [, tableColumn]...) [WITH "paramName=paramValue [,paramName=paramValue]..."] -tableColumn := columnName columnType [DEFAULT defaultValue] [PRIMARY KEY] +tableColumn = columnName columnType [[NOT] NULL] [DEFAULT defaultValue] [PRIMARY KEY] ---- @@ -45,10 +44,8 @@ Parameters: * `tableName` - name of the table. * `tableColumn` - name and type of a column to be created in the new table. -* `columnName` - name of a previously defined column. * `DEFAULT` - specifies a default value for the column. Only constant values are accepted. * `IF NOT EXISTS` - create the table only if a table with the same name does not exist. -* `PRIMARY KEY` - specifies a primary key for the table that can consist of a single column or multiple columns. * `WITH` - accepts additional parameters not defined by ANSI-99 SQL: ** `Replicas` - sets the number of partition copies, including the master copy. @@ -64,7 +61,7 @@ Create Person table: [source,sql] ---- CREATE TABLE IF NOT EXISTS Person ( - id int, + id int primary key, city_id int, name varchar, age int, @@ -72,6 +69,69 @@ CREATE TABLE IF NOT EXISTS Person ( ) ---- +== ALTER TABLE + +Modify the structure of an existing table. + +[source,sql] +---- +ALTER TABLE [IF EXISTS] tableName {alter_specification} + +alter_specification: + ADD [COLUMN] {[IF NOT EXISTS] tableColumn | (tableColumn [,...])} + | DROP [COLUMN] {[IF EXISTS] columnName | (columnName [,...])} + +tableColumn := columnName columnType +---- + +Parameters: + +- `tableName` - the name of the table. +- `tableColumn` - the name and type of the column to be added to the table. +- `IF EXISTS` - if applied to TABLE, do not throw an error if a table with the specified table name does not exist. If applied to COLUMN, do not throw an error if a column with the specified name does not exist. +- `IF NOT EXISTS` - do not throw an error if a column with the same name already exists. + + +`ALTER TABLE ADD` adds a new column or several columns to a previously created table. Once a column is added, it can be accessed by using DML commands and indexed with the CREATE INDEX statement. + +`ALTER TABLE DROP` removes an existing column or multiple columns from a table. Once a column is removed, it cannot be accessed within queries. Consider the following notes and limitations: + +Examples: + +Add a column to the table: + +[source,sql] +---- +ALTER TABLE Person ADD COLUMN city varchar; +---- + +== DROP TABLE + +The `DROP TABLE` command drops an existing table. + +[source,sql] +---- +DROP TABLE [IF EXISTS] tableName +---- + +Parameters: + +- `tableName` - the name of the table. +- `IF NOT EXISTS` - do not throw an error if a table with the same name does not exist. + + +Both DDL and DML commands targeting the same table are blocked while the `DROP TABLE` is in progress. +Once the table is dropped, all pending commands will fail with appropriate errors. + +Examples: + +Drop Person table if the one exists: + +[source,sql] +---- +DROP TABLE IF EXISTS "Person"; +---- + == CREATE INDEX @@ -79,7 +139,7 @@ Create an index on the specified table. [source,sql] ---- -CREATE INDEX [[IF NOT EXISTS] indexName] ON tableName (columnName [ASC|DESC] [,...]) +CREATE INDEX indexName [[IF NOT EXISTS] indexName] ON tableName (columnName [ASC|DESC] [,...]) ---- Parameters: From d5c07f7eac150fccbd8640a98886b2eb16fcba8d Mon Sep 17 00:00:00 2001 From: IgGusev Date: Mon, 10 Jan 2022 13:08:14 +0300 Subject: [PATCH 4/4] Added performing transactions topic --- docs/_docs/performing-transactions.adoc | 46 +++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/_docs/performing-transactions.adoc diff --git a/docs/_docs/performing-transactions.adoc b/docs/_docs/performing-transactions.adoc new file mode 100644 index 00000000000..6a59b868738 --- /dev/null +++ b/docs/_docs/performing-transactions.adoc @@ -0,0 +1,46 @@ += Performing Transactions + +== Executing Transactions + +The key-value API provides an interface for starting and completing transactions. Use the `igniteTransactions` class to create a transaction object and the `commit` method to send it. + +[tabs] +-- +tab:Java[] +[source,java] +---- +Transaction tx = igniteTransactions.begin(); +tx.commit() +---- +-- + + +== Asynchronous Transactions + +You can also perform transactions asynchronously. + +[tabs] +-- +tab:Java[] +[source,java] +---- +protected Table accounts; +protected Table customers; + +accounts.recordView().upsert(null, makeValue(1, BALANCE_1)); +accounts.recordView().upsert(null, makeValue(2, BALANCE_2)); + +igniteTransactions.beginAsync() + .thenCompose(tx -> accounts.recordView().getAsync(tx, makeKey(1)) + .thenCombine(accounts.recordView().getAsync(tx, makeKey(2)), (v1, v2) -> new Pair<>(v1, v2)) + .thenCompose(pair -> allOf( + accounts.recordView().upsertAsync( + tx, makeValue(1, pair.getFirst().doubleValue("balance") - DELTA)), + accounts.recordView().upsertAsync( + tx, makeValue(2, pair.getSecond().doubleValue("balance") + DELTA)) + ) + .thenApply(ignored -> tx) + ) + ).thenCompose(Transaction::commitAsync).join(); +---- +-- \ No newline at end of file