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:

Get_document
Get_document_async

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // Define the 'GetDocumentsCommand'
  var command = new GetDocumentsCommand(store.Conventions,
      "orders/1-A", null, metadataOnly: false);
  
  // Call 'Execute' on the Store's Request Executor to send the command to the server
  store.GetRequestExecutor().Execute(command, context);
  
  // Access the results
  var blittable = (BlittableJsonReaderObject)command.Result.Results[0];
  
  // Deserialize the blittable JSON into a strongly-typed 'Order' object
  var order = (Order)store.Conventions.Serialization.DefaultConverter
      .FromBlittable(typeof(Order), blittable);
  
  var orderedAt = order.OrderedAt;
}

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // Define the 'GetDocumentsCommand'
  var command = new GetDocumentsCommand(store.Conventions,
      "orders/1-A", null, metadataOnly: false);
  
  // Call 'ExecuteAsync' on the Store's Request Executor to send the command to the server
  await store.GetRequestExecutor().ExecuteAsync(command, context);
  
  // Access the results
  var blittable = (BlittableJsonReaderObject)command.Result.Results[0];
  
  // Deserialize the blittable JSON into a strongly-typed 'Order' object
  var order = (Order)store.Conventions.Serialization.DefaultConverter
      .FromBlittable(typeof(Order), blittable);
  
  var orderedAt = order.OrderedAt;
}

Get document command - using the Session's request executor:

Get_document
Get_document_async

using (var store = new DocumentStore())
using (var session = store.OpenSession())
{
  // Define the 'GetDocumentsCommand'
  var command = new GetDocumentsCommand(store.Conventions,
      "orders/1-A", null, metadataOnly: false);
  
  // Call 'Execute' on the Session's Request Executor to send the command to the server
  session.Advanced.RequestExecutor.Execute(command, session.Advanced.Context);
  
  // Access the results
  var blittable  = (BlittableJsonReaderObject)command.Result.Results[0];
  
  // Deserialize the blittable JSON into a strongly-typed 'Order' object
  // Setting the last param to 'true' will cause the session to track the 'Order' entity
  var order = session.Advanced.JsonConverter.FromBlittable<Order>(ref blittable,
      "orders/1-A", trackEntity: true);

  var orderedAt = order.OrderedAt;
}

using (var store = new DocumentStore())
using (var asyncSession = store.OpenAsyncSession())
{
  // Define the 'GetDocumentsCommand'
  var command = new GetDocumentsCommand(store.Conventions,
      "orders/1-A", null, metadataOnly: false);
  
  // Call 'ExecuteAsync' on the Session's Request Executor to send the command to the server
  await asyncSession.Advanced.RequestExecutor.ExecuteAsync(
      command, asyncSession.Advanced.Context);
  
  // Access the results
  var blittable  = (BlittableJsonReaderObject)command.Result.Results[0];
  
  // Deserialize the blittable JSON into a strongly-typed 'Order' object
  // Setting the last param to 'true' will cause the session to track the 'Order' entity
  var order = asyncSession.Advanced.JsonConverter.FromBlittable<Order>(ref blittable,
      "orders/1-A", trackEntity: true);

  var orderedAt = order.OrderedAt;
}

Get multiple documents

Get multiple documents:

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // Pass a list of document IDs to the get command
  var command = new GetDocumentsCommand(store.Conventions,
      new[] { "orders/1-A", "employees/2-A", "products/1-A" }, null, false);
  
  store.GetRequestExecutor().Execute(command, context);
  
  // Access results
  var orderBlittable = (BlittableJsonReaderObject)command.Result.Results[0];
  var orderDocument = (Order)store.Conventions.Serialization.DefaultConverter
      .FromBlittable(typeof(Order), orderBlittable);
  
  var employeeBlittable = (BlittableJsonReaderObject)command.Result.Results[1];
  var employeeDocument = (Employee)store.Conventions.Serialization.DefaultConverter
      .FromBlittable(typeof(Employee), orderBlittable);
  
  var productBlittable = (BlittableJsonReaderObject)command.Result.Results[2];
  var productDocument = (Product)store.Conventions.Serialization.DefaultConverter
      .FromBlittable(typeof(Product), productBlittable);
}

