describeValuesFromHierarchy

The "describeValuesFromHierarchy" action retrieves all key-value pairs located at the specified hierarchical level. It returns keys, values, metadata, and the key without its hierarchy.

Use the "getKeysFromHierarchy" action to return only keys and use "getValuesFromHierarchy" to return only key-value pairs.

This action is useful for retrieving user-defined keys. For example, your application may let users create, name, and save items in keystores. When your application needs these items, it can use this action to retrieve them.

This action returns the "keyWithoutHierarchy" property, which contains the part of the key following the "partialKey" value. This property contains the user-defined name of an item. For example, given a key of "myApp/queries/My Favorite" and a partial key of "myApp/queries/", the key without the hierarchy is "My Favorite".

 

How to use "describeValuesFromHierarchy"

Use the required "keyStore" property to specify the keystore from which keys are returned, and use the required "partialKey" property to define the hierarchical level of those keys. To ensure the action matches the hierarchical levels you want, include the hierarchical delimiter at the end of the partial key, such as "myApp/queries/". Use "partialKey": "" to return all keys in the store.

When using the "role" keystore, you must set the "roleName" property to the name of the role that owns the key-value pair. The action returns an error when the current user does not have the specified role. An administrator account may set and get values for any role.

When using the "user" keystore, the action uses the session's username to identify the user's keys. When an administrator account runs the action, it can optionally use the "username" property to specify the user that owns the keys. This allows an elevated account to retrieve keys for other accounts.

 

Request examples

Global keystore

