Patch commands perform a partial modification of existing models by setting the model with specified values.
This is in contrast with upsert commands which fully replace (or create) the models.
PATCH /rest/users/1
{ "city": "Copenhagen" }{
"data": { "id": "1", "name": "Anthony", "city": "Copenhagen" }
}Advanced patch commands use operators to perform a
transformation on the model's attributes. Operators are objects describing the
transformation to apply as { "_OPERATOR": ARGUMENT }, e.g. { "_add": 1 }.
The example below increments the user's age by 1.
PATCH /rest/users/1
{ "age": { "_add": 1 } }{
"data": { "id": "1", "name": "Anthony", "age": 31 }
}Some patch operators are specific to arrays, e.g. _push or _pop. Others are
specific to scalar attributes, e.g. _add.
If a scalar patch operator is applied to an array attribute, it will be applied to each element of the array.
The example below multiplies each score's element by 100.
PATCH /rest/users/1
{ "scores": { "_mul": 100 } }{
"data": { "id": "1", "name": "Anthony", "scores": [200, 300, 800] }
}It is possible to refer to another attribute of the same model using the
model.ATTRIBUTE notation.
The example below sets the model's first_name to the same value as its name.
PATCH /rest/users/1
{ "first_name": { "_set": "model.name" } }or the shorter syntax:
PATCH /rest/users/1
{ "first_name": "model.name" }{
"data": { "id": "1", "name": "Anthony", "first_name": "Anthony" }
}The _set operator assigns the value, like variable = value in JavaScript.
PATCH /rest/users/1
{ "first_name": { "_set": "Anthony" } }It is the same as regular patch commands:
PATCH /rest/users/1
{ "first_name": "Anthony" }The _invert operator flips a boolean attribute, like variable = !variable
in JavaScript. Its argument must always be null.
PATCH /rest/users/1
{ "is_manager": { "_invert": null } }The _add operator increments a number or integer attribute, like
variable += value in JavaScript.
PATCH /rest/users/1
{ "money": { "_add": 10.5 } }The _sub operator decrements a number or integer attribute, like
variable -= value in JavaScript.
PATCH /rest/users/1
{ "money": { "_sub": 10.5 } }The _mul operator multiplies a number or integer attribute, like
variable *= value in JavaScript.
PATCH /rest/users/1
{ "money": { "_mul": 2 } }The _div operator divides a number or integer attribute, like
variable /= value in JavaScript.
PATCH /rest/users/1
{ "money": { "_div": 2 } }The _replace operator replaces a string by another string inside a string
attribute, like variable.replace(regExp, value) in JavaScript. The argument
must be an array with the following elements:
- a regular expression, as a string: the pattern to replace
- the new value, as a string. It can contain the
$1,$&, etc. like thereplace()JavaScript function. - the regular expression flags. This is optional and defaults to
gi
PATCH /rest/article/1
{ "title": { "_replace": ["Anthony", "George"] } }The _insertstr operator inserts a string inside a string attribute at a
given position. The argument must be an array with the following elements:
- the position where to insert inside the string, as an integer. It can be a
positive integer (position from the beginning), a negative integer (position
from the end) or
null(i.e. the end). - the new value, as a string.
PATCH /rest/article/1
{ "title": { "_insertstr": [null, " text to append"] } }The _slicestr operator extracts part of a string attribute at a given start
and end position. The argument must be an array with the following elements:
- the position where the slice starts inside the string, as an integer. It can
be a positive integer (position from the beginning), a negative integer
(position from the end) or
null(i.e. the end). - the position where the slice ends, using the same kind of integer. It defaults to the end of the string.
PATCH /rest/article/1
{ "title": { "_slicestr": [0, 100] } }The _insert operator inserts some values inside an array attribute at a
given position. The argument must be an array with the following elements:
- the position where to insert inside the array, as an integer. It can be a
positive integer (position from the beginning), a negative integer (position
from the end) or
null(i.e. the end). - the new values, as several arguments.
PATCH /rest/user/1
{ "scores": { "_insert": [5, 100, 500, 300] } }The _slice operator extracts part of an array attribute at a given start and
end position. The argument must be an array with the following elements:
- the position where the slice starts inside the array, as an integer. It can be
a positive integer (position from the beginning), a negative integer (position
from the end) or
null(i.e. the end). - the position where the slice ends, using the same kind of integer. It defaults to the end of the array.
PATCH /rest/user/1
{ "scores": { "_slice": [0, 100] } }The _push operator inserts some values at the end of an array attribute. The
argument must be the values to insert.
PATCH /rest/user/1
{ "scores": { "_push": [100, 500, 300] } }The _unshift operator inserts some values at the beginning of an array
attribute. The argument must be the values to insert.
PATCH /rest/user/1
{ "scores": { "_unshift": [100, 500, 300] } }The _pop operator removes the last value of an array attribute. The argument
must always be null.
PATCH /rest/user/1
{ "scores": { "_pop": null } }The _shift operator removes the first value of an array attribute. The
argument must always be null.
PATCH /rest/user/1
{ "scores": { "_shift": null } }The _remove operator removes values from an array attribute. The argument
must be the set of values to remove.
PATCH /rest/user/1
{ "scores": { "_remove": [100, 200, 500] } }The _sort operator sort the values of an array attribute. The argument must
be either asc or desc to specify the sorting order. It defaults to asc.
PATCH /rest/user/1
{ "scores": { "_sort": "asc" } }Servers can specify additional custom operators.