Merge branch '65-add-query-functionalities' into dev

Author: greenrobot

AGENTS.md

@@ -32,7 +32,7 @@ Python binding for the ObjectBox C API (objectbox-c) via `ctypes`; objects are s
   - `codegen.py` — experimental, the alternative to `fast_builder.py` (only one is active: `experimental._flatbuffers_mode`): `CodegenBuilder` generates and `exec`s a marshal function per entity that does what `FastBuilder.marshal` does, unrolled; it uses a `FastBuilder`'s layouts. Changes to `FastBuilder.marshal` must be mirrored in the generated code; the same tests check both. It also generates an unmarshal function, used by `_Entity._unmarshal` in codegen mode, that must return the same values as `_unmarshal_table` (flatbuffers.Table, the reference), so changes to reading go into both. Each function is compiled at its first use; with `cache_dir` (`enable_flatbuffers_codegen`), via a .py file in that directory (named by the source hash) and Python's bytecode cache.
   - `idsync.py` — assigns IDs/UIDs by syncing the model against an `objectbox-model.json` file (read, matched by UID then name, rewritten from scratch). This is how renames/removals are tracked across schema changes.
 - **`Store`** (`store.py`) — opening a store: resolve the model (a `Model` or a model name string → collect registered entities), locate `objectbox-model.json` (explicit `model_json_file`, else the calling module's directory found via the call stack, else `__main__`'s directory, else CWD), run `sync_model` (only once per `Model` and JSON file in a process: `Model._synced_json_file`; models for names are cached in `_models_by_name`), then build `StoreOptions` and call `obx_store_open`. `skip_model_sync=True` opens an existing store without passing the model (schema from the database). Directory prefix `memory:` opens an in-memory DB.
-- **`Box`** (`box.py`) — CRUD per entity. `box.query(condition)` returns a `QueryBuilder`; conditions (`condition.py`, combinable with `&`/`|`) are applied onto the C query builder, then `.build()` yields a `Query`.
+- **`Box`** (`box.py`) — CRUD per entity. `box.query(condition)` returns a `QueryBuilder`; conditions (`condition.py`, combinable with `&`/`|`) are applied onto the C query builder, then `.build()` yields a `Query`. `Query.set_parameter(s)()` choose the C function by the property type (`_parameter_functions` in `query.py`); for `set_parameter(s)_alias()`, `QueryBuilder` records the property of each condition alias (`_alias_for_property`).
 - **Sync** (`sync.py`) — `SyncClient` (created only via `Sync.client()`; its constructor raises) wraps the C sync client (`obx_sync_*`; ctypes callbacks passed to C, also replaced ones, are kept referenced until the client is closed). The store keeps its open client alive (`Store.sync_client()`, like Java and Dart) and closes it (close listener) before the store is closed. `@SyncEntity()` sets the entity's Sync flags.
 - **Deprecated API**: `ObjectBox` and `Builder` are thin wrappers around `Store` kept for backward compatibility (`tests/test_deprecated.py`).
 - numpy and flatbuffers (which imports numpy) are imported lazily, only where needed (vector/flex properties, the reference FlatBuffers paths); no module-level imports of either (`tests/test_lazy_imports.py`). Use `is_ndarray()` (`c.py`) for type checks and `prop._fb_format` (struct format) instead of `prop._fb_type` outside the reference paths.

CHANGELOG.md

@@ -28,6 +28,18 @@ ObjectBox Python ChangeLog
   **Breaking:** this replaces `CoreException` and `NotFoundException` (the latter was exported by the top-level module).
   `IllegalArgumentError` is also a `ValueError`, `IllegalStateError` and `FeatureNotAvailable` are also a
   `RuntimeError`, so they can be caught as the matching built-in exception, too.
+* Query: order results via `QueryBuilder.order(property, flags)`, e.g. `box.query().order(Person.name).build()`;
+  `OrderFlags` (exported by the top-level module) adjust the order, e.g. `DESCENDING` or `CASE_SENSITIVE`;
+  `order_desc(property)` orders descending
+* Query: new "one of" conditions `String.one_of(values)` and, for integer properties, `one_of(values)` and
+  `not_one_of(values)`; their values can be changed on a built query via `set_parameter()` (see below)
+* Query: `set_parameter(property, value)` and `set_parameter_alias(alias, value)` change the value of a condition;
+  the property type decides how, e.g. a list sets the vector of a nearest neighbor search or the values of a
+  "one of" condition, and `Date` properties also take a `datetime`. `set_parameters(property, a, b)` and
+  `set_parameters_alias(alias, a, b)` change the two values of `between()`. New are also parameters for floating point
+  and bytes properties, and `describe_parameters()`.
+  **Breaking:** the typed methods `set_parameter_string()`, `set_parameter_int()` and `set_parameter_vector_f32()` are
+  removed; use `set_parameter()` instead, and `set_parameter_alias()` for their `set_parameter_alias_*()` variants.
 * Store: new `log_callback` option to receive the database's log messages
 * Top-level module now also exports `Query`, `QueryBuilder`, `PropertyQueryCondition` and `HnswFlags`
 * API reference documentation (docstrings for the public API; generated via Sphinx)

