feat(fts): implement search_documents() method for document-centric search

[jhamon]

Summary

Implements the search_documents() method for both Index and IndexAsyncio classes to enable document-centric search using the Full-Text Search (FTS) alpha API.

• Adds search_documents() method that accepts TextQuery or VectorQuery for flexible scoring
• Supports metadata filtering including the new $text_match operator for FTS filtering
• Returns typed DocumentSearchResponse with easy-to-use Document objects
• Includes both sync and async implementations

Usage Examples

Text Search

from pinecone import Pinecone, text_query

pc = Pinecone()
index = pc.Index(host="example-index-host")

# Simple text search
results = index.search_documents(
    namespace="movies",
    score_by=text_query("title", 'return "pink panther"'),
    filter={"genre": {"$eq": "comedy"}},
    top_k=10,
)

# Access results
for doc in results.documents:
    print(f"{doc.id}: {doc.score}")
    print(f"Title: {doc.title}")

Vector Search with FTS Filter

from pinecone import Pinecone, vector_query

results = index.search_documents(
    namespace="logs",
    score_by=vector_query("embedding", values=[0.1, 0.2, 0.3]),
    filter={
        "service": {"$eq": "payment-gateway"},
        "message": {"$text_match": '+error +"connection refused"'},
    },
    include_fields=["message", "timestamp"],
    top_k=10,
)

Async Usage

import asyncio
from pinecone import Pinecone, text_query

async def main():
    pc = Pinecone()
    async with pc.IndexAsyncio(host="example-host") as index:
        results = await index.search_documents(
            namespace="movies",
            score_by=text_query("title", "pink panther"),
            top_k=10,
        )
        for doc in results.documents:
            print(doc.id, doc.score)

asyncio.run(main())

Test Plan

• Unit tests for request factory
• Unit tests for Document and DocumentSearchResponse classes
• Unit tests for various query types (text, vector, sparse)
• Unit tests for filter and include_fields parameters
• Integration tests (covered by SDK-114)

Related

• Linear: SDK-111
• Depends on: Document response models (PR12)

---

Note

Medium Risk
Introduces new request/response shaping around an alpha OpenAPI endpoint; main risk is mismatches with evolving API response fields or filters leading to runtime issues.

Overview
Enables document-centric search by adding search_documents() to Index, IndexAsyncio, and IndexInterface, backed by the OpenAPI DocumentOperationsApi/AsyncioDocumentOperationsApi.

Adds IndexRequestFactory.search_documents_request() to build DocumentSearchRequest from TextQuery/VectorQuery, with support for optional metadata filter (including $text_match) and include_fields (special-casing ['*'] to "*"). Results are normalized into a DocumentSearchResponse containing Document objects plus usage/_response_info.

Includes new unit tests covering request construction for text/vector/sparse queries, filters, include_fields handling, and Document/DocumentSearchResponse behaviors.

^{Written by Cursor Bugbot for commit 600106a. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}