diff --git a/bindings/python/docs/api/database.md b/bindings/python/docs/api/database.md index 683a0036b94..55324f88491 100644 --- a/bindings/python/docs/api/database.md +++ b/bindings/python/docs/api/database.md @@ -820,7 +820,8 @@ Lookup a record by its RID. **Parameters:** -- `rid` (str): Record ID string (e.g. "#10:5") +- `rid` (str | RID): Record ID string (e.g. "#10:5"), or the RID object a row holds (see + [Record ids in rows](results.md#record-ids-in-rows)) **Returns:** diff --git a/bindings/python/docs/api/record-wrappers.md b/bindings/python/docs/api/record-wrappers.md index 2ffce26a616..3b9e4c9a2de 100644 --- a/bindings/python/docs/api/record-wrappers.md +++ b/bindings/python/docs/api/record-wrappers.md @@ -182,8 +182,9 @@ rid = doc.get_rid() #### `get_identity()` -Get the record identity (the underlying Java RID object). For a string RID, use -`get_rid()` or wrap with `str(...)`. +Get the record identity as an RID object (the engine's own `RID` on the JVM wheel; see +[Record ids in rows](results.md#record-ids-in-rows) for what it offers on both wheels). +For a string RID, use `get_rid()` or wrap with `str(...)`. ```python identity = doc.get_identity() diff --git a/bindings/python/docs/api/results.md b/bindings/python/docs/api/results.md index e4eb1caecd2..fa507323099 100644 --- a/bindings/python/docs/api/results.md +++ b/bindings/python/docs/api/results.md @@ -78,7 +78,8 @@ Convert all results to a list of dictionaries. Rows come over from the JVM in batches. Java writes each batch as JSON, tags the values JSON cannot carry exactly (`DECIMAL`, `DATE`, `DATETIME`, sets), and hands everything else -(RIDs, embedded documents, `float[]` arrays, ...) over as the engine's own object, so each +(RIDs, embedded documents, `float[]` arrays, ...) over as the engine's own object (a record id: see +[Record ids in rows](#record-ids-in-rows)), so each value has the Python type it always had (`date`, `datetime`, `Decimal`, ...) and no value crosses the JVM boundary on its own. On a 10,000-row, nine-property scan that is 7.1x faster than it was and within a few percent of `to_json_list()` (261 ms to 37 ms, laptop, @@ -615,6 +616,10 @@ Get the Record ID (RID) of the result, if available. - `str` (e.g. `"#10:5"`) or `None` +A record row (`SELECT FROM T`, `expand(...)`) has an identity, and so has a projection of `@rid` +that does not alias it (`SELECT @rid, name FROM T`). An aliased `@rid`, any other projection, +and an aggregate have none and return `None`. The value is text on every wheel. + **Example:** ```python @@ -625,6 +630,34 @@ print(result.get_rid()) --- +### Record ids in rows + +A record id that sits in a row value (`SELECT @rid AS r`, a `LINK` property, a list of +links such as `out('Knows').@rid`) comes back as an RID object, not as text, and it is the +same kind of value on the JVM wheel and the native wheel: + +- `str(rid)` is the text (`"#10:5"`), and so is an f-string. Compare and store record ids + as `str(rid)` when you need text; `get_rid()` always returns text. +- Two RIDs of the same record are equal and hash alike, so they work in sets and as dict + keys. RIDs sort by bucket, then position. +- `getBucketId()`, `getPosition()`, `toString()` and `isValid()` work on it. On the JVM + wheel the object is the engine's own `RID`; the native wheel returns a Python class with + the same methods. +- It goes back in as a query parameter (`WHERE @rid = ?`, or in a list passed by name) and to + `lookup_by_rid()`, as itself or as its text. +- Do not compare an RID with a string (`rid == "#10:5"`): that is `False` on the JVM wheel + and `True` on the native wheel. Use `str(rid) == "#10:5"`. + +```python +row = db.query("sql", "SELECT @rid AS r, name FROM User LIMIT 1").first() +rid = row.get("r") +print(str(rid)) # #10:5 +print(rid.getBucketId(), rid.getPosition()) # 10 5 +same = db.lookup_by_rid(rid) # or db.lookup_by_rid(str(rid)) +``` + +--- + ### `to_dict(convert_types: bool = True) -> Dict[str, Any]` Convert the result to a Python dictionary. diff --git a/bindings/python/docs/development/testing.md b/bindings/python/docs/development/testing.md index 8687ae7570c..082092a0823 100644 --- a/bindings/python/docs/development/testing.md +++ b/bindings/python/docs/development/testing.md @@ -75,6 +75,7 @@ asserts, so the list below stops at the file. | --- | --- | | `test_resultset.py` | `Result` and `ResultSet` iteration, accessors, paging, and release of the engine cursor | | `test_resultset_arrow.py` | `ResultSet.to_arrow()` | +| `test_record_id_values.py` | A record id inside a row (`SELECT @rid`, a LINK property, a list of links) behaves the same on both wheels: `str()`, equality, hashing, ordering, `getBucketId()` and friends, as a query parameter and to `lookup_by_rid()`; `get_rid()` is text for record, edge, `expand()` and `@rid` projection rows | | `test_dataframe_ingest.py` | `Database.insert_dataframe` and `insert_arrow` (every Arrow type of the mapping table written and read back, DATETIME precisions, nulls, declared-property conversion and refusal, pandas, Polars, and Arrow inputs, vertex types, a 100,000-row frame in batches, the failure contract) and `ResultSet.to_polars()` (round trip, the ImportError messages) | | `test_columnar_readers.py` | `to_columns`, `to_dataframe`, and `to_arrow` on schemaless and DECIMAL data, at several batch sizes | | `test_resultset_read_errors.py` | An engine error raised while a result set is read arrives as `ArcadeDBError` on every way of reading | diff --git a/bindings/python/src/arcadedb_embedded/_native/codec.py b/bindings/python/src/arcadedb_embedded/_native/codec.py index c57504fad6f..74fa605d603 100644 --- a/bindings/python/src/arcadedb_embedded/_native/codec.py +++ b/bindings/python/src/arcadedb_embedded/_native/codec.py @@ -123,7 +123,13 @@ def _dump(obj, binary): class RID: - """A record id as the engine returns it in a row; passed back as a parameter it is a link, not a string.""" + """A record id as the engine returns it in a row; passed back as a parameter it is a link, not a string. + + The JVM wheel hands out the engine's own ``RID`` in the same places, so this class offers what user code written + against that one uses: ``str(rid)`` is the text (``"#10:5"``), two RIDs of one record are equal and hash alike, + RIDs sort by bucket then position, and ``getBucketId()``, ``getPosition()``, ``toString()``, ``isValid()``, + ``equals()`` and ``compareTo()`` answer like the Java methods. Unlike the Java RID, an RID here also equals its text. + """ __slots__ = ("text",) @@ -142,6 +148,63 @@ def __eq__(self, other): def __hash__(self): return hash(self.text) + def _numbers(self): + """(bucket id, position) from the text; (-1, -1) for a text that is not ``#bucket:position``.""" + bucket, sep, position = self.text.lstrip("#").partition(":") + try: + return (int(bucket), int(position)) if sep else (-1, -1) + except ValueError: + return (-1, -1) + + def __lt__(self, other): + return ( + self._numbers() < other._numbers() + if isinstance(other, RID) + else NotImplemented + ) + + def __le__(self, other): + return ( + self._numbers() <= other._numbers() + if isinstance(other, RID) + else NotImplemented + ) + + def __gt__(self, other): + return ( + self._numbers() > other._numbers() + if isinstance(other, RID) + else NotImplemented + ) + + def __ge__(self, other): + return ( + self._numbers() >= other._numbers() + if isinstance(other, RID) + else NotImplemented + ) + + # the Java RID's methods, by their Java names (the JVM wheel's RID is that object) + def getBucketId(self): + return self._numbers()[0] + + def getPosition(self): + return self._numbers()[1] + + def toString(self): + return self.text + + def isValid(self): + bucket, position = self._numbers() + return bucket > -1 and position > -1 + + def equals(self, other): + return isinstance(other, RID) and self.text == other.text + + def compareTo(self, other): + mine, theirs = self._numbers(), other._numbers() + return (mine > theirs) - (mine < theirs) + def _restore_float(text): return float(text) diff --git a/bindings/python/src/arcadedb_embedded/_native/database.py b/bindings/python/src/arcadedb_embedded/_native/database.py index 68fe220b894..62f7b623fb2 100644 --- a/bindings/python/src/arcadedb_embedded/_native/database.py +++ b/bindings/python/src/arcadedb_embedded/_native/database.py @@ -83,7 +83,11 @@ def get_raw(self, name: str) -> Any: return self.get(name) def get_rid(self) -> Optional[str]: - return self._meta[0] if self._meta else None + if self._meta: + return self._meta[0] + # a projection of @rid (not an alias of it) is a row with that identity, as on the JVM wheel + rid = self._props.get("@rid") + return None if rid is None else str(rid) def _record(self, kinds): from .records import _wrap diff --git a/bindings/python/src/arcadedb_embedded/core.py b/bindings/python/src/arcadedb_embedded/core.py index ab22edf250b..be6bec1845e 100644 --- a/bindings/python/src/arcadedb_embedded/core.py +++ b/bindings/python/src/arcadedb_embedded/core.py @@ -1272,7 +1272,7 @@ def lookup_by_rid(self, rid: str) -> Any: Lookup a record by its RID. Args: - rid: Record ID string (e.g. "#10:5") + rid: Record ID string (e.g. "#10:5"), or the RID object a row holds Returns: Record object (Vertex, Document, or Edge) diff --git a/bindings/python/tests/test_record_id_values.py b/bindings/python/tests/test_record_id_values.py new file mode 100644 index 00000000000..5ec86db1f55 --- /dev/null +++ b/bindings/python/tests/test_record_id_values.py @@ -0,0 +1,224 @@ +"""A record id inside a row: the same behaviour on the JVM wheel and the native wheel. + +The contract (docs/api/results.md, "Record ids in rows"): + +- a record id that sits in a row value (``SELECT @rid``, a LINK property, a list of links) is an + RID object, not text: ``str(rid)`` is the text (``"#10:5"``), two RIDs of the same record are + equal and hash alike, and RIDs sort by bucket and position; +- ``getBucketId()``, ``getPosition()``, ``toString()`` and ``isValid()`` work on it (the Java + ``RID`` has them; the native wheel's ``RID`` offers the same names); +- an RID goes back in as a query parameter, and to ``lookup_by_rid``, as itself or as its text; +- ``get_rid()`` is text (or ``None``) on every wheel. + +Before this file the JVM wheel handed out a Java ``RID`` and the native wheel its own ``RID`` +class, and nothing pinned what the two had in common. Comparing an RID with a string (``rid == +"#10:5"``) is False on the JVM wheel and True on the native wheel, so it is not part of the +contract: compare ``str(rid)``. +""" + +import re + +import pytest + +RID_TEXT = re.compile(r"^#\d+:\d+$") + + +@pytest.fixture +def graph_db(temp_db): + db = temp_db + db.command("sql", "CREATE VERTEX TYPE Person") + db.command("sql", "CREATE EDGE TYPE Knows") + db.command("sql", "CREATE PROPERTY Person.friend LINK") + with db.transaction(): + db.command("sql", "CREATE VERTEX Person SET name = 'ann'").close() + db.command("sql", "CREATE VERTEX Person SET name = 'bob'").close() + db.command("sql", "CREATE VERTEX Person SET name = 'cy'").close() + for target in ("bob", "cy"): + db.command( + "sql", + "CREATE EDGE Knows FROM (SELECT FROM Person WHERE name = 'ann') " + "TO (SELECT FROM Person WHERE name = ?)", + target, + ).close() + db.command( + "sql", + "UPDATE Person SET friend = (SELECT @rid FROM Person WHERE name = 'bob') " + "WHERE name = 'ann'", + ).close() + return db + + +def _rid_of(db, name): + return ( + db.query("sql", "SELECT @rid AS r FROM Person WHERE name = ?", name) + .first() + .get("r") + ) + + +def test_rid_in_a_row_prints_as_its_text(graph_db): + rid = _rid_of(graph_db, "ann") + assert not isinstance(rid, str) + assert RID_TEXT.match(str(rid)) + assert f"{rid}" == str(rid) + assert f"x{rid}x" == f"x{str(rid)}x" + + +def test_every_row_path_gives_the_same_kind_of_value(graph_db): + sql = "SELECT @rid AS r FROM Person WHERE name = 'ann'" + via_get = graph_db.query("sql", sql).first().get("r") + via_list = graph_db.query("sql", sql).to_list()[0]["r"] + via_dict = graph_db.query("sql", sql).first().to_dict()["r"] + via_iter = next(iter(graph_db.query("sql", sql).iter_dicts()))["r"] + assert type(via_get) is type(via_list) is type(via_dict) is type(via_iter) + assert str(via_get) == str(via_list) == str(via_dict) == str(via_iter) + + +def test_same_record_is_equal_and_hashes_alike(graph_db): + first = _rid_of(graph_db, "ann") + second = _rid_of(graph_db, "ann") + other = _rid_of(graph_db, "bob") + assert first == second + assert not (first != second) + assert first != other + assert hash(first) == hash(second) + assert len({first, second, other}) == 2 + assert {first: "x"}[second] == "x" + + +def test_rids_sort_by_bucket_and_position(graph_db): + rids = [ + r["r"] for r in graph_db.query("sql", "SELECT @rid AS r FROM Person").to_list() + ] + assert len(rids) == 3 + + def by_numbers(rid): + bucket, position = str(rid)[1:].split(":") + return int(bucket), int(position) + + assert [str(r) for r in sorted(rids)] == [ + str(r) for r in sorted(rids, key=by_numbers) + ] + lowest, highest = sorted(rids)[0], sorted(rids)[-1] + assert lowest < highest + assert highest > lowest + assert lowest <= lowest + assert highest >= highest + + +def test_bucket_and_position_accessors(graph_db): + rid = _rid_of(graph_db, "bob") + bucket, position = (int(part) for part in str(rid)[1:].split(":")) + assert int(rid.getBucketId()) == bucket + assert int(rid.getPosition()) == position + assert str(rid.toString()) == str(rid) + assert bool(rid.isValid()) is True + + +def test_link_property_is_a_rid_of_the_target(graph_db): + bob = _rid_of(graph_db, "bob") + row = graph_db.query("sql", "SELECT friend FROM Person WHERE name = 'ann'").first() + assert row.get("friend") == bob + assert type(row.get("friend")) is type(bob) + record = ( + graph_db.query("sql", "SELECT FROM Person WHERE name = 'ann'") + .first() + .get_vertex() + ) + assert record.get("friend") == bob + assert record.to_dict()["friend"] == bob + assert str(record.get("friend")) == graph_db.lookup_by_rid(str(bob)).get_rid() + + +def test_list_of_rids(graph_db): + row = graph_db.query( + "sql", "SELECT out('Knows').@rid AS ids FROM Person WHERE name = 'ann'" + ).first() + ids = row.get("ids") + assert len(ids) == 2 + assert {str(i) for i in ids} == { + str(_rid_of(graph_db, "bob")), + str(_rid_of(graph_db, "cy")), + } + assert all(type(i) is type(_rid_of(graph_db, "bob")) for i in ids) + + +def test_rid_goes_back_in_as_a_parameter(graph_db): + bob = _rid_of(graph_db, "bob") + cy = _rid_of(graph_db, "cy") + + def names(rows): + return sorted(r.get("name") for r in rows) + + assert names( + graph_db.query("sql", "SELECT name FROM Person WHERE @rid = ?", bob) + ) == ["bob"] + assert names( + graph_db.query("sql", "SELECT name FROM Person WHERE @rid = :r", {"r": bob}) + ) == ["bob"] + # (a lone list argument is the parameter list itself, so a list value goes by name) + assert names( + graph_db.query( + "sql", "SELECT name FROM Person WHERE @rid IN :ids", {"ids": [bob, cy]} + ) + ) == ["bob", "cy"] + # the text works as a parameter on both wheels as well + assert names( + graph_db.query("sql", "SELECT name FROM Person WHERE @rid = ?", str(bob)) + ) == ["bob"] + + +def test_lookup_by_rid_takes_the_rid_or_its_text(graph_db): + bob = _rid_of(graph_db, "bob") + assert graph_db.lookup_by_rid(bob).get("name") == "bob" + assert graph_db.lookup_by_rid(str(bob)).get("name") == "bob" + assert graph_db.lookup_by_rid(bob).get_rid() == str(bob) + + +def test_get_identity_is_the_same_kind_of_value(graph_db): + bob = _rid_of(graph_db, "bob") + vertex = graph_db.lookup_by_rid(str(bob)) + assert vertex.get_identity() == bob + assert type(vertex.get_identity()) is type(bob) + assert str(vertex.get_identity()) == vertex.get_rid() + + +def test_get_rid_is_text_for_every_kind_of_row(graph_db): + record = graph_db.query("sql", "SELECT FROM Person WHERE name = 'ann'").first() + assert isinstance(record.get_rid(), str) and RID_TEXT.match(record.get_rid()) + assert isinstance(record.get_vertex().get_rid(), str) + + edge = graph_db.query("sql", "SELECT FROM Knows").first() + assert isinstance(edge.get_rid(), str) and RID_TEXT.match(edge.get_rid()) + assert isinstance(edge.get_edge().get_rid(), str) + + expanded = graph_db.query( + "sql", "SELECT expand(out('Knows')) FROM Person WHERE name = 'ann'" + ).first() + assert isinstance(expanded.get_rid(), str) + + +def test_get_rid_of_a_projection(graph_db): + # a projection of @rid is a row with that identity, an aliased one or an aggregate is not + plain = graph_db.query( + "sql", "SELECT @rid, name FROM Person WHERE name = 'ann'" + ).first() + assert plain.get_rid() == str(_rid_of(graph_db, "ann")) + edge = graph_db.query("sql", "SELECT @rid FROM Knows").first() + assert isinstance(edge.get_rid(), str) and RID_TEXT.match(edge.get_rid()) + assert ( + graph_db.query("sql", "SELECT @rid AS r, name FROM Person WHERE name = 'ann'") + .first() + .get_rid() + is None + ) + assert ( + graph_db.query("sql", "SELECT name FROM Person WHERE name = 'ann'") + .first() + .get_rid() + is None + ) + assert ( + graph_db.query("sql", "SELECT count(*) AS c FROM Person").first().get_rid() + is None + )