Java API Help

Page Contents

Basic Principles

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.

Important Concepts and Terms

  • 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

Installation

Graph API

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

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   saveAsXMLFile().

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

Bounds Language

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...

  • { pass {@1~51397} to [ *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 API

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.

Job Broker API

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.

Please feel free to use the Comments section below if there's anything you'd like to see addressed in this Help document.


Comments

simple. elegant. powerful