See on GitHub

    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:

    // Define the json document to 'put'
const jsonDocument = {
    name: "My category",
    description: "My category description",
    "@metadata": {
        "@collection": "categories"
    }
}

// Define the 'PutDocumentCommand'
// Pass the document ID, whether to make concurrency checks, 
// and the json document to store
const command = new PutDocumentCommand("categories/999", null, jsonDocument);

// Call 'execute' on the Store Request Executor to send the command to the server
await documentStore.getRequestExecutor().execute(command);

// Access the command result
const result = command.result;
const theDocumentID = result.id;
const theDocumentCV = result.changeVector;

assert.strictEqual(theDocumentID, "categories/999");

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

    const session = documentStore.openSession();

// Create a new entity
const category = new Category();
category.name = "My category";
category.description = "My category description";

// To be able to specify under which collection the document should be stored 
// you need to convert the entity to a json document first.

// Passing the entity as is instead of the json document
// will result in storing the document under the "@empty" collection.

const documentInfo = new DocumentInfo();
documentInfo.collection = "categories"; // The target collection
const jsonDocument = EntityToJson.convertEntityToJson(
    category, documentStore.conventions, documentInfo);

// Define the 'PutDocumentCommand'
// Pass the document ID, whether to make concurrency checks,
// and the json document to store
const command = new PutDocumentCommand("categories/999", null, jsonDocument);

// Call 'execute' on the Session Request Executor to send the command to the server
await session.advanced.requestExecutor.execute(command);

// Access the command result
const result = command.result;
const theDocumentID = result.id;
const theDocumentCV = result.changeVector;

assert.strictEqual(theDocumentID, "categories/999");

    Syntax 

    PutDocumentCommand(id, changeVector, 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 object The document to store. 

    // Executing `PutDocumentCommand` returns the following object:
{
    // The document id under which the entity was stored
    id; // string
    
    // The change vector assigned to the stored document
    changeVector; // string
}

    related articlesRelated Articles

    Commands

    Home / Docs / Client Api / Commands / Documents / Put