Get multiple documents - missing documents:

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // Assuming that employees/9999-A doesn't exist
  var command = new GetDocumentsCommand(store.Conventions,
      new[] { "orders/1-A", "employees/9999-A", "products/3-A" }, null, false);
  
  store.GetRequestExecutor().Execute(command, context);
  
  // Results will contain 'null' for any missing document
  var results = command.Result.Results;  // orders/1-A, null, products/3-A
  Assert.Null(results[1]);
}

Get metadata only

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // Pass 'true' in the 'metadataOnly' param to retrieve only the document METADATA
  var command = new GetDocumentsCommand(store.Conventions,
      "orders/1-A", null, metadataOnly: true);
  
  store.GetRequestExecutor().Execute(command, context);
  
  // Access results
  var blittable = (BlittableJsonReaderObject)command.Result.Results[0];
  var documentMetadata = (BlittableJsonReaderObject)blittable["@metadata"];

  // Print out all metadata properties
  foreach (var propertyName in documentMetadata.GetPropertyNames())
  {
      documentMetadata.TryGet<object>(propertyName, out var propertyValue);
      Console.WriteLine("{0} = {1}", propertyName, propertyValue);
  }
}

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.

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // Specify the number of documents to skip (start)
  // and the number of documents to get (pageSize)
  var command = new GetDocumentsCommand(start: 0, pageSize: 128);
  
  store.GetRequestExecutor().Execute(command, context);
  
  // The documents are sorted by the last modified date,
  // with the most recent modifications appearing first.
  var firstDocs = command.Result.Results;
}

Get documents - by ID prefix

Retrieve documents that match a specified ID prefix:

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // Return up to 50 documents with ID that starts with 'products/'
  var command = new GetDocumentsCommand(store.Conventions,
      startWith: "products/",
      startAfter: null,
      matches: null,
      exclude: null,
      start: 0,
      pageSize: 50,
      metadataOnly: false);
  
  store.GetRequestExecutor().Execute(command, context);
  
  // Access a Product document
  var blittable = (BlittableJsonReaderObject)command.Result.Results[0];
  var product = (Product)store.Conventions.Serialization.DefaultConverter
      .FromBlittable(typeof(Product), blittable);
}

Retrieve documents that match a specified ID prefix - with "matches" pattern:

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // 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
  var command = new GetDocumentsCommand(store.Conventions,
      startWith: "orders/",
      startAfter: null,
      matches: "23*|?10-A",
      exclude: null,
      start: 0,
      pageSize: 50,
      metadataOnly: false);
  
  store.GetRequestExecutor().Execute(command, context);
  
  // Access an Order document
  var blittable = (BlittableJsonReaderObject)command.Result.Results[0];
  var order = (Order)store.Conventions.Serialization.DefaultConverter
      .FromBlittable(typeof(Order), blittable);

  Assert.True(order.Id.StartsWith("orders/23") || 
              Regex.IsMatch(order.Id, @"^orders/.{1}10-A$"));
}

Retrieve documents that match a specified ID prefix - with "exclude" pattern:

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // 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
  var command = new GetDocumentsCommand(store.Conventions,
      startWith: "orders/",
      startAfter: null,
      matches: null,
      exclude: "*10-A",
      start: 0,
      pageSize: 50,
      metadataOnly: false);
  
  store.GetRequestExecutor().Execute(command, context);
  
  // Access an Order document
  var blittable = (BlittableJsonReaderObject)command.Result.Results[0];
  var order = (Order)store.Conventions.Serialization.DefaultConverter
      .FromBlittable(typeof(Order), blittable);

  Assert.True(order.Id.StartsWith("orders/") && !order.Id.EndsWith("10-A"));
}

Get documents - with includes

