text¶
On this page
Definition¶
-
text
¶ New in version 2.4.
Searches text content stored in the text index. The
text
command is case-insensitive.The
text
command returns all documents that contain any of the terms; i.e. it performs a logicalOR
search. By default, the command limits the matches to the top 100 scoring documents, in descending score order, but you can specify a different limit.The
text
command has the following syntax:The
text
command has the following parameters:Field Type Description search
string A string of terms that MongoDB parses and uses to query the text
index. Enclose the string of terms in escaped double quotes to match on the phrase. For further information on thesearch
field syntax, see The search Field.filter
document Optional. A query document to further limit the results of the query using another database field. Use any valid MongoDB query in the filter document, except if the index includes an ascending or descending index field as a prefix. If the index includes an ascending or descending index field as a prefix, the filter
is required and thefilter
query must be an equality match.project
document Optional. Limits the fields returned by the query to only those specified. By default, the _id
field returns as part of the result set, unless you explicitly exclude the field in the project document.limit
number Optional. The maximum number of documents to include in the response. The text
command sorts the results before applying thelimit
. The default limit is 100.language
string Optional. The language that determines the list of stop words for the search and the rules for the stemmer and tokenizer. If not specified, the search uses the default language of the index. For supported languages, see Text Search Languages. Specify the language in lowercase. Returns: The text
command returns a document that contains a fieldresults
that contains an array of the highest scoring documents, in descending order by score. See Output for details.Warning
The complete results of the
text
command must fit within theBSON Document Size
. Otherwise, the command will limit the results to fit within theBSON Document Size
. Use thelimit
and theproject
parameters with thetext
command to limit the size of the result set.Note
- If the
search
string includes phrases, the search performs anAND
with any other terms in the search string; e.g. search for"\"twinkle twinkle\" little star"
searches for"twinkle twinkle"
and ("little"
or"star"
or"twinkle"
). text
adds all negations to the query with the logicalAND
operator.- The
text
command ignores language-specific stop words, such asthe
andand
in English. - The
text
command matches on the complete stemmed word. So if a document field contains the wordblueberry
, a search on the termblue
will not match. However,blueberry
orblueberries
will match.
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 combinetext
with the$near
operator.- If the
The search
Field¶
The search
field takes a string of terms that MongoDB parses and
uses to query the text
index. Enclose the string of terms in
escaped double quotes to match on the phrase. Additionally, the
text
command treats most punctuation as delimiters,
except when a hyphen -
negates terms.
Prefixing a word with a hyphen sign (-
) negates a word:
- The negated word excludes documents that contain the negated word from the result set.
- When passed a search string that only contains negated words, text search will not match any documents.
- A hyphenated word, such as
pre-market
, is not a negation. The text command treats the hyphen as a delimiter.
Examples¶
The following examples assume a collection articles
that has a text
index on the field subject
:
Search for a Single Word¶
The following command searches for the word coffee
:
This query returns documents that contain the word coffee
,
case-insensitive, in the indexed subject
field.
Search for Multiple Words¶
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.
The following command searches for bake
or coffee
or cake
:
This query returns documents that contain either bake
or
coffee
or cake
in the indexed subject
field.
Search for a Phrase¶
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
"bake coffee cake"
:
This query returns documents that contain the phrase bake
coffee cake
.
Exclude a Term from the Result Set¶
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.
If the search text contains only negated terms, the text
command will not return any results.
The following examples searches for documents that contain the words
bake
or coffee
but do not contain the word cake
:
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:
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 with
a 0
in the project
document.
The following example returns only the _id
field and the subject
field in the matching documents:
Search with Additional Query Conditions¶
Use the filter
option to include additional query conditions.
The following example searches for a single word coffee
with an
additional filter on the about
field, but limit the results to 2
documents with the highest score and return only the subject
field
in the matching documents:
- The
filter
query document may use any of the available query operators. - Because the
_id
field is implicitly included, in order to return only thesubject
field, you must explicitly exclude (0
) the_id
field. Within theproject
document, you cannot mix inclusions (i.e.<fieldA>: 1
) and exclusions (i.e.<fieldB>: 0
), except for the_id
field.
See also
Search a Different Language¶
Use the language
option to specify Spanish as the language
that determines the list of stop words and the rules for the
stemmer and tokenizer:
See Text Search Languages for the supported languages.
Important
Specify the language in lowercase.
Output¶
The following is an example document returned by the text
command:
The text
command returns the following data:
-
text.
queryDebugString
¶ For internal use only.
-
text.
language
¶ The
language
field returns the language used for the text search. This language determines the list of stop words and the rules for the stemmer and tokenizer.
-
text.
results
¶ The
results
field returns an array of result documents that contain the information on the matching documents. The result documents are ordered by thescore
. Each result document contains:-
text.results.
obj
¶ The
obj
field returns the actual document from the collection that contained the stemmed term or terms.
-
text.results.
score
¶ The
score
field for the document that contained the stemmed term or terms. Thescore
field signifies how well the document matched the stemmed term or terms. See Control Search Results with Weights for how you can adjust the scores for the matching words.
-
-
text.
stats
¶ The
stats
field returns a document that contains the query execution statistics. Thestats
field contains:-
text.stats.
nscannedObjects
¶ The
nscannedObjects
field returns the total number of documents scanned to satisfy the providedfilter
.
-
text.stats.
n
¶ The
n
field returns the number of elements in theresults
array. This number may be less than the total number of matching documents, i.e.nfound
, if the full result exceeds theBSON Document Size
.
-
text.stats.
nfound
¶ The
nfound
field returns the total number of documents that match. This number may be greater than the size of theresults
array, i.e.n
, if the result set exceeds theBSON Document Size
.
-
text.stats.
timeMicros
¶ The
timeMicros
field returns the time in microseconds for the search.
-
Text Search Languages¶
The text index and the text
command support the following languages:
danish
dutch
english
finnish
french
german
hungarian
italian
norwegian
portuguese
romanian
russian
spanish
swedish
turkish
Note
If you specify a language value of "none"
, then the text search
has no list of stop words, and the text search does not stem or
tokenize the search terms.