objectbox/__init__.py

@@ -27,6 +27,7 @@
 from objectbox.query_builder import QueryBuilder
 from objectbox.builder import Builder
 from objectbox.objectbox import ObjectBox
+from objectbox.query_builder import OrderFlags
 
 __all__ = [
     'Box',
@@ -77,7 +78,8 @@
     'QueryBuilder',
     'SyncEntity',
     'SyncClock',
-    'SyncPrecedence'
+    'SyncPrecedence',
+    'OrderFlags'
 ]
 
 # Python binding version

objectbox/c.py

@@ -976,6 +976,84 @@ def c_array_pointer(py_list: Union[List[Any], np.ndarray], c_type):
 # OBX_C_API obx_err obx_query_param_alias_int(OBX_query* query, const char* alias, int64_t value);
 obx_query_param_alias_int = c_fn_rc('obx_query_param_alias_int', [OBX_query_p, ctypes.c_char_p, ctypes.c_int64])
 
+# OBX_C_API obx_err obx_query_param_strings(OBX_query* query, obx_schema_id entity_id, obx_schema_id property_id,
+#                                          const char* const values[], size_t count);
+obx_query_param_strings = c_fn_rc('obx_query_param_strings',
+                                  [OBX_query_p, obx_schema_id, obx_schema_id, ctypes.POINTER(ctypes.c_char_p),
+                                   ctypes.c_size_t])
+
+# OBX_C_API obx_err obx_query_param_int64s(OBX_query* query, obx_schema_id entity_id, obx_schema_id property_id,
+#                                         const int64_t values[], size_t count);
+obx_query_param_int64s = c_fn_rc('obx_query_param_int64s',
+                                 [OBX_query_p, obx_schema_id, obx_schema_id, ctypes.POINTER(ctypes.c_int64),
+                                  ctypes.c_size_t])
+
+# OBX_C_API obx_err obx_query_param_int32s(OBX_query* query, obx_schema_id entity_id, obx_schema_id property_id,
+#                                         const int32_t values[], size_t count);
+obx_query_param_int32s = c_fn_rc('obx_query_param_int32s',
+                                 [OBX_query_p, obx_schema_id, obx_schema_id, ctypes.POINTER(ctypes.c_int32),
+                                  ctypes.c_size_t])
+
+# OBX_C_API obx_err obx_query_param_alias_strings(OBX_query* query, const char* alias, const char* const values[],
+#                                                size_t count);
+obx_query_param_alias_strings = c_fn_rc('obx_query_param_alias_strings',
+                                        [OBX_query_p, ctypes.c_char_p, ctypes.POINTER(ctypes.c_char_p),
+                                         ctypes.c_size_t])
+
+# OBX_C_API obx_err obx_query_param_alias_int64s(OBX_query* query, const char* alias, const int64_t values[],
+#                                               size_t count);
+obx_query_param_alias_int64s = c_fn_rc('obx_query_param_alias_int64s',
+                                       [OBX_query_p, ctypes.c_char_p, ctypes.POINTER(ctypes.c_int64), ctypes.c_size_t])
+
+# OBX_C_API obx_err obx_query_param_alias_int32s(OBX_query* query, const char* alias, const int32_t values[],
+#                                               size_t count);
+obx_query_param_alias_int32s = c_fn_rc('obx_query_param_alias_int32s',
+                                       [OBX_query_p, ctypes.c_char_p, ctypes.POINTER(ctypes.c_int32), ctypes.c_size_t])
+
+# OBX_C_API obx_err obx_query_param_2ints(OBX_query* query, obx_schema_id entity_id, obx_schema_id property_id,
+#                                        int64_t value_a, int64_t value_b);
+obx_query_param_2ints = c_fn_rc('obx_query_param_2ints',
+                                [OBX_query_p, obx_schema_id, obx_schema_id, ctypes.c_int64, ctypes.c_int64])
+
+# OBX_C_API obx_err obx_query_param_double(OBX_query* query, obx_schema_id entity_id, obx_schema_id property_id,
+#                                         double value);
+obx_query_param_double = c_fn_rc('obx_query_param_double', [OBX_query_p, obx_schema_id, obx_schema_id, ctypes.c_double])
+
+# OBX_C_API obx_err obx_query_param_2doubles(OBX_query* query, obx_schema_id entity_id, obx_schema_id property_id,
+#                                           double value_a, double value_b);
+obx_query_param_2doubles = c_fn_rc('obx_query_param_2doubles',
+                                   [OBX_query_p, obx_schema_id, obx_schema_id, ctypes.c_double, ctypes.c_double])
+
+# OBX_C_API obx_err obx_query_param_bytes(OBX_query* query, obx_schema_id entity_id, obx_schema_id property_id,
+#                                        const void* value, size_t size);
+obx_query_param_bytes = c_fn_rc('obx_query_param_bytes',
+                                [OBX_query_p, obx_schema_id, obx_schema_id, ctypes.c_void_p, ctypes.c_size_t])
+
+# OBX_C_API obx_err obx_query_param_alias_2ints(OBX_query* query, const char* alias, int64_t value_a, int64_t value_b);
+obx_query_param_alias_2ints = c_fn_rc('obx_query_param_alias_2ints',
+                                      [OBX_query_p, ctypes.c_char_p, ctypes.c_int64, ctypes.c_int64])
+
+# OBX_C_API obx_err obx_query_param_alias_double(OBX_query* query, const char* alias, double value);
+obx_query_param_alias_double = c_fn_rc('obx_query_param_alias_double', [OBX_query_p, ctypes.c_char_p, ctypes.c_double])
+
+# OBX_C_API obx_err obx_query_param_alias_2doubles(OBX_query* query, const char* alias, double value_a, double value_b);
+obx_query_param_alias_2doubles = c_fn_rc('obx_query_param_alias_2doubles',
+                                         [OBX_query_p, ctypes.c_char_p, ctypes.c_double, ctypes.c_double])
+
+# OBX_C_API obx_err obx_query_param_alias_bytes(OBX_query* query, const char* alias, const void* value, size_t size);
+obx_query_param_alias_bytes = c_fn_rc('obx_query_param_alias_bytes',
+                                      [OBX_query_p, ctypes.c_char_p, ctypes.c_void_p, ctypes.c_size_t])
+
+# OBX_C_API size_t obx_query_param_get_type_size(OBX_query* query, obx_schema_id entity_id, obx_schema_id property_id);
+# Not checked: returns 0 for non-scalar types (e.g. strings) and on errors.
+obx_query_param_get_type_size = c_fn_nocheck('obx_query_param_get_type_size', ctypes.c_size_t,
+                                             [OBX_query_p, obx_schema_id, obx_schema_id])
+
+# OBX_C_API size_t obx_query_param_alias_get_type_size(OBX_query* query, const char* alias);
+# Not checked: returns 0 for non-scalar types (e.g. strings) and on errors.
+obx_query_param_alias_get_type_size = c_fn_nocheck('obx_query_param_alias_get_type_size', ctypes.c_size_t,
+                                                   [OBX_query_p, ctypes.c_char_p])
+
 # OBX_C_API obx_err obx_qb_order(OBX_query_builder* builder, obx_schema_id property_id, OBXOrderFlags flags);
 obx_qb_order = c_fn_rc('obx_qb_order', [OBX_query_builder_p, obx_schema_id, OBXOrderFlags])
 

