1# Gizmo API 2![Autogenerated file](https://img.shields.io/badge/file-generated-orange.svg) 3 4## The `graph` object 5 6Name: `graph`, Alias: `g` 7 8This is the only special object in the environment, generates the query objects. 9Under the hood, they're simple objects that get compiled to a Go iterator tree when executed. 10 11 12### `graph.AddDefaultNamespaces()` 13 14AddDefaultNamespaces register all default namespaces for automatic IRI resolution. 15 16 17### `graph.AddNamespace(pref, ns)` 18 19AddNamespace associates prefix with a given IRI namespace. 20 21 22### `graph.Emit(*)` 23 24Emit adds data programmatically to the JSON result list. Can be any JSON type. 25 26```javascript 27g.Emit({name:"bob"}) // push {"name":"bob"} as a result 28``` 29 30 31### `graph.LoadNamespaces()` 32 33LoadNamespaces loads all namespaces saved to graph. 34 35 36### `graph.M()` 37 38M is a shorthand for Morphism. 39 40 41### `graph.Morphism()` 42 43Morphism creates a morphism path object. Unqueryable on it's own, defines one end of the path. 44Saving these to variables with 45 46```javascript 47var shorterPath = graph.Morphism().Out("foo").Out("bar") 48``` 49 50is the common use case. See also: path.Follow(), path.FollowR(). 51 52 53### `graph.Uri(s)` 54 55Uri creates an IRI values from a given string. 56 57 58### `graph.V(*)` 59 60V is a shorthand for Vertex. 61 62 63### `graph.Vertex([nodeId],[nodeId]...)` 64 65Vertex starts a query path at the given vertex/vertices. No ids means "all vertices". 66 67 68Arguments: 69 70* `nodeId` (Optional): A string or list of strings representing the starting vertices. 71 72Returns: Path object 73 74 75## Path object 76 77Both `.Morphism()` and `.Vertex()` create path objects, which provide the following traversal methods. 78Note that `.Vertex()` returns a query object, which is a subclass of path object. 79 80For these examples, suppose we have the following graph: 81 82``` 83+-------+ +------+ 84| alice |----- ->| fred |<-- 85+-------+ \---->+-------+-/ +------+ \-+-------+ 86 ----->| #bob# | | |*emily*| 87+---------+--/ --->+-------+ | +-------+ 88| charlie | / v 89+---------+ / +--------+ 90 \--- +--------+ |*#greg#*| 91 \-->| #dani# |------------>+--------+ 92 +--------+ 93``` 94 95Where every link is a `<follows>` relationship, and the nodes with an extra `#` in the name have an extra `<status>` link. As in, 96 97``` 98<dani> -- <status> --> "cool_person" 99``` 100 101Perhaps these are the influencers in our community. So too are extra `*`s in the name -- these are our smart people, 102according to the `<smart_graph>` label, eg, the quad: 103 104``` 105<greg> <status> "smart_person" <smart_graph> . 106``` 107 108 109### `path.All()` 110 111All executes the query and adds the results, with all tags, as a string-to-string (tag to node) map in the output set, one for each path that a traversal could take. 112 113 114### `path.And(path)` 115 116And is an alias for Intersect. 117 118 119### `path.As(tags)` 120 121As is an alias for Tag. 122 123 124### `path.Back(tag)` 125 126Back returns current path to a set of nodes on a given tag, preserving all constraints. 127 128If still valid, a path will now consider their vertex to be the same one as the previously tagged one, 129with the added constraint that it was valid all the way here. 130Useful for traversing back in queries and taking another route for things that have matched so far. 131 132Arguments: 133 134* `tag`: A previous tag in the query to jump back to. 135 136Example: 137```javascript 138// Start from all nodes, save them into start, follow any status links, 139// jump back to the starting node, and find who follows them. Return the result. 140// Results are: 141// {"id": "<alice>", "start": "<bob>"}, 142// {"id": "<charlie>", "start": "<bob>"}, 143// {"id": "<charlie>", "start": "<dani>"}, 144// {"id": "<dani>", "start": "<bob>"}, 145// {"id": "<dani>", "start": "<greg>"}, 146// {"id": "<dani>", "start": "<greg>"}, 147// {"id": "<fred>", "start": "<greg>"}, 148// {"id": "<fred>", "start": "<greg>"} 149g.V().Tag("start").Out("<status>").Back("start").In("<follows>").All() 150``` 151 152 153### `path.Both([predicatePath], [tags])` 154 155Both follow the predicate in either direction. Same as Out or In. 156 157 158Example: 159```javascript 160// Find all followers/followees of fred. Returns bob, emily and greg 161g.V("<fred>").Both("<follows>").All() 162``` 163 164 165### `path.Count()` 166 167Count returns a number of results and returns it as a value. 168 169Example: 170```javascript 171// Save count as a variable 172var n = g.V().Count() 173// Send it as a query result 174g.Emit(n) 175``` 176 177 178### `path.Difference(path)` 179 180Difference is an alias for Except. 181 182 183### `path.Except(path)` 184 185Except removes all paths which match query from current path. 186 187In a set-theoretic sense, this is (A - B). While `g.V().Except(path)` to achieve `U - B = !B` is supported, it's often very slow. 188Example: 189```javascript 190var cFollows = g.V("<charlie>").Out("<follows>") 191var dFollows = g.V("<dani>").Out("<follows>") 192// People followed by both charlie (bob and dani) and dani (bob and greg) -- returns bob. 193cFollows.Except(dFollows).All() // The set (dani) -- what charlie follows that dani does not also follow. 194// Equivalently, g.V("<charlie>").Out("<follows>").Except(g.V("<dani>").Out("<follows>")).All() 195``` 196 197 198### `path.Filter(args)` 199 200Filter applies constraints to a set of nodes. Can be used to filter values by range or match strings. 201 202 203### `path.Follow(path)` 204 205Follow is the way to use a path prepared with Morphism. Applies the path chain on the morphism object to the current path. 206 207Starts as if at the g.M() and follows through the morphism path. 208 209Example: 210```javascript 211var friendOfFriend = g.Morphism().Out("<follows>").Out("<follows>") 212// Returns the followed people of who charlie follows -- a simplistic "friend of my friend" 213// and whether or not they have a "cool" status. Potential for recommending followers abounds. 214// Returns bob and greg 215g.V("<charlie>").Follow(friendOfFriend).Has("<status>", "cool_person").All() 216``` 217 218 219### `path.FollowR(path)` 220 221FollowR is the same as Follow but follows the chain in the reverse direction. Flips "In" and "Out" where appropriate, 222the net result being a virtual predicate followed in the reverse direction. 223 224Starts at the end of the morphism and follows it backwards (with appropriate flipped directions) to the g.M() location. 225 226Example: 227```javascript 228var friendOfFriend = g.Morphism().Out("<follows>").Out("<follows>") 229// Returns the third-tier of influencers -- people who follow people who follow the cool people. 230// Returns charlie (from bob), charlie (from greg), bob and emily 231g.V().Has("<status>", "cool_person").FollowR(friendOfFriend).All() 232``` 233 234 235### `path.FollowRecursive(*)` 236 237FollowRecursive is the same as Follow but follows the chain recursively. 238 239Starts as if at the g.M() and follows through the morphism path multiple times, returning all nodes encountered. 240 241Example: 242```javascript 243var friend = g.Morphism().Out("<follows>") 244// Returns all people in Charlie's network. 245// Returns bob and dani (from charlie), fred (from bob) and greg (from dani). 246g.V("<charlie>").FollowRecursive(friend).All() 247``` 248 249 250### `path.ForEach(callback) or (limit, callback)` 251 252ForEach calls callback(data) for each result, where data is the tag-to-string map as in All case. 253 254 255Arguments: 256 257* `limit` (Optional): An integer value on the first `limit` paths to process. 258* `callback`: A javascript function of the form `function(data)` 259 260Example: 261```javascript 262// Simulate query.All().All() 263graph.V("<alice>").ForEach(function(d) { g.Emit(d) } ) 264``` 265 266 267### `path.GetLimit(limit)` 268 269GetLimit is the same as All, but limited to the first N unique nodes at the end of the path, and each of their possible traversals. 270 271 272### `path.Has(predicate, object)` 273 274Has filters all paths which are, at this point, on the subject for the given predicate and object, 275but do not follow the path, merely filter the possible paths. 276 277Usually useful for starting with all nodes, or limiting to a subset depending on some predicate/value pair. 278 279 280 281Arguments: 282 283* `predicate`: A string for a predicate node. 284* `object`: A string for a object node or a set of filters to find it. 285 286Example: 287```javascript 288// Start from all nodes that follow bob -- results in alice, charlie and dani 289g.V().Has("<follows>", "<bob>").All() 290// People charlie follows who then follow fred. Results in bob. 291g.V("<charlie>").Out("<follows>").Has("<follows>", "<fred>").All() 292// People with friends who have names sorting lower then "f". 293g.V().Has("<follows>", gt("<f>")).All() 294``` 295 296 297### `path.HasR(*)` 298 299HasR is the same as Has, but sets constraint in reverse direction. 300 301 302### `path.In([predicatePath], [tags])` 303 304In is inverse of Out. 305Starting with the nodes in `path` on the object, follow the quads with predicates defined by `predicatePath` to their subjects. 306 307 308Arguments: 309 310* `predicatePath` (Optional): One of: 311 * null or undefined: All predicates pointing into this node 312 * a string: The predicate name to follow into this node 313 * a list of strings: The predicates to follow into this node 314 * a query path object: The target of which is a set of predicates to follow. 315* `tags` (Optional): One of: 316 * null or undefined: No tags 317 * a string: A single tag to add the predicate used to the output set. 318 * a list of strings: Multiple tags to use as keys to save the predicate used to the output set. 319 320Example: 321 322```javascript 323// Find the cool people, bob, dani and greg 324g.V("cool_person").In("<status>").All() 325// Find who follows bob, in this case, alice, charlie, and dani 326g.V("<bob>").In("<follows>").All() 327// Find who follows the people emily follows, namely, bob and emily 328g.V("<emily>").Out("<follows>").In("<follows>").All() 329``` 330 331 332### `path.InPredicates()` 333 334InPredicates gets the list of predicates that are pointing in to a node. 335 336Example: 337```javascript 338// bob only has "<follows>" predicates pointing inward 339// returns "<follows>" 340g.V("<bob>").InPredicates().All() 341``` 342 343 344### `path.Intersect(path)` 345 346Intersect filters all paths by the result of another query path. 347 348This is essentially a join where, at the stage of each path, a node is shared. 349Example: 350```javascript 351var cFollows = g.V("<charlie>").Out("<follows>") 352var dFollows = g.V("<dani>").Out("<follows>") 353// People followed by both charlie (bob and dani) and dani (bob and greg) -- returns bob. 354cFollows.Intersect(dFollows).All() 355// Equivalently, g.V("<charlie>").Out("<follows>").And(g.V("<dani>").Out("<follows>")).All() 356``` 357 358 359### `path.Is(node, [node..])` 360 361Filter all paths to ones which, at this point, are on the given node. 362 363 364Arguments: 365 366* `node`: A string for a node. Can be repeated or a list of strings. 367 368Example: 369```javascript 370// Starting from all nodes in the graph, find the paths that follow bob. 371// Results in three paths for bob (from alice, charlie and dani).All() 372g.V().Out("<follows>").Is("<bob>").All() 373``` 374 375 376### `path.LabelContext([labelPath], [tags])` 377 378LabelContext sets (or removes) the subgraph context to consider in the following traversals. 379Affects all In(), Out(), and Both() calls that follow it. The default LabelContext is null (all subgraphs). 380 381 382Arguments: 383 384* `predicatePath` (Optional): One of: 385 * null or undefined: In future traversals, consider all edges, regardless of subgraph. 386 * a string: The name of the subgraph to restrict traversals to. 387 * a list of strings: A set of subgraphs to restrict traversals to. 388 * a query path object: The target of which is a set of subgraphs. 389* `tags` (Optional): One of: 390 * null or undefined: No tags 391 * a string: A single tag to add the last traversed label to the output set. 392 * a list of strings: Multiple tags to use as keys to save the label used to the output set. 393 394Example: 395```javascript 396// Find the status of people Dani follows 397g.V("<dani>").Out("<follows>").Out("<status>").All() 398// Find only the statuses provided by the smart_graph 399g.V("<dani>").Out("<follows>").LabelContext("<smart_graph>").Out("<status>").All() 400// Find all people followed by people with statuses in the smart_graph. 401g.V().LabelContext("<smart_graph>").In("<status>").LabelContext(null).In("<follows>").All() 402``` 403 404 405### `path.Labels()` 406 407Labels gets the list of inbound and outbound quad labels 408 409 410### `path.Limit(limit)` 411 412Limit limits a number of nodes for current path. 413 414Arguments: 415 416* `limit`: A number of nodes to limit results to. 417 418Example: 419```javascript 420// Start from all nodes that follow bob, and limit them to 2 nodes -- results in alice and charlie 421g.V().Has("<follows>", "<bob>").Limit(2).All() 422``` 423 424 425### `path.Map(*)` 426 427Map is a alias for ForEach. 428 429 430### `path.Or(path)` 431 432Or is an alias for Union. 433 434 435### `path.Out([predicatePath], [tags])` 436 437Out is the work-a-day way to get between nodes, in the forward direction. 438Starting with the nodes in `path` on the subject, follow the quads with predicates defined by `predicatePath` to their objects. 439 440 441Arguments: 442 443* `predicatePath` (Optional): One of: 444 * null or undefined: All predicates pointing out from this node 445 * a string: The predicate name to follow out from this node 446 * a list of strings: The predicates to follow out from this node 447 * a query path object: The target of which is a set of predicates to follow. 448* `tags` (Optional): One of: 449 * null or undefined: No tags 450 * a string: A single tag to add the predicate used to the output set. 451 * a list of strings: Multiple tags to use as keys to save the predicate used to the output set. 452 453Example: 454 455```javascript 456// The working set of this is bob and dani 457g.V("<charlie>").Out("<follows>").All() 458// The working set of this is fred, as alice follows bob and bob follows fred. 459g.V("<alice>").Out("<follows>").Out("<follows>").All() 460// Finds all things dani points at. Result is bob, greg and cool_person 461g.V("<dani>").Out().All() 462// Finds all things dani points at on the status linkage. 463// Result is bob, greg and cool_person 464g.V("<dani>").Out(["<follows>", "<status>"]).All() 465// Finds all things dani points at on the status linkage, given from a separate query path. 466// Result is {"id": "cool_person", "pred": "<status>"} 467g.V("<dani>").Out(g.V("<status>"), "pred").All() 468``` 469 470 471### `path.OutPredicates()` 472 473OutPredicates gets the list of predicates that are pointing out from a node. 474 475Example: 476```javascript 477// bob has "<follows>" and "<status>" edges pointing outwards 478// returns "<follows>", "<status>" 479g.V("<bob>").OutPredicates().All() 480``` 481 482 483### `path.Save(predicate, tag)` 484 485Save saves the object of all quads with predicate into tag, without traversal. 486 487 488Arguments: 489 490* `predicate`: A string for a predicate node. 491* `tag`: A string for a tag key to store the object node. 492 493Example: 494```javascript 495// Start from dani and bob and save who they follow into "target" 496// Returns: 497// {"id" : "<bob>", "target": "<fred>" }, 498// {"id" : "<dani>", "target": "<bob>" }, 499// {"id" : "<dani>", "target": "<greg>" } 500g.V("<dani>", "<bob>").Save("<follows>", "target").All() 501``` 502 503 504### `path.SaveInPredicates(tag)` 505 506SaveInPredicates tags the list of predicates that are pointing in to a node. 507 508Example: 509```javascript 510// bob only has "<follows>" predicates pointing inward 511// returns {"id":"<bob>", "pred":"<follows>"} 512g.V("<bob>").SaveInPredicates("pred").All() 513``` 514 515 516### `path.SaveOpt(*)` 517 518SaveOpt is the same as Save, but returns empty tags if predicate does not exists. 519 520 521### `path.SaveOptR(*)` 522 523SaveOptR is the same as SaveOpt, but tags values via reverse predicate. 524 525 526### `path.SaveOutPredicates(tag)` 527 528SaveOutPredicates tags the list of predicates that are pointing out from a node. 529 530Example: 531```javascript 532// bob has "<follows>" and "<status>" edges pointing outwards 533// returns {"id":"<bob>", "pred":"<follows>"} 534g.V("<bob>").SaveInPredicates("pred").All() 535``` 536 537 538### `path.SaveR(*)` 539 540SaveR is the same as Save, but tags values via reverse predicate. 541 542 543### `path.Skip(offset)` 544 545Skip skips a number of nodes for current path. 546 547Arguments: 548 549* `offset`: A number of nodes to skip. 550 551Example: 552```javascript 553// Start from all nodes that follow bob, and skip 2 nodes -- results in dani 554g.V().Has("<follows>", "<bob>").Skip(2).All() 555``` 556 557 558### `path.Tag(tags)` 559 560Tag saves a list of nodes to a given tag. 561 562In order to save your work or learn more about how a path got to the end, we have tags. 563The simplest thing to do is to add a tag anywhere you'd like to put each node in the result set. 564 565Arguments: 566 567* `tag`: A string or list of strings to act as a result key. The value for tag was the vertex the path was on at the time it reached "Tag" 568Example: 569```javascript 570// Start from all nodes, save them into start, follow any status links, and return the result. 571// Results are: 572// {"id": "cool_person", "start": "<bob>"}, 573// {"id": "cool_person", "start": "<dani>"}, 574// {"id": "cool_person", "start": "<greg>"}, 575// {"id": "smart_person", "start": "<emily>"}, 576// {"id": "smart_person", "start": "<greg>"} 577g.V().Tag("start").Out("<status>").All() 578``` 579 580 581### `path.TagArray(*)` 582 583TagArray is the same as ToArray, but instead of a list of top-level nodes, returns an Array of tag-to-string dictionaries, much as All would, except inside the JS environment. 584 585Example: 586```javascript 587// bobTags contains an Array of followers of bob (alice, charlie, dani). 588var bobTags = g.V("<bob>").Tag("name").In("<follows>").TagArray() 589// nameValue should be the string "<bob>" 590var nameValue = bobTags[0]["name"] 591``` 592 593 594### `path.TagValue()` 595 596TagValue is the same as TagArray, but limited to one result node. Returns a tag-to-string map. 597 598 599### `path.ToArray(*)` 600 601ToArray executes a query and returns the results at the end of the query path as an JS array. 602 603Example: 604```javascript 605// bobFollowers contains an Array of followers of bob (alice, charlie, dani). 606var bobFollowers = g.V("<bob>").In("<follows>").ToArray() 607``` 608 609 610### `path.ToValue()` 611 612ToValue is the same as ToArray, but limited to one result node. 613 614 615### `path.Union(path)` 616 617Union returns the combined paths of the two queries. 618 619Notice that it's per-path, not per-node. Once again, if multiple paths reach the same destination, 620they might have had different ways of getting there (and different tags). 621See also: `path.Tag()` 622 623Example: 624```javascript 625var cFollows = g.V("<charlie>").Out("<follows>") 626var dFollows = g.V("<dani>").Out("<follows>") 627// People followed by both charlie (bob and dani) and dani (bob and greg) -- returns bob (from charlie), dani, bob (from dani), and greg. 628cFollows.Union(dFollows).All() 629``` 630 631 632### `path.Unique()` 633 634Unique removes duplicate values from the path. 635 636 637