git.iko.soy/urbit.org
on 66e9727 help sign in
urbit.org/userspace/landscape/reference/graph-store.md
160 lines 4.7 kB history raw
1+++
2title = "Graph Store"
3weight = 3
4template = "doc.html"
5+++
7`graph-store` is a gall agent that implements of a tree with additional virtual
8edges by allowing nodes to reference other nodes. It is most comparable to
9modern NoSQL databases in structure, though it allows for schemas to be written
10in the form of marks. It is used as the backend for an increasing number of
11Landscape applications, and is considered to be best used for social data.
13## Data types
15`graphs` is a map of `resource` to `marked-graph`
17`resource` is a pair of ship and term which is where the graph is hosted and the name of the resource. Every graph is it's own resource.
19`marked-graph` is a pair of `graph` and `(unit mark)`. The semantics of a graph are defined by the mark. This is just for validating the structure of the graph.
21`graph` is a `mop`, a mold builder for order map, of an atom and a `node`.
23`node` is a pair of `post` and `children`.
25`post` is defined in `sur/post`. It contains:
27```hoon
28+$ post
29 $: author=ship
30 =index
31 time-sent=time
32 contents=(list content)
33 hash=(unit hash)
34 =signatures
35 ==
36```
39Most of these elements are self explanatory.
41`contents` is a `list` of `content` where `content` is a tagged union of text, url, code, or reference. This is where the contents of a publish post or an entry from links would be stored.
43`hash` is a `sham` hash of `validated-portion` which includes the parent hash, author, time sent, and contents.
45`signatures` is a set of `signature` which is used to cryptographically sign graph-store messages.
47When interacting with `graph-store` you will need to create an `update`
49`update` is a tagged union that currently only has one option
51`[%0 p=time q=update-0]`
53The reason this is a union is to serve as future proofing for version changes.
55An `update-0` can either be logged in the case of adding/removing nodes or signatures, or non-logged as in the case of adding/removing a graph. This logging refers to if this action adds an entry to the update log that is used to synchronize state between ships.
57Below is an excerpt of `sur/graph-store.hoon` at the time of writing, showing the definition of `logged-update-0` and `update-0` which should now be readable.
59```hoon
60+$ logged-update-0
61 $% [%add-nodes =resource nodes=(map index node)]
62 [%remove-nodes =resource indices=(set index)]
63 [%add-signatures =uid =signatures]
64 [%remove-signatures =uid =signatures]
65 ==
66::
67+$ update-0
68 $% logged-update-0
69 [%add-graph =resource =graph mark=(unit mark)]
70 [%remove-graph =resource]
71 ::
72 [%add-tag =term =resource]
73 [%remove-tag =term =resource]
74 ::
75 [%archive-graph =resource]
76 [%unarchive-graph =resource]
77 [%run-updates =resource =update-log]
78 ::
79 :: NOTE: cannot be sent as pokes
80 ::
81 [%keys =resources]
82 [%tags tags=(set term)]
83 [%tag-queries =tag-queries]
84 ==
85```
88## Pokes
90Graph Store can be poked with a `graph-update`, which can:
91 - add and remove a graph
93 `[%add-graph =resource =graph mark=(unit mark)]`
95 `[%remove-graph =resource]`
97 - add and remove a node to a graph
99 `[%add-nodes =resource nodes=(map index node)]`
101 `[%remove-nodes =resource indices=(set index)]`
103 - add and remove signatures
105 `[%add-signatures =uid =signatures]`
107 `[%remove-signatures =uid =signatures]`
109 - add and remove tags
111 `[%add-tag =term =resource]`
113 `[%remove-tag =term =resource]`
115 - archive and unarchive a graph
117 `[%archive-graph =resource]`
119 `[%unarchive-graph =resource]`
121## Scries
123What follows is a summary of the scrys available in graph-store
125- Fetch keys
126 `[%x %keys ~]`
128- Fetch tags
129 `[%x %tags ~]`
131- Fetch tag queries
132 `[%x %tag-queries ~]`
134- Fetch a specific graph by resource
135 `[%x %graph @ @ ~]`
137- Archive a specific graph by resource
138 `[%x %archive @ @ ~]`
140- Fetch a subset of the graph by resource and start and end indices
141 `[%x %graph-subset @ @ @ @ ~]`
143- Select a node from a graph by resource and index
144 `[%x %node @ @ @ *]`
146- Fetch a subset of the children of a node by resource, index, and start and end indices
147 `[%x %node-children-subset @ @ @ @ @ *]`
149- Fetch a subset of the update log by resource and start and end indices
150 `[%x %update-log-subset @ @ @ @ ~]`
152- Fetch the update log by resource
153 `[%x %update-log @ @ ~]`
155- Fetch the time of the last entry of the update log
156 `[%x %peek-update-log @ @ ~]`
158## Marks
160There are marks in `mar/graph/validator` that are worth reviewing. They are each short enough to read quickly. They are used to validate the shapes of various nouns to be stored in the graph-store.