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 <warm...@gmail.com>
Authored: Tue Oct 18 13:09:53 2016 +0100
Committer: Adrian Warman <warm...@gmail.com>
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 <find/selectors>` used for :ref:`_find <api/db/_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 <find/selectors>` used for :ref:`_find <api/db/_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.
+
+

Reply via email to