Reading Data
- how-to
How to read documents in Couchbase.
Introduction
Retrieving documents by ID is the fastest and simplest way to read data in Couchbase. The Key-Value (KV) or Data Service allows you to retrieve a full document when you need to fetch all of the data stored. However, in instances where this can be costly and unnecessary, Couchbase also provides access to specific paths within a document.
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.
|
Reading a Document
To read a single document in Couchbase, perform a get operation.
-
cbc
-
.NET
-
Java
-
Node.js
-
Python
Use the cbc cat
command to retrieve a document by ID and output its data.
The example below retrieves document hotel-123
from the travel-sample.inventory.hotel
keyspace.
cbc cat hotel-123 -u Administrator -P password -U couchbase://localhost/travel-sample \
--scope='inventory' \
--collection='hotel'
hotel-123 CAS=0x16ba896b78930000, Flags=0x0, Size=567, Datatype=0x01(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."
}
The output has been prettified for readability.
If the document cannot be found, cbc will return a LCB_ERR_DOCUMENT_NOT_FOUND error.
|
For further details, refer to cbc(1).
Use the GetAsync()
method to retrieve a document by ID.
A GetResult
object is returned, which includes the content
, cas
value, and other valuable metadata.
The example below retrieves document hotel-123
from the travel-sample.inventory.hotel
keyspace.
var getResult = await hotelCollection.GetAsync("hotel-123");
// Print some result metadata to the console.
Console.WriteLine($"CAS: {getResult.Cas}");
Console.WriteLine($"Data: {getResult.ContentAs<JObject>()}");
If the document doesn’t exist, the SDK will return a DocumentNotFoundException error.
|
Click the GitHub button to view this code in context.
For further details, refer to CollectionExtensions.
Use the get()
method to retrieve a document by ID.
A GetResult
object is returned, which includes the content
, cas
value, and other valuable metadata.
The example below retrieves document hotel-123
from the travel-sample.inventory.hotel
keyspace.
GetResult getResult = hotelCollection.get("hotel-123");
// Print the result's CAS metadata to the console.
System.out.println("CAS:" + getResult.cas());
If the document doesn’t exist, the SDK will return a DocumentNotFoundException error.
|
Click the GitHub button to view this code in context.
For further details, refer to Collection.
Use the get()
function to retrieve a document by ID.
A GetResult
promise is returned, which includes the content
, cas
value, and other valuable metadata.
The example below retrieves document hotel-123
from the travel-sample.inventory.hotel
keyspace.
const getResult = await hotelCollection.get('hotel-123')
// Print some result metadata to the console.
console.log('CAS:', getResult.cas)
console.log('Data:', JSON.stringify(getResult.content, null, ' '))
If the document doesn’t exist, the SDK will return a DocumentNotFoundError error.
|
Click the GitHub button to view this code in context.
For further details, refer to Collection.
Use the get()
function to retrieve a document by ID.
A GetResult
object is returned, which includes the content
, cas
value, and other valuable metadata.
The example below retrieves document hotel-123
from the travel-sample.inventory.hotel
keyspace.
get_result = hotel_collection.get("hotel-123")
# Print some result metadata to the console.
print("CAS:", get_result.cas)
print("Data: {}".format(get_result.content_as[dict]))
If the document doesn’t exist, the SDK will return a DocumentNotFoundException error.
|
Click the GitHub button to view this code in context.
For further details, refer to Collection.
Reading with Options
To specify further parameters, such as expiry, add options to the get operation.
-
cbc
-
.NET
-
Java
-
Node.js
-
Python
Use the cbc cat
command to retrieve a document by ID and pass options as required.
The example below uses an --expiry
option for the cat
command which adds an expiry of 60 seconds to the hotel-123
document.
cbc cat hotel-123 -u Administrator -P password -U couchbase://localhost/travel-sample \
--scope='inventory' \
--collection='hotel' \
--expiry=60
hotel-123 CAS=0x16bcec98e00c0000, Flags=0x0, Size=567, Datatype=0x01(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."
}
The output has been prettified for readability.
For further details, refer to cbc(1).
Pass any required options to the GetAsync()
method when retrieving a document.
A GetResult
object is returned, which may include extra metadata, depending on the options passed.
The example below retrieves a document hotel-123
with additional expiry metadata.
var getResult = await hotelCollection.GetAsync("hotel-456", options =>
{
options.Expiry();
});
// Print some result metadata to the console.
Console.WriteLine($"CAS: {getResult.Cas}");
Console.WriteLine($"Data: {getResult.ContentAs<JObject>()}");
Console.WriteLine($"Expiry: {getResult.ExpiryTime}");
Click the GitHub button to view this code in context.
For further details, refer to CollectionExtensions.
Pass any required options to the get()
method when retrieving a document.
A GetResult
object is returned, which may include extra metadata, depending on the options passed.
The example below retrieves a document hotel-123
with additional expiry metadata.
GetResult getResult = hotelCollection.get("hotel-123",
GetOptions.getOptions().withExpiry(true)
);
// Print the result's CAS metadata to the console.
System.out.println("CAS:" + getResult.cas());
System.out.println("Data:" + getResult.contentAsObject());
System.out.println("Expiry:" + getResult.expiryTime());
Click the GitHub button to view this code in context.
For further details, refer to Collection.
Pass any required options to the get()
method when retrieving a document.
A GetResult
object is returned, which may include extra metadata, depending on the options passed.
The example below retrieves a document hotel-123
with additional expiry metadata.
const getResult = await hotelCollection.get('hotel-456', {
withExpiry: true,
})
// Print some result metadata to the console.
console.log('CAS:', getResult.cas)
console.log('Data:', JSON.stringify(getResult.content, null, ' '))
console.log('Expiry time:', getResult.expiryTime)
Click the GitHub button to view this code in context.
For further details, refer to Collection.
Pass any required options to the get()
method when retrieving a document.
A GetResult
object is returned, which may include extra metadata, depending on the options passed.
The example below retrieves a document hotel-123
with additional expiry metadata.
get_result = hotel_collection.get(
"hotel-456", GetOptions(with_expiry=True)
)
# Print some result metadata to the console.
print("CAS:", get_result.cas)
print("Data: {}".format(get_result.content_as[dict]))
print("Expiry time: {}".format(get_result.expiryTime))
Click the GitHub button to view this code in context.
For further details, refer to Collection.
Reading a Sub-Document
JSON documents can contain a lot of nested data — which might not necessarily need to be accessed all at once. Reading full documents to access a field or two is not ideal and could cause performance issues in your application. Instead, a better practice would be to access specific paths, or sub-documents, to perform more efficient read operations.
To fetch a specific field inside a document, you can perform a sub-document get operation.
-
cbc-subdoc
-
.NET
-
Java
-
Node.js
-
Python
-
Connect to the
cbc-subdoc
interactive shell. -
Use the
get
command to access specific fields in a JSON document with the--path
argument.
The example below fetches the geo
data from the airport_1254
document.
{
"id": 1254,
// ...
"geo": {
"lat": 50.962097,
"lon": 1.954764,
"alt": 12
}
}
cbc-subdoc -u Administrator -P password -U couchbase://localhost/travel-sample
subdoc> get airport_1254 --path geo
airport_1254 CAS=0x16b815068df80000
0. Size=43, RC=LCB_SUCCESS (0)
{"lat":50.962097,"lon":1.954764,"alt":12.0}
If the path cannot be found, cbc-subdoc will return a LCB_ERR_SUBDOC_PATH_NOT_FOUND error.
|
For further details, refer to cbc-subdoc(1).
-
Call the
LookupInAsync()
method, which takes a document ID and an IEnumerable containingLookUpInSpec
objects. -
Use the
LookUpInSpec
object to specify the sub-operation to be performed within the lookup.
A LookupInResult
object is returned, containing the result and metadata relevant to the sub-document get operation.
The example below fetches the geo
data from the hotel-123
document.
var lookupInResult = await hotelCollection.LookupInAsync("hotel-123",
specs => specs.Get("geo")
);
Console.WriteLine($"CAS: {lookupInResult.Cas}");
Console.WriteLine($"Geo: {lookupInResult.ContentAs<JObject>(0)}");
Click the GitHub button to view this code in context.
For further details, refer to CollectionExtensions.
-
Call the
lookupIn()
method, which takes a document ID and an array ofLookUpInSpec
objects. -
Use the
LookUpInSpec
object to specify the sub-operation to be performed within the lookup.
A LookupInResult
object is returned, containing the result and metadata relevant to the sub-document get operation.
The example below fetches the geo
data from the hotel-123
document.
List<LookupInSpec> specs = Arrays.asList(LookupInSpec.get("geo"));
LookupInResult lookupInResult = hotelCollection.lookupIn("hotel-123", specs);
System.out.println("CAS:" + lookupInResult.cas());
System.out.println("Geo:" + lookupInResult.contentAsObject(0));
If the document path can’t be found, the SDK will return a PathNotFoundException error.
|
Click the GitHub button to view this code in context.
For further details, refer to Collection.
-
Call the
lookupIn()
function, which takes a document ID and an array ofLookUpInSpec
objects. -
Use the
LookUpInSpec
object to specify the sub-operation to be performed within the lookup.
A LookupInResult
promise is returned containing the result and metadata relevant to the sub-document get operation.
The example below fetches the geo
data from the hotel-123
document.
const lookupInResult = await hotelCollection.lookupIn('hotel-123', [
couchbase.LookupInSpec.get('geo'),
])
console.log('CAS:', lookupInResult.cas)
console.log('Geo:', lookupInResult.content[0].value)
Click the GitHub button to view this code in context.
For further details, refer to Collection.
-
Call the
lookup_in()
function, which takes a document ID and a list ofLookUpInSpec
objects. -
Use the
LookUpInSpec
object to represent the sub-operation to be performed within the lookup.
A LookupInResult
object is returned containing the result and metadata relevant to the sub-document get operation.
The example below fetches the geo
data from the hotel-123
document.
lookup_in_result = hotel_collection.lookup_in(
"hotel-123", [subdocument.get("geo")]
)
print("CAS:", lookup_in_result.cas)
print("Data:", lookup_in_result.content_as[dict](0))
If the document path can’t be found, the SDK will return a PathNotFoundException error.
|
Click the GitHub button to view this code in context.
For further details, refer to Collection.