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

    Nested Classes
    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.GeoRegion` A geographic region intended for use in a `Query.StContainsFilter`.
    `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.
    `static class` | `Query.StContainsFilter` A `Query.Filter` representing a geo-region containment predicate.

  - ### Field Summary

    Fields
    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 Summary

    Constructors
    Constructor and Description
    `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

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `Query` | `addFilter(java.lang.String propertyName, Query.FilterOperator operator, java.lang.Object value)` Deprecated. Use `setFilter(Filter)`
    `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()` Returns whether this query is distinct.
    `Query.Filter` | `getFilter()` Returns the filter for this query, or `null`.
    `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)` Sets whether to return only results with distinct values of the properties being projected.
    `Query` | `setFilter(Query.Filter filter)` Sets the filter to use 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

          @Deprecated
          public static final java.lang.String KIND_METADATA_KIND

      Deprecated.
      See Also:
        Constant Field Values

    - #### PROPERTY_METADATA_KIND

          @Deprecated
          public static final java.lang.String PROPERTY_METADATA_KIND

      Deprecated.
      See Also:
        Constant Field Values

    - #### NAMESPACE_METADATA_KIND

          @Deprecated
          public static final java.lang.String NAMESPACE_METADATA_KIND

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

    - #### getAppId

          public java.lang.String getAppId()

      Returns the appId for this `Query`.

    - #### getNamespace

          public java.lang.String getNamespace()

      Returns the namespace for this `Query`.

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

    - #### setDistinct

          public Query setDistinct(boolean distinct)

      Sets whether to return only results with distinct values of the properties being projected.
      Parameters:
        `distinct` - if this query should be distinct. This may only be used when the query has a projection.
      Returns:
        `this` (for chaining)

    - #### getDistinct

          public boolean getDistinct()

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

    - #### setFilter

          public Query setFilter(Query.Filter filter)

      Sets the filter to use for this query.
      Parameters:
        `filter` - the filter to use for this query, or `null`
      Returns:
        `this` (for chaining)
      See Also:
        `Query.CompositeFilter`, `Query.FilterPredicate`

    - #### getFilter

          public Query.Filter getFilter()

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

    - #### addFilter

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

      Deprecated. Use `setFilter(Filter)`
      Add a `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.

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

    - #### getFilterPredicates

          @Deprecated
          public java.util.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)`

    - #### 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 a mutable 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)

    - #### clearKeysOnly

          public Query clearKeysOnly()

      Clears the keys only flag.
      Returns:
        `this` (for chaining)
      See Also:
        `setKeysOnly()`

    - #### addProjection

          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 `Query.FilterOperator.EQUAL` and `Query.FilterOperator.IN`.
      Parameters:
        `projection` - the projection to add
      Returns:
        `this` (for chaining)
      Throws:
        `java.lang.IllegalArgumentException` - if the query already contains a projection with the same name
      See Also:
        `getProjections()`

    - #### getProjections

          public java.util.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.
      Returns:
        a mutable collection properties included in the projection for this query
      See Also:
        `addProjection(Projection)`

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

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