Edges

Link two records, change the link and remove it.

Syntax

Three statements, one for each change. The collection's name ends in _edge.

INSERT EDGE {"_from": gid, "_to": gid, "key": value} IN name_edge
UPDATE EDGE {"key": value} IN name_edge FILTER(condition)
REMOVE EDGE IN name_edge FILTER(condition)

Parameters and arguments

  • _from, _to

    The GIDs of the two ends, in an insert

    Required: Yes
  • label

    The relationship's name. Kept in the metadata, and on the edge as the label a named graph filters by

    Required: No
  • weight

    A number a shortest-path search adds up. The default is 1

    Required: No
  • other keys

    Kept as the edge's metadata. In an update they are merged into what is there

    Required: No
  • name_edge

    The edge collection: lower case, ending in _edge, such as placed_by_edge. It is made the first time you write to it

    Required: Yes
  • FILTER(…)

    Chooses the edges to change or remove. Required for UPDATE EDGE and REMOVE EDGE

    Required: Yes

Examples

An edge with a label kept as metadata.

Return type and behaviour

INSERT EDGE. The answer lists the edge's id. info.insertedIds holds one record when the statement made a new edge, and info.updatedIds holds one when the pair of ends already had an edge and the statement replaced its metadata, label and weight. The record's gid is the edge's id as stored, the only id an edge collection carries.

"info": {"insertedIds": [{"gid": "gid://<namespace>/edge/<hash>"}]}

Writing the same _from and _to again answers updatedIds with the same gid, which is how you tell a new link from a repeat without a read:

"info": {"updatedIds": [{"gid": "gid://<namespace>/edge/<hash>"}]}

The edge id. The engine makes it from the two ends alone: gid://<namespace>/<resource>/<hash>, where the hash is the MD5 of _from, a | and _to. The namespace is your tenant's platform name. The resource is edge for a collection made by a first write, and the type the platform registers for one of its own, such as ProductEdge. The same two ends always make the same id, and the direction counts: a to b and b to a are two edges. You never write an id.

UPDATE EDGE. It answers the number of edges it changed in info.modifiedCount. A FILTER that matches no edge answers 0 and a notice that the FILTER matched no edges.

"info": {"modifiedCount": 1}

REMOVE EDGE. It answers the number of edges it deleted in info.deletedCount, and with no match 0 and a notice that the FILTER matched no edges.

"info": {"deletedCount": 2}

Who owns an edge. The engine stamps tenant_id from your session and member_id from the member the session acts as, when there is one. A row is visible to its tenant, and to its member, so an edge written for a member's own graph stays that member's.

The collection. The first write to a name_edge makes the collection in your tenant's own schema, with these columns. A write sets the first group; the rest take their defaults and are there for the governance and history of the link.

ColumnWhat it holdsSet by
edge_idThe edge's id, the GID described above. With tenant_id it is the primary key, so one pair of ends is one edge in a tenantThe engine
tenant_idThe tenant that owns the edge. Every read and write is scoped to itThe engine
member_idThe member that owns the edge, when it was written as a member. Empty for a company's edgeThe engine
_fromThe GID of the record the edge leaves. Must start with gid://You
_toThe GID of the record the edge arrives at. Must start with gid://, and must differ from _fromYou
_from_type, _to_typeThe resource part of each end, such as order and customer, in lower case. A PRUNE compares against theseThe engine, from the GIDs
labelThe relationship's name, from the label key. Empty when none is given. A named graph filters by itYou
weightA number, from the weight key, and 1 when none is given. A shortest-path search adds it up along a routeYou
metadataEvery other key you wrote, as a JSON document, with label and weight as well. UPDATE EDGE merges new keys into itYou
classificationHow sensitive the link is. INTERNAL by default. A traversal does not follow an edge classified above the caller's clearanceDefault
jurisdiction_code, acl_policy_id, acl_visibilityThe jurisdiction, the access policy and the list of who may see the edge. Empty by defaultDefault
confidenceHow sure the link is, from 0 to 1. 1 by defaultDefault
source_flow_id, proof_refThe flow that produced the edge and a reference to its proof. Empty unless a governed statement sets themDefault
signer_principal_id, signature, signed_atWho signed the edge, the signature and when. Empty unless a governed statement sets themDefault
valid_from, valid_toThe period the link holds in the business. valid_from is the time of the write. A valid_to of null means the link is current, and a traversal follows only current edgesDefault
system_from, system_toThe period the database held this version of the rowDefault
created_at, updated_atWhen the edge was first written, and when it was last changed by a rewrite of its pair or an UPDATE EDGEThe engine

The collection is indexed on (tenant_id, _from, label) and (tenant_id, _to, label), so a read by one end, with or without a label, is the fast path in either direction. It is also indexed on each end's type and on the metadata.

Reading edges back. An edge collection is a table, so a LOOKUP reads it and a FILTER on _from, _to or label chooses the edges. For a walk, a path or a stop at a type, the graph statements read the same collection: see Traversal, BFS and DFS, Shortest paths and Pruning.

Errors and exceptions
ErrorWhat happenedHow to recover
HTQL-6011The collection is not named like name_edgeUse lower case with the _edge suffix
HTQL-6012An edge is missing _from or _to, sets a key the engine owns (edgeId, _from_type, _to_type, tenant_id), joins an end to itself, moves an end, or names an end that does not existFix the edge as the message says
HTQL-2011An UPDATE EDGE or REMOVE EDGE has no FILTERAdd FILTER(condition)
Placement and context

Each is a statement of its own, and each can be a step inside a FOREACH.

FOR row IN table
  FILTER(row.column = value) BEGIN
  INSERT EDGE {
    "_from": row.fromColumn,
    "_to": row.toColumn,
    "label": "name"
  } IN name_edge
END

In a loop _from and _to may be the loop's fields, so one statement links every row the loop walks, one edge for each row, in the same transaction as the loop's other writes. An end's existence is not checked inside a loop: the engine skips the lookup that a single INSERT EDGE makes, and takes the end's type from the resource part of its GID. Check the ends in the loop's own FILTER when a row might hold a GID that names no record.

A loop that finds no rows writes no edges. See FOREACH.

Limitations
  • An edge cannot join a record to itself.
  • UPDATE EDGE changes an edge's attributes: its document is merged into the metadata, and a label or weight it names becomes the label a named graph filters by and the weight a shortest-path search adds up. It cannot move an edge's ends.
  • A write needs a FILTER for UPDATE and REMOVE.
  • For the platform's own record types, such as order and customer, both ends must exist. An end of any other resource, such as ticket, is accepted as written.
Permissions and security

The engine sets the tenant, so the caller never writes tenant_id.

Best practices
  • Name each collection for the relationship, such as placed_by_edge.
  • To relink, remove the edge and insert a new one.
  • Run the same FILTER in a LOOKUP before you remove edges.