---
title: "Put Document Command"
url: "https://docs.ravendb.net/6.2/client-api/commands/documents/put"
version: "6.2"
language: "csharp"
---

# Put Document Command

> Client language: C#. Also available for [Java](https://docs.ravendb.net/6.2/client-api/commands/documents/put.java.md), [Python](https://docs.ravendb.net/6.2/client-api/commands/documents/put.python.md), [PHP](https://docs.ravendb.net/6.2/client-api/commands/documents/put.php.md), [Node.js](https://docs.ravendb.net/6.2/client-api/commands/documents/put.nodejs.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

> **Note**
>
> - 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](https://docs.ravendb.net/6.2/client-api/session/storing-entities.md).  
>   To update an existing document using a higher-level method, see [update entities](https://docs.ravendb.net/6.2/client-api/session/updating-entities.md).
>
> - In this page:
>
>   - [Examples](#examples)
>   - [Syntax](#syntax)

## Examples

> **Note**
>
> **Put document command - using the Store's request executor**:
>
> ### Put\_document
>
> ```csharp
> 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;
> }
> ```
>
> ### Put\_document\_async
>
> ```csharp
> 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;
> }
> ```

> **Note**
>
> **Put document command - using the Session's request executor**:
>
> ### Put\_document
>
> ```csharp
> // 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;
> ```
>
> ### Put\_document\_async
>
> ```csharp
> // 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

```csharp
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,<br />used for [optimistic concurrency control](https://docs.ravendb.net/6.2/server/clustering/replication/change-vector.md#concurrency-control--change-vectors).<br />Pass `null` to skip the check and force the 'put'. |
| **document** | `BlittableJsonReaderObject` | The document to store. Use:<br />`session.Advanced.JsonConverter.ToBlittable(doc, docInfo);` to convert your entity to a `BlittableJsonReaderObject`. |

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

## See also

- [Get document](https://docs.ravendb.net/6.2/client-api/commands/documents/get.md)
- [Delete document](https://docs.ravendb.net/6.2/client-api/commands/documents/delete.md)
- [Send multiple commands using a batch](https://docs.ravendb.net/6.2/client-api/commands/batches/how-to-send-multiple-commands-using-a-batch.md)
