Create Documents

Capella Operational

how-to

How to create documents with a command line tool or an SDK.

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:

Couchbase Shell (cbsh) — developer preview
SDK Clients

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 Import Data with the Capella UI for details.

Inserting a Document

To create a single document, perform an insert operation.

cbsh
.NET
Java
Node.js
Python

If you haven’t already done so, use cb-env to set the bucket, scope, and collection in which to store the document.
Create a structured JSON object containing your data.
Use doc insert to create the document.

The example below inserts a new JSON document in the hotel keyspace in the inventory scope. The document’s ID is hotel-123.

cb-env bucket travel-sample
cb-env scope inventory
cb-env collection hotel

doc insert hotel-123 {
  "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."
}

Result

╭───┬───────────┬─────────┬────────┬──────────┬─────────╮
│ # │ processed │ success │ failed │ failures │ cluster │
├───┼───────────┼─────────┼────────┼──────────┼─────────┤
│ 0 │         1 │       1 │      0 │          │ capella │
╰───┴───────────┴─────────┴────────┴──────────┴─────────╯

If the document already exists, Couchbase Shell returns a Key already exists error.

For further details, refer to Mutating in the Couchbase Shell documentation.

Create a structured document object containing your data.
Use the InsertAsync() method to insert the document in a given keyspace.

A MutationResult object is returned containing the result and metadata relevant to the insert operation.

The example below inserts a new JSON document in the hotel keyspace in the inventory scope. The document’s ID is hotel-123.

// Create a document object.
var document = new
{
	id = 123,
	name = "Medway Youth Hostel ",
	address = "Capstone Road, ME7 3JE",
	url = "http://www.yha.org.uk",
	geo = new
	{
		lat = 51.35785,
		lon = 0.55818,
		accuracy = "RANGE_INTERPOLATED"
	},
	country = "United Kingdom",
	city = "Medway",
	state = (string)null,
	reviews = new[]
	{
		new {
			content = "This was our 2nd trip here and we enjoyed it more than last year.",
			author = "Ozella Sipes",
			date = DateTime.UtcNow
		}
	},
	vacancy = true,
	description = "40 bed summer hostel about 3 miles from Gillingham."
};

// Insert the document in the hotel collection.
var insertResult = await hotelCollection.InsertAsync("hotel-123", document);

// Print the result's CAS metadata to the console.
Console.WriteLine($"Cas: {insertResult.Cas}");

If the document already exists, the SDK returns a DocumentExistsException error.

Click the View button to see this code in context.

For further details, refer to CollectionExtensions.

Create a structured document object containing your data.
Use the insert() method to insert the document in a given keyspace.

A MutationResult object is returned containing the result and metadata relevant to the insert operation.

The example below inserts a new JSON document in the hotel keyspace in the inventory scope. The document’s ID is hotel-123.

// Create the document object.
JsonObject geo = JsonObject.create()
    .put("lat", 51.35785)
    .put("lon", 0.55818)
    .put("accuracy", "RANGE_INTERPOLATED");

JsonArray reviews = JsonArray.create();
reviews.add(JsonObject.create()
    .put("content", "This was our 2nd trip here and we enjoyed it more than last year.")
    .put("author", "Ozella Sipes")
    .put("date", DateTimeFormatter.ISO_INSTANT.format(Instant.now())));

JsonObject document = JsonObject.create()
    .put("id", "hotel-123")
    .put("name", "Medway Youth Hostel")
    .put("address", "Capstone Road, ME7 3JE")
    .put("url", "http://www.yha.org.uk")
    .put("geo", geo)
    .put("country", "United Kingdom")
    .put("city", "Medway")
    .put("state", (String) null)
    .put("reviews", reviews)
    .put("vacancy", true)
    .put("description", "40 bed summer hostel about 3 miles from Gillingham.");

// Insert the document in the hotel collection.
MutationResult insertResult = hotelCollection.insert("hotel-123", document);

// Print the result's CAS metadata to the console.
System.out.println("CAS:" + insertResult.cas());

If the document already exists, the SDK returns a DocumentExistsException error.

Click the View button to see this code in context.

For further details, refer to Collection.

Create a structured document object containing your data.
Use the insert() method to insert the document in a given keyspace.

A MutationResult promise is returned containing the result and metadata relevant to the insert operation.

The example below inserts a new JSON document in the hotel keyspace in the inventory scope. The document’s ID is hotel-123.

// Create a document object.
const document = {
  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: new Date().toISOString(),
    },
  ],
  vacancy: true,
  description: '40 bed summer hostel about 3 miles from Gillingham.',
}

