The GraphBase Console is the first tool you'll see after launching. It's used to...

  • Connect to a GraphBase Node.
  • Launch the GraphPad, BoundsPad and Navigator tools.
  • See messages about notable GraphBase events.


You can work locally with GraphPad and BoundsPad using JSON and XML files - but to use Navigator you must be connected to a remote GraphBase Cloud Node. You'll need to...

  • Load a Credentials graph. You'll receive a default UserCredentials.json file as part of your download.
  • Connect using the NodeID and URI of the GraphBase Node you want to connect to.

The GraphBase GraphPad is visual tool that allows you to create and manipulate GSF (Graph Simple Form) graphs.

The first thing you'll see when clicking up an instance of GraphPad is a "New Graph" tab. This new graph has a single vertex with a payload value of "new". Every time you attach a new vertex in GraphPad this is what you'll see. Edit this default payload in the text-box to the upper right. If the vertex doesn't need a payload, just delete the text.

In this screenshot, our first vertex is "Amy" and we're attaching six of her friends. [right-mouse-click] brings up a popup version of the "Edit" menu.



It may seem odd that the graph in the above screenshot is represented as a tree. Graph structures can quickly become a visual mess as you'll see in later images. Flattening them into trees usually makes it easier to see and comprehend the data that is attached to each vertex. This flattening process usually results in several vertices being represented in the tree multiple times. These "dupes" are always leaves and are flagged with a small "back-into-the-tree" arrow.

The three screens below show how a classic collabsible tree structure can make it easier to focus on a key vertex and its connections.



You'll also notice a couple of unusual symbols. We've borrowed these from predicate logic. "∀" is the Universal Quantifier (UQ) - effectively it means "this vertex represents all of these". "∃" is the Existentail Quantifier (EQ) - it means "this vertex represents some of these".

An arrow between two vertices indicates that the arc between them is directed. Direction indicates a simple subsumption or containment relationship, where a vertex either "has" or "is of" its connected neighbour.

See Graph Simple Form for a more detailed discussion on quantifiers, containment and other features of the graph structures used by these tools.



In the image above, a second framework has been added to the AmyFriends graph. The two black UQ vertices at the lower left are from the Universal Semantic Framework. Multiple frameworks or "schemas" are a powerful tool for managing graph complexity. Find out more in Understanding Frameworks.

GraphPad Tips

Use the View Buttons to explore your graph from varying perspectives...


  • Sets the graph focus to the selected vertex.
  • Expands the graph from your focus using a breadth-first traversal.
  • Expands the graph from your focus using a depth-first traversal.
  • Produces an automatic layout of your graph.
  • Produces a radial layout of your graph.
  • A visual update is sometimes required after significant changes to your graph.

Several keyboard/mouse actions can be used to speed graph-manipulation...


  • [right-mouse-click] brings up a popup version of the "Edit" menu.
  • [mouse-wheel-scroll] zooms the Auto View or Radial View graph window.
  • [Ctrl-drag] from one vertex to another to connect them with a new arc.

The GraphBase BoundsPad is a visual tool that allows you to create and modify a GraphBase query. This query is refered to as a Bounds object.



A Bounds object contains one or more simple expressions that define the scope of your graph query. Objects can be created using the GraphBase API, but they are often best worked-with using a Bounds Language statement. BoundsPad lets you work with both Bounds objects and Bounds Language statements. For more detail - including examples - see API Help.

BoundsPad Tips

  • Paste Bounds Language statements into the BoundsPad Expression window to check them.
  • To execute any Bounds query, drag it from the left window into Navigator or a GraphPad graph.
  • Dragging also works for inner Bounds.

The GraphBase Navigator lets you open one or more windows into a connected GraphBase Node.

Navigator is a version of GraphPad that displays non-editable views of a super-graph. Your super-graph is the single large graph that contains all of your GraphBase data. It can reside on multiple, geographically-distributed GraphBase Nodes and can be navigated by connecting to any one of those Nodes.A Navigator view window is created by...

  • Dragging in a Bounds query object from BoundsPad or
  • Using the Navigator Search box.


The screen-shot above is a "dbms"-searched view of the Universal Semantic Framework mentioned above.

Navigator Tips

  • Copy a graph from GraphPad and use Navigator to deliver it directly to a GraphBase Node.
  • Copy a view graph from Navigator and paste it into GraphPad for editing.
  • To traverse beyond your graph view, select an edge vertex and create a new view centered on that vertex.

When you work with GraphBase, you work with graphs. GraphBase stores data as one large (usually connected) graph. Data is delivered to GraphBase as small graphs, a query to GraphBase returns data as a graph and the smallest transactional unit is a graph. GraphBase also contains visual tools that let you think about, manipulate, and store your data - as graphs.

  • Graph - a graph structured in Graph Simple Form.
  • Vertex - a vertex (or node) within a Graph.
  • Arc - an arc (or edge) connecting vertices within a Graph.
  • VSet - a Vertex Set. A package which encapsulates a Vertex and its incident Arcs.
  • Super-Graph - a single Graph maintained by one or more GraphBase Nodes.
  • Concept Space - the aggregated content of all GraphBase Super-Graphs.
  • GlobalID - a 128-bit identifier used primarily to identify a vertex within Concept Space.
  • Surrogate GlobalID - a to-be-replaced GlobalID used when attaching new vertices to a graph.
  • Node - a GraphBase server application which stores sub-graphs and processes Jobs.
  • Proxy Node - a Node with limited functionality that relies on a full Node for storage and processing.
  • Bounds - a query object used to extract a sub-graph from a graph, or from a GraphBase Node.
  • Bounds Language - text that can be parsed to create a Bounds object.
  • Job - the GraphBase unit of work. Used for query, delivery and operations upon one or more Graphs.
  • Job Broker - an Interface which accepts a Job and returns its result.
  • Credentials - a Graph, submitted with a Job, that allows access to parts of a Super-Graph.
  • Handler - a snippet of Java that allows manipulation of graphs within a Job.
  • Agent - a snippet of Java that may be embedded within a Super-Graph Vertex.
  • Package Runner - a class used for configuring package-specific parameters and injecting dependencies

The Graph class sample methods below are cut from the JavaDoc that comes with GraphBase Agility.


Graph Sample Methods
static GraphnewSingleVertexGraph(GlobalID vertexID, int vertexType, java, lang, String vertexPayload)Simplest factory method for creating a new Graph with a single vertex.
GraphnewAddedVertexGraph(VSet vSet, GlobalID farVertexID, int arcType)Return a copy of this Graph with vSet added and attached to farVertexID.
Graphand(Graph otherGraph)Return a graph of vertices and arcs that are common to this and otherGraph.
GraphnewestOr(Graph otherGraph)Return a graph of vertices and arcs found in either this or otherGraph.
GraphsubGraph(Bounds bounds)Applies a Bounds query object to this graph and returns a sub-graph.
GlobalID[]getLeafIDs()Return an array of vertexIDs for those vSets that CONTAIN nothing.
< T > java.util.ListasObjectsList(GlobalID[] focusVertexIDs, T templateObject, java.util.Map translationMap)Return a List of templateObject objects built using this graph.
booleansaveAsJsonFile(java.io.File file)Save Graph as a GraphBase Standard JSON file.

The class comes with a wealth of functionality to let you create, manipulate, analyse and compare Graphs.

  • Create a new Graph using newSingleVertexGraph().
  • Add to it using newAddedVertexGraph().
  • Compare it with another Graph using and().
  • Merge it with another Graph using or().
  • Query it using subGraph().
  • Extract some useful features using getLeafIDs().
  • Convert it directly to useful Java Objects using asObjectsList().
  • Save it for later use or for viewing in GraphPad using saveAsJsonFile().

Download GraphSampleMethodsJava.txt to see these methods applied in a simple program.

A Bounds object is query that, when applied to a local Graph, or to a Super-Graph, returns a sub-graph. A Bounds query describes a set of simultaneous graph traversals together with the operations applied to, and between, those traversals. Each Bounds object contains...

  • A filter expression - to be applied to a vertex's incident arc.
  • An optional fromBounds object - vertices that the filter expression will operate on.
  • An integer reach - the number of consecutive traversals that will use the expression.
  • Optional range cursors - to select a subset of the vertices normally returned.
  • An optional toBounds object - that will receive vertices returned by this Bounds.
  • Optional encapsulatedBounds objects - upon which extended boolean operations may be performed. These may also receive vertices returned by this Bounds.

The filter epression is composed of one or more simple filters - called ExpressionFragments - that are applied to either the arc type or the arc hint. The easiest way to work with these is to use Bounds Language.

Let's start by introducing the features, or tokens, used by the language. First up, some basic structural tokens that encapsulate and control evaluation order.


Structural Tokens
TokenNameDescription
{BOUNDS_OPENOpening Bounds encapsulation token.
}BOUNDS_CLOSEClosing Bounds encapsulation token.
(OPEN_BRACKETEncapsulates a filter expression and overrides evaluation order.
)CLOSE_BRACKETEncapsulates a filter expression and overrides evaluation order.
fromBOUNDS_FROMResults will be taken FROM the following Bounds encapsulation.
passBOUNDS_PASSPASS results of the following filter expression on.
toBOUNDS_TOPass resulting vertices TO the following encapsulation.

Tokens in this next block are used to filter on the type of a vertex's incident arcs.


