see on GitHub

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;