# Setup Azure CosmosDB 

## Creating an Azure CosmosDB account

[Follow the instructions](https://docs.microsoft.com/en-us/azure/cosmos-db/how-to-manage-database-account) from the Azure documentation on how to create an Azure CosmosDB account.  The database and collection must be created in CosmosDB before Dapr can use it.  

**Note : The partition key for the collection must be named "/partitionKey".  Note: this is case-sensitive.**

In order to setup CosmosDB as a state store, you need the following properties:

* **URL**: the CosmosDB url. for example: https://******.documents.azure.com:443/
* **Master Key**: The key to authenticate to the CosmosDB account
* **Database**: The name of the database
* **Collection**: The name of the collection

## Create a Dapr component

The next step is to create a Dapr component for CosmosDB.

Create the following YAML file named `cosmosdb.yaml`:

```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
  namespace: <NAMESPACE>
spec:
  type: state.azure.cosmosdb
  metadata:
  - name: url
    value: <REPLACE-WITH-URL>
  - name: masterKey
    value: <REPLACE-WITH-MASTER-KEY>
  - name: database
    value: <REPLACE-WITH-DATABASE>
  - name: collection
    value: <REPLACE-WITH-COLLECTION>
```

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here](../../concepts/secrets/README.md)

Here is an example of what the values could look like:

```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: statestore
spec:
  type: state.azure.cosmosdb
  metadata:
  - name: url
    value: https://accountname.documents.azure.com:443
  - name: masterKey
    value: thekey==
  - name: database
    value: db1
  - name: collection
    value: c1
```
The following example uses the Kubernetes secret store to retrieve the secrets:

```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
  namespace: <NAMESPACE>
spec:
  type: state.azure.cosmosdb
  metadata:
  - name: url
    value: <REPLACE-WITH-URL>
  - name: masterKey
    secretKeyRef:
      name: <KUBERNETES-SECRET-NAME>
      key: <KUBERNETES-SECRET-KEY>
  - name: database
    value: <REPLACE-WITH-DATABASE>
  - name: collection
    value: <REPLACE-WITH-COLLECTION>
```

If you wish to use CosmosDb as an actor store, append the following to the yaml.

```yaml
  - name: actorStateStore
    value: "true"
```

## Apply the configuration

### In Kubernetes

To apply the CosmosDB state store to Kubernetes, use the `kubectl` CLI:

```
kubectl apply -f cosmos.yaml
```

### Running locally

To run locally, create a YAML file described above and provide the path to the `dapr run` command with the flag `--components-path`.  See [this](https://github.com/dapr/cli#use-non-default-components-path) or run `dapr run --help` for more information on the path.

## Data format

To use the cosmos state store, your data must be sent to Dapr in json-serialized.  Having it just json *serializable* will not work.

If you are using the Dapr SDKs (e.g. https://github.com/dapr/dotnet-sdk) the SDK will serialize your data to json.

For examples see the curl operations in the [Partition keys](#partition-keys) section.

## Partition keys


For **non-actor state** operations, the Azure CosmosDB state store will use the `key` property provided in the requests to the Dapr API to determine the CosmosDB partition key.  This can be overridden by specifying a metadata field in the request with a key of `partitionKey` and a value of the desired partition.

The following operation will use `nihilus` as the partition key value sent to CosmosDB:

```shell
curl -X POST http://localhost:3500/v1.0/state/<store_name> \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "nihilus",
          "value": "darth"
        }
      ]'
```

For **non-actor** state operations, if you want to control the CosmosDB partition, you can specify it in metadata.  Reusing the example above, here's how to put it under the `mypartition` partition

```shell
curl -X POST http://localhost:3500/v1.0/state/<store_name> \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "nihilus",
          "value": "darth",
          "metadata": {
            "partitionKey": "mypartition"
          }
        }
      ]'
```
     

For **actor** state operations, the partition key will be generated by Dapr using the appId, the actor type, and the actor id, such that data for the same actor will always end up under the same partition (you do not need to specify it).  This is because actor state operations must use transactions, and in CosmosDB the items in a transaction must be on the same partition.