com.google.appengine.api.datastore

## Interface PreparedQuery

-     public interface PreparedQuery

  Contains methods for fetching and returning entities from a `Query`. If the `Query` specified a sort order, `Entities` are returned in that order. Otherwise, the order is undefined.

  A `PreparedQuery` does not cache results. Each use of `PreparedQuery` results in a new trip to the datastore.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `PreparedQuery.TooManyResultsException` Indicates that too many results were found for `asSingleEntity()`.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Iterable<Entity>` | `asIterable()` Equivalent to `asIterable(FetchOptions)` but uses default `FetchOptions`.
    `java.lang.Iterable<Entity>` | `asIterable(FetchOptions fetchOptions)` Retrieves the `Query` `Entities` as an `Iterable` using the provided `FetchOptions`.
    `java.util.Iterator<Entity>` | `asIterator()` Equivalent to `asIterator(FetchOptions)` but uses default `FetchOptions`.
    `java.util.Iterator<Entity>` | `asIterator(FetchOptions fetchOptions)` Retrieves the `Query` `Entities` as an `Iterator` using the provided `FetchOptions`.
    `java.util.List<Entity>` | `asList(FetchOptions fetchOptions)` Retrieves the `Query` `Entities` as a `List` using the provided `FetchOptions`.
    `QueryResultIterable<Entity>` | `asQueryResultIterable()` Similar to `asIterable()` except a `QueryResultIterable` is returned.
    `QueryResultIterable<Entity>` | `asQueryResultIterable(FetchOptions fetchOptions)` Similar to `asIterable(FetchOptions)` except a `QueryResultIterable` is returned.
    `QueryResultIterator<Entity>` | `asQueryResultIterator()` Similar to `asIterator()` except a `QueryResultIterator` is returned.
    `QueryResultIterator<Entity>` | `asQueryResultIterator(FetchOptions fetchOptions)` Similar to `asIterator(FetchOptions)` except a `QueryResultIterator` is returned.
    `QueryResultList<Entity>` | `asQueryResultList(FetchOptions fetchOptions)` Similar to `asList(com.google.appengine.api.datastore.FetchOptions)` except a `QueryResultIterator` is returned.
    `Entity` | `asSingleEntity()` Retrieves the one and only result for the `Query`.
    `int` | `countEntities()` Deprecated. Use `countEntities(FetchOptions)` instead. Calling this function imposes a maximum result limit of 1000.
    `int` | `countEntities(FetchOptions fetchOptions)` Retrieves the number of `Entities` that currently match this `Query`.

- - ### Method Detail

    - #### asList

          java.util.List<Entity> asList(FetchOptions fetchOptions)

      Retrieves the `Query` `Entities` as a `List` using the provided `FetchOptions`.

      Note that if `FetchOptions.getLimit()` is greater than the number of `Entities`, the length of the returned `List` will be smaller than`FetchOptions.getLimit()`.

      To operate on large result sets, you should prefer `asIterable(com.google.appengine.api.datastore.FetchOptions)` and `asIterator(com.google.appengine.api.datastore.FetchOptions)`, which stream the results from the datastore.

      Parameters:
        `fetchOptions` - The fetch options to apply.
      Returns:
        The result of the PreparedQuery, represented as a `List`.
      Throws:
        `java.lang.IllegalStateException` - If the query being executed is associated with a `Transaction` that is not active.
      See Also:
        `FetchOptions`

    - #### asQueryResultList

          QueryResultList<Entity> asQueryResultList(FetchOptions fetchOptions)

      Similar to `asList(com.google.appengine.api.datastore.FetchOptions)` except a `QueryResultIterator` is returned.

    - #### asIterable

          java.lang.Iterable<Entity> asIterable(FetchOptions fetchOptions)

      Retrieves the `Query` `Entities` as an `Iterable` using the provided `FetchOptions`.

      Each use of `Iterable.iterator()` results in an entirely new and independent `Iterator`.

      Parameters:
        `fetchOptions` - The fetch options to apply.
      Returns:
        The result of the PreparedQuery, represented as an `Iterable`.
      Throws:
        `java.lang.IllegalStateException` - If the query being executed is associated with a `Transaction` that is not active.
      See Also:
        `FetchOptions`

    - #### asIterable

          java.lang.Iterable<Entity> asIterable()

      Equivalent to `asIterable(FetchOptions)` but uses default `FetchOptions`.

    - #### asQueryResultIterable

          QueryResultIterable<Entity> asQueryResultIterable(FetchOptions fetchOptions)

      Similar to `asIterable(FetchOptions)` except a `QueryResultIterable` is returned. Call this method to have (indirect) access to `Cursor`s for your result set.

    - #### asQueryResultIterable

          QueryResultIterable<Entity> asQueryResultIterable()

      Similar to `asIterable()` except a `QueryResultIterable` is returned. Call this method to have (indirect) access to `Cursor`s for your result set.

    - #### asIterator

          java.util.Iterator<Entity> asIterator(FetchOptions fetchOptions)

      Retrieves the `Query` `Entities` as an `Iterator` using the provided `FetchOptions`.
      Parameters:
        `fetchOptions` - The fetch strategy to apply.
      Returns:
        The result of the PreparedQuery, represented as an `Iterator`.
      Throws:
        `java.lang.IllegalStateException` - If the query being executed is associated with a `Transaction` that is not active.
      See Also:
        `FetchOptions`

    - #### asIterator

          java.util.Iterator<Entity> asIterator()

      Equivalent to `asIterator(FetchOptions)` but uses default `FetchOptions`.

    - #### asQueryResultIterator

          QueryResultIterator<Entity> asQueryResultIterator(FetchOptions fetchOptions)

      Similar to `asIterator(FetchOptions)` except a `QueryResultIterator` is returned. Call this method to have access to `Cursor`s for your result set.

    - #### asQueryResultIterator

          QueryResultIterator<Entity> asQueryResultIterator()

      Similar to `asIterator()` except a `QueryResultIterator` is returned. Call this method to have access to `Cursor`s for your result set.

    - #### asSingleEntity

          Entity asSingleEntity()
                         throws PreparedQuery.TooManyResultsException

      Retrieves the one and only result for the `Query`.
      Returns:
        the single, matching result, or `null` if no entities match
      Throws:
        `PreparedQuery.TooManyResultsException` - if more than one result is returned from the `Query`.
        `java.lang.IllegalStateException` - If the query being executed is associated with a `Transaction` that is not active.

    - #### countEntities

          int countEntities(FetchOptions fetchOptions)

      Retrieves the number of `Entities` that currently match this `Query`.
      Returns:
        a count >= 0
      Throws:
        `java.lang.IllegalStateException` - If the query being executed is associated with a `Transaction` that is not active.

    - #### countEntities

          @Deprecated
          int countEntities()

      Deprecated. Use `countEntities(FetchOptions)` instead. Calling this function imposes a maximum result limit of 1000.
      Retrieves the number of `Entities` that currently match this `Query`.
      Returns:
        a count >= 0
      Throws:
        `java.lang.IllegalStateException` - If the query being executed is associated with a `Transaction` that is not active.