// Insert the document in the hotel collection.
const insertResult = await hotelCollection.insert('hotel-123', document)

// Print the result's CAS metadata to the console.
console.log('CAS:', insertResult.cas)

If the document already exists, the SDK returns a DocumentExistsError error.

Click the View button to see this code in context.

For further details, refer to Collection.

Create a structured document object containing your data.
Use the insert() function to insert the document in a given keyspace.

A MutationResult object is returned containing the result and metadata relevant to the insert operation.

The example below inserts a new JSON document in the hotel keyspace in the inventory scope. The document’s ID is hotel-123.

# Create a document object.
document = {
    "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": None,
    "reviews": [
        {
            "content": "This was our 2nd trip here and we enjoyed it more than last year.",
            "author": "Ozella Sipes",
            "date": datetime.now().isoformat(),
        },
    ],
    "vacancy": True,
    "description": "40 bed summer hostel about 3 miles from Gillingham.",
}

# Insert the document in the hotel collection.
insert_result = hotel_collection.insert("hotel-123", document)

# Print the result's CAS metadata to the console.
print("CAS:", insert_result.cas)

If the document already exists, the SDK returns a DocumentExistsException error.

Click the View button to see this code in context.

For further details, refer to Collection.

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.

cbsh
.NET
Java
Node.js
Python

If you haven’t already done so, use cb-env to set the bucket, scope, and collection in which to store the document.
Create a structured JSON object containing your data.
Use doc insert to create the document.
Pass any required options, such as --expiry.

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

cb-env bucket travel-sample
cb-env scope inventory
cb-env collection hotel

doc insert --expiry 60 hotel-456 {
  "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
}

Result

╭───┬───────────┬─────────┬────────┬──────────┬─────────╮
│ # │ processed │ success │ failed │ failures │ cluster │
├───┼───────────┼─────────┼────────┼──────────┼─────────┤
│ 0 │         1 │       1 │      0 │          │ capella │
╰───┴───────────┴─────────┴────────┴──────────┴─────────╯

For further details, refer to Mutating in the Couchbase Shell documentation.

Create a structured document object containing your data.
Use the InsertAsync() method to insert the document with a given option parameter.

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

var document = new
{
	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
};

// Insert the document with an expiry time option of 60 seconds.
var insertResult = await hotelCollection.InsertAsync("hotel-456", document, options =>
{
	options.Expiry(TimeSpan.FromSeconds(60));
});

// Print the result's CAS metadata to the console.
Console.WriteLine($"CAS: {insertResult.Cas}");

Click the View button to see this code in context.

For further details, refer to CollectionExtensions.

Create a structured document object containing your data.
Use the insert() method to insert the document with a given option parameter.

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

JsonObject document = JsonObject.create()
    .put("id", 456)
    .put("title", "Ardèche")
    .put("name", "La Pradella")
    .put("address", "rue du village, 07290 Preaux, France")
    .put("phone", "+33 4 75 32 08 52")
    .put("url", "http://www.lapradella.fr")
    .put("country", "France")
    .put("city", "Preaux")
    .put("state", "Rhône-Alpes")
    .put("vacancy", false);

// Insert the document with an expiry time option of 60 seconds.
MutationResult insertResult = hotelCollection.insert(
  "hotel-456",
  document,
  InsertOptions.insertOptions().expiry(Duration.ofSeconds(2))
);

// Print the result's CAS metadata to the console.
System.out.println("CAS:" + insertResult.cas());

Click the View button to see this code in context.

For further details, refer to Collection.

Create a structured document object containing your data.
Use the insert() function to insert the document with a given option parameter.

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

document = {
  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,
}

// Insert the document with an expiry time option of 60 seconds.
const insertResult = await hotelCollection.insert('hotel-456', document, {
  expiry: 60,
})

// Print the result's CAS metadata to the console.
console.log('CAS:', insertResult.cas)

Click the View button to see this code in context.

For further details, refer to Collection.

Create a structured document object containing your data.
Use the insert() function to insert the document with a given option parameter.

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

document = {
    "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,
}
# Insert the document with an expiry time option of 60 seconds.
insert_result = hotel_collection.insert(
    "hotel-456", document, InsertOptions(expiry=timedelta(seconds=60))
)

# Print the result's CAS metadata to the console.
print("CAS:", insert_result.cas)

Click the View button to see this code in context.

For further details, refer to Collection.

Key-Value Operations with SDKs:

C | .NET | Go | Java | Node.js | PHP | Python | Ruby | Scala

Create Documents

Introduction

Inserting a Document

Inserting with Options

Related Links