Skip to content
This repository was archived by the owner on Nov 21, 2026. It is now read-only.
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion bindings/python/docs/api/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:**

Expand Down
5 changes: 3 additions & 2 deletions bindings/python/docs/api/record-wrappers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
35 changes: 34 additions & 1 deletion bindings/python/docs/api/results.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down
1 change: 1 addition & 0 deletions bindings/python/docs/development/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
65 changes: 64 additions & 1 deletion bindings/python/src/arcadedb_embedded/_native/codec.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",)

Expand All @@ -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)
Expand Down
6 changes: 5 additions & 1 deletion bindings/python/src/arcadedb_embedded/_native/database.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion bindings/python/src/arcadedb_embedded/core.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading
Loading