onyx-database 2.2.0__tar.gz → 2.3.0__tar.gz

{onyx_database-2.2.0 → onyx_database-2.3.0}/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2.3.0 - 2026-08-29
+
+- Added typed, hard-bounded native `CANDIDATES`, `SEARCH_CANDIDATES`, and
+  `HNSW_CANDIDATES` query helpers to sync and async builders.
+- Added lossless semantic-signature and HNSW wire validation, including signed
+  64-bit calibration identifiers, mixed-radix bucket checks, vector/work bounds,
+  and sole-root admission enforcement.
+- Added the missing public `NOT_BETWEEN` operator/helper so the Python SDK now
+  covers every Cloud query operator.
+
 ## 2.2.0 - 2026-08-29
 
 - Added sync and async `fenced_save`, `fenced_delete_where`, and `fenced_update_where` helpers for the

{onyx_database-2.2.0 → onyx_database-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: onyx-database
-Version: 2.2.0
+Version: 2.3.0
 Summary: Python client SDK for Onyx Cloud Database (builder-pattern API and schema helpers)
 Project-URL: Homepage, https://onyx.dev
 Project-URL: Repository, https://github.com/OnyxDevTools/onyx-database-python
@@ -491,7 +491,7 @@ Importable helpers for conditions and sort:
 from onyx_database import (
     eq, neq, within, not_within,
     in_op, not_in,
-    between,
+    between, not_between,
     gt, gte, lt, lte,
     like, not_like, contains, not_contains,
     starts_with, not_starts_with, matches, not_matches,
@@ -503,6 +503,39 @@ from onyx_database import (
 - Prefer `within` / `not_within` for inclusion checks (supports arrays, comma-separated strings, or inner queries).
 - `in_op` / `not_in` remain available for backward compatibility and are exact aliases.
 
+Native candidate channels are explicit and physically bounded:
+
+```py
+from onyx_database import hnsw_search_query
+
+lexical = (
+    db.from_table("ActiveDocumentChunk")
+    .in_partition("revision-7")
+    .approximate_search("customer success", max_candidates=128)
+    .limit(20)
+    .list()
+)
+
+semantic = (
+    db.from_table("ChunkAttentionHash")
+    .in_partition("revision-7")
+    .hnsw_candidates(
+        hnsw_search_query(
+            calibration_id=73,
+            vector=prompt_embedding,
+            max_candidates=256,
+            ef_search=1024,
+        )
+    )
+    .limit(20)
+    .list()
+)
+```
+
+`CANDIDATES`, `SEARCH_CANDIDATES`, and `HNSW_CANDIDATES` must be the sole root
+criterion. Candidate results are approximate; exactly rerank them when the
+full-precision vectors are available.
+
 Aggregate / string helpers for `select()` expressions:
 
 ```py
@@ -554,7 +587,7 @@ roles_missing_permission = (
 )
 ```
 
-### Native bounded full-text search
+### Native vector-managed search
 
 Use `.search(...)` on a builder or the `search` predicate helper to add a `MATCHES` condition against the `__full_text__` pseudo-field. `db.search(...)` sets `table = "ALL"` and seeds a query builder with that condition (extras like `partition`, `pageSize`, `nextPage` remain querystring params when provided).
 
@@ -694,6 +727,99 @@ Example request bodies emitted by the SDK:
 }
 ```
 
+For table-specific lexical, semantic, or hybrid search, build a validated
+`VectorSearchQuery`. The helper accepts Python snake_case arguments and emits the
+Cloud API's camelCase wire fields:
+
+```py
+from onyx_database import semantic_vector_signature, vector_search_query
+
+signature = semantic_vector_signature(
+    calibration_id=-7909761245221418085,
+    bucket_id=5,
+    cells=[1, 2],
+    cell_counts=[2, 3],
+    fingerprint=["0x0123456789abcdef"],
+    boundary_confidence=0.2,
+)
+
+hybrid = vector_search_query(
+    text="storm warning",
+    semantic=signature,
+    min_score=0.15,
+    nearby_bucket_radius=2,
+    max_candidates=500,
+    require_all_terms=False,
+)
+
+db.from_table(tables.Document).search(hybrid).limit(20).list()
+```
+
+`VectorSearchQuery` requires text and/or a semantic signature. Its defaults are
+`nearbyBucketRadius=1`, `maxCandidates=1000`, and `requireAllTerms=true`;
+`maxCandidates` is bounded to `1..5000`. Semantic helpers validate the mixed-radix
+bucket identifier, compute or verify exactly four fingerprint bands, keep the
+non-zero signed 64-bit calibration identifier as decimal text, and emit fingerprint
+words as fixed-width unsigned hexadecimal strings.
+
+Three explicit candidate APIs provide physically bounded admission for downstream
+reranking:
+
+```py
+from onyx_database import hnsw_search_query
+
+# Bounded lexical admission from a SEARCHABLE table.
+lexical = (
+    db.from_table(tables.Document)
+      .in_partition("corpus-a")
+      .approximate_search(
+          "storm warning",
+          min_score=0.1,
+          max_candidates=250,
+          require_all_terms=False,
+      )
+      .limit(20)
+      .list()
+)
+
+# Native HNSW nearest-neighbor admission.
+hnsw = hnsw_search_query(
+    calibration_id=-7909761245221418085,
+    vector=[0.25, -0.5, 0.75],
+    max_candidates=100,
+    ef_search=400,
+    min_score=0.2,
+)
+neighbors = (
+    db.from_table(tables.Document)
+      .in_partition("corpus-a")
+      .hnsw_candidates(hnsw)
+      .list()
+)
+
+# Bounded EQUAL/IN-style admission from an ordinary secondary index.
+routed = (
+    db.from_table(tables.Document)
+      .in_partition("corpus-a")
+      .approximate_candidates("tenantId", ["tenant-a", "tenant-b"], 200)
+      .list()
+)
+```
+
+`SEARCH_CANDIDATES`, `HNSW_CANDIDATES`, and `CANDIDATES` are positive, read-only,
+sole-root criteria. The builders reject attempts to combine them with `where`,
+`and_`, `or_`, or `search` in either call order. Partitioned tables require one
+concrete partition. HNSW vectors contain `1..16384` finite values with a non-zero
+norm; `maxCandidates` is `1..5000`, `efSearch` is at least `maxCandidates` and at
+most `20000`, and `minScore` is optional in `[-1, 1]`. The same methods and wire
+validation are available on `AsyncQueryBuilder`.
+
+Condition forms are exported as `approximate_search`, `hnsw_candidates`, and
+`approximate_candidates`. Use them only as the sole condition, for example
+`.where(approximate_search("storm", max_candidates=250))`. Database-wide
+`db.search(...)` remains the text-only API because the `ALL` route performs its own
+bounded lexical fan-out.
+
 ---
 
 ## Usage examples with `User`, `Role`, `Permission`

{onyx_database-2.2.0 → onyx_database-2.3.0}/README.md

@@ -466,7 +466,7 @@ Importable helpers for conditions and sort:
 from onyx_database import (
     eq, neq, within, not_within,
     in_op, not_in,
-    between,
+    between, not_between,
     gt, gte, lt, lte,
     like, not_like, contains, not_contains,
     starts_with, not_starts_with, matches, not_matches,
@@ -478,6 +478,39 @@ from onyx_database import (
 - Prefer `within` / `not_within` for inclusion checks (supports arrays, comma-separated strings, or inner queries).
 - `in_op` / `not_in` remain available for backward compatibility and are exact aliases.
 
+Native candidate channels are explicit and physically bounded:
+
+```py
+from onyx_database import hnsw_search_query
+
+lexical = (
+    db.from_table("ActiveDocumentChunk")
+    .in_partition("revision-7")
+    .approximate_search("customer success", max_candidates=128)
+    .limit(20)
+    .list()
+)
+
+semantic = (
+    db.from_table("ChunkAttentionHash")
+    .in_partition("revision-7")
+    .hnsw_candidates(
+        hnsw_search_query(
+            calibration_id=73,
+            vector=prompt_embedding,
+            max_candidates=256,
+            ef_search=1024,
+        )
+    )
+    .limit(20)
+    .list()
+)
+```
+
+`CANDIDATES`, `SEARCH_CANDIDATES`, and `HNSW_CANDIDATES` must be the sole root
+criterion. Candidate results are approximate; exactly rerank them when the
+full-precision vectors are available.
+
 Aggregate / string helpers for `select()` expressions:
 
 ```py
@@ -529,7 +562,7 @@ roles_missing_permission = (
 )
 ```
 
-### Native bounded full-text search
+### Native vector-managed search
 
 Use `.search(...)` on a builder or the `search` predicate helper to add a `MATCHES` condition against the `__full_text__` pseudo-field. `db.search(...)` sets `table = "ALL"` and seeds a query builder with that condition (extras like `partition`, `pageSize`, `nextPage` remain querystring params when provided).
 
@@ -669,6 +702,99 @@ Example request bodies emitted by the SDK:
 }
 ```
 
+For table-specific lexical, semantic, or hybrid search, build a validated
+`VectorSearchQuery`. The helper accepts Python snake_case arguments and emits the
+Cloud API's camelCase wire fields:
+
+```py
+from onyx_database import semantic_vector_signature, vector_search_query
+
+signature = semantic_vector_signature(
+    calibration_id=-7909761245221418085,
+    bucket_id=5,
+    cells=[1, 2],
+    cell_counts=[2, 3],
+    fingerprint=["0x0123456789abcdef"],
+    boundary_confidence=0.2,
+)
+
+hybrid = vector_search_query(
+    text="storm warning",
+    semantic=signature,
+    min_score=0.15,
+    nearby_bucket_radius=2,
+    max_candidates=500,
+    require_all_terms=False,
+)
+
+db.from_table(tables.Document).search(hybrid).limit(20).list()
+```
+
+`VectorSearchQuery` requires text and/or a semantic signature. Its defaults are
+`nearbyBucketRadius=1`, `maxCandidates=1000`, and `requireAllTerms=true`;
+`maxCandidates` is bounded to `1..5000`. Semantic helpers validate the mixed-radix
+bucket identifier, compute or verify exactly four fingerprint bands, keep the
+non-zero signed 64-bit calibration identifier as decimal text, and emit fingerprint
+words as fixed-width unsigned hexadecimal strings.
+
+Three explicit candidate APIs provide physically bounded admission for downstream
+reranking:
+
+```py
+from onyx_database import hnsw_search_query
+
+# Bounded lexical admission from a SEARCHABLE table.
+lexical = (
+    db.from_table(tables.Document)
+      .in_partition("corpus-a")
+      .approximate_search(
+          "storm warning",
+          min_score=0.1,
+          max_candidates=250,
+          require_all_terms=False,
+      )
+      .limit(20)
+      .list()
+)
+
+# Native HNSW nearest-neighbor admission.
+hnsw = hnsw_search_query(
+    calibration_id=-7909761245221418085,
+    vector=[0.25, -0.5, 0.75],
+    max_candidates=100,
+    ef_search=400,
+    min_score=0.2,
+)
+neighbors = (
+    db.from_table(tables.Document)
+      .in_partition("corpus-a")
+      .hnsw_candidates(hnsw)
+      .list()
+)
+
+# Bounded EQUAL/IN-style admission from an ordinary secondary index.
+routed = (
+    db.from_table(tables.Document)
+      .in_partition("corpus-a")
+      .approximate_candidates("tenantId", ["tenant-a", "tenant-b"], 200)
+      .list()
+)
+```
+
+`SEARCH_CANDIDATES`, `HNSW_CANDIDATES`, and `CANDIDATES` are positive, read-only,
+sole-root criteria. The builders reject attempts to combine them with `where`,
+`and_`, `or_`, or `search` in either call order. Partitioned tables require one
+concrete partition. HNSW vectors contain `1..16384` finite values with a non-zero
+norm; `maxCandidates` is `1..5000`, `efSearch` is at least `maxCandidates` and at
+most `20000`, and `minScore` is optional in `[-1, 1]`. The same methods and wire
+validation are available on `AsyncQueryBuilder`.
+
+Condition forms are exported as `approximate_search`, `hnsw_candidates`, and
+`approximate_candidates`. Use them only as the sole condition, for example
+`.where(approximate_search("storm", max_candidates=250))`. Database-wide
+`db.search(...)` remains the text-only API because the `ALL` route performs its own
+bounded lexical fan-out.
+
 ---
 
 ## Usage examples with `User`, `Role`, `Permission`

{onyx_database-2.2.0 → onyx_database-2.3.0}/onyx.schema.json

@@ -1,5 +1,5 @@
 {
-  "databaseId": "bbabca0e-82ce-11f0-0000-a2ce78b61b6a",
+  "databaseId": "YOUR_DATABASE_ID",
   "entities": [
     {
       "name": "AuditLog",

onyx_database-2.3.0/onyx_database/__init__.py

@@ -0,0 +1,177 @@
+"""Public entrypoint for the Onyx Database Python SDK."""
+
+from .config import WireFormat
+from .errors import (
+    OnyxConfigError,
+    OnyxHTTPError,
+    OnyxUnauthorizedError,
+    OnyxNotFoundError,
+    OnyxRateLimitedError,
+    OnyxClientError,
+    OnyxServerError,
+    OnyxTimeoutError,
+)
+from .onyx import OnyxFacade, onyx
+from .helpers.conditions import (
+    approximate_candidates,
+    approximate_search,
+    eq,
+    neq,
+    within,
+    not_within,
+    in_op,
+    not_in,
+    between,
+    not_between,
+    gt,
+    gte,
+    lt,
+    lte,
+    like,
+    not_like,
+    contains,
+    not_contains,
+    starts_with,
+    not_starts_with,
+    matches,
+    not_matches,
+    is_null,
+    not_null,
+    search,
+    hnsw_candidates,
+)
+from .helpers.candidate_search import (
+    DEFAULT_APPROXIMATE_INDEX_CANDIDATES,
+    DEFAULT_HNSW_CANDIDATES,
+    DEFAULT_HNSW_EF_SEARCH,
+    HNSW_QUERY_FORMAT_VERSION,
+    MAX_APPROXIMATE_INDEX_CANDIDATES,
+    MAX_APPROXIMATE_INDEX_ROUTE_VALUES,
+    MAX_HNSW_CANDIDATES,
+    MAX_HNSW_EF_SEARCH,
+    MAX_HNSW_VECTOR_DIMENSION,
+    MAX_VECTOR_SEARCH_CANDIDATES,
+    approximate_index_candidate_query,
+    hnsw_search_query,
+    semantic_vector_signature,
+    vector_search_query,
+)
+from .helpers.sort import asc, desc
+from .onyx_async import OnyxAsyncFacade, onyx_async
+from .types import (
+    ApproximateIndexCandidateQuery,
+    ApproximateSearchOptions,
+    FullTextQuery,
+    HnswSearchQuery,
+    HnswSearchQueryInput,
+    Int64WireInput,
+    QueryCriteriaOperator,
+    SemanticVectorSignature,
+    SemanticVectorSignatureInput,
+    VectorSearchQuery,
+    VectorSearchQueryInput,
+)
+from .helpers.aggregates import (
+    avg,
+    sum,
+    count,
+    min,
+    max,
+    std,
+    variance,
+    median,
+    upper,
+    lower,
+    substring,
+    replace,
+    format,
+    percentile,
+)
+
+__all__ = [
+    "OnyxFacade",
+    "OnyxAsyncFacade",
+    "onyx",
+    "onyx_async",
+    "WireFormat",
+    "OnyxConfigError",
+    "OnyxHTTPError",
+    "OnyxUnauthorizedError",
+    "OnyxNotFoundError",
+    "OnyxRateLimitedError",
+    "OnyxClientError",
+    "OnyxServerError",
+    "OnyxTimeoutError",
+    # conditions
+    "eq",
+    "neq",
+    "within",
+    "not_within",
+    "in_op",
+    "not_in",
+    "between",
+    "not_between",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "like",
+    "not_like",
+    "contains",
+    "not_contains",
+    "starts_with",
+    "not_starts_with",
+    "matches",
+    "not_matches",
+    "is_null",
+    "not_null",
+    "search",
+    "approximate_search",
+    "hnsw_candidates",
+    "approximate_candidates",
+    # native candidate-search wire helpers
+    "HNSW_QUERY_FORMAT_VERSION",
+    "DEFAULT_HNSW_CANDIDATES",
+    "DEFAULT_HNSW_EF_SEARCH",
+    "MAX_HNSW_CANDIDATES",
+    "MAX_HNSW_EF_SEARCH",
+    "MAX_HNSW_VECTOR_DIMENSION",
+    "DEFAULT_APPROXIMATE_INDEX_CANDIDATES",
+    "MAX_APPROXIMATE_INDEX_CANDIDATES",
+    "MAX_APPROXIMATE_INDEX_ROUTE_VALUES",
+    "MAX_VECTOR_SEARCH_CANDIDATES",
+    "semantic_vector_signature",
+    "vector_search_query",
+    "hnsw_search_query",
+    "approximate_index_candidate_query",
+    # public search types
+    "ApproximateIndexCandidateQuery",
+    "ApproximateSearchOptions",
+    "FullTextQuery",
+    "HnswSearchQuery",
+    "HnswSearchQueryInput",
+    "Int64WireInput",
+    "QueryCriteriaOperator",
+    "SemanticVectorSignature",
+    "SemanticVectorSignatureInput",
+    "VectorSearchQuery",
+    "VectorSearchQueryInput",
+    # sort
+    "asc",
+    "desc",
+    # aggregates
+    "avg",
+    "sum",
+    "count",
+    "min",
+    "max",
+    "std",
+    "variance",
+    "median",
+    "upper",
+    "lower",
+    "substring",
+    "replace",
+    "format",
+    "percentile",
+]