Reading a document

The steps shown here demonstrate how to read a document:

1. Send a GET request to retrieve a document.

2. Run the following command: https://$ACCOUNT.cloudant.com/$DATABASE/$DOCUMENT_ID.

Recall that for a partitioned database the $DOCUMENT_ID is formed of a partition key part and a document key part.

If you don't know the _id for a particular document, you can query the database for all documents.

Due to the distributed, eventually consistent nature of IBM Cloudant, reads might return stale data. In particular, data written recently, even by the same client, might not be returned from a read request immediately following the write request. To work around this behavior, a client can cache the state of data locally. Caching also helps to keep request counts down, increase application performance, and decrease load on the database cluster. This behavior also applies to other read requests such as to MapReduce and search indexes.

See an example of retrieving a document by using HTTP:

GET /$DATABASE/$DOCUMENT_ID HTTP/1.1

You can customize this section for the programming language that you want to use by selecting the language in the code examples.

See an example of retrieving a document:

curl -H "Authorization: Bearer $API_BEARER_TOKEN" -X GET "$SERVICE_URL/products/small-appliances:1000042"

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.Document;
import com.ibm.cloud.cloudant.v1.model.GetDocumentOptions;

Cloudant service = Cloudant.newInstance();

GetDocumentOptions documentOptions =
    new GetDocumentOptions.Builder()
        .db("products")
        .docId("small-appliances:1000042")
        .build();

Document response =
    service.getDocument(documentOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.getDocument({
  db: 'products',
  docId: 'small-appliances:1000042'
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.get_document(
  db='products',
  doc_id='small-appliances:1000042'
).get_result()

print(response)

getDocumentOptions := service.NewGetDocumentOptions(
  "products",
  "small-appliances:1000042",
)

document, response, err := service.GetDocument(getDocumentOptions)
if err != nil {
  panic(err)
}

b, _ := json.MarshalIndent(document, "", "  ")
fmt.Println(string(b))

The previous Go example requires the following import block:

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

All Go examples require the service object to be initialized. For more information, see the API documentation's Authentication section for examples.

The response contains the document that you requested, or a description of the error if the document can't be retrieved.

See an example response of retrieving a document:

{
  "_id": "exampleid",
  "brand": "Foo",
  "colours": [
    "red",
    "green",
    "black",
    "blue"
  ],
  "description": "Slim Colourful Design Electronic Cooking Appliance for ...",
  "image": "assets/img/0gmsnghhew.jpg",
  "keywords": [
    "Foo",
    "Scales",
    "Weight",
    "Digital",
    "Kitchen"
  ],
  "name": "Digital Kitchen Scales",
  "price": 14.99,
  "productid": "1000042",
  "taxonomy": [
    "Home",
    "Kitchen",
    "Small Appliances"
  ],
  "type": "product"
}