Arc Type Filter Operations
TokenNameDescription
allALL_ARCSAll of this vertex's incident arcs.
[ALL_CONTAINED_BY_THISArcs with a type that implies far vertices are contained by this one. For GSF this means types HAS_A, MUTUAL_HAS and SAME_AS.
]ALL_CONTAINING_THISArcs with a type that implies that far vertices contain this one. For GSF this means types IS_OF, MUTUAL_HAS and SAME_AS.
![ALL_NOT_CONTAINED_BY_THISArcs with a type that implies far vertices are not contained by this one. For GSF this means types IS_OF and SAME_AS.
!]ALL_NOT_CONTAINING_THISArcs with a type that implies that far vertices do no contain this one. For GSF this means types HAS_A and SAME_AS.
T=TYPE_ISOperand is an integer. Filter returns arcs of the operand's type.
T!=TYPE_IS_NOTOperand is an integer. Filter returns arcs NOT of the operand's type.

Some examples...

{ from {@1~51397} pass All} - a graph of all vertices adjacent to a vertex of known ID.
{ from {@1~51397} pass [ } - vertices contained by this vertex.

Each arc may carry an heuristic or hint as to the contents of its pointed-to vertex. This feature allows arcs to behave as an adjacent index and it dramatically-improves query speed for graphs with known structure. Tokens for filtering using hints are these.


Arc Hint Filter Operations
TokenNameDescription
H=EQUAL_TOIncident arcs where hint equals operand.
H!=NOT_EQUAL_TOIncident arcs where hint does not equal operand.
H>GREATER_THANArcs where hint is greater than operand. *
H>=NOT_LESS_THANArcs where hint is greater than or equal to operand. *
H<LESS_THANArcs where hint is less than operand. *
H<=NOT_GREATER_THANArcs where hint is less than or equal to operand. *
* String hints are evaluated in UTF-8 order.

Some examples...

{ from {@1~1} pass H='name' to { pass H='Fred' }} - framework and arc hints as an index.
{ from {@1~1} pass H='age' to { pass H>18 }} - framework and arc hints as a range query.

Filter operations can be further refined by applying boolean operations to two or more expressions.


Expression Association Operations - In Operation Precedence Order
TokenNameDescription
andANDReturns arcs that are common to both expressions.
orORReturns arcs that are found in the results of either expression.
xorXORReturns arcs that are found in the results of either expression but not in both.
andnotAND_NOTReturns arcs that are found in the results of the first expression, but not in the second
Use ( encapsulating brackets ) to ensure that evaluation order is as expected.

Extending the above examples...

{ from {@1~1} pass H='name' to { pass H>'Fred' and H<'Free' }} - get Freddy, Frederick and other derivations.
{ from {@1~1} pass H='age' to { pass H>=18 and H<40 }} - over 18, but under 40.


Expression Modifiers
TokenNameDescription
*REACHApplies the expression to the specified number of traversals. e.g *3 Default is 1.
#RESULT_RANGEReturns the range of expression results specified by the modifier indices. e.g. #1-100

Extending an earlier example above to perform three traversals using the same expression...

{ from {@1~51397} pass [ *3 } - applies the containment expression to successive results.

Similar operations can also be applied between evaluated Bounds objects. The result of a Bounds Association Operation is a complete Graph.


Bounds Association Operations - In Operation Precedence Order
TokenNameDescription
ANDANDReturns a graph of vertices that are common to the results of both Bounds objects.
XANDXANDAs for AND, but eXtended to include the vertices used to traverse to the found common vertices.
ORORReturns a graph of vertices that are found in the results of either Bounds objects.
XORXORReturns a graph of vertices that are found in the results of either Bounds objects but not in both.
ANDNOTAND_NOTReturns a graph of vertices that are found in the results of the first Bounds object, but not in the second.

Putting it all together...

@1~51397 is the Semantic Framework conceptID for "actor".
See http://graphbase.net/semantic/@1~51397. This Bounds query returns a graph of Actors, 18 to 40 years of age. Use of the XAND operator ensures that the returned graph can be further explored using the same frameworks.

Bounds Language is the easiest way to create a new or simple Bounds query, but the Bounds API can be useful for complex queries or for the creation of Bounds queries that conform to regularly-used patterns.

  • newCompoundBounds() lets you collect in bulk by applying a simple template.
  • newMultipleVertexIDAttachedBounds() for a graph of what multiple vertices have in common.
  • newMultipleVertexIDContainmentBounds() get the intersection of many traversal paths.
  • vertexIDReplaced() makes it easy to program using a single template pattern.

Once you've connected to a GraphBase Node, you can query a super-graph, add to it or manipulate it via a Job Broker.

  • Use issueAndWaitForJob() for most jobs issued against a single Node.
  • Use issueJob() if your application can come back for its results.
  • Use hasCompleted() to check on the progress of long-running or distributed jobs.
  • Use issueAndForgetJob() for automated super-graph manipulations.