The QueryDescriptor class provides a fluent interface for building and configuring vector search queries. It allows you to combine vector-based similarity search with traditional filtering, specify result formatting, and execute searches against your indexed data.

​
Constructor

QueryDescriptor(index, schema, clauses=None, query_user_config=None)

​
Parameters

​
index
Index
required
The vector index to query against.
​
schema
IdSchemaObject
required
The schema object that defines the data structure being queried.
​
clauses
Sequence[QueryClause] | None
default:"None"
Optional list of query clauses that define the search criteria.
​
query_user_config
QueryUserConfig | None
default:"None"
Optional user configuration for query execution behavior.

​
Properties

​
clauses
Sequence[QueryClause]
required
The collection of query clauses that define the search criteria.
​
index
Index
required
The vector index being queried.
​
query_user_config
QueryUserConfig
required
User configuration settings for the query.
​
schema
IdSchemaObject
required
The schema object for the data being queried.
​
with_metadata
bool
required
Whether to include metadata in the query results.

​
Core Query Methods

​
similar()

Add a similarity clause to find items similar to a given input. 
similar(space_field_set, param, weight=1.0) -> QueryDescriptor
​
space_field_set
HasSpaceFieldSet | SpaceFieldSet
required
The space or field set to search within.
​
param
ParamType
required
The query parameter - can be a fixed value or a Param placeholder for later substitution.
​
weight
float | int | Param
default:"1.0"
The weight to apply to this similarity clause.
Returns: QueryDescriptor - The query object for method chaining. Raises:
  • InvalidInputException - If the space is already bound in the query
  • InvalidInputException - If the schema is not in the similarity field’s schema types

​
with_vector()

Add a clause to use an existing stored vector for similarity search. 
with_vector(schema_obj, id_param, weight=1.0) -> QueryDescriptor
​
schema_obj
IdSchemaObject
required
The schema object the vector originates from.
​
id_param
str | Param
required
The ID parameter - the ID of the vector to use in the query.
​
weight
float | int | Param | Mapping[Space, float | int | Param]
default:"1.0"
Weight for the retrieved vector. Can be fine-tuned with space-wise weighting.
Returns: QueryDescriptor - The query object for method chaining.

​
Filtering Methods

​
filter()

Add filtering criteria to limit results based on field values. 
filter(comparison_operation) -> QueryDescriptor
​
comparison_operation
ComparisonOperation[SchemaField] | _Or[SchemaField]
required
The comparison operation defining the filter criteria.
Returns: QueryDescriptor - The query object for method chaining.

​
Filter Examples

The original documentation shows these filter patterns:
  • filter(color_schema.color == "blue")
  • filter(color_schema.color == Param("color_param"))
  • filter(color_schema.color != "red")
  • filter(color_schema.rating > 3)
  • filter(color_schema.rating >= 3)
  • filter(color_schema.rating < 3)
  • filter(color_schema.rating <= 3)
  • filter((color_schema.color == "blue") | (color_schema.color == "red"))
  • filter(color_schema.categories.contains(["bright", "matte"])) - returns both bright and matte colors
  • filter(color_schema.categories.not_contains(["bright", "matte"])) - returns colors that are non-bright and non-matte
  • filter(color_schema.categories.contains_all(["bright", "blue"])) - returns colors that are bright and blue at the same time

​
Result Configuration Methods

​
limit()

Set the maximum number of results to return. 
limit(limit) -> QueryDescriptor
​
limit
int | Param | None
required
The maximum number of results. If None, -1 will be used (not handled by all databases).
Returns: QueryDescriptor - The query object for method chaining.

​
radius()

Set a radius for the search to limit results by distance. 
radius(radius) -> QueryDescriptor
​
radius
float | int | Param | None
required
The maximum distance from the query vector. Valid range is 0-1. A radius of 0.05 means minimum cosine similarity of 0.95.
Returns: QueryDescriptor - The query object for method chaining. Raises: InvalidInputException - If the radius is not between 0 and 1.

​
select()

Select specific fields to return in the results. 
select(fields=None, metadata=None) -> QueryDescriptor
​
fields
SchemaField | str | Param | Sequence[SchemaField | str | Param] | None
default:"None"
The fields to select. Can be SchemaField objects, field names as strings, or Param objects.
​
metadata
Sequence[Space] | None
default:"None"
The spaces identifying the requested vector parts.
Returns: QueryDescriptor - The query object for method chaining. Raises:
  • InvalidInputException - If multiple Param objects are provided or Param is mixed with other field types
  • TypeException - If any fields are of unsupported types
  • FieldException - If any schema fields are not part of the schema
  • InvalidInputException - If any spaces in metadata is not a Space

​
select_all()

Select all fields from the schema to be returned. 
select_all(metadata=None) -> QueryDescriptor
​
metadata
Sequence[Space] | None
default:"None"
The spaces identifying the requested vector parts.
Returns: QueryDescriptor - The query object for method chaining.

​
Metadata and Configuration

​
include_metadata()

Include per-item metadata in query results. 
include_metadata() -> QueryDescriptor
Current metadata includes space-wise partial scores. Returns: QueryDescriptor - The query object for method chaining.

​
space_weights()

Set custom weights for different vector spaces. 
space_weights(weight_by_space) -> QueryDescriptor
​
weight_by_space
Mapping[Space, float | int | Param]
required
Mapping of spaces to their weights.
Returns: QueryDescriptor - The query object for method chaining.

​
Natural Language Query Support

​
with_natural_query()

Enable natural language query processing to automatically fill parameter values. 
with_natural_query(natural_query, client_config, system_prompt=None) -> QueryDescriptor
​
natural_query
str | Param
required
Query containing desired characteristics in natural language.
​
client_config
OpenAIClientConfig
required
Client configuration to initialize the OpenAI client.
​
system_prompt
str | Param | None
default:"None"
Custom system prompt to use for the query.
Returns: QueryDescriptor - The query object for method chaining.

​
nlq_suggestions()

Get suggestions for improving natural language query parameters. 
nlq_suggestions(feedback=None) -> QuerySuggestionsModel
​
feedback
str | None
default:"None"
Additional feedback to help generate more targeted suggestions.
Returns: QuerySuggestionsModel - Model containing improvement suggestions and clarifying questions. The original documentation shows this example usage: 
suggestions = query.nlq_suggestions()
suggestions.print()  # Prints formatted suggestions
# Or access directly:
print(suggestions.improvement_suggestions)
print(suggestions.clarifying_questions)
Raises: InvalidInputException - If with_natural_query() has not been called before this method.

​
Advanced Configuration

​
override_now()

Override the current timestamp for time-based queries. 
override_now(now) -> QueryDescriptor
​
now
int | Param
required
The timestamp to use as “now” for time-based calculations.
Returns: QueryDescriptor - The query object for method chaining.

​
replace_user_config()

Replace the current query user configuration. 
replace_user_config(query_user_config) -> QueryDescriptor
​
query_user_config
QueryUserConfig
required
The new configuration to use for this query.
Returns: QueryDescriptor - A new query descriptor with the updated configuration.

​
Utility Methods

​
get_clause_by_type()

Get a specific clause by its type. 
get_clause_by_type(clause_type) -> QueryClauseT | None

​
get_clauses_by_type()

Get all clauses of a specific type. 
get_clauses_by_type(clause_type) -> list[QueryClauseT]

​
append_missing_mandatory_clauses()

Add any missing mandatory clauses to the query. 
append_missing_mandatory_clauses() -> QueryDescriptor

​
replace_clauses()

Replace the current clauses with a new set. 
replace_clauses(clauses) -> QueryDescriptor

​
QueryDescriptorValidator

Validation utility for query descriptors. 
QueryDescriptorValidator()

​
Static Methods

​
validate()

Validate a query descriptor for correctness. 
@staticmethod
validate(query_descriptor: QueryDescriptor) -> None

​
Method Chaining

QueryDescriptor supports fluent interface patterns for building complex queries through method chaining. Each method returns the QueryDescriptor instance, allowing you to chain multiple operations together.