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

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


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:


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