Creating Data
- how-to
How to create documents in Couchbase.
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 buckets.
To restore your sample data, remove and reinstall the travel-sample bucket.
Refer to Sample Buckets for details.
|
Inserting a Document
To create a single document in Couchbase, perform an insert operation.
-
cbc
-
.NET
-
Java
-
Node.js
-
Python
-
Create a structured JSON document to insert in the database.
-
Use the
cbc create
command with--mode insert
to create the document. -
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 travel-sample.inventory.hotel
keyspace.
First, create the file hotel-123.json
and store it in the tmp
directory:
{
"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.
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).
-
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 travel-sample.inventory.hotel
keyspace.
// 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 will return a DocumentExistsException error.
|
Click the GitHub button to view 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 travel-sample.inventory.hotel
keyspace.
// 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 will return a DocumentExistsException error.
|
Click the GitHub button to view 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 travel-sample.inventory.hotel
keyspace.
// 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 will return a DocumentExistsError error.
|
Click the GitHub button to view 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 travel-sample.inventory.hotel
keyspace.
# 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 will return a DocumentExistsException error.
|
Click the GitHub button to view 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.
-
cbc
-
.NET
-
Java
-
Node.js
-
Python
-
Create a structured document object containing your data.
-
Use the
cbc create
command with--mode insert
to create the document. -
Pass the
--scope
and--collection
parameters to specify the keyspace in which to store the document. -
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:
{
"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
hotel-456 Stored. CAS=0x16b5dc9223f30000
SYNCTOKEN=733,211618429638288,95
For further details, refer to cbc(1).
-
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 GitHub button to view 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 GitHub button to view 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 GitHub button to view 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 GitHub button to view this code in context.
For further details, refer to Collection.