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 and key 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

type

String

Yes

Type of command to run. Set to PUT_NAMESPACE.

namespace

String

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:

  • Fewer than 512 bytes
  • Doesn't begin with the string "sqlite_"
  • Doesn't match any SQLite reserved keywords
  • Doesn't start with an underscore (_)
  • Allowed character set: [_ - . a-z A-Z 0-9]

The namespace name contributes to the data store storage allocated to your skill. For details about limits, see Data store limits.

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

type

String

Yes

Type of command to run. Set to PUT_OBJECT.

namespace

String

Yes

Unique identifier for the namespace to update with the provided content. Must be unique within the region for your skill. The namespace must be a be a non-empty string that meets the follow requirements:

  • Fewer than 512 bytes
  • Doesn't begin with the string "sqlite_"
  • Doesn't match any SQLite reserved keywords
  • Doesn't start with an underscore (_)
  • Allowed character set: [_ - . a-z A-Z 0-9]

The namespace name contributes to the data store storage allocated to your skill. For details about limits, see Data store limits.

key

String

Yes

Unique identifier for the object to update with the provided content. The key must be a non-empty string that meets the following requirements:

  • Fewer than 512 bytes
  • Doesn't start with an underscore (_)
  • Allowed character set: [_ - . a-z A-Z 0-9]

The key name contributes to the data store storage allocated to your skill. For details about limits, see Data store limits.

content

Object or Array

Yes

The content to add or update at the specified namespace and key. The PUT_OBJECT command doesn't inspect or validate this payload.

Make sure that the data you provide in this property matches the dataType defined for the specified namespace and key. For example, if you configured the data store extension to store an ARRAY at a specified namespace and key, then you must provide an ARRAY in the content property of the PUT_OBJECT command. For examples, see Example: update an object in the data store and Example: Update an array in the data store.

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

type

String

Yes

Type of command to run. Set to REMOVE_NAMESPACE.

namespace

String

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

type

String

Yes

Type of command to run. Set to REMOVE_OBJECT.

namespace

String

Yes

Unique identifier for the namespace that contains the object to remove.

key

String

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

type

String

Yes

Type of command to run. Set to CLEAR.

Last updated: May 18, 2023