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

Update by id

Changes the columns you send on one row, and leaves the others as they are. The row is found by its primary key, or by the column you name.

In short

  • PUT /api/schema/<user-path>/<instance>/<database>/<table>/update-by-id/<id>
  • The body holds only the columns that change.
  • ?upsert=true inserts the row when the id is not there.
  • An unknown id changes nothing and answers data: null, unless you ask for a 404.
Method PUT
URL /api/schema/admin/mysql8/inventory/customers/update-by-id/:id[/:primaryKey]
Body the columns to change
Query params select, deep, upsert, returnDocument, throwErrorIfRecordNotFound
Answer data : the row after the change, or before it with returnDocument=before
Databases MongoDB, MySQL, MariaDB, PostgreSQL, SQL Server, Oracle, TiDB, Percona
Cached no. It clears the cached answers of the table.
From code g.sys.db.updateById
API id SCHEMA_PUT_UPDATE_BY_ID
Without a schema /api/gen/admin/mysql8/inventory/customers/update-by-id/:id[/:primaryKey] : below

The examples change the table of get all.

Change some columns

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 columns at once are fine.
  • On MongoDB, a key with dots changes that path only : "address.city".

Find the row by another column

PUT /api/schema/admin/mysql8/inventory/customers/update-by-id/Mallory/first_name
Body
{ "first_name": "Alice" }

The row whose first_name is Mallory gets the new name. The column of the URL can be in the body too.

More options

Option What it does
?upsert=true No row 999 ? One is inserted, with the id and the body. It is checked like a new row. See upsert.
?returnDocument=before The answer holds the row as it was. The update happens all the same.
?throwErrorIfRecordNotFound=true An unknown id answers 404 : Record not found.
?select=first_name&deep=… Shapes the row of the answer.

What the schema does

  • The columns you send are converted and checked like a save : types, trim, case, conversionFun, encryption, rules, validatorFun. A key the schema does not have is refused. Every error comes back at once, with 400.
  • required is checked for new rows only. An update does not check it.
  • A nested object on a column with a relation is saved in its own table, and replaced by its id, as in master save.
  • Version check. When the schema has a column with isConcurrencyControlField, the body must hold it, with the value the row has. Else the answer is 400 : Concurrency version mismatch in 'version'. This row/document is already updated. Nothing changes. See Optimistic concurrency control.

Only the rows of the caller

Update by id reads no find from the URL. A pre hook can add one to g.req.query.find. The row must then match both the id and that find, else nothing changes.

From your code

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

Without a schema : /api/gen

Every table also answers this operation under /api/gen, with or without a schema :
URL /api/gen/admin/mysql8/inventory/customers/update-by-id/:id[/:primaryKey]
API id GEN_PUT_UPDATE_BY_ID
From code g.sys.db.gen.updateByIdGen

The columns go in as you send them : nothing is converted or checked. On MongoDB, 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