This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Work with backend state stores

Guides for working with specific backend states stores

1: Azure Cosmos DB
2: Redis
3: SQL server

Explore the Operations section to see a list of supported state stores and how to setup state store components.

1 - Azure Cosmos DB

Use Azure Cosmos DB as a state store

Dapr doesn’t transform state values while saving and retrieving states. Dapr requires all state store implementations to abide by a certain key format scheme (see the state management spec. You can directly interact with the underlying store to manipulate the state data, such as:

Querying states.
Creating aggregated views.
Making backups.

Note

Azure Cosmos DB is a multi-modal database that supports multiple APIs. The default Dapr Cosmos DB state store implementation uses the Azure Cosmos DB SQL API.

Connect to Azure Cosmos DB

To connect to your Cosmos DB instance, you can either:

Use the Data Explorer on Azure Management Portal.
Use various SDKs and tools.

Note

When you configure an Azure Cosmos DB for Dapr, specify the exact database and collection to use. The following Cosmos DB SQL API samples assume you’ve already connected to the right database and a collection named “states”.

List keys by App ID

To get all state keys associated with application “myapp”, use the query:

SELECT * FROM states WHERE CONTAINS(states.id, 'myapp||')

The above query returns all documents with an id containing “myapp-”, which is the prefix of the state keys.

Get specific state data

To get the state data by a key “balance” for the application “myapp”, use the query:

SELECT * FROM states WHERE states.id = 'myapp||balance'

Read the value field of the returned document. To get the state version/ETag, use the command:

SELECT states._etag FROM states WHERE states.id = 'myapp||balance'

Read actor state

To get all the state keys associated with an actor with the instance ID “leroy” of actor type “cat” belonging to the application with ID “mypets”, use the command:

SELECT * FROM states WHERE CONTAINS(states.id, 'mypets||cat||leroy||')

And to get a specific actor state such as “food”, use the command:

SELECT * FROM states WHERE states.id = 'mypets||cat||leroy||food'

Warning

You should not manually update or delete states in the store. All writes and delete operations should be done via the Dapr runtime. The only exception: it is often required to delete actor records in a state store, once you know that these are no longer in use, to prevent a build up of unused actor instances that may never be loaded again.

2 - Redis

Use Redis as a state store

Dapr doesn’t transform state values while saving and retrieving states. Dapr requires all state store implementations to abide by a certain key format scheme (see the state management spec. You can directly interact with the underlying store to manipulate the state data, such as:

Querying states.
Creating aggregated views.
Making backups.

Note

The following examples uses Redis CLI against a Redis store using the default Dapr state store implementation.

Connect to Redis

You can use the official redis-cli or any other Redis compatible tools to connect to the Redis state store to query Dapr states directly. If you are running Redis in a container, the easiest way to use redis-cli is via a container:

docker run --rm -it --link <name of the Redis container> redis redis-cli -h <name of the Redis container>

List keys by App ID

To get all state keys associated with application “myapp”, use the command:

KEYS myapp*

The above command returns a list of existing keys, for example:

1) "myapp||balance"
2) "myapp||amount"

Get specific state data

Dapr saves state values as hash values. Each hash value contains a “data” field, which contains:

The state data.
A “version” field, with an ever-incrementing version serving as the ETag.

For example, to get the state data by a key “balance” for the application “myapp”, use the command:

HGET myapp||balance data

To get the state version/ETag, use the command:

HGET myapp||balance version

Read actor state

To get all the state keys associated with an actor with the instance ID “leroy” of actor type “cat” belonging to the application with ID “mypets”, use the command:

KEYS mypets||cat||leroy*

To get a specific actor state such as “food”, use the command:

HGET mypets||cat||leroy||food value

Warning

You should not manually update or delete states in the store. All writes and delete operations should be done via the Dapr runtime. The only exception: it is often required to delete actor records in a state store, once you know that these are no longer in use, to prevent a build up of unused actor instances that may never be loaded again.

3 - SQL server

Use SQL server as a backend state store

Dapr doesn’t transform state values while saving and retrieving states. Dapr requires all state store implementations to abide by a certain key format scheme (see the state management spec. You can directly interact with the underlying store to manipulate the state data, such as:

Querying states.
Creating aggregated views.
Making backups.

Connect to SQL Server

The easiest way to connect to your SQL Server instance is to use the:

Azure Data Studio (Windows, macOS, Linux)
SQL Server Management Studio (Windows)

Note

When you configure an Azure SQL database for Dapr, you need to specify the exact table name to use. The following Azure SQL samples assume you’ve already connected to the right database with a table named “states”.

List keys by App ID

To get all state keys associated with application “myapp”, use the query:

SELECT * FROM states WHERE [Key] LIKE 'myapp||%'

The above query returns all rows with id containing “myapp||”, which is the prefix of the state keys.

Get specific state data

To get the state data by a key “balance” for the application “myapp”, use the query:

SELECT * FROM states WHERE [Key] = 'myapp||balance'

Read the Data field of the returned row. To get the state version/ETag, use the command:

SELECT [RowVersion] FROM states WHERE [Key] = 'myapp||balance'

Get filtered state data

To get all state data where the value “color” in json data equals to “blue”, use the query:

SELECT * FROM states WHERE JSON_VALUE([Data], '$.color') = 'blue'

Read actor state

To get all the state keys associated with an actor with the instance ID “leroy” of actor type “cat” belonging to the application with ID “mypets”, use the command:

SELECT * FROM states WHERE [Key] LIKE 'mypets||cat||leroy||%'

To get a specific actor state such as “food”, use the command:

SELECT * FROM states WHERE [Key] = 'mypets||cat||leroy||food'

Warning

You should not manually update or delete states in the store. All writes and delete operations should be done via the Dapr runtime. The only exception: it is often required to delete actor records in a state store, once you know that these are no longer in use, to prevent a build up of unused actor instances that may never be loaded again.