# Work with key value store
You must create a key value store to hold the key-value pairs that you want to use in CloudFront Functions.
After you create the key value stores and added key-value pairs, you can use the key values in your CloudFront function code.
To get started, see the following topics:
**Topics**
+ [Create a key value store](kvs-with-functions-create.md)
+ [Associate a key value store with a function](kvs-with-functions-associate.md)
+ [Update a key value store](kvs-with-functions-edit.md)
+ [Get a reference to a key value store](kvs-with-functions-get-reference.md)
+ [Delete a key value store](kvs-with-functions-delete.md)
+ [File format for key-value pairs](kvs-with-functions-create-s3-kvp.md)
**Note**
The JavaScript runtime 2.0 includes some helper methods for working with key values in the function code. For more information, see [Helper methods for key value stores](functions-custom-methods.md).
# Create a key value store
You can create a key value store and its key-value pairs at the same time. You can also create an empty key value store now and then add the key-value pairs later.
**Note**
If you specify your data source from an Amazon S3 bucket, you must have the `s3:GetObject` and `s3:GetBucketLocation` permissions to that bucket. If you don't have these permissions, CloudFront can't successfully create your key value store.
Decide if you want to add key-value pairs at the same time when you create the key value store. You can import your key-value pairs by using the CloudFront console, CloudFront API, or AWS SDKs. However, you can only import your file of key-value pairs when you *initially* create the key value store.
To create a file of key-value pairs, see [File format for key-value pairs](kvs-with-functions-create-s3-kvp.md).
------
#### [ Console ]
**To create a key value store**
1. Sign in to the AWS Management Console and open the **Functions** page in the CloudFront console at [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions).
1. Choose the **KeyValueStores** tab, and then choose **Create KeyValueStore**.
1. Enter a name and optional description for the key value store.
1. Complete **S3 URI**:
+ If you have a file of key-value pairs, enter the path to the Amazon S3 bucket where you stored the file.
+ Leave this field blank if you plan to enter the key-value pairs manually.
1. Choose **Create**. The key value store now exists.
The details page for the new key value store appears. The information on the page includes the ID and the ARN of the key value store.
+ The ID is a random string of characters that is unique in your AWS account.
+ The ARN has this syntax:
*AWS account*`:key-value-store/`*the key value stores ID*
1. Look at the **Key value pairs** section. If you imported a file, this section shows some key-value pairs. You can do the following:
+ If you imported a file, you can also add more values manually.
+ If you didn't import a file from an Amazon S3 bucket, and if you want to add key-value pairs now, you can complete the next step.
+ You can skip this step and add the key-value pairs later.
1. To add the pairs now:
1. Choose **Add key-value pairs**.
1. Choose **Add pair** and enter a name and value. Repeat this step to add more pairs.
1. When you're finished, choose **Save changes** to save all the key-value pairs in the key value store. On the dialog box that appears, choose **Done**.
1. To associate the key value store with a function now, complete the **Associated functions** section. For more information, see [Create functions](create-function.md) or [Update functions](update-function.md).
You can also associate the function later, either from this key value store details page, or from the function's details page.
------
#### [ AWS CLI ]
**To create a key value store**
+ Run the following command to create a key value store and import the key-value pairs from an Amazon S3 bucket.
```
aws cloudfront create-key-value-store \
--name=keyvaluestore1 \
--comment="This is my key value store file" \
--import-source=SourceType=S3,SourceARN=arn:aws:s3:::amzn-s3-demo-bucket1/kvs-input.json
```
**Response**
```
{
"ETag": "ETVABCEXAMPLE",
"Location": "https://cloudfront.amazonaws.com/2020-05-31/key-value-store/arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example",
"KeyValueStore": {
"Name": "keyvaluestore1",
"Id": "8aa76c93-3198-462c-aaf6-example",
"Comment": "This is my key value store file",
"ARN": "arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example",
"Status": "PROVISIONING",
"LastModifiedTime": "2024-08-06T22:19:10.813000+00:00"
}
}
```
------
#### [ API ]
**To create a key value store**
1. Use the [CloudFront CreateKeyValueStore](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_CreateKeyValueStore.html) operation. The operation takes several parameters:
+ A `name` of the key value store.
+ A `comment` parameter that includes a comment.
+ An `import-source` parameter that lets you import key-value pairs from a file that is stored in an Amazon S3 bucket. You can import from a file only when you first create the key value store. For information about the file structure, see [File format for key-value pairs](kvs-with-functions-create-s3-kvp.md).
The operation response includes the following information:
+ The values passed in the request, including the name that you assigned.
+ Data such as the creation time.
+ An `ETag` (for example, `ETVABCEXAMPLE`), the ARN that includes the name of the key value store (for example, `arn:aws:cloudfront::123456789012:key-value-store/keyvaluestore1`).
You will use some combination of the `ETag`, the ARN, and the name to work with the key value store programmatically.
------
## Key value store statuses
When you create a key value store, the data store can have the following status values.
****
| Value | Description |
| --- | --- |
| **Provisioning** | The key value store was created and CloudFront is processing the data source that you specified. |
| **Ready** | The key value store was created and CloudFront successfully processed the data source that you specified. |
| **Import failed** | CloudFront wasn't able to process the data source that you specified. This status can appear if your file format isn't valid or that it exceeds the size limit. For more information, see [File format for key-value pairs](kvs-with-functions-create-s3-kvp.md). |
# Associate a key value store with a function
After you create your key value store, you can update your function to associate it with your key value store. You must make this association to use the key-value pairs from that store in that function. The following rules apply:
+ A function can have only one key value store
+ You can associate the same key value store with multiple functions
------
#### [ Console ]
**To associate a key value store with a function**
1. Sign in to the CloudFront console at [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions) and choose the **Functions** page.
1. Choose the function name.
1. Go to the **Associate KeyValueStore** section and choose **Associate existing KeyValueStore**.
1. Select the key value store that contains the key-value pairs in the function, and then choose **Associate KeyValueStore**.
CloudFront immediately associates the store with the function. You don't need to save the function.
1. To specify a different key value store, choose **Update associated KeyValueStore**, select another key value store name, and then choose **Associate KeyValueStore**.
For more information, see [Update functions](update-function.md).
------
#### [ AWS CLI ]
**To associate a key value store with a function**
+ Run the following command to update the `MaxAge` function and associate a key value store resource.
```
aws cloudfront update-function \
--name MaxAge \
--function-config '{"Comment":"Max Age 2 years","Runtime":"cloudfront-js-2.0","KeyValueStoreAssociations":{"Quantity":1,"Items":[{"KeyValueStoreARN":"arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example"}]}}' \
--function-code fileb://function-max-age-v1.js \
--if-match ETVABCEXAMPLE
```
+ To associate a key value store with a function, specify the `KeyValueStoreAssociations` parameter and the key value store ARN.
+ To change the association, specify another key value store ARN.
+ To remove the association, remove the `KeyValueStoreAssociations` parameter.
For more information, see [Update functions](update-function.md).
------
#### [ API ]
**To associate a key value store with a function**
+ Use the [UpdateFunction](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_UpdateFunction.html) API operation. For more information, see [Update functions](update-function.md).
------
**Notes**
If you modify a key value store without changing the key-value pairs, or if you only modify the key-value pairs in the key value store, you don't need to associate the key value store again. You also don't need to republish the function.
However, we recommend that you test the function to verify that it works as expected. For more information, see [Test functions](test-function.md).
You can view all the functions that use specific key value stores. On the CloudFront console, choose the key value store details page.
# Update a key value store
When you update a key value store, you can change the key-value pairs, or change the association between the key value store and the function.
------
#### [ Console ]
**To update a key value store**
1. Sign in to the AWS Management Console and open the **Functions** page in the CloudFront console at [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions).
1. Choose the **KeyValueStores** tab.
1. Select the key value store that you want to update.
+ To update the key-value pairs, choose **Edit** in the **Key value pairs** section. You can add or delete any key-value pairs. You can also change the value for an existing key-value pair. When you're finished, choose **Save changes**.
+ To update the association for this key value store, choose **Go to functions**. For more information, see [Associate a key value store with a function](kvs-with-functions-associate.md).
------
#### [ AWS CLI ]
**To update a key value store**
1. **Change the key-value pairs** – You can add more key-value pairs, delete one or more key-value pairs, and change the value of an existing key-value pair. For more information, see [Work with key value data](kvs-with-functions-kvp.md).
1. **Change the function association for the key value store ** – To update the function the association for the key value store, see [Associate a key value store with a function](kvs-with-functions-associate.md).
**Tip**
You will need the ARN of the key value store. For more information, see [Get a reference to a key value store](kvs-with-functions-get-reference.md).
------
#### [ API ]
**To update a key value store**
1. **Change the key-value pairs** – You can add more key-value pairs, delete one or more key-value pairs, and change the value of an existing key-value pair. For more information, see [Work with key value data](kvs-with-functions-kvp.md).
1. **Change the function association for the key value store** – To update the function association for the key value store, use the [UpdateFunction](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_UpdateFunction.html) API operation. For more information, see [Update functions](update-function.md).
**Tip**
You will need the ARN of the key value store. For more information, see [Get a reference to a key value store](kvs-with-functions-get-reference.md).
------
# Get a reference to a key value store
To work with the key value stores programmatically, you need the `ETag` and the name of the key value store.
To get both values, you can use the AWS Command Line Interface (AWS CLI) or the CloudFront API.
------
#### [ AWS CLI ]
**To get the key value store reference**
1. To return a list of key value stores, run the following command Find the name of the key value store that you want to change.
```
aws cloudfront list-key-value-stores
```
1. From the response, find the name of the key value store that you want.
**Response**
```
{
"KeyValueStoreList": {
"Items": [
{
"Name": "keyvaluestore3",
"Id": "37435e19-c205-4271-9e5c-example3",
"ARN": "arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example3",
"Status": "READY",
"LastModifiedTime": "2024-05-08T14:50:18.876000+00:00"
},
{
"Name": "keyvaluestore2",
"Id": "47970d59-6408-474d-b850-example2",
"ARN": "arn:aws:cloudfront::123456789012:key-value-store/47970d59-6408-474d-b850-example2",
"Status": "READY",
"LastModifiedTime": "2024-05-30T21:06:22.113000+00:00"
},
{
"Name": "keyvaluestore1",
"Id": "8aa76c93-3198-462c-aaf6-example",
"ARN": "arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example",
"Status": "READY",
"LastModifiedTime": "2024-08-06T22:19:30.510000+00:00"
}
]
}
}
```
1. Run the following command to return the `ETag` for the specified key value store.
```
aws cloudfront describe-key-value-store \
--name=keyvaluestore1
```
**Response**
```
{
"ETag": "E3UN6WX5RRO2AG",
"KeyValueStore": {
"Name": "keyvaluestore1",
"Id": "8aa76c93-3198-462c-aaf6-example",
"Comment": "This is an example KVS",
"ARN": "arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example",
"Status": "READY",
"LastModifiedTime": "2024-08-06T22:19:30.510000+00:00"
}
}
```
------
#### [ API ]
**To get the key value store reference**
1. Use the [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListKeyValueStores.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListKeyValueStores.html) API operation to return a list of key value stores. Find the name of the key value store that you want to change.
1. Use the [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DescribeKeyValueStore.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DescribeKeyValueStore.html) API operation and specify the name of the key value store that you returned from the previous step.
------
The response includes a UUID, the ARN of the key value store, and the `ETag` of the key value store.
+ An `ETag`, such as `E3UN6WX5RRO2AG`
+ The UUID is 128 bits, such as `8aa76c93-3198-462c-aaf6-example`
+ The ARN includes the AWS account number, the constant `key-value-store`, and the UUID, like the following example:
`arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example`
For more information about the `DescribeKeyValueStore` operation, see [About the CloudFront KeyValueStore](kvs-with-functions-kvp.md#kvs-with-functions-api-describe).
# Delete a key value store
You can delete your key value store by using the Amazon CloudFront console or API.
------
#### [ Console ]
**To delete a key value store**
1. Sign in to the AWS Management Console and open the **Functions** page in the CloudFront console at [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions).
1. Choose the function name.
1. Under the **Associated KeyValueStore** section, verify if a key value store is associated with the function. If it is, remove the association by choosing **Disassociate KeyValueStore** and then choose **Remove association**.
1. In the navigation pane, choose the **Functions** page and then choose the **KeyValueStores** tab.
1. Select the key value store that you want to delete and then choose **Delete**.
------
#### [ AWS CLI ]
**To delete a key value store**
1. Get the `ETag` and the name of the key value stores. For more information, see [Get a reference to a key value store](kvs-with-functions-get-reference.md).
1. Verify if the key value stores is associated with a function. If it is, remove the association. For more information on both these steps, see [Update functions](update-function.md).
1. After you have the name and `ETag` of the key value store and it's no longer associated with a function, you can delete it.
Run the following command to delete the specified key value store.
```
aws cloudfront delete-key-value-store \
--name=keyvaluestore1 \
--if-match=E3UN6WX5RRO2AG
```
------
#### [ API ]
**To delete a key value store**
1. Get the `ETag` and the name of the key value stores. For more information, see [Get a reference to a key value store](kvs-with-functions-get-reference.md).
1. Verify if the key value stores is associated with a function. If it is, remove the association. For more information on both these steps, see [Update functions](update-function.md).
1. To delete the key value store, use the CloudFront [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DeleteKeyValueStore.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DeleteKeyValueStore.html) API operation.
------
# File format for key-value pairs
When you create a UTF-8 encoded file, use the following JSON format:
```
{
"data":[
{
"key":"key1",
"value":"value"
},
{
"key":"key2",
"value":"value"
}
]
}
```
Your file can't include duplicate keys. If you specified an invalid file in your Amazon S3 bucket, you can update the file to remove any duplicates and then try creating your key value store again.
For more information, see [Create a key value store](kvs-with-functions-create.md).
**Note**
The file for your data source and its key-value pairs have the following limits:
File size – 5 MB
Key size – 512 characters
Value size – 1024 characters