{
  "api": "db",
  "action": "describeValuesFromHierarchy",
  "params": {
    "keyStore": "global", 
    "partialKey": "myApp/queries/",
    "hierarchyDelimiter": "/"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Role keystore

The action uses the specified role and returns an error if the current session's account does not have that role. An administrator account may get key-value pairs for any role.

{
  "api": "db",
  "action": "describeValuesFromHierarchy",
  "params": {
    "keyStore": "role", 
    "roleName": "operator",
    "partialKey": "myApp/queries/",
    "hierarchyDelimiter": "/"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

User keystore

The action automatically uses the session's username.

{
  "api": "db",
  "action": "describeValuesFromHierarchy",
  "params": {
    "keyStore": "user", 
    "partialKey": "nonexistent/hierarchy/",
    "hierarchyDelimiter": "/"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

User keystore request using elevated privileges

When an administrator account runs the action, it can optionally use the "username" property to specify the account of the key-value pair. This allows an elevated account to get key-value pairs for other accounts.

{
  "api": "db",
  "action": "describeValuesFromHierarchy",
  "params": {
    "keyStore": "user", 
    "username": "someone_else", 
    "partialKey": "myApp/queries/",
    "hierarchyDelimiter": "/"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Global keystore

{
  "result": {
    "keyStore": "global", 
    "hierarchyDelimiter": "/",
    "partialKey": "myApp/queries/",
    "keyValuePairDetails": [
      {
        "key": "myApp/queries/My Favorite",
        "value": {"savedQuery": "favorite = 1"},
        "keyWithoutHierarchy": "My Favorite",
        "username": "some_user",
        "createdTimestamp": "2025-09-04T15:35:21.014",
        "updatedTimestamp": "2025-09-04T15:35:21.014"
      },
      {
        "key": "myApp/queries/Find Errors",
        "value": {"savedQuery": "error = 1"},
        "keyWithoutHierarchy": "Find Errors",
        "username": "some_user",
        "createdTimestamp": "2025-09-04T15:35:21.014",
        "updatedTimestamp": "2025-09-04T15:35:21.014"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

Role keystore

{
  "result": {
    "keyStore": "role", 
    "roleName": "operator",
    "partialKey": "myApp/queries/",
    "hierarchyDelimiter": "/",
    "keyValuePairDetails": [
      {
        "key": "myApp/queries/My Favorite",
        "value": {"savedQuery": "favorite = 1"},
        "keyWithoutHierarchy": "My Favorite",
        "username": "some_user",
        "createdTimestamp": "2025-09-04T15:35:21.014",
        "updatedTimestamp": "2025-09-04T15:35:21.014"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

User keystore

When the partial key has no matches, "keyValuePairDetails" is empty.

{
  "result": {
    "keyStore": "user", 
    "username": "me", 
    "partialKey": "nonexistent/hierarchy/",
    "hierarchyDelimiter": "/",
    "keyValuePairDetails": []
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

User keystore response using elevated privileges

{
  "result": {
    "keyStore": "user", 
    "username": "someone_else", 
    "partialKey": "myApp/queries/",
    "hierarchyDelimiter": "/",
    "keyValuePairDetails": [
      {
        "key": "myApp/queries/My Favorite",
        "value": {"savedQuery": "favorite = 1"},
        "keyWithoutHierarchy": "My Favorite",
        "username": "someone_else",
        "createdTimestamp": "2025-09-04T15:35:21.014",
        "updatedTimestamp": "2025-09-04T15:35:21.014"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

hierarchyDelimiter

The "hierarchyDelimiter" property delimits hierarchical levels in the key. When set to "", this property defines no hierarchy. It may contain zero or more UTF-8 characters, such "/" or "||".

 

The "describeValues" action uses this string to calculate the "keyWithoutHierarchy" property, which contains the key's text following the last occurrence of the delimiter. If the "hierarchyDelimiter" property is "" or the action cannot find the delimiter string, it sets the "keyWithoutHierarchy" property to the whole key because the key does not contain a hierarchy.


Examples

  • Given the key, "myKey" and a hierarchy delimiter of "", the "keyWithoutHierarchy" property contains "myKey".
  • Given the key, "myKey" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "myKey".
  • Given the key, "myApp/queries/" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "".
  • Given the key, "myApp||queries||" and a hierarchy delimiter of "||", the "keyWithoutHierarchy" property contains "".
  • Given the key, "myApp/queries/My Favorite" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "My Favorite".
  • Given the key, "myApp||queries||My Favorite" and a hierarchy delimiter of "||", the "keyWithoutHierarchy" property contains "My Favorite".
     
 Optional with default of "" string 1 byte

keyStore

The "keyStore" property specifies the keystore where the action stores and retrieves key-value pairs. There are three keystores: "global", "role", and "user".


The Simple Secure Key-Value API stores key-value pairs independently in each keystore; thus, the same key can exist in different keystores with different values. For example, the "settings/default/" key can exist in the global, user, and role keystores.


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.


Within the user keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.


When using the "role" keystore, you must set the "roleName" property to the name of the role that owns the key-value pair. The action returns an error when the current user does not have the specified role. An administrator account may set and get values for any role.


When using the "user" keystore, the action uses the session's username to identify the user's keys. When an administrator account runs the action, it can optionally use the "username" property to specify the user that owns the keys. This allows an elevated account to create and modify keys for other accounts.

 Required - No default value string enum

"global"

"role"

"user"

partialKey

The "partialKey" property defines the range of returned records. For more details, see "partialKey". 

Optional with default of "" or []

Required in the Key-Value API 

 string or array

1 or more strings/arrays

1 to 128 bytes in the Key-Value API 

roleName

The "roleName" property specifies the key's role, which must match an RBAC role that exists in the server. It is not used with the other keystores. 


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.

 Required when "keystore": "role" string 1 to 64 bytes

username

The "username" property specifies the name that uniquely identifies the account. 

 

In "alter" actions, this property specifies the account that will be altered.

 

In Key-Value actions, the "username" property is optionally used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.
 

Required - No default value

 

Optional with default of the account name of the currently logged-in user for Key-Value actions

 

 string 1 to 64 bytes

 

Response properties ("result")

Property Description Type Limits (inclusive)

hierarchyDelimiter

The "hierarchyDelimiter" property is a string that delimits hierarchical levels in the key. It defaults to the empty string "", which defines no hierarchy. It may contain zero or more UTF-8 characters, such "/" or "||".

 

The "describeValues" action uses this string to calculate the "keyWithoutHierarchy" property, which contains the key's text following the last occurrence of the delimiter. If the "hierarchyDelimiter" property is "" or the action cannot find the delimiter string, it sets the "keyWithoutHierarchy" property to the whole key because the key does not contain a hierarchy.


Examples

  • Given the key, "myKey" and a hierarchy delimiter of "", the "keyWithoutHierarchy" property contains "myKey".
  • Given the key, "myKey" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "myKey".
  • Given the key, "myApp/queries/" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "".
  • Given the key, "myApp||queries||" and a hierarchy delimiter of "||", the "keyWithoutHierarchy" property contains "".
  • Given the key, "myApp/queries/My Favorite" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "My Favorite".
  • Given the key, "myApp||queries||My Favorite" and a hierarchy delimiter of "||", the "keyWithoutHierarchy" property contains "My Favorite".
     
 string 1 byte

keyStore

The "keyStore" property specifies the keystore where the action stores and retrieves key-value pairs. There are three keystores: "global", "role", and "user".


The Simple Secure Key-Value API stores key-value pairs independently in each keystore; thus, the same key can exist in different keystores with different values. For example, the "settings/default/" key can exist in the global, user, and role keystores.


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.


Within the user keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.


When using the "role" keystore, you must set the "roleName" property to the name of the role that owns the key-value pair. The action returns an error when the current user does not have the specified role.  An administrator account may set and get values for any role.


When using the "user" keystore, the action uses the session's username to identify the user's keys. When an administrator account runs the action, it can optionally use the "username" property to specify the user that owns the keys. This allows an elevated account to create and modify keys for other accounts.

 string enum

"global"

"role"

"user"

keyValuePairDetails

The "keyValuePairDetails" property contains an array of objects. Each object represents a key-value pair and contains extended information about a key and its value, including the "key", "value", "keyWithoutHierarchy", "username", "createdTimestamp", and "updatedTimestamp" properties.
 

{
  "key": "myKey",
  "value": {"my": "value"},
  "keyWithoutHierarchy": "myKey",
  "username": "some_user", 
  "createdTimestamp": "2025-09-04T15:35:21.014",
  "updatedTimestamp": "2025-09-04T15:35:21.014"
}
array of objects 
[
  { 
    "key": "k1",
    "value": 1,
    "keyWithoutHierarchy": "myKey",
    "username": "some_user",
    "createdTimestamp": "2025-09-04T15:35:21.014",
    "updatedTimestamp": "2025-09-04T15:35:21.014" 
  }
]

keyValuePairDetails

.createdTimestamp

 The "createdTimestamp" property is the date and time when something, such as a thing or key, was originally created in ISO 8601 format, such as "2025-08-28T10:47:13.041". It is never null. timestamp An ISO 8601 timestamp

keyValuePairDetails

.key

 The "key" property is part of an optional key-value object that is defined in an array in the "userProperties" property. It is a user-defined string value. string 1 to 128 bytes

keyValuePairDetails

.keyWithoutHierarchy

The "keyWithoutHierarchy" property contains the leaf part of a hierarchical key, which is the last part of a key following the hierarchical delimiter. For example, given the key "myApp/queries/My Favorite" and a / delimiter, the leaf part of the key is "My Favorite".


The "describeValuesFromHierarchy" action populates the "keyWithoutHierarchy" property with the part of the key following the value of the "partialKey" property.


The "describeValues" action populates the "keyWithoutHierarchy" property with the part of the key following the "hierarchyDelimiter" property.


How to use "keyWithoutHierarchy"


The "keyWithoutHierarchy" property is useful when an application lets users save items with user-defined names. An application defines the base part of a hierarchical key and the user defines the rest. For example, an application defines a base key of "myApp/queries/" and the user specifies a name, such as "My Favorite". The complete key is "myApp/queries/My Favorite". The "keyWithoutHierarchy" property contains the user-defined name, such as "My Favorite".


An application can use the "describeValuesFromHierarchy" action to return user-defined items that match a base key. Each match contains a "keyWithoutHierarchy" property, which is the user-defined name of an item. 

 string 1 to 128 bytes

keyValuePairDetails

.updatedTimestamp

 The "updatedTimestamp" property is the date and time when the thing was last updated. It is the same as the "createdTimestamp" property when the thing has never been updated. It is returned in ISO 8601 format, such as "2025-08-28T10:47:13.041". timestamp ISO 8601 timestamp

keyValuePairDetails

.username

The "username" property specifies the account name of a user or application.

It is required by the "createSession" action for authentication.

All API actions are performed in the context of the account identified by "username". For example, all tables created by an account are owned by the account. All queries use tables owned by the account.

In JSON DB API and JSON Hub API, use the "ownerName" property to cause an action to use a different account name than the value of "username". This allows an account to use tables created by another account and to create tables that are owned by another account.

Unlike other property names, such as "databaseName", "username" is all lowercase.

A zero-length username is invalid.

Note See System limits for requirements of this and all other system properties.

In Key-Value actions, the "username" property is used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.

string

 

 

 1 to 64 bytes

keyValuePairDetails

.value

The "value" property associates a value with a label. It can be any JSON value that is associated with a label.

 

When you use the "alterLabel" action to update the "value" property, it replaces "value" with an entirely new value. It cannot replace parts of the JSON value.

 

In Key-Value actions, the "value" property contains a JSON value, which may be up to 2 gigabytes in length. It can be any JSON value, such as an object, array, string, number, true, false, or null.

 JSON 0 to 65,500 bytes

partialKey

The "partialKey" property defines the range of returned records. The "getRecordsByPartialKeyRange" action uses the "partialKey" to find a starting position in the index where it can start returning records. 

  • When the index key is based on one field, the "partialKey" property can be a string that contains some or all of the key values. The value must start from the beginning of the key.
    • When a field is stored in the index in reverse order, the "partialKey" property must start with bytes from the end of the key in reverse order. This allows you to do a partial match starting from the end of the key. To create a reverse order key, create the index and set one or more fields in the index to "reverseCompare": true.
  • You must include one value for each field in the index in the order the fields are in the index. The last field in the index may be omitted or may contain a partial key.
  • There are two forms of the "partialKey" property a string and an array.
  • The method finds the starting record by matching all the bytes in the "partialKey" value to the initial bytes in the indexes' keys.
  • A zero-length value matches all index keys.
  • All values in the array, except for the last, must represent a complete field value.
  • Only the last value in the array may be a partial value.
  • The fields must be placed in the array in index order.
  • Each value in the array must be compatible with the data type of its corresponding field.
    • JSON true or false for "bit" field.
    • JSON number for all number fields.
    • JSON string for "char", "varchar", "lvarchar", "binary", "varbinary", and "lvarbinary" fields.
  • A binary value is embedded in a string and is encoded as "base64" or "hex" according to the setting of "binaryFormat".

Note The Array (multi-field) shows how to use "partialKey" when an index contains five fields ("date", "bit", "varchar", "double", and "varbinary"). The values for "date", "bit", "varchar", and "double" cannot be partial values because they occur before the last field. The binary value in the "varbinary" field is encoded as base64 and since it is the last field it can contain a partial binary key.

 

String

"partialKey": "Mi"

Array (multi-field)

"partialKey":
[
  "2023-01-01", true, "full string", -3.4, "TWk="
]

In the Key-Value API, the "partialKey" property retrieves child keys from a key hierarchy. It defines the base hierarchical level of returned keys, such as "partialKey": "myApp/queries/". The action uses an index on the key to find all keys that match the characters specified in "partialKey". Keys are case sensitive.


To ensure the action matches the hierarchical levels you want, include the hierarchical delimiter at the end of the partial key, such as "myApp/queries/".


You can use "partialKey": "" to return all keys in the store.

 string or array

1 or more strings/arrays

1 to 128 bytes in the Key-Value API 

roleName

The "roleName" property is required by the role keystore. It is not used with the other keystores. It specifies the key's role, which must match an RBAC role that exists in the server.


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.

 string 1 to 64 bytes

username

The "username" property specifies the account name of a user or application.

It is required by the "createSession" action for authentication.

All API actions are performed in the context of the account identified by "username". For example, all tables created by an account are owned by the account. All queries use tables owned by the account.

In JSON DB API and JSON Hub API, use the "ownerName" property to cause an action to use a different account name than the value of "username". This allows an account to use tables created by another account and to create tables that are owned by another account.

Unlike other property names, such as "databaseName", "username" is all lowercase.

A zero-length username is invalid.

Note See System limits for requirements of this and all other system properties.

In Key-Value actions, the "username" property is used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.

string

 

 

 1 to 64 bytes

 


 

Was this article helpful?

Give feedback about this article

Related Articles