Include related documents:

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // Fetch document products/77-A and include its related Supplier document
  var command = new GetDocumentsCommand(store.Conventions,
      id:"products/77-A",
      includes: new[] { "Supplier" },
      metadataOnly: false);
  
  store.GetRequestExecutor().Execute(command, context);
  
  var productBlittable = (BlittableJsonReaderObject)command.Result.Results[0];
  if (productBlittable.TryGet<string>("Supplier", out var supplierId))
  {
      // Access the related document that was included
      var supplierBlittable = 
          (BlittableJsonReaderObject)command.Result.Includes[supplierId];
      
      var supplier = (Supplier)store.Conventions.Serialization.DefaultConverter
          .FromBlittable(typeof(Supplier), supplierBlittable);
  }
}

Include counters:

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // Fetch document products/77-A and include the specified counters
  var command = new GetDocumentsCommand(store.Conventions,
      ids:new[] {"products/77-A"},
      includes: null, 
      // Pass the names of the counters to include. In this example,
      // the counter names in RavenDB's sample data are stars... 
      counterIncludes: new[] { "⭐", "⭐⭐" },
      timeSeriesIncludes: null,
      compareExchangeValueIncludes: null,
      metadataOnly: false);
  
  store.GetRequestExecutor().Execute(command, context);
 
  // Access the included counters results
  var counters = (BlittableJsonReaderObject)command.Result.CounterIncludes;
  var countersBlittableArray = 
      (BlittableJsonReaderArray)counters["products/77-A"];
  
  var counter = (BlittableJsonReaderObject)countersBlittableArray[0];
  var counterName = counter["CounterName"];
  var counterValue = counter["TotalValue"];
}

Include time series:

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // Fetch document employees/1-A and include the specified time series
  var command = new GetDocumentsCommand(store.Conventions,
      ids:new[] {"employees/1-A"},
      includes: null, 
      counterIncludes: null,
      // Specify the time series name and the time range
      timeSeriesIncludes: new[] { new TimeSeriesRange
      {
          Name = "HeartRates",
          From = DateTime.MinValue,
          To = DateTime.MaxValue
      } },
      compareExchangeValueIncludes:null,
      metadataOnly: false);
  
  store.GetRequestExecutor().Execute(command, context);
 
  // Access the included time series results
  var timeSeriesBlittable = 
      (BlittableJsonReaderObject)command.Result.TimeSeriesIncludes["employees/1-A"];
  
  var timeSeriesBlittableArray = 
      (BlittableJsonReaderArray)timeSeriesBlittable["HeartRates"];
  
  var ts = (BlittableJsonReaderObject)timeSeriesBlittableArray[0];
  var entries = (BlittableJsonReaderArray)ts["Entries"];

  var tsEntry = (BlittableJsonReaderObject)entries[0];
  var entryTimeStamp = tsEntry["Timestamp"];
  var entryValues = tsEntry["Values"];
}

Include revisions:

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // Fetch document orders/826-A and include the specified revisions
  var command = new GetDocumentsCommand(store.Conventions,
      ids:new[] {"orders/826-A"},
      includes: null, 
      counterIncludes: null,
      // 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: new[]
      {
          "RevisionChangeVectorField1",
          "RevisionChangeVectorField2"
      },
      revisionIncludeByDateTimeBefore: null,
      timeSeriesIncludes: null,
      compareExchangeValueIncludes: null,
      metadataOnly: false);
  
  store.GetRequestExecutor().Execute(command, context);
  
  // Access the included revisions 
  var revisions = (BlittableJsonReaderArray)command.Result.RevisionIncludes;
  
  var revisionObj = (BlittableJsonReaderObject)revisions[0];
  var revision = (BlittableJsonReaderObject)revisionObj["Revision"];
}

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // Fetch document orders/826-A and include the specified revisions
  var command = new GetDocumentsCommand(store.Conventions,
      ids:new[] {"orders/826-A"},
      includes: null, 
      counterIncludes: null,
      // 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: new[]
      {
          "RevisionsChangeVectors"
      },
      revisionIncludeByDateTimeBefore: null,
      timeSeriesIncludes: null,
      compareExchangeValueIncludes: null,
      metadataOnly: false);
  
  store.GetRequestExecutor().Execute(command, context);
  
  // Access the included revisions 
  var revisions = (BlittableJsonReaderArray)command.Result.RevisionIncludes;
  
  var revisionObj = (BlittableJsonReaderObject)revisions[0];
  var revision = (BlittableJsonReaderObject)revisionObj["Revision"];
}

