Key-value API

When to use the Key-value API

Use the Key-value API when an application needs one JSON value per scoped key, such as ui:preferences. Use the Progress API for frequently changing integer progress and the Array API for independently addressable collections.

All examples use the USER scope. See the Personalization overview for authentication, scopes, key syntax, and shared limits.

Operations

Operation	Purpose
setKey	Insert or update one value
getKey	Read one or more values
deleteKey	Delete one value

Store or update a value

setKey inserts a value when the key does not exist and updates the value when it does.

Example: Save user interface preferences

mutation SetPreferences($input: SetKeyInput!) {
  setKey(input: $input) {
    acknowledged
    insertedCount
    updatedCount
  }
}

{
  "input": {
    "scope": "USER",
    "key": "ui:preferences",
    "value": {
      "theme": "dark",
      "autoplay": false
    }
  }
}

First write response:

{
  "data": {
    "setKey": {
      "acknowledged": true,
      "insertedCount": 1,
      "updatedCount": 0
    }
  }
}

A later write to the same scoped key returns insertedCount: 0 and updatedCount: 1. Inspect these counts when the distinction matters; acknowledged only indicates that the mutation was accepted.

Read values

getKey accepts multiple keys and returns found entries only.

Example: Read several keys

query GetPreferences($input: GetKeyInput!) {
  getKey(input: $input) {
    data {
      key
      value
    }
  }
}

{
  "input": {
    "scope": "USER",
    "keys": ["ui:preferences", "ui:accessibility", "unknown:key"]
  }
}

{
  "data": {
    "getKey": {
      "data": [
        {
          "key": "ui:preferences",
          "value": {
            "theme": "dark",
            "autoplay": false
          }
        },
        {
          "key": "ui:accessibility",
          "value": {
            "captions": true
          }
        }
      ]
    }
  }
}

Unknown keys are omitted. Response order is not guaranteed to match request order; associate each result by its returned key.

Delete a value

deleteKey deletes one scoped key.

Example: Delete user interface preferences

mutation DeletePreferences($input: DeleteKeyInput!) {
  deleteKey(input: $input) {
    acknowledged
    deletedCount
  }
}

{
  "input": {
    "scope": "USER",
    "key": "ui:preferences"
  }
}

{
  "data": {
    "deleteKey": {
      "acknowledged": true,
      "deletedCount": 1
    }
  }
}

Deleting an unknown key is a successful no-op with deletedCount: 0.

Value and key constraints

• Keys must match ^[\\w-]+(:[\\w-]+)*$.
• JSON values are limited to 10,240 bytes.
• Values may be JSON scalars, objects, or arrays.
• Errors are reported through GraphQL errors[].extensions; do not parse message text.

See Errors and limits.