# pip install --upgrade pinecone
import os
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index = pc.Index(name="articles")
NAMESPACE = "example-namespace"
# BM25 token matching
response = index.documents.search(
namespace=NAMESPACE,
top_k=10,
score_by=[{"type": "text", "fields": ["body"], "query": "machine learning"}],
include_fields=["title", "body", "category", "year"],
)
for match in response.matches:
print(match._id, match._score, getattr(match, "title", ""))
# Lucene query string
response = index.documents.search(
namespace=NAMESPACE,
top_k=10,
score_by=[{"type": "query_string", "query": "title:(quantum) OR body:(machine learning)"}],
include_fields=["title", "body"],
)
# Dense vector ranking with phrase-match filter
query_vector = [0.12, 0.34, 0.56] # replace with your actual query vector
response = index.documents.search(
namespace=NAMESPACE,
top_k=10,
score_by=[{
"type": "dense_vector",
"fields": ["embedding"],
"values": query_vector,
}],
filter={"body": {"$match_phrase": "machine learning"}},
include_fields=["title", "body"],
)
// npm install @pinecone-database/pinecone
import { Pinecone } from '@pinecone-database/pinecone';
// Reads PINECONE_API_KEY from the environment
const pc = new Pinecone();
const index = pc.index({
name: 'articles',
namespace: 'example-namespace',
});
// BM25 token matching
let response = await index.documents.search({
topK: 10,
scoreBy: [
{
type: 'text',
fields: ['body'],
query: 'machine learning',
},
],
includeFields: ['title', 'body', 'category', 'year'],
});
for (const match of response.matches) {
console.log(match._id, match._score, match.title);
}
// Lucene query string
response = await index.documents.search({
topK: 10,
scoreBy: [
{
type: 'query_string',
query: 'title:(quantum) OR body:(machine learning)',
},
],
includeFields: ['title', 'body'],
});
// Dense vector ranking with phrase-match filter
const queryVector = [0.12, 0.34, 0.56]; // replace with your actual query vector
response = await index.documents.search({
topK: 10,
scoreBy: [
{
type: 'dense_vector',
fields: ['embedding'],
values: queryVector,
},
],
filter: {
body: {
$match_phrase: 'machine learning',
},
},
includeFields: ['title', 'body'],
});
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/pinecone-io/go-pinecone/v7/pinecone"
)
func main() {
ctx := context.Background()
pc, err := pinecone.NewClient(pinecone.NewClientParams{
ApiKey: os.Getenv("PINECONE_API_KEY"),
})
if err != nil {
log.Fatalf("Failed to create Client: %v", err)
}
idx, err := pc.DescribeIndex(ctx, "articles")
if err != nil {
log.Fatalf("Failed to describe index: %v", err)
}
idxConnection, err := pc.Index(pinecone.NewIndexConnParams{
Host: idx.Host,
Namespace: "example-namespace",
})
if err != nil {
log.Fatalf("Failed to create IndexConnection: %v", err)
}
// BM25 token matching
textQuery := "machine learning"
res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
TopK: 10,
ScoreBy: []pinecone.DocumentScoringMethod{
{
Type: "text",
Fields: []string{"body"},
Query: &textQuery,
},
},
IncludeFields: []string{"title", "body", "category", "year"},
})
if err != nil {
log.Fatalf("Failed to search documents: %v", err)
}
for _, match := range res.Matches {
fmt.Print(match.Id)
if match.Score != nil {
fmt.Printf(" %.3f", *match.Score)
}
fmt.Printf(" %v\n", match.Fields["title"])
}
// Lucene query string
queryString := "title:(quantum) OR body:(machine learning)"
res, err = idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
TopK: 10,
ScoreBy: []pinecone.DocumentScoringMethod{
{
Type: "query_string",
Query: &queryString,
},
},
IncludeFields: []string{"title", "body"},
})
if err != nil {
log.Fatalf("Failed to search documents: %v", err)
}
// Dense vector ranking with phrase-match filter
queryVector := []float32{0.12, 0.34, 0.56} // replace with your actual query vector
res, err = idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
TopK: 10,
ScoreBy: []pinecone.DocumentScoringMethod{
{
Type: "dense_vector",
Fields: []string{"embedding"},
Values: &queryVector,
},
},
Filter: map[string]interface{}{
"body": map[string]interface{}{
"$match_phrase": "machine learning",
},
},
IncludeFields: []string{"title", "body"},
})
if err != nil {
log.Fatalf("Failed to search documents: %v", err)
}
}
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io"
# EXAMPLE REQUEST 1: BM25 token matching (type: "text")
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body", "category", "year"],
"score_by": [{
"type": "text",
"fields": ["body"],
"query": "machine learning"
}],
"top_k": 10
}'
# EXAMPLE REQUEST 2: Cross-field boolean query (type: "query_string")
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body"],
"score_by": [{
"type": "query_string",
"query": "title:(quantum) OR body:(machine learning)"
}],
"top_k": 10
}'
# EXAMPLE REQUEST 3: Dense vector ranking with phrase-match filter
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body"],
"filter": { "body": { "$match_phrase": "machine learning" } },
"score_by": [{
"type": "dense_vector",
"fields": ["embedding"],
"values": [0.12, 0.34, 0.56]
}],
"top_k": 10
}'
# EXAMPLE REQUEST 4: Sparse vector ranking
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body"],
"score_by": [{
"type": "sparse_vector",
"fields": ["sparse_embedding"],
"sparse_values": {
"indices": [12, 287, 4096],
"values": [0.41, 0.33, 0.18]
}
}],
"top_k": 10
}'
# EXAMPLE REQUEST 5: Compound filter ($and + $match_all + metadata)
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["body", "category", "year"],
"filter": {
"$and": [
{ "body": { "$match_all": "federal reserve" } },
{ "category": { "$eq": "finance" } },
{ "year": { "$gte": 2024 } }
]
},
"score_by": [{
"type": "text",
"fields": ["body"],
"query": "monetary policy impact"
}],
"top_k": 10
}'
{
"matches": [
{
"_id": "doc-1",
"_score": 0.9281134605407715,
"title": "Introduction to Machine Learning"
}
],
"namespace": "my-namespace",
"usage": {
"egress_bytes": 1024,
"read_units": 5
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
},
"status": 400
}Unauthorized{
"error": {
"code": "INVALID_ARGUMENT",
"message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
},
"status": 400
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
},
"status": 400
}Documents
Search documents
Search for documents in a namespace using one or more scoring methods (dense vector, sparse vector, text, or query string similarity, or similarity to query text that Pinecone embeds with a field’s own model).
Returns the top-k most similar documents along with their scores and requested fields.
POST
/
namespaces
/
{namespace}
/
documents
/
search
# pip install --upgrade pinecone
import os
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index = pc.Index(name="articles")
NAMESPACE = "example-namespace"
# BM25 token matching
response = index.documents.search(
namespace=NAMESPACE,
top_k=10,
score_by=[{"type": "text", "fields": ["body"], "query": "machine learning"}],
include_fields=["title", "body", "category", "year"],
)
for match in response.matches:
print(match._id, match._score, getattr(match, "title", ""))
# Lucene query string
response = index.documents.search(
namespace=NAMESPACE,
top_k=10,
score_by=[{"type": "query_string", "query": "title:(quantum) OR body:(machine learning)"}],
include_fields=["title", "body"],
)
# Dense vector ranking with phrase-match filter
query_vector = [0.12, 0.34, 0.56] # replace with your actual query vector
response = index.documents.search(
namespace=NAMESPACE,
top_k=10,
score_by=[{
"type": "dense_vector",
"fields": ["embedding"],
"values": query_vector,
}],
filter={"body": {"$match_phrase": "machine learning"}},
include_fields=["title", "body"],
)
// npm install @pinecone-database/pinecone
import { Pinecone } from '@pinecone-database/pinecone';
// Reads PINECONE_API_KEY from the environment
const pc = new Pinecone();
const index = pc.index({
name: 'articles',
namespace: 'example-namespace',
});
// BM25 token matching
let response = await index.documents.search({
topK: 10,
scoreBy: [
{
type: 'text',
fields: ['body'],
query: 'machine learning',
},
],
includeFields: ['title', 'body', 'category', 'year'],
});
for (const match of response.matches) {
console.log(match._id, match._score, match.title);
}
// Lucene query string
response = await index.documents.search({
topK: 10,
scoreBy: [
{
type: 'query_string',
query: 'title:(quantum) OR body:(machine learning)',
},
],
includeFields: ['title', 'body'],
});
// Dense vector ranking with phrase-match filter
const queryVector = [0.12, 0.34, 0.56]; // replace with your actual query vector
response = await index.documents.search({
topK: 10,
scoreBy: [
{
type: 'dense_vector',
fields: ['embedding'],
values: queryVector,
},
],
filter: {
body: {
$match_phrase: 'machine learning',
},
},
includeFields: ['title', 'body'],
});
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/pinecone-io/go-pinecone/v7/pinecone"
)
func main() {
ctx := context.Background()
pc, err := pinecone.NewClient(pinecone.NewClientParams{
ApiKey: os.Getenv("PINECONE_API_KEY"),
})
if err != nil {
log.Fatalf("Failed to create Client: %v", err)
}
idx, err := pc.DescribeIndex(ctx, "articles")
if err != nil {
log.Fatalf("Failed to describe index: %v", err)
}
idxConnection, err := pc.Index(pinecone.NewIndexConnParams{
Host: idx.Host,
Namespace: "example-namespace",
})
if err != nil {
log.Fatalf("Failed to create IndexConnection: %v", err)
}
// BM25 token matching
textQuery := "machine learning"
res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
TopK: 10,
ScoreBy: []pinecone.DocumentScoringMethod{
{
Type: "text",
Fields: []string{"body"},
Query: &textQuery,
},
},
IncludeFields: []string{"title", "body", "category", "year"},
})
if err != nil {
log.Fatalf("Failed to search documents: %v", err)
}
for _, match := range res.Matches {
fmt.Print(match.Id)
if match.Score != nil {
fmt.Printf(" %.3f", *match.Score)
}
fmt.Printf(" %v\n", match.Fields["title"])
}
// Lucene query string
queryString := "title:(quantum) OR body:(machine learning)"
res, err = idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
TopK: 10,
ScoreBy: []pinecone.DocumentScoringMethod{
{
Type: "query_string",
Query: &queryString,
},
},
IncludeFields: []string{"title", "body"},
})
if err != nil {
log.Fatalf("Failed to search documents: %v", err)
}
// Dense vector ranking with phrase-match filter
queryVector := []float32{0.12, 0.34, 0.56} // replace with your actual query vector
res, err = idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
TopK: 10,
ScoreBy: []pinecone.DocumentScoringMethod{
{
Type: "dense_vector",
Fields: []string{"embedding"},
Values: &queryVector,
},
},
Filter: map[string]interface{}{
"body": map[string]interface{}{
"$match_phrase": "machine learning",
},
},
IncludeFields: []string{"title", "body"},
})
if err != nil {
log.Fatalf("Failed to search documents: %v", err)
}
}
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io"
# EXAMPLE REQUEST 1: BM25 token matching (type: "text")
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body", "category", "year"],
"score_by": [{
"type": "text",
"fields": ["body"],
"query": "machine learning"
}],
"top_k": 10
}'
# EXAMPLE REQUEST 2: Cross-field boolean query (type: "query_string")
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body"],
"score_by": [{
"type": "query_string",
"query": "title:(quantum) OR body:(machine learning)"
}],
"top_k": 10
}'
# EXAMPLE REQUEST 3: Dense vector ranking with phrase-match filter
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body"],
"filter": { "body": { "$match_phrase": "machine learning" } },
"score_by": [{
"type": "dense_vector",
"fields": ["embedding"],
"values": [0.12, 0.34, 0.56]
}],
"top_k": 10
}'
# EXAMPLE REQUEST 4: Sparse vector ranking
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body"],
"score_by": [{
"type": "sparse_vector",
"fields": ["sparse_embedding"],
"sparse_values": {
"indices": [12, 287, 4096],
"values": [0.41, 0.33, 0.18]
}
}],
"top_k": 10
}'
# EXAMPLE REQUEST 5: Compound filter ($and + $match_all + metadata)
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["body", "category", "year"],
"filter": {
"$and": [
{ "body": { "$match_all": "federal reserve" } },
{ "category": { "$eq": "finance" } },
{ "year": { "$gte": 2024 } }
]
},
"score_by": [{
"type": "text",
"fields": ["body"],
"query": "monetary policy impact"
}],
"top_k": 10
}'
{
"matches": [
{
"_id": "doc-1",
"_score": 0.9281134605407715,
"title": "Introduction to Machine Learning"
}
],
"namespace": "my-namespace",
"usage": {
"egress_bytes": 1024,
"read_units": 5
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
},
"status": 400
}Unauthorized{
"error": {
"code": "INVALID_ARGUMENT",
"message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
},
"status": 400
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
},
"status": 400
}Filters apply before scoring, so only documents that match the
filter are ranked. For how each scoring type works and how to combine them, see Full-text search and the query syntax reference.
# pip install --upgrade pinecone
import os
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index = pc.Index(name="articles")
NAMESPACE = "example-namespace"
# BM25 token matching
response = index.documents.search(
namespace=NAMESPACE,
top_k=10,
score_by=[{"type": "text", "fields": ["body"], "query": "machine learning"}],
include_fields=["title", "body", "category", "year"],
)
for match in response.matches:
print(match._id, match._score, getattr(match, "title", ""))
# Lucene query string
response = index.documents.search(
namespace=NAMESPACE,
top_k=10,
score_by=[{"type": "query_string", "query": "title:(quantum) OR body:(machine learning)"}],
include_fields=["title", "body"],
)
# Dense vector ranking with phrase-match filter
query_vector = [0.12, 0.34, 0.56] # replace with your actual query vector
response = index.documents.search(
namespace=NAMESPACE,
top_k=10,
score_by=[{
"type": "dense_vector",
"fields": ["embedding"],
"values": query_vector,
}],
filter={"body": {"$match_phrase": "machine learning"}},
include_fields=["title", "body"],
)
// npm install @pinecone-database/pinecone
import { Pinecone } from '@pinecone-database/pinecone';
// Reads PINECONE_API_KEY from the environment
const pc = new Pinecone();
const index = pc.index({
name: 'articles',
namespace: 'example-namespace',
});
// BM25 token matching
let response = await index.documents.search({
topK: 10,
scoreBy: [
{
type: 'text',
fields: ['body'],
query: 'machine learning',
},
],
includeFields: ['title', 'body', 'category', 'year'],
});
for (const match of response.matches) {
console.log(match._id, match._score, match.title);
}
// Lucene query string
response = await index.documents.search({
topK: 10,
scoreBy: [
{
type: 'query_string',
query: 'title:(quantum) OR body:(machine learning)',
},
],
includeFields: ['title', 'body'],
});
// Dense vector ranking with phrase-match filter
const queryVector = [0.12, 0.34, 0.56]; // replace with your actual query vector
response = await index.documents.search({
topK: 10,
scoreBy: [
{
type: 'dense_vector',
fields: ['embedding'],
values: queryVector,
},
],
filter: {
body: {
$match_phrase: 'machine learning',
},
},
includeFields: ['title', 'body'],
});
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/pinecone-io/go-pinecone/v7/pinecone"
)
func main() {
ctx := context.Background()
pc, err := pinecone.NewClient(pinecone.NewClientParams{
ApiKey: os.Getenv("PINECONE_API_KEY"),
})
if err != nil {
log.Fatalf("Failed to create Client: %v", err)
}
idx, err := pc.DescribeIndex(ctx, "articles")
if err != nil {
log.Fatalf("Failed to describe index: %v", err)
}
idxConnection, err := pc.Index(pinecone.NewIndexConnParams{
Host: idx.Host,
Namespace: "example-namespace",
})
if err != nil {
log.Fatalf("Failed to create IndexConnection: %v", err)
}
// BM25 token matching
textQuery := "machine learning"
res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
TopK: 10,
ScoreBy: []pinecone.DocumentScoringMethod{
{
Type: "text",
Fields: []string{"body"},
Query: &textQuery,
},
},
IncludeFields: []string{"title", "body", "category", "year"},
})
if err != nil {
log.Fatalf("Failed to search documents: %v", err)
}
for _, match := range res.Matches {
fmt.Print(match.Id)
if match.Score != nil {
fmt.Printf(" %.3f", *match.Score)
}
fmt.Printf(" %v\n", match.Fields["title"])
}
// Lucene query string
queryString := "title:(quantum) OR body:(machine learning)"
res, err = idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
TopK: 10,
ScoreBy: []pinecone.DocumentScoringMethod{
{
Type: "query_string",
Query: &queryString,
},
},
IncludeFields: []string{"title", "body"},
})
if err != nil {
log.Fatalf("Failed to search documents: %v", err)
}
// Dense vector ranking with phrase-match filter
queryVector := []float32{0.12, 0.34, 0.56} // replace with your actual query vector
res, err = idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
TopK: 10,
ScoreBy: []pinecone.DocumentScoringMethod{
{
Type: "dense_vector",
Fields: []string{"embedding"},
Values: &queryVector,
},
},
Filter: map[string]interface{}{
"body": map[string]interface{}{
"$match_phrase": "machine learning",
},
},
IncludeFields: []string{"title", "body"},
})
if err != nil {
log.Fatalf("Failed to search documents: %v", err)
}
}
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io"
# EXAMPLE REQUEST 1: BM25 token matching (type: "text")
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body", "category", "year"],
"score_by": [{
"type": "text",
"fields": ["body"],
"query": "machine learning"
}],
"top_k": 10
}'
# EXAMPLE REQUEST 2: Cross-field boolean query (type: "query_string")
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body"],
"score_by": [{
"type": "query_string",
"query": "title:(quantum) OR body:(machine learning)"
}],
"top_k": 10
}'
# EXAMPLE REQUEST 3: Dense vector ranking with phrase-match filter
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body"],
"filter": { "body": { "$match_phrase": "machine learning" } },
"score_by": [{
"type": "dense_vector",
"fields": ["embedding"],
"values": [0.12, 0.34, 0.56]
}],
"top_k": 10
}'
# EXAMPLE REQUEST 4: Sparse vector ranking
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body"],
"score_by": [{
"type": "sparse_vector",
"fields": ["sparse_embedding"],
"sparse_values": {
"indices": [12, 287, 4096],
"values": [0.41, 0.33, 0.18]
}
}],
"top_k": 10
}'
# EXAMPLE REQUEST 5: Compound filter ($and + $match_all + metadata)
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["body", "category", "year"],
"filter": {
"$and": [
{ "body": { "$match_all": "federal reserve" } },
{ "category": { "$eq": "finance" } },
{ "year": { "$gte": 2024 } }
]
},
"score_by": [{
"type": "text",
"fields": ["body"],
"query": "monetary policy impact"
}],
"top_k": 10
}'
Authorizations
Headers
Required date-based version header
Path Parameters
The namespace to search.
Body
application/json
The request for the search_documents operation.
score_by
(Dense vector · object | Sparse vector · object | Text · object | Query string · object | Embed · object | Sparse embed · object)[]
required
The scoring clauses used to rank documents.
One clause of any type is always valid. Several clauses can be combined only when every clause is text or query_string, and the server combines them into one ranking. A dense_vector, sparse_vector, embed, or sparse_embed clause must be the only clause.
Required array length:
1 - 100 elementsA scoring clause that defines how documents are scored against a query. type selects the scoring method and which other fields the clause takes.
- Dense vector
- Sparse vector
- Text
- Query string
- Embed
- Sparse embed
Show child attributes
Show child attributes
The number of top-ranked documents to return.
Required range:
1 <= x <= 10000Example:
10
The document fields to return on each match alongside _id and _score. When omitted or empty, no fields are returned. Pass ["*"] to return every field. A name the schema doesn't declare is read as a metadata key, and returns nothing for documents without that key.
Naming a field whose schema sets store_text: false is rejected with 400, since its text is not stored; ["*"] leaves such fields out.
Example:
["title", "content"]
A metadata filter expression to restrict the documents searched.
Response
A successful search response.
The response for the search_documents operation.
The matching documents, ordered from most to least similar.
Show child attributes
Show child attributes
The namespace that served the search: the request's namespace, or the alias's target namespace when the request named a namespace alias.
Example:
"my-namespace"
Usage information for the search_documents operation.
Show child attributes
Show child attributes
Example:
{ "egress_bytes": 1024, "read_units": 5 }
Was this page helpful?