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.SortDirection
SortDirection controls the order of a sort.
|
static class
|
Query.SortPredicate
SortPredicate is a data container that holds a single sort
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 query
public Query(Key ancestor)
ancestor
- the ancestor key or null
java.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 query
ancestor
- the ancestor key or null
java.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)
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()
public Query addSort(java.lang.String propertyName)
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)
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 add
this
(for chaining)
java.lang.IllegalArgumentException
- if the query already contains a projection with the same name
getProjections()
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()
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 can be converted for use with
the reverse query through
Cursor.reverse()
.
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