Search String Content for Text¶

On this page

Search for a Term
Match Any of the Search Terms
Match Phrases
Match Some Words But Not Others
Limit the Number of Matching Documents in the Result Set
Specify Which Fields to Return in the Result Set
Search with Additional Query Conditions
Search for Text in Specific Languages
Text Search Output

In 2.4, you can enable the text search feature to create text indexes and issue text queries using the text.

The following tutorial offers various query patterns for using the text search feature.

The examples in this tutorial use a collection quotes that has a text index on the fields quote that contains a string and related_quotes that contains an array of string elements.

Note

You cannot combine the text command, which requires a special text index, with a query operator that requires a different type of special index. For example you cannot combine text with the $near operator.

Search for a Term¶

The following command searches for the word TOMORROW:

copy

db.quotes.runCommand( "text", { search: "TOMORROW" } )

Because text command is case-insensitive, the text search will match the following document in the quotes collection:

copy

{
  "_id" : ObjectId("50ecef5f8abea0fda30ceab3"),
  "quote" : "tomorrow, and tomorrow, and tomorrow, creeps in this petty pace",
  "related_quotes" : [
                       "is this a dagger which I see before me",
                       "the handle toward my hand?"
                     ],
  "src" : {
            "title" : "Macbeth",
            "from" : "Act V, Scene V"
          },
  "speaker" : "macbeth"
}

Match Any of the Search Terms¶

If the search string is a space-delimited text, text command performs a logical OR search on each term and returns documents that contains any of the terms.

For example, the search string "tomorrow largo" searches for the term tomorrow OR the term largo:

copy

db.quotes.runCommand( "text", { search: "tomorrow largo" } )

The command will match the following documents in the quotes collection:

copy

{
  "_id" : ObjectId("50ecef5f8abea0fda30ceab3"),
  "quote" : "tomorrow, and tomorrow, and tomorrow, creeps in this petty pace",
  "related_quotes" : [
                       "is this a dagger which I see before me",
                       "the handle toward my hand?"
                     ],
  "src" : {
            "title" : "Macbeth",
            "from" : "Act V, Scene V"
          },
  "speaker" : "macbeth"
 }

 {
   "_id" : ObjectId("50ecf0cd8abea0fda30ceab4"),
   "quote" : "Es tan corto el amor y es tan largo el olvido.",
   "related_quotes" : [
                        "Como para acercarla mi mirada la busca.",
                        "Mi corazón la busca, y ella no está conmigo."
                      ],
   "speaker" : "Pablo Neruda",
   "src" : {
             "title" : "Veinte poemas de amor y una canción desesperada",
             "from" : "Poema 20"
           }
  }

Match Phrases¶

To match the exact phrase that includes a space(s) as a single term, escape the quotes.

For example, the following command searches for the exact phrase "and tomorrow":

copy

db.quotes.runCommand( "text", { search: "\"and tomorrow\"" } )

If the search string contains both phrases and individual terms, the text command performs a compound logical AND of the phrases with the compound logical OR of the single terms, including the individual terms from each phrase.

For example, the following search string contains both individual terms corto and largo as well as the phrase \"and tomorrow\":

copy

db.quotes.runCommand( "text", { search: "corto largo \"and tomorrow\"" } )

The text command performs the equivalent to the following logical operation, where the individual terms corto, largo, as well as the term tomorrow from the phrase "and tomorrow", are part of a logical OR expression:

copy

(corto OR largo OR tomorrow) AND ("and tomorrow")

As such, the results for this search will include documents that only contain the phrase "and tomorrow" as well as documents that contain the phrase "and tomorrow" and the terms corto and/or largo. Documents that contain the phrase "and tomorrow" as well as the terms corto and largo will generally receive a higher score for this search.

Match Some Words But Not Others¶

A negated term is a term that is prefixed by a minus sign -. If you negate a term, the text command will exclude the documents that contain those terms from the results.

Note

If the search text contains only negated terms, the text command will not return any results.

The following example returns those documents that contain the term tomorrow but not the term petty.

copy

db.quotes.runCommand( "text" , { search: "tomorrow -petty" } )

Limit the Number of Matching Documents in the Result Set¶

Note

The result from the text command must fit within the maximum BSON Document Size.

By default, the text command will return up to 100 matching documents, from highest to lowest scores. To override this default limit, use the limit option in the text command, as in the following example:

copy

db.quotes.runCommand( "text", { search: "tomorrow", limit: 2 } )

The text command will return at most 2 of the highest scoring results.

The limit can be any number as long as the result set fits within the maximum BSON Document Size.

Specify Which Fields to Return in the Result Set¶

In the text command, use the project option to specify the fields to include (1) or exclude (0) in the matching documents.

Note

The _id field is always returned unless explicitly excluded in the project document.

The following example returns only the _id field and the src field in the matching documents:

copy

db.quotes.runCommand( "text", { search: "tomorrow",
                                project: { "src": 1 } } )

Search with Additional Query Conditions¶

The text command can also use the filter option to specify additional query conditions.

The following example will return the documents that contain the term tomorrow AND the speaker is macbeth:

copy

db.quotes.runCommand( "text", { search: "tomorrow",
                                filter: { "speaker" : "macbeth" } } )

Search for Text in Specific Languages¶

You can specify the language that determines the tokenization, stemming, and removal of stop words, as in the following example:

copy

db.quotes.runCommand( "text", { search: "amor", language: "spanish" } )

See Text Search Languages for a list of supported languages as well as Specify a Language for Text Index for specifying languages for the text index.

Text Search Output¶

The text command returns a document that contains the result set.

See Output for information on the output.

← Create a text Index Specify a Language for Text Index →