# Query
Date: 2012-02-24

## 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`