- Join us for DaprCon on October 19th-20th, 2021!
+ Watch DaprCon sessions on-demand!
- The first ever DaprCon will take place October 19th-20th, 2021 virtually! Tune in for free and attend technical sessions, panels and real world examples from the community on building applications with Dapr!
Learn more >>
+ The first ever DaprCon took place October 19th-20th, 2021. Read this recap and find links to all on-demand content
Learn more >>
diff --git a/daprdocs/content/en/developing-applications/building-blocks/observability/w3c-tracing/w3c-tracing-howto.md b/daprdocs/content/en/developing-applications/building-blocks/observability/w3c-tracing/w3c-tracing-howto.md
index 99f26ba18..145b9cd59 100644
--- a/daprdocs/content/en/developing-applications/building-blocks/observability/w3c-tracing/w3c-tracing-howto.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/observability/w3c-tracing/w3c-tracing-howto.md
@@ -47,7 +47,7 @@ client.InvokeService(ctx, &pb.InvokeServiceRequest{
### Retrieve trace context in C#
#### For HTTP calls
-To retrieve the trace context from HTTP response, you can use [.NET API](https://docs.microsoft.com/en-us/dotnet/api/system.net.http.headers.httpresponseheaders?view=netcore-3.1) :
+To retrieve the trace context from HTTP response, you can use [.NET API](https://docs.microsoft.com/dotnet/api/system.net.http.headers.httpresponseheaders?view=netcore-3.1) :
```csharp
// client is HttpClient. req is HttpRequestMessage
@@ -75,7 +75,7 @@ var response = await call.ResponseAsync;
var headers = await call.ResponseHeadersAsync();
var tracecontext = headers.First(e => e.Key == "grpc-trace-bin");
```
-Additional general details on calling gRPC services with .NET client [here](https://docs.microsoft.com/en-us/aspnet/core/grpc/client?view=aspnetcore-3.1).
+Additional general details on calling gRPC services with .NET client [here](https://docs.microsoft.com/aspnet/core/grpc/client?view=aspnetcore-3.1).
## How to propagate trace context in a request
`Note: There are no helper methods exposed in Dapr SDKs to propagate and retrieve trace context. You need to use http/gRPC clients to propagate and retrieve trace headers through http headers and gRPC metadata.`
@@ -109,7 +109,7 @@ You can then continuing passing this go context `ctx` in subsequent Dapr gRPC ca
### Pass trace context in C#
#### For HTTP calls
-To pass trace context in HTTP request, you can use [.NET API](https://docs.microsoft.com/en-us/dotnet/api/system.net.http.headers.httprequestheaders?view=netcore-3.1) :
+To pass trace context in HTTP request, you can use [.NET API](https://docs.microsoft.com/dotnet/api/system.net.http.headers.httprequestheaders?view=netcore-3.1) :
```csharp
// client is HttpClient. req is HttpRequestMessage
@@ -127,7 +127,7 @@ var headers = new Metadata();
headers.Add("grpc-trace-bin", tracecontext);
using var call = client.InvokeServiceAsync(req, headers);
```
-Additional general details on calling gRPC services with .NET client [here](https://docs.microsoft.com/en-us/aspnet/core/grpc/client?view=aspnetcore-3.1).
+Additional general details on calling gRPC services with .NET client [here](https://docs.microsoft.com/aspnet/core/grpc/client?view=aspnetcore-3.1).
## How to create trace context
You can create a trace context using the recommended OpenCensus SDKs. OpenCensus supports several different programming languages.
diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md
index 20f49f250..ca2c4289d 100644
--- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md
@@ -486,6 +486,33 @@ If you want to use your own custom CloudEvent, make sure to specify the content
Read about content types [here](#content-types), and about the [Cloud Events message format]({{< ref "pubsub-overview.md#cloud-events-message-format" >}}).
+#### Example
+
+{{< tabs "Dapr CLI" "HTTP API (Bash)" "HTTP API (PowerShell)">}}
+
+{{% codetab %}}
+Publish a custom CloudEvent to the `deathStarStatus` topic:
+```bash
+dapr publish --publish-app-id testpubsub --pubsub pubsub --topic deathStarStatus --data '{"specversion" : "1.0", "type" : "com.dapr.cloudevent.sent", "source" : "testcloudeventspubsub", "subject" : "Cloud Events Test", "id" : "someCloudEventId", "time" : "2021-08-02T09:00:00Z", "datacontenttype" : "application/cloudevents+json", "data" : {"status": "completed"}}'
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+Publish a custom CloudEvent to the `deathStarStatus` topic:
+```bash
+curl -X POST http://localhost:3500/v1.0/publish/pubsub/deathStarStatus -H "Content-Type: application/cloudevents+json" -d '{"specversion" : "1.0", "type" : "com.dapr.cloudevent.sent", "source" : "testcloudeventspubsub", "subject" : "Cloud Events Test", "id" : "someCloudEventId", "time" : "2021-08-02T09:00:00Z", "datacontenttype" : "application/cloudevents+json", "data" : {"status": "completed"}}'
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+Publish a custom CloudEvent to the `deathStarStatus` topic:
+```powershell
+Invoke-RestMethod -Method Post -ContentType 'application/cloudevents+json' -Body '{"specversion" : "1.0", "type" : "com.dapr.cloudevent.sent", "source" : "testcloudeventspubsub", "subject" : "Cloud Events Test", "id" : "someCloudEventId", "time" : "2021-08-02T09:00:00Z", "datacontenttype" : "application/cloudevents+json", "data" : {"status": "completed"}}' -Uri 'http://localhost:3500/v1.0/publish/pubsub/deathStarStatus'
+```
+{{% /codetab %}}
+
+{{< /tabs >}}
+
## Next steps
- Try the [Pub/Sub quickstart sample](https://github.com/dapr/quickstarts/tree/master/pub-sub)
@@ -494,4 +521,4 @@ Read about content types [here](#content-types), and about the [Cloud Events mes
- Learn about [message time-to-live]({{< ref pubsub-message-ttl.md >}})
- Learn [how to configure Pub/Sub components with multiple namespaces]({{< ref pubsub-namespaces.md >}})
- List of [pub/sub components]({{< ref setup-pubsub >}})
-- Read the [API reference]({{< ref pubsub_api.md >}})
+- Read the [API reference]({{< ref pubsub_api.md >}})
\ No newline at end of file
diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-message-ttl.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-message-ttl.md
index 881908210..e2c998996 100644
--- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-message-ttl.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-message-ttl.md
@@ -22,7 +22,7 @@ When message time-to-live has native support in the pub/sub component, Dapr simp
#### Azure Service Bus
-Azure Service Bus supports [entity level time-to-live](https://docs.microsoft.com/en-us/azure/service-bus-messaging/message-expiration). This means that messages have a default time-to-live but can also be set with a shorter timespan at publishing time. Dapr propagates the time-to-live metadata for the message and lets Azure Service Bus handle the expiration directly.
+Azure Service Bus supports [entity level time-to-live](https://docs.microsoft.com/azure/service-bus-messaging/message-expiration). This means that messages have a default time-to-live but can also be set with a shorter timespan at publishing time. Dapr propagates the time-to-live metadata for the message and lets Azure Service Bus handle the expiration directly.
## Non-Dapr subscribers
diff --git a/daprdocs/content/en/developing-applications/building-blocks/secrets/secrets-overview.md b/daprdocs/content/en/developing-applications/building-blocks/secrets/secrets-overview.md
index f7490c38b..83516a008 100644
--- a/daprdocs/content/en/developing-applications/building-blocks/secrets/secrets-overview.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/secrets/secrets-overview.md
@@ -34,7 +34,7 @@ Applications can use the secrets API to access secrets from a Kubernetes secret
-In Azure Dapr can be configured to use Managed Identities to authenticate with Azure Key Vault in order to retrieve secrets. In the example below, an Azure Kubernetes Service (AKS) cluster is configured to use managed identities. Then Dapr uses [pod identities](https://docs.microsoft.com/en-us/azure/aks/operator-best-practices-identity#use-pod-identities) to retrieve secrets from Azure Key Vault on behalf of the application.
+In Azure Dapr can be configured to use Managed Identities to authenticate with Azure Key Vault in order to retrieve secrets. In the example below, an Azure Kubernetes Service (AKS) cluster is configured to use managed identities. Then Dapr uses [pod identities](https://docs.microsoft.com/azure/aks/operator-best-practices-identity#use-pod-identities) to retrieve secrets from Azure Key Vault on behalf of the application.
diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-state-query-api.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-state-query-api.md
new file mode 100644
index 000000000..011d8a7d8
--- /dev/null
+++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-state-query-api.md
@@ -0,0 +1,422 @@
+---
+type: docs
+title: "How-To: Query state"
+linkTitle: "How-To: Query state"
+weight: 250
+description: "API for querying state stores"
+---
+
+{{% alert title="alpha" color="warning" %}}
+The state query API is in **alpha** stage.
+{{% /alert %}}
+
+## Introduction
+
+The state query API provides a way of querying the key/value data stored in state store components. This query API is not a replacement for a complete query language, and is focused on retrieving, filtering and sorting key/value data that you have saved through the state management APIs.
+
+Even though the state store is a key/value store, the `value` might be a JSON document with its own hierarchy, keys, and values.
+The query API allows you to use those keys and values to retrive corresponding documents.
+
+This query API does not support querying of actor state stored in a state store. For that you need to use the query API for the specific database.
+See [querying actor state]({{< ref "state-management-overview.md#querying-actor-state" >}}).
+
+You can find additional information in the [related links]({{< ref "#related-links" >}}) section.
+
+## Querying the state
+
+You submit query requests via HTTP POST/PUT or gRPC.
+The body of the request is the JSON map with 3 entries: `filter`, `sort`, and `pagination`.
+
+The `filter` is an optional section. It specifies the query conditions in the form of a tree of key/value operations, where the key is the operator and the value is the operands.
+
+The following operations are supported:
+
+| Operator | Operands | Description |
+|----------|-------------|--------------|
+| `EQ` | key:value | key == value |
+| `IN` | key:[]value | key == value[0] OR key == value[1] OR ... OR key == value[n] |
+| `AND` | []operation | operation[0] AND operation[1] AND ... AND operation[n] |
+| `OR` | []operation | operation[0] OR operation[1] OR ... OR operation[n] |
+
+If `filter` section is omitted, the query returns all entries.
+
+The `sort` is an optional section and is an ordered array of `key:order` pairs, where `key` is a key in the state store, and the `order` is an optional string indicating sorting order: `"ASC"` for ascending and `"DESC"` for descending. If omitted, ascending order is the default.
+
+The `pagination` is an optional section containing `limit` and `token` parameters. `limit` sets the page size. `token` is an iteration token returned by the component, and is used in subsequent queries.
+
+For some background understanding, this query request is translated into the native query language and executed by the state store component.
+
+## Example data and query
+
+Let's look at some real examples, starting with simple and progressing towards more complex ones.
+
+As a dataset, let's consider a [collection of with employee records](../query-api-examples/dataset.json) containing employee ID, organization, state, and city.
+Notice that this dataset is an array of key/value pairs where `key` is the unique ID, and the `value` is the JSON object with employee record.
+To better illustrate functionality, let's have organization name (org) and employee ID (id) as a nested JSON person object.
+
+First, you need to create an instance of MongoDB, which is your state store.
+```bash
+docker run -d --rm -p 27017:27017 --name mongodb mongo:5
+```
+
+Next is to start a Dapr application. Refer to this [component configuration file](../query-api-examples/components/mongodb.yml), which instructs Dapr to use MongoDB as its state store.
+```bash
+dapr run --app-id demo --dapr-http-port 3500 --components-path query-api-examples/components
+```
+
+Now populate the state store with the employee dataset, so you can then query it later.
+```bash
+curl -X POST -H "Content-Type: application/json" -d @query-api-examples/dataset.json http://localhost:3500/v1.0/state/statestore
+```
+
+Once populated, you can examine the data in the state store. The image below a section of the MongoDB UI displaying employee records.
+
+
-
## Features
+These are the features available as part of the state management API:
### Pluggable state stores
-
Dapr data stores are modeled as components, which can be swapped out without any changes to your service code. See [supported state stores]({{< ref supported-state-stores >}}) to see the list.
-### Configurable state store behavior
-
-Dapr allows developers to attach additional metadata to a state operation request that describes how the request is expected to be handled. You can attach:
+### Configurable state store behaviors
+Dapr allows you to include additional metadata in a state operation request that describes how the request is expected to be handled. You can attach:
- Concurrency requirements
- Consistency requirements
By default, your application should assume a data store is **eventually consistent** and uses a **last-write-wins** concurrency pattern.
-[Not all stores are created equal]({{< ref supported-state-stores.md >}}). To ensure portability of your application you can query the capabilities of the store and make your code adaptive to different store capabilities.
+[Not all stores are created equal]({{< ref supported-state-stores.md >}}). To ensure portability of your application you can query the metadata capabilities of the store and make your code adaptive to different store capabilities.
### Concurrency
+Dapr supports Optimistic Concurrency Control (OCC) using ETags. When a state value is requested, Dapr always attaches an ETag property to the returned state. When the user code tries to update or delete a state, it’s expected to attach the ETag either through the request body for updates or the `If-Match` header for deletes. The write operation can succeed only when the provided ETag matches with the ETag in the state store.
-Dapr supports optimistic concurrency control (OCC) using ETags. When a state is requested, Dapr always attaches an ETag property to the returned state. When the user code tries to update or delete a state, it’s expected to attach the ETag either through the request body for updates or the `If-Match` header for deletes. The write operation can succeed only when the provided ETag matches with the ETag in the state store.
-
-Dapr chooses OCC because in many applications, data update conflicts are rare because clients are naturally partitioned by business contexts to operate on different data. However, if your application chooses to use ETags, a request may get rejected because of mismatched ETags. It's recommended that you use a retry policy to compensate for such conflicts when using ETags.
+Dapr chooses OCC because in many applications, data update conflicts are rare because clients are naturally partitioned by business contexts to operate on different data. However, if your application chooses to use ETags, a request may get rejected because of mismatched ETags. It's recommended that you use a retry policy in your code to compensate for such conflicts when using ETags.
If your application omits ETags in writing requests, Dapr skips ETag checks while handling the requests. This essentially enables the **last-write-wins** pattern, compared to the **first-write-wins** pattern with ETags.
@@ -50,14 +48,7 @@ For stores that don't natively support ETags, it's expected that the correspondi
Read the [API reference]({{< ref state_api.md >}}) to learn how to set concurrency options.
-### Automatic encryption
-
-Dapr supports automatic client encryption of application state with support for key rotations. This is a preview feature and it is supported on all Dapr state stores.
-
-For more info, read the [How-To: Encrypt application state]({{< ref howto-encrypt-state.md >}}) section.
-
### Consistency
-
Dapr supports both **strong consistency** and **eventual consistency**, with eventual consistency as the default behavior.
When strong consistency is used, Dapr waits for all replicas (or designated quorums) to acknowledge before it acknowledges a write request. When eventual consistency is used, Dapr returns as soon as the write request is accepted by the underlying data store, even if this is a single replica.
@@ -66,25 +57,40 @@ Read the [API reference]({{< ref state_api.md >}}) to learn how to set consisten
### Bulk 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 the bulk 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 handled as an atomic transaction.
+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.
Read the [API reference]({{< ref state_api.md >}}) to learn how use bulk and multi options.
+### 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.
+
+### Shared state between applications
+Different applications might have different needs when it comes to sharing state. For example, in one scenario you may want to encapsulate all state within a given application and have Dapr manage the access for you. In a different scenario, you may need to have two applications working on the same state be able to get and save the same keys. Dapr enable states to be isolated to an application, shared in a state store between applications or have multiple applications share state across different state stores. For more details read [How-To: Share state between applications]({{< ref howto-share-state.md >}}),
+
### Actor state
-Transactional state stores can be used to store actor state. To specify which state store to be used for actors, specify value of property `actorStateStore` as `true` in the metadata section of the state store component. Actors state is stored with a specific scheme in transactional state stores, which allows for consistent querying. Only a single state store component can be used as the statestore for all actors. Read the [API reference]({{< ref state_api.md >}}) to learn more about state stores for actors and the [actors API reference]({{< ref actors_api.md >}})
+Transactional state stores can be used to store actor state. To specify which state store to be used for actors, specify value of property `actorStateStore` as `true` in the metadata section of the state store component. Actors state is stored with a specific scheme in transactional state stores, which allows for consistent querying. Only a single state store component can be used as the state store for all actors. Read the [API reference]({{< ref state_api.md >}}) to learn more about state stores for actors and the [actors API reference]({{< ref actors_api.md >}})
-### Query state store directly
+### Querying state
+There are two ways to query the state:
+ * Using the [state management query API]({{< ref "#state-query-api" >}}) provided in Dapr runtime.
+ * Querying state store [directly]({{< ref "#query-state-store-directly" >}}) with the store's native SDK.
+#### Query API
+The query API provides a way of querying the key/value data saved using state management in state stores regardless of underlying database or storage technology. It is an optional state management API. Using the state management query API you can filter, sort and paginate the key/value data. For more details read [How-To: Query state]({{< ref howto-state-query-api.md >}}).
+
+#### Querying state store directly
Dapr saves and retrieves state values without any transformation. You can query and aggregate state directly from the [underlying state store]({{< ref query-state-store >}}).
-
For example, to get all state keys associated with an application ID "myApp" in Redis, use:
```bash
KEYS "myApp*"
```
-#### Querying actor state
+{{% alert title="Note on direct queries" color="primary" %}}
+Direct queries of the state store are not governed by Dapr concurrency control, since you are not calling through the Dapr runtime. What you see are snapshots of committed data which are acceptable for read-only queries across multiple actors, however writes should be done via the Dapr state management or actors APIs.
+{{% /alert %}}
+##### Querying actor state
If the data store supports SQL queries, you can query an actor's state using SQL queries. For example use:
```sql
@@ -97,20 +103,20 @@ You can also perform aggregate queries across actor instances, avoiding the comm
SELECT AVG(value) FROM StateTable WHERE Id LIKE '