From cbb84ba8a69afb795e5e21abe79b460f4f9058c9 Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Thu, 14 Apr 2022 18:28:54 -0500 Subject: [PATCH 1/5] clarify transactional operations in docs Signed-off-by: Hannah Hunter --- .../state-management/state-management-overview.md | 12 +++++++++--- daprdocs/content/en/reference/api/state_api.md | 11 +++++++++-- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md index d6c48658002..bbba34b748a 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md @@ -66,11 +66,17 @@ With the HTTP API, you can set content type via URL query parameter `metadata.co With the gRPC API, you can set content type by adding key/value pair `"contentType" : ` to the request metadata. -### Bulk operations +### Operations -Dapr supports two types of bulk operations: **bulk** or **multi**. You can group several requests of the same type into a bulk (or a batch). Dapr submits requests in bulk operations as individual requests to the underlying data store. In other words, bulk operations are not transactional. On the other hand, you can group requests of different types into a multi-operation, which is then handled as an atomic transaction. +Dapr supports two types of bulk operations: **bulk** or **transactional**. Read the [API reference]({{< ref state_api.md >}}) to learn how use bulk and multi options. -Read the [API reference]({{< ref state_api.md >}}) to learn how use bulk and multi options. +#### Bulk operations + +You can group several requests of the same type into a bulk (or batch). Dapr submits requests in bulk operations as individual requests to the underlying data store. + +#### Transactional operations + +You can group requests of different types into a multi-item operation, which is then handled as an atomic transaction. Requests will succeed or fail as a group. ### State encryption Dapr supports automatic client encryption of application state with support for key rotations. This is supported on all Dapr state stores. For more info, read the [How-To: Encrypt application state]({{< ref howto-encrypt-state.md >}}) topic. diff --git a/daprdocs/content/en/reference/api/state_api.md b/daprdocs/content/en/reference/api/state_api.md index 375b775ab95..be344fb7b7e 100644 --- a/daprdocs/content/en/reference/api/state_api.md +++ b/daprdocs/content/en/reference/api/state_api.md @@ -443,7 +443,7 @@ POST http://localhost:3500/v1.0-alpha1/state/myStore/query?metadata.partitionKey ## State transactions -Persists the changes to the state store as a multi-item transaction. +Persists the changes to the state store as a [multi-item transaction]({{< ref "state-management-overview.md#transactional-operations" >}}). > This operation depends on a state store component that supports multi-item transactions. @@ -484,7 +484,14 @@ Field | Description `operations` | A JSON array of state operation `metadata` | (optional) The metadata for transaction that applies to all operations -Each state operation is comprised with the following fields: +All transactional databases implement the following required operations: + +Operation | Description +--------- | ----------- +`upsert` | Adds or updates the value +`delete` | Deletes the value + +Each operation is comprised of the following fields: Field | Description ---- | ----------- From 55af978248b9fa6321ed32e6c7d1a56daecbf8f3 Mon Sep 17 00:00:00 2001 From: Mark Fussell Date: Fri, 15 Apr 2022 15:10:38 -0700 Subject: [PATCH 2/5] Added some more details for clarity --- daprdocs/content/en/reference/api/state_api.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/daprdocs/content/en/reference/api/state_api.md b/daprdocs/content/en/reference/api/state_api.md index be344fb7b7e..a04a7f9a0f3 100644 --- a/daprdocs/content/en/reference/api/state_api.md +++ b/daprdocs/content/en/reference/api/state_api.md @@ -445,7 +445,7 @@ POST http://localhost:3500/v1.0-alpha1/state/myStore/query?metadata.partitionKey Persists the changes to the state store as a [multi-item transaction]({{< ref "state-management-overview.md#transactional-operations" >}}). -> This operation depends on a state store component that supports multi-item transactions. +> This API depends on a state store component that supports transactions. Refer to the [state store component spec]({{< ref "supported-state-stores.md" >}}) for a full, current list of state stores that support transactions. @@ -481,8 +481,8 @@ POST http://localhost:3500/v1.0/state/myStore/transaction?metadata.contentType=a Field | Description ---- | ----------- -`operations` | A JSON array of state operation -`metadata` | (optional) The metadata for transaction that applies to all operations +`operations` | A JSON array of state `operation` +`metadata` | (optional) The `metadata` for the transaction that applies to all operations All transactional databases implement the following required operations: @@ -491,17 +491,18 @@ Operation | Description `upsert` | Adds or updates the value `delete` | Deletes the value -Each operation is comprised of the following fields: +Each operation has an associated `request` that is comprised of the following fields: -Field | Description +Request | Description ---- | ----------- `key` | State key `value` | State value, which can be any byte array `etag` | (optional) State ETag -`metadata` | (optional) Additional key-value pairs to be passed to the state store +`metadata` | (optional) Additional key-value pairs to be passed to the state store that apply for this operation `options` | (optional) State operation options; see [state operation options](#optional-behaviors) #### Examples +The example below shows an `upsert` operation for `key1` and a `delete` operation for `key2`. This is applied to the partition named 'planet' in the state store. Both operations either succeed or fail in the transaction. ```shell curl -X POST http://localhost:3500/v1.0/state/starwars/transaction \ From 47d54ef66a350b63a88d8b6f4e4ca34f361c9084 Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Fri, 15 Apr 2022 17:39:17 -0500 Subject: [PATCH 3/5] updates per Mark Signed-off-by: Hannah Hunter --- .../state-management/state-management-overview.md | 10 +++++----- daprdocs/content/en/reference/api/state_api.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md index bbba34b748a..93a42e4e9ee 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md @@ -66,17 +66,17 @@ With the HTTP API, you can set content type via URL query parameter `metadata.co With the gRPC API, you can set content type by adding key/value pair `"contentType" : ` to the request metadata. -### Operations +### Multiple operations -Dapr supports two types of bulk operations: **bulk** or **transactional**. Read the [API reference]({{< ref state_api.md >}}) to learn how use bulk and multi options. +Dapr supports two types of mult-read or multi-write operations: **bulk** or **transactional**. Read the [API reference]({{< ref state_api.md >}}) to learn how use bulk and multi options. -#### Bulk operations +#### Bulk read operations -You can group several requests of the same type into a bulk (or batch). Dapr submits requests in bulk operations as individual requests to the underlying data store. +You can group multiple read requests into a bulk (or batch) operation. In the bulk operation, Dapr submits the read requests as individual requests to the underlying data store, and returns them as a single result. #### Transactional operations -You can group requests of different types into a multi-item operation, which is then handled as an atomic transaction. Requests will succeed or fail as a group. +You can group write, update and delete operations into a request, which are then handled as an atomic transaction. The request will succeed or fail as a transactional set of operations. ### State encryption Dapr supports automatic client encryption of application state with support for key rotations. This is supported on all Dapr state stores. For more info, read the [How-To: Encrypt application state]({{< ref howto-encrypt-state.md >}}) topic. diff --git a/daprdocs/content/en/reference/api/state_api.md b/daprdocs/content/en/reference/api/state_api.md index a04a7f9a0f3..011d4d595db 100644 --- a/daprdocs/content/en/reference/api/state_api.md +++ b/daprdocs/content/en/reference/api/state_api.md @@ -443,7 +443,7 @@ POST http://localhost:3500/v1.0-alpha1/state/myStore/query?metadata.partitionKey ## State transactions -Persists the changes to the state store as a [multi-item transaction]({{< ref "state-management-overview.md#transactional-operations" >}}). +Persists the changes to the state store as a [transactional operation]({{< ref "state-management-overview.md#transactional-operations" >}}). > This API depends on a state store component that supports transactions. From c9d16964b6c9fc539dc482b1ee565f541f26756a Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Fri, 15 Apr 2022 17:40:37 -0500 Subject: [PATCH 4/5] remove en from link Signed-off-by: Hannah Hunter --- daprdocs/content/en/contributing/codespaces.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/contributing/codespaces.md b/daprdocs/content/en/contributing/codespaces.md index 993f3e2bd7f..89d250c39e5 100644 --- a/daprdocs/content/en/contributing/codespaces.md +++ b/daprdocs/content/en/contributing/codespaces.md @@ -46,4 +46,4 @@ git reset --hard ``` ## Related links -- [GitHub documentation](https://docs.github.com/en/github/developing-online-with-codespaces/about-codespaces) +- [GitHub documentation](https://docs.github.com/github/developing-online-with-codespaces/about-codespaces) From 166847d06d3d554d505c0f6fc1a0fe00fbee724a Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Fri, 15 Apr 2022 17:48:12 -0500 Subject: [PATCH 5/5] ignore links attempt Signed-off-by: Hannah Hunter --- daprdocs/content/en/contributing/codespaces.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/daprdocs/content/en/contributing/codespaces.md b/daprdocs/content/en/contributing/codespaces.md index 89d250c39e5..111f04d9be8 100644 --- a/daprdocs/content/en/contributing/codespaces.md +++ b/daprdocs/content/en/contributing/codespaces.md @@ -46,4 +46,6 @@ git reset --hard ``` ## Related links + - [GitHub documentation](https://docs.github.com/github/developing-online-with-codespaces/about-codespaces) +