Channel Data Model

This is a high-level overview of how channel and access information is stored in the _sync metadata.

What are channels?

Functionally, a channel defines read-side security for documents. Documents are assigned to zero or more channels, and users are granted access to zero or more channels. In order for a user to read a document through the Sync Gateway REST API (and by extension, via client replication), the document needs to be assigned to a channel that the user has access to.

Channels are associated with a particular revision of a document. All channel information for a document is stored in Sync Gateway's private _sync metadata block in the document itself. The _sync metadata isn't accessible to clients for read or write - it's managed by Sync Gateway, and is stripped from documents before they are replicated.

Channel information stored in Sync Gateway metadata

1. Channel presence history

The channels property in the _sync metadata is a list of all channels the document has ever been assigned. For channels that aren't assigned to the active revisions, the channels property tracks the revision when the document was removed from that channel.

Sample data:

"channels": {
      "channel_B": null,
      "channel_A": {
        "seq": 22,
        "rev": "2-f38e39675f20d50803192f14232f2226"
      }
    },

In the above example, the current (active) revision of the document belongs to channel channel_B. It previously was assigned to channel_A, but that assignment was removed at revision 2-f38e39675f20d50803192f14232f2226.

If a document is added/removed from a channel multiple times, only the most recent removal is tracked in the _channels metadata.

2. Channel information in the revision tree

In addition to the information stored in the channels property, Sync Gateway also stores channel information in the revision tree for the document. For each revision in the rev tree, we store the list of channels that are assigned to that revision of the document.

Channel metadata usage