feat: add TextQuery and VectorQuery classes

[jhamon]

Summary

Add query model classes for the document search API.

Closes SDK-108

Classes

Class	Purpose	Key Parameters
TextQuery	Full-text search	field, query, boost, slop
VectorQuery	Vector similarity search	field, values, sparse_values

Both classes:

• Support dict-like access (query["field"])
• Serialize to API format via to_dict()
• Can be used as score_by parameter in search_documents()

Usage Example

from pinecone import TextQuery, VectorQuery

# Text query for full-text search
results = index.search_documents(
    namespace="movies",
    score_by=TextQuery(field="title", query='return "pink panther"'),
    top_k=10,
)

# Vector query for similarity search
results = index.search_documents(
    namespace="movies",
    score_by=VectorQuery(field="embedding", values=[0.1, 0.2, 0.3, ...]),
    top_k=10,
)

Test Plan

• Unit tests for TextQuery serialization (7 tests)
• Unit tests for VectorQuery serialization (7 tests)
• Tests for dict-like access
• Tests for optional parameters
• mypy type checking passes

---

Note

Low Risk
Low risk: adds new lightweight dataclass helpers and exports plus unit tests, without changing existing request/response handling or core search logic.

Overview
Adds new TextQuery and VectorQuery dataclasses to represent search_documents() score_by inputs, including optional parameters and to_dict() serialization (and DictLike access via the existing base).

Exports these types via pinecone.db_data.dataclasses and top-level lazy imports in pinecone/__init__.py, and adds unit tests validating serialization and dict-like behavior.

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

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

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

[cursor]

TextQuery.to_dict() uses wrong API field name

High Severity

The to_dict() method serializes the query string with key "query", but the Pinecone API expects "text_query" as shown in the OpenAPI-generated model at pinecone/core/openapi/db_data/model/text_query.py. This mismatch will cause API requests using TextQuery as the score_by parameter to fail or produce unexpected results because the server won't recognize the query text.

 

[cursor]

TextQuery.to_dict() missing required type discriminator field

High Severity

The to_dict() methods in TextQuery and VectorQuery omit the required type discriminator field. The Pinecone API uses this field (e.g., 'text', 'vector') to correctly identify the query type within the score_by parameter, so its absence prevents proper API interpretation.

Additional Locations (1)

• pinecone/db_data/dataclasses/vector_query.py#L47-L58

 

[cursor]

Inconsistent method naming with similar query classes

Low Severity

The new TextQuery and VectorQuery classes use to_dict() for serialization, while semantically similar query classes in the same module (SearchQuery, SearchQueryVector, SearchRerank) all use as_dict(). This naming inconsistency within the query-related classes could confuse developers expecting a uniform API.

Additional Locations (1)

• pinecone/db_data/dataclasses/vector_query.py#L47-L48