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

# Read Documents

> Find and query documents with the Query Builder

## executeUnique

Find a single document by any field. Returns the latest version by timestamp.

```typescript TypeScript theme={null}
const user = await client.queryBuilder()
  .collection('users')
  .whereField('email').equals('alice@example.com')
  .executeUnique<User>();

if (user) {
  console.log('Found user:', user.name);
} else {
  console.log('User not found');
}
```

### Return Value

Returns `T | null` - the document if found, or `null` if not found.

## execute (Find Many)

Find multiple documents with filters and options.

```typescript TypeScript theme={null}
const result = await client.queryBuilder()
  .collection('users')
  .whereField('active').isTrue()
  .orderBy('createdAt', 'DESC')
  .limit(10)
  .offset(0)
  .execute<User>();

console.log(`Found ${result.records.length} active users`);
```

### QueryResponse

| Field     | Type     | Description                       |
| --------- | -------- | --------------------------------- |
| `records` | `T[]`    | Array of matching documents       |
| `total`   | `number` | Total count of matching documents |
| `error`   | `string` | Error message if query failed     |

## count

Count documents matching a filter.

```typescript TypeScript theme={null}
const count = await client.queryBuilder()
  .collection('users')
  .whereField('active').isTrue()
  .count();
console.log(`Active users: ${count}`);
```

## Examples

### Find by ID

```typescript TypeScript theme={null}
const user = await client.queryBuilder()
  .collection('users')
  .whereField('id').equals('user_123')
  .executeUnique<User>();
```

### Find with Pagination

```typescript TypeScript theme={null}
// Page 1
const page1 = await client.queryBuilder()
  .collection('posts')
  .orderBy('createdAt', 'DESC')
  .limit(10)
  .offset(0)
  .execute();

// Page 2
const page2 = await client.queryBuilder()
  .collection('posts')
  .orderBy('createdAt', 'DESC')
  .limit(10)
  .offset(10)
  .execute();
```

### Select Specific Fields

```typescript TypeScript theme={null}
const users = await client.queryBuilder()
  .collection('users')
  .whereField('active').isTrue()
  .selectFields(['id', 'name', 'email'])
  .orderBy('createdAt', 'DESC')
  .limit(50)
  .execute();
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Update" icon="pen" href="/crud/update">
    Update existing documents
  </Card>

  <Card title="Query Builder" icon="magnifying-glass" href="/querying/query-builder">
    Complex queries with operators
  </Card>
</CardGroup>