Technology
Learn
Products
Blog
Java API Help
Page Contents
- Basic Principles.
- Important Concepts and Terms.
- Installation.
- Graph API.
- Bounds Language.
- Bounds API.
- Job Broker API.
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
- Make sure you have the Java SE6 or newer runtime (JRE) installed.
- Download the latest GraphBaseAgility.zip file and unpack it.
- Add GraphBaseProxy.jar and the lib library to your application's ClassPath.
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 | ||
| Token | Name | Description |
| { | BOUNDS_OPEN | Opening Bounds encapsulation token. |
| } | BOUNDS_CLOSE | Closing Bounds encapsulation token. |
| ( | OPEN_BRACKET | Encapsulates a filter expression and overrides evaluation order. |
| ) | CLOSE_BRACKET | Encapsulates a filter expression and overrides evaluation order. |
| from | BOUNDS_FROM | Results will be taken FROM the following Bounds encapsulation. |
| pass | BOUNDS_PASS | PASS results of the following filter expression on. |
| to | BOUNDS_TO | Pass 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 | ||
| Token | Name | Description |
| all | ALL_ARCS | All of this vertex's incident arcs. |
| [ | ALL_CONTAINED_BY_THIS | Arcs 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_THIS | Arcs 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_THIS | Arcs 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_THIS | Arcs 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_IS | Operand is an integer. Filter returns arcs of the operand's type. |
| T!= | TYPE_IS_NOT | Operand 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 | ||
| Token | Name | Description |
| H= | EQUAL_TO | Incident arcs where hint equals operand. |
| H!= | NOT_EQUAL_TO | Incident arcs where hint does not equal operand. |
| H> | GREATER_THAN | Arcs where hint is greater than operand. * |
| H>= | NOT_LESS_THAN | Arcs where hint is greater than or equal to operand. * |
| H< | LESS_THAN | Arcs where hint is less than operand. * |
| H<= | NOT_GREATER_THAN | Arcs 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 | ||
| Token | Name | Description |
| and | AND | Returns arcs that are common to both expressions. |
| or | OR | Returns arcs that are found in the results of either expression. |
| xor | XOR | Returns arcs that are found in the results of either expression but not in both. |
| andnot | AND_NOT | Returns 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 | ||
| Token | Name | Description |
| * | REACH | Applies the expression to the specified number of traversals. e.g *3 Default is 1. |
| # | RESULT_RANGE | Returns 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 | ||
| Token | Name | Description |
| AND | AND | Returns a graph of vertices that are common to the results of both Bounds objects. |
| XAND | XAND | As for AND, but eXtended to include the vertices used to traverse to the found common vertices. |
| OR | OR | Returns a graph of vertices that are found in the results of either Bounds objects. |
| XOR | XOR | Returns a graph of vertices that are found in the results of either Bounds objects but not in both. |
| ANDNOT | AND_NOT | Returns a graph of vertices that are found in the results of the first Bounds object, but not in the second. |
@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.