Read Documents

Capella Operational

how-to

March 23, 2025

+ 12

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

Introduction

Retrieving documents by ID is the fastest and simplest way to read data in Couchbase Capella. 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:

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.

Reading a Document

To read a single document, perform a get operation.

cbsh
.NET
Java
Node.js
Python

If you haven’t already done so, use cb-env to set the bucket, scope, and collection where the document is stored.
Use the doc get command to retrieve a document by ID and output its data.

An object is returned, which includes the id, content, and other metadata. The document itself is wrapped in the content field.

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

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

doc get hotel-123

Result

console
Copy
╭───┬───────────┬────────────────────┬─────────────────────┬───────┬─────────╮
│ # │    id     │      content       │         cas         │ error │ cluster │
├───┼───────────┼────────────────────┼─────────────────────┼───────┼─────────┤
│ 0 │ hotel-123 │ {record 11 fields} │ 1717190781443309568 │       │ capella │
╰───┴───────────┴────────────────────┴─────────────────────┴───────┴─────────╯

If the document cannot be found, Couchbase Shell returns a Key not found error.

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

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 hotel keyspace in the inventory scope.

csharp
ViewCopy
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 returns a DocumentNotFoundException error.

Click the View button to see 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 hotel keyspace in the inventory scope.

java
ViewCopy
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 returns a DocumentNotFoundException error.

Click the View button to see 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 hotel keyspace in the inventory scope.

nodejs
ViewCopy
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 returns a DocumentNotFoundError error.

Click the View button to see 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 hotel keyspace in the inventory scope.

python
ViewCopy
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 returns a DocumentNotFoundException error.

Click the View button to see this code in context.

For further details, refer to Collection.

Reading with Options

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

cbsh
.NET
Java
Node.js
Python

If you haven’t already done so, use cb-env to set the bucket, scope, and collection where the document is stored.
Use the doc get command to retrieve a document by ID, and pass options as required.

The example below pipes the hotel-123 document and its metadata through the to json filter to transform the output to JSON.

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

doc get hotel-123 | to json

Result

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

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

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.

csharp
ViewCopy
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 View button to see 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.

java
ViewCopy
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 View button to see 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.

nodejs
ViewCopy
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 View button to see 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.

python
ViewCopy
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 View button to see 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. For example, the document airport_1254 contains a sub-document called geo.

airport_1254

json
Copy
{
  "id": 1254,
//  ...
  "geo": {
    "lat": 50.962097,
    "lon": 1.954764,
    "alt": 12
  }
}

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.

cbsh
.NET
Java
Node.js
Python

If you haven’t already done so, use cb-env to set the bucket, scope, and collection where the document is stored.
Use the doc get command to retrieve a document by ID.
Pipe the document through the get filter and specify the path to the field containing the sub-document.

The example below fetches the geo data from the hotel-123 document.

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

doc get hotel-123 | get content.geo

Result

console
Copy
╭───┬────────────────────┬─────────┬────────╮
│ # │      accuracy      │   lat   │  lon   │
├───┼────────────────────┼─────────┼────────┤
│ 0 │ RANGE_INTERPOLATED │ 51.3578 │ 0.5582 │
╰───┴────────────────────┴─────────┴────────╯

If the field containing the sub-document cannot be found, the get command returns a Cannot find column error.

For further details, refer to get for filters in the Nushell documentation.

Call the LookupInAsync() method, which takes a document ID and an IEnumerable containing LookUpInSpec 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.

csharp
ViewCopy
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 View button to see this code in context.

For further details, refer to CollectionExtensions.

Call the lookupIn() method, which takes a document ID and an array of LookUpInSpec 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.

java
ViewCopy
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 returns a PathNotFoundException error.

Click the View button to see this code in context.

For further details, refer to Collection.

Call the lookupIn() function, which takes a document ID and an array of LookUpInSpec 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.

nodejs
ViewCopy
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 View button to see this code in context.

For further details, refer to Collection.

Call the lookup_in() function, which takes a document ID and a list of LookUpInSpec 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.

python
ViewCopy
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 returns a PathNotFoundException error.

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

Sub-Document operations with SDKs:

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

Read Documents

Introduction

Reading a Document

Reading with Options

Reading a Sub-Document

Related Links