chore: import upstream snapshot with attribution

python/zvec/model/param/__init__.py

@@ -0,0 +1,60 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from zvec._zvec.param import (
+    AddColumnOption,
+    AlterColumnOption,
+    CollectionOption,
+    DiskAnnIndexParam,
+    DiskAnnQueryParam,
+    FlatIndexParam,
+    FtsIndexParam,
+    FtsQueryParam,
+    HnswIndexParam,
+    HnswQueryParam,
+    HnswRabitqIndexParam,
+    HnswRabitqQueryParam,
+    IndexOption,
+    InvertIndexParam,
+    IVFIndexParam,
+    IVFQueryParam,
+    OptimizeOption,
+    QuantizerParam,
+    VamanaIndexParam,
+    VamanaQueryParam,
+)
+
+__all__ = [
+    "AddColumnOption",
+    "AlterColumnOption",
+    "CollectionOption",
+    "DiskAnnIndexParam",
+    "DiskAnnQueryParam",
+    "FlatIndexParam",
+    "FtsIndexParam",
+    "FtsQueryParam",
+    "HnswIndexParam",
+    "HnswQueryParam",
+    "HnswRabitqIndexParam",
+    "HnswRabitqQueryParam",
+    "IVFIndexParam",
+    "IVFQueryParam",
+    "IndexOption",
+    "InvertIndexParam",
+    "OptimizeOption",
+    "QuantizerParam",
+    "VamanaIndexParam",
+    "VamanaQueryParam",
+]

python/zvec/model/param/query.py

@@ -0,0 +1,143 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+from typing import Optional, Union
+
+from ...common import VectorType
+from . import FtsQueryParam, HnswQueryParam, HnswRabitqQueryParam, IVFQueryParam
+
+__all__ = ["Fts", "Query", "VectorQuery"]
+
+
+@dataclass(frozen=True)
+class Fts:
+    """Full-text search query parameters.
+
+    Attributes:
+        query_string (Optional[str]): FTS query expression
+            (e.g. '+vector -slow "exact phrase"'). Mutually exclusive with match_string.
+        match_string (Optional[str]): Natural language match string,
+            tokenized and combined using the default operator.
+            Mutually exclusive with query_string.
+    """
+
+    query_string: Optional[str] = None
+    match_string: Optional[str] = None
+
+
+@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.
+
+        Returns:
+            bool: True if `vector` is non-empty, False otherwise.
+        """
+        return self.vector is not None and len(self.vector) > 0
+
+    def has_fts(self) -> bool:
+        """Check if the query contains an FTS (full-text search) condition.
+
+        Returns:
+            bool: True if `fts` is set with a query_string or match_string.
+        """
+        if self.fts is not None:
+            return bool(self.fts.query_string) or bool(self.fts.match_string)
+        return False
+
+    def _validate(self) -> None:
+        if self.field_name is None:
+            raise ValueError("Field name cannot be empty")
+        if self.has_id() and self.has_vector():
+            raise ValueError("Cannot provide both id and vector")
+        if self.has_fts() and (self.has_vector() or self.has_id()):
+            raise ValueError(
+                "Cannot combine fts with vector search fields (id/vector) in a single Query"
+            )
+        if self.fts is not None and self.fts.query_string and self.fts.match_string:
+            raise ValueError(
+                "Cannot provide both query_string and match_string in Fts; "
+                "they are mutually exclusive"
+            )
+
+
+class VectorQuery(Query):
+    """Deprecated alias for Query. Use Query instead."""
+
+    def __new__(cls, *args, **kwargs):  # noqa : ARG004
+        warnings.warn(
+            "VectorQuery is deprecated and will be removed in a future version. "
+            "Use Query instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return super().__new__(cls)