org.hypergraphdb

Class HGQuery<SearchResult>

java.lang.Object

org.hypergraphdb.HGQuery<SearchResult>

All Implemented Interfaces:

HGGraphHolder

Direct Known Subclasses:

AnalyzedQuery, ExpressionBasedQuery, IndexBasedQuery, IndexScanQuery, IntersectionQuery, KeyBasedQuery, PipeQuery, PredicateBasedFilter, PredicateBasedRAFilter, ResultMapQuery, TraversalBasedQuery, UnionQuery

public abstract class HGQuery<SearchResult>
extends Object
implements HGGraphHolder

The HGQuery class represents an arbitrary query to the HyperGraph database. Queries can be constructed out of HGQueryConditions via the static make method and then executed through the execute method.

Queries can be parametarized by a set of variables. You can get and set variables for a given query execution with the var(String) and var(String, Object) methods. Queries that used variables must be "pre-compiled" by first calling the make(Class, HyperGraph) method and then compile(HGQueryCondition) with the query condition right away. Multiple calls to compile(HGQueryCondition) on the same HGQuery instance are not advised.

To ensure thread-safety and allow a single HGQuery instance to be pre-compiled and reused from multiple threads, each thread of execution will get its own copy of the set of variables, cloned from the initial set that was created during the compilation of the query. This initial set of variables remains untouched by the var methods, but can be modified by the analogous #initialVar(String) and initialVar(String, Object).

Author:

Borislav Iordanov

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	HGQuery.hg This class serves as a namespace to a set of syntactically concise functions for constructing HyperGraph query conditions and performing HyperGraph queries.

Field Summary

Fields

Modifier and Type	Field and Description
protected VarContext	ctx
protected HyperGraph	graph

Constructor Summary

Constructors

Constructor and Description
HGQuery()

Method Summary

Methods

Modifier and Type	Method and Description
HGQuery<SearchResult>	compile(HGQueryCondition condition) Compile the passed in condition as this query object and return this.
abstract HGSearchResult<SearchResult>	execute() Execute the query and return the result set.
List<SearchResult>	findAll() Execute the query and accumulate the results in a List.
Set<SearchResult>	findInSet() Execute the query and accumulate the results in a Set.
SearchResult	findOne() Execute the query and return the first result, if any.
HyperGraph	getHyperGraph() Return the HyperGraph instance against which this query is executed.
<T> T	initialValue(String name)
<T> HGQuery<SearchResult>	initialVar(String name, T value)
static <SearchResult> HGQuery<SearchResult>	make(Class<SearchResult> type, HyperGraph graph) Create a new query with the given result type and bound to the given HyperGraph instance.
static <SearchResult> HGQuery<SearchResult>	make(HyperGraph graph, HGQueryCondition condition) Create a new query returning all atoms matching the given HGQueryCondition.
static <ResultType> HGQuery<ResultType>	NOP() A query that return the empty result set.
void	setHyperGraph(HyperGraph graph) Specify the HyperGraph instance against which this method is executed.
<T> Var<T>	var(String name) Return the thread-local copy of a given variable.
<T> HGQuery<SearchResult>	var(String name, T value) Modify the thread-local copy of a given variable.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

graph

protected HyperGraph graph

ctx

protected VarContext ctx

Constructor Detail

HGQuery

public HGQuery()

Method Detail

var

public <T> Var<T> var(String name)

Return the thread-local copy of a given variable. Use this method to obtain the value of a variable that will be used when executing this query in the current thread.

var

public <T> HGQuery<SearchResult> var(String name,
                            T value)

Modify the thread-local copy of a given variable. Use this method to modify the value of a variable that will be used when executing this query in the current thread.

initialValue

public <T> T initialValue(String name)

initialVar

public <T> HGQuery<SearchResult> initialVar(String name,
                                   T value)

NOP

public static <ResultType> HGQuery<ResultType> NOP()

A query that return the empty result set.

make

public static <SearchResult> HGQuery<SearchResult> make(HyperGraph graph,
                                        HGQueryCondition condition)

Create a new query returning all atoms matching the given HGQueryCondition. The query condition can be constructed directly from classes implementing the HGQueryCondition interface or by using the expression building static methods of the HGQuery.hg class nested here.

The result of this method can be executed repeatedly. In place where performance is critical and a given query is executed often, it is beneficial to construct it before hand and reuse. The performance gain will depend on how complex the condition is. Constructing a query involves creating an execution plan based on indices etc. Therefore, a trivial condition that only constraints the type of the atoms doesn't take much time to translate into a query, while a more complex one involving some structural pattern will burn valuable extra cycles in building a query plan.

IMPORTANT NOTE: This method does not support variables in the query condition. If your condition contains variables created by one of the var(String) methods, please use the make(Class, HyperGraph) to create the query and then invoke its compile(HGQueryCondition) method to specify the condition.

Type Parameters:

SearchResult - The type of the return result.

Parameters:

graph - The HyperGraph instance against which the query will be executed.

condition - The HGQueryCondition specifying which atoms to return from the graph.

Returns:

An executable HGQuery object.

compile

public HGQuery<SearchResult> compile(HGQueryCondition condition)

Compile the passed in condition as this query object and return this.

make

public static <SearchResult> HGQuery<SearchResult> make(Class<SearchResult> type,
                                        HyperGraph graph)

Create a new query with the given result type and bound to the given HyperGraph instance.

Parameters:

type - The type of the result objects. This parameter is only necessary to avoid type casts.

graph - The database instance.

Returns:

A new, empty HGQuery object. The returned query doesn't have a condition yet. Please call its compile(HGQueryCondition) method in order to specify a condition.

getHyperGraph

public HyperGraph getHyperGraph()

Return the HyperGraph instance against which this query is executed.

setHyperGraph

public void setHyperGraph(HyperGraph graph)

Specify the HyperGraph instance against which this method is executed. This method is intended mostly for internal use. A HGQuery object is normally constructed by using information from a specific graph instance (e.g. available indices). Therefore, changing the graph instance and executing it again may fail if the metadata used in building the query differs between the two graphs.

Specified by:

setHyperGraph in interface HGGraphHolder

execute

public abstract HGSearchResult<SearchResult> execute()

Execute the query and return the result set. Note that queries are lazily executed so that results are actually obtained when one iterates (using the next and prev of the returned object).

findOne

public SearchResult findOne()

Execute the query and return the first result, if any. Otherwise return null.

findAll

public List<SearchResult> findAll()

Execute the query and accumulate the results in a List.

findInSet

public Set<SearchResult> findInSet()

Execute the query and accumulate the results in a Set.