The Thinkmap Graph Query language is designed to make querying a graph straightforward and easy.
Queries are specified as a JavaScript object, and then compiled using the graph.query(q) method (where q is the query), which returns the compiled query. Compiled queries are optimized by the query planner and can be saved and executed multiple times.
A compiled query is then typically executed and then returns a ResultSet,
which is a subclass of thinkmap.async.Future that will
return results as the query executes asynchronously. Each result
the query produces is a TraversalPath, which represents a path through the input
graph that matches the query.
When a ResultSet completes, it produces a final result graph, which contains the union of all the resulting paths that were taken through the input graph while executing the query.
Let's look at an example:
// do a graph query for "Tom Cruise" and log the results
graph.query({$search:'Tom Cruise'})
.execute()
.onresult(function( path ) {
console.log( 'got result:'+ path );
})
.oncomplete(function( resultGraph ) {
console.log( 'complete graph', resultGraph.toArray() );
});
The execute method on Queries can also take an enitity, or collection of entities. This limits the starting point for the query to just the input entities.
// assume that the variable 'myNode' points to a node in the graph
// this query will return all the nodes and edges directly connected to 'myNode'
graph.query(['node','edge','node']) // query for nodes connected to nodes
.execute( myNode ) // start the query at myNode
.oncomplete(function( resultGraph ) {
console.log( resultGraph.toArray() );
});
The simplest query is just a string, which will match all entities
of that type. Passing a string is really just a shortcut for using
the $t type operator.
graph.query('node') // matches all nodes
graph.query({$t:'node'}) // also matches all nodes, equivalent to above
graph.query('edge') // matches all edges
graph.query('movie') // matches all movies
You may also pass an object as a condition to a query. This will query for entities that have a "data" property that matches the condition.
// create the type 'employee' which extends node
graph.createType('employee','node');
// create an employee
graph.add(graph.createNode({firstname:'John',lastname:'Smith'},'employee'))
.execute();
// query for the node created above
graph.query({lastname:'Smith'}).execute();
// sometimes it's useful to combine the type operator and property conditions
graph.query({$t:'employee',lastname:'Smith'}).execute();
Query paths are used when you want to query for things that are connected in the graph. Query Paths are specified as Arrays.
//query for nodes connected to startNode
graph.query(['node','edge','node']).execute(startNode);
//query for movies connected to the actor Kevin Bacon
graph.query([{$search:'Kevin Bacon', $t:'actor'},'edge','movie']).execute();
Query paths can be specified with an optional repeat to match paths that repeat or have an indeterminate length. Repeat notation is specified by adding an additional member at the end of the path array, which is an array of two numbers. The first number represents the minimum number of times that the path must occur, and the second number represents the maximum number of times that the path can occur. To specify an infinite number for the maximum, use "-1". Also, as you can see below, query paths can be nested.
//query for people who are connected to a company, or not
graph.query(['person',['edge','company',[0,1]]]);
// find all people within 3 degrees of Kevin Bacon
graph.query([ {$search:'Kevin Bacon', $t:'actor'},
['edge', 'movie', 'edge', 'person', [1,3] ]
]).execute();
You can use the $choice operator to represent a "fork"
in the road. The query will traverse all the possible paths specified
in the $choice
// find all the actors and genres associated with startMovie
graph.query({$choice:[
['movie','edge','actor'],
['movie','edge','genre']
]}).execute( startMovie );
Entity operators are used to evaluate entities in the path. Note that if you combine multiple operators in a single condition, the result is a logical AND of those conditions.
| Operator | Description |
|---|---|
$search |
Performs a full-text search on an entity. The search operator
will look at all properties of an entity when doing a search
(unless a full-text index has been created that restricts the
search domain). Search supports the "*" and "?" wildcards, as
well as property specific search with the ":" field operator.
e.g: Search for all entities starting with "smit" {$search:'smit*'} e.g: Search the title field for "breakfast" {$search:'title:breakfast'} Phrases placed in quotes will be searched for as literals. e.g: {$search:"title:'my bodyguard'"} |
$t |
The $t operator tests the type of an entity. e.g: search movies that contain
the word john:
{$search:'john',$t:'movie'}
|
$or |
Performs a logical OR between two conditions. e.g: {$or:[ { lastname:'Smith' }, { 'lastname':'Jones' } ]}
|
$and |
Performs a logical AND between two conditions. e.g: {$and:[ {lastname:'Smith'}, {'firstname':'John'} ]}Typically you don't use this operator, because this is equivalent: { lastname:'Smith', 'firstname':'John' }
|
$not |
Performs a logical NOT of a condition. e.g: {$not: {lastname:'Smith'} }
|
$fn |
Allows you to use a JavaScript function as a condition in a query.
The function will be called with the Entity as the "this" argument
and the Entity's data as the first argument. E.g: find all the nodes connected to entities with a data property named value that is set to true: ['node','edge', { $fn:function(data,path,traversal) { return data.value; } } ]
|
$inresult |
Allows you to determine if the entity being considered was
already included in the result graph. This is useful
in optimizing queries with repeats that are traversing
through highly connected graphs.
e.g: find all paths through a graph, but don't consider edges that have already been included in the ResultSet graph. ['node',[{$t:'edge', $inresult:false},'node',[0,-1]]
|
$visited |
$visited is like $inresult, but it is more broad. It
allows you to determine if the entity being considered was
already considered earlier in the traversal. This includes
entities in paths that were considered for inclusion, but
were rejected because they failed to meet a subsequent
condition. $visited is useful
in optimizing queries with repeats that are traversing
through highly connected graphs.
e.g: find all paths through a graph, but don't consider edges that have already been explored by the query. ['node',[{$t:'edge', $visited:false},'node',[0,-1]]
|
$label |
Applies an output label to a TraversalPath. Output labels can be used by users of the Professional Edition to dynamically search and replace portions of a traversal while a query is executing. |
Property operators are used to evaluate properites on the data associated with entities.
| Operator | Description |
|---|---|
$gt |
Tests if a property is greater than a value. e.g: {cost:{$gt:1000}}
|
$gte |
Tests if a property is greater than or equal to a value. e.g: {cost:{$gte:1000}}
|
$lt |
Tests if a property is less than a value. e.g: {cost:{$lt:1000}}e.g: {cost:{$lt:1000,$gt:500}} |
$lte |
Tests if a property is less than or equal to a value. e.g: {cost:{$lte:1000}}
|
$eq |
Tests if a property is equal to a value. Mostly, this is
operator is included for completeness, since it is not necessary to use in
most cases. e.g: {name:{$eq:'John'}}equivalent to: {name:'John'}
|
$neq |
Tests if a property is not equal to a value. e.g: {name:{$neq:'John'}}
|