Cayley Graph Database

The Cayley UI provides several views and actions accessible via the sidebar to interact with your graph data:

• Run Query: Executes the current query.
• Gizmo: A dropdown to select your query language. Cayley supports two languages: GizmoAPI and MQL.
• Query: A request/response editor for the selected query language.
• Query Shape: Provides a visualization of the structure/shape of the final query without executing it.
• Visualize: Runs a query and generates a sigmajs graph view of the results (requires specific tagging).
• Write: An interface for adding or removing individual quads or quad files.
• Documentation: Access to the project documentation.

In the context of a graph.QuadStore, a token is a graph.Value. It is an opaque identifier that the backing store uses to represent a quad or a node. The specific implementation of a token depends on the backend:

• Traditional graph databases: Might use int64 (e.g., GUIDs).
• Direct graph implementations: Might use pointers to structs or the quads themselves.

Base iterators pass these tokens around to identify elements within the graph.

Reification is the process of treating a relationship (an edge) as an entity (a node).

In graph modeling, you use reification when you need to add additional information (metadata) to a relationship. Instead of a direct link between two nodes, you create a new node that represents the statement itself, which then points to the subject and object. This effectively creates a 'metagraph' on top of your existing graph.

A Shape is an abstract representation of a query. It sits in the query hierarchy between Paths (higher level) and Iterators (lower level).

Key characteristics:

• It describes the structure of a query tree.
• It allows for high-level operations such as traversing inbound/outbound predicates or finding unions and intersections.
• Its primary purpose is to be transformed into a tree of Iterators via BuildIterator, which performs the actual mechanical processing of quads to find results.
• It supports backend-agnostic optimizations via the Optimize method.

type Shape interface {
    BuildIterator(qs graph.QuadStore) graph.Iterator
    Optimize(ctx context.Context, r Optimizer) (Shape, bool)
}

A Morphism is a prepared path chain that can be applied to other queries using .follow(path) or .followR(path). This allows you to define complex traversal patterns (like "friend of a friend") once and reuse them.

• .follow(path): Applies the morphism chain in the forward direction.
• .followR(path): Applies the morphism chain in the reverse direction (flips "In" and "Out").
• .followRecursive(path): Applies the morphism chain recursively, returning all encountered nodes.

var friendOfFriend = g
  .Morphism()
  .out("<follows>")
  .out("<follows>");

// Use the morphism to find friends of friends of Charlie
g.V("<charlie>")
  .follow(friendOfFriend)
  .all();

Gizmo is a query language for Cayley inspired by Gremlin/TinkerPop. It uses a JavaScript-like syntax to traverse and filter named graphs.

Key concepts:

• .v(): Used to select a Vertex (node). For example, g.V() returns a list of all vertices in the graph.
• Inbound/Outbound Predicates: Refers to the direction of a relation. If A follows B, follows is an outbound predicate for A and an inbound predicate for B. In Gizmo, you can traverse using .out("predicate") or .in("predicate").

// Example: Find names of projects created by two friends
g.V().match(
  as("a").out("knows").as("b"),
  as("a").out("created").as("c"),
  as("b").out("created").as("c"),
  as("c").in("created").count().is(2)).
    select("c").by("name")

In raw mode (the default), Cayley streams selected quads directly to Gephi. This mode is best for visualizing small subgraphs or graphs without metadata (like types and properties). If you use this mode on graphs with many common types, you will see many quads pointing to nodes describing those types.

Parameters:

• mode=raw - Sets the streaming mode.
• limit - Maximal number of quads returned (default 10000; use -1 for no limit).
• sub - Filter quads by Subject.
• pred - Filter quads by Predicate.
• obj - Filter quads by Object.
• label - Filter quads by Label.

/* Example: All quads */
/gephi/gs?mode=raw&pred=<follows>&limit=-1

/* Example: Links from <bob> via <follows> or <status> */
/gephi/gs?mode=raw&sub=<bob>&pred=<follows>,<status>&limit=-1

Graph queries in Cayley are represented as a tree of iterators (implementing graph.Iterator).

• An iterator is a stand-in for a set of items matching a specific part of the graph.
• Subiterators are the branches and leaves of the iterator tree. Evaluation occurs by repeatedly calling Next() on the root iterator.

Key Iterator Types

HasA Iterator

An iterator that takes a subiterator of links and acts as an iterator of nodes in a specific direction. It effectively says a link "HasA" a certain component (e.g., a link has a subject).

LinksTo Iterator

An iterator that takes a subiterator of nodes and returns the links that "link to" those nodes in a given direction. It is the dual of the HasA iterator.

The graph object (aliased as g) is the primary entry point for the Gizmo API. It is used to generate query objects which are compiled into a Go iterator tree for execution. All queries originate from this object.

// 'g' is the common alias for 'graph'
var query = g.V().out("friend");