# Interface PreparedQuery (5.0.3)

    public interface PreparedQuery

Contains methods for fetching and returning entities from a [Query](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.Query(class)). If the [Query](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.Query(class))
specified a sort order, [Entities](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity) are returned in that order. Otherwise, the order
is undefined.

A [PreparedQuery](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.PreparedQuery) does not cache results. Each use of [PreparedQuery](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.PreparedQuery) results in a
new trip to the datastore.

## Methods

### asIterable()

    public abstract Iterable<Entity> asIterable()

Equivalent to [#asIterable(FetchOptions)](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.PreparedQuery#com_google_appengine_api_datastore_PreparedQuery_asIterable_com_google_appengine_api_datastore_FetchOptions_) but uses default [FetchOptions](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions).

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/lang/Iterable.html<https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity>` |   |

### asIterable(FetchOptions fetchOptions)

    public abstract Iterable<Entity> asIterable(FetchOptions fetchOptions)

Retrieves the [Query](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.Query(class)) [Entities](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity) as an [Iterable](https://docs.oracle.com/javase/8/docs/api/java/lang/Iterable.html) using the provided
[FetchOptions](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions).

Each use of Iterable#iterator results in an entirely new and independent [Iterator](https://docs.oracle.com/javase/8/docs/api/java/util/Iterator.html).
See Also: [FetchOptions](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions)

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `fetchOptions` | `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions` The fetch options to apply. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/lang/Iterable.html<https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity>` | The result of the PreparedQuery, represented as an [Iterable](https://docs.oracle.com/javase/8/docs/api/java/lang/Iterable.html). |

### asIterator()

    public abstract Iterator<Entity> asIterator()

Equivalent to [#asIterator(FetchOptions)](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.PreparedQuery#com_google_appengine_api_datastore_PreparedQuery_asIterator_com_google_appengine_api_datastore_FetchOptions_) but uses default [FetchOptions](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions).

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/util/Iterator.html<https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity>` |   |

### asIterator(FetchOptions fetchOptions)

    public abstract Iterator<Entity> asIterator(FetchOptions fetchOptions)

Retrieves the [Query](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.Query(class)) [Entities](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity) as an [Iterator](https://docs.oracle.com/javase/8/docs/api/java/util/Iterator.html) using the provided
[FetchOptions](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions).
See Also: [FetchOptions](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions)

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `fetchOptions` | `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions` The fetch strategy to apply. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/util/Iterator.html<https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity>` | The result of the PreparedQuery, represented as an [Iterator](https://docs.oracle.com/javase/8/docs/api/java/util/Iterator.html). |

### asList(FetchOptions fetchOptions)

    public abstract List<Entity> asList(FetchOptions fetchOptions)

Retrieves the [Query](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.Query(class)) [Entities](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity) as a [List](https://docs.oracle.com/javase/8/docs/api/java/util/List.html) using the provided [FetchOptions](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions).

Note that if [FetchOptions#getLimit()](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions#com_google_appengine_api_datastore_FetchOptions_getLimit__) is greater than the number of [Entities](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity), the length of the returned [List](https://docs.oracle.com/javase/8/docs/api/java/util/List.html) will be smaller than[FetchOptions#getLimit()](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions#com_google_appengine_api_datastore_FetchOptions_getLimit__).

To operate on large result sets, you should prefer [#asIterable](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.PreparedQuery#com_google_appengine_api_datastore_PreparedQuery_asIterable_) and [#asIterator](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.PreparedQuery#com_google_appengine_api_datastore_PreparedQuery_asIterator_), which stream the results from the datastore.
See Also: [FetchOptions](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions)

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `fetchOptions` | `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions` The fetch options to apply. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/util/List.html<https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity>` | The result of the PreparedQuery, represented as a [List](https://docs.oracle.com/javase/8/docs/api/java/util/List.html). |

### asQueryResultIterable()

    public abstract QueryResultIterable<Entity> asQueryResultIterable()

Similar to [#asIterable()](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.PreparedQuery#com_google_appengine_api_datastore_PreparedQuery_asIterable__) except a [QueryResultIterable](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.QueryResultIterable) is returned. Call this
method to have (indirect) access to [Cursor](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.Cursor)s for your result set.

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.QueryResultIterable<https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity>` |   |

### asQueryResultIterable(FetchOptions fetchOptions)

    public abstract QueryResultIterable<Entity> asQueryResultIterable(FetchOptions fetchOptions)

Similar to [#asIterable(FetchOptions)](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.PreparedQuery#com_google_appengine_api_datastore_PreparedQuery_asIterable_com_google_appengine_api_datastore_FetchOptions_) except a [QueryResultIterable](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.QueryResultIterable) is returned.
Call this method to have (indirect) access to [Cursor](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.Cursor)s for your result set.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `fetchOptions` | `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.QueryResultIterable<https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity>` |   |

### asQueryResultIterator()

    public abstract QueryResultIterator<Entity> asQueryResultIterator()

Similar to [#asIterator()](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.PreparedQuery#com_google_appengine_api_datastore_PreparedQuery_asIterator__) except a [QueryResultIterator](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.QueryResultIterator) is returned. Call this
method to have access to [Cursor](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.Cursor)s for your result set.

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.QueryResultIterator<https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity>` |   |

### asQueryResultIterator(FetchOptions fetchOptions)

    public abstract QueryResultIterator<Entity> asQueryResultIterator(FetchOptions fetchOptions)

Similar to [#asIterator(FetchOptions)](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.PreparedQuery#com_google_appengine_api_datastore_PreparedQuery_asIterator_com_google_appengine_api_datastore_FetchOptions_) except a [QueryResultIterator](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.QueryResultIterator) is returned.
Call this method to have access to [Cursor](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.Cursor)s for your result set.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `fetchOptions` | `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.QueryResultIterator<https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity>` |   |

### asQueryResultList(FetchOptions fetchOptions)

    public abstract QueryResultList<Entity> asQueryResultList(FetchOptions fetchOptions)

Similar to [#asList](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.PreparedQuery#com_google_appengine_api_datastore_PreparedQuery_asList_) except a [QueryResultIterator](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.QueryResultIterator) is returned.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `fetchOptions` | `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.QueryResultList<https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity>` |   |

### asSingleEntity()

    public abstract Entity asSingleEntity()

Retrieves the one and only result for the [Query](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.Query(class)).

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity` | the single, matching result, or `null` if no entities match |

| **Exceptions** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.PreparedQuery.TooManyResultsException` | if more than one result is returned from the Query. |

### countEntities() (deprecated)

    public abstract int countEntities()

**Deprecated.** *Use [#countEntities(FetchOptions)](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.PreparedQuery#com_google_appengine_api_datastore_PreparedQuery_countEntities_com_google_appengine_api_datastore_FetchOptions_) instead. Calling this function imposes a
maximum result limit of 1000.*

Retrieves the number of [Entities](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity) that currently match this [Query](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.Query(class)).

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` | a count \>= 0 |

### countEntities(FetchOptions fetchOptions)

    public abstract int countEntities(FetchOptions fetchOptions)

Retrieves the number of [Entities](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.Entity) that currently match this [Query](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.Query(class)).

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `fetchOptions` | `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.FetchOptions` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` | a count \>= 0 |