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

Update by id (schema API)

Changes the fields you send on one row and leaves the others alone. The row is found by its primary key, or by the column you name.
Method PUT
URL /api/schema/admin/mysql8/inventory/customers/update-by-id/:id[/:primaryKey]
Body the fields to change
Query params select, deep, upsert, returnDocument, throwErrorIfRecordNotFound, find
Answer data : the row after the change (or before, with returnDocument=before)
Databases MongoDB, MySQL, MariaDB, PostgreSQL, SQL Server, Oracle, TiDB, Percona
Cached no (a write ; it resets the cache of the table)
From code g.sys.db.updateById
API id SCHEMA_PUT_UPDATE_BY_ID (groups, settings, hooks, WebSocket subscriptions)
The other family Update by id 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/update-by-id/:id[/:primaryKey] : replace admin with the user path of your account, mysql8 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

Some fields

PUT /api/schema/admin/mysql8/inventory/customers/update-by-id/1
Body
{ "pincode": 382330 }
Answer
{
    "success": true,
    "statusCode": 200,
    "data": { "customer_id": 1, "first_name": "Bob", "last_name": "lin", "last_update": "2022-11-14T04:34:58.000Z", "pincode": 382330, "isActive": 1 }
}
  • Send only what changes. Several fields at once are fine. On MongoDB, a nested key like "address.city" updates that path.

By another column

PUT /api/schema/admin/mysql8/inventory/customers/update-by-id/Bob/first_name
  • The row whose first_name is Bob is updated. The column named as the key can itself be in the body : /update-by-id/Mallory/first_name with { "first_name": "Alice" } renames her.

Insert when missing : upsert

PUT /api/schema/admin/mysql8/inventory/customers/update-by-id/999?upsert=true
Body
{ "first_name": "Daphney", "last_name": "Sonia", "pincode": 980220 }
  • No row with customer_id 999 : one is inserted with the id and the body (the body is validated as a save). A row exists : it is updated. On every database.

The row before the change

PUT /api/schema/admin/mysql8/inventory/customers/update-by-id/1?returnDocument=before
  • The answer holds the row as it was ; the update happens all the same. Default : after. See returnDocument.

Unknown id

  • By default an unknown id answers success: true with data: null and changes nothing. With ?throwErrorIfRecordNotFound=true it answers 404 and Record not found.
  • find adds conditions the row must match : ?find={isActive:1}. A pre hook can add the condition for every call.
PUT /api/schema/admin/mysql8/inventory/customers/update-by-id/1?select=first_name,last_name&deep=[{s_key:'customer_id',t_col:'orders',t_key:'customer_id'}]

What the schema does

  • The fields sent are converted and validated like a save (types, trim, case, conversionFun, encryption, rules, validatorFun) ; unknown keys are refused ; required only applies to the fields present. Every error comes back at once with 400.
  • A nested object on a relation field is saved or updated in its table and replaced by its id, as in master save.
  • Version check. When the schema has a field with isConcurrencyControlField, the body must carry it and its value must be the one of the row : otherwise 400 with Concurrency version mismatch in 'version'. This row/document is already updated. and nothing changes. See Optimistic concurrency control.

From your code

g.sys.db.updateById 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.