Secure 5.1.1: Couchbase upsertDocuments

Couchbase upsertDocuments

Last updated: July 13, 2026

Inserts or replaces documents in a Couchbase collection. If a document with the specified key already exists, it is completely replaced.

Known limitations:

Existing documents are completely replaced without warning. All previous document data is lost.
There is no automatic rollback support.

Available attributes

You must specify all top-level attributes marked as required. If you specify an optional attribute, you must also specify any nested attributes that it requires.

Attribute	Type	Description	Required
`bucketName`	String	The name of the bucket containing the collection.	Yes
`scopeName`	String	The name of the scope containing the collection.	Yes
`collectionName`	String	The name of the collection to upsert documents into.	Yes
`document / documents`	Element	One or more inline documents to upsert. Mutually exclusive with `importFile`. See nested tags below.	Yes*
`importFile`	Element	A file reference for bulk document import. Mutually exclusive with `document`. See nested tags below.	Yes*

Nested tags — document

Attribute	Type	Description	Required
`id`	String	The unique document key.	Yes
`value`	Element	The document data. Contains `data` (String) and `type` (String). See nested tags below.	Yes

Nested tags — value (within document)

Attribute	Type	Description	Required
`data`	String	The document content as a string, formatted according to the specified `type`.	Yes
`type`	String	The data type of `data`. `Json` is a JSON object. `String` is a plain string. `Long` is an integer. `Double` is a floating-point number. `Boolean` is a boolean. `JsonArray` is a JSON array.	Yes

Nested tags — importFile

Attribute	Type	Description	Required
`filePath`	String	Path to the JSON file to import.	Yes
`importType`	String	How to read the file. `LINES` reads one JSON object per line. `LIST` reads a JSON array. `SAMPLE` reads sample documents. `KEY_GENERATORS` uses a custom key generator.	Yes
`keyProviderType`	String	How to generate document keys. `DEFAULT` uses an existing key field. `UID` generates a UUID. `INCREMENT` uses an auto-increment integer. `EXPRESSION` uses `keyProviderExpression`.	Yes
`keyProviderExpression`	String	Expression template for key generation. Required when `keyProviderType` is `EXPRESSION`.	No

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.19.xsd
        http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-couchbase-ext.xsd">

    <changeSet id="1" author="liquibase">
        <ext:upsertDocuments>
            <ext:bucketName>myBucket</ext:bucketName>
            <ext:scopeName>myScope</ext:scopeName>
            <ext:collectionName>myCollection</ext:collectionName>
            <ext:documents>
                <ext:document>
                    <ext:id>id1</ext:id>
                    <ext:value>
                        <ext:data>{"key": "value"}</ext:data>
                        <ext:type>Json</ext:type>
                    </ext:value>
                </ext:document>
            </ext:documents>
        </ext:upsertDocuments>
    </changeSet>

</databaseChangeLog>

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "1",
        "author": "liquibase",
        "upsertDocuments": {
          "bucketName": "myBucket",
          "scopeName": "myScope",
          "collectionName": "myCollection",
          "documents": [
            {
              "id": "id1",
              "value": {
                "data": "{\"key\": \"value\"}",
                "type": "Json"
              }
            }
          ]
        }
      }
    }
  ]
}

databaseChangeLog:
  - changeSet:
      id: '1'
      author: liquibase
      upsertDocuments:
        bucketName: myBucket
        scopeName: myScope
        collectionName: myCollection
        documents:
          - id: id1
            value:
              data: '{"key": "value"}'
              type: Json

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.19.xsd
        http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-couchbase-ext.xsd">

    <changeSet id="1" author="liquibase">
        <ext:upsertDocuments>
            <ext:bucketName>myBucket</ext:bucketName>
            <ext:scopeName>myScope</ext:scopeName>
            <ext:collectionName>myCollection</ext:collectionName>
            <ext:documents>
                <ext:document>
                    <ext:id>id1</ext:id>
                    <ext:value>
                        <ext:data>{"key": "value"}</ext:data>
                        <ext:type>Json</ext:type>
                    </ext:value>
                </ext:document>
            </ext:documents>
        </ext:upsertDocuments>
    </changeSet>

</databaseChangeLog>

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "1",
        "author": "liquibase",
        "upsertDocuments": {
          "bucketName": "myBucket",
          "scopeName": "myScope",
          "collectionName": "myCollection",
          "documents": [
            {
              "id": "id1",
              "value": {
                "data": "{\"key\": \"value\"}",
                "type": "Json"
              }
            }
          ]
        }
      }
    }
  ]
}

databaseChangeLog:
  - changeSet:
      id: '1'
      author: liquibase
      upsertDocuments:
        bucketName: myBucket
        scopeName: myScope
        collectionName: myCollection
        documents:
          - id: id1
            value:
              data: '{"key": "value"}'
              type: Json

Couchbase upsertDocuments

Available attributes

Nested tags — document

Nested tags — value (within document)

Nested tags — importFile

XML example

JSON example

YAML example

More like this