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

# Get Documents Command

> Client language: Node.js. 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), [PHP](https://docs.ravendb.net/6.2/client-api/commands/documents/get.php.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 the low-level `GetDocumentsCommand` to retrieve documents from the database.
>
> - To retrieve documents using a higher-level method, see [loading entities](https://docs.ravendb.net/6.2/client-api/session/loading-entities.nodejs.md) or [query for documents](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.nodejs.md).
>
> - In this page:
>   - [Get single document](#get-single-document)
>   - [Get multiple documents](#get-multiple-documents)
>   - [Get metadata only](#get-metadata-only)
>   - [Get paged documents](#get-paged-documents)
>   - [Get documents - by ID prefix](#get-documents---by-id-prefix)
>   - [Get documents - with includes](#get-documents---with-includes)
>   - [Syntax](#syntax)

## Get single document

- The following examples demonstrate how to retrieve a document using either the *Store's request executor*  
  or the *Session's request executor*.
- The examples in the rest of the article use the *Store's request executor*, but you can apply the Session's implementation shown here to ALL cases.

> **Note**
>
> **Get document command - using the Store's request executor**:
>
> ```javascript
> // Define the 'GetDocumentsCommand'
> const command = new GetDocumentsCommand({
>   conventions: documentStore.conventions,
>   id: "orders/1-A"
> });
>
> // Call 'execute' on the Store's Request Executor to send the command to the server
> await documentStore.getRequestExecutor().execute(command);
>
> // Access the results
> const order = command.result.results[0];
> const orderedAt = order.OrderedAt;
> ```

> **Note**
>
> **Get document command - using the Session's request executor**:
>
> ```javascript
> const session = documentStore.openSession();
>
> // Define the 'GetDocumentsCommand'
> const command = new GetDocumentsCommand({ 
>     conventions: documentStore.conventions, 
>     id: "orders/1-A"
> });
>
> // Call 'execute' on the Session's Request Executor to send the command to the server
> await session.advanced.requestExecutor.execute(command);
>
> // Access the results
> const order = command.result.results[0];
> const orderedAt = order.OrderedAt;
> ```

## Get multiple documents

> **Note**
>
> **Get multiple documents**:
>
> ```javascript
> // Pass a list of document IDs to the get command
> const command = new GetDocumentsCommand({
>   conventions: documentStore.conventions,
>   ids: ["orders/1-A", "employees/2-A", "products/1-A"]
> });
>
> await documentStore.getRequestExecutor().execute(command);
>
> // Access results
> const order = command.result.results[0];
> const employee = command.result.results[1];
> const product = command.result.results[2];
> ```

> **Note**
>
> **Get multiple documents - missing documents**:
>
> ```javascript
> // Assuming that employees/9999-A doesn't exist
> const command = new GetDocumentsCommand({
>   conventions: documentStore.conventions,
>   ids: [ "orders/1-A", "employees/9999-A", "products/3-A" ]
> });
>
> await documentStore.getRequestExecutor().execute(command);
>
> // Results will contain 'null' for any missing document
> const results = command.result.results; // orders/1-A, null, products/3-A
> assert.equal(results[1], null);
> ```

## Get metadata only

```javascript
// Pass 'true' in the 'metadataOnly' param to retrieve only the document METADATA
const command = new GetDocumentsCommand({
  conventions: documentStore.conventions,
  id: "orders/1-A",
  metadataOnly: true
});

await documentStore.getRequestExecutor().execute(command);

// Access results
const results = command.result.results[0];
const metadata = results["@metadata"];

// Print out all metadata properties
for (const propertyName in metadata) {
  console.log(`${propertyName} = ${metadata[propertyName]}`);
}
```

## Get paged documents

- You can retrieve documents in pages by specifying how many documents to skip and how many to fetch.
- Using this overload, no specific collection is specified, the documents will be fetched from ALL collections.

```javascript
// Specify the number of documents to skip (start)
// and the number of documents to get (pageSize)
const command = new GetDocumentsCommand({
  conventions: documentStore.conventions,
  start: 0,
  pageSize: 128
});

await documentStore.getRequestExecutor().execute(command);

// The documents are sorted by the last modified date,
// with the most recent modifications appearing first.
const firstDocs = command.result.results;
```

## Get documents - by ID prefix

> **Note**
>
> **Retrieve documents that match a specified ID prefix**:
>
> ```javascript
> // Return up to 50 documents with ID that starts with 'products/'
> const command = new GetDocumentsCommand({
>   conventions: documentStore.conventions,
>   startsWith: "products/",  
>   start: 0, 
>   pageSize: 50
> });
>
> await documentStore.getRequestExecutor().execute(command);
>
> // Access a Product document
> const product = command.result.results[0];
> ```

> **Note**
>
> **Retrieve documents that match a specified ID prefix - with "matches" pattern**:
>
> ```javascript
> // Return up to 50 documents with IDs that start with 'orders/'
> // and the rest of the ID either begins with '23',
> // or contains any character at the 1st position and ends with '10-A'
> // e.g. orders/234-A, orders/810-A
> const command = new GetDocumentsCommand({
>   conventions: documentStore.conventions,
>   startsWith: "orders/", 
>   matches: "23*|?10-A", 
>   start: 0, 
>   pageSize: 50
> });
>
> await documentStore.getRequestExecutor().execute(command);
>
> // Access an Order document
> const order = command.result.results[0];
>
> const orderId = order["@metadata"]["@id"];
> assert.ok(orderId.startsWith("orders/23") || /^orders\/.{1}10-A$/.test(orderId));
> ```

> **Note**
>
> **Retrieve documents that match a specified ID prefix - with "exclude" pattern**:
>
> ```javascript
> // Return up to 50 documents with IDs that start with 'orders/'
> // and the rest of the ID excludes documents ending with '10-A',
> // e.g. will return orders/820-A, but not orders/810-A
> const command = new GetDocumentsCommand({
>   conventions: documentStore.conventions,
>   startsWith: "orders/",
>   exclude: "*10-A",
>   start: 0,
>   pageSize: 50
> });
>
> await documentStore.getRequestExecutor().execute(command);
>
> // Access an Order document
> const order = command.result.results[0];
>
> const orderId = order["@metadata"]["@id"];
> assert.ok(orderId.startsWith("orders/") && !orderId.endsWith("10-A"));
> ```

## Get documents - with includes

> **Note**
>
> **Include related documents**:
>
> ```javascript
> // Fetch document products/77-A and include its related Supplier document
> const command = new GetDocumentsCommand({
>   conventions: documentStore.conventions,
>   id: "products/77-A",
>   includes: [ "Supplier" ]
> });
>
> await documentStore.getRequestExecutor().execute(command);
>
> // Access the related document that was included
> const product = command.result.results[0];
> const supplierId = product["Supplier"];
> const supplier = command.result.includes[supplierId];
> ```

> **Note**
>
> **Include counters**:
>
> ```javascript
> // Fetch document products/77-A and include the specified counters
> const command = new GetDocumentsCommand({
>   conventions: documentStore.conventions,
>   id: "products/77-A",
>   // Pass the names of the counters to include. In this example,
>   // the counter names in RavenDB's sample data are stars... 
>   counterIncludes: ["⭐", "⭐⭐"]
> });
>
> await documentStore.getRequestExecutor().execute(command);
>
> // Access the included counters results
> const counters = command.result.counterIncludes["products/77-A"]
> const counter = counters[0];
>
> const counterName = counter["counterName"];
> const counterValue = counter["totalValue"];
> ```

> **Note**
>
> **Include time series**:
>
> ```javascript
> // Fetch document employees/1-A and include the specified time series
> const command = new GetDocumentsCommand({
>   conventions: documentStore.conventions,
>   ids: ["employees/1-A"],
>   // Specify the time series name and the time range
>   timeSeriesIncludes: [
>       {
>           name: "HeartRates",
>           from: new Date("2020-04-01T00:00:00.000Z"),
>           to: new Date("2024-12-31T00:00:00.000Z")
>       }
>   ]
> });
>
> await documentStore.getRequestExecutor().execute(command);
>
> // Access the included time series results
> const timeseries = command.result.timeSeriesIncludes["employees/1-A"];
> const tsEntries = timeseries["HeartRates"][0].entries;
>
> const entryTimeStamp = tsEntries[0].timestamp;
> const entryValues = tsEntries[0].values;
> ```

> **Note**
>
> **Include revisions**:
>
> ```javascript
> // Fetch document orders/826-A and include the specified revisions
> const command = new GetDocumentsCommand({
>   conventions: documentStore.conventions,
>   ids: ["orders/826-A"],
>   // Specify list of document fields (part of document orders/826-A),
>   // where each field is expected to contain the change-vector
>   // of the revision you wish to include.
>   revisionsIncludesByChangeVector: [
>       "RevisionChangeVectorField1",
>       "RevisionChangeVectorField2"
>   ]
> });
>
> await documentStore.getRequestExecutor().execute(command);
>
> // Access the included revisions
> const revisionObj = command.result.revisionIncludes[0];
> const revision = revisionObj.Revision;    
> ```
>
> ```javascript
> // Fetch document orders/826-A and include the specified revisions
> const command = new GetDocumentsCommand({
>   conventions: documentStore.conventions,
>   ids: ["orders/826-A"],
>   // Another option is to specify a single document field (part of document orders/826-A).
>   // This field is expected to contain a list of all the change-vectors
>   // for the revisions you wish to include.
>   revisionsIncludesByChangeVector: [
>       "RevisionsChangeVectors"
>   ]
> });
>
> await documentStore.getRequestExecutor().execute(command);
>
> // Access the included revisions
> const revisionObj = command.result.revisionIncludes[0];
> const revision = revisionObj.Revision;
> ```

> **Note**
>
> **Include compare-exchange values**:
>
> ```javascript
> // Fetch document orders/826-A and include the specified compare-exchange
> const command = new GetDocumentsCommand({
>   conventions: documentStore.conventions,
>   ids: ["orders/826-A"],
>   // Similar to the previous "include revisions" examples,
>   // EITHER:
>   // Specify a list of document fields (part of document orders/826-A),
>   // where each field is expected to contain a compare-exchange KEY
>   // for the compare-exchange item you wish to include
>   // OR:
>   // Specify a single document field that contains a list of all keys to include.
>   compareExchangeValueIncludes: [
>       "CmpXchgItemField1",
>       "CmpXchgItemField2"
>   ]
> });
>
> await documentStore.getRequestExecutor().execute(command);
>
> // Access the included compare-exchange items
> const cmpXchgItems = command.result.compareExchangeValueIncludes;
>
> const cmpXchgItemKey = Object.keys(cmpXchgItems)[0];
> const cmpXchgItemValue = cmpXchgItem[cmpXchgItemKey].value.Object;
> ```

## Syntax

```javascript
// Available overloads:
// ====================

new GetDocumentsCommand({
  conventions, id, 
  includes?, counterIncludes?, includeAllCounters?, metadataOnly? 
});

new GetDocumentsCommand({
  conventions, ids,
  includes?, timeSeriesIncludes?, compareExchangeValueIncludes?,
  revisionsIncludesByChangeVector?, revisionIncludeByDateTimeBefore?, 
  counterIncludes?, includeAllCounters?, metadataOnly?
});

new GetDocumentsCommand({
  conventions, start, pageSize, 
  startsWith?, startsAfter?, matches?, exclude?,
  counterIncludes?, includeAllCounters?, metadataOnly?
});
```

| Parameter | Type | Description |
| - | - | - |
| **conventions** | `DocumentConventions` | The store's conventions. |
| **id** | `string` | ID of the document to get. |
| **ids** | `string[]` | IDs of the documents to get. |
| **includes** | `string[]` | Related documents to fetch along with the document. |
| **counterIncludes** | `string[]` | Counters to fetch along with the document. |
| **includeAllCounters** | `boolean` | Whether to include all counters. |
| **timeSeriesIncludes** | `AbstractTimeSeriesRange[]` | Time series to fetch along with the document. |
| **compareExchangeValueIncludes** | `string[]` | List of document fields containing cmpXchg keys of the compare-exchange items you wish to include. |
| **revisionsIncludesByChangeVector** | `string[]` | List of document fields containing the change-vectors of the revisions you wish to include. |
| **revisionIncludeByDateTimeBefore** | `Date` | When this date is provided, retrieve the most recent revision that was created before this date value. |
| **metadataOnly** | `boolean` | Whether to fetch the whole document or just the metadata. |
| **start** | `number` | Number of documents that should be skipped. |
| **pageSize** | `number` | Maximum number of documents that will be retrieved. |
| **startsWith** | `string` | Fetch only documents with this prefix. |
| **startAfter** | `string` | Skip 'document fetching' until the given ID is found, and return documents after that ID (default: null). |
| **matches** | `string` | Pipe ('\|') separated values for which document IDs (after `startsWith`) should be matched.<br />(`?` any single character, `*` any characters). |
| **exclude** | `string` | Pipe ('\|') separated values for which document IDs (after `startsWith`) should Not be matched.<br />(`?` any single character, `*` any characters). |

```javascript
// The `GetDocumentCommand` result object:
// =======================================

{
  includes;                     // object
  results;                      // any[]
  counterIncludes;              // object
  revisionIncludes;             // any[]
  timeSeriesIncludes;           // object
  compareExchangeValueIncludes; // object
}
```

## See also

- [Put document](https://docs.ravendb.net/6.2/client-api/commands/documents/put.nodejs.md)
- [Delete document](https://docs.ravendb.net/6.2/client-api/commands/documents/delete.nodejs.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.nodejs.md)
