@@ -1,15 +1,9 @@
2−title = "Graph Store"
2+title = "Graph Store - Reference"
4template = "doc.html"
4template = "doc.html"
7−`graph-store` is a gall agent that implements of a tree with additional virtual
8−edges by allowing nodes to reference other nodes. It is most comparable to
9−modern NoSQL databases in structure, though it allows for schemas to be written
10−in the form of marks. It is used as the backend for an increasing number of
11−Landscape applications, and is considered to be best used for social data.
13## Data types
7## Data types
15`graphs` is a map of `resource` to `marked-graph`
9`graphs` is a map of `resource` to `marked-graph`
@@ -35,61 +29,13 @@ Landscape applications, and is considered to be best used for social data.
38−Most of these elements are self explanatory.
40−`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.
42−`hash` is a `sham` hash of `validated-portion` which includes the parent hash, author, time sent, and contents.
44−`signatures` is a set of `signature` which is used to cryptographically sign graph-store messages.
46−When interacting with `graph-store` you will need to create an `update`
48−`update` is a tagged union that currently only has one option
50−`[%0 p=time q=update-0]`
52−The reason this is a union is to serve as future proofing for version changes.
54−An `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.
56−Below 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.
60− $% [%add-nodes =resource nodes=(map index node)]
61− [%remove-nodes =resource indices=(set index)]
62− [%add-signatures =uid =signatures]
63− [%remove-signatures =uid =signatures]
68− [%add-graph =resource =graph mark=(unit mark)]
69− [%remove-graph =resource]
71− [%add-tag =term =resource]
72− [%remove-tag =term =resource]
74− [%archive-graph =resource]
75− [%unarchive-graph =resource]
76− [%run-updates =resource =update-log]
78− :: NOTE: cannot be sent as pokes
81− [%tags tags=(set term)]
82− [%tag-queries =tag-queries]
88Graph Store can be poked with a `graph-update`, which can:
34Graph Store can be poked with a `graph-update`, which can:
90- add and remove a graph
36- add and remove a graph
92−`[%add-graph =resource =graph mark=(unit mark)]`
38+`[%add-graph =resource =graph mark=(unit mark) overwrite=?]`
94`[%remove-graph =resource]`
40`[%remove-graph =resource]`
@@ -97,7 +43,7 @@ Graph Store can be poked with a `graph-update`, which can:
98`[%add-nodes =resource nodes=(map index node)]`
44`[%add-nodes =resource nodes=(map index node)]`
100−`[%remove-nodes =resource indices=(set index)]`
46+`[%remove-posts =resource indices=(set index)]`
102- add and remove signatures
48- add and remove signatures
@@ -107,9 +53,9 @@ Graph Store can be poked with a `graph-update`, which can:
108- add and remove tags
54- add and remove tags
110−`[%add-tag =term =resource]`
56+`[%add-tag =term =uid]`
112−`[%remove-tag =term =resource]`
58+`[%remove-tag =term =uid]`
114- archive and unarchive a graph
60- archive and unarchive a graph
@@ -117,43 +63,61 @@ Graph Store can be poked with a `graph-update`, which can:
118`[%unarchive-graph =resource]`
64`[%unarchive-graph =resource]`
66+- manually process an update log on a resource
67+ `[%run-updates =resource =update-log]`
122What follows is a summary of the scrys available in graph-store
71What follows is a summary of the scrys available in graph-store
73+<!-- enhancement: add examples -->
124- Fetch keys
75- Fetch keys
125− `[%x %keys ~]`
76+ `/x/keys`
127- Fetch tags
81- Fetch tags
128− `[%x %tags ~]`
82+ `/x/tag-queries/tags`
130−- Fetch tag queries
84+- Archive a specific graph by resource
131− `[%x %tag-queries ~]`
85+ `/x/archive/[ship]/[name]`
87+- Fetch the update log by resource
88+ `/x/update-log/[ship]/[name]`
90+- Fetch the latest entry in the update log by resource
91+ `/x/update-log/[ship]/[name]/latest`
93+- Fetch a subset of the update log
94+ `/x/update-log/[ship]/[name]/subset/[start]/[end]`
133- Fetch a specific graph by resource
96- Fetch a specific graph by resource
134− `[%x %graph @ @ ~]`
97+ `/x/graph/[ship]/[name]`
136−- Archive a specific graph by resource
99+- Request the mark of a graph
137− `[%x %archive @ @ ~]`
100+ `/x/graph/[ship]/[name]/mark`
139−- Fetch a subset of the graph by resource and start and end indices
102+- Request a subset of the graph
140− `[%x %graph-subset @ @ @ @ ~]`
103+ `/x/graph/[ship]/[name]/subset/[mode]/[start]/[end]`
142−- Select a node from a graph by resource and index
105+- Check if node exists
143− `[%x %node @ @ @ *]`
106+ `/x/graph/[ship]/[name]/node/exists/[index+]`
145−- Fetch a subset of the children of a node by resource, index, and start and end indices
108+- Request a node
146− `[%x %node-children-subset @ @ @ @ @ *]`
109+ `/x/graph/[ship]/[name]/node/index/[mode]/[index+]`
148−- Fetch a subset of the update log by resource and start and end indices
111+- Request a node's children
149− `[%x %update-log-subset @ @ @ @ ~]`
112+ `/x/graph/[ship]/[name]/node/children/[mode]/[start]/[end]/[index+]`
151−- Fetch the update log by resource
114+- Request a node's siblings
152− `[%x %update-log @ @ ~]`
115+ `/x/graph/[ship]/[name]/node/siblings/[direction]/[mode]/[count]/[index+]`
154−- Fetch the time of the last entry of the update log
117+- Request a node's firstborn child
155− ` [%x %peek-update-log @ @ ~]`
118+ `/x/graph/[ship]/[name]/node/firstborn/[index+]`
157−## Marks
120+- Request nodes, depth first
121+ `/x/graph/[ship]/[name]/node/depth-first/[count]/[start]`
159−There 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.
123+## Agent State