pub type Degree = u32; A graph collection, created with Modality::Graph, indexes every edge from both of its vertices, and an Edge is laid out as the source, target and identifier keys the ABI puts on its tapes.
A slice of edges therefore crosses as three strided columns, and the tape a lookup exports reads back as &[Edge] without a copy.
Collection::graph adds and removes one edge at a time under the default identifier, and looks up a batch of vertices in one role through a one-off arena, copying the edges or the degrees out of it:
let mut similar = database.collection("similar")?;
similar.graph().add_edge(avatar, titanic)?;
let recommendations: Vec<Edge> = similar.graph().read_edges(&[avatar], Role::Source)?;
let degrees: Vec<Degree> = similar.graph().degrees(&[avatar, titanic], Role::Any)?;
similar.graph().remove_edge(avatar, titanic)?;The batch verbs, named as the C ABI names them, take edges with identifiers of their own, vertices, and a role per vertex:
use ustore::{Edge, Role, Roles};
let follows = database.collection_create("follows", Modality::Graph)?;
let [first, second, third, fourth, seventh] = [1u64, 2, 3, 4, 7].map(Key::from);
let edges = [Edge::new(first, second), Edge::new(first, third), Edge::with_id(second, third, seventh)];
database.head().graph_write_edges(follows, &edges, Durability::Buffered)?;
database.head().graph_write_vertices(follows, [fourth], Durability::Buffered)?;
let vertices = [first, third];
let found = database.head().graph_read_edges(follows, &vertices, Roles::Every(Role::Any), &mut arena)?;
for (vertex, run) in vertices.iter().zip(found.iter()) {
for edge in run.unwrap_or_default() {
println!("{vertex} meets {:?}", edge.neighbor_of(*vertex));
}
}
let roles = Roles::Each(&[Role::Source, Role::Target]);
let degrees = database.head().graph_degrees(follows, [first, second], roles, &mut arena)?;
database.head().graph_remove_edges(follows, [Edge::with_id(second, third, seventh)], Durability::Buffered)?;
database.head().graph_remove_vertices(follows, [first], Roles::Every(Role::Any), Durability::Buffered)?;Neighborhoods holds the degree of every vertex, the edges of all of them on one tape, and one more offset than vertices bounding the run of each, where a vertex the graph does not hold spans none, and its iterator splits the tape at those offsets.
Within one role the edges of a vertex come sorted by neighbor, and with both roles the outgoing edges precede the incoming ones. graph_degrees asks for the degrees alone, exporting no edges. Roles::Every gives the whole batch one role and Roles::Each gives every vertex its own, which must match the batch in length.
Every graph verb takes owned edges and vertices as well, so a deferred view serves each of them.
API
Types
DegreeThe number of edges a vertex connects to in the roles a lookup asked for.
StructGraphThe edges of one collection, each under the default identifier.4
pub struct Graph<'collection, 'view, Parent = Database> Every verb consumes the view; Collection::graph hands out the next one.
Implements
Debugadd_edgeAdds an edge from source to target, creating the collection as a graph when it is missing.
pub fn add_edge(self, source: Key, target: Key) -> Result<()> remove_edgeRemoves the edge from source to target, whether or not the graph holds it.
pub fn remove_edge(self, source: Key, target: Key) -> Result<()> read_edgesThe edges of every vertex in role, one run after another, copied out of a one-off arena, as db['similar'].graph.read_edges(avatar) lists them.
pub fn read_edges(self, vertices: &[Key], role: Role) -> Result<Vec<Edge>> degreesThe degree of every vertex in role, copied out of a one-off arena that exports no edges.
pub fn degrees(self, vertices: &[Key], role: Role) -> Result<Vec<Degree>> StructEdgeAn edge from its source to its target, laid out as the three keys every edge takes on a tape.3
pub struct Edge Fields
source | Key | The vertex the edge leaves. |
|---|---|---|
target | Key | The vertex the edge enters. |
id | Key | The identifier telling apart several edges between the same vertices. |
Implements
Clone, Copy, StructuralPartialEq, PartialEq, Eq, PartialOrd, Ord, Debug, HashnewAn edge carrying the default identifier.
pub fn new(source: Key, target: Key) -> Self with_idAn edge carrying its own identifier.
pub fn with_id(source: Key, target: Key, id: Key) -> Self neighbor_ofThe end of the edge opposite vertex, or None when vertex is neither end.
pub fn neighbor_of(&self, vertex: Key) -> Option<Key> StructGraphSampleVerticesConfigThe vertices a sample draws; see On::graph_sample_vertices.
pub struct GraphSampleVerticesConfig Fields
wanted | usize | Vertices drawn, at most. |
|---|
Implements
Clone, Copy, Debug, From<usize>StructGraphScanVerticesConfigThe vertices a scan keeps, what admits them and how it reports; see On::graph_scan_vertices.
pub struct GraphScanVerticesConfig<'config> Fields
wanted | usize | Vertices kept, at most. |
|---|---|---|
matching | Matching<'config> | Admits only the vertices its predicate approves; every vertex by default. |
mode | ScanMode | In what order the vertices come. |
progress | Option<&'config mut ProgressCallback<'config>> | Reports the scans finished and stops wherever it says to. |
Implements
From<usize>StructGraphVerticesCursorA walk over the vertices of one graph collection, which every pull resumes past the last key the pull before it handed out, as a crate::Cursor walks blobs, keeping the keys its Matching admits.1
pub struct GraphVerticesCursor<'view> Mirrors ustore_graph_vertices_cursor_t; dropping it calls ustore_graph_vertices_cursor_free.
Implements
Debug, DropnextPulls up to wanted next keys into arena, fewer once the walk nears its end and none past it.
pub fn next<'arena>(&mut self, wanted: usize, arena: &'arena mut Arena) -> Result<&'arena [Key]> Calls ustore_graph_vertices_cursor_next.
StructGraphVerticesCursorConfigWhat admits the vertices a cursor hands out; see On::graph_vertices_cursor.
pub struct GraphVerticesCursorConfig<'config> Fields
matching | Matching<'config> | Admits only the vertices its predicate approves; every vertex by default. |
|---|
Implements
StructNeighborhoodsThe degree and the edges of every vertex one lookup addressed, in the order they were asked for.4
pub struct Neighborhoods<'arena> The edges of one vertex run consecutively: sorted by neighbor within one role, with the outgoing edges ahead of the incoming ones when both roles were asked for.
Implements
Clone, Copy, Debug, IntoIteratordegreesThe degree of every vertex, with degree_missing for a vertex the graph does not hold.
pub fn degrees(&self) -> &'arena [Degree] offsetsOne more offset than vertices into Neighborhoods::edges, counted in edges, bounding the run of every vertex, where a vertex the graph does not hold spans none.
pub fn offsets(&self) -> &'arena [u64] edgesThe edges of every vertex, one run after another.
pub fn edges(&self) -> &'arena [Edge] iterThe edges of every vertex in order, or None for a vertex the graph does not hold.
pub fn iter(&self) -> EdgeRuns<'arena> EnumRoleThe role a vertex plays in the edges a call addresses.
pub enum Role Values
Source | 1 | The vertex the edges leave. |
|---|---|---|
Target | 2 | The vertex the edges enter. |
Any | 3 | Either end, which is the only role an undirected graph uses. |
Implements
Clone, Copy, StructuralPartialEq, PartialEq, Eq, Debug, Default, Hash, Display, FromStrEnumRolesThe roles of a batch of vertices: one for all of them, or one each.
pub enum Roles<'roles> Values
Every | (<a data-ref="Role">Role</a>) | Every vertex plays the same role. |
|---|---|---|
Each | (&'roles [<a data-ref="Role">Role</a>]) | The vertex at each position plays the role at the same position. |
Implements
Clone, Copy, StructuralPartialEq, PartialEq, Eq, Debug, HashStructEdgeRunsThe edges of every vertex of one lookup in order, or None for a vertex the graph does not hold.
pub struct EdgeRuns<'arena> Implements
Clone, Debug, Iterator, ExactSizeIterator, FusedIteratorStructGraphWriteEdgesAn upsert of edges; see On::graph_write_edges.
StructGraphRemoveEdgesA removal of edges; see On::graph_remove_edges.
StructGraphWriteVerticesAn upsert of bare vertices; see On::graph_write_vertices.
StructGraphRemoveVerticesA removal of vertices with their edges; see On::graph_remove_vertices.
StructGraphRemoveVerticesRangeA removal of one range of vertices with their edges; see On::graph_remove_vertices_range.
StructGraphScanVerticesA walk over the vertices of one graph collection; see On::graph_scan_vertices.
StructGraphSampleVerticesA random draw of vertices from one graph collection; see On::graph_sample_vertices.
StructGraphMeasureVerticesAn estimate of what a range of vertices holds; see On::graph_measure_vertices.
StructGraphDegreesA lookup of the degrees of vertices; see On::graph_degrees.
StructGraphReadEdgesA lookup of the degrees and the edges of vertices; see On::graph_read_edges.
Functions
degree_missingThe degree a lookup reports for a vertex the graph does not hold.
pub const fn degree_missing() -> Degree default_edge_idThe identifier an edge carries when it was given none, every bit of it set like key_unknown.
pub const fn default_edge_id() -> Key