# Package org.modeshape.jcr.query

The Query API provides a mechanism for building and executing queries.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  BufferManager.Buffer | A basic buffer interface.
  BufferManager.DistinctBuffer<T> | A buffer used to determine distinct values.
  BufferManager.DistinctBufferMaker<T> | An object use to create a new `BufferManager.DistinctBuffer`.
  BufferManager.Predicate<T> |
  BufferManager.QueueBuffer<T> | A buffer that maintains the insertion order of a series of values.
  BufferManager.QueueBufferMaker<T> | An object use to create a new `BufferManager.DistinctBuffer`.
  BufferManager.SortingBuffer<SortType,RecordType> | A buffer used to sort values into ascending or descending order.
  BufferManager.SortingBufferMaker<SortType,RecordType> | An object use to create a new `BufferManager.SortingBuffer`.
  CancellableQuery | A simple interface that allows tracking an executing query that can be cancelled.
  JcrQueryContext | The context in which queries are executed.
  NodeSequence.Batch | A batch of rows containing nodes and scores.
  NodeSequence.Restartable |
  NodeSequence.RowAccessor | An interface that abstracts accessing the node(s) and score(s) in a row.
  NodeSequence.RowFilter | A filter of rows.
  QueryBuilder.DynamicOperandBuilder | Interface that defines a dynamic operand portion of a criteria.
  QueryBuilder.OrderByOperandBuilder |
  QueryEngine |
  QueryResults | The resulting output of a query.
  QueryResults.Columns | Definition of the columns that are available in the results.
  RowExtractors.ExtractFromRow | An operation that extracts a single value from the current row in a given `NodeSequence.Batch`.
  Tuples.TupleFactory<T> |

- Class Summary
  Class | Description
  --- | ---
  BufferManager | A manager of temporary buffers used in the query system.
  BufferManager.DbHolder |
  CompositeIndexWriter | A composition of multiple QueryIndexWriter instances.
  JcrAbstractQuery | Abstract implementation of JCR's `Query` interface.
  JcrQuery | Implementation of `Query` that represents a `query command`.
  JcrQueryResult | The results of a query.
  JcrQueryResult.AbstractRow |
  JcrQueryResult.MultiSelectorQueryResultRow |
  JcrQueryResult.QueryResultIterator | The `NodeIterator` implementation returned by the `JcrQueryResult`.
  JcrQueryResult.QueryResultNodeIterator | The `NodeIterator` implementation returned by the `JcrQueryResult`.
  JcrQueryResult.QueryResultRowIterator | The `RowIterator` implementation returned by the `JcrQueryResult`.
  JcrQueryResult.SingleSelectorQueryResultRow |
  JcrQueryResult.SingleSelectorQueryResultRowIterator | The `RowIterator` implementation returned by the `JcrQueryResult`.
  JcrSqlQueryResult | A specialization of `JcrQueryResult` that addresses the JCR-SQL specific columns.
  JcrTypeSystem |
  NodeSequence | A sequence of nodes that is accessed by batches and that is accessible only once.
  NodeSequence.AlternateSizeBatch |
  NodeSequence.LimitBatch |
  NodeSequence.MultiWidthBatch |
  NodeSequence.SingleWidthBatch |
  QueryBuilder | A component that can be used to programmatically create `QueryCommand` objects.
  QueryContext | An immutable context in which queries are to be executed.
  QueryEngineBuilder |
  QueryResults.Statistics |
  RowExtractors | Standard `RowExtractors.ExtractFromRow` implementations.
  Tuples | A simple set of classes for working with tuples of data.
  Tuples.Tuple2<T1,T2> |
  Tuples.Tuple2Serializer<T1,T2> |
  Tuples.Tuple2TypeFactory<T1,T2> |
  Tuples.Tuple3<T1,T2,T3> |
  Tuples.Tuple3Serializer<T1,T2,T3> |
  Tuples.Tuple3TypeFactory<T1,T2,T3> |
  Tuples.Tuple4<T1,T2,T3,T4> |
  Tuples.Tuple4Serializer<T1,T2,T3,T4> |
  Tuples.Tuple4TypeFactory<T1,T2,T3,T4> |
  Tuples.TupleN |
  Tuples.TupleNSerializer |
  Tuples.TupleNTypeFactory |
  XPathQueryResult | `QueryResult` implementation for XPath results.

