Querying

A single documents.search request ranks by one scoring type. score_by accepts a list, but every entry must share a type:

• Multiple text clauses (one per field) — that’s how multi-field BM25 works.
• A single query_string clause (which can target multiple fields via fields: [...] or inline field:term syntax inside the Lucene expression).
• dense_vector clauses must appear alone.
• sparse_vector clauses must appear alone.
• You cannot blend types — no text + query_string, no text + dense_vector, no cross-type mix. The server rejects it.

To compose lexical and dense / sparse signals, put the lexical signal in filter via the text-match operators ($match_phrase / $match_all / $match_any) and let the vector clause in score_by do the ranking. That’s the supported hybrid pattern in 2026-07.

score_by signal types

1. text — BM25 token-OR on a single text field

Tokenizes query with the field’s analyzer, scores each matching document with a BM25 ranker over the inverted index, returns the top top_k. Multiple terms use OR semantics — documents matching any token participate, those matching more / rarer tokens score higher. Phrase constraints (adjacent words in order) are not supported here — use query_string with quotes, or a $match_phrase filter, for phrase semantics.

field is a single string (singular) naming an FTS-enabled string field — text clauses are scoped to one field at a time. For multi-field BM25, pass several text clauses (one per field) or use a query_string clause with a fields array (see Multi-field BM25 below).

2. query_string — Lucene syntax (boolean / phrase / boost / slop / prefix / cross-field)

Supported operators (full table in the public docs, summarized here):

Fuzzy (~N, edit distance 0-2; bare ~ picks a distance from term length) and regex (/…/, matched against analyzed tokens, not raw field text) are query_string-only — the ~ and /…/ syntax is treated as literal text under type: "text". Fuzzy matching is best-effort on stemmed fields, since a typo can shift which stem a term normalizes to; it’s most reliable on fields without stemming.

Cross-field clauses are unique to query_string — they let one expression target multiple text-searchable fields with their own sub-clauses. Optionally pass a top-level fields array on the clause to restrict scope; omitted, the query runs against every text-searchable field in the schema.

Single-term prefix wildcards (auto*) are not supported. Use phrase prefix instead: "machine lea"* (phrase must contain at least two terms; only the last is matched as prefix).

3. dense_vector — score against a stored dense vector

field is a single string (singular) naming a dense_vector field. values is a list[float] matching the field’s declared dimension. Typically produced by embedding the user’s query through the same (or a compatible) model at runtime. For text embedders with a passage/query distinction (e.g. multilingual-e5-large), use input_type="query" on the query side. Must appear alone in score_by.

4. sparse_vector — score against a stored sparse vector

Stored and queried as {"indices": [...], "values": [...]}. Hosted sparse models (e.g. pinecone-sparse-english-v0) return embeddings with .sparse_indices and .sparse_values ready to drop in. Must appear alone in score_by. The sparse_vector field this scores against must have been declared explicitly at schema-creation time — see references/schema-design.md.

Multi-field BM25

Two equivalent ways to score across multiple text fields in one request:

Option A — multiple text clauses (one per field):

Option B — one query_string cross-field expression:

Both reward documents that match in multiple fields. 2026-07 weights every contributing field equally — there is no per-clause weight parameter. To approximate weighting, use Option B with ^N term boosts inside the query string (title:({q})^3 OR body:({q})).

Filtering

Filters run before scoring — they shrink the candidate set, then the chosen score_by ranks survivors. Two families of operators.

Text-match filters (on text-searchable fields)

These operate on full_text_search-enabled fields and reuse the field’s tokenizer / stemmer. Each value is a single string (max 128 tokens). Not available inside query_string — they live in filter.

These are the supported way to compose lexical pre-filtering with dense_vector (or sparse_vector) scoring — see “Cross-modal hybrid” below.

Scoring-only operators don’t go in filter. Phrase slop ("…"~N), term boost (^N), and phrase prefix ("… word"*) influence ranking, so they’re available in query_string score_by but not in filter.

Metadata filters (on filterable fields)

Standard comparison and membership operators. On a managed index, none of string, string_list, float, or boolean metadata fields are declared in the schema — any field present on an upserted document is auto-indexed for filtering regardless of type (see references/schema-design.md → “Filterable metadata — never schema-declared on managed indexes”).

Composing with $and / $or / $not

Multiple keys at the top level of a filter object are implicitly AND-ed. Use $and, $or, $not for explicit / nested composition. Text-match and metadata filters compose freely:

Cross-modal hybrid: dense ranking + text-match filter

The supported way to compose lexical and dense signals in one request: dense (or sparse) score_by, plus a text-match filter that hard-restricts the candidate set to documents whose lexical field contains the right tokens / phrase.

Read it top-down: only docs whose body contains the exact phrase "beautifully written", ranked by dense-vector similarity to the embedding of “a moving family epic.” One round trip, server-side hard filter, dense rerank.

When to use which text-match operator inside a hybrid query:

include_fields modes

include_fields controls what each match object carries back in the response.

Always pass include_fields explicitly on documents.search. Being explicit avoids surprises and makes the call’s intent obvious.

User metadata fields literally named score are returned alongside the system-owned _score match score — the leading underscore prevents collisions.

Reading match objects

Match objects carry:

• _id (string) — document ID.
• _score (float) — system match score; higher is better.
• The fields requested via include_fields.

The score field name is reserved for user metadata; the system match score is always _score. Read m._score, not m.score.

documents.fetch — direct retrieval by ID or filter

documents.fetch accepts exactly one of ids or filter:

Missing IDs are silently omitted from the response (no error). ids accepts 1–1000 entries per call.

A filter-based fetch is paginated — up to 10,000 documents per page:

An ID-based fetch never sets response.pagination (always None), so existing single-page fetch(ids=...) call sites need no loop.

documents.delete — by ID, filter, or delete_all

Exactly one of ids, filter, or delete_all must be given. documents.delete returns a DeleteDocumentsResponse (it used to return None). matched_records is populated only for a filtered delete — it’s a point-in-time count when the server accepted the request, not a promise about how many documents ultimately disappear (deletes apply asynchronously). It’s None for an ID-list or delete_all delete. Deletes are permanent within the namespace.

documents.list — enumerate document IDs

New in the graduated API — no equivalent existed under pinecone.preview. Lazily paginated, sorted by _id, and returns IDs only (no other fields):

namespace is required. limit (1–100) tunes page size only — the default iterator form above still walks every page; use .pages() (or itertools.islice) if you want to stop early. prefix is ASCII-only, ≤512 characters. There’s no filter — for anything beyond an ID prefix, use documents.search or documents.fetch(filter=...) instead, both of which return actual field data.

Useful for confirming what’s in a namespace before a delete_all, or auditing chunk coverage for a parent document by prefix.

Worked cross-modal example — “pick your signal” pattern

One index with two FTS text fields and one multimodal dense vector field. The dense field holds an embedding that lives in a shared text/image space (e.g. a Gemini multimodal embedding of each document’s representative image). Because text and image share the space, a typed description can be embedded as text and scored against the stored image vectors.

Schema

Three query modes against the same index

1. Pure text — multi-field BM25 token-OR.

2. Exact phrase via query_string.

3. Pure dense — semantic query against stored vectors.

4. Hybrid — $match_all filter narrows; dense ranks.

The same index supports all four modes; which one you want depends on whether the user’s intent is keyword-driven (Mode 1), phrase-driven (Mode 2), appearance-driven (Mode 3), or “constrain by keyword, rank by appearance” (Mode 4). That’s the pick-your-signal pattern — build the index once, vary the query shape per user intent.