Put Document Command

• Use the low-level PutDocumentCommand to insert a new document to the database or update an existing document.

• When using PutDocumentCommand, you must explicitly specify the collection to which the document will belong, otherwise, the document will be placed in the @empty collection. See how this is done in the example below.

• To insert a document to the database using a higher-level method, see storing entities.
  To update an existing document using a higher-level method, see update entities.

• In this page:

  • Examples
  • Syntax

Examples

Put document command - using the Store's request executor:

• Put_document
• Put_document_async

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // Define the document to 'put' as a blittable object
  var blittableDocument = context.ReadObject(new DynamicJsonValue()
  {
      ["@metadata"] = new DynamicJsonValue()
      {
          ["@collection"] = "Categories"
      },
      ["Name"] = "My category",
      ["Description"] = "My category description"
  }, "categories/999");
  
  // Define the PutDocumentCommand
  var command = new PutDocumentCommand(store.Conventions,
      "categories/999", null, blittableDocument);

  // Call 'Execute' on the Store Request Executor to send the command to the server
  store.GetRequestExecutor().Execute(command, context);

  // Access the command result
  var putResult = command.Result;
  var theDocumentID = putResult.Id;
  var theDocumentCV = putResult.ChangeVector;
}

using (var store = new DocumentStore())
using (store.GetRequestExecutor().ContextPool.AllocateOperationContext(out var context))
{
  // Define the document to 'put' as a blittable object
  var blittableDocument = context.ReadObject(new DynamicJsonValue()
  {
      ["@metadata"] = new DynamicJsonValue()
      {
          ["@collection"] = "Categories"
      },
      ["Name"] = "My category",
      ["Description"] = "My category description"
  }, "categories/999");
  
  // Define the PutDocumentCommand
  var command = new PutDocumentCommand(store.Conventions,
      "categories/999", null, blittableDocument);

  // Call 'ExecuteAsync' on the Store Request Executor to send the command to the server
  await store.GetRequestExecutor().ExecuteAsync(command, context);

  // Access the command result
  var putResult = command.Result;
  var theDocumentID = putResult.Id;
  var theDocumentCV = putResult.ChangeVector;
}

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

• Put_document
• Put_document_async

// Create a new document entity
var doc = new Category
{
  Name = "My category",
  Description = "My category description"
};

// Specify the collection to which the document will belong
var docInfo = new DocumentInfo
{
  Collection = "Categories"
};

// Convert your entity to a BlittableJsonReaderObject
var blittableDocument = session.Advanced.JsonConverter.ToBlittable(doc, docInfo);

// Define the PutDocumentCommand
var command = new PutDocumentCommand(store.Conventions,
  "categories/999", null, blittableDocument);

// Call 'Execute' on the Session Request Executor to send the command to the server
session.Advanced.RequestExecutor.Execute(command, session.Advanced.Context);

// Access the command result
var putResult = command.Result;
var theDocumentID = putResult.Id;
var theDocumentCV = putResult.ChangeVector;

// Create a new document entity
var doc = new Category
{
  Name = "My category",
  Description = "My category description"
};

// Specify the collection to which the document will belong
var docInfo = new DocumentInfo
{
  Collection = "Categories"
};

// Convert your entity to a BlittableJsonReaderObject
var blittableDocument = asyncSession.Advanced.JsonConverter.ToBlittable(doc, docInfo);

// Define the PutDocumentCommand
var command = new PutDocumentCommand(store.Conventions,
  "categories/999", null, blittableDocument);

// Call 'Execute' on the Session Request Executor to send the command to the server
await asyncSession.Advanced.RequestExecutor.ExecuteAsync(
  command, asyncSession.Advanced.Context);

// Access the command result
var putResult = command.Result;
var theDocumentID = putResult.Id;
var theDocumentCV = putResult.ChangeVector;

Syntax

public PutDocumentCommand(DocumentConventions conventions,
      string id, string changeVector, BlittableJsonReaderObject document)

Parameter	Type	Description
id	string	Unique ID under which document will be stored.
changeVector	string	The change-vector of the document you wish to update, used for optimistic concurrency control. Pass null to skip the check and force the 'put'.
document	BlittableJsonReaderObject	The document to store. Use: session.Advanced.JsonConverter.ToBlittable(doc, docInfo); to convert your entity to a BlittableJsonReaderObject.

// The `PutDocumentCommand` result:
// ================================

public class PutResult
{
  /// The ID under which document was stored 
  public string Id { get; set; }

  // The changeVector that was assigned to the stored document
  public string ChangeVector { get; set; }
}