A newer version of this documentation is available.

View Latest
February 16, 2025
+ 12

How to create documents in Couchbase.
This guide is for Couchbase Server.

Introduction

Couchbase stores its data as either JSON or Binary documents with unique IDs (primary keys) by which they can be located.

Documents are organized and grouped in buckets using scopes and collections. If a scope or collection is not provided when creating a document, Couchbase will automatically store data in the _default collection or _default scope.

Read the following for further information about the clients available:

Please note that the examples in this guide will alter the data in your sample database. To restore your sample data, remove and reinstall the travel sample data. Refer to Sample Buckets for details.

Inserting a Document

To create a single document in Couchbase, perform an insert operation.

  1. Create a structured JSON document to insert in the database.

  2. Use the cbc create command with --mode insert to create the document.

  3. Pass the --scope and --collection parameters to specify the keyspace in which to store the document, and use < to specify the JSON document to insert.


The example below inserts a new JSON document in the hotel keyspace in the inventory scope.

First, create the file hotel-123.json and store it in the tmp directory:

hotel-123.json
{
  "id": 123,
  "name": "Medway Youth Hostel",
  "address": "Capstone Road, ME7 3JE",
  "url": "http://www.yha.org.uk",
  "geo": {
    "lat": 51.35785,
    "lon": 0.55818,
    "accuracy": "RANGE_INTERPOLATED"
  },
  "country": "United Kingdom",
  "city": "Medway",
  "state": null,
  "reviews": [
    {
      "content": "This was our 2nd trip here and we enjoyed it more than last year.", 
      "author": "Ozella Sipes",
      "date": "2021-11-17T17:35:05.351Z"
    }
  ],
  "vacancy": true,
  "description": "40 bed summer hostel about 3 miles from Gillingham."
}

Now insert the document:

cbc create -u Administrator -P password -U couchbase://localhost/travel-sample \
	--scope='inventory' \
	--collection='hotel' \
	--mode insert hotel-123 <./tmp/hotel-123.json

hotel-123 is the document’s ID. The document is redirected (<) to the cbc command’s standard input.

Result
console
hotel-123 Stored. CAS=0x16b37e5081690000 SYNCTOKEN=829,51260943619833,92
If the document already exists, cbc will return a LCB_ERR_DOCUMENT_EXISTS error.

For further details, refer to cbc(1).

When a document is created, Couchbase assigns it a CAS (Compare And Swap) value to keep track of the document’s state within the database. Each time a document is mutated the CAS will change accordingly. This unique value allows the database to protect against concurrent updates to the same document.

Inserting with Options

To specify further parameters for the inserted document, such as expiry, add the options to the insert operation.

  1. Create a structured document object containing your data.

  2. Use the cbc create command with --mode insert to create the document.

  3. Pass the --scope and --collection parameters to specify the keyspace in which to store the document.

  4. Pass any required options, such as --expiry, and use < to specify the JSON document to insert.


The example below inserts a new JSON document and sets it to expire after 60 seconds. The document will be automatically deleted once expired.

First, create the file hotel-456.json and store it in the tmp directory:

hotel-456.json
{
  "id": 456,
  "title": "Ardèche",
  "name": "La Pradella",
  "address": "rue du village, 07290 Preaux, France",
  "phone": "+33 4 75 32 08 52",
  "url": "http://www.lapradella.fr", 
  "country": "France",
  "city": "Preaux",
  "state": "Rhône-Alpes",
  "vacancy": false
}

Now insert the document:

cbc create -u Administrator -P password -U couchbase://localhost/travel-sample \
	--scope='inventory' \
	--collection='hotel' \
	--mode insert hotel-456 \
	--expiry 60 <./tmp/hotel-456.json
Result
console
hotel-456 Stored. CAS=0x16b5dc9223f30000 SYNCTOKEN=733,211618429638288,95

For further details, refer to cbc(1).

Key-Value Operations with SDKs: