diff --git a/daprdocs/content/en/developing-applications/building-blocks/actors/actors-overview.md b/daprdocs/content/en/developing-applications/building-blocks/actors/actors-overview.md index 36676f36e..ada5c602a 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/actors/actors-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/actors/actors-overview.md @@ -90,15 +90,6 @@ The Dapr actor runtime provides a simple turn-based access model for accessing a Transactional state stores can be used to store actor state. To specify which state store to use for actors, specify value of property `actorStateStore` as `true` in the state store component's metadata section. Actors state is stored with a specific scheme in transactional state stores, allowing for consistent querying. Only a single state store component can be used as the state store for all actors. Read the [state API reference]({{< ref state_api.md >}}) and the [actors API reference]({{< ref actors_api.md >}}) to learn more about state stores for actors. -#### Time to Live (TTL) on state -You should always set the TTL metadata field (`ttlInSeconds`), or the equivalent API call in your chosen SDK when saving actor state to ensure that state eventually removed. Read [actors overview]({{< ref actors-overview.md >}}) for more information. - -#### Demo - -Watch this video for a demo on [Actor State TTL](https://youtu.be/kVpQYkGemRc?t=20) from the Dapr Community Call #80: - - - ### Actor timers and reminders Actors can schedule periodic work on themselves by registering either timers or reminders. diff --git a/daprdocs/content/en/operations/support/support-preview-features.md b/daprdocs/content/en/operations/support/support-preview-features.md index 92522d496..085b8644a 100644 --- a/daprdocs/content/en/operations/support/support-preview-features.md +++ b/daprdocs/content/en/operations/support/support-preview-features.md @@ -21,6 +21,7 @@ For CLI there is no explicit opt-in, just the version that this was first made a | **Multi-App Run** | Configure multiple Dapr applications from a single configuration file and run from a single command | `dapr run -f` | [Multi-App Run]({{< ref multi-app-dapr-run.md >}}) | v1.10 | | **Workflows** | Author workflows as code to automate and orchestrate tasks within your application, like messaging, state management, and failure handling | N/A | [Workflows concept]({{< ref "components-concept#workflows" >}})| v1.10 | | **Service invocation for non-Dapr endpoints** | Allow the invocation of non-Dapr endpoints by Dapr using the [Service invocation API]({{< ref service_invocation_api.md >}}). Read ["How-To: Invoke Non-Dapr Endpoints using HTTP"]({{< ref howto-invoke-non-dapr-endpoints.md >}}) for more information. | N/A | [Service invocation API]({{< ref service_invocation_api.md >}}) | v1.11 | +| **Actor State TTL** | Allow actors to save records to state stores with Time To Live (TTL) set to automatically clean up old data. In its current implementation, actor state with TTL may not be reflected correctly by clients, read [Actor State Transactions]({{< ref actors_api.md >}}) for more information. | `ActorStateTTL` | [Actor State Transactions]({{< ref actors_api.md >}}) | v1.11 | ### Streaming for HTTP service invocation diff --git a/daprdocs/content/en/reference/api/actors_api.md b/daprdocs/content/en/reference/api/actors_api.md index 180bea672..5e4bbd579 100644 --- a/daprdocs/content/en/reference/api/actors_api.md +++ b/daprdocs/content/en/reference/api/actors_api.md @@ -75,10 +75,15 @@ Persists the change to the state for an actor as a multi-item transaction. ***Note that this operation is dependant on a using state store component that supports multi-item transactions.*** -When putting state, _always_ set the `ttlInSeconds` field in the -metadata for each value, unless there is a state clean up process out of band of -Dapr. Omitting this field will result in the underlying Actor state store to -grow indefinitely. +#### TTL + +With the [`ActorStateTTL` feature enabled]]({{< ref +"support-preview-features.md" >}}), actor clients can set the `ttlInSeconds` +field in the transaction metadata to have the state expire after that many +seconds. If the `ttlInSeconds` field is not set, the state will not expire. + +Keep in mind when building actor applications with this feature enabled; +Currently, all actor SDKs will preserve the actor state in their local cache even after the state has expired. This means that the actor state will not be removed from the local cache if the TTL has expired until the actor is restarted or deactivated. This behaviour will be changed in a future release. See the Dapr Community Call 80 recording for more details on actor state TTL. @@ -109,6 +114,8 @@ Parameter | Description #### Examples +> Note, the following example uses the `ttlInSeconds` field, which requires the [`ActorStateTTL` feature enabled]]({{< ref "support-preview-features.md" >}}). + ```shell curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state \ -H "Content-Type: application/json" \