5.2.19. xgt.TableRow

class xgt.TableRow(mapping=None, *, container_map: _ContainerMap | None = None, validation_id: int = 0)

Represents a row from a table frame providing access to the row properties and the frame the row belongs to. The base element class; Vertex and Edge extend it for their frame types.

The user shouldn’t manually construct these. They will be constructed by calls to get_data() when expand is 'light' or 'full'.

The class is implemented as a dictionary with the following keys:

  • ‘id’: Row ID

  • ‘metadata’: dict containing frame metadata (present only with expand='full'):

  • ‘name’: Table frame name

  • ‘schema’: Frame schema

  • ‘properties’: dict mapping column names to values

Identity. Equality and hashing are by element identity – the row id (frame + position) – not by dictionary contents. So the same element compares equal however much detail it was materialized with ('light' vs 'full'), and elements are usable as set members and dict keys. This matches the server’s WHERE v = $obj comparison. The validation (commit) id is deliberately not part of identity; use element_id when you need to distinguish versions:

  • a == b – same element (identity).

  • a.element_id == b.element_id – same element and same version.

Changed in version 2.7.0: Equality, ordering, and hashing are by element identity; previously these classes compared like plain dictionaries and were unhashable.

Round-trip. A captured element can be handed back to a later query to select the same element (an O(1) direct lookup, not a scan), in two forms:

  • Object: MATCH (v) WHERE v = $obj, passing the element as $obj.

  • String: MATCH (v) WHERE elementId(v) = $idval, passing element_id as $idval (the durable/storable form, and the only one available to arrow consumers).

Experimental: The API of this class may change in future releases.

Attributes

element_id

The element's elementId() string, "{rowid}:{commit_id}" -- a stable, round-trippable reference to this element.

frame

The frame the element belongs to.

position

The position of the element's row in its frame.

properties

A dictionary of the properties of the element.
property element_id: str

The element’s elementId() string, "{rowid}:{commit_id}" – a stable, round-trippable reference to this element. Pass it back into a query with WHERE elementId(v) = $idval to select this element in O(1), or compare two elements’ element_id values to check identity and version.

The token is opaque: treat it as a parseable string, not a durable key. A delete anywhere in the element’s frame invalidates it (see the server elementId() documentation).

Added in version 2.7.0.

Notes

The commit portion is the source frame’s delete id as captured when the result was written, so for an element a query returned this equals the server’s elementId(v) for the same element, whichever query returned it. A row id inserted directly into a ROWID column carries a conservative upper-bound id instead when the insert never read the frame it references; that can differ numerically from a same-element elementId(v) but validates the same way, rejecting on the first delete in the source frame, so the reference still round-trips.

property frame: TableFrame | VertexFrame | EdgeFrame

The frame the element belongs to.

property position: int

The position of the element’s row in its frame.

property properties: dict[str, Any]

A dictionary of the properties of the element. The keys are the property names.