## Package org.modeshape.jcr.query Description

The Query API provides a mechanism for building and executing queries. The framework provides a reusable and extensible query engine that is capable of planning, validating, optimizing, and executing queries against a generic back-end system.

### Abstract query model

At the heart of the entire query system is a single representation of what constitutes a query. The `abstract query model` defines a language-independent vocabulary for queries, and consists of a family of Java classes each represent the important semantic elements needed to fully define a query.

There are two ways to construct abstract query models. The first is to programmatically construct a query model using the `QueryBuilder`, which provides a fluent API that makes it easy to create a query with Java code. The second (and more common) approach is to use a `QueryParser` that parses a query represented in a specific language (like SQL or XPath) and then creates the query's equivalent abstract query model. There's even a `QueryParsers` class that can manage the parsers for multiple languages.

The abstract query model classes are immutable, making them very easily shared or reused if that is advantageous.

### SQL language

One of the `QueryParser` implementation provided out of the box is the `BasicSqlQueryParser`, which understands a subset of SQL.

### QueryEngine

The `QueryEngine` is the component that accepts and executes queries expressed as abstract query models. Each submitted query is planned, validated, optimized, and then processed to compute and return the final `query results`.

Note that the QueryEngine is thread-safe.

#### Planning

In the planning stage, a canonical plan is generated for each query. This plan is a tree of `PlanNode` objects that each represent a different aspect of the query, and is a form that is easily manipulated by subsequent stages. Any implementation of `Planner` can be used, though a `CanonicalPlanner` implementation is provided and will be sufficient for most cases. In fact, the subsequent execution steps often require the plan to be in its canonical form, so for most situations it may be best to simply reuse the CanonicalPlanner and in other simply extend it.

Note that query plans are mutable and not thread-safe, meaning that such plans are not intended to be shared or reused.

#### Optimization

In the optimization stage, the canonical query plan is evaluated, validated, and manipulated to produce a more a single optimized query processing plan. The query plan is often changed in situ, although this is not required of the `Optimizer` implementations. A library of existing `OptimizerRule` classes is provided, though it's very easy to add more optimizer rules.

The `RuleBasedOptimizer` is an implementation that optimizes a query using a stack of rules. A new stack is created for each rule, though the rules are required to be immutable and thus often shared and reused. And, the RuleBasedOptimizer is easily subclassed to define a custom stack of rules.

#### Validation

The canonical planner or the optimization rules have access to the table and column definitions that may be queried. The query framework does not prescribe the semantics of a table or column, but instead provides a `Schemata` interface that provides access to the immutable `Schemata.Table` definitions (that then contain the `Schemata.Column` and `Schemata.Key` definitions).

The canonical planner and a number of the provided optimizer rules use the Schemata to verify that the query is referencing an existing table and columns, whatever they are defined to be. Although any Schemata implementaiton can be used, the query framework provides an `ImmutableSchemata` class with a `builder` with a fluent API that can create the corresponding immutable table, column and key definitions.

#### Processing

In the processing stage, the optimized query plan is used to construct and assemble a `NodeSequence` that abstractly represents the nodes that satisfy the query. When the sequence is accessed, the processing logic of the query engine dynamically performs the necessary operations to return the correct nodes.

### QueryResults

A query over a graph of content will result in a set of nodes that matched the criteria specified in the query. Each node contained in the results will be identified by its `NodeKey` as well as any values for the selected properties. Typically, queries will result in a single node per row, although joins may result in multiple rows per row.

Copyright © 2008-2014 JBoss, a division of Red Hat. All Rights Reserved.