feat: add sorting functionality

Author: Matthias Zimmermann

src/arkiv/__init__.py

@@ -9,9 +9,14 @@
 from .node import ArkivNode
 from .query import QueryIterator
 from .types import (
+    ASC,
+    DESC,
+    INT,
+    STR,
     CreateEvent,
     DeleteEvent,
     ExtendEvent,
+    OrderByAttribute,
     TransactionReceipt,
     UpdateEvent,
 )
@@ -23,6 +28,10 @@
     __version__ = "dev"
 
 __all__ = [
+    "ASC",
+    "DESC",
+    "INT",
+    "STR",
     "Arkiv",
     "ArkivNode",
     "AsyncArkiv",
@@ -32,6 +41,7 @@
     "EventFilter",
     "ExtendEvent",
     "NamedAccount",
+    "OrderByAttribute",
     "QueryIterator",
     "TransactionReceipt",
     "UpdateEvent",

src/arkiv/query.py

@@ -91,10 +91,11 @@ def __next__(self) -> Entity:
 
         # Fetch next page if available
         if self._current_result.has_more() and not self._exhausted:
-            options = QueryOptions(
-                fields=self._options.fields,
+            from dataclasses import replace
+
+            options = replace(
+                self._options,
                 at_block=self._current_result.block_number,
-                max_results_per_page=self._options.max_results_per_page,
                 cursor=self._current_result.cursor,
             )
             logger.info(
@@ -207,10 +208,11 @@ async def __anext__(self) -> Entity:
 
         # Fetch next page if available
         if self._current_result.has_more() and not self._exhausted:
-            options = QueryOptions(
-                fields=self._options.fields,
+            from dataclasses import replace
+
+            options = replace(
+                self._options,
                 at_block=self._current_result.block_number,
-                max_results_per_page=self._options.max_results_per_page,
                 cursor=self._current_result.cursor,
             )
             logger.info(

src/arkiv/types.py

@@ -40,12 +40,30 @@
 # Cursor type for entity set pagination for query results
 Cursor = NewType("Cursor", str)
 
+# Order by type constants
+STR = "str"
+INT = "int"
+
+# Order by direction constants
+ASC = "asc"
+DESC = "desc"
+
+
+@dataclass(frozen=True)
+class OrderByAttribute:
+    """Annotation for specifying order by fields in queries."""
+
+    attribute: str
+    type: Literal["str", "int"]
+    direction: Literal["asc", "desc"] = "asc"
+
 
 @dataclass(frozen=True)
 class QueryOptions:
     """Options for querying entities."""
 
     fields: int = ALL  # Bitmask of fields to populate
+    order_by: Sequence[OrderByAttribute] | None = None  # Fields to order results by
     at_block: int | None = (
         None  # Block number to pin query to specific block, or None to use latest block available
     )

src/arkiv/utils.py

@@ -32,13 +32,15 @@
     ATTRIBUTES,
     CONTENT_TYPE,
     CREATED_AT,
+    DESC,
     EXPIRATION,
     KEY,
     LAST_MODIFIED_AT,
     MAX_RESULTS_PER_PAGE_DEFAULT,
     OP_INDEX_IN_TX,
     OWNER,
     PAYLOAD,
+    STR,
     TX_INDEX_IN_BLOCK,
     Attributes,
     ChangeOwnerEvent,
@@ -298,6 +300,16 @@ def to_rpc_query_options(
     if options.cursor is not None:
         rpc_query_options["cursor"] = options.cursor
 
+    if options.order_by is not None:
+        rpc_query_options["orderBy"] = [
+            {
+                "name": ob.attribute,
+                "type": "string" if ob.type == STR else "numeric",
+                "desc": ob.direction == DESC,
+            }
+            for ob in options.order_by
+        ]
+
     return rpc_query_options
 
 

tests/test_query_language.py

@@ -1,176 +1,17 @@
 """Tests for Arkiv query language syntax and operators."""
 
 import logging
-import uuid
 
 from arkiv import Arkiv
-from arkiv.types import ATTRIBUTES, KEY, CreateOp, Operations, QueryOptions
+from arkiv.types import ATTRIBUTES, KEY, QueryOptions
 
-from .utils import to_create
+from .utils import create_test_entities
 
 OPTIONS = QueryOptions(fields=KEY | ATTRIBUTES, max_results_per_page=20)
 
 logger = logging.getLogger(__name__)
 
 
-def add_to_c(c: list[CreateOp], a):
-    c.append(to_create(attributes=a))
-
-
-def create_test_entities(client: Arkiv) -> tuple[str, list[str]]:
-    """
-    Create a batch of test entities with sequential numeric attributes.
-    """
-    batch = str(uuid.uuid4())
-
-    # Build list of CreateOp operations
-    c: list[CreateOp] = []
-    add_to_c(
-        c,
-        {
-            "batch": batch,
-            "id": 1,
-            "type": "A",
-            "size": "xs",
-            "idx": 1,
-            "email": "[email protected]",
-        },
-    )
-    add_to_c(
-        c,
-        {
-            "batch": batch,
-            "id": 2,
-            "type": "A",
-            "size": "s",
-            "idx": 2,
-            "email": "[email protected]",
-        },
-    )
-    add_to_c(
-        c,
-        {
-            "batch": batch,
-            "id": 3,
-            "type": "A",
-            "size": "m",
-            "idx": 3,
-            "email": "[email protected]",
-        },
-    )
-    add_to_c(
-        c,
-        {
-            "batch": batch,
-            "id": 4,
-            "type": "A",
-            "size": "l",
-            "idx": 4,
-            "email": "[email protected]",
-        },
-    )
-
-    add_to_c(
-        c,
-        {
-            "batch": batch,
-            "id": 5,
-            "type": "B",
-            "size": "xs",
-            "idx": 1,
-            "email": "[email protected]",
-        },
-    )
-    add_to_c(
-        c,
-        {
-            "batch": batch,
-            "id": 6,
-            "type": "B",
-            "size": "s",
-            "idx": 2,
-            "email": "[email protected]",
-        },
-    )
-    add_to_c(
-        c,
-        {
-            "batch": batch,
-            "id": 7,
-            "type": "B",
-            "size": "m",
-            "idx": 3,
-            "email": "[email protected]",
-        },
-    )
-    add_to_c(
-        c,
-        {
-            "batch": batch,
-            "id": 8,
-            "type": "B",
-            "size": "l",
-            "idx": 4,
-            "email": "[email protected]",
-        },
-    )
-
-    add_to_c(
-        c,
-        {
-            "batch": batch,
-            "id": 9,
-            "type": "C",
-            "size": "xs",
-            "idx": 1,
-            "email": "[email protected]",
-        },
-    )
-    add_to_c(
-        c,
-        {
-            "batch": batch,
-            "id": 10,
-            "type": "C",
-            "size": "s",
-            "idx": 2,
-            "email": "[email protected]",
-        },
-    )
-    add_to_c(
-        c,
-        {
-            "batch": batch,
-            "id": 11,
-            "type": "C",
-            "size": "m",
-            "idx": 3,
-            "email": "[email protected]",
-        },
-    )
-    add_to_c(
-        c,
-        {
-            "batch": batch,
-            "id": 12,
-            "type": "C",
-            "size": "l",
-            "idx": 4,
-            "email": "[email protected]",
-        },
-    )
-
-    # Execute all creates in a single transaction
-    operations = Operations(creates=c)
-    receipt = client.arkiv.execute(operations)
-
-    # Extract entity keys from receipt
-    entity_keys = [create.key for create in receipt.creates]
-    assert len(entity_keys) == 12
-
-    return batch, entity_keys
-
-
 def execute_query_test(
     client: Arkiv, label: str, query: str, expected_ids: list[int]
 ) -> None: