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

Array operations (schema API)

Changes array fields of MongoDB documents in place : push, addToSet, pull, pullAll, pop and set, on every document matching find, several operations in one call.
Method PUT
URL /api/schema/admin/mysql8/inventory/customers/array-operations
Body { find, select?, operations: [ … ] }
Query params none
Answer data : one array per operation with the documents matched, projected to the array (or select)
Databases MongoDB only
Cached no (a write ; it resets the cache of the table)
From code g.sys.db.arrayOperations
API id SCHEMA_ARRAY_OPERATIONS (groups, settings, hooks, WebSocket subscriptions)
The other family Array operations as a generated API

Generated (/api/gen) or schema (/api/schema) ?

Both families offer the same operations on the same URL pattern. The schema APIs read the schema of the table : values are converted to their types, validated, encrypted, defaulted and numbered before they reach the database. The generated APIs are schemaless : they pass your data as it is, so a number sent as "22" stays a string. Use the schema APIs for the tables your application writes to, and the generated APIs for quick reads and for tables without a schema.

The URL

/api/schema/admin/mysql8/inventory/customers/array-operations : replace admin with the user path of your account, mongodb with your instance, inventory with the database and customers with the table. The examples use this table :

customer_id first_name last_name last_update pincode isActive
1 Bob lin 2022-11-14 04: 34: 58 382345 1
2 Alice Page 2022-10-15 02: 10: 40 382346 1
3 Mallory Brown 2022-09-13 03: 44: 05 382347 1
4 Eve Mathly 2022-11-12 01: 59: 33 382348 1
5 Eve Page 2022-11-12 01: 59: 33 382349 1

The body

{
    "find": { "customer_id": 1 },
    "operations": [
        { "operation": "push", "path": "ages", "dataToPush": [ { "age": 33, "birth_year": 1989 } ] }
    ]
}
Key Meaning
find Which documents to change. {} : all of them.
select The fields to return for the matched documents. Without it, the array of path.
operations Run one after the other, each on every matched document.
Operation Keys Does
push path, dataToPush (array), position, slice, sort Appends the items. position inserts at an index, slice keeps the first N (or last N when negative), sort ({ field: 1 or -1 }) reorders.
addToSet path, dataToPush (one value or an array) Appends only the values which are not there yet.
pull path, queryToRemove Removes every item matching the query.
pullAll path, dataToPull (array) Removes every item equal to one of the values.
pop path, direction 1 removes the last item, -1 the first.
set dataToSet, arrayFilters, upsert Updates fields of items with the positional $[item] syntax and its filters.

Push and pull

Push two items at the front, keep the array at 10
{ "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": [ "old", "draft" ] } ] }

Set inside an array

{
    "find": {},
    "operations": [ {
        "operation": "set",
        "dataToSet": { "ages.$[item].age": 45, "ages.$[item].birth_year": 1999 },
        "arrayFilters": [ { "item.birth_year": 1999 } ],
        "upsert": true
    } ]
}
  • arrayFilters decide which items $[item] means, upsert: true inserts a document when find matches none.

Several operations at once

{ "find": {}, "operations": [
    { "operation": "push", "path": "ages", "dataToPush": [ { "age": 60 } ] },
    { "operation": "pull", "path": "ages", "queryToRemove": { "age": 2 } }
] }
Answer : one entry per operation
{ "success": true, "statusCode": 200, "data": [
    [ { "_id": "63e0775abd0e063920533f7c", "ages": [ { "age": 33 }, { "age": 60 } ] } ],
    [ { "_id": "63e0775abd0e063920533f7c", "ages": [ { "age": 33 }, { "age": 60 } ] } ]
] }

With a schema

  • The items pushed, added or set are converted and validated against the schema of the array field before they are written, like a save. Encrypted fields inside an array are handled too.

From your code

g.sys.db.arrayOperations makes the same call from custom APIs, hooks, events, schedulers and test cases, with the same headers and params. Pass true as the second argument to get the whole response envelope instead of data.

Headers

Every call takes the request headers : the tokens, x-am-response-case, x-am-content-type-response (JSON, XML, YAML…), x-am-response-object-type: make_flat, x-am-cache-control, x-am-get-encrypted-data, x-am-internationalization, x-am-tenant-username, x-am-meta.

Errors

Code When
401 The token in x-am-authorization is missing or invalid.
403 No group of the API user grants this API of this table, or a field of the request.
404 The instance, database or table of the URL does not exist, or the table has no schema (use /api/gen).
400 The query or the body is wrong : the error messages say which key and why.