Data Store Commands Reference
Use data store commands to update and manage the data store on a device.
About the data store commands
You use the Data Store REST API to run the commands. You can update the data store from within a request sent to your skill, or from outside the skill session.
The Data Store Extension also includes commands related to the data store, but you use those commands within the Alexa Presentation Language (APL) document. The commands in the extension aren't available when you use the REST API.
Data store organization
The data store on a device is organized by region, namespace, and key. A region can contain multiple namespaces, and a namespace can contain multiple keys. Each key contains an object with the data.
Each data store command has properties to specify the namespace
and key
as needed. The REST API automatically determines the region for your skill based on the skill ID. Your skill can't access the data store for any other skills.
Data store limits
The data store imposes the following limitations:
- A skill can store up to 1 MB of data on a device. This limit is per skill and is shared across all the widgets associated with the skill. Each item in the region, including the
namespace
andkey
names, contributes to storage consumed by the skill. - Your skill can't exceed 25 transactions per second (TPS) when it writes data to the data store.
PUT_NAMESPACE
Creates new namespace in the region with the provided namespace
name. Ignored if the namespace
already exists in the region.
Command properties
Property | Type | Required | Description |
---|---|---|---|
|
|
Yes |
Type of command to run. Set to |
|
|
Yes |
Identifier for the namespace to create. Must be unique within the region for your skill. The namespace must be a be a non-empty string that meets the follow requirements:
The |
PUT_OBJECT
Adds the object provided in content
to the specified key
within the specified namespace
. This command creates the namespace if the specified namespace
doesn't exist in the region.
If the specified key
contains an existing object, the PUT_OBJECT
command updates the existing object by using the following logic:
- Add any properties provided in the new
PUT_OBJECT
command that weren't a part of the existing object. - Update the properties that exist in both the new
PUT_OBJECT
command and the existing object in the data store. For each property, the command replaces the existing value in the data store with the value provided in the commmand. - Keep the old values for any properties that exist in the data store, but don't exist in the new
PUT_OBJECT
command.
If the specified key
contains an existing array, the PUT_OBJECT
command replaces the array in the data store with the array provided in the command. The command doesn't attempt to merge the two arrays.
Command properties
Property | Type | Required | Description |
---|---|---|---|
|
|
Yes |
Type of command to run. Set to |
|
|
Yes |
Unique identifier for the namespace to update with the provided
The |
|
|
Yes |
Unique identifier for the object to update with the provided
The |
|
|
Yes |
The content to add or update at the specified |
Example: update an object in the data store
The following example shows an APL document that configures the data store to store an object at the key called mainPage
. The dataType
is set to OBJECT
. For details about the data store settings in a document, see APL Data Store Extension.
{
"type": "APL",
"version": "2023.1",
"extensions": [
{
"uri": "alexaext:datastore:10",
"name": "DataStore"
}
],
"settings": {
"DataStore": {
"dataBindings": [
{
"namespace": "objectDataStoreExample",
"key": "mainPage",
"dataBindingName": "dsMainPage",
"dataType": "OBJECT"
}
]
}
},
"mainTemplate": {}
}
To update the object at the mainPage
key, use the following PUT_OBJECT
command. Note that the content
property in the command must contain an object because the dataType
of the data stored at this key is OBJECT
. In this example, the new object for the mainPage
key has four properties.
{
"type": "PUT_OBJECT",
"namespace": "objectDataStoreExample",
"key": "mainPage",
"content": {
"headerTitle": "This is the header title from the data store",
"primaryText": "This is the primaryText from the data store",
"secondaryText": "Secondary text from the data store",
"tertiaryText": "Tertiary text from the data store"
}
}
Example: Update an array in the data store
The following example shows an APL document that configures the data store to store an array at the key called mainList
. The dataType
is set to ARRAY
. For details about the data store settings in a document, see APL Data Store Extension.
{
"type": "APL",
"version": "2023.1",
"extensions": [
{
"uri": "alexaext:datastore:10",
"name": "DataStore"
}
],
"settings": {
"DataStore": {
"dataBindings": [
{
"namespace": "arrayDataStoreExample",
"key": "mainList",
"dataBindingName": "dsListItemsToShow",
"dataType": "ARRAY"
}
]
}
},
"mainTemplate": {}
}
To update the array at the mainList
key, use the following PUT_OBJECT
command. Note that the content
property in the command must contain an array because the dataType
of the data stored at this key is ARRAY
. In this example, the new array for the mainList
key contains four items.
{
"type": "PUT_OBJECT",
"namespace": "arrayDataStoreExample",
"key": "mainList",
"content": [
{
"primaryText": "The first list item."
},
{
"primaryText": "The second list item."
},
{
"primaryText": "The third list item."
},
{
"primaryText": "The fourth list item."
}
]
}
REMOVE_NAMESPACE
Deletes the specified namespace
from the region. Ignored if the provided namespace
doesn't exist.
Command parameters
Property | Type | Required | Description |
---|---|---|---|
|
|
Yes |
Type of command to run. Set to |
|
|
Yes |
Identifier for the namespace to remove. |
REMOVE_OBJECT
Deletes the object stored at the specified namespace
and key
. Ignored if the object doesn't exist.
Command properties
Property | Type | Required | Description |
---|---|---|---|
|
|
Yes |
Type of command to run. Set to |
|
|
Yes |
Unique identifier for the namespace that contains the object to remove. |
|
|
Yes |
Unique identifier for the object to remove. |
CLEAR
Deletes the region for your skill. Ignored if your skill doesn't have a region on the device.
Deleting a region deletes all namespaces
and objects stored within that region. Data stored in the region isn't recoverable. The next PUT_NAMESPACE
or PUT_OBJECT
command recreates the region with the data specified in those commands, but doesn't restore any of the deleted data.
Command properties
Property | Type | Required | Description |
---|---|---|---|
|
|
Yes |
Type of command to run. Set to |
Related topics
- Alexa.DataStore Interface Reference
- Data Store REST API
- Alexa.DataStore.PackageManager Interface Reference
- About Widgets and Alexa Presentation Language (APL)
Last updated: May 18, 2023