public final class Query
extends java.lang.Object
implements java.io.Serializable
Query
encapsulates a request for zero or more Entity
objects out of the
datastore. It supports querying on zero or more properties, querying by ancestor, and sorting.
Entity
objects which match the query can be retrieved in a single list, or with an
unbounded iterator.Modifier and Type | Class and Description |
---|---|
static class |
Query.CompositeFilter
A
Query.Filter that combines several sub filters using a Query.CompositeFilterOperator . |
static class |
Query.CompositeFilterOperator
Operators supported by
Query.CompositeFilter . |
static class |
Query.Filter
The base class for a query filter.
|
static class |
Query.FilterOperator
Operators supported by
Query.FilterPredicate . |
static class |
Query.FilterPredicate
A
Query.Filter on a single property. |
static class |
Query.GeoRegion
A geographic region intended for use in a
Query.StContainsFilter . |
static class |
Query.SortDirection
SortDirection controls the order of a sort.
|
static class |
Query.SortPredicate
SortPredicate is a data container that holds a single sort predicate.
|
static class |
Query.StContainsFilter
A
Query.Filter representing a geo-region containment predicate. |
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
KIND_METADATA_KIND
Deprecated.
|
static java.lang.String |
NAMESPACE_METADATA_KIND
Deprecated.
|
static java.lang.String |
PROPERTY_METADATA_KIND
Deprecated.
|
Constructor and Description |
---|
Query()
|
Query(Key ancestor)
|
Query(java.lang.String kind)
|
Query(java.lang.String kind,
Key ancestor)
|
Modifier and Type | Method and Description |
---|---|
Query |
addFilter(java.lang.String propertyName,
Query.FilterOperator operator,
java.lang.Object value)
Deprecated.
|
Query |
addProjection(Projection projection)
Adds a projection for this query.
|
Query |
addSort(java.lang.String propertyName)
Specify how the query results should be sorted.
|
Query |
addSort(java.lang.String propertyName,
Query.SortDirection direction)
Specify how the query results should be sorted.
|
Query |
clearKeysOnly()
Clears the keys only flag.
|
boolean |
equals(java.lang.Object o) |
Key |
getAncestor()
Gets the current ancestor for this query, or null if there is no ancestor specified.
|
java.lang.String |
getAppId()
Returns the appId for this
Query . |
boolean |
getDistinct() |
Query.Filter |
getFilter() |
java.util.List<Query.FilterPredicate> |
getFilterPredicates()
Deprecated.
Use
setFilter(Filter) and getFilter() instead |
java.lang.String |
getKind()
Only
Entity objects whose kind matches this value will be returned. |
java.lang.String |
getNamespace()
Returns the namespace for this
Query . |
java.util.Collection<Projection> |
getProjections()
Returns a mutable collection properties included in the projection for this query.
|
java.util.List<Query.SortPredicate> |
getSortPredicates()
Returns a mutable list of the current sort predicates.
|
int |
hashCode() |
boolean |
isKeysOnly()
Returns true if this query will fetch and return keys only, false if it will fetch and return
full entities.
|
Query |
reverse()
Creates a query sorted in the exact opposite direction as the current one.
|
Query |
setAncestor(Key ancestor)
Sets an ancestor for this query.
|
Query |
setDistinct(boolean distinct) |
Query |
setFilter(Query.Filter filter) |
Query |
setKeysOnly()
Makes this query fetch and return only keys, not full entities.
|
java.lang.String |
toString()
Outputs a SQL like string representing the query.
|
@Deprecated public static final java.lang.String KIND_METADATA_KIND
@Deprecated public static final java.lang.String PROPERTY_METADATA_KIND
@Deprecated public static final java.lang.String NAMESPACE_METADATA_KIND
public Query()
public Query(java.lang.String kind)
Query
that finds Entity
objects with the specified kind
.
Note that kindless queries are not yet supported in the Java dev appserver.kind
- the kind or null to create a kindless querypublic Query(Key ancestor)
ancestor
- the ancestor key or nulljava.lang.IllegalArgumentException
- If ancestor is not complete.public Query(java.lang.String kind, Key ancestor)
Query
that finds Entity
objects with the specified kind
and the specified ancestor
. Note that kindless queries are not yet supported in the
Java dev appserver.kind
- the kind or null to create a kindless queryancestor
- the ancestor key or nulljava.lang.IllegalArgumentException
- If the ancestor is not complete.public java.lang.String getKind()
Entity
objects whose kind matches this value will be returned.public java.lang.String getAppId()
Query
.public java.lang.String getNamespace()
Query
.public Key getAncestor()
public Query setAncestor(Key ancestor)
This restricts the query to only return result entities that are descended from a given entity. In other words, all of the results will have the ancestor as their parent, or parent's parent, or etc.
If null is specified, unsets any previously-set ancestor. Passing null
as a
parameter does not query for entities without ancestors (this type of query is not currently
supported).
this
(for chaining)java.lang.IllegalArgumentException
- If the ancestor key is incomplete, or if you try to unset an
ancestor and have not set a kind, or if you try to unset an ancestor and have not
previously set an ancestor.public Query setDistinct(boolean distinct)
distinct
- if this query should be distinct. This may only be used when the query has a
projection.this
(for chaining)public boolean getDistinct()
setDistinct(boolean)
public Query setFilter(Query.Filter filter)
filter
- the filter to use for this query, or null
this
(for chaining)Query.CompositeFilter
,
Query.FilterPredicate
public Query.Filter getFilter()
null
setFilter(Filter)
@Deprecated public Query addFilter(java.lang.String propertyName, Query.FilterOperator operator, java.lang.Object value)
setFilter(Filter)
Query.FilterPredicate
on the specified property.
All Query.FilterPredicate
s added using this message are combined using Query.CompositeFilterOperator.AND
.
Cannot be used in conjunction with setFilter(Filter)
which sets a single Query.Filter
instead of many Query.FilterPredicate
s.
propertyName
- The name of the property to which the filter applies.operator
- The filter operator.value
- An instance of a supported datastore type. Note that entities with multi-value
properties identified by propertyName
will match this filter if the multi-value
property has at least one value that matches the condition expressed by operator
and value
. For more information on multi-value property filtering please see the datastore documentation.this
(for chaining)java.lang.NullPointerException
- If propertyName
or operator
is null.java.lang.IllegalArgumentException
- If value
is not of a type supported by the datastore.
See DataTypeUtils.isSupportedType(Class)
. Note that unlike PropertyContainer.setProperty(String, Object)
, you cannot provide a Collection
containing
instances of supported types to this method.@Deprecated public java.util.List<Query.FilterPredicate> getFilterPredicates()
setFilter(Filter)
and getFilter()
insteadpublic Query addSort(java.lang.String propertyName)
The first call to addSort will register the property that will serve as the primary sort key. A second call to addSort will set a secondary sort key, etc.
This method will always sort in ascending order. To control the order of the sort, use
addSort(String,SortDirection)
.
Note that entities with multi-value properties identified by propertyName
will be
sorted by the smallest value in the list. For more information on sorting properties with
multiple values please see the datastore documentation.
this
(for chaining)java.lang.NullPointerException
- If any argument is null.public Query addSort(java.lang.String propertyName, Query.SortDirection direction)
The first call to addSort will register the property that will serve as the primary sort key. A second call to addSort will set a secondary sort key, etc.
Note that if direction
is Query.SortDirection.ASCENDING
, entities with multi-value
properties identified by propertyName
will be sorted by the smallest value in the list.
If direction
is Query.SortDirection.DESCENDING
, entities with multi-value properties
identified by propertyName
will be sorted by the largest value in the list. For more
information on sorting properties with multiple values please see the datastore documentation.
this
(for chaining)java.lang.NullPointerException
- If any argument is null.public java.util.List<Query.SortPredicate> getSortPredicates()
public Query setKeysOnly()
this
(for chaining)public Query clearKeysOnly()
this
(for chaining)setKeysOnly()
public Query addProjection(Projection projection)
Projections are limited in the following ways:
names
must be unique.
Query.FilterOperator.EQUAL
and Query.FilterOperator.IN
.
projection
- the projection to addthis
(for chaining)java.lang.IllegalArgumentException
- if the query already contains a projection with the same namegetProjections()
public java.util.Collection<Projection> getProjections()
If empty, the full or keys only entities are returned. Otherwise partial entities are
returned. A non-empty projection is not compatible with setting keys-only. In this case a
IllegalArgumentException
will be thrown when the query is prepared
.
Projection queries are similar to SQL statements of the form:
SELECT prop1, prop2, ...As they return partial entities, which only contain the properties specified in the projection. However, these entities will only contain a single value for any multi-valued property and, if a multi-valued property is specified in the order, an inequality property, or the projected properties, the entity will be returned multiple times. Once for each unique combination of values.
Specifying a projection:
addProjection(Projection)
public boolean isKeysOnly()
public Query reverse()
This function requires a sort order on Entity.KEY_RESERVED_PROPERTY
to guarantee
that each entity is uniquely identified by the set of properties used in the sort (which is
required to exactly reverse the order of a query). Advanced users can reverse the sort orders
manually if they know the set of sorted properties meets this requirement without a order on
Entity.KEY_RESERVED_PROPERTY
.
The results of the reverse query will be the same as the results of the forward query but in reverse direction.
Cursors
from the original query may also be used in the reverse query.
java.lang.IllegalStateException
- if the current query is not sorted by Entity.KEY_RESERVED_PROPERTY
.public boolean equals(java.lang.Object o)
equals
in class java.lang.Object
public int hashCode()
hashCode
in class java.lang.Object
public java.lang.String toString()
toString
in class java.lang.Object