Data Store Commands Reference

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

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

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.

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.2",
  "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.2",
  "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`.

Was this page helpful?

Provide feedback

Last updated: May 18, 2023

Data Store Commands Reference

About the data store commands

Data store organization

Data store limits

PUT_NAMESPACE

Command properties

PUT_OBJECT

Command properties

Example: update an object in the data store

Example: Update an array in the data store

REMOVE_NAMESPACE

Command parameters

REMOVE_OBJECT

Command properties

CLEAR

Command properties

Related topics

Was this page helpful?