Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id 181DB200BB3 for ; Wed, 19 Oct 2016 03:01:01 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id 16CEA160AFC; Wed, 19 Oct 2016 01:01:01 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 3A28A160AE5 for ; Wed, 19 Oct 2016 03:01:00 +0200 (CEST) Received: (qmail 35635 invoked by uid 500); 19 Oct 2016 01:00:59 -0000 Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 35621 invoked by uid 99); 19 Oct 2016 01:00:59 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 19 Oct 2016 01:00:59 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 4E582E00DC; Wed, 19 Oct 2016 01:00:59 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: vatamane@apache.org To: commits@couchdb.apache.org Date: Wed, 19 Oct 2016 01:00:59 -0000 Message-Id: <80ec8b8568c64c87b5e8eb4c95a551ae@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [1/3] documentation commit: updated refs/heads/master to 1957f02 archived-at: Wed, 19 Oct 2016 01:01:01 -0000 Repository: couchdb-documentation Updated Branches: refs/heads/master 2d448159e -> 1957f02cf Add material describing selector objects as part of a replication document. Project: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/repo Commit: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/commit/c92f59ce Tree: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/tree/c92f59ce Diff: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/diff/c92f59ce Branch: refs/heads/master Commit: c92f59ceee622ef64a658f0eb6c7f643539aff76 Parents: 34984e8 Author: Adrian Warman Authored: Tue Oct 18 13:09:53 2016 +0100 Committer: Adrian Warman Committed: Tue Oct 18 13:09:53 2016 +0100 ---------------------------------------------------------------------- src/api/database/changes.rst | 2 +- src/json-structure.rst | 70 ++++++++++++++++++++----------------- src/replication/intro.rst | 26 ++++++++++---- src/replication/replicator.rst | 27 ++++++++++++++ 4 files changed, 85 insertions(+), 40 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/c92f59ce/src/api/database/changes.rst ---------------------------------------------------------------------- diff --git a/src/api/database/changes.rst b/src/api/database/changes.rst index 2ff1bc3..70cb89b 100644 --- a/src/api/database/changes.rst +++ b/src/api/database/changes.rst @@ -477,7 +477,7 @@ This filter accepts only changes for documents which match a specified selector, defined using the same :ref:`selector syntax ` used for :ref:`_find `. -This is more significantly more efficient than using a JavaScript filter +This is significantly more efficient than using a JavaScript filter function and is the recommended option if filtering on document attributes only. Note that, unlike JavaScript filters, selectors do not have access to the http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/c92f59ce/src/json-structure.rst ---------------------------------------------------------------------- diff --git a/src/json-structure.rst b/src/json-structure.rst index 9711ae9..d24ecd9 100644 --- a/src/json-structure.rst +++ b/src/json-structure.rst @@ -242,39 +242,43 @@ List of Active Tasks Replication Settings ==================== -+--------------------------------+---------------------------------------------+ -| Field | Description | -+================================+=============================================+ -| source | Source database name or URL | -+--------------------------------+---------------------------------------------+ -| target | Target database name or URL | -+--------------------------------+---------------------------------------------+ -| create_target (optional) | Creates the target database | -+--------------------------------+---------------------------------------------+ -| continuous (optional) | Configure the replication to be continuous | -+--------------------------------+---------------------------------------------+ -| cancel (optional) | Cancels the replication | -+--------------------------------+---------------------------------------------+ -| doc_ids (optional) | Array of document IDs to be synchronized | -+--------------------------------+---------------------------------------------+ -| proxy (optional) | Address of a proxy server through which | -| | replication should occur | -+--------------------------------+---------------------------------------------+ -| since_seq (optional) | Sequence from which the replication should | -| | start | -+--------------------------------+---------------------------------------------+ -| filter (optional) | name of the filter function in the form of | -| | ``ddoc/myfilter`` | -+--------------------------------+---------------------------------------------+ -| query_params (optional) | Query parameter that are passed to the | -| | filter function; the value should be a | -| | document containing parameters as members | -+--------------------------------+---------------------------------------------+ -| use_checkpoints (optional) | Whether to use replication checkpoints | -| | or not | -+--------------------------------+---------------------------------------------+ -| checkpoint_interval (optional) | Specifies the checkpoint interval in ms. | -+--------------------------------+---------------------------------------------+ ++--------------------------------+---------------------------------------------------+ +| Field | Description | ++================================+===================================================+ +| source | Source database name or URL | ++--------------------------------+---------------------------------------------------+ +| target | Target database name or URL | ++--------------------------------+---------------------------------------------------+ +| cancel (optional) | Cancels the replication | ++--------------------------------+---------------------------------------------------+ +| checkpoint_interval (optional) | Specifies the checkpoint interval in ms. | ++--------------------------------+---------------------------------------------------+ +| continuous (optional) | Configure the replication to be continuous | ++--------------------------------+---------------------------------------------------+ +| create_target (optional) | Creates the target database | ++--------------------------------+---------------------------------------------------+ +| doc_ids (optional) | Array of document IDs to be synchronized | ++--------------------------------+---------------------------------------------------+ +| filter (optional) | name of the filter function in the form of | +| | ``ddoc/myfilter`` | ++--------------------------------+---------------------------------------------------+ +| proxy (optional) | Address of a proxy server through which | +| | replication should occur | ++--------------------------------+---------------------------------------------------+ +| query_params (optional) | Query parameter that are passed to the | +| | filter function; the value should be a | +| | document containing parameters as members | ++--------------------------------+---------------------------------------------------+ +| selector (optional) | Select the documents included in the replication. | +| | This option provides performance benefits | +| | compared with using the ``filter`` option. | ++--------------------------------+---------------------------------------------------+ +| since_seq (optional) | Sequence from which the replication should | +| | start | ++--------------------------------+---------------------------------------------------+ +| use_checkpoints (optional) | Whether to use replication checkpoints | +| | or not | ++--------------------------------+---------------------------------------------------+ .. _replication-status: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/c92f59ce/src/replication/intro.rst ---------------------------------------------------------------------- diff --git a/src/replication/intro.rst b/src/replication/intro.rst index a63610d..1a3f08d 100644 --- a/src/replication/intro.rst +++ b/src/replication/intro.rst @@ -73,13 +73,27 @@ B already exists in A and will wait for further changes. Controlling which Documents to Replicate ======================================== -There are two ways for controlling which documents are replicated, and which -are skipped. *Local* documents are never replicated (see :ref:`api/local`). +There are three options for controlling which documents are replicated, +and which are skipped: -Additionally, :ref:`filterfun` can be used in a replication (see -:ref:`replication-settings`). The replication task will then evaluate -the filter function for each document in the changes feed. The document will -only be replicated if the filter returns `true`. +1. Defining documents as being local. +2. Using :ref:`selectorobj`. +3. Using :ref:`filterfun`. + +Local documents are never replicated (see :ref:`api/local`). + +:ref:`selectorobj` can be included in a replication document (see +:ref:`replication-settings`). A selector object contains a query expression +that is used to test whether a document should be replicated. + +:ref:`filterfun` can be used in a replication (see +:ref:`replication-settings`). The replication task evaluates +the filter function for each document in the changes feed. The document is +only replicated if the filter returns `true`. + +.. note:: + Using a selector provides performance benefits when compared with using a + :ref:`filterfun`. You should use :ref:`selectorobj` where possible. Migrating Data to Clients ========================= http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/c92f59ce/src/replication/replicator.rst ---------------------------------------------------------------------- diff --git a/src/replication/replicator.rst b/src/replication/replicator.rst index a09a362..83f2a81 100644 --- a/src/replication/replicator.rst +++ b/src/replication/replicator.rst @@ -407,3 +407,30 @@ Example delegated replication document: As stated before, the ``user_ctx`` property is optional for admins, while being mandatory for regular (non-admin) users. When the roles property of ``user_ctx`` is missing, it defaults to the empty list ``[]``. + +.. _selectorobj: + +Selector Objects +================ + +Including a Selector Object in the replication document enables you to +use a query expression to determine if a document should be included in +the replication. + +The selector specifies fields in the document, and provides an expression +to evaluate with the field content or other data. If the expression resolves +to ``true``, the document is replicated. + +The selector object must: + +- Be structured as valid JSON. +- Contain a valid query expression. + +The syntax for a selector is the same as the +:ref:`selectorsyntax ` used for :ref:`_find `. + +Using a selector is significantly more efficient than using a JavaScript +filter function, and is the recommended option if filtering on document +attributes only. + +