org.apache.jackrabbit.commons.query
Class GQL

java.lang.Object
  org.apache.jackrabbit.commons.query.GQL

public final class GQL
extends Object

GQL is a simple fulltext query language, which supports field prefixes similar to Lucene or Google queries.

GQL basically consists of a list of query terms that are optionally prefixed with a property name. E.g.: title:jackrabbit. When a property prefix is omitted, GQL will perform a fulltext search on all indexed properties of a node. There are a number of pseudo properties that have special meaning:

• path: only search nodes below this path. If you specify more than one term with a path prefix, only the last one will be considered.
• type: only return nodes of the given node types. This includes primary as well as mixin types. You may specify multiple comma separated node types. GQL will return nodes that are of any of the specified types.
• order: order the result by the given properties. You may specify multiple comma separated property names. To order the result in descending order simply prefix the property name with a minus. E.g.: order:-name. Using a plus sign will return the result in ascending order, which is also the default.
• limit: limits the number of results using an interval. E.g.: limit:10..20 Please note that the interval is zero based, start is inclusive and end is exclusive. You may also specify an open interval: limit:10.. or limit:..20 If the dots are omitted and only one value is specified GQL will return at most this number of results. E.g. limit:10 (will return the first 10 results)
• name: a constraint on the name of the returned nodes. The following wild cards are allowed: '*', matching any character sequence of length 0..n; '?', matching any single character.

Property name

Instead of a property name you may also specify a relative path to a property. E.g.: "jcr:content/jcr:mimeType":text/plain

Double quotes

The property name as well as the value may enclosed in double quotes. For certain use cases this is required. E.g. if you want to search for a phrase: title:"apache jackrabbit". Similarly you need to enclose the property name if it contains a colon: "jcr:title":apache, otherwise the first colon is interpreted as the separator between the property name and the value. This also means that a value that contains a colon does not need to be enclosed in double quotes.

Auto prefixes

When a property, node or node type name does not have a namespace prefix GQL will guess the prefix by looking up item and node type definitions in the node type manager. If it finds a definition with a local name that matches it will automatically assign the prefix that is in the definition. This means that you can write: 'type:file' and GQL will return nodes that are of node type nt:file. Similarly you can write: order:lastModified and your result nodes will be sorted by their jcr:lastModified property value.

Common path prefix

For certain queries it is useful to specify a common path prefix for the GQL query statement. See execute(String, Session, String). E.g. if you are searching for file nodes with matches in their resource node. The common path prefix is prepended to every term (except to pseudo properties) before the query is executed. This means you can write: 'type:file jackrabbit' and call execute with three parameters, where the third parameter is jcr:content. GQL will return nt:file nodes with jcr:content nodes that contain matches for jackrabbit.

Excerpts

To get an excerpt for the current row in the result set simply call Row.getValue("rep:excerpt()");. Please note that this is feature is Jackrabbit specific and will not work with other implementations!

Parser callbacks

You can get callbacks for each field and query term pair using the method parse(String, Session, ParserCallback). This may be useful when you want to do some transformation on the GQL before it is actually executed.

Nested Class Summary

static interface	GQL.Filter Defines a filter for query result rows.
static interface	GQL.ParserCallback Defines a callback interface that may be implemented by client code to get a callback for each GQL term that is parsed.

Method Summary

static RowIterator	execute(String statement, Session session) Executes the GQL query and returns the result as a row iterator.
static RowIterator	execute(String statement, Session session, String commonPathPrefix) Executes the GQL query and returns the result as a row iterator.
static RowIterator	execute(String statement, Session session, String commonPathPrefix, GQL.Filter filter) Executes the GQL query and returns the result as a row iterator.
static void	parse(String statement, Session session, GQL.ParserCallback callback) Parses the given statement and generates callbacks for each GQL term parsed.

Methods inherited from class java.lang.Object

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

Method Detail

execute

public static RowIterator execute(String statement,
                                  Session session)

Executes the GQL query and returns the result as a row iterator.

Parameters:

statement - the GQL query.

session - the session that will execute the query.

Returns:

the result.

execute

public static RowIterator execute(String statement,
                                  Session session,
                                  String commonPathPrefix)

Executes the GQL query and returns the result as a row iterator.

Parameters:

statement - the GQL query.

session - the session that will execute the query.

commonPathPrefix - a common path prefix for the GQL query.

Returns:

the result.

execute

public static RowIterator execute(String statement,
                                  Session session,
                                  String commonPathPrefix,
                                  GQL.Filter filter)

Executes the GQL query and returns the result as a row iterator.

Parameters:

statement - the GQL query.

session - the session that will execute the query.

commonPathPrefix - a common path prefix for the GQL query.

filter - an optional filter that may include/exclude result rows.

Returns:

the result.

parse

public static void parse(String statement,
                         Session session,
                         GQL.ParserCallback callback)
                  throws RepositoryException

Parses the given statement and generates callbacks for each GQL term parsed.

Parameters:

statement - the GQL statement.

session - the current session to resolve namespace prefixes.

callback - the callback handler.

Throws:

RepositoryException - if an error occurs while parsing.