Skip to content
This page View Markdown Open in ChatGPT Open in Claude

Array operations

Changes the lists inside MongoDB documents : push, addToSet, pull, pullAll, pop and set. It works on every document that find matches, with several operations in one call.

In short

  • PUT /api/schema/<user-path>/<instance>/<database>/<collection>/array-operations
  • MongoDB only. An SQL table answers 400 : This API is only supported for mongodb.
  • The body holds a find and a list of operations, run one after the other.
Method PUT
URL /api/schema/admin/mongodb/inventory/customers/array-operations
Body { find, select?, operations: [ … ] }
Query params none
Answer data : one list for each operation, with the matched documents after it
Databases MongoDB only
Cached no. It clears the cached answers of the collection.
From code g.sys.db.arrayOperations
API id SCHEMA_ARRAY_OPERATIONS
Without a schema /api/gen/admin/mongodb/inventory/customers/array-operations : below

The body

The examples change this document of customers :

{ "_id": "63e0775abd0e063920533f7c", "customer_id": 1, "ages": [ { "age": 33, "birth_year": 1989 } ], "tags": [ "new", "draft" ] }
Body : push one item into ages
{
    "find": { "customer_id": 1 },
    "operations": [
        { "operation": "push", "path": "ages", "dataToPush": [ { "age": 60, "birth_year": 1962 } ] }
    ]
}
Key What it holds
find Which documents change. {} : all of them.
select The fields to answer for the matched documents. Without it, the list of path.
operations The changes, run one after the other, each on every matched document.
Operation Keys What it does
push path, dataToPush (a list), position, slice, sort Adds the items. position : at this index. slice : keep the first N items (the last N when negative). sort ({ age: 1 }) : reorder.
addToSet path, dataToPush (a value or a list) Adds only the values that are not there yet.
pull path, queryToRemove Removes every item that matches the query.
pullAll path, dataToPull (a list) Removes every item equal to one of the values.
pop path, direction 1 removes the last item, -1 the first.
set dataToSet, arrayFilters, upsert Changes fields of the items that arrayFilters pick, with $[item].

Each operation refuses a missing key : Please provide 'queryToRemove' to query array items and remove them.

Push and pull

Push two items at the front, sort by age, keep 10 items
{ "find": {}, "operations": [ { "operation": "push", "path": "ages", "dataToPush": [ { "age": 2 }, { "age": 5 } ], "position": 0, "slice": 10, "sort": { "age": 1 } } ] }
Remove the items of a year
{ "find": { "customer_id": 1 }, "operations": [ { "operation": "pull", "path": "ages", "queryToRemove": { "birth_year": 1989 } } ] }
Remove exact values
{ "find": {}, "operations": [ { "operation": "pullAll", "path": "tags", "dataToPull": [ "new", "draft" ] } ] }

Change items in place : set

{
    "find": {},
    "operations": [ {
        "operation": "set",
        "dataToSet": { "ages.$[item].age": 45 },
        "arrayFilters": [ { "item.birth_year": 1989 } ]
    } ]
}
  • arrayFilters is required : it says which items $[item] stands for.
  • upsert: true inserts a document when find matches none.

Several operations at once

{ "find": { "customer_id": 1 }, "operations": [
    { "operation": "push", "path": "ages", "dataToPush": [ { "age": 60 } ] },
    { "operation": "pull", "path": "ages", "queryToRemove": { "age": 33 } }
] }
Answer : one list for each operation
{ "success": true, "statusCode": 200, "data": [
    [ { "_id": "63e0775abd0e063920533f7c", "ages": [ { "age": 33, "birth_year": 1989 }, { "age": 60 } ] } ],
    [ { "_id": "63e0775abd0e063920533f7c", "ages": [ { "age": 60 } ] } ]
] }

Good to know

  • With a schema, the items that are pushed, added or set are converted and checked like a save, encrypted columns included. A path that is not a list in the schema is refused : Type of 'ages' should be array in schema.
  • Columns. The columns of find must be ones the groups of the caller may use.

From your code

g.sys.db.arrayOperations makes the same call from custom APIs, hooks, events, schedulers and test cases.

Without a schema : /api/gen

Every collection also answers this operation under /api/gen, with or without a schema :
URL /api/gen/admin/mongodb/inventory/customers/array-operations
API id GEN_ARRAY_OPERATIONS
From code g.sys.db.gen.arrayOperationsGen

The items go in as you send them : nothing is converted or checked. A text that looks like an ObjectId is turned into one.

Headers and errors

This operation takes the request headers of every API. It answers the envelope, with the status codes and the messages of every API.

Related : All APIs · Table schema · Pre hooks · Post hooks · API group permission