The Thinkmap Graph Query Language

The Thinkmap Graph Query language is designed to make querying a graph straightforward and easy.

Typical Use

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() );
       });

Query Syntax

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

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();

Repeat Notation

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();

The $choice operator

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

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

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'}}