Edit Page

Remove (blueprint)

Remove a foreign record (e.g. a comment) from one of this record's collections (e.g. "comments").

DELETE /:model/:id/:association/:fk

This action removes a reference to some other record (the "foreign" or "child" record) from a collection of this record (the "primary" or "parent" record). Note that this does not actually destroy the foreign record, it just unlinks it.

  • If the primary record does not exist, this responds using res.notFound().
  • If the foreign record does not exist, this responds using res.notFound().
  • If the collection doesn't contain a reference to the foreign record, this action will not modify any records.
  • If the association is "2-way" (meaning it has via), then the foreign key or collection it points to with that via will also be updated on the foreign record.

Parameters

Parameter Type Details
model The identity of the containing model for the parent record.

e.g. 'store' (in /store/16/employeesOfTheMonth/7)
id The desired parent record's primary key value.

e.g. '16' (in /store/16/employeesOfTheMonth/7)
association The name of the collection attribute.

e.g. 'employeesOfTheMonth'
fk The primary key value (usually id) of the child record to remove from the collection.

e.g. '7'

Example

Say you're building an app for a small chain of grocery stores. Each store has a giant television screen that displays the current "Employees of the Month" at that store, so that customers and team members see it when they walk in the door. In order to be sure it is up to date, you build a scheduled job (e.g. using cron) that runs on the first day of every month to change the "Employees of the Month" for each store in their system.

Let's say that, as a part of this scheduled job, we send a request to remove Dolly (employee #7) from store #16's employeesOfTheMonth:

DELETE /store/16/employeesOfTheMonth/7

Run in Postman

Expected response
{
  "id": 16,
  "name": "Parmer and N. Lamar",
  "createdAt": 1485552033435,
  "updatedAt": 1485552048794,
  "employeesOfTheMonth": [
    {
      "id": 12,
      "name": "Motoki",
      "createdAt": 1485462079725,
      "updatedAt": 1485476060873
    },
    {
      "id": 4,
      "name": "Timothy",
      "createdAt": 1485462079727,
      "updatedAt": 1485476090874
    }
  ]
}

Socket notifications

If you have WebSockets enabled for your app, then every client subscribed to the parent record will receive a notification about the removed child, where the notification event name is that of the parent model identity (e.g. store), and the “message” has the following format:

id: <the parent record's primary key value>,
verb: 'removedFrom',
attribute: <the parent record collection attribute name>,
removedIds: <the now-removed child records' primary key values>

For instance, continuing the example above, all clients subscribed to employee #7 (except for the client making the request) would receive the following message:

{
  id: 16,
  verb: 'removedFrom',
  attribute: 'employeesOfTheMonth',
  removedIds: [ 7 ]
}

Clients subscribed to the child record receive an additional notification:

Assuming employeesOfTheMonth was defined with a via, then either updated or removedFrom notifications would also be sent to any clients who were subscribed to Dolly, the child record we removed.

If the via-linked attribute on the other side is also plural (e.g. employeeOfTheMonthAtStores), then another removedFrom notification will be sent. Otherwise, if the via points at a singular attribute (e.g. employeeOfTheMonthAtStore) then the updated notification will be sent.

Notes

  • If you'd like to spend some more time with Dolly, a more detailed walkthrough for the example above is available here.
  • This action is for dealing with plural ("collection") attributes. If you want to set or unset a singular ("model") attribute, just use update and set the foreign key to the id of the new foreign record (or null to clear the association).
  • If you want to completely replace the set of records in the collection with another set, use the replace blueprint.

Is something missing?

If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the sails repo. Once we merge it, the changes will be reflected on the website the next time it is deployed.

Sails logo
  • Home
  • Get started
  • Support
  • Documentation
  • Documentation

For a better experience on sailsjs.com, update your browser.

Check out the full Sailsconf 2022 playlist on Youtube

Tweet Follow @sailsjs

Documentation

Reference Concepts App structure | Upgrading Contribution guide | Tutorials More

Reference

  • Application
    • Advanced usage
      • Lifecycle
      • sails.LOOKS_LIKE_ASSET_RX
      • sails.getActions()
      • sails.getRouteFor()
      • sails.lift()
      • sails.load()
      • sails.lower()
      • sails.registerAction()
      • sails.registerActionMiddleware()
      • sails.reloadActions()
      • sails.renderView()
      • sails.request()
      • sails.getBaseUrl()
    • sails.config.custom
    • sails.getDatastore()
    • sails.getUrlFor()
    • sails.log()
  • Blueprint API
    • add to
    • create
    • destroy
    • find one
    • find where
    • populate where
    • remove from
    • replace
    • update
  • Command-line interface
    • sails --version
    • sails console
    • sails debug
    • sails generate
    • sails inspect
    • sails lift
    • sails new
  • 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`)
    • res.attachment()
    • res.badRequest()
    • res.clearCookie()
    • res.cookie()
    • res.forbidden()
    • res.get()
    • res.json()
    • res.jsonp()
    • res.location()
    • res.notFound()
    • res.ok()
    • res.redirect()
    • res.send()
    • res.serverError()
    • res.set()
    • res.status()
    • res.type()
    • res.view()
    • res.negotiate()
  • Waterline (ORM)
    • Datastores
      • .driver
      • .manager
      • .leaseConnection()
      • .sendNativeQuery()
      • .transaction()
    • Models
      • .addToCollection()
      • .archive()
      • .archiveOne()
      • .avg()
      • .count()
      • .create()
      • .createEach()
      • .destroy()
      • .destroyOne()
      • .find()
      • .findOne()
      • .findOrCreate()
      • .getDatastore()
      • .removeFromCollection()
      • .replaceCollection()
      • .stream()
      • .sum()
      • .update()
      • .updateOne()
      • .validate()
      • .native()
      • .query()
    • Queries
      • .catch()
      • .decrypt()
      • .exec()
      • .fetch()
      • .intercept()
      • .limit()
      • .meta()
      • .populate()
      • .skip()
      • .sort()
      • .then()
      • .tolerate()
      • .toPromise()
      • .usingConnection()
      • .where()
    • Records
      • .toJSON()
  • WebSockets
    • Resourceful PubSub
      • .getRoomName()
      • .publish()
      • .subscribe()
      • .unsubscribe()
    • sails.sockets
      • .addRoomMembersToRooms()
      • .blast()
      • .broadcast()
      • .getId()
      • .join()
      • .leave()
      • .leaveAll()
      • .removeRoomMembersFromRooms()
      • sails.sockets.id()
    • Socket client
      • io.sails
      • io.socket
      • SailsSocket
        • Methods
        • Properties
      • io.socket.delete()
      • io.socket.get()
      • io.socket.off()
      • io.socket.on()
      • io.socket.patch()
      • io.socket.post()
      • io.socket.put()
      • io.socket.request()

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!

Sails:
  • What is Sails?
  • Community
  • News
  • For business
About:
  • Our company
  • Security
  • Legal
  • Logos/artwork
Help:
  • Get started
  • Documentation
  • Docs
  • Contribute
  • Take a class

© 2012-2022 The Sails Company. 
The Sails framework is free and open-source under the MIT License. 
Illustrations by Edamame.