Get Documents Command
-
Use the low-level
GetDocumentsCommand
to retrieve documents from the database. -
To retrieve documents using a higher-level method, see loading entities or query for documents.
-
In this page:
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.
Get document command - using the Store's request executor:
// 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;
Get document command - using the Session's request executor:
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
Get multiple documents:
// 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];
Get multiple documents - missing documents:
// 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
// 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.
// 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
Retrieve documents that match a specified ID prefix:
// 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];
Retrieve documents that match a specified ID prefix - with "matches" pattern:
// 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));
Retrieve documents that match a specified ID prefix - with "exclude" pattern:
// 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
Include related documents:
// 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];
Include counters:
// 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"];
Include time series:
// 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;
Include revisions:
// 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;
// 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;
Include compare-exchange values:
// 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
// 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.( ? any single character, * any characters). |
exclude | string |
Pipe ('|') separated values for which document IDs (after startsWith ) should Not be matched.( ? any single character, * any characters). |
// The `GetDocumentCommand` result object:
// =======================================
{
includes; // object
results; // any[]
counterIncludes; // object
revisionIncludes; // any[]
timeSeriesIncludes; // object
compareExchangeValueIncludes; // object
}