DOCSP-9563 crud search text (#85)

* added CRUD Search Text page

Author: kyuan-mongodb

source/fundamentals/crud/read-operations.txt

@@ -9,11 +9,9 @@ Read Operations
 - :doc:`/fundamentals/crud/read-operations/sort`
 - :doc:`/fundamentals/crud/read-operations/skip`
 - :doc:`/fundamentals/crud/read-operations/limit`
-- :doc:`/fundamentals/crud/read-operations/geo`
 - :doc:`/fundamentals/crud/read-operations/project`
-
-..
-  - :doc:`/fundamentals/crud/read-operations/text`
+- :doc:`/fundamentals/crud/read-operations/geo`
+- :doc:`/fundamentals/crud/read-operations/text`
 
 .. toctree::
    :caption: Read Operations
@@ -23,9 +21,6 @@ Read Operations
    /fundamentals/crud/read-operations/sort
    /fundamentals/crud/read-operations/skip
    /fundamentals/crud/read-operations/limit
-   /fundamentals/crud/read-operations/geo
    /fundamentals/crud/read-operations/project
-
-..
-  /fundamentals/crud/read-operations/text
-
+   /fundamentals/crud/read-operations/geo
+   /fundamentals/crud/read-operations/text

source/fundamentals/crud/read-operations/text.txt

@@ -0,0 +1,235 @@
+===========
+Search Text
+===========
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to run a **text search** in the MongoDB
+Java driver.
+
+You can use a text search to retrieve documents that contain a **term**
+or a **phrase** in a specified field. A term is a sequence of characters
+that excludes whitespace characters. A phrase is a sequence of terms
+with any number of whitespace characters. 
+
+The following sections show you how to perform the following types of
+text searches:
+
+- Search Text by a Term
+- Search Text by a Phrase
+- Search Text with Terms Excluded
+
+If you want to sort your text search results, see the :ref:`Text Search
+<sorts-crud-text-search>` section of our Sort Results guide. 
+
+Sample Documents
+~~~~~~~~~~~~~~~~
+
+The following sections feature examples of text searches on the
+``fast_and_furious_movies`` collection. Each section uses a variable
+named ``collection`` to refer to the ``MongoCollection`` instance of the
+``fast_and_furious_movies`` collection. 
+
+The ``fast_and_furious_movies`` collection contains documents that
+describe one of the several movies that are part of the Fast and Furious
+movie franchise. Each document contains a title field and a tags field.
+
+.. code-block:: json
+
+   { "_id": 1, "title": "2 Fast 2 Furious ", "tags": ["undercover", "drug dealer"] } 
+   { "_id": 2, "title": "Fast 5", "tags": ["bank robbery", "full team"] }
+   { "_id": 3, "title": "Furious 7", "tags": ["emotional"] }
+   { "_id": 4, "title": "The Fate of the Furious", "tags": ["betrayal"] }
+
+Text Index
+~~~~~~~~~~
+
+You must create a **text index** before running a text search. A text
+index specifies the string or string array field on which to run a text
+search.
+
+In the following examples, you run text searches on the ``title``
+field in the ``fast_and_furious_movies`` collection. To enable text
+searches on the ``title`` field, create a text index using the
+:ref:`Indexes <index-text-indexes>` builder with the following 
+snippet: 
+
+.. literalinclude:: /includes/fundamentals/code-snippets/SearchText.java
+   :language: java
+   :dedent:
+   :start-after: begin textIndex
+   :end-before: end textIndex
+
+For more information, see the following resources:
+
+- :ref:`Text Indexes <text-indexes>` section of our Indexes guide
+- :manual:`Text Indexes </core/index-text/>` Server Manual Entry
+
+
+Text Search
+-----------
+
+Use the ``Filters.text()`` method to specify a text search. 
+
+The ``Filters.text()`` method uses the :doc:`Filters builder
+</fundamentals/builders/filters>` to define a query filter specifying
+what to search for during the text search. The query filter is
+represented by a :ref:`Bson <bson>` instance. Pass the query filter to the
+``find()`` method to run a text search. 
+
+When you execute the ``find()`` method, MongoDB runs a text search on
+all the fields indexed with the text index on the collection. MongoDB
+returns documents that contain one or more of the search terms and a
+relevance score for each result. For more information on relevance
+scores, see the :ref:`Text Search <sorts-crud-text-search>` section in
+our Sort Results guide.  
+
+Specify Options
+~~~~~~~~~~~~~~~
+
+You can include ``TextSearchOptions`` as the second parameter of the
+``Filters.text()`` method to specify text search options such as case
+sensitivity. By default, text searches run without case sensitivity
+which means the search matches lowercase and uppercase values.
+
+To specify a case sensitive search, use the following snippet:
+
+.. code-block:: java
+
+   TextSearchOptions options = new TextSearchOptions().caseSensitive(true);
+   Bson filter = Filters.text("SomeText", options);
+
+See the following API documentation for more information:
+
+- :java-core-api:`Filters.text() <com/mongodb/client/model/Filters.html#text(java.lang.String)>`
+- :java-core-api:`TextSearchOptions <com/mongodb/client/model/TextSearchOptions.html>`
+
+.. _term_search:
+
+Search Text by a Term
+~~~~~~~~~~~~~~~~~~~~~
+
+Pass a term as a string to the ``Filters.text()`` method to specify the
+term in your text search. 
+
+Example 
+```````
+
+The following example runs a text search on the documents in the
+``fast_and_furious_movies`` collection for titles that contain the
+term "fast":
+
+.. literalinclude:: /includes/fundamentals/code-snippets/SearchText.java
+   :language: java
+   :dedent:
+   :start-after: begin termExample
+   :end-before: end termExample
+
+The following shows the output of the preceding code:
+
+.. code-block:: json
+   :copyable: false
+
+   { "_id": 1, "title": "2 Fast 2 Furious ", "tags": ["undercover", "drug dealer"] }
+   { "_id": 2, "title": "Fast 5", "tags": ["bank robbery", "full team"] }
+
+To match multiple terms in your text search, separate each term
+with spaces in the ``Filters.text()`` builder method. The builder method
+returns the text search query as a ``Bson`` instance. When you pass
+this to the ``find()`` method, it returns documents that match any of
+the terms.
+
+Example 
+```````
+
+The following example runs a text search on the documents in the
+``fast_and_furious_movies`` collection for titles that contain the
+terms "fate" or "7":
+
+.. literalinclude:: /includes/fundamentals/code-snippets/SearchText.java
+   :language: java
+   :dedent:
+   :start-after: begin multipleTermExample
+   :end-before: end multipleTermExample
+
+The following shows the output of the preceding code:
+
+.. code-block:: json
+   :copyable: false
+
+   { "_id": 3, "title": "Furious 7", "tags": ["emotional"] }
+   { "_id": 4, "title": "The Fate of the Furious", "tags": ["betrayal"] }
+
+Search Text by a Phrase
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Pass a phrase with **escaped quotes** to the ``Filters.text()`` method to
+specify the phrase in your text search. Escaped quotes are double quote
+characters preceded by a backslash character. If you don't add escaped
+quotes around the phrase, the ``find()`` method runs a :ref:`term search
+<term_search>`. 
+
+Example 
+```````
+
+The following example runs a text search on the documents in the
+``fast_and_furious_movies`` collection for titles that contain the
+phrase "fate of the furious":
+
+.. literalinclude:: /includes/fundamentals/code-snippets/SearchText.java
+   :language: java
+   :dedent:
+   :start-after: begin phraseExample
+   :end-before: end phraseExample
+
+The following shows the output of the preceding code:
+
+.. code-block:: json
+   :copyable: false
+
+   { "_id": 4, "title": "The Fate of the Furious", "tags": ["betrayal"] }
+ 
+Search Text with Terms Excluded
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For each term you want to exclude from your text search, prefix the term
+with a minus sign in the string that you pass to the ``Filters.text()``
+builder method. 
+
+None of the documents returned from the search contain the excluded term
+in your text index field. 
+
+.. note::
+
+   You must have at least one text search term if you want to
+   exclude terms from your search. 
+
+Example 
+```````
+
+The following example runs a text search on the documents in the
+``fast_and_furious_movies`` collection for titles that contain the
+term "furious", but do not contain the term "fast":
+
+.. literalinclude:: /includes/fundamentals/code-snippets/SearchText.java
+   :language: java
+   :dedent:
+   :start-after: begin negateExample
+   :end-before: end negateExample
+
+The following shows the output of the preceding code:
+
+.. code-block:: json
+   :copyable: false
+
+   { "_id": 3, "title": "Furious 7", "tags": ["emotional"] }
+   { "_id": 4, "title": "The Fate of the Furious", "tags": ["betrayal"] }