A newer version of this documentation is available.

View Latest
February 16, 2025
+ 12

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

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 database. To restore your sample data, remove and reinstall the travel sample data. Refer to Sample Buckets for details.

Reading a Document

To read a single document in Couchbase, perform a get operation.

Use the cbc cat command to retrieve a document by ID and output its data.


The example below retrieves document hotel-123 from the hotel keyspace in the inventory scope.

cbc cat hotel-123 -u Administrator -P password -U couchbase://localhost/travel-sample \
	--scope='inventory' \
	--collection='hotel'
Result
console
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).

Reading with Options

To specify further parameters, such as expiry, add options to the get operation.

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
Result
console
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).

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.

  1. Connect to the cbc-subdoc interactive shell.

  2. 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.

airport_1254
json
{ "id": 1254, // ... "geo": { "lat": 50.962097, "lon": 1.954764, "alt": 12 } }
console
cbc-subdoc -u Administrator -P password -U couchbase://localhost/travel-sample subdoc> get airport_1254 --path geo
Result
console
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).

Key-Value Operations with SDKs:

Sub-Document operations with SDKs: