Query
Query Results
Data structures for handling search results, including entries, metadata, and scoring information
The query result system provides structured data models for representing search results returned from vector queries. These Pydantic-based models ensure type safety and consistent result formatting.
QueryResult
The main container for query results, holding a collection of result entries and associated metadata.Properties
A sequence of result entries, each representing a matching item from the search with its associated data and scoring information.
Global metadata about the query execution, including search parameters and execution context.
Pydantic model configuration for validation and serialization behavior.
ResultEntry
Individual result item containing the matched data and associated metadata.Properties
The unique identifier of the matched item from the original data source.
Dictionary containing the actual field values from the matched item, as selected in the query.
Detailed metadata about this specific result entry, including scoring and vector information.
Pydantic model configuration for this entry.
ResultEntryMetadata
Detailed scoring and vector information for individual result entries.Properties
The overall similarity score for this result entry, representing how well it matches the query criteria.
Individual similarity scores from each vector space that contributed to the final score, allowing for detailed analysis of match quality.
The actual vector representations from each space for this result entry, useful for debugging and analysis.
Pydantic model configuration for metadata handling.
ResultMetadata
Global information about the query execution and search context.Properties
The name of the schema that was queried, if available.
The parameters that were used during the search execution, including any resolved parameter values.
The final search vector that was used for similarity comparison, after all transformations and weightings.
Pydantic model configuration for result metadata.
Inheritance
All result classes inherit from Pydantic’s BaseModel through ImmutableBaseModel: Inheritance Chain:QueryResult/ResultEntry/ResultEntryMetadata/ResultMetadata- →
ImmutableBaseModel - →
BaseModel
- Type Validation: Automatic validation of field types and values
- Serialization: JSON serialization/deserialization support
- Immutability: Result objects cannot be modified after creation
- Documentation: Automatic API documentation generation
Model Features
Validation
All models include comprehensive validation:- Field type checking
- Required field enforcement
- Custom validation rules
- Nested model validation
Serialization
Built-in support for:- JSON export/import
- Dictionary conversion
- Custom serialization rules
- Field filtering and selection
Immutability
Result objects are immutable to ensure:- Data consistency across application layers
- Thread safety for concurrent access
- Prevention of accidental modifications
- Reliable caching and memoization
Best Practices
Score Interpretation: Similarity scores are typically between 0 and 1, with higher values indicating better matches. Use partial_scores to understand how different vector spaces contributed to the final score.
Metadata Usage: Use the metadata information for debugging query performance, understanding result ranking, and implementing result explain-ability features.
Large Results: For queries returning many results, consider the memory impact of storing full vector information in metadata. Use selective field loading when appropriate.