Include compare-exchange values:

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // Fetch document orders/826-A and include the specified compare-exchange
  var command = new GetDocumentsCommand(store.Conventions,
      ids:new[] {"orders/826-A"},
      includes: null, 
      counterIncludes: null,
      revisionsIncludesByChangeVector: null,
      revisionIncludeByDateTimeBefore: null,
      timeSeriesIncludes: null,
      // 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"
      ],
      metadataOnly: false);
  
  store.GetRequestExecutor().Execute(command, context);
  
  // Access the included compare-exchange items
  var cmpXchgItems = 
      (BlittableJsonReaderObject)command.Result.CompareExchangeValueIncludes;
  
  var cmpXchgItemKey = cmpXchgItems.GetPropertyNames()[0]; // The cmpXchg KEY NAME
  var cmpXchgItemObj = (BlittableJsonReaderObject)cmpXchgItems[cmpXchgItemKey];
  
  var cmpXchgItemValueObj = (BlittableJsonReaderObject)cmpXchgItemObj["Value"];
  var cmpXchgItemValue = cmpXchgItemValueObj["Object"]; // The cmpXchg KEY VALUE
}

Syntax

// Available overloads:
// ====================

public GetDocumentsCommand(int start, int pageSize)

public GetDocumentsCommand(DocumentConventions conventions, 
  string id,
  string[] includes,
  bool metadataOnly);
  
public GetDocumentsCommand(DocumentConventions conventions,
  string[] ids,
  string[] includes,
  bool metadataOnly);
  
public GetDocumentsCommand(DocumentConventions conventions, 
  string[] ids,
  string[] includes, 
  string[] counterIncludes, 
  IEnumerable<AbstractTimeSeriesRange> timeSeriesIncludes, 
  string[] compareExchangeValueIncludes, 
  bool metadataOnly);
  
public GetDocumentsCommand(DocumentConventions conventions, 
  string[] ids,
  string[] includes,
  string[] counterIncludes, 
  IEnumerable<string> revisionsIncludesByChangeVector, 
  DateTime? revisionIncludeByDateTimeBefore, 
  IEnumerable<AbstractTimeSeriesRange> timeSeriesIncludes, 
  string[] compareExchangeValueIncludes,
  bool metadataOnly);
  
public GetDocumentsCommand(DocumentConventions conventions,
  string[] ids,
  string[] includes,
  bool includeAllCounters,
  IEnumerable<AbstractTimeSeriesRange> timeSeriesIncludes,
  string[] compareExchangeValueIncludes,
  bool metadataOnly);
  
public GetDocumentsCommand(DocumentConventions conventions,
  string startWith,
  string startAfter,
  string matches, string exclude,
  int start, int pageSize,
  bool metadataOnly);
  
public GetDocumentsCommand(int start, int pageSize);            

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	`bool`	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 change-vectors of the revisions you wish to include.
revisionIncludeByDateTimeBefore	`DateTime`	When this date is provided, retrieve the most recent revision that was created before this date value.
metadataOnly	`bool`	Whether to fetch the whole document or just the metadata.
start	`int`	Number of documents that should be skipped.
pageSize	`int`	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:
// ================================

public class PutResult
{
  public BlittableJsonReaderObject Includes { get; set; }
  public BlittableJsonReaderArray Results { get; set; }
  public BlittableJsonReaderObject CounterIncludes { get; set; }
  public BlittableJsonReaderArray RevisionIncludes { get; set; }
  public BlittableJsonReaderObject TimeSeriesIncludes { get; set; }
  public BlittableJsonReaderObject CompareExchangeValueIncludes { get; set; }
}

Get single document​

Get multiple documents​

Get metadata only​

Get paged documents​

Get documents - by ID prefix​

Get documents - with includes​

Syntax​