document-filtering.txt

.. _c2c-beta-document-filtering:

==================
Document Filtering
==================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

.. include:: /includes/beta-feature.rst

.. include:: /includes/document-filtering-intro.rst

Syntax 
------

The :ref:`c2c-api-start` API endpoint accepts an optional ``documentFilter`` 
parameter with the following syntax:

.. code-block:: json
   :copyable: false

   "documentFilter" : {
      "field" : <field-name>,
      "matchValues" : [<field-values>] 
   }

Parameter Fields 
----------------

.. list-table::
   :header-rows: 1

   * - Field 
     - Type 
     - Necessity 
     - Description 

   * - ``field`` 
     - String
     - Required 
     - Field name  

   * - ``matchValues`` 
     - Array 
     - Required 
     - Field value(s) that a document must have in order to migrate.

Limitations
-----------

.. include:: /includes/document-filtering-limitations.rst

Examples 
--------

Start ``mongosync`` with a Document Filter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/intro-start-api-example-intro.rst

``cluster0`` contains the ``travel`` database, which includes the 
``restaurants``, ``attractions``, and ``lodging`` collections. Documents in the 
``restaurants``, ``attractions``, and ``lodging`` collections all contain a 
``city`` field. 

The ``documentFilter`` document in this example filters for documents where the 
``city`` field is either ``Los Angeles``, ``New York``, or ``San Francisco``. 

.. code-block:: json

   "documentFilter" : {
             field : "city",
             matchValues: [ "Los Angeles", "New York", "San Francisco" ]
         }

Learn More 
----------

- :ref:`c2c-beta-program`
- :ref:`c2c-api-start`