objectbox/condition.py

@@ -88,6 +88,8 @@ class PropertyQueryConditionOp(Enum):
     CONTAINS_KEY_VALUE = 12
     IS_NULL = 13
     NOT_NULL = 14
+    ONE_OF = 15
+    NOT_ONE_OF = 16
 
 
 class PropertyQueryCondition(QueryCondition):
@@ -112,6 +114,8 @@ class PropertyQueryCondition(QueryCondition):
         PropertyQueryConditionOp.CONTAINS_KEY_VALUE: "_contains_key_value",
         PropertyQueryConditionOp.IS_NULL: "_apply_is_null",
         PropertyQueryConditionOp.NOT_NULL: "_apply_not_null",
+        PropertyQueryConditionOp.ONE_OF: "_apply_one_of",
+        PropertyQueryConditionOp.NOT_ONE_OF: "_apply_not_one_of",
         # ... new property query conditions here ... :)
     }
 
@@ -130,7 +134,8 @@ def __init__(self, property_id: int, op: PropertyQueryConditionOp, args: Dict[st
         self._alias = None
 
     def alias(self, value: str):
-        """ Sets an alias for this condition that can later be used with Query's set_parameter_* methods. """
+        """ Sets an alias for this condition to change its value(s) on the built query via
+        ``Query.set_parameter_alias()`` or ``Query.set_parameters_alias()``. """
         self._alias = value
         return self
 
@@ -274,8 +279,21 @@ def _apply_is_null(self, qb: QueryBuilder) -> obx_qb_cond:
     def _apply_not_null(self, qb: QueryBuilder) -> obx_qb_cond:
         return qb.not_null(self._property_id)
 
+    def _apply_one_of(self, qb: QueryBuilder) -> obx_qb_cond:
+        values = self._args['values']
+        # Cannot tell strings from ints by the values (the list may be empty), so use the property kind
+        if self._args.get('string', False):
+            case_sensitive = self._args['case_sensitive']
+            return qb.in_strings(self._property_id, values, case_sensitive)
+        else:
+            return qb.in_ints(self._property_id, values)
+
+    def _apply_not_one_of(self, qb: QueryBuilder) -> obx_qb_cond:
+        values = self._args['values']
+        return qb.not_in_ints(self._property_id, values)
+
     def apply(self, qb: QueryBuilder) -> obx_qb_cond:
         c_cond = self._op_func(qb)
         if self._alias is not None:
-            qb.alias(self._alias)
+            qb._alias_for_property(self._alias, self._property_id)
         return c_cond

objectbox/model/properties.py

@@ -394,6 +394,32 @@ def not_equals(self, value) -> PropertyQueryCondition:
         args = {'value': value}
         return PropertyQueryCondition(self.id, PropertyQueryConditionOp.NOT_EQ, args)
 
+    def one_of(self, values: List[int]) -> PropertyQueryCondition:
+        """ *one of* (``in``) condition to be passed to :func:`Box.query`;
+        matches if the property value equals any of the given values.
+        Supported for 32-bit (Int32) and 64-bit (Int64, Id, Date, DateNano) integer properties;
+        raises a ``TypeError`` for other properties (e.g. Int8, Int16, Bool). """
+        self._assert_ids_assigned()
+        self._assert_one_of_supported()
+        args = {'values': values}
+        return PropertyQueryCondition(self.id, PropertyQueryConditionOp.ONE_OF, args)
+
+    def not_one_of(self, values: List[int]) -> PropertyQueryCondition:
+        """ *not one of* (``not in``) condition to be passed to :func:`Box.query`;
+        matches if the property value equals none of the given values.
+        Supported for 32-bit (Int32) and 64-bit (Int64, Id, Date, DateNano) integer properties;
+        raises a ``TypeError`` for other properties (e.g. Int8, Int16, Bool). """
+        self._assert_ids_assigned()
+        self._assert_one_of_supported()
+        args = {'values': values}
+        return PropertyQueryCondition(self.id, PropertyQueryConditionOp.NOT_ONE_OF, args)
+
+    def _assert_one_of_supported(self):
+        # The C API only supports 32-bit and 64-bit integers for "in" conditions
+        if self._ob_type not in (PropertyType.int, PropertyType.long, PropertyType.date, PropertyType.dateNano):
+            raise TypeError(f"Property \"{self.name}\" of type {PropertyType(self._ob_type).name} "
+                            f"does not support one_of()/not_one_of(); supported are 32-bit and 64-bit integers")
+
 
 # ID property (primary key)
 class Id(_IntProperty):
@@ -466,8 +492,13 @@ def less_or_equal(self, value, case_sensitive: bool = True) -> PropertyQueryCond
         self._assert_ids_assigned()
         args = {'value': value, 'case_sensitive': case_sensitive}
         return PropertyQueryCondition(self.id, PropertyQueryConditionOp.LTE, args)
-    
 
+    def one_of(self, values: List[str], case_sensitive: bool = True) -> PropertyQueryCondition:
+        """ *one of* (``in``) condition (opt-in: case-sensitive) to be passed to :func:`Box.query`;
+        matches if the property value equals any of the given values. """
+        self._assert_ids_assigned()
+        args = {'values': values, 'case_sensitive': case_sensitive, 'string': True}
+        return PropertyQueryCondition(self.id, PropertyQueryConditionOp.ONE_OF, args)
 
 # Signed Integer Numeric Properties
 class Int8(_IntProperty):