---
title: "Get Documents Command"
url: "https://docs.ravendb.net/6.2/client-api/commands/documents/get"
version: "6.2"
language: "php"
---

# Get Documents Command

> Client language: PHP. Also available for [C#](https://docs.ravendb.net/6.2/client-api/commands/documents/get.md), [Java](https://docs.ravendb.net/6.2/client-api/commands/documents/get.java.md), [Python](https://docs.ravendb.net/6.2/client-api/commands/documents/get.python.md), [Node.js](https://docs.ravendb.net/6.2/client-api/commands/documents/get.nodejs.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

> **Note**
>
> - Use `GetDocumentsCommand` to retrieve documents from the database.
>
> - In this page:
>   - [Get single document](#get-single-document)
>   - [Get multiple documents](#get-multiple-documents)
>   - [Get paged documents](#get-paged-documents)
>   - [Get documents by ID prefix](#get-documents-by-id-prefix)

## Get single document

**GetDocumentsCommand** can be used to retrieve a single document

#### Syntax:

```php
public static function forSingleDocument(string $id, StringArray|array|null $includes = null, bool $metadataOnly = false): GetDocumentsCommand;
```

| Parameters | Type | Description |
| - | - | - |
| **id** | `string` | ID of the documents to get |
| **includes** | `StringArray` or `array` or `null` | Related documents to fetch along with the document |
| **metadataOnly** | `bool` | Whether to fetch the whole document or just its metadata. |

#### Example:

```php
$command = GetDocumentsCommand::forSingleDocument("orders/1-A", null, false);
$session->advanced()->getRequestExecutor()->execute($command);

/** @var GetDocumentsResult $documentsResult */
$documentsResult = $command->getResult();
$order = $documentsResult->getResults()[0];
```

## Get multiple documents

**GetDocumentsCommand** can also be used to retrieve a list of documents.

#### Syntax:

```php
public static function forMultipleDocuments(StringArray|array|null $ids, StringArray|array|null $includes, bool $metadataOnly = false): GetDocumentsCommand;
```

| Parameters | Type | Description |
| - | - | - |
| **ids** | `StringArray` or `array` or `null` | IDs of the documents to get |
| **includes** | `StringArray` or `array` or `null` | Related documents to fetch along with the documents |
| **metadataOnly** | `bool` | Whether to fetch whole documents or just the metadata |

#### Example I

```php
$command = GetDocumentsCommand::forMultipleDocuments(["orders/1-A", "employees/3-A"], null, false);
$session->advanced()->getRequestExecutor()->execute($command);

/** @var GetDocumentsResult $result */
$result = $command->getResult();
$order = $result->getResults()[0];
$employee = $result->getResults()[1];
```

#### Example II - Using Includes

```php
// Fetch employees/5-A and his boss.
$command = GetDocumentsCommand::forSingleDocument("employees/5-A", [ "ReportsTo" ], false);
$session->advanced()->getRequestExecutor()->execute($command);
/** @var GetDocumentsResult $result */
$result = $command->getResult();
$employee = $result->getResults()[0];
if (array_key_exists("ReportsTo", $employee)) {
  $bossId = $employee["ReportsTo"];

  $boss = $result->getIncludes()[$bossId];
}
```

#### Example III - Missing Documents

```php
// Assuming that products/9999-A doesn't exist.
$command = GetDocumentsCommand::forMultipleDocuments([ "products/1-A", "products/9999-A", "products/3-A" ], null, false);
$session->advanced()->getRequestExecutor()->execute($command);

/** @var GetDocumentsResult $result */
$result = $command->getResult();
$products = $result->getResults(); // products/1-A, null, products/3-A
```

## Get paged documents

**GetDocumentsCommand** can also be used to retrieve a paged set of documents.

#### Syntax:

```php
public static function withStartAndPageSize(int $start, int $pageSize): GetDocumentsCommand;
```

| Parameters | Type | Description |
| - | - | - |
| **start** | `int` | number of documents that should be skipped |
| **pageSize** | `int` | maximum number of documents that will be retrieved |

#### Example:

```php
$command = GetDocumentsCommand::withStartAndPageSize(0, 128);
$session->advanced()->getRequestExecutor()->execute($command);

/** @var GetDocumentsResult $result */
$result = $command->getResult();
$firstDocs = $result->getResults();
```

## Get documents by ID prefix

**GetDocumentsCommand** can be used to retrieve multiple documents for a specified ID prefix.

#### Syntax:

```php
public static function withStartWith(
  ?string $startWith,
  ?string $startAfter,
  ?string $matches,
  ?string $exclude,
  int $start,
  int $pageSize,
  bool $metadataOnly
): GetDocumentsCommand;
```

| Parameters | Type | Description |
| - | - | - |
| **startWith** | `?string` | prefix for which documents should be returned |
| **startAfter** | `?string` | skip 'document fetching' until the given ID is found, and return documents after that ID (default: None) |
| **matches** | `?string` | pipe ('\|') separated values for which document IDs (after `startWith`) should be matched ('?' any single character, '\*' any characters) |
| **exclude** | `?string` | pipe ('\|') separated values for which document IDs (after `startWith`) should **not** be matched ('?' any single character, '\*' any characters) |
| **start** | `int` | number of documents that should be skipped |
| **pageSize** | `int` | maximum number of documents that will be retrieved |
| **metadataOnly** | `bool` | specifies whether or not only document metadata should be returned |

#### Example I

```php
// return up to 128 documents with key that starts with 'products'
$command = GetDocumentsCommand::withStartWith(
  startWith: "products",
  startAfter: null,
  matches: null,
  exclude: null,
  start: 0,
  pageSize: 128,
  metadataOnly: false);
$session->advanced()->getRequestExecutor()->execute($command);

/** @var GetDocumentsResult $result */
$result = $command->getResult();
$products = $result->getResults();
```

#### Example II

```php
// return up to 128 documents with key that starts with 'products/'
// and rest of the key begins with "1" or "2" e.g. products/10, products/25
$command = GetDocumentsCommand::withStartWith(
  startWith: "products",
  startAfter: null,
  matches: "1*|2*",
  exclude: null,
  start: 0,
  pageSize: 128,
  metadataOnly: false);
$session->advanced()->getRequestExecutor()->execute($command);

/** @var GetDocumentsResult $result */
$result = $command->getResult();
$products = $result->getResults();
```

#### Example III

```php
// return up to 128 documents with key that starts with 'products/'
// and rest of the key have length of 3, begins and ends with "1"
// and contains any character at 2nd position e.g. products/101, products/1B1
$command = GetDocumentsCommand::withStartWith(
  startWith: "products",
  startAfter: null,
  matches: "1?1",
  exclude: null,
  start: 0,
  pageSize: 128,
  metadataOnly: false);

$session->advanced()->getRequestExecutor()->execute($command);

/** @var GetDocumentsResult $result */
$result = $command->getResult();
$products = $result->getResults();
```

## See also

- [Put document](https://docs.ravendb.net/6.2/client-api/commands/documents/put.php.md)
- [Delete document](https://docs.ravendb.net/6.2/client-api/commands/documents/delete.php.md)
- [Send multiple commands using a batch](https://docs.ravendb.net/6.2/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.md)
