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