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, _toThe GIDs of the two ends, in an insert
Required: YeslabelThe relationship's name. Kept in the metadata, and on the edge as the label a named graph filters by
Required: NoweightA number a shortest-path search adds up. The default is 1
Required: Noother keysKept as the edge's metadata. In an update they are merged into what is there
Required: Noname_edgeThe edge collection: lower case, ending in
Required: Yes_edge, such asplaced_by_edge. It is made the first time you write to itFILTER(…)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.
| Column | What it holds | Set by |
|---|---|---|
edge_id | The 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 tenant | The engine |
tenant_id | The tenant that owns the edge. Every read and write is scoped to it | The engine |
member_id | The member that owns the edge, when it was written as a member. Empty for a company's edge | The engine |
_from | The GID of the record the edge leaves. Must start with gid:// | You |
_to | The GID of the record the edge arrives at. Must start with gid://, and must differ from _from | You |
_from_type, _to_type | The resource part of each end, such as order and customer, in lower case. A PRUNE compares against these | The engine, from the GIDs |
label | The relationship's name, from the label key. Empty when none is given. A named graph filters by it | You |
weight | A number, from the weight key, and 1 when none is given. A shortest-path search adds it up along a route | You |
metadata | Every other key you wrote, as a JSON document, with label and weight as well. UPDATE EDGE merges new keys into it | You |
classification | How sensitive the link is. INTERNAL by default. A traversal does not follow an edge classified above the caller's clearance | Default |
jurisdiction_code, acl_policy_id, acl_visibility | The jurisdiction, the access policy and the list of who may see the edge. Empty by default | Default |
confidence | How sure the link is, from 0 to 1. 1 by default | Default |
source_flow_id, proof_ref | The flow that produced the edge and a reference to its proof. Empty unless a governed statement sets them | Default |
signer_principal_id, signature, signed_at | Who signed the edge, the signature and when. Empty unless a governed statement sets them | Default |
valid_from, valid_to | The 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 edges | Default |
system_from, system_to | The period the database held this version of the row | Default |
created_at, updated_at | When the edge was first written, and when it was last changed by a rewrite of its pair or an UPDATE EDGE | The 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
| Error | What happened | How to recover |
|---|---|---|
HTQL-6011 | The collection is not named like name_edge | Use lower case with the _edge suffix |
HTQL-6012 | An 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 exist | Fix the edge as the message says |
HTQL-2011 | An UPDATE EDGE or REMOVE EDGE has no FILTER | Add 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 EDGEchanges an edge's attributes: its document is merged into the metadata, and alabelorweightit 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
orderandcustomer, both ends must exist. An end of any other resource, such asticket, 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.