A graph collection stores edges as triplets of a source, a target and an edge identifier, indexed from both ends.
The graph calls address a collection created with ustore_modality_graph_k, which the in-memory engine keeps apart from every collection of values.
Several edges between the same two vertices need distinct edge identifiers, and an edge without one gets ustore_edge_id_default_k.
ustore_graph_write_edges adds edges together with their vertices.
ustore_graph_write_vertices adds vertices without edges.
ustore_graph_read_edges exports the degree and the edges of every requested vertex in the requested role.
ustore_graph_remove_edges removes edges and keeps their vertices.
ustore_graph_remove_vertices removes vertices together with all their edges.
ustore_graph_scan_vertices lists the vertices, those without edges included, as ustore_blobs_scan lists keys; a missing vertex reads with the degree ustore_vertex_degree_missing_k.
Every found edge takes three keys of edges: its source, its target and its identifier.
The edges of vertex i span from edge edges_offsets[i] up to edge edges_offsets[i + 1], so a missing vertex spans none, and edges_offsets is required whenever edges_per_vertex is asked for.
Outgoing edges come first, sorted by target, then incoming edges, sorted by source, and a missing vertex has the degree ustore_vertex_degree_missing_k.
Roles matter only in directed graphs, where ustore_vertex_role_source_k and ustore_vertex_role_target_k select one direction, and roles with NULL data stand for ustore_vertex_role_any_k.
API
Types
ustore_vertex_role_tThe role a vertex plays in an edge, where undirected graphs use ustore_vertex_role_any_k.
ustore_graph_vertices_cursor_tAn opaque handle to a walk over the vertex keys of one collection, which every pull resumes past the last key the pull before it handed out, as ustore_blobs_cursor_t walks.
ustore_status_contended_k The arena or the transaction the view reads through serves another call, the executor's deferred table is full, a callback blocks on the executor running it, or an NVMe value keeps changing size across reads.
Optional output for count plus one offsets into edges_per_vertex, counted in edges, where a missing vertex spans none, inside arena; required with edges_per_vertex.
Rewound by this call, then holding every output it writes; NULL is refused.
Statuses
ustore_status_invalid_argument_k means the arena, collections, vertices or degrees output is missing, the edges are asked without their offsets, the view was made by neither view constructor or belongs to another engine, a watching read goes through a staged transaction, or a collection holds another modality.
ustore_graph_write_edgesWrites a batch of edges between existing or new vertices.
Whether the transaction records the vertices it reads and writes for conflicts.
Statuses
ustore_status_contended_k The transaction serves another call, the executor's deferred table is full, a callback blocks on the executor running it, or an NVMe value keeps changing size across reads.
ustore_status_invalid_argument_k The collections, sources or targets are missing, the transaction belongs to another engine or is staged, the durability or watch is unknown, a flushed write names a transaction, ustore_watch_none_k comes without one on RocksDB and LevelDB, or a collection holds another modality.
Whether the transaction records the vertices it reads and writes for conflicts.
Statuses
ustore_status_contended_k The transaction serves another call, the executor's deferred table is full, a callback blocks on the executor running it, or an NVMe value keeps changing size across reads.
ustore_status_invalid_argument_k The collections, sources or targets are missing, the transaction belongs to another engine or is staged, the durability or watch is unknown, a flushed remove names a transaction, ustore_watch_none_k comes without one on RocksDB and LevelDB, or a collection holds another modality.
ustore_status_invalid_argument_k means the collections or vertices are missing, the transaction belongs to another engine or is staged, the durability or watch is unknown, a flushed write names a transaction, ustore_watch_none_k comes without one on RocksDB and LevelDB, or a collection holds another modality.
Whether the transaction records the vertices it reads and writes for conflicts.
Statuses
ustore_status_contended_k The transaction serves another call, the executor's deferred table is full, a callback blocks on the executor running it, or an NVMe value keeps changing size across reads.
ustore_status_invalid_argument_k means the collections or vertices are missing, the transaction belongs to another engine or is staged, the durability or watch is unknown, a flushed remove names a transaction, ustore_watch_none_k comes without one on RocksDB and LevelDB, or a collection holds another modality.
Whether the transaction records the vertices it reads and writes for conflicts.
Statuses
ustore_status_contended_k The transaction serves another call, the executor's deferred table is full, a callback blocks on the executor running it, or an NVMe value keeps changing size across reads.
ustore_status_contended_k The arena or the transaction the view reads through serves another call, the executor's deferred table is full, a callback blocks on the executor running it, or an NVMe value keeps changing size across reads.
ustore_status_invalid_argument_k means the arena, collections or an output is missing, the mode, direction or a predicate cost is unknown, the view was made by neither view constructor or belongs to another engine, a watching scan goes through a staged transaction, or a collection holds another modality.
ustore_graph_vertices_cursor_initOpens a walk over the vertex keys of one collection, reading nothing until its first pull.
Executor of the kind every pull runs on, which picks the side the walk computes on, where NULL walks on host executors; a pull on another kind of executor reports ustore_status_device_k.
Optional verdict on the keys of every page, asked as its cost says; host executors only.
Statuses
ustore_status_invalid_argument_k The cursor output is NULL, the view was made by neither view constructor or reads another database, or a predicate cost is unknown.
Optional callback reporting the one pull, which may cancel it before the cursor advances.
progress_statevoid *
Opaque pointer passed to progress.
Statuses
ustore_status_invalid_argument_k The cursor, the arena or the written output is NULL, the cursor walks another database, a watching pull goes through a staged transaction, or the collection holds another modality.
ustore_status_device_k The arena lives where another executor computes, a cursor opened for a device is pulled on host threads, or a host cursor is pulled on a device.
ustore_status_contended_k The arena, the cursor or the transaction it reads through serves another call, the executor's deferred table is full, a callback blocks on the executor running it, or an NVMe value keeps changing size across reads.
ustore_graph_vertices_cursor_freeWaits until every deferred call naming the cursor finishes, then frees it, giving back the holds it kept on its database and on the transaction or snapshot it reads through.
ustore_status_invalid_argument_k The arena, collections or an output is missing, the view was made by neither view constructor or belongs to another engine, a watching sample goes through a staged transaction, or a collection holds another modality.
ustore_status_contended_k The arena or the transaction the view reads through serves another call, the executor's deferred table is full, or a callback blocks on the executor running it.
ustore_status_invalid_argument_k means the arena or the collections are missing, the direction is unknown, the view was made by neither view constructor or belongs to another engine, a watching measure goes through a staged transaction, or a collection holds another modality.
ustore_status_contended_k The arena or the transaction the view reads through serves another call, the executor's deferred table is full, or a callback blocks on the executor running it.