A newer version of this documentation is available.

View Latest

channel()

      +

      Assigning Sync Gateway channels

      Related Topics:    access()   |   channel()   |   expiry()   |   requireAccess()   |   requireAdmin()   |   requireRole()   |   requireUser()   |   role()   |   throw()

      Function Call

      channel(channelname)

      Purpose

      Use the channel() function to route the document to the named channel(s).

      Arguments

      Argument Description

      channels

      Must be a string identifying a channel name, or an array of strings to specify multiple channel names (for example: (['channel1', 'channel2']); the function is applied to each element in the array.

      If the value resolves to null the function result is a no-op.

      Sync Function Examples

      Couchbase Sync Gateway defines a Sync Function at the collection level. Defining at this level helps simplify data management and improve data reliability. Each collection in the system allows for only one Sync Function, which enables the specification of Access Control rules.

      Example 1. Default Sync Function
      function (doc, oldDoc, meta) {
         channel(CollectionName);
      
      }

      Here the function then calls the channel and passes in the name of the collection (CollectionsName) as an argument.

      By default, every document in the collection is automatically assigned to a channel with the same name as the collection. This system automatically creates a channel with the collection’s name. The assignment of all documents to the collection channel is functionally similar to assigning them to the Star Channel.

      To override this, use a custom sync function or a Specified Default Sync Function.

      Example 2. Upgraded Default Sync Function
      function (doc, oldDoc, meta) {
         channel(doc.channels);
      
      }

      Here is the default Sync Function when you have upgraded; it remains the same as the previous version.

      Context

      The channel function can be called zero or more times from the sync function, for any document.

      Channels don’t have to be predefined.
      A channel implicitly comes into existence when a document is routed to it.

      Routing changes have no effect until the document is actually saved in the database, so if the sync function first calls channel() or access(), but then rejects the update, the channel and access changes will not occur.

      As a convenience, it is legal to call channel with a null or undefined argument; it simply does nothing.
      This allows you to do something like channel(doc.channels) without having to first check whether doc.channels exists.

      Use

      Example 3. channel(channelname)

      This example routes all "published" documents to the "public" channel:

      function (doc, oldDoc, meta) {
         if (doc.published) {
            channel("public");
         }
      }