Commands: Get Documents

• Use GetDocumentsCommand to retrieve documents from the database.

• In this page:

  • Get single document
  • Get multiple documents
  • Get paged documents
  • Get documents by ID prefix

Get single document

GetDocumentsCommand can be used to retrieve a single document

Syntax:

public GetDocumentsCommand(string id, string[] includes, bool metadataOnly)

Parameters	Type	Description
id	string	ID of the documents to get
includes	string[]	Related documents to fetch along with the document
metadataOnly	boolean	Whether to fetch the whole document or just the metadata.

Example:

var command = new GetDocumentsCommand("orders/1-A", null, false);
session.Advanced.RequestExecutor.Execute(command, session.Advanced.Context);
var order = (BlittableJsonReaderObject)command.Result.Results[0];

Get multiple documents

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

Syntax:

public GetDocumentsCommand(string[] ids, string[] includes, bool metadataOnly)

Parameters	Type	Description
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

Example I

var command = new GetDocumentsCommand(new[] { "orders/1-A", "employees/3-A" }, null, false);
session.Advanced.RequestExecutor.Execute(command, session.Advanced.Context);
var order = (BlittableJsonReaderObject)command.Result.Results[0];
var employee = (BlittableJsonReaderObject)command.Result.Results[1];

Example II - Using Includes

// Fetch employees/5-A and his boss.
var command = new GetDocumentsCommand("employees/5-A", includes: new[] { "ReportsTo" }, metadataOnly: false);
session.Advanced.RequestExecutor.Execute(command, session.Advanced.Context);
var employee = (BlittableJsonReaderObject)command.Result.Results[0];
if (employee.TryGet<string>("ReportsTo", out var bossId))
{
  var boss = command.Result.Includes[bossId];
}

Example III - Missing Documents

// Assuming that products/9999-A doesn't exist.
var command = new GetDocumentsCommand(new[] { "products/1-A", "products/9999-A", "products/3-A" }, null, false);
session.Advanced.RequestExecutor.Execute(command, session.Advanced.Context);
var 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:

public GetDocumentsCommand(int start, int pageSize)

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

Example:

var command = new GetDocumentsCommand(start: 0, pageSize: 128);
session.Advanced.RequestExecutor.Execute(command, session.Advanced.Context);
var firstDocs = command.Result.Results;

Get documents by ID prefix

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

Syntax:

public GetDocumentsCommand(string startWith, string startAfter, string matches, string exclude, int start, int pageSize, bool metadataOnly)

Parameters	Type	Description
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	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

// return up to 128 documents with key that starts with 'products'
var command = new GetDocumentsCommand(
  startWith: "products",
  startAfter: null,
  matches: null,
  exclude: null,
  start: 0,
  pageSize: 128,
  metadataOnly: false);
session.Advanced.RequestExecutor.Execute(command, session.Advanced.Context);
var 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" e.g. products/10, products/25
var command = new GetDocumentsCommand(
  startWith: "products",
  startAfter: null,
  matches: "1*|2*",
  exclude: null,
  start: 0,
  pageSize: 128,
  metadataOnly: false);
session.Advanced.RequestExecutor.Execute(command, session.Advanced.Context);
var products = command.Result.Results;

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
var command = new GetDocumentsCommand(
  startWith: "products",
  startAfter: null,
  matches: "1?1",
  exclude: null,
  start: 0,
  pageSize: 128,
  metadataOnly: false);
session.Advanced.RequestExecutor.Execute(command, session.Advanced.Context);
var products = command.Result.Results;