com.google.appengine.api.datastore
Class Query

java.lang.Object
  com.google.appengine.api.datastore.Query

All Implemented Interfaces:

java.io.Serializable

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.

See Also:

Serialized Form

Nested Class Summary

static class	Query.FilterOperator FilterOperator specifies what type of operation you want to apply to your filter.
static class	Query.FilterPredicate FilterPredicate is a data container that holds a single filter predicate.
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.

Constructor Summary

Query()
Create a new kind-less Query that finds Entity objects.

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

Query(java.lang.String kind)
Create a new Query that finds Entity objects with the specified kind.

Query(java.lang.String kind, Key ancestor)
Create a new Query that finds Entity objects with the specified kind.

Method Summary

Query	addFilter(java.lang.String propertyName, Query.FilterOperator operator, java.lang.Object value) Add a filter on the specified property.
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.
boolean	equals(java.lang.Object o)
Key	getAncestor() Gets the current ancestor for this query, or null if there is no ancestor specified.
java.util.List<Query.FilterPredicate>	getFilterPredicates() Returns an unmodifiable list of the current filter predicates.
java.lang.String	getKind() Only Entity objects whose kind matches this value will be returned.
java.util.List<Query.SortPredicate>	getSortPredicates() Returns an unmodifiable 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	setAncestor(Key ancestor) Sets an ancestor for this query.
Query	setKeysOnly() Makes this query fetch and return only keys, not full entities.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Query

public Query()

Create a new kind-less Query that finds Entity objects. Currently the only operations supported on a kind-less query are filter by __key__, ancestor, and order by __key__ ascending.

Query

public Query(java.lang.String kind)

Create a new Query that finds Entity objects with the specified kind.

Parameters:

kind - the kind or null to create a kind-less query

Query

public Query(Key ancestor)

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

Parameters:

ancestor - the ancestor key or null

Throws:

java.lang.IllegalArgumentException - If ancestor is not complete.

Query

public Query(java.lang.String kind,
             Key ancestor)

Create a new Query that finds Entity objects with the specified kind.

Parameters:

kind - the kind or null to create a kind-less query

ancestor - the ancestor key or null

Throws:

java.lang.IllegalArgumentException - If the ancestor is not complete.

Method Detail

getKind

public java.lang.String getKind()

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

getAncestor

public Key getAncestor()

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

setAncestor

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

Returns:

this (for chaining)

Throws:

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.

addFilter

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

Add a filter on the specified property.

Parameters:

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.

Returns:

this (for chaining)

Throws:

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 Entity.setProperty(String, Object), you cannot provide a Collection containing instances of supported types to this method.

java.lang.IllegalArgumentException - If operator is Query.FilterOperator.NOT_EQUAL and the query already has a Query.FilterOperator.NOT_EQUAL filter.

getFilterPredicates

public java.util.List<Query.FilterPredicate> getFilterPredicates()

Returns an unmodifiable list of the current filter predicates.

addSort

public Query addSort(java.lang.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.

Returns:

this (for chaining)

Throws:

java.lang.NullPointerException - If any argument is null.

addSort

public Query addSort(java.lang.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 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.

Returns:

this (for chaining)

Throws:

java.lang.NullPointerException - If any argument is null.

getSortPredicates

public java.util.List<Query.SortPredicate> getSortPredicates()

Returns an unmodifiable list of the current sort predicates.

setKeysOnly

public Query setKeysOnly()

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

Returns:

this (for chaining)

isKeysOnly

public boolean isKeysOnly()

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

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object