Class Query (2.0.0)

public final class Query implements 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.

Inheritance

Object > Query

Implements

Serializable

Static Fields

KIND_METADATA_KIND

public static final String KIND_METADATA_KIND
Field Value
Type Description
String

NAMESPACE_METADATA_KIND

public static final String NAMESPACE_METADATA_KIND
Field Value
Type Description
String

PROPERTY_METADATA_KIND

public static final String PROPERTY_METADATA_KIND
Field Value
Type Description
String

Constructors

Query()

public Query()

Create a new kindless Query that finds Entity objects. Note that kindless queries are not yet supported in the Java dev appserver.

Currently the only operations supported on a kindless query are filter by key, ancestor, and order by key ascending.

Query(@Nullable String kind, @Nullable Key ancestor)

public Query(@Nullable String kind, @Nullable Key ancestor)

Create a new 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.

Parameters
Name Description
kind @org.checkerframework.checker.nullness.qual.Nullable java.lang.String

the kind or null to create a kindless query

ancestor @org.checkerframework.checker.nullness.qual.Nullable com.google.appengine.api.datastore.Key

the ancestor key or null

Query(Key ancestor)

public Query(Key ancestor)

Create a new Query that finds Entity objects with the specified Key as an ancestor.

Parameter
Name Description
ancestor Key

the ancestor key or null

Query(String kind)

public Query(String kind)

Create a new Query that finds Entity objects with the specified kind. Note that kindless queries are not yet supported in the Java dev appserver.

Parameter
Name Description
kind String

the kind or null to create a kindless query

Methods

addFilter(String propertyName, Query.FilterOperator operator, Object value) (deprecated)

public Query addFilter(String propertyName, Query.FilterOperator operator, Object value)

Deprecated. Use #setFilter(Filter)

Add a FilterPredicate on the specified property.

All FilterPredicates added using this message are combined using CompositeFilterOperator#AND.

Cannot be used in conjunction with #setFilter(Filter) which sets a single Filter instead of many FilterPredicates.

Parameters
Name Description
propertyName String

The name of the property to which the filter applies.

operator Query.FilterOperator

The filter operator.

value Object

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.

Returns
Type Description
Query

this (for chaining)

addProjection(Projection projection)

public Query addProjection(Projection projection)

Adds a projection for this query.

Projections are limited in the following ways:

  • Un-indexed properties cannot be projected and attempting to do so will result in no entities being returned.
  • Projection names must be unique.
  • Properties that have an equality filter on them cannot be projected. This includes the operators FilterOperator#EQUAL and FilterOperator#IN.
See Also: #getProjections()

Parameter
Name Description
projection Projection

the projection to add

Returns
Type Description
Query

this (for chaining)

addSort(String propertyName)

public Query addSort(String propertyName)

Specify how the query results should be sorted.

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.

Parameter
Name Description
propertyName String
Returns
Type Description
Query

this (for chaining)

addSort(String propertyName, Query.SortDirection direction)

public Query addSort(String propertyName, Query.SortDirection direction)

Specify how the query results should be sorted.

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 SortDirection#ASCENDING, entities with multi-value properties identified by propertyName will be sorted by the smallest value in the list. If direction is 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.

Parameters
Name Description
propertyName String
direction Query.SortDirection
Returns
Type Description
Query

this (for chaining)

clearKeysOnly()

public Query clearKeysOnly()

Clears the keys only flag. See Also: #setKeysOnly()

Returns
Type Description
Query

this (for chaining)

equals(@Nullable Object o)

public boolean equals(@Nullable Object o)
Parameter
Name Description
o @org.checkerframework.checker.nullness.qual.Nullable java.lang.Object
Returns
Type Description
boolean
Overrides

getAncestor()

public Key getAncestor()

Gets the current ancestor for this query, or null if there is no ancestor specified.

Returns
Type Description
Key

getAppId()

public String getAppId()

Returns the appId for this Query.

Returns
Type Description
String

getDistinct()

public boolean getDistinct()

Returns whether this query is distinct. See Also: #setDistinct(boolean)

Returns
Type Description
boolean

getFilter()

public @Nullable Query.Filter getFilter()

Returns the filter for this query, or null. See Also: #setFilter(Filter)

Returns
Type Description
@org.checkerframework.checker.nullness.qual.Nullable com.google.appengine.api.datastore.Query.Filter

getFilterPredicates() (deprecated)

public List<Query.FilterPredicate> getFilterPredicates()

Deprecated. Use #setFilter(Filter) and #getFilter() instead

Returns a mutable list of the current filter predicates. See Also: #addFilter(String, FilterOperator, Object)

Returns
Type Description
List<FilterPredicate>

getKind()

public @Nullable String getKind()

Only Entity objects whose kind matches this value will be returned.

Returns
Type Description
@org.checkerframework.checker.nullness.qual.Nullable java.lang.String

getNamespace()

public String getNamespace()

Returns the namespace for this Query.

Returns
Type Description
String

getProjections()

public Collection<Projection> getProjections()

Returns a mutable collection properties included in the projection for this query.

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:

  • May change the type of any property returned in a projection.
  • May change the index requirements for the given query.
  • Will cause a partial entity to be returned.
  • Will cause only entities that contain those properties to be returned.

However, projection queries are significantly faster than normal queries. See Also: #addProjection(Projection)

Returns
Type Description
Collection<Projection>

a mutable collection properties included in the projection for this query

getSortPredicates()

public List<Query.SortPredicate> getSortPredicates()

Returns a mutable list of the current sort predicates.

Returns
Type Description
List<SortPredicate>

hashCode()

public int hashCode()
Returns
Type Description
int
Overrides

isKeysOnly()

public boolean isKeysOnly()

Returns true if this query will fetch and return keys only, false if it will fetch and return full entities.

Returns
Type Description
boolean

reverse()

public Query reverse()

Creates a query sorted in the exact opposite direction as the current one.

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.

Returns
Type Description
Query

A new query with the sort order reversed.

setAncestor(Key ancestor)

public Query setAncestor(Key ancestor)

Sets an ancestor for this query.

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).

Parameter
Name Description
ancestor Key
Returns
Type Description
Query

this (for chaining)

setDistinct(boolean distinct)

public Query setDistinct(boolean distinct)

Sets whether to return only results with distinct values of the properties being projected.

Parameter
Name Description
distinct boolean

if this query should be distinct. This may only be used when the query has a projection.

Returns
Type Description
Query

this (for chaining)

setFilter(@Nullable Query.Filter filter)

public Query setFilter(@Nullable Query.Filter filter)

Sets the filter to use for this query. See Also: CompositeFilter, FilterPredicate

Parameter
Name Description
filter @org.checkerframework.checker.nullness.qual.Nullable com.google.appengine.api.datastore.Query.Filter

the filter to use for this query, or null

Returns
Type Description
Query

this (for chaining)

setKeysOnly()

public Query setKeysOnly()

Makes this query fetch and return only keys, not full entities.

Returns
Type Description
Query

this (for chaining)

toString()

public String toString()

Outputs a SQL like string representing the query.

Returns
Type Description
String
Overrides