# PreparedQuery
Date: 2012-02-24

## 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
`static class` `PreparedQuery.TooManyResultsException` Indicates that too many results were found for `asSingleEntity()`.

Method Summary
`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`

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

### asIterable

    java.lang.Iterable<Entity> asIterable()

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

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