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

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

Parameters
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
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
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 first10Docs = command.Result.Results;

Get by starts with

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
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;