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.

Field Summary

static java.lang.String	KIND_METADATA_KIND A metadata kind that can be used to query for kinds that exist in the datastore.
static java.lang.String	NAMESPACE_METADATA_KIND A metadata kind that can be used to query for namespaces that exist in the datastore.
static java.lang.String	PROPERTY_METADATA_KIND A metadata kind that can be used to query for properties that exist in the datastore.

Constructor Summary

Query()
Create a new kindless 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 and the specified ancestor.

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	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	setKeysOnly() Makes this query fetch and return only keys, not full entities.
java.lang.String	toString() Outputs a SQL like string representing the query.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

KIND_METADATA_KIND

public static final java.lang.String KIND_METADATA_KIND

A metadata kind that can be used to query for kinds that exist in the datastore.

See Also:

Constant Field Values

PROPERTY_METADATA_KIND

public static final java.lang.String PROPERTY_METADATA_KIND

A metadata kind that can be used to query for properties that exist in the datastore.

See Also:

Constant Field Values

NAMESPACE_METADATA_KIND

public static final java.lang.String NAMESPACE_METADATA_KIND

A metadata kind that can be used to query for namespaces that exist in the datastore.

See Also:

Constant Field Values

Constructor Detail

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

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

Parameters:

kind - the kind or null to create a kindless 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 and the specified ancestor. Note that kindless queries are not yet supported in the Java dev appserver.

Parameters:

kind - the kind or null to create a kindless 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.

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.

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. Cursors from the original query can be converted for use with the reverse query through Cursor.reverse().

Returns:

A new query with the sort order reversed.

Throws:

java.lang.IllegalStateException - if the current query is not sorted by Entity.KEY_RESERVED_PROPERTY.

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

toString

public java.lang.String toString()

Outputs a SQL like string representing the query.

Overrides:

toString in class java.lang.Object