Id of the object to set. If set, it has precedence over $alias. Used to look up the record to be operated on. By default (upsert) the record is created if nothing exists with the provided $id. This behaviour can be changed by providing $operation.
When no $id is provided, $alias can be used to reference user-provided alternative names to records, such as human readable identifiers, or url paths and the like.
const result = await client.set({
$alias: '/hello',
type: 'match',
$id: 'muASxsd3',
title: {
en: 'hello',
},
})When type is provided, such as it is above, if the provided $alias option doesn't resolve to an existing id, a new record will be created, and the provided $alias created for it automatically. This behaviour can be controlled with $operation also.
One can provide a list of aliases instead of a single alias. In this case all the aliases will be checked before failure or creating a new record if type is provided and the $operation allows for it.
const result = await client.set({
$alias: ['/hello', '/hey', '/hi`],
type: 'match',
$id: 'muASxsd3',
title: {
en: 'hello'
}
})If a new record is created, these aliases are created for it automatically.
NOTE: if the record does exist already, the missing aliases are not created.
To add new aliases to existing records add to or set the aliases default field which is a set field of string items. For more information see the set documentation.
Operation has to be one of upsert, update, create.
Upsert mode is the default set operation type. It updates an existing record or creates a new one if no record exists.
const result = await client.set({
$operation: 'upsert', // optional to provide $operation
$id: 'muASxsd3',
title: {
en: 'hello',
},
})Upsert acts both as create and update.
Create mode fails if a record already exists and returns undefined instead of the id of the created entry. If no entry exists with the specified $id or $alias.
const result = await client.set({
$operation: 'create',
$id: 'maASxsd3',
title: {
en: 'hello',
},
})
/*
If no record exists, value of `const result`: `maASxsd3`
If the record already exists, value of `const result`: `undefined`. In this case nothing is set in the database and the record remains as it was.
*/The same applies to $alias, if does not resolve nothing is done.
const result = await client.set({
$operation: 'create',
$alias: 'myAlias',
title: {
en: 'hello',
},
})
/*
If no record exists, value of `const result`: `maASxsd3`
If the record already exists, value of `const result`: `undefined`. In this case nothing is set in the database and the record remains as it was.
*/If neither $id nor $alias is provided but type is provided, a completely new record is created and and id is generated for it.
const result = await client.set({
$operation: 'create',
type: 'match',
title: {
en: 'hello',
},
})
/*
Value of `const result`: ma<random string> such as `maASxsd3`
Resulting record in database:
{
id: 'maASxsd3',
type: 'match',
title: {
en: 'hello'
}
}
*/Update mode is the opposite of create, in that it fails if the record being updated does not exist. The API signature is the same both for $id and $alias, and if neither is provided the operation fails.
let result = await client.set({
$operation: 'create',
type: 'match',
title: {
en: 'hello',
},
})
/*
Value of `const result`: `undefined`
Record in the database remains untouched
*/
result = await client.set({
$operation: 'create',
$id: 'maASxsd3',
title: {
en: 'hello',
},
})
/*
If the record exists, value of `const result`: `maASxsd3`
If the record does not exist, value of `const result`: `undefined`. In this case nothing is set in the database and the record remains as it was.
*/Default value: true
The $merge operator can be used to specify whether any fields specified in the .set() should overwrite everything that exists in the database for that record currently (if it is updated), or whether any fields specified will be added or overwritten only if provided.
/*
Let's assume the following record in database:
{
id: 'maASxsd3',
type: 'match',
value: 10,
title: {
en: 'yes'
}
}
*/
const result = await client.set({
$merge: true, // optional, defaults to true
type: 'match',
title: {
en: 'hello',
de: 'hallo',
},
name: 'match',
})
/*
Value of `const result`: `maASxsd3`
Resulting record in database:
{
id: 'maASxsd3',
type: 'match',
value: 10, // value remains
title: {
en: 'hello', // .en is overwritten
de: 'hallo' // .de is merged in
},
name: 'match' // name is merged in
}
*/
/* With $merge: false */
/*
Let's assume the following record in database:
{
id: 'maASxsd3',
type: 'match',
value: 10,
title: {
en: 'yes'
}
}
*/
const result = await client.set({
$merge: false,
title: {
de: 'hallo',
},
name: 'match',
})
/*
Value of `const result`: `maASxsd3`
Resulting record in database:
{
id: 'maASxsd3',
type: 'match',
title: {
de: 'hallo' // .de is added but .en is deleted
},
name: 'match' // name is added but value is deleted
}
*/See here for more details in the field type documentation.
Any and all field names can be set that exist in the schema of the provided type of record. Some operators exist that are specific to the type of field being set. Accepted values and operators for each field type are outlined below.
- digest
- timestamp
- url
- phone
- type
- string
- int
- float
- number
- boolean
- text
- array
- json
- geo
- set
- references
- object
For more information, please refer to the schema documentation.
The type property is normally only provided when creating a new record with the following syntax:
const result = await client.set({
type: 'match',
title: {
en: 'hello',
},
})If type is specified in other cases, it must always match the type of the existing record, as well as the schema prefix of that type. Type can never be overwritten for existing records.
Only values of type string are accepted for the digest type. Any value provided will be automatically passed through a SHA256 hashing algorithm. The digest is stored in the database instead of the actual passed string value.
const result = await client.set({
$id: 'usASxsd3',
type: 'user',
password: 'top_secret_password', // field with type 'digest'
})
/*
Value of `const result`: `usASxsd3`
Resulting record in database:
{
id: 'usASxsd3',
type: 'user',
password: '4bc838fb5a7160b6433be6c4e188ed1fee0cc08337789bd5d6c77994ad6b50c8' // using default secret 'selva-client'
}
*/The following operators are available with the digest type:
Field type timestamp accepts positive numeric values after the epoch (in milliseconds). In addition, it also accepts one string value: 'now'. When 'now' is provided, it is automatically converted to the current time in milliseconds since epoch.
The following operators are available with the timestamp type:
The url field type accepts any string values that are valid URLs.
The following operators are available with the url type:
The email field type accepts any string values that are valid email addresses.
The following operators are available with the email type:
The phone field type accepts any string values that are valid phone numbers.
The following operators are available with the phone type:
The string type accepts any string values.
The following operators are available with the string type:
The int type accepts any number values that are representable as an integer.
The following operators are available with the int type:
The float type accepts any number values that are representable as floating point numbers.
The following operators are available with the float type:
The number type accepts any number values.
The following operators are available with the number type:
The boolean type accepts a boolean value, true or false.
The following operators are available with the boolean type:
The text type accepts depends on whether the top level operator $language has been set.
If $langauge is set, text fields only accept string values, and the value is set in the language field of the text entry corresponding to the language.
const result = await client.set({
$language: 'en',
$id: 'maASxsd3',
type: 'match',
title: 'the super bowl 2020',
})If the $language operator is not present, the text type field accepts an object value with properties set to any languages that are present in the schema.
const result = await client.set({
$language: 'en',
$id: 'maASxsd3',
type: 'match',
title: {
en: 'the super bowl 2020',
de: 'das super schüssel 2020',
},
})The following operators are supported both on the text field itself, as well as all the language keys:
Fields with array type accept javascript array values where all entries correspond to the item type specified in the schema.
The following operators are available with the array type:
The json type allows any javascript values, unless properties has been defined for it in the schema. In that case, an object type value must be provided that contains only values that contain properties set in that schema definition.
The following operators are available with the json type:
Fields with type geo must always be set with an object where all of the following properties are set:
const result = await client.set({
$id: 'maASxsd3',
type: 'match',
geoField: {
lat: 60, // latitude, has to be a number (required field)
lon: 0.2, // longitude, has to be a number (required field)
},
})No operators exist for field of the geo type.
Fields with set type accept javascript array values where all entries correspond to the item type specified in the schema. They also accept a single item of the item type to set a list of one item. Any value set will reset the currently stored values of the set.
To add and remove items from the set, the following operators are supported:
Same as set but items are always id strings.
The object type can receive a javascript object as long as it only contains properties specified in the schema. All operators and values of the object properties are allowed based on the type of the property.
Only object specific operator is the $merge operator.
- Basic field type operators
- Number field type operators
- Set and reference field type operators
- Reference only field type operators
- Object field type operators
Number fields support the $increment operator, which itself takes a number value. If specified, the number value in the database is incremented by the specified amount. If not set, the number is assumed 0 and the $increment value is effectively set to the field, unless $default is specified in which case it is set before applying the $increment. The increment can be negative and fractional.
const result = await client.set({
$id: 'maASxsd3',
type: 'match',
value: { $increment: 10 }, // can be applied to int, float, number fields
})If provided, the value put in $default has to correspond the type of the field the operator is used on. It is only set if no value currently exists fo that field of the record.
/*
Let's assume the following record in database:
{
id: 'maASxsd3',
type: 'match',
title: {
en: 'yes'
}
}
*/
let result = await client.set({
id: 'maASxsd3',
value: { $default: 10 },
})
/*
Value of `const result`: `maASxsd3`
Resulting record in database:
{
id: 'maASxsd3',
type: 'match',
value: 10, // value is set, as it was empty
title: {
en: 'yes'
}
}
*/
result = await client.set({
id: 'maASxsd3',
value: { $default: 11 },
})
/*
Value of `const result`: `maASxsd3`
Resulting record in database:
{
id: 'maASxsd3',
type: 'match',
value: 10, // value is still 10, as it had already been set
title: {
en: 'yes'
}
}
*/Using the $value operator is practically always allowed instead of passing the value directly. It is rarely useful by itself, an is often only used if other operators are used with it, so specify what the actual value is to be set.
const result = await client.set({
$id: 'maASxsd3',
type: 'match',
value: { $value: 10 }, // same as value: 10
})The $ref option allows referencing other fields within the same object. Whenever the value of the field is read in a query, it actually resolves to the reference stored in it.
const result = await client.set({
$id: 'maASxsd3',
type: 'match',
value: { $ref: 'otherValue' },
otherValue: 10,
})The reference operator can be used in conjunction with other options, such as $default:
const result = await client.set({
$id: 'maASxsd3',
type: 'match',
value: { $default: { $ref: 'otherValue' } }, // the reference is established only if `.value` is not set
otherValue: 10,
})Default value: true
The $merge option operates exactly the same way as the top-level set $merge operator, but in the context of the fields of the object type. When an object is set with $merge: false, only the set fields will remain in the database.
The $add operator can be used to add one or more entries to a set or references type field. A single item type value or an array of item type values may be specified to $add. All the existing values in the set will remain, but no duplicates are allowed.
/*
Let's assume the following record in database:
{
id: 'maASxsd3',
type: 'match',
availableSeats: ['a2', 'a3', 'b5']
}
*/
let result = await client.set({
id: 'maASxsd3',
availableSeats: { $add: 'b12' },
})
/*
Value of `const result`: `maASxsd3`
Resulting record in database:
{
id: 'maASxsd3',
type: 'match',
availableSeats: ['a2', 'a3', 'b5', 'b12']
}
*/
result = await client.set({
id: 'maASxsd3',
availableSeats: { $add: ['b13', 'b14'] },
})
/*
Value of `const result`: `maASxsd3`
Resulting record in database:
{
id: 'maASxsd3',
type: 'match',
availableSeats: ['a2', 'a3', 'b5', 'b12', 'b13', 'b14']
}
*/The $delete operator can be used to remove one or more entries to a set or references type field. A single item type value or an array of item type values may be specified to $delete.
/*
Let's assume the following record in database:
{
id: 'maASxsd3',
type: 'match',
availableSeats: ['a2', 'a3', 'b5', 'b12', 'b13', 'b14']
}
*/
let result = await client.set({
id: 'maASxsd3',
availableSeats: { $delete: ['b13', 'b14'] },
})
/*
Value of `const result`: `maASxsd3`
Resulting record in database:
{
id: 'maASxsd3',
type: 'match',
availableSeats: ['a2', 'a3', 'b5', 'b12']
}
*/
result = await client.set({
id: 'maASxsd3',
availableSeats: { $delete: 'b12' },
})
/*
Value of `const result`: `maASxsd3`
Resulting record in database:
{
id: 'maASxsd3',
type: 'match',
availableSeats: ['a2', 'a3', 'b5']
}
*/Potentially dangerous to use advanced feature. Take care using this option.
Default value: true
The $hierarchy operator only applies to a very special case of references type fields: children and parents. When $hierarchy is set to true (default), if parents of the record being set are updated, their children will be updated to reflect the changes in the record. The same applies to parents of its children, if the children field is updated. When set to false, this default behaviour is ignored.