Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions ydb/docs/en/core/concepts/_includes/transactions.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,31 @@ If consistency or freshness requirement for data read by a transaction can be re
* *Stale Read-Only*: Read operations within a transaction may return results that are slightly out-of-date (lagging by fractions of a second). Each individual read returns consistent data, but no consistency between different reads is guaranteed.
* *Snapshot Read-Only*: All the read operations within a transaction access the database snapshot. All the data reads are consistent. The snapshot is taken when the transaction begins, meaning the transaction sees all changes committed before it began.

### Implicit Transactions {#implicit}

If no [transaction mode](../transactions.md#modes) is specified for a query, {{ ydb-short-name }} automatically manages its behavior. This mode is called an **implicit transaction**.

In this mode, based on the query, {{ ydb-short-name }} decides whether to execute it outside a transaction or wrap it in a transaction with *Serializable* mode. Implicit transactions are a universal way to execute queries, as they support statements of any kind with a certain behavior described below.

#### Behavior for Different Types of Statements

- **[Data Definition Language](https://en.wikipedia.org/wiki/Data_definition_language) (DDL) Statements**
DDL statements (such as [`CREATE TABLE`](../../yql/reference/syntax/create_table/index.md), [`DROP TABLE`](../../yql/reference/syntax/drop_table.md), etc.) are executed outside a transaction. A query can consist only of DDL statements. If an error occurs, changes made by previous statements in the query are not rolled back.

- **[Data Manipulation Language](https://en.wikipedia.org/wiki/Data_manipulation_language) (DML) Statements**
DML statements (such as [`SELECT`](../../yql/reference/syntax/select/index.md), [`UPSERT`](../../yql/reference/syntax/upsert_into.md), [`UPDATE`](../../yql/reference/syntax/update.md), etc.) are wrapped in a transaction with *Serializable* mode. A query can consist only of DML statements. On success, changes are committed. If an error occurs, all changes are rolled back.

- **Batch Modification Statements**
Batch modification statements (such as [`BATCH UPDATE`](../../yql/reference/syntax/batch-update.md) and [`BATCH DELETE`](../../yql/reference/syntax/batch-delete.md)) are executed outside a transaction. A query can contain only one batch modification statement. If an error occurs, the statement's changes are not rolled back.

#### Summary Table

| Statement Type | Implicit Transaction Handling | Multistatement Support | Rollback on Error |
|----------------|---------------------------------------------------|------------------------|-----------------------|
| DDL | Outside a transaction | Yes (DDL-only) | No |
| DML | Auto transaction (Serializable) | Yes (DML-only) | Yes |
| Batch Modification Statements | Outside a transaction | No | No |

The transaction execution mode is specified in its settings when creating the transaction. See the examples for the {{ ydb-short-name }} SDK in the [{#T}](../../recipes/ydb-sdk/tx-control.md).

## YQL Language {#language-yql}
Expand Down
4 changes: 4 additions & 0 deletions ydb/docs/en/core/concepts/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,10 @@ Together, these mechanisms allow {{ ydb-short-name }} to provide [strict consist

The implementation of distributed transactions is covered in a separate article [{#T}](../contributor/datashard-distributed-txs.md), while below there's a list of several [related terms](#deterministic-transactions).

### Implicit Transactions {#implicit-transactions}

An **implicit transaction** is the query execution mode used when the [transaction mode](transactions.md#modes) is not specified. {{ ydb-short-name }} automatically determines the behavior for each statement — whether to wrap it in a transaction or execute it outside one. This mode is described in more detail in [{#T}](transactions.md#implicit).

### Interactive transactions {#interactive-transaction}

The term **interactive transactions** refers to transactions that are split into multiple queries and involve data processing by an application between these queries. For example:
Expand Down
2 changes: 1 addition & 1 deletion ydb/docs/en/core/yql/reference/syntax/batch-delete.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ This query, like the standard `DELETE FROM`, executes synchronously and returns
The semantics are inherited from the standard `DELETE FROM` with the following restrictions:

* Supported only for [row-oriented tables](../../../concepts/glossary.md#row-oriented-table).
* Supported only for queries with implicit transaction control (`NoTx` mode or `EmptyTxControl` in SDK).
* Supported only for queries with [implicit transaction control](../../../concepts/transactions.md#implicit).
* The use of subqueries and multiple statements in a single query is prohibited.
* The `RETURNING` clause is unavailable.

Expand Down
2 changes: 1 addition & 1 deletion ydb/docs/en/core/yql/reference/syntax/batch-update.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ This query, like the standard `UPDATE`, executes synchronously and returns a sta
The semantics are inherited from the standard `UPDATE` with the following restrictions:

* Supported only for [row-oriented tables](../../../concepts/glossary.md#row-oriented-table).
* Supported only for queries with implicit transaction control (`NoTx` mode or `EmptyTxControl` in SDK).
* Supported only for queries with [implicit transaction control](../../../concepts/transactions.md#implicit).
* Only idempotent updates are supported: expressions following `SET` should not depend on the current values of the columns being modified.
* The use of subqueries and multiple statements in a single query is prohibited.
* The `RETURNING` clause is unavailable.
Expand Down
25 changes: 25 additions & 0 deletions ydb/docs/ru/core/concepts/_includes/transactions.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,31 @@
* *Stale Read-Only* — чтения данных в транзакции возвращают результаты с возможным отставанием от актуальных (доли секунды). Данные в каждом отдельно взятом чтении консистентны, между разными чтениями консистентность данных не гарантируется.
* *Snapshot Read-Only* — все чтения транзакции производятся из снапшота базы данных, при этом все чтения данных консистентны. Взятие снапшота происходит в момент старта транзакции, т.е. транзакция видит все изменения, закоммиченные до момента своего начала.

### Неявные транзакции {#implicit}

Если для запроса не задан [режим транзакции](../transactions.md#modes), {{ ydb-short-name }} автоматически управляет его поведением. Такой режим называется неявной транзакцией.

В этом режиме {{ ydb-short-name }} на основе запроса определяет, выполнить его вне транзакции или обернуть в транзакцию с режимом *Serializable*. Режим неявной транзакции является универсальным для выполнения запроса, так как поддерживает инструкции любого вида с определённым поведением, описанным ниже.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Я бы добавил объяснение. Грубо говоря, YDB не поддерживает транзакционный DDL, поэтому появляется описание работы неявных транзакций.


#### Поведение для разных видов инструкций
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Я бы убрал заголовок. Вот просто совсем без него.


- **Инструкции [Data Definition Language](https://en.wikipedia.org/wiki/Data_definition_language) (DDL)**
DDL-инструкции (такие как [CREATE TABLE](../../yql/reference/syntax/create_table/index.md), [DROP TABLE](../../yql/reference/syntax/drop_table.md) и т.д.) выполняются вне транзакции. Запрос может состоять только из DDL-инструкций. При возникновении ошибки изменения, внесённые предыдущими инструкциями запроса, не откатываются.

- **Инструкции [Data Manipulation Language](https://en.wikipedia.org/wiki/Data_manipulation_language) (DML)**
DML-инструкции (такие как [UPSERT](../../yql/reference/syntax/upsert_into.md), [SELECT](../../yql/reference/syntax/select/index.md), [UPDATE](../../yql/reference/syntax/update.md) и т.д.) оборачиваются в транзакцию с режимом *Serializable*. Запрос может состоять только из DML-инструкций. При успешном выполнении изменения коммитятся (фиксируются), а при возникновении ошибки — откатываются.

- **Инструкции пакетного изменения**
Инструкции пакетного изменения (такие как [BATCH UPDATE](../../yql/reference/syntax/batch-update.md) и [BATCH DELETE FROM](../../yql/reference/syntax/batch-delete.md)) выполняются вне транзакции. Запрос может состоять только из одной инструкции пакетного изменения. При возникновении ошибки изменения инструкции не откатываются.

#### Сводная таблица
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

И этот заголовок бы убрал.


| Тип инструкции | Обработка неявной транзакции | Поддержка нескольких инструкций | Откат при ошибке |
|----------------|---------------------------------------------------|---------------------------------|-----------------------|
| DDL | Вне транзакции | Да (только DDL) | Нет |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Мне не нравится фраза "Вне транзакции". Больше нравится "Каждый DDL statement в своей транзакции"

| DML | Автоматическая транзакция (Serializable) | Да (только DML) | Да |
| Инструкции пакетного изменения | Вне транзакции | Нет | Нет |

Режим выполнения транзакции задается в настройках транзакции при ее создании. Примеры для {{ ydb-short-name }} SDK смотрите в статье [{#T}](../../recipes/ydb-sdk/tx-control.md).

## Язык YQL {#language-yql}
Expand Down
4 changes: 4 additions & 0 deletions ydb/docs/ru/core/concepts/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,10 @@

{% endif %}

### Неявные транзакции {#implicit-transactions}

**Неявная транзакция** — это режим выполнения запросов, при котором [режим транзакции](transactions.md#modes) не указан. В этом случае {{ ydb-short-name }} самостоятельно определяет, нужно ли обернуть их в транзакцию. Этот режим описан более подробно в [{#T}](transactions.md#implicit).

### Многоверсионное управление параллелизмом {#mvcc}

[**Многоверсионное управление параллелизмом**](https://ru.wikipedia.org/wiki/MVCC), **multi-version concurrency control** или **MVCC** — это метод, используемый {{ ydb-short-name }} для одновременного доступа нескольких параллельных транзакций к базе данных без взаимных помех. Он описан более подробно в отдельной статье [{#T}](mvcc.md).
Expand Down
2 changes: 1 addition & 1 deletion ydb/docs/ru/core/yql/reference/syntax/batch-delete.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
Семантика наследуется от стандартного `DELETE FROM` с ограничениями:

* Поддерживается только для [строковых таблиц](../../../concepts/glossary.md#row-oriented-table).
* Поддерживается только для неявного контроля транзакции (режим `NoTx` или `EmptyTxControl` в SDK).
* Поддерживается только в режиме [неявного контроля транзакций](../../../concepts/transactions.md#implicit).
* Запрещено использование подзапросов и нескольких выражений в одном запросе.
* Недоступно ключевое слово `RETURNING`.

Expand Down
2 changes: 1 addition & 1 deletion ydb/docs/ru/core/yql/reference/syntax/batch-update.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
Семантика наследуется от стандартного `UPDATE` с ограничениями:

* Поддерживается только для [строковых таблиц](../../../concepts/glossary.md#row-oriented-table).
* Поддерживается только для неявного контроля транзакции (режим `NoTx` или `EmptyTxControl` в SDK).
* Поддерживается только в режиме [неявного контроля транзакций](../../../concepts/transactions.md#implicit).
* Поддерживаются только идемпотентные обновления: выражения после `SET` не должны зависеть от текущих значений изменяемых колонок.
* Запрещено использование подзапросов и нескольких выражений в одном запросе.
* Недоступно ключевое слово `RETURNING`.
Expand Down