From 796177ad3da286cb09fcc2390d1b63185ea6cce3 Mon Sep 17 00:00:00 2001 From: Haishi2016 Date: Sun, 6 Oct 2019 20:41:41 -0700 Subject: [PATCH] Update Cosmos DB how-to to query state store (#63) * update state store queries for cosmos db * update state concept links * apparently now it's called Azure Cosmos DB SQL API --- concepts/state-management/state-management.md | 2 +- .../query-state-store/query-cosmosdb-store.md | 49 +++++++++++++++++++ howto/query-state-store/query-redis-store.md | 13 +++-- 3 files changed, 60 insertions(+), 4 deletions(-) diff --git a/concepts/state-management/state-management.md b/concepts/state-management/state-management.md index 58f03ba83..85715f72b 100644 --- a/concepts/state-management/state-management.md +++ b/concepts/state-management/state-management.md @@ -84,4 +84,4 @@ SELECT AVG(value) FROM StateTable WHERE Id LIKE '--*-temper * [Spec: Dapr state managment specification](https://github.com/dapr/spec/blob/master/state.md) * [Spec: Dapr actors specification](https://github.com/dapr/spec/blob/master/actors.md) * [How-to: Query Redis store](../../howto/query-state-store/query-redis-store.md) -* [How-to: Query Azure Cosmos DB store](../../howto/query-state-store/query-redis-store.md) +* [How-to: Query Azure Cosmos DB store](../../howto/query-state-store/query-cosmosdb-store.md) diff --git a/howto/query-state-store/query-cosmosdb-store.md b/howto/query-state-store/query-cosmosdb-store.md index e69de29bb..df03ce8d7 100644 --- a/howto/query-state-store/query-cosmosdb-store.md +++ b/howto/query-state-store/query-cosmosdb-store.md @@ -0,0 +1,49 @@ +# Query Azure Cosmos DB state store + +Dapr doesn't transform state values while saving and retriving states. Dapr requires all state store implementations to abide by a certain key format scheme (see [Dapr state management spec](https://github.com/dapr/spec/blob/master/state.md)). You can directly interact with the underlying store to manipulate the state data, such querying states, creating aggregated views and 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](https://docs.microsoft.com/en-us/azure/cosmos-db/sql-query-getting-started). + +## 1. Connect to Azure Cosmos DB + +The easiest way to connect to your Cosmos DB instance is to use the Data Explorer on [Azure Management Portal](https://portal.azure.com). Alternatively, you can use [various SDKs and tools](https://docs.microsoft.com/en-us/azure/cosmos-db/mongodb-introduction). + +> **NOTE:** The following samples use Cosmos DB [SQL API](https://docs.microsoft.com/en-us/azure/cosmos-db/sql-query-getting-started). When you configure an Azure Cosmos DB for Dapr, you need to specify the exact database and collection to use. The follow samples asume you've already connected to the right database and a collection named "states". + +## 2. List keys by Dapr id + +To get all state keys associated with application "myapp", use the query: + +```sql +SELECT * FROM states WHERE CONTAINS(states.id, 'myapp-') +``` + +The above query returns all documents with id containing "myapp-", which is the prefix of the state keys. + +## 3. Get specific state data + +To get the state data by a key "balance" for the application "myapp", use the query: + +```bash +SELECT * FROM states WHERE states.id = 'myapp-balance' +``` +Then, read the **value** field of the returned document. + +To get the state version/ETag, use the command: +```bash +SELECT states._etag FROM states WHERE states.id = 'myapp-balance' +``` +## 4. 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: + +```bash +SELECT * FROM states WHERE CONTAINS(states.id, 'mypets-cat-leroy-') +``` +And to get a specific actor state such as "food", use the command: + +```bash +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. \ No newline at end of file diff --git a/howto/query-state-store/query-redis-store.md b/howto/query-state-store/query-redis-store.md index beadff453..5c12d3bba 100644 --- a/howto/query-state-store/query-redis-store.md +++ b/howto/query-state-store/query-redis-store.md @@ -4,7 +4,14 @@ Dapr doesn't transform state values while saving and retriving states. Dapr requ >**NOTE:** The following examples uses Redis CLI against a Redis store using the default Dapr state store implementation. -## 1. List keys by Dapr id +## 1. Connect to Redis + +You can use the official [redis-cli](https://redis.io/topics/rediscli) or any other Redis compatible tools to connect to the Redis state store to directly query Dapr states. If you are running Redis in a container, the easiest way to use redis-cli is to use a container: + +```bash +docker run --rm -it --link redis redis-cli -h +``` +## 2. List keys by Dapr id To get all state keys associated with application "myapp", use the command: @@ -18,7 +25,7 @@ The above command returns a list of existing keys, for example: 2) "myapp-amount" ``` -## 2. Get specific state data +## 3. Get specific state data Dapr saves state values as hash values. Each hash value contains a "data" field, which contains the state data and a "version" field, which contains an ever-incrementing version serving as the ETag. @@ -32,7 +39,7 @@ To get the state version/ETag, use the command: ```bash HGET myapp-balance version ``` -## 3. Read actor state +## 4. 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: