@@ -1,15 +1,9 @@
11+++
2−title = "Graph Store"
2+title = "Graph Store - Reference"
33weight = 3
44template = "doc.html"
55+++
66
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.
12−
137## Data types
148
159`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.
3529 ==
3630```
3731
38−Most of these elements are self explanatory.
39−
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.
41−
42−`hash` is a `sham` hash of `validated-portion` which includes the parent hash, author, time sent, and contents.
43−
44−`signatures` is a set of `signature` which is used to cryptographically sign graph-store messages.
45−
46−When interacting with `graph-store` you will need to create an `update`
47−
48−`update` is a tagged union that currently only has one option
49−
50−`[%0 p=time q=update-0]`
51−
52−The reason this is a union is to serve as future proofing for version changes.
53−
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.
55−
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.
57−
58−```hoon
59−+$ logged-update-0
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]
64− ==
65−::
66−+$ update-0
67− $% logged-update-0
68− [%add-graph =resource =graph mark=(unit mark)]
69− [%remove-graph =resource]
70− ::
71− [%add-tag =term =resource]
72− [%remove-tag =term =resource]
73− ::
74− [%archive-graph =resource]
75− [%unarchive-graph =resource]
76− [%run-updates =resource =update-log]
77− ::
78− :: NOTE: cannot be sent as pokes
79− ::
80− [%keys =resources]
81− [%tags tags=(set term)]
82− [%tag-queries =tag-queries]
83− ==
84−```
85−
8632## Pokes
8733
8834Graph Store can be poked with a `graph-update`, which can:
8935
9036- add and remove a graph
9137
92−`[%add-graph =resource =graph mark=(unit mark)]`
38+`[%add-graph =resource =graph mark=(unit mark) overwrite=?]`
9339
9440`[%remove-graph =resource]`
9541
@@ -97,7 +43,7 @@ Graph Store can be poked with a `graph-update`, which can:
9743
9844`[%add-nodes =resource nodes=(map index node)]`
9945
100−`[%remove-nodes =resource indices=(set index)]`
46+`[%remove-posts =resource indices=(set index)]`
10147
10248- add and remove signatures
10349
@@ -107,9 +53,9 @@ Graph Store can be poked with a `graph-update`, which can:
10753
10854- add and remove tags
10955
110−`[%add-tag =term =resource]`
56+`[%add-tag =term =uid]`
11157
112−`[%remove-tag =term =resource]`
58+`[%remove-tag =term =uid]`
11359
11460- archive and unarchive a graph
11561
@@ -117,43 +63,61 @@ Graph Store can be poked with a `graph-update`, which can:
11763
11864`[%unarchive-graph =resource]`
11965
66+- manually process an update log on a resource
67+ `[%run-updates =resource =update-log]`
68+
12069## Scries
12170
12271What follows is a summary of the scrys available in graph-store
12372
73+<!-- enhancement: add examples -->
74+
12475- Fetch keys
125− `[%x %keys ~]`
76+ `/x/keys`
77+
78+- Fetch tag queries
79+ `/x/tag-queries`
12680
12781- Fetch tags
128− `[%x %tags ~]`
82+ `/x/tag-queries/tags`
12983
130−- Fetch tag queries
131− `[%x %tag-queries ~]`
84+- Archive a specific graph by resource
85+ `/x/archive/[ship]/[name]`
86+
87+- Fetch the update log by resource
88+ `/x/update-log/[ship]/[name]`
89+
90+- Fetch the latest entry in the update log by resource
91+ `/x/update-log/[ship]/[name]/latest`
92+
93+- Fetch a subset of the update log
94+ `/x/update-log/[ship]/[name]/subset/[start]/[end]`
13295
13396- Fetch a specific graph by resource
134− `[%x %graph @ @ ~]`
97+ `/x/graph/[ship]/[name]`
13598
136−- Archive a specific graph by resource
137− `[%x %archive @ @ ~]`
99+- Request the mark of a graph
100+ `/x/graph/[ship]/[name]/mark`
138101
139−- Fetch a subset of the graph by resource and start and end indices
140− `[%x %graph-subset @ @ @ @ ~]`
102+- Request a subset of the graph
103+ `/x/graph/[ship]/[name]/subset/[mode]/[start]/[end]`
141104
142−- Select a node from a graph by resource and index
143− `[%x %node @ @ @ *]`
105+- Check if node exists
106+ `/x/graph/[ship]/[name]/node/exists/[index+]`
144107
145−- Fetch a subset of the children of a node by resource, index, and start and end indices
146− `[%x %node-children-subset @ @ @ @ @ *]`
108+- Request a node
109+ `/x/graph/[ship]/[name]/node/index/[mode]/[index+]`
147110
148−- Fetch a subset of the update log by resource and start and end indices
149− `[%x %update-log-subset @ @ @ @ ~]`
111+- Request a node's children
112+ `/x/graph/[ship]/[name]/node/children/[mode]/[start]/[end]/[index+]`
150113
151−- Fetch the update log by resource
152− `[%x %update-log @ @ ~]`
114+- Request a node's siblings
115+ `/x/graph/[ship]/[name]/node/siblings/[direction]/[mode]/[count]/[index+]`
153116
154−- Fetch the time of the last entry of the update log
155− ` [%x %peek-update-log @ @ ~]`
117+- Request a node's firstborn child
118+ `/x/graph/[ship]/[name]/node/firstborn/[index+]`
156119
157−## Marks
120+- Request nodes, depth first
121+ `/x/graph/[ship]/[name]/node/depth-first/[count]/[start]`
158122
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