public final class GQL
extends java.lang.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.
Escaping
To imply double-quotes("), backslash(\), and colon(:) literally you can
escape them with a backslash. E.g. similar to example above in quoting for colon,
"jcr:title":apache
is equiavalent to jcr\:title:apache.
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.
Modifier and Type | Class and Description |
---|---|
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.
|
Modifier and Type | Method and Description |
---|---|
static RowIterator |
execute(java.lang.String statement,
Session session)
Executes the GQL query and returns the result as a row iterator.
|
static RowIterator |
execute(java.lang.String statement,
Session session,
java.lang.String commonPathPrefix)
Executes the GQL query and returns the result as a row iterator.
|
static RowIterator |
execute(java.lang.String statement,
Session session,
java.lang.String commonPathPrefix,
GQL.Filter filter)
Executes the GQL query and returns the result as a row iterator.
|
static RowIterator |
executeXPath(java.lang.String jcrQuery,
java.lang.String jcrQueryLanguage,
Session session,
java.lang.String commonPathPrefix,
GQL.Filter filter)
Executes the GQL query and returns the result as a row iterator.
|
static void |
parse(java.lang.String statement,
Session session,
GQL.ParserCallback callback)
Parses the given
statement and generates callbacks for each
GQL term parsed. |
static java.lang.String |
translateToXPath(java.lang.String statement,
Session session,
java.lang.String commonPathPrefix)
Translate the GQL query to XPath.
|
public static RowIterator execute(java.lang.String statement, Session session)
statement
- the GQL query.session
- the session that will execute the query.public static RowIterator execute(java.lang.String statement, Session session, java.lang.String commonPathPrefix)
statement
- the GQL query.session
- the session that will execute the query.commonPathPrefix
- a common path prefix for the GQL query.public static RowIterator execute(java.lang.String statement, Session session, java.lang.String commonPathPrefix, GQL.Filter filter)
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.public static RowIterator executeXPath(java.lang.String jcrQuery, java.lang.String jcrQueryLanguage, Session session, java.lang.String commonPathPrefix, GQL.Filter filter)
jcrQuery
- the native JCR query.jcrQueryLanguage
- the JCR query languagesession
- 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.public static java.lang.String translateToXPath(java.lang.String statement, Session session, java.lang.String commonPathPrefix) throws RepositoryException
statement
- the GQL query.session
- the session that will execute the query.commonPathPrefix
- a common path prefix for the GQL query.RepositoryException
public static void parse(java.lang.String statement, Session session, GQL.ParserCallback callback) throws RepositoryException
statement
and generates callbacks for each
GQL term parsed.statement
- the GQL statement.session
- the current session to resolve namespace prefixes.callback
- the callback handler.RepositoryException
- if an error occurs while parsing."Copyright © 2010 - 2020 Adobe Systems Incorporated. All Rights Reserved"