Class Query

python/zvec/model/param/query.py:43–130

Represents a search query for a specific field in a collection. A `Query` can be constructed for either vector search or full-text search, but not both simultaneously. For vector search, provide `id` or `vector` (and optionally `param`). For FTS, provide `fts`. Attributes:

@dataclass(frozen=True)
class Query:
    """Represents a search query for a specific field in a collection.

    A `Query` can be constructed for either vector search or full-text search,
    but not both simultaneously.

    For vector search, provide `id` or `vector` (and optionally `param`).
    For FTS, provide `fts`.

    Attributes:
        field_name (str): Name of the field to query.
        id (Optional[str], optional): Document ID to fetch vector from. Default is None.
        vector (VectorType, optional): Explicit query vector. Default is None.
        param (Optional[Union[HnswQueryParam, HnswRabitqQueryParam, IVFQueryParam, FtsQueryParam]], optional):
            Index-specific query parameters. Default is None.
        fts (Optional[Fts], optional): Full-text search parameters. Default is None.

    Examples:
        >>> import zvec
        >>> # Query by ID
        >>> q1 = zvec.Query(field_name="embedding", id="doc123")
        >>> # Query by vector
        >>> q2 = zvec.Query(
        ...     field_name="embedding",
        ...     vector=[0.1, 0.2, 0.3],
        ...     param=HnswQueryParam(ef=300)
        ... )
        >>> # FTS query
        >>> q3 = zvec.Query(
        ...     field_name="content",
        ...     fts=Fts(match_string="machine learning")
        ... )
        >>> # FTS query with custom operator
        >>> q4 = zvec.Query(
        ...     field_name="content",
        ...     fts=Fts(match_string="machine learning"),
        ...     param=FtsQueryParam(default_operator="AND")
        ... )
    """

    field_name: str
    id: Optional[str] = None
    vector: VectorType = None
    param: Optional[
        Union[HnswQueryParam, HnswRabitqQueryParam, IVFQueryParam, FtsQueryParam]
    ] = None
    fts: Optional[Fts] = None

    def has_id(self) -> bool:
        """Check if the query is based on a document ID.

        Returns:
            bool: True if `id` is set, False otherwise.
        """
        return self.id is not None

    def has_vector(self) -> bool:
        """Check if the query contains an explicit vector.