The "getValuesFromHierarchy" action retrieves all key-value pairs located at the specified hierarchical level. It returns keys and values.
Use the "getKeysFromHierarchy" action to return only keys and use "describeValuesFromHierarchy" to return all information about a key.
This action is useful for retrieving user-defined keys and their values. For example, your application may let users create, name, and save items in the keystores. When your application needs these items, it can use this action to retrieve them.
How to use "getValuesFromHierarchy"
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.
If you set the required "partialKey" to the "" string, it returns all keys in the specified store.
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.
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.
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)
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"
keyValuePairs
The "keyValuePairs" property contains an array of objects. Each object represents a key-value pair and contains "key" and "value" properties, such as { "key": "k1", "value": 1 }.
array of key-value objects
[
{
"key": "myKey",
"value": 1
}
]
keyValuePairs
.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
keyValuePairs
.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.
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.
