Ydbdocs 1008 transactions topics tables en (#13880)

Co-authored-by: Ivan Blinkov <ivan@ydb.tech>

3 files changed, 43 insertions, 0 deletions

diff --git a/ydb/docs/en/core/concepts/_includes/transactions.md b/ydb/docs/en/core/concepts/_includes/transactions.md
index 263397aaaf0..1e1d08830b3 100644
--- a/ydb/docs/en/core/concepts/_includes/transactions.md
+++ b/ydb/docs/en/core/concepts/_includes/transactions.md
@@ -54,3 +54,9 @@ A database [table](../datamodel/table.md) in {{ ydb-short-name }} can be sharded
 A [topic](../topic.md) in {{ ydb-short-name }} can be sharded into several partitions. Different topic partitions, similar to table shards, can be served by different distributed database servers.
 
 {{ ydb-short-name }} supports distributed transactions. Distributed transactions are transactions that affect more than one shard of one or more tables and topics. They require more resources and take more time. While point reads and writes may take up to 10 ms in the 99th percentile, distributed transactions typically take from 20 to 500 ms.
+
+## Transactions with topics and tables {#topic-table-transactions}
+
+{{ ydb-short-name }} supports transactions involving [row-oriented tables](../glossary.md#row-oriented-table) and/or [topics](../glossary.md#topic). This makes it possible to transactionally transfer data from tables to topics and vice versa, as well as between topics. This ensures that data is neither lost nor duplicated in case of a network outage or other issues. This enables the implementation of the transactional outbox pattern within {{ ydb-short-name }}.
+
+For more information about transactions with tables and topics in {{ ydb-short-name }}, see [{#T}](../topic.md#topic-transactions) and [{#T}](../../reference/ydb-sdk/topic.md).
\ No newline at end of file
diff --git a/ydb/docs/en/core/concepts/topic.md b/ydb/docs/en/core/concepts/topic.md
index c2be80473b7..cf8ecf98c3e 100644
--- a/ydb/docs/en/core/concepts/topic.md
+++ b/ydb/docs/en/core/concepts/topic.md
@@ -193,3 +193,27 @@ A consumer may be flagged as "important". This flag indicates that messages in a
 As a long timeout of an important consumer may result in full use of all available free space by unread messages, be sure to monitor important consumers' data read lags.
 
 {% endnote %}
+
+## Topic protocols {#topic-protocols}
+
+To work with topics, the {{ ydb-short-name }} SDK is used (see also [Reference](../reference/ydb-sdk/topic.md)).
+
+Kafka API version 3.4.0 is also supported with some restrictions (see [Work with Kafka API](../reference/kafka-api/index.md)).
+
+## Transactions with topics {#topic-transactions}
+
+{{ ydb-short-name }} supports working with topics within [transactions](./transactions.md).
+
+### Read from a topic within a transaction {#topic-transactions-read}
+
+Topic data does not change during a read operation. Therefore, within transactional reads from a topic, only the offset commit is a true transactional operation. The postponed offset commit occurs automatically at the transaction commit, and the SDK handles this transparently for the user.
+
+### Write into a topic within a transaction {#topic-transactions-write}
+
+During transactional writes to a topic, data is stored outside the partition until the transaction is committed. At the transaction commit, the data is published to the partition and appended to the end of the partition with sequential offsets. Changes made within the transaction are not visible in transactions with topics in {{ ydb-short-name }}.
+
+### Topic transaction constraints {#topic-transactions-constraints}
+
+There are no additional constraints when working with topics within a transaction. It is possible to write large amounts of data to a topic, write to multiple partitions, and read with multiple consumers.
+
+However, it is recommended to consider that data is published only at transaction commit. Therefore, if a transaction is long-running, the data will become visible only after a significant delay.
\ No newline at end of file
diff --git a/ydb/docs/en/core/reference/ydb-sdk/topic.md b/ydb/docs/en/core/reference/ydb-sdk/topic.md
index d0172daf9cf..1ca0018783a 100644
--- a/ydb/docs/en/core/reference/ydb-sdk/topic.md
+++ b/ydb/docs/en/core/reference/ydb-sdk/topic.md
@@ -866,6 +866,19 @@ All the metadata provided when writing a message is sent to a consumer with the
 
 {% list tabs group=lang %}
 
+- C++
+
+  To write to a topic within a transaction, it is necessary to pass a transaction object reference to the `Write` method of the writing session.
+
+  ```c++
+    auto tableSession = tableClient.GetSession().GetValueSync().GetSession();
+    auto transaction = tableSession.BeginTransaction().GetValueSync().GetTransaction();
+    NYdb::NTopic::TWriteMessage writeMessage("message");
+
+    topicSession->Write(std::move(writeMessage), transaction);
+    transaction.Commit().GetValueSync();
+  ```
+
 - Go
 
   To write to a topic within a transaction, create a transactional writer by calling [TopicClient.StartTransactionalWriter](https://pkg.go.dev/github.com/ydb-platform/ydb-go-sdk/v3/topic#Client.StartTransactionalWriter) with the `tx` argument. Once created, you can send messages as usual. There's no need to close the transactional writer manually, as it will be closed automatically when the transaction ends.