Replace by id¶
Replaces one MongoDB document with the body. A field you do not send is gone. To change some fields only, use update by id.
In short
PUT /api/schema/<user-path>/<instance>/<database>/<collection>/replace-by-id/<id>- MongoDB only. An SQL table answers
400. - The body is the whole new document : the schema checks it like a new row.
| Method | PUT |
| URL | /api/schema/admin/mongodb/inventory/customers/replace-by-id/:id[/:primaryKey] |
| Body | the whole new document |
| Query params | select, deep, upsert, returnDocument, throwErrorIfRecordNotFound |
| Answer | data : the document after the change, or before it with returnDocument=before |
| Databases | MongoDB only |
| Cached | no. It clears the cached answers of the collection. |
| From code | g.sys.db.replaceById |
| API id | SCHEMA_PUT_REPLACE_BY_ID |
| Without a schema | /api/gen/admin/mongodb/inventory/customers/replace-by-id/:id[/:primaryKey] : below |
The call¶
{ "customer_id": 1, "first_name": "Rex", "last_name": "Nestor", "pincode": 879654, "isActive": 0 }
- The document keeps its
_id, and gets exactly these fields. A field of the old document that is not in the body disappears. - By another column :
/replace-by-id/4/customer_id.
Options¶
| Option | What it does |
|---|---|
?upsert=true |
Inserts the document when the id is not there. |
?returnDocument=before |
Answers the old document. |
?throwErrorIfRecordNotFound=true |
Answers 404 for an unknown id, in place of data: null. |
select, deep |
Shape the answer. |
What the schema does¶
The body is checked like a new row : conversions, defaults, made values and every rule apply. So every required field must be there. When the schema has a version field of optimistic concurrency control, it must match the document.
On an SQL table¶
The answer is 400 : Replace by id API is not supported for instance type 'MYSQL_DB'. Use update by id with every column instead.
From your code¶
g.sys.db.replaceById 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/replace-by-id/:id[/:primaryKey] |
| API id | GEN_PUT_REPLACE_BY_ID |
| From code | g.sys.db.gen.replaceByIdGen |
The document goes in as you send it : 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