setValues

The "setValues" action stores one or more key-value pairs in the server. The key is a UTF-8 string up to 128 bytes in length. The value is a JSON object up to 2 gigabytes. If the key does not exist, the action creates it. If the key exists, the action updates it. Each key has its own value.

 

How to use "setValues"

Use the "keyStore" property to specify the keystore for the key-value pairs you want to create or update. Include one or more key-value pair objects in the "keyValuePairs" property. Use the "key" and "value" properties to define each key-value pair. The key is a string and the value is JSON. A JSON value can be an object, array, string, number, true, false, or null. 

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 limit which keys the user can set and retrieve. 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.

If the response contains "errorCode": 0, then the request succeeded. No additional information is included in the response to optimize network communication speed. If there is an error, the "errorMessage" property describes the problem.

Tip You may optionally create a key hierarchy using the slash / character or any other string you prefer. Each level in the hierarchy should end with the delimiter string. For instance, "color/" acts as a parent to keys like "color/red" and "color/green". You may assign a value to any key string, including those that are parents of other keys, such as "color/".

 

Request examples

Global keystore

{
  "api": "db",
  "action": "setValues",
  "params": {

    "keyStore": "global", 
    "keyValuePairs": 
    [
      { 
        "key": "myKey", 
        "value": {"my": "value"}
      },
      { 
        "key": "myApp/queries/My Favorite", 
        "value": {"savedQuery": "favorite = 1"}
      },
      { 
        "key": "myApp/queries/Find Errors", 
        "value": {"savedQuery": "error = 1"}
      }
    ]

  },
  "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 create and modify key-value pairs for any role.

{
  "api": "db",
  "action": "setValues",
  "params": {

    "keyStore": "role", 
    "roleName": "operator",
    "keyValuePairs": 
    [
      { 
        "key": "myKey", 
        "value": 1
      },
      { 
        "key": "myApp/queries/My Favorite", 
        "value": {"savedQuery": "favorite = 1"}
      }
    ]

  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

User keystore 

The action automatically uses the session's username.

{
  "api": "db",
  "action": "setValues",
  "params": {
    "keyStore": "user",
    "keyValuePairs": 
    [
      { 
        "key": "myKey", 
        "value": "myValue"
      }
    ]
  },
  "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 create and modify key-value pairs for other accounts.

{
  "api": "db",
  "action": "setValues",
  "params": {
    "keyStore": "user",
    "username": "someone_else", 
    "keyValuePairs": 
    [
      { 
        "key": "myKey", 
        "value": "someone_else_value"
      },
      { 
        "key": "myApp/queries/My Favorite", 
        "value": {"savedQuery": "favorite = 1"}
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"  
}
 
 

 

Response examples

Global keystore 

{
  "result": {},
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

Role keystore 

{
  "result": {},
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

User keystore 

{
  "result": {},
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

User keystore using elevated privileges

{
  "result": {},
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default 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.

 Required - No default value string enum

"global"

"role"

"user"

keyValuePairs

 The "keyValuePairs" property contains objects that represent a key-value pair and contain "key" and "value" properties, such as { "key": "k1",  "value": 1 }. Required - No default value 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.

Optional with default of "".

 

Required in the Key-Value API 

 string 1 to 128 bytes

keyValuePairs

.value

The "value" property is used by the server to compare the value assigned to "value" to the appropriate field data in records.

 

In Key-Value actions, the required "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.

 Required - No default value string

"string"

"integer"

"number"

"boolean"

"null"

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

 

 

Was this article helpful?

Give feedback about this article

Related Articles