Skip to content
This repository was archived by the owner on Oct 25, 2022. It is now read-only.

Latest commit

 

History

History
507 lines (411 loc) · 11 KB

set.md

File metadata and controls

507 lines (411 loc) · 11 KB

Set Method Query Reference

Introduction

The based.set() method changes data in the database. It can either create a new node or modify existing ones.
As argument it takes a single object formatted using the based-db query language, and it returns an object containing the ID of the node it just operated on, or undefined if the set was not succesful.
The query language supports several operators to change the behaviour of the set operation. These operators are prefixed with a $ (e.g. $id, $operator... ).
Fields without the $ represent a specific field of the node.

Operators can act at the node level or at the individual field level.

Node level operators

$id: string

If provided, the operation is applied to the node the id points to. By default, if the node doesn't exist yet, a node with that id will be created and the operation will be applied to it. This behaviour can be change with the $operation operator.

// This sets the 'title' field on a node with id 'ma6d044a24' of type 'match'
const result = await client.set({
  $id: 'ma6d044a24',
  type: 'match',
  title: {
    en: 'hello',
  },
})
// This creates a new node of type 'match' and fills the 'title' field with 'hello'.
// 'result' will hold the id of the node just set.
const result = await client.set({
  type: 'match',
  title: {
    en: 'hello',
  },
})

$db: string

There will be cases in which you'll want to store data on different indipendent database instances.
Each instance can be assigned a name, which can be later specified with the $db operator.
It can be left empty if only one database instance is present.

// Set operation on the 'users' server
const result = await client.set({
  $db: 'users',
  $id: 'ma6d044a24',
  type: 'match',
  title: {
    en: 'hello',
  },
})

aliases: string | string[]

An alias is an alternative way of referencing a node. Each node can have one or more aliases to be referenced by, and they can be set by modifying the aliases field of a node. This field is always present in a node.

This allows to later get the node by using the alias instead of the ID.

Setting

{
  aliases: [ 'alias' ]
}

Adding

{
  aliases: { $add: [ 'nice' ] }
}

Deleting

{
  aliases: { $delete: [ 'nice' ] }
}

Clearing

{
  aliases: []
 }

or

{
  aliases: { $delete: true }
}

$merge: boolean

Default value: true

The $merge operator can be used to specify whether any fields specified in the .set() should overwrite everything that currently exists in the database for that node (if it is updated), or whether any fields specified will be added or overwritten only if provided.

/*
Let's assume the following node 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 node 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 node 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 node 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
}

*/

$language: string

This operator changes how you set a value in a field of type text. See later for details. TODO

$operation: string

Values: upsert | create | update, defaults to upsert.

This operator changes the set operation type.

Upsert

Upsert mode is the default set operation type. It updates an existing node or creates a new one if no node exists.

const result = await client.set({
  $operation: 'upsert', // optional, defaults to 'upsert'
  $id: 'muASxsd3',
  title: {
    en: 'hello',
  },
})

Upsert acts both as create and update.

Create

Create mode fails if a node already exists, and returns undefined instead of the ID of the created node. If no entry exists with the specified $id or $alias, then it succesfully creates a new node, and returns its ID.

const result = await client.set({
  $operation: 'create',
  $id: 'maASxsd3',
  title: {
    en: 'hello',
  },
})

/*
If no node with id = maASxsd3 exists, value of `result` = `maASxsd3`
If the node already exists, value of `result`= `undefined`. In this case nothing is set in the database and the node remains as it was.
*/

The same applies to $alias.

const result = await client.set({
  $operation: 'create',
  $alias: 'myAlias',
  title: {
    en: 'hello',
  },
})

/*
If no node exists, value of `const result`: `maASxsd3`
If the node already exists, value of `const result`: `undefined`. In this case nothing is set in the database and the  node remains as it was.
*/

If neither $id nor $alias is provided but type is provided, a completely new node 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  node in database:
{
  id: 'maASxsd3',
  type: 'match',
  title: {
    en: 'hello'
  }
}
*/

Update

Update mode is the opposite of create, in that it fails if the node being updated does not exist.

let result = await client.set({
  $operation: 'create',
  type: 'match',
  title: {
    en: 'hello',
  },
})

/*
Value of `const result`: `undefined`
Node in the database remains untouched because we haven't provided an ID or alias.
*/

result = await client.set({
  $operation: 'create',
  $id: 'maASxsd3',
  title: {
    en: 'hello',
  },
})

/*
If the node exists, value of `const result`: `maASxsd3`, and the fields are set.
If the node does not exist, value of `const result`: `undefined`. In this case nothing is set in the database and the node remains as it was.
*/

Field type specific operators

Basic operators

These operators can be applied to any field type. The syntax and explanation follows.

$default : any

Only sets a value if it isn't already set.

client.set({
  $id: 'maASxsd3',
  username: { $default: 'giovanni' },
})

$delete : boolean

This unsets the node's field.

client.set({
  $id: 'maASxsd3',
  username: { $delete: true },
})
// This will delete the 'username' field.

set and references type field operators

You can add and remove elements to set and references fields using the $add and $delete operators. These operators can take a single value or an array of values.

$add: any | [any, any, ...]

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.

❗ Please note: Whenever a new node is created, if no parent is specified, it is implicitely set as a child of root. This is to avoid orphan nodes in the database. If you wish for new nodes not to be children of root, you can simply specify parents : ['parentId1', 'parentId2', ...] without using the $add operator. Only use the $add operator to add extra references to a list.

/*
Let's assume the following node in database, where availableSeats is of type 'set':
{
  id: 'maASxsd3',
  type: 'match',
  availableSeats: ['a2', 'a3', 'b5']
}
*/

let result = await client.set({
  id: 'maASxsd3',
  availableSeats: { $add: 'b12' },
})

/*
Value of `const result`: `maASxsd3`
Resulting node 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 node in database:
{
  id: 'maASxsd3',
  type: 'match',
  availableSeats: ['a2', 'a3', 'b5', 'b12', 'b13', 'b14']
}
*/

$delete: any | [any, any, ...]

This operator is the opposite of the $add operator, and takes the same arguments.

/*
Let's assume the following node 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 node 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 node in database:
{
  id: 'maASxsd3',
  type: 'match',
  availableSeats: ['a2', 'a3', 'b5']
}
*/

object and record type field operators

The only operation for objects and records is the merge operation, which allows to either overwrite the whole structure, or merge it. See below.

$merge: boolean

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.

/*
Let's assume the following node in database:
{
  id: 'maASxsd3',
  type: 'match',
  details: {
    league: 'serie-a',
    location: 'rome'
  }
}
*/

let result = await client.set({
  id: 'maASxsd3',
  details: {
    $merge: true, //optional, defaults to true
    league: 'serie-b',
  },
})

/*
Value of `const result`: `maASxsd3`
Resulting node in database:
{
  id: 'maASxsd3',
  type: 'match',
  details: {
    league: 'serie-b',
    location: 'rome'
  }
}
*/

let result = await client.set({
  id: 'maASxsd3',
  details: {
    $merge: false,
    league: 'serie-b',
  },
})

/*
Value of `const result`: `maASxsd3`
Resulting node in database:
{
  id: 'maASxsd3',
  type: 'match',
  details: {
    league: 'serie-b',
  }
}
*/