DOCSP-29802: explain text index field weights

source/code-snippets/indexes/text.js

@@ -10,23 +10,26 @@ const client = new MongoClient(uri);
 async function run() {
   try {
     // begin-idx
-    const database = client.db("sample_mflix");
-    const movies = database.collection("movies");
+    const myDB = client.db("testDB");
+    const myColl = myDB.collection("blogPosts");
 
-    // Create a text index on the "fullplot" field in the
-    // "movies" collection.
-    const result = await movies.createIndex({ fullplot: "text" }, { default_language: "english" });
-    console.log(`Index created: ${result}`);
+    // Create a text index on the "title" and "body" fields
+    const result = await myColl.createIndex(
+      { title: "text", body: "text" },
+      { default_language: "english" },
+      { weights: { body: 10, title: 3 } }
+    );
     // end-idx
+    console.log(`Index created: ${result}`);
 
     // begin-query
-    const query = { $text: { $search: "java coffee shop" } };
-    const projection = { _id: 0, fullplot: 1 };
-    const cursor = movies
-      .find(query)
-      .project(projection);
+    const query = { $text: { $search: "life ahead" } };
+    const projection = { _id: 0, title: 1 };
+    const cursor = myColl.find(query).project(projection);
     // end-query
-
+    for await (const doc of cursor) {
+      console.log(doc);
+    }
   } finally {
     await client.close();
   }

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

@@ -32,26 +32,40 @@ code for creating a text index and using the ``$text`` query operator.
 Examples
 --------
 
-The following examples use the ``movies`` collection in the ``sample_mflix``
-database. In order to enable text searches on the ``title`` field, create
-the **text index** using the following command:
+The following examples use sample data from the ``movies`` collection in
+the ``sample_mflix`` database. In order to enable text searches on the
+``title``  field, create a **text index** by using the following command:
 
 .. code-block:: javascript
 
    db.movies.createIndex({ title: "text" });
 
-We use this text index for the examples, but you can create a compound
-text index that broadens your text queries to multiple fields as follows:
+We use a single field text index for the examples in this guide, but you can
+create a compound text index that broadens your text queries to multiple
+fields. The following command creates a text index on two fields in the
+``movies`` collection:
 
 .. code-block:: javascript
 
-   db.movies.createIndex({ title: "text", fullplot: "text" });
+   db.movies.createIndex({ title: "text", plot: "text" });
+
+.. tip:: Specify Field Weights in a Text Index
+
+   When creating a compound text index, you can specify a weight option to
+   prioritize certain text fields in your index relative to the other
+   indexed fields. When you execute a text search, the field weights
+   influence how MongoDB calculates the :ref:`text search score
+   <node-text-search-score>` for each matching document.
+
+   To learn more about specifying field weights when creating a text
+   index, see the :ref:`Text Indexes <node-fundamentals-text-indexes>`
+   section in the Indexes guide.
 
 You can only create *one* text index per collection. Every text search
 queries all the fields specified in that index for matches.
 
-See the MongoDB server manual for more information on creating
-:manual:`text indexes </core/index-text/>`.
+See the MongoDB server manual to learn more about :manual:`text indexes
+</core/index-text/>`.
 
 Query for Words
 ~~~~~~~~~~~~~~~
@@ -160,6 +174,8 @@ Querying with the negated term yields the following documents:
 
 .. include:: /includes/access-cursor-note.rst
 
+.. _node-text-search-score:
+
 Sort by Relevance
 ~~~~~~~~~~~~~~~~~
 

source/fundamentals/indexes.txt

@@ -187,38 +187,47 @@ To learn more, see
 :v6.0:`Clustered Indexes </reference/method/db.createCollection/#std-label-db.createCollection.clusteredIndex>` and
 :v6.0:`Clustered Collections </core/clustered-collections>`.
 
+.. _node-fundamentals-text-indexes:
+
 Text Indexes
 ~~~~~~~~~~~~
 
 **Text indexes** support text search queries on string content. These indexes
 can include any field whose value is a string or an array of string elements.
-MongoDB supports text search for various languages. You can specify the
-default language as an option when creating the index. Read our guide on
-:doc:`text search queries </fundamentals/crud/read-operations/text>` for more
-information.
 
-The following example uses the ``createIndex()`` method to create a
-``text`` index on the ``fullplot`` field in the ``movies`` collection in
-the ``sample_mflix`` database and specifies ``english`` as the default
-language.
+MongoDB supports text search for various languages, so you can specify the
+default language as an option when creating the index. You can also
+specify a weight option to prioritize certain text fields in your
+index relative to the other indexed fields.
+
+Read our guide on :ref:`text search queries <node-fundamentals-text>` for
+more information.
+
+The following example uses the ``createIndex()`` method to perform the
+following actions:
+
+- Create a ``text`` index on the ``title`` and ``body`` fields in the
+  ``blogPosts`` collection
+- Specify ``english`` as the default language
+- Set the field weight of ``body`` to ``10`` and ``title`` to ``3``
 
 .. literalinclude:: /code-snippets/indexes/text.js
    :language: js
    :start-after: begin-idx
    :end-before: end-idx
    :dedent:
 
-The following is an example of a query that would be covered by the index
-created above. Note that the ``sort`` is omitted because text indexes do not
-contain sort order.
+The following is an example of a query that uses the text index created
+in the previous code:
 
 .. literalinclude:: /code-snippets/indexes/text.js
    :language: js
    :start-after: begin-query
    :end-before: end-query
    :dedent:
 
-To learn more, see :manual:`Text Indexes </core/index-text>`.
+To learn more about text indexes, see :manual:`Text Indexes
+</core/index-text>` in the Server manual.
 
 Geospatial Indexes
 ~~~~~~~~~~~~~~~~~~