> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Interface: OrderedQuery<TableInfo>

> A Query with an order that has already been defined.

[server](/api/modules/server).OrderedQuery

A [Query](/api/interfaces/server.Query) with an order that has already been defined.

## Type parameters

| Name | Type |
| :- | :- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server#generictableinfo) |

## Hierarchy

* `AsyncIterable`\<[`DocumentByInfo`](/api/modules/server#documentbyinfo)\<`TableInfo`>>

  ↳ **`OrderedQuery`**

  ↳↳ [`Query`](/api/interfaces/server.Query)

  ↳↳ [`SelectableOrderedQuery`](/api/interfaces/server.SelectableOrderedQuery)

## Methods

### filter

▸ **filter**(`predicate`): [`OrderedQuery`](/api/interfaces/server.OrderedQuery)\<`TableInfo`>

Filter the query output, returning only the values for which `predicate` evaluates to true.

**Important:** Prefer using `.withIndex()` over `.filter()` whenever
possible. Filters scan all documents matched so far and discard non-matches,
while indexes efficiently skip non-matching documents. Define an index in
your schema for fields you filter on frequently.

#### Parameters

| Name | Type | Description |
| :- | :- | :- |
| `predicate` | (`q`: [`FilterBuilder`](/api/interfaces/server.FilterBuilder)\<`TableInfo`>) => [`ExpressionOrValue`](/api/modules/server#expressionorvalue)\<`boolean`> | An [Expression](/api/classes/server.Expression) constructed with the supplied [FilterBuilder](/api/interfaces/server.FilterBuilder) that specifies which documents to keep. |

#### Returns

[`OrderedQuery`](/api/interfaces/server.OrderedQuery)\<`TableInfo`>

* A new [OrderedQuery](/api/interfaces/server.OrderedQuery) with the given filter predicate applied.

***

### paginate

▸ **paginate**(`paginationOpts`): `Promise`\<[`PaginationResult`](/api/interfaces/server.PaginationResult)\<[`DocumentByInfo`](/api/modules/server#documentbyinfo)\<`TableInfo`>>>

Load a page of `n` results and obtain a [Cursor](/api/modules/server#cursor) for loading more.

Note: If this is called from a reactive query function the number of
results may not match `paginationOpts.numItems`!

`paginationOpts.numItems` is only an initial value. After the first invocation,
`paginate` will return all items in the original query range. This ensures
that all pages will remain adjacent and non-overlapping.

#### Parameters

| Name | Type | Description |
| :- | :- | :- |
| `paginationOpts` | [`PaginationOptions`](/api/interfaces/server.PaginationOptions) | A [PaginationOptions](/api/interfaces/server.PaginationOptions) object containing the number of items to load and the cursor to start at. |

#### Returns

`Promise`\<[`PaginationResult`](/api/interfaces/server.PaginationResult)\<[`DocumentByInfo`](/api/modules/server#documentbyinfo)\<`TableInfo`>>>

A [PaginationResult](/api/interfaces/server.PaginationResult) containing the page of results and a
cursor to continue paginating.

***

### collect

▸ **collect**(): `Promise`\<[`DocumentByInfo`](/api/modules/server#documentbyinfo)\<`TableInfo`>\[]>

Execute the query and return all of the results as an array.

**Warning:** This loads every matching document into memory. If the result
set can grow unbounded as your database grows, `.collect()` will eventually
cause performance problems or hit limits. Only use `.collect()` when the
result set is tightly bounded (e.g., a known small number of items).

Prefer `.first()`, `.unique()`, `.take(n)`, or `.paginate()` when the
result set may be large or unbounded. For processing many results without
loading all into memory, use the `Query` as an `AsyncIterable` with
`for await...of`.

#### Returns

`Promise`\<[`DocumentByInfo`](/api/modules/server#documentbyinfo)\<`TableInfo`>\[]>

* An array of all of the query's results.

***

### take

▸ **take**(`n`): `Promise`\<[`DocumentByInfo`](/api/modules/server#documentbyinfo)\<`TableInfo`>\[]>

Execute the query and return the first `n` results.

#### Parameters

| Name | Type | Description |
| :- | :- | :- |
| `n` | `number` | The number of items to take. |

#### Returns

`Promise`\<[`DocumentByInfo`](/api/modules/server#documentbyinfo)\<`TableInfo`>\[]>

* An array of the first `n` results of the query (or less if the
  query doesn't have `n` results).

***

### first

▸ **first**(): `Promise`\<`null` | [`DocumentByInfo`](/api/modules/server#documentbyinfo)\<`TableInfo`>>

Execute the query and return the first result if there is one.

#### Returns

`Promise`\<`null` | [`DocumentByInfo`](/api/modules/server#documentbyinfo)\<`TableInfo`>>

* The first value of the query or `null` if the query returned no results.

***

### unique

▸ **unique**(): `Promise`\<`null` | [`DocumentByInfo`](/api/modules/server#documentbyinfo)\<`TableInfo`>>

Execute the query and return the singular result if there is one.

Use this when you expect exactly zero or one result, for example when
querying by a unique field. If the query matches more than one document,
this will throw an error.

**`Example`**

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
const user = await ctx.db
  .query("users")
  .withIndex("by_email", (q) => q.eq("email", "alice@example.com"))
  .unique();
```

**`Throws`**

Will throw an error if the query returns more than one result.

#### Returns

`Promise`\<`null` | [`DocumentByInfo`](/api/modules/server#documentbyinfo)\<`TableInfo`>>

* The single result returned from the query or null if none exists.

***

### \[asyncIterator]

▸ **\[asyncIterator]**(): `AsyncIterator`\<[`DocumentByInfo`](/api/modules/server#documentbyinfo)\<`TableInfo`>, `any`, `undefined`>

#### Returns

`AsyncIterator`\<[`DocumentByInfo`](/api/modules/server#documentbyinfo)\<`TableInfo`>, `any`, `undefined`>

#### Inherited from

AsyncIterable.\[asyncIterator]