Full-text search query syntax

Full-text search offers two text-based query types: type: "text" for BM25 token search over one or more named fields, and type: "query_string" for the full Lucene grammar, with boolean operators, phrases, boosting, fuzzy matching, and more.

Choosing a query type

The two types differ in the capabilities they support:

Feature	`type: "text"`	`type: "query_string"`
Purpose	Token search on one or more fields	Lucene query syntax
Field targeting	Required `fields`, one or more text fields (scores against all)	No `field`/`fields` param; use Lucene field qualifiers (`title:(...)`) in the query
Multi-word behavior	Token match, OR across terms (BM25)	OR by default; use `AND`, quotes, etc. for other logic
Boolean operators	Not supported (treated as words)	`AND`, `OR`, `NOT`, `+`, `-`
Phrase prefix	Not supported	`"phrase pre"*` (last term as prefix)
Single-term prefix (`auto*`)	Not supported	Not supported. Use phrase prefix
Phrase matching	Not supported in `score_by` (use `query_string` or `$match_phrase` filter)	Wrap in quotes: `"exact phrase"`
Phrase slop	Not supported	`"phrase"~N`
Boosting	Not supported	`term^N`
Regex	Not supported	`field:/pattern.*/`
Fuzzy matching	Not supported	`term~`, `term~N` (typo tolerance)
Stemming	Supported (when enabled)	Supported (when enabled)
Case sensitivity	Case-insensitive	Case-insensitive

Token matching (`type: "text"`)

With type: "text", the query string is run through the field’s analyzer pipeline (see Tokens and analyzers) and each resulting term contributes to the BM25 score. Multiple terms use OR semantics: documents can match if they contain any of the terms; documents that match more terms or stronger term statistics typically rank higher. Matching is case-insensitive. Exact phrase constraints (adjacent words in order) belong in type: "query_string" using quotes, or in a $match_phrase filter.

Query	Matches	Doesn’t match
`machine learning`	”Machine learning is great” (has “machine”)	“Vector databases only” (neither term)
`machine learning`	”We use learning and machine” (both terms present, any order)	“Vector databases only” (neither term)
`machine`	”Machine learning is great"	"Vector databases only” (no “machine”)

Key behaviors

Single term (machine): Matches documents containing that term. Case-insensitive.
Multiple terms (machine learning): Each term is searched independently with OR-style matching and combined BM25 scoring, not as a single adjacent phrase.
No operator support: Characters like AND, OR, NOT, *, ~, ^, +, -, and quotes are treated as literal text.

Lucene query syntax (`type: "query_string"`)

With type: "query_string", you write Lucene query syntax, with operator support. Field names are embedded in the query itself (e.g., content:(term)) and can combine multiple fields with boolean operators.

Operator	Syntax	Example	Description
Term	`field:(word)`	`body:(computers)`	Match documents containing term
Multiple terms	`field:(a b)`	`body:(machine learning)`	OR by default, matches either term
Phrase	`field:("words")`	`body:("machine learning")`	Exact phrase match (adjacent, in order)
AND	`AND`	`body:(a AND b)`	Both terms required
OR	`OR`	`body:(a OR b)`	Either term matches (same as default)
NOT	`NOT`	`body:(a NOT b)`	Exclude second term
Required	`+term`	`body:(+database search)`	Term must be present
Excluded	`-term`	`body:(database -deprecated)`	Term must not be present
Grouping	`(expr)`	`body:((a OR b) AND c)`	Control precedence
Phrase slop	`"phrase"~N`	`body:("fast search"~2)`	Allow up to N words between phrase terms
Boost	`term^N`	`body:(machine^3 learning)`	Multiply the clause’s relevance score by N (`0` or greater, decimals allowed)
Phrase prefix	`"phrase pre"*`	`body:("james w"*)`	Last term in phrase matched as prefix
Regex	`field:/pattern.*/`	`body:/comput.*/`	Match documents by regular expression on a field
Fuzzy	`term~` or `term~N`	`body:(compxter~1)`	Match terms within edit distance N (0–2) for typo tolerance
Cross-field	`fieldA:(…) OR fieldB:(…)`	`title:(quantum) OR body:(machine)`	Combine clauses across text-searchable fields

