Edit Page
.replaceCollection()
Replace all members of the specified collection (e.g. the comments of BlogPost #4).
await Something.replaceCollection(parentId, association)
.members(childIds);
Usage
#| Argument | Type | Details | |
|---|---|---|---|
| 1 | parentId | The primary key value(s) (i.e. ids) for the parent record(s). Must be a number or string (e.g. '507f191e810c19729de860ea' or 49). Alternatively, an array of numbers or strings may be specified (e.g. ['507f191e810c19729de860ea', '14832ace0c179de897'] or [49, 32, 37]). In this case, the child records will be replaced in each parent record. |
|
| 2 | association | The name of the plural ("collection") association (e.g. "pets") | |
| 3 | childIds | The primary key values (i.e. ids) for the child records that will be the new members of the association. Note that this does not create these records or destroy the old ones, it just attaches/detaches records to/from the specified parent(s). |
Errors
#| Name | Type | When? |
|---|---|---|
| UsageError | Thrown if something invalid was passed in. | |
| AdapterError | Thrown if something went wrong in the database adapter. | |
| Error | Thrown if anything else unexpected happens. |
See Concepts > Models and ORM > Errors for examples of negotiating errors in Sails and Waterline.
Example
#For user 3, replace all pets in the "pets" collection with pets 99 and 98:
await User.replaceCollection(3, 'pets')
.members([99,98]);
Edge cases
#- If the parent id does not actually correspond with an existing, persisted record, then this will do nothing.
- If one of the child ids does not actually correspond with an existing, persisted record, then that child id will be ignored, and only those members that correspond with the other provided child ids will be included in the replacement collection.
- If an empty array of child ids is provided, or if none of the provided child ids correspond to existing records, then this will detach all child records from the parent.
Notes
#
- This method can be used with
await, promise chaining, or traditional Node callbacks.- If the association is "2-way" (meaning it has
via) then the child records will be modified accordingly. If the attribute on the other side is singular, the each newly-linked-or-unlinked child record's foreign key will be changed. If it's plural, then each child record's collection will be modified accordingly.- In addition, if the
viapoints at a singular ("model") attribute on the other side, then.addToCollection()will "steal" these child records if necessary. For example, imagine you have an Employee model with this plural ("collection") attribute:involvedInPurchases: { collection: 'Purchase', via: 'cashier' }. If you executedEmployee.addToCollection(7, 'involvedInPurchases', [47])to assign this purchase to employee #7 (Dolly), but purchase #47 was already associated with a different employee (e.g. #12, Motoki), then this would "steal" the purchase from Motoki and give it to Dolly. In other words, if you executedEmployee.find([7, 12]).populate('involvedInPurchases'), Dolly'sinvolvedInPurchasesarray would contain purchase #47 and Motoki's would not.
v1.x
For a better experience on sailsjs.com, update your browser.
Reference
- Application
- Blueprint API
- Command-line interface
-
Configuration
- sails.config.*
- sails.config.blueprints
- sails.config.bootstrap()
- sails.config.custom
- sails.config.datastores
- sails.config.globals
- sails.config.http
- sails.config.i18n
- sails.config.log
- sails.config.models
- sails.config.policies
- sails.config.routes
- sails.config.security
- sails.config.session
- sails.config.sockets
- sails.config.views
-
Request (`req`)
- req._startTime
- req.body
- req.cookies
- req.fresh
- req.headers
- req.hostname
- req.ip
- req.ips
- req.isSocket
- req.method
- req.options
- req.originalUrl
- req.params
- req.path
- req.protocol
- req.query
- req.secure
- req.signedCookies
- req.socket
- req.subdomains
- req.url
- req.wantsJSON
- req.xhr
- req.accepts()
- req.acceptsCharsets()
- req.acceptsLanguages()
- req.allParams()
- req.file()
- req.get()
- req.is()
- req.param()
- req.setLocale()
- req.setTimeout()
- req.host
- Response (`res`)
- WebSockets
Reference
Built with Love
The Sails framework is built by a web & mobile shop in Austin, TX, with the help of our contributors. We created Sails in 2012 to assist us on Node.js projects. Naturally we open-sourced it. We hope it makes your life a little bit easier!
© 2012-2025 The Sails Company.
The Sails framework is free and open-source under the MIT License.
Illustrations by Edamame.