Skip to Navigation
Commands: Documents: Get
There are a few methods that allow you to retrieve documents from a database:
Get single document
GetDocumentsCommand can be used to retrieve a single document
Syntax
new GetDocumentsCommand({
id,
includes,
metadataOnly,
conventions
});| Parameters | ||
|---|---|---|
| options | object | |
| id | string | ID of the document to get |
| includes | string[] | Related documents to fetch along with the document |
| metadataOnly | boolean | Whether to fetch the whole document or just the metadata. |
| conventions | DocumentConventions | Document conventions |
Example
const command = new GetDocumentsCommand({ id: "orders/1-A" });
await session.advanced.getRequestExecutor().execute(command);
const order = command.result.results[0];
Get multiple documents
GetDocumentsCommand can also be used to retrieve a list of documents.
Syntax
new GetDocumentsCommand({
ids,
includes,
metadataOnly,
conventions
});| Parameters | ||
|---|---|---|
| options | object | |
| ids | string[] | IDs of the documents to get |
| includes | string[] | Related documents to fetch along with the documents |
| metadataOnly | boolean | Whether to fetch whole documents or just the metadata |
| conventions | DocumentConventions | Document conventions |
Example I
const command = new GetDocumentsCommand({
ids: [ "orders/1-A", "employees/3-A" ]
});
await session.advanced.getRequestExecutor().execute(command);
const order = command.result.results[0];
const employee = command.result.results[1];Example II - Using Includes
// Fetch emploees/5-A and his boss.
const command = new GetDocumentsCommand({
id: "employees/5-A",
includes: [ "ReportsTo" ]
});
await session.advanced.getRequestExecutor().execute(command);
const employee = command.result.results[0];
const bossId = employee.ReportsTo;
const boss = command.result.includes[bossId];Example III - Missing Documents
// Assuming that products/9999-A doesn't exist.
const command = new GetDocumentsCommand({
ids: [ "products/1-A", "products/9999-A", "products/3-A" ]
});
await session.advanced.getRequestExecutor().execute(command);
const products = command.result.results; // products/1-A, null, products/3-A
Get paged documents
GetDocumentsCommand can also be used to retrieve a paged set of documents.
Syntax
new GetDocumentsCommand({
start,
pageSize,
conventions
});| Parameters | ||
|---|---|---|
| options | object | |
| start | number | number of documents that should be skipped |
| pageSize | number | maximum number of documents that will be retrieved |
| conventions | DocumentConventions | Document conventions |
Example
const command = new GetDocumentsCommand({
start: 0,
pageSize: 128
});
await session.advanced.getRequestExecutor().execute(command);
const firstDocs = command.result.results;
Get by starts with
GetDocumentsCommand can be used to retrieve multiple documents for a specified ID prefix.
Syntax
new GetDocumentsCommand({
start,
pageSize,
startsWith,
startsAfter,
matches,
exclude,
metadataOnly,
conventions
});| Parameters | ||
|---|---|---|
| options | object | |
| startsWith | 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: 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) |
| start | number | number of documents that should be skipped |
| pageSize | number | maximum number of documents that will be retrieved |
| metadataOnly | boolean | specifies whether or not only document metadata should be returned |
| conventions | DocumentConventions | Document conventions |
Example I
const command = new GetDocumentsCommand({
startsWith: "products",
start: 0,
pageSize: 128
});
await session.advanced.getRequestExecutor().execute(command);
const products = command.result.results;Example II
// return up to 128 documents with key that starts with 'products/'
// and rest of the key begins with "1" or "2", eg. products/10, products/25
const command = new GetDocumentsCommand({
startsWith: "products",
matches: "1*|2*",
start: 0,
pageSize: 128
});Example III
// 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
const command = new GetDocumentsCommand({
startsWith: "products",
matches: "1?1",
start: 0,
pageSize: 128
});
await session.advanced.getRequestExecutor().execute(command);
const products = command.result.results;
Related Articles