Terms and default OR behavior

A term is a single word. Multiple space-separated terms use OR logic by default.

body:(machine learning)

Matches documents containing “machine” OR “learning” (or both). Documents with both terms rank higher.

Phrases

Wrap multiple words in quotes to match them as an exact sequence.

body:("machine learning")

Matches only documents containing the exact phrase “machine learning” with the words adjacent. That’s different from type: "text" with query: "machine learning", which uses token OR matching on the field. For phrase matching as a filter (e.g., composed with dense-vector ranking), use {"body": {"$match_phrase": "machine learning"}} in the filter block. Phrase terms are matched against the field’s analyzed tokens. If stemming is enabled on the field, the phrase terms stem too, e.g., "running fast" matches running fast and runs fast.

Boolean operators (AND, OR, NOT)

Use AND, OR, and NOT for explicit boolean logic.

body:(machine AND learning)        # Both terms required (any order)
body:(machine OR learning)         # Either term (same as default)
body:(machine NOT learning)        # "machine" but not "learning"

AND binds tighter than OR, so use parentheses to control order:

body:((database OR storage) AND distributed)

Required and excluded terms (+, -)

Use + to require a term and - to exclude a term.

body:(+database distributed)       # MUST contain "database", "distributed" optional
body:(database -deprecated)        # Contains "database", must NOT contain "deprecated"
body:(+vector +search -legacy)     # MUST have "vector" AND "search", must NOT have "legacy"

Phrase proximity (slop)

Allow words in a phrase to appear within N positions of each other.

body:("machine learning"~3)

Matches “machine learning”, “machine deep learning”, or “machine-assisted learning” (words within 3 positions). The phrase terms are matched against analyzed tokens, so stemming (when enabled on the field) applies here too.

Boosting

Use ^N to multiply a clause’s contribution to the relevance score, where N is 0 or greater. The default is 1, so ^2 doubles the contribution and ^0.5 halves it. Scaling is linear.

body:(machine^3 learning)           # "machine" weighted 3x more than "learning"
body:(machine^0.5 learning)         # "machine" weighted half as much as "learning"
body:("neural network"^2 deep)      # Phrase boosted 2x
body:((machine OR neural)^2 deep)   # Whole group boosted 2x

Attach ^N directly to a term, a quoted phrase, or a parenthesized group. A space on either side of ^, as in body:(machine ^2 learning), is a query error (400).

N is a literal number, whole or decimal, with digits on both sides of the decimal point, such as 2, 1.5, or 0.75.
Values below 1 reduce the clause’s weight, and ^1 leaves scoring unchanged.
^0 drops the clause’s contribution to zero, though documents matching it are still returned. If every clause in the query is boosted to 0, all matches score 0 and their order isn’t meaningful.
Anything else is a query error (400): Arithmetic (^(2*3)), negatives (^-2), scientific notation (^1e3), a bare leading decimal point (^.5), and chained boosts (^2^3).

There’s no function- or field-based scoring, so weight by a stored field value or a formula in your application after the search returns. Boosting is available only with type: "query_string". With type: "text" and in the text-match filters, ^ is treated as a literal character.

Phrase prefix

Append * to a quoted phrase to treat the last term as a prefix. The phrase must contain at least two terms.

body:("james w"*)                  # Matches "james webb", "james watson", "james wilde"
body:("machine lea"*)              # Matches "machine learning", "machine learns"

A single-term prefix wildcard, such as auto*, isn’t supported. It returns no matches rather than an error. Use a phrase prefix instead, or configure the field for substring search. Both the literal terms and the prefix are matched against the field’s analyzed tokens. If stemming is enabled on the field, stemming applies to the completed terms in the phrase, while the final prefix is expanded against analyzed tokens. Phrase prefix is optimized for autocomplete-style queries where the final word prefix is reasonably specific. To keep latency low, Pinecone expands the final prefix to the first 50 matching terms in lexicographic order. For example, "new yor"* can match new york, but "new yo"* might not if york isn’t among the first 50 expanded terms for yo.

