From 4172d7e89e01a03645d54130b9164a39aff178f6 Mon Sep 17 00:00:00 2001 From: hzh0425 <642256541@qq.com> Date: Fri, 1 Mar 2024 03:04:03 +0800 Subject: [PATCH 1/2] [improve][doc]Add introduction of transaction isolation level in the txn-advanced-features.md (#712) * Add introduction of transaction isolation level in the txn-advanced-features.md Co-authored-by: Kiryl Valkovich --- docs/txn-advanced-features.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/docs/txn-advanced-features.md b/docs/txn-advanced-features.md index 8819fcf8fba3..f00aa6f858c7 100644 --- a/docs/txn-advanced-features.md +++ b/docs/txn-advanced-features.md @@ -37,10 +37,33 @@ If you want to enable authentication with transactions, follow the steps below. 2. [Configure authentication](security-overview/#authentication) in a Pulsar client. +## Select transaction isolation level + +To enhance the flexibility of Pulsar transactions, they support two distinct isolation levels: +- `READ_COMMITTED`(default): The consumer can only consume all transactional messages that have been committed. +- `READ_UNCOMMITTED`: The consumer can consume all messages, even transactional messages that have been aborted. + +For different scenarios, they use different subscriptions and choose different isolation levels. One scenario might require transactions, while another might not. In general, not all subscriptions of the same topic require transaction guarantees. Some want low latency without the exact-once semantic guarantee (like a real-time monitoring system), and some must require the exactly-once guarantee (e.g., business processing systems). +Users can freely choose different isolation levels according to different scenarios. + +Note that this is a subscription-level configuration, and all consumers under the same subscription must be configured with the same isolation level. + +In this example, the consumer builder uses the `READ_UNCOMMITTED` isolation level. + +```java +Consumer consumer = client + .newConsumer(Schema.STRING) + .topic("persistent://my-tenant/my-namespace/my-topic") + .subscriptionName("my-subscription") + .subscriptionType(SubscriptionType.Shared) + .subscriptionIsolationLevel(SubscriptionIsolationLevel.READ_UNCOMMITTED) // Adding the isolation level configuration + .subscribe(); +``` + ## Guarantee exactly-once semantics If you want to guarantee exactly-once semantics with transactions, you can [enable message deduplication at the broker, namespace, or topic level](cookbooks-deduplication.md#enable-message-deduplication-at-namespace-or-topic-level). ## Related topics -- To get up quickly, see [Pulsar transactions - Get started](txn-use.md). \ No newline at end of file +- To get up quickly, see [Pulsar transactions - Get started](txn-use.md). From 907f91192533b6c8db62790ad1ea71cf9b8ffaf9 Mon Sep 17 00:00:00 2001 From: Lari Hotari Date: Tue, 29 Oct 2024 09:12:03 +0200 Subject: [PATCH 2/2] Apply docs to versioned_docs after 3.2.x --- .../version-3.2.x/txn-advanced-features.md | 25 ++++++++++++++++++- .../version-3.3.x/txn-advanced-features.md | 25 ++++++++++++++++++- .../version-4.0.x/txn-advanced-features.md | 25 ++++++++++++++++++- 3 files changed, 72 insertions(+), 3 deletions(-) diff --git a/versioned_docs/version-3.2.x/txn-advanced-features.md b/versioned_docs/version-3.2.x/txn-advanced-features.md index 8819fcf8fba3..f00aa6f858c7 100644 --- a/versioned_docs/version-3.2.x/txn-advanced-features.md +++ b/versioned_docs/version-3.2.x/txn-advanced-features.md @@ -37,10 +37,33 @@ If you want to enable authentication with transactions, follow the steps below. 2. [Configure authentication](security-overview/#authentication) in a Pulsar client. +## Select transaction isolation level + +To enhance the flexibility of Pulsar transactions, they support two distinct isolation levels: +- `READ_COMMITTED`(default): The consumer can only consume all transactional messages that have been committed. +- `READ_UNCOMMITTED`: The consumer can consume all messages, even transactional messages that have been aborted. + +For different scenarios, they use different subscriptions and choose different isolation levels. One scenario might require transactions, while another might not. In general, not all subscriptions of the same topic require transaction guarantees. Some want low latency without the exact-once semantic guarantee (like a real-time monitoring system), and some must require the exactly-once guarantee (e.g., business processing systems). +Users can freely choose different isolation levels according to different scenarios. + +Note that this is a subscription-level configuration, and all consumers under the same subscription must be configured with the same isolation level. + +In this example, the consumer builder uses the `READ_UNCOMMITTED` isolation level. + +```java +Consumer consumer = client + .newConsumer(Schema.STRING) + .topic("persistent://my-tenant/my-namespace/my-topic") + .subscriptionName("my-subscription") + .subscriptionType(SubscriptionType.Shared) + .subscriptionIsolationLevel(SubscriptionIsolationLevel.READ_UNCOMMITTED) // Adding the isolation level configuration + .subscribe(); +``` + ## Guarantee exactly-once semantics If you want to guarantee exactly-once semantics with transactions, you can [enable message deduplication at the broker, namespace, or topic level](cookbooks-deduplication.md#enable-message-deduplication-at-namespace-or-topic-level). ## Related topics -- To get up quickly, see [Pulsar transactions - Get started](txn-use.md). \ No newline at end of file +- To get up quickly, see [Pulsar transactions - Get started](txn-use.md). diff --git a/versioned_docs/version-3.3.x/txn-advanced-features.md b/versioned_docs/version-3.3.x/txn-advanced-features.md index 8819fcf8fba3..f00aa6f858c7 100644 --- a/versioned_docs/version-3.3.x/txn-advanced-features.md +++ b/versioned_docs/version-3.3.x/txn-advanced-features.md @@ -37,10 +37,33 @@ If you want to enable authentication with transactions, follow the steps below. 2. [Configure authentication](security-overview/#authentication) in a Pulsar client. +## Select transaction isolation level + +To enhance the flexibility of Pulsar transactions, they support two distinct isolation levels: +- `READ_COMMITTED`(default): The consumer can only consume all transactional messages that have been committed. +- `READ_UNCOMMITTED`: The consumer can consume all messages, even transactional messages that have been aborted. + +For different scenarios, they use different subscriptions and choose different isolation levels. One scenario might require transactions, while another might not. In general, not all subscriptions of the same topic require transaction guarantees. Some want low latency without the exact-once semantic guarantee (like a real-time monitoring system), and some must require the exactly-once guarantee (e.g., business processing systems). +Users can freely choose different isolation levels according to different scenarios. + +Note that this is a subscription-level configuration, and all consumers under the same subscription must be configured with the same isolation level. + +In this example, the consumer builder uses the `READ_UNCOMMITTED` isolation level. + +```java +Consumer consumer = client + .newConsumer(Schema.STRING) + .topic("persistent://my-tenant/my-namespace/my-topic") + .subscriptionName("my-subscription") + .subscriptionType(SubscriptionType.Shared) + .subscriptionIsolationLevel(SubscriptionIsolationLevel.READ_UNCOMMITTED) // Adding the isolation level configuration + .subscribe(); +``` + ## Guarantee exactly-once semantics If you want to guarantee exactly-once semantics with transactions, you can [enable message deduplication at the broker, namespace, or topic level](cookbooks-deduplication.md#enable-message-deduplication-at-namespace-or-topic-level). ## Related topics -- To get up quickly, see [Pulsar transactions - Get started](txn-use.md). \ No newline at end of file +- To get up quickly, see [Pulsar transactions - Get started](txn-use.md). diff --git a/versioned_docs/version-4.0.x/txn-advanced-features.md b/versioned_docs/version-4.0.x/txn-advanced-features.md index 8819fcf8fba3..f00aa6f858c7 100644 --- a/versioned_docs/version-4.0.x/txn-advanced-features.md +++ b/versioned_docs/version-4.0.x/txn-advanced-features.md @@ -37,10 +37,33 @@ If you want to enable authentication with transactions, follow the steps below. 2. [Configure authentication](security-overview/#authentication) in a Pulsar client. +## Select transaction isolation level + +To enhance the flexibility of Pulsar transactions, they support two distinct isolation levels: +- `READ_COMMITTED`(default): The consumer can only consume all transactional messages that have been committed. +- `READ_UNCOMMITTED`: The consumer can consume all messages, even transactional messages that have been aborted. + +For different scenarios, they use different subscriptions and choose different isolation levels. One scenario might require transactions, while another might not. In general, not all subscriptions of the same topic require transaction guarantees. Some want low latency without the exact-once semantic guarantee (like a real-time monitoring system), and some must require the exactly-once guarantee (e.g., business processing systems). +Users can freely choose different isolation levels according to different scenarios. + +Note that this is a subscription-level configuration, and all consumers under the same subscription must be configured with the same isolation level. + +In this example, the consumer builder uses the `READ_UNCOMMITTED` isolation level. + +```java +Consumer consumer = client + .newConsumer(Schema.STRING) + .topic("persistent://my-tenant/my-namespace/my-topic") + .subscriptionName("my-subscription") + .subscriptionType(SubscriptionType.Shared) + .subscriptionIsolationLevel(SubscriptionIsolationLevel.READ_UNCOMMITTED) // Adding the isolation level configuration + .subscribe(); +``` + ## Guarantee exactly-once semantics If you want to guarantee exactly-once semantics with transactions, you can [enable message deduplication at the broker, namespace, or topic level](cookbooks-deduplication.md#enable-message-deduplication-at-namespace-or-topic-level). ## Related topics -- To get up quickly, see [Pulsar transactions - Get started](txn-use.md). \ No newline at end of file +- To get up quickly, see [Pulsar transactions - Get started](txn-use.md).