getValues

The "getValues" action takes one or more keys and retrieves their values. The server looks up each key you specify. A key is case sensitive and must exactly match the key you used to store the value. 

The response includes matching key-value pairs in the "keyValuePairs" property. It includes keys it could not find in the "unmatchedKeys" property. It does not return an error. 

 

How to use "getValues"

Use the "keyStore" property to specify the keystore from which keys are returned. In the "keys" property, include one or more key strings. 

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 automatically 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 the response contains "errorCode": 0, then the request succeeded. The "keyValuePairs" property in the response contains an array of key-value pair objects: one for each matching key. The "unmatchedKeys" property in the response contains an array of key strings: one for each unmatched key. 

No additional information is included in the response to optimize network communication speed. If there is an error, the "errorMessage" property describes the problem.

 

Request examples

Global keystore 

{
  "api": "db",
  "action": "getValues",
  "params": {
    "keyStore": "global", 
    "keys": [ 
      "myKey", 
      "myApp/queries/My Favorite" 
    ]
  },
  "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": "getValues",
  "params": {
    "keyStore": "role", 
    "roleName": "operator",
    "keys": [ 
      "myKey"
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

User keystore request

The action automatically uses the session's username.

{
  "api": "db",
  "action": "getValues",
  "params": {
    "keyStore": "user", 
    "keys": [ 
      "nonExistentKey"
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

User keystore 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": "getValues",
  "params": {
    "keyStore": "user", 
    "username": "someone_else", 
    "keys": [ 
      "myKey" 
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Global keystore 

{
  "result": {
    "keyStore": "global", 
    "keyValuePairs": [
      {
        "key": "myKey",
        "value": {"my": "value"}
      },
      {
        "key": "myApp/queries/My Favorite",
        "value": {"savedQuery": "favorite = 1"}
      }
    ],
    "unmatchedKeys": []
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

Role keystore

{
  "result": {
    "keyStore": "role", 
    "roleName": "operator",
    "keyValuePairs": [
      {
        "key": "myKey",
        "value": 1
      }
    ],
    "unmatchedKeys": []
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

User keystore

Notice the response does not contain any objects in "keyValuePairs" when the requested key does not exist.

{
  "result": {
    "keyStore": "user", 
    "username": "me", 
    "keyValuePairs": [],
    "unmatchedKeys": [ 
      "nonExistentKey" 
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

User keystore using elevated privileges

Notice the response does not contain any objects in "keyValuePairs" when the requested key does not exist.

{
  "result": {
    "keyStore": "user", 
    "username": "someone_else", 
    "keyValuePairs": [
     { 
       "key": "myKey", 
       "value": "someone_else_value"
      }
    ],
    "unmatchedKeys": []
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

keys

 The "keys" property contains an array of keys for an action to work on and return, such as [ "key1", "key2" ]. Required - No default value array of strings one or more key strings

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"

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

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

unmatchedKeys

The "unmatchedKeys" property contains a list of keys that an action could not find. An application can check this property to troubleshoot issues with key names.


The following actions look up keys by exact match and return this property:

  • "getValues"
  • "describeValues"
  • "deleteValues"
  • "renameKeys"
     
 array of strings zero or more key strings

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