Regex

Wrap a pattern in forward slashes to match documents by regular expression on a field.

body:/comput.*/

Matches documents whose body field contains a token matching the regex comput.* (e.g., “computer”, “computing”, “computation”). Regex patterns are matched against individual analyzed tokens, not the raw field text.

body:/machin[ei].*/

Matches tokens like “machine” or “machene”. Standard Lucene regex syntax is supported. Regex is only available with type: "query_string". It’s not supported with type: "text".

Fuzzy matching (typo tolerance)

Append ~ to a bare term to match indexed terms within a small edit distance, so a misspelled query term still matches the intended word.

body:(compxter~1)                  # Matches "computer" (1 edit away)
body:(machine~ learning~)          # Auto distance per term, based on term length
title:(pinecone~2)                 # Explicit distance 2

term~ — automatic distance based on the term’s length: terms shorter than 4 characters must match exactly, terms of 4–7 characters allow 1 edit, and terms of 8 or more characters allow 2 edits.
term~N — fixed edit distance N, where N is 0, 1, or 2. ~0 is an exact match. A distance greater than 2 is a query error (400).

An “edit” is an inserted, deleted, or substituted character (plain Levenshtein distance). Swapping two adjacent characters counts as 2 edits. Matching is case-insensitive, as with all text queries. Fuzzy matches are scored as a constant; exact matches still contribute their full BM25 score, so an exact hit ranks above a fuzzy hit for the same term. Fuzzy composes with the rest of the query syntax, boolean operators, required/excluded terms, boosts, field qualifiers, and metadata filters.

The ~ operator is fuzzy only when it follows a bare term. After a quoted phrase, ~N keeps its phrase slop meaning, for example, body:("machine learning"~2) is slop, while body:(learning~2) is fuzzy. There is no fuzzy phrase matching.

On stemmed fields, fuzzy matching runs against the stemmed terms and is best-effort: a typo that changes how a word stems may not match. Fuzzy matching is most effective on fields without stemming (the default). Fuzzy is available only with type: "query_string". With type: "text", ~ is treated as a literal character. Fuzzy also doesn’t apply in the $match_phrase, $match_all, and $match_any text-match filters, where a ~ operator is matched literally and the filter finds nothing.

Cross-field queries

query_string can target multiple fields in the same expression. Use Lucene field qualifiers (field:(clause)) directly in the query string; omit them to run against all text-searchable fields:

title:(quantum) OR body:(machine learning)

Matches documents whose title contains “quantum”, documents whose body contains “machine” or “learning”, or both, with BM25 scoring combining across fields.

Get started

Core concepts

Index data

Search

Optimize

Manage data

Manage cost

Move to production

Admin

Operations

Using pods

Full-text search query syntax

Choosing a query type

Token matching (`type: "text"`)

Key behaviors

Lucene query syntax (`type: "query_string"`)

Terms and default OR behavior

Phrases

Boolean operators (AND, OR, NOT)

Required and excluded terms (+, -)

Phrase proximity (slop)

Boosting

Phrase prefix

Regex

Fuzzy matching (typo tolerance)

Cross-field queries

​Choosing a query type

​Token matching (type: "text")

​Key behaviors

​Lucene query syntax (type: "query_string")

​Terms and default OR behavior

​Phrases

​Boolean operators (AND, OR, NOT)

​Required and excluded terms (+, -)

​Phrase proximity (slop)

​Boosting

​Phrase prefix

​Regex

​Fuzzy matching (typo tolerance)

​Cross-field queries

Choosing a query type

Token matching (`type: "text"`)

Key behaviors

Lucene query syntax (`type: "query_string"`)

Terms and default OR behavior

Phrases

Boolean operators (AND, OR, NOT)

Required and excluded terms (+, -)

Phrase proximity (slop)

Boosting

Phrase prefix

Regex

Fuzzy matching (typo tolerance)

Cross-field queries