Introduction

IBM® Cloudant® for IBM Cloud® is a document-oriented database as a service (DBaaS). It stores data as documents in JSON format. It is built with scalability, high availability, and durability in mind. It comes with a wide variety of indexing options that include MapReduce, IBM Cloudant Query, and full-text indexing. The replication capabilities make it easy to keep data in sync between database clusters, desktop PCs, and mobile devices.

The key API difference between Gen 1 and Gen 2 is how you manage some aspects of instance configuration. In Gen 2, you use IBM Cloud resource management to configure these instead.

Detailed documentation is also available such as a Getting started tutorial, API overview documentation, tutorials, and guides.

If you intend to store sensitive information in an IBM® Cloudant® for IBM Cloud® database you must use client-side encryption to render data unreadable to Cloudant operators. For example for PCI DSS compliance you must encrypt the Primary Account Number (PAN) before sending a document containing it to the database.

This documentation describes the SDKs and examples. To see usage information and examples in your preferred SDK, select the language tab in the right pane.

This documentation describes the Java SDK and examples. To see usage information and examples in your preferred SDK, select the language tab in the right pane.

This documentation describes the Node SDK and examples. To see usage information and examples in your preferred SDK, select the language tab in the right pane.

This documentation describes the Python SDK and examples. To see usage information and examples in your preferred SDK, select the language tab in the right pane.

This documentation describes the Go SDK and examples. To see usage information and examples in your preferred SDK, select the language tab in the right pane.

The code examples on this tab use the IBM Cloudant SDK for Java&trade.

Gradle

implementation 'com.ibm.cloud:cloudant:0.+'

Maven

Maven installation instructions

GitHub

https://github.com/ibm/cloudant-java-sdk

The code examples on this tab use the IBM Cloudant SDK for Node.js.

Installation

npm install --save @ibm-cloud/cloudant

GitHub

https://github.com/ibm/cloudant-node-sdk

The code examples on this tab use the IBM Cloudant SDK for Python.

Installation

pip3 install ibmcloudant

GitHub

https://github.com/ibm/cloudant-python-sdk

The code examples on this tab use the IBM Cloudant SDK for Go.

Installation

go get -u github.com/IBM/cloudant-go-sdk/cloudantv1

GitHub

https://github.com/ibm/cloudant-go-sdk

Endpoint URLs

The IBM Cloudant API uses an instance-specific endpoint URL. You can find your public or private endpoint by following these steps:

Go to the IBM Cloud dashboard and open an instance.
Click the Service credentials tab.
Click the chevron next to the service credentials to open the credentials pane.
Copy the value from the url (public) or vpe_url (private) field. This value is the endpoint.

For more information, see the Locating your service credentials tutorial.

Or you can copy your endpoint by following these steps:

Go to the IBM Cloud dashboard and open an instance.
Under the Manage tab on the Overview page, see the Public endpoint or Private endpoint in the table.
Click Copy to copy the endpoint. Paste the endpoint where you need your URL.

Example endpoints:

Public: https://00000000-0000-0000-0000-000000000000.zzz.cloudant.us-south.dataservices.appdomain.cloud/
Private: https://00000000-0000-0000-0000-000000000000.private.zzz.cloudant.us-south.dataservices.appdomain.cloud/

You must use your specific instance endpoint with your unique ID and region information.

Authentication

You can access IBM Cloudant with IBM Cloud® Identity and Access Management (IAM).

IAM authentication

Access to IBM Cloudant is centrally controlled by IBM Cloud® Identity and Access Management (IAM), which provides a unified approach to managing user identities, and access control across your IBM Cloud® services and applications using the same set of credentials.

To work with the API, authenticate your application or service by including your IBM Cloud® IAM access token in API requests.

Additional authentication resources

IBM Cloudant client libraries provide full integration with IAM's access controls and automatically retrieve an IAM access token when an appropriate IAM configuration is provided (for example, an IAM API key or IAM profile ID).
View IBM Cloudant authentication documentation.

Authentication with external configuration

In this scenario, the configuration is defined with an external credentials file and an authenticator that is constructed by SDK's authenticator factory during client initialization. Using the external credentials file avoids hardcoded credentials within the application code.

The default name of the credentials file is ibm-credentials.env. It is expected to be located in either the current directory or in the user's home directory. The path and name of the file can be controlled by using the IBM_CREDENTIALS_FILE environment variable.

Cloudant configuration properties start with a chosen service name prefix that identifies your service. By default it is CLOUDANT.

If you would like to rename your Cloudant service from CLOUDANT, or use multiple services at the same time you must use your defined service name as the prefix for all of your Cloudant related configuration properties. You also must use the same service name at instantiating your service.

This way, each configuration property includes both the name of the service and the specific attribute, combined in a format like CLOUDANT_APIKEY.

It is not necessary to use a .env file. These properties can be set by using environment variables with the same name in the environment where the application is run.

Variable guide for the authentication code samples

| Attribute name | Description | |----------|-------------| | {apikey} | IAM API key | | {url} | URL of Cloudant instance | | {service-name} | Chosen service name of your Cloudant instance. \n Same as the prefix of your configuration properties. \n Default value is CLOUDANT. |

SDK managing the IAM token. Replace {apikey} and {url}.

{service-name}_URL={url}
{service-name}_APIKEY={apikey}

import com.ibm.cloud.cloudant.v1.Cloudant;

Cloudant service = Cloudant.newInstance("{service-name}");

import { CloudantV1 } from '@ibm-cloud/cloudant';

const service = CloudantV1.newInstance({
    serviceName: '{service-name}'
});

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance(service_name="{service-name}")

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

service, err := cloudantv1.NewCloudantV1UsingExternalConfig(
    &cloudantv1.CloudantV1Options{
        ServiceName: "{service-name}",
    },
)

Programmatic authentication

In this scenario, authentication is configured by constructing an authenticator instance, supplying the configuration attributes programmatically, and then passing this instance to a client constructor.

SDK managing the IAM token.

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

IamAuthenticator authenticator = new IamAuthenticator.Builder()
    .apikey("{apikey}")
    .build();

Cloudant service = new Cloudant(Cloudant.DEFAULT_SERVICE_NAME, authenticator);

service.setServiceUrl("{url}");

import { CloudantV1 } from '@ibm-cloud/cloudant';
import { IamAuthenticator } from 'ibm-cloud-sdk-core';

const authenticator = new IamAuthenticator({
    apikey: '{apikey}'
});

const service = new CloudantV1({
    authenticator: authenticator
});

service.setServiceUrl('{url}');

from ibmcloudant.cloudant_v1 import CloudantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')

service = CloudantV1(authenticator=authenticator)

service.set_service_url('{url}')

import (
    "github.com/IBM/cloudant-go-sdk/cloudantv1"
    "github.com/IBM/go-sdk-core/core"
)

authenticator := &core.IamAuthenticator{
    ApiKey: "{apikey}",
}

service, err := cloudantv1.NewCloudantV1(
    &cloudantv1.CloudantV1Options{
        URL:           "{url}",
        Authenticator: authenticator,
    },
)
if err != nil {
    panic(err)
}

Error handling

IBM Cloudant operation uses standard HTTP response codes to indicate the status of the operation. HTTP response codes in the 2xx range indicate success. A 4xx range indicates a failure, and a 5xx range usually indicates an internal system error. More detailed error information is available in the body of the response.

For some HTTP requests, for example bulk operations, a 2xx response may indicate overall request success, but individual actions may have failed. For these cases the HTTP status code is insufficient to indicate success or failure and the caller must inspect the response body contents.

| HTTP Code | Meaning | |-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 200 - OK | Request completed successfully. | | 201 - Created | Resource created or updated successfully. The resource could be a database or a document, for example. | | 202 - Accepted | Request accepted, but failed to meet the quorum for the operation. | | 206 - Partial Content | Request was successful and the body contains the ranges of data, as described in the Range header of the request. | | 304 - Not Modified | The requested content has not changed. The ETag system that identifies the version of information returned uses this code. | | 400 - Bad Request | Bad request structure. The error can indicate an error with the request URL, path, or headers. Differences in the supplied MD5 hash and content also trigger this error, as this error might indicate message corruption. | | 401 - Unauthorized | The item requested was not available with the supplied authorization, or authorization was not supplied. | | 402 - Payment required | Either the account is in arrears or the amount of data exceeds the plan quota. You can delete data, upgrade plan, or bring the account up to date. | | 403 - Forbidden | The server forbids access to the requested item or operation. | | 404 - Not Found | The requested resource does not exist or is not visible. The content includes further information as a JSON object, if available. The structure contains two keys, error and reason, similar to the following example: { "error":"not_found", "reason":"no_db_file" } | | 405 - Resource Not Allowed | A request was made by using an invalid HTTP request type for the URL requested. For example, you requested a PUT when a POST is expected. Errors of this type can also be triggered by invalid URL strings. | | 406 - Not Acceptable | The requested response content type is not supported by the server. | | 408 - Request Timeout | Timeout during reading client request. | | 410 - Gone | The requested resource is no longer available. | | 409 - Conflict | Request resulted in an update conflict. The two most common causes are firstly, trying to update or delete a document without providing a revision and secondly, that the latest revision of the document on the server changed between a fetch and an update. | | 412 - Precondition Failed | The request headers from the client and the capabilities of the server do not match. Alternatively, a request to create a database was denied because the database exists. | | 413 - Request Entity Too Large | The request size exceeded the limit for the IBM Cloudant API. | | 415 - Bad Content Type | The content type of the request is not supported by the server. | | 416 - Requested Range Not Satisfiable | The server cannot satisfy the range specified in the request header. | | 429 - Too Many Requests | The user sent too many requests in a specific amount of time. More information is available in the corresponding RFC 6585. | | 500 - Internal Server Error | The server could not complete the request. It could be due to an internal error or sometimes invalid data in the request. | | 502 - Bad Gateway | The server while acting as a gateway or proxy, received an invalid response from the upstream server. | | 503 - Service Unavailable | The service is not available for the request. Seeing this response might indicate a misspelled IBM Cloudant account name. | | 504 - Gateway Timeout | Timeout when the server is acting as a gateway and cannot get a response in time. | | 507 - Insufficient Storage | There is insufficient storage space to complete the request. |

IBM Cloudant HTTP API requests may also fail due to external factors, for example, network errors. These kinds of errors may prevent the server receiving the request or the client receiving the HTTP response. As a result the error format is different in these cases.

Error response

| Name | Description | |------------------------------|---------------------------------------------------------------------------------------| | error string | the error message returned in the response | | reason string | a more detailed description about the cause of the failure | | caused_by (optional) string| the cause of the error |

The HTTP response headers may contain additional information useful for tracing errors.

curl -H "Authorization: Bearer A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" -X GET 'https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud/products'

Error response

{
  "error": "not_found",
  "reason": "Database does not exist."
}

Error response

When the Go SDK receives an error response from the server endpoint it returns a standard Go error. The Error() function of the error returns either the HTTP response error message or a generic error message.

In addition to an error SDK operations may also return a DetailedResponse with methods to retrieve additional information.

| Field | Method | Description | |------------|----------------|----------------------------------------------------------------------| | StatusCode | GetStatusCode | HTTP response status code. | | Result | GetResultAsMap | JSON error response object unmarshalled as map[string]interface{}. | | RawResult | GetRawResult | Raw error response body as []byte. |

| Key | Value description | |-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------| | message | Human readable and printable error message of error and reason. | | error | Error type, for example not_found. | | reason | Error reason, for example Database does not exist. | | caused_by | Additional error cause information if available. | | trace | Trace UUID from the X-Request-ID or X-Couch-Request-ID response header. |

Other errors

HTTP API requests may also fail with other error conditions, for example, validation or networking issues.

For errors unrelated to the HTTP status code the SDK still returns a standard Go error. However, the DetailedResponse information is absent or limited.

An example would be an HTTP request that the server terminates when it exceeds a timeout. In this case the request returns a DetailedResponse with only a StatusCode. The Result and RawResult elements are nil.

Argument validation prevents some invalid values and the SDK does not send the request. This results in Result and RawResult being nil, and a returned error message with no status code or reason.

In all other cases, DetailedResponse is nil because there is no JSON error response from the IBM Cloudant Service.

Example error handling

import (
	"encoding/json"
	"fmt"

	"github.com/IBM/cloudant-go-sdk/cloudantv1"
	"github.com/IBM/go-sdk-core/v5/core"
)

func errorHandlingExample() {
	service, err := cloudantv1.NewCloudantV1(
		&cloudantv1.CloudantV1Options{},
	)
	if err != nil {
		panic(err)
	}

	getDatabaseInformationOptions := service.NewGetDatabaseInformationOptions(
		"products",
	)

	var response core.DetailedResponse
	databaseInformation, response, err := service.GetDatabaseInformation(getDatabaseInformationOptions)
	if err != nil {
		// Use the DetailedResponse to check the HTTP status code
		if response.StatusCode == 404 {
			// Handle database not existing, maybe create it
		} else {
			fmt.Println("Error: ", err.Error())
			fmt.Println("Error status code: ", response.StatusCode)
			// Handle other errors
			errorMap, ok := response.GetResultAsMap()
			if ok {
				// Get the request UUID for what went wrong
				fmt.Println("Trace request UUID: ", errorMap["trace"])
			} else {
				// For example to handle non-JSON response bodies
				fmt.Println("Raw error response: ", response.RawResult)
			}
		}
	}

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

Error response

When the Java SDK receives an error response from the server endpoint it throws a RuntimeException. Specifically a subclass of ServiceResponseException from the com.ibm.cloud.sdk.core.service.exception package. The specific subclass depends on the error encountered.

| Exception class | Description including HTTP status code where applicable | |---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| | ServiceResponseException | Super class for all service response exceptions. | | BadRequestException | 400 Bad Request. | | UnauthorizedException | 401 Unauthorized. | | ForbiddenException | 403 Forbidden. | | NotFoundException | 404 Not Found. | | NotAcceptableException | 406 Not Acceptable. | | ConflictException | 409 Conflict. | | RequestTooLargeException | 413 Request Entity Too Large. | | UnsupportedException | 415 Unsupported media type. | | TooManyRequestsException | 429 Too Many Requests. | | InternalServerErrorException | 500 Internal server error. | | ServiceUnavailableException | 503 Service Unavailable. | | InvalidServiceResponseException | Could not process the response body. Most commonly caused when the server truncates a long running query that exceeded the time limit. |

All ServiceResponseException types have methods to retrieve additional error information.

| Method | Description | |--------------------|---------------------------------------------------------------------------| | getStatusCode() | HTTP response status code. | | getMessage() | Human readable and printable error message. | | getDebuggingInfo() | JSON error response body as a Map<String, Object> | | getHeaders() | HTTP response headers. | | getResponseBody() | Raw error response body as String. |

| Key | Value description | |-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------| | message | Human readable and printable error message of error and reason. | | error | Error type, for example not_found. | | reason | Error reason, for example Database does not exist. | | caused_by | Additional error cause information if available. | | trace | Trace UUID from the X-Request-ID or X-Couch-Request-ID response header. |

Other errors

HTTP API requests may also fail with other error conditions, for example, validation or networking issues.

For errors unrelated to the HTTP status code the SDK throws other RuntimeException types.

For example for many networking errors the SDK throws an IOException wrapped in a RuntimeException.

Argument validation prevents some invalid values and the SDK does not send the request. For these cases the SDK throws an IllegalArgumentException.

| Exception class | Description | |--------------------------|------------------------------------------------------------------------------------------------------------| | RuntimeException | Use getCause() to identify the underlying cause. Typically an IOException caused by networking issues. | | IllegalArgumentException | Invalid argument passed to the method. | | IllegalStateException | The operation cannot be performed, for example starting a changes follower that is already started. |

Example error handling

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.DatabaseInformation;
import com.ibm.cloud.cloudant.v1.model.GetDatabaseInformationOptions;
import com.ibm.cloud.sdk.core.service.exception.NotFoundException;
import com.ibm.cloud.sdk.core.service.exception.ServiceResponseException;

public class ErrorHandlingExample {

    public static void main() {
        Cloudant service = Cloudant.newInstance();

        GetDatabaseInformationOptions databaseInfoOptions =
                new GetDatabaseInformationOptions.Builder().db("products").build();

        try {
            DatabaseInformation response =
                    service.getDatabaseInformation(databaseInfoOptions).execute().getResult();
            System.out.println(response);
        } catch (NotFoundException e) {
            // Handle database not existing, maybe create it
        } catch (ServiceResponseException e) {
            System.out.println("Error: " + e.getMessage());
            System.out.println("Error status code: " + e.getStatusCode());
            System.out.println("Trace UUID: " + e.getDebuggingInfo().getOrDefault("trace", "No trace available"));
        } catch (RuntimeException e) {
            e.printStackTrace();
        }
    }
}

Error response

When the Node SDK receives an error response from the server endpoint it creates an Error that contains either the HTTP response error message or a generic error message. The Promise returned from the SDK operation rejects with this Error.

For HTTP response errors the properties of the of Error include additional information.

| Property | Description | |------------|---------------------------------------------| | status | HTTP response status code. | | statusText | Text description of the status code. | | message | Human readable and printable error message. | | result | Error JSON response body as an object. | | body | Raw error response body as a string. |

| Key | Value description | |-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------| | error | Error type, for example not_found. | | reason | Error reason, for example Database does not exist. | | caused_by | Additional error cause information if available. | | trace | Trace UUID from the X-Request-ID or X-Couch-Request-ID response header. |

Other errors

HTTP API requests may also fail with other error conditions, for example, validation or networking issues.

For errors unrelated to the HTTP status code the SDK still rejects with an Error. However, the available error properties may be more limited.

For these errors message still provides a summary of the problem. There is no status defined since there is no HTTP response status code. The statusText or body contain additional information.

When an error prevents the request reaching the service the Error code property may be useful.

An example is argument validation that prevents some invalid values and the SDK does not send the request. Invalid argument values reject with an Error object containing a code field with the value ERR_INVALID_ARG_VALUE.

| Property | Description | |------------|-----------------------------------------------------------| | message | Human readable and printable error message. | | statusText | Text description of the status code. | | body | Raw error response body as a string. | | code | Code for some errors that occur before sending a request. |

Example error handling

import { CloudantV1 } from '@ibm-cloud/cloudant';

function errorHandlingExample() {
  const service = CloudantV1.newInstance({});

  return service.getDatabaseInformation({ db: "products"})
    .then(response => {
      console.log(response.result);
    }).catch((error) => {
      console.log(`Error message:      ${error.message}`);
      console.log(`Error status text:  ${error.statusText}`);
      if (error.status) {
        if (error.status === 404) {
          // Handle database not existing, maybe create it
        } else {
          console.log(`Error status code:  ${error.status}`);
          console.log(`Trace request UUID: ${error?.result?.trace}`);
        }
      } else if (error.code) {
        console.log(`Error code:         ${error.code}`);
      } else {
        console.log(`Error body:         ${error.body}`);
      }
    });
}

await errorHandlingExample();

Error response

When the Python SDK receives an error response from the server endpoint it raises a standard Python Exception. For HTTP response errors the subclass is ApiException from the ibm_cloud_sdk_core module. The ApiException includes more information about the cause of the failure.

| Attribute | Description | |---------------|------------------------------------------------------------| | code | HTTP response status code | | message | Human readable and printable error message. | | http_response | Raw requests.response object for the HTTP response body. |

Use the json() method of the http_response attribute to obtain even more detailed error information.

| Key | Value description | |-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------| | error | Error type, for example not_found. | | reason | Error reason, for example Database does not exist. | | caused_by | Additional error cause information if available. | | trace | Trace UUID from the X-Request-ID or X-Couch-Request-ID response header. |

Other errors

HTTP API requests may also fail with other error conditions, for example, validation or networking issues.

For errors unrelated to the HTTP status code the SDK still raises an Exception. However, the available error properties are different.

Networking errors and issues like timeouts raise a requests.RequestException. Consult the requests documentation for details of the available subclasses for specific connection related error conditions.

Argument validation prevents some invalid values and the request is not sent. Invalid argument values raise a ValueError exception.

Example error handling

from ibmcloudant.cloudant_v1 import CloudantV1
from ibm_cloud_sdk_core import ApiException
from requests import RequestException

service = CloudantV1.new_instance()

try:
    response = service.get_database_information(db="products").get_result()
    print(response)
except ApiException as ae:
    print("Error message: " + ae.message)
    if ae.status_code == 404:
        # Handle database not existing, maybe create it
        pass
    else:
        print(f'Error status code: {ae.status_code}')
        if 'trace' in (debugInfo := ae.http_response.json()):
            print(f'Trace request UUID: {debugInfo["trace"]}')
except (RequestException, ValueError) as err:
    print(err)

Auditing

You can monitor API activity within your account by using the IBM Cloud® Activity Tracker service. An event is generated for most of the API endpoints when they are called, and you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method. For methods that don't list any events, no events are generated.

For more information about how to track IBM Cloudant activity, see Audit logging.

Additional headers

IBM Cloudant uses HTTP. Set the correct HTTP request headers and process the response headers inline with the HTTP specification. This course of action ensures that you get the correct format and encoding. Different environments and clients are more or less strict on the effect of these HTTP headers, especially when they are not present. To reduce the likelihood of problems or unexpected behavior, be as specific as possible for your client environment.

IBM Cloudant SDKs handle required headers automatically. The SDKs also allow for setting some headers as part of the request options without needing to use custom header code.

You can pass additional request header parameters in all requests or in a single request to the service.

To pass header parameters in a single curl request, use the -H option.

Example header parameter in a request

curl -H 'Custom-Header:custom_value' -H "Authorization: Bearer A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" -X GET https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud

To pass header parameters with every request, use the SetDefaultHeaders method of the service object.

To pass header parameters in a single request, use SetHeaders to include the headers in the options struct before calling the operation.

Example header parameter in all requests

customHeaders := http.Header{}
customHeaders.Add("Custom-Header", "custom_value")
service.SetDefaultHeaders(customHeaders)

Example header parameter in a request

options := service.NewGetServerInformationOptions()

customHeaders := make(map[string]string)
customHeaders["Custom-Header"] = "custom_value"

options.SetHeaders(customHeaders)

serverInformation, response, err := service.GetServerInformation(options)

You can pass request header parameters in all requests or in a single request to the service.

To pass header parameters with every request, use the setDefaultHeaders method of the service object.

To pass header parameters in a single request, use the addHeader method as a modifier before you execute the request.

Example header parameter in all requests

Map<String, String> headers = new HashMap<String, String>();
headers.put("Customer-Header", "custom_value");

service.setDefaultHeaders(headers);

Example header parameter in a request

ServerInformation response = service.getServerInformation()
        .addHeader("Custom-Header", "custom_value")
        .execute();

You can pass request header parameters in all requests or in a single request to the service.

To pass header parameters with every request, specify the set_default_headers method of the service object.

To pass header parameters in a single request, include headers as a dict in the request.

Example header parameter in all requests

const service = CloudantV1.newInstance({
  headers: {
    'Custom-Header': 'custom_value',
  },
});

Example header parameter in a request

service.getServerInformation({
  headers: {
    'Custom-Header': 'custom_value'
  }
}).then(response => {
  console.log(response.result);
});

You can pass request header parameters in all requests or in a single request to the service.

To pass header parameters with every request, specify the set_default_headers method of the service object.

To pass header parameters in a single request, include headers as a dict in the request.

Example header parameter in all requests

headers = {
    'Custom-Header': 'custom_value'
}

service.set_default_headers(headers)

Example header parameter in a request

response = service.get_server_information(
    headers = {
        'Custom-Header': 'custom_value'
    })

Request headers

Additional supported HTTP request headers are:

Accept
Accept-Encoding
Content-Type
Content-Encoding
If-None-Match
Range
X-Request-ID

Accept

The Accept header specifies the list of potential data types returned by the server that the client accepts. The format is a list of one or more MIME types, separated by colons.

For the most requests, the accepted list must include JSON data (application/json).

For attachments, you can either specify the MIME type explicitly, or use */* to specify that the client accepts any type.

If the Accept header is not supplied, then the server assumes the */* MIME type, which means that the client accepts all formats.

The use of Accept in queries to IBM Cloudant is not required, but is highly recommended as it helps to ensure that the client can process the data returned.

If you specify a data type that uses the Accept header, IBM Cloudant honors the specified type in the Content-Type header field of responses. For example, if you explicitly request application/json in the Accept of a request, the returned HTTP headers use this value in the returned Content-Type field.

IBM Cloudant SDKs set this header automatically except for requests where the user controls the content type, for example, attachments.

Example of sending a request without an explicit Accept header, or when you specify */*.

GET /recipes HTTP/1.1
Host: username.cloudant.com
Accept: */*

Example of a returned header when the client accepts all formats.

The returned content type is text/plain even though the information returned by the request is in JSON format.

Server: CouchDB/1.0.2 (Erlang OTP/R14B)
Date: Thu, 13 Jan 2011 13:39:34 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: #7
Cache-Control: must-revalidate

Example request that explicitly specifies the Accept header.

GET /recipes HTTP/1.1
Host: username.cloudant.com
Accept: application/json

Example of the headers returned in response, including the application/json content type.

Server: CouchDB/1.0.2 (Erlang OTP/R14B)
Date: Thu, 13 Jan 2011 13:40:11 GMT
Content-Type: application/json
Content-Length: #7
Cache-Control: must-revalidate

Accept-Encoding

The Accept-Encoding header specifies the server encoding of the response body the client accepts. The supported values are:

gzip
identity

Content-Encoding

The Content-Encoding header specifies the encoding of the request body. The supported value is gzip. If the header is used, the request body must be encoded with the corresponding format.

IBM Cloudant SDKs set this header and compress request bodies automatically.

You can also send compressed request bodies using gzip and curl.

Example creating a gzipped document.

echo '{"foo":"bar"}' | gzip > doc.gzip

Example using the gzipped document in a curl request.

curl "https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud/db/doc" \
	-X PUT \
	-T doc.gzip \
	-H "Content-Encoding: gzip"

Content-Type

The Content-Type header specifies the content type of the HTTP request body. The specification uses MIME type specifications. For most requests, the content type is JSON (application/json).

For some settings, the MIME type is plain text.

In particular, when you upload attachments the type must be the corresponding MIME type for the attachment or binary (application/octet-stream).

The use of the Content-Type on a request is highly recommended.

If-None-Match

The If-None-Match header is optional. You might send it to determine whether a document changed since it was last read or updated. The value of the If-None-Match header must match the last Etag value received. If the value matches the current revision of the document, the server sends a 304 Not Modified status code, and the response itself has no body.

If the document changed, you get a normal 200 response, provided the document still exists and no other errors occurred.

Range

The Range header specifies the parts of an attachment that the server should return. Several parts can be requested at the same time in one Range header, and the server may send back these ranges in a multipart document. If the server sends back ranges, it uses the status line 206 Partial Content for the response.

X-Request-ID

Assign a UUIDv4 (random) to a request for tracing. If the supplied X-Request-ID header value is a valid UUIDv4 it is also returned in the response X-Request-ID header. If the X-Request-ID is not set on a request or the supplied value is not a valid UUIDv4 then the server generates a valid value and returns it in the response X-Couch-Request-ID header.

Response headers

The server returns response headers when you receive content. They include a number of different fields. Many of the fields are standard HTTP response headers and have no significance regarding how IBM Cloudant operates. The supported HTTP response headers that are important to IBM Cloudant are:

Cache-Control
Content-Encoding
Content-Length
Content-Range
Content-Type
Etag
X-Content-Type-Options
X-Couch-Request-ID
X-Frame-Options
X-Request-ID

You can access response headers returned by IBM Cloudant operations to retrieve metadata such as request IDs for tracing and debugging.

The examples show how to retrieve the X-Couch-Request-ID header from a response.

To view response headers in a curl request, use the -i or --include option.

Access the Headers field of the DetailedResponse returned by operations.

Access the Headers object from the Response returned by operations.

Access the headers field of the response object returned by operations.

Access headers using the get_headers() method of the DetailedResponse returned by operations.

Cache-Control

The Cache-Control HTTP response header provides a suggestion for the client cache mechanisms on how to treat the returned information. IBM Cloudant typically returns the must-revalidate value, which indicates that the information must be revalidated if possible. Revalidation ensures that the dynamic nature of the content is correctly updated.

Content-Encoding

Indicates the encoding of the response body as negotiated by the Accept-Encoding request header.

Content-Length

The Content-Length header reports the length in bytes of the returned content.

Content-Range

The Content-Range header specifies where in the full document's attachment a partial content belongs. The value is in the form of bytes <range>/<total content length>. The Range request header is required to specify the partial content to be returned.

Content-Type

The Content-Type header specifies the MIME type of the returned data. For most request, the returned MIME type is text/plain. All text is encoded in Unicode (UTF-8), which is explicitly stated in the returned Content-Type as text/plain;charset=utf-8.

Etag

The Etag header is used to show the revision for a document, or the response from a show function. For documents, the value is identical to the revision of the document. The value can be used with an If-None-Match request header to get a 304 Not Modified response if the revision is still current.

ETags cannot currently be used with views or lists, since the ETags returned from those requests are random numbers that change on every request.

X-Content-Type-Options

The X-Content-Type-Options response HTTP header is a marker used by the server to indicate that the MIME types advertised in the Content-Type headers should be followed and not be changed. This is a security feature to block content sniffing that could transform non-executable MIME types into executable MIME types. By default Cloudant returns X-Content-Type-Options: nosniff that blocks a request if the request destination is of type style and the MIME type is not text/css, or of type script and the MIME type is not a JavaScript MIME type.

X-Couch-Request-ID

A unique identifier generated by the server if the request did not have a valid X-Request-ID header.

X-Frame-Options

The X-Frame-Options is a response header that controls whether an HTTP response can be embedded in a <frame>, <iframe> or <object>. This is a security feature to help against clickjacking. Cloudant returns X-Frame-Options: DENY by default.

X-Request-ID

This header contains a UUIDv4 value matching the one supplied on the request. If a value was not supplied then the server assigns a UUIDv4 in the X-Couch-Request-ID response header.

Example showing response headers

curl -i -H "Authorization: Bearer A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" -X GET https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud/products/1000042

The response includes headers such as X-Couch-Request-ID:

HTTP/1.1 200 OK
X-Couch-Request-ID: 00000000-0000-0000-0000-000000000000
Content-Type: application/json
...

Example retrieving response headers

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

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

// Access response headers
responseHeaders := response.GetHeaders()
couchRequestID := responseHeaders.Get("X-Couch-Request-ID")
fmt.Printf("X-Couch-Request-ID: %s\n", couchRequestID)

Example retrieving response headers

GetDocumentOptions getDocumentOptions = new GetDocumentOptions.Builder()
    .db("products")
    .docId("1000042")
    .build();

Response<Document> response = service.getDocument(getDocumentOptions).execute();

// Access response headers
Headers responseHeaders = response.getHeaders();
String couchRequestId = responseHeaders.values("X-Couch-Request-ID").get(0);
System.out.println("X-Couch-Request-ID: " + couchRequestId);

Example retrieving response headers

service.getDocument({
  db: 'products',
  docId: '1000042'
}).then(response => {
  // Access response headers
  const couchRequestId = response.headers['x-couch-request-id'];
  console.log('X-Couch-Request-ID: ' + couchRequestId);
});

Example retrieving response headers

response = service.get_document(
    db='products',
    doc_id='1000042'
)

## Access response headers
response_headers = response.get_headers()
couch_request_id = response_headers.get('X-Couch-Request-ID')
print(f'X-Couch-Request-ID: {couch_request_id}')

Pagination

Pagination is a best-practice to break apart large queries into multiple server requests. For performance reasons, if you are displaying large amounts of data, you must consider using pagination. It is essential when dealing with large result sets or API endpoints that impose a limit on results returned. Advantages of using pagination include:

Keeps requests within server imposed limits, for example
- 200 max results for text search
- 2000 max results for partitioned queries
Fetches only the necessary data, for example
- User finds required result on first page, no need to continue fetching results
Reduces the duration of any individual query
- Reduces the risk of a query running for longer than the server timeout limit
- Reduces the risk of network request timeouts

Different request types in IBM Cloudant use different pagination approaches. In all cases use the limit parameter to control number of results returned, which is the page size. The chosen page size for an application depends on service limits, document size, latency demands, memory consumption, and other tradeoffs.

The IBM Cloudant SDKs provide built-in pagination to correctly paginate different request types.

Do not use the skip parameter or offset value to paginate. It is not recommended for two reasons. Firstly, entries added or removed from the index between requests can result in missed or duplicated results. Secondly, performance will degrade with increasing skip values. Use the pagination recipes outlined in this section or the built-in pagination of the SDKs instead.

Index key pagination

The primary (document ID) index and IBM Cloudant Views use the index key from the last entry of the previous page to identify the start position of the next page of the query.

For details of how to paginate these request types visit the sections:

Paging all documents
Paging view queries

Bookmark pagination

Imagine you're creating a web application that shows a set of search results, whether they be books, actors, or products in your store. As the user scrolls through the search results, another page of matches is appended at the end. This behavior is known as an "infinite scroll" design pattern. It allows the user to endlessly scroll through a large data set with ease, while they fetch only smaller batches of data from the database each time.

It's this sort of access pattern that IBM Cloudant bookmarks are built for. Here's how it works:

Your application runs a search on an IBM Cloudant database, for example, find me the first 10 cities where the country is "US".
IBM Cloudant provides an array of 10 documents and a bookmark, an opaque key that represents a pointer to the next documents in the result set.
When the next set of results is required, the search is repeated. However, the query is sent, with the bookmark from the first response, to IBM Cloudant in the request.
IBM Cloudant replies with the second set of documents and another bookmark, which can be used to get a third page of results.
Repeat!

IBM Cloudant Query and IBM Cloudant Search provide a bookmark in the response. When passed to the next request the bookmark identifies the next page of results.

For details of how to paginate these request types visit the sections:

Paging selector syntax queries
Paging search index queries

The IBM Cloudant database changes feed is similar, but uses a sequence identifier instead of a bookmark. For details of how to paginate changes visit the section:

Paging the changes feed

The SDK pagination feature accepts options for a single operation and automatically creates the multiple requests to the server necessary to page through the results a fixed number at a time.

For simplicity the examples shown here demonstrate only iterating the result rows. The SDK pagination feature provides multiple alternative pagination options, for full details and examples visit the SDK repository pagination documentation SDK repository pagination documentation SDK repository pagination documentation SDK repository pagination documentation

Paging on all documents

The all documents pagination recipe applies to these endpoints:

GET /{db}/_all_docs
POST /{db}/_all_docs
GET /{db}/_partition/{partition_key}/_all_docs
POST /{db}/_partition/{partition_key}/_all_docs
GET /{db}/_design_docs
POST /{db}/_design_docs

Primary indexes based on the document ID have unique keys. To paginate you need to calculate a value of start_key, which means the next ID after the last _id in the result set.

There are two options to either get or calculate the next start_key.

Option 1 - Fetch one document too many

Instead of fetching five documents limit=5, fetch 5+1 limit=6, but hide the sixth document from your users. The _id of the sixth document becomes the start_key of your request for the next page of results.

This option always works, but you end up fetching n+1 documents when only n are required.

Option 2 - The \u0000 trick

If you're determined to fetch only n documents each time, then you need to calculate a value of start_key. For example, if the last document in the first page of results is "example", what must the start_key of the next call to _all_docs be? It can't be "example", otherwise you get the same document ID again. It turns out that you can append \u0000 to the end of a key string to indicate the "next key" because it is the earliest sorting value.

The \u0000 trick does not work in a descending direction because it is the first sort.

\u0000 is a Unicode null character, which can be placed in a URL as-is or with the percent code %00.

Example of fetch one document too many

curl -H "Authorization: Bearer A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" "https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud/orders/_all_docs?limit=6"

{
  "total_rows": 11,
  "offset": 0,
  "rows": [
    { "id": "4eee973603bf77f30b1f880ed83df76a" ....},
    { "id": "4eee973603bf77f30b1f880ed83f469a" ....},
    { "id": "65fa623a384648740ec1f39b495d591c" ....},
    { "id": "d7404903579d6d5880514c22ad983529" ....},
    { "id": "example" ....},
    { "id": "mydoc" ....} // <-- This is the 6th result we use as the start_key of the next request
   ]
}

curl -H "Authorization: Bearer A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" "https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud/orders/_all_docs?limit=6&start_key=\"mydoc\""

{
  "total_rows": 11,
  "offset": 5,
  "rows": [
    { "id": "mydoc" ....},
    { "id": "order00057" ....},
    ...
   ]
}

Example of the \u0000 trick

curl -H "Authorization: Bearer A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" "https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud/orders/_all_docs?limit=5"

{
  "total_rows": 11,
  "offset": 0,
  "rows": [
    { "id": "4eee973603bf77f30b1f880ed83df76a" ....},
    { "id": "4eee973603bf77f30b1f880ed83f469a" ....},
    { "id": "65fa623a384648740ec1f39b495d591c" ....},
    { "id": "d7404903579d6d5880514c22ad983529" ....},
    { "id": "example" ....} // <-- append \u0000 to this to get the start_key of the next request
   ]
}

curl -H "Authorization: Bearer A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" "https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud/orders/_all_docs?limit=5&start_key=\"example\u0000\""

{
  "total_rows": 11,
  "offset": 5,
  "rows": [
    { "id": "mydoc" ....},
    { "id": "order00057" ....},
    ...
    { "id": "order00067" ....} <-- append \u0000 to this to get the start_key of the next request
   ]
}

The SDK pagination feature is the recommended method to page results on these endpoints.

postAllDocs
postPartitionAllDocs
postDesignDocs
post_all_docs
post_partition_all_docs
post_design_docs
PostAllDocs
PostPartitionAllDocs
PostDesignDocs

The known limitations:
- Cannot reverse direction during pagination.
- No pagination for key option. There is no need to paginate as IDs are unique and this returns only a single row. This is better achieved with a single document get request.
- No pagination for keys option.

Example of paging on all documents

import java.util.List;
import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.DocsResultRow;
import com.ibm.cloud.cloudant.v1.model.PostAllDocsOptions;
import com.ibm.cloud.cloudant.features.pagination.Pager;
import com.ibm.cloud.cloudant.features.pagination.Pagination;

// Initialize service
Cloudant service = Cloudant.newInstance();

// Setup options
PostAllDocsOptions options = new PostAllDocsOptions.Builder()
  .db("orders") // example database name
  .limit(50) // limit option sets the page size
  .startKey("abc") // start from example doc ID abc
  .build();

// Create pagination
Pagination<PostAllDocsOptions, DocsResultRow> pagination = Pagination.newPagination(service, options);
// pagination can be reused without side-effects as a factory for iterables, streams or pagers
// options are fixed at pagination creation time

// Option: iterate rows
// Ideal for using an enhanced for loop with each row.
// The Iterable returned from rows() is reusable in that
// calling iterator() returns a new iterator each time.
// The returned iterators, however, are single use.
for (DocsResultRow row : pagination.rows()) {
  // Do something with row
}

import { CloudantV1, Pagination, PagerType } from '@ibm-cloud/cloudant';
import { Writable } from 'node:stream';
import { pipeline } from 'node:stream/promises';

// Initialize service
const client = CloudantV1.newInstance();

// Setup params
const paginationParams = {
  db: 'orders', // Required: the database name.
  limit: 50, // Optional: limit parameter sets the page size. Default and max is 200.
  startKey: 'abc', // start from example doc ID abc
};

// Create pagination
// pagination can be reused without side-effects as a factory for async iterables, streams or pagers
const pagination = Pagination.newPagination(
  client, // Required: the Cloudant service client instance.
  PagerType.POST_ALL_DOCS, // Required: Pager type
  paginationParams // Required: pagination configuration params are fixed at pagination creation time
);

// Option: iterate rows with for await...of statement
(async () => {
  for await (const row of pagination.rows()) {
    // Do something with row
  }
})();
// Note: Alternatively to for await....of the iterator protocol functions and properties:
// `next()`, `done`, value`, can be also used on rows().
// As `next(`)` returns with a Promise, make sure using `await` or `.then()` on it.

from ibmcloudant import Pager, Pagination, PagerType
from ibmcloudant.cloudant_v1 import CloudantV1

## Initialize service
service = CloudantV1.new_instance()

## Setup options
opts = {
    'db': 'orders',  # example database name
    'limit': 50,  # limit option sets the page size,
    'start_key':  'abc' # start from example doc ID abc
}

## Create pagination
pagination = Pagination.new_pagination(
    service, PagerType.POST_ALL_DOCS, **opts)
## pagination can be reused without side-effects as a factory for iterables or pagers
## options are fixed at pagination creation time

## Option: iterate rows
## Ideal for using a for loop with each row.
## Each call to rows() returns a fresh iterator that can be traversed once.
for row in pagination.rows():
    # Do something with row
    pass

import (
	"github.com/IBM/cloudant-go-sdk/cloudantv1"
	"github.com/IBM/cloudant-go-sdk/features"
)

// Initialize service
service, err := cloudantv1.NewCloudantV1UsingExternalConfig(
	&cloudantv1.CloudantV1Options{},
)
if err != nil {
	panic(err)
}

// Setup options
opts := service.NewPostAllDocsOptions("orders")
opts.SetLimit(50)
opts.SetStartKey("abc")

// Create pagination
// pagination can be reused without side-effects as a factory for iterators or pagers
// options are fixed at pagination creation time
pagination := features.NewAllDocsPagination(service, opts)

// Option: iterate rows
// Ideal for using a for/range loop with each row.
// The iter.Seq2 returned from Rows() has an error as a second element.
for row, err := range pagination.Rows() {
	// Break on err != nil
	// Do something with row
}

Paging on view queries

MapReduce views are secondary indexes defined by key-value pairs produced from user-supplied JavaScript functions. This view pagination approach applies to these endpoints:

GET /{db}/_design/{ddoc}/_view/{view}
POST /{db}/_design/{ddoc}/_view/{view}
GET /{db}/_partition/{partition_key}/_design/{ddoc}/_view/{view}
POST /{db}/_partition/{partition_key}/_design/{ddoc}/_view/{view}

Querying MapReduce views is similar to all documents and view pagination methods also work for all documents. However, unlike the primary index, where every _id is unique, the secondary index might have entries with the same key. For example, lots of entries that include the key "fulfilled". This situation makes pagination by using only start_key/end_key tricky, so you can use other parameters to help: start_key_doc_id/end_key_doc_id.

The best way to paginate view is to fetch one result more than necessary and use that extra result to determine the next page start_key and start_key_doc_id. Instead of fetching five results with limit=5, fetch 5+1 with limit=6, but hide the sixth document from your users. The key of the sixth result becomes the start_key and the _id becomes the start_key_doc_id of your request for the next page of results.

The start_key_doc_id parameter works only if a start_key is supplied and where all index entries share a key. If they don't share a key, then pagination can be achieved with manipulation of start_key/end_key parameters only. Also, the start_key_doc_id parameter is not JSON encoded.

Example of paging on view queries with the \u0000 trick

## get first page of fulfilled orders
curl -H "Authorization: Bearer A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" "https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud/orders/_design/allClients/_view/getStatus?limit=3&start_key=\"fulfilled\"&end_key=\"fulfilled\""

{
  "total_rows": 10,
  "offset": 2,
  "rows": [
    {
      "id": "order00057",
      "key": "fulfilled",
      "value": 1
    },
    {
      "id": "order00058",
      "key": "fulfilled",
      "value": 1
    },
    {
      "id": "order00067", // <-- append \u0000 to the start_key_doc_id to of the next request
      "key": "fulfilled",
      "value": 1
    }
  ]
}

## get next page of fulfilled orders
curl -H "Authorization: Bearer A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" "https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud//orders/_design/allClients/_view/getStatus?limit=3&start_key=\"fulfilled\"&end_key=\"fulfilled\"&start_key_doc_id=order00067%00"

{
  "total_rows": 10,
  "offset": 5,
  "rows": [
    {
      "id": "order00077",
      "key": "fulfilled",
      "value": 1
    }
  ]
}

The SDK pagination feature is the recommended method to page results on these endpoints.

postView
postPartitionView
post_view
post_partition_view
PostView
PostPartitionView

The known limitations:
- Cannot reverse direction during pagination.
- No pagination for key option. Pass the same key as a start and end key instead.
- No pagination for keys option.
- Views that emit multiple identical keys (with the same or different values) from the same document cannot paginate if those key rows with the same ID span a page boundary. The pagination feature detects this condition and an error occurs. It may be possible to workaround using a different page size.

Example of paging on view queries

import java.util.List;
import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.ViewResultRow;
import com.ibm.cloud.cloudant.v1.model.PostViewOptions;
import com.ibm.cloud.cloudant.features.pagination.Pager;
import com.ibm.cloud.cloudant.features.pagination.Pagination;

// Initialize service
Cloudant service = Cloudant.newInstance();

// Setup options
PostViewOptions options = new PostViewOptions.Builder()
  .db("shoppers") // example database name
  .limit(50) // limit option sets the page size
  .ddoc("allUsers") // use the allUsers design document
  .view("getVerifiedEmails") // the view to use
  .build();

// Create pagination
Pagination<PostViewOptions, ViewResultRow> pagination = Pagination.newPagination(service, options);
// pagination can be reused without side-effects as a factory for iterables, streams or pagers
// options are fixed at pagination creation time

// Option: iterate rows
// Ideal for using an enhanced for loop with each row.
// The Iterable returned from rows() is reusable in that
// calling iterator() returns a new iterator each time.
// The returned iterators, however, are single use.
for (ViewResultRow row : pagination.rows()) {
  // Do something with row
}

import { CloudantV1, Pagination, PagerType } from '@ibm-cloud/cloudant';
import { Writable } from 'node:stream';
import { pipeline } from 'node:stream/promises';

// Initialize service
const client = CloudantV1.newInstance();

// Setup params
const paginationParams = {
  db: 'shoppers', // Required: the database name.
  limit: 50, // Optional: limit parameter sets the page size. Default and max is 200.
  ddoc: 'allUsers', // use the allUsers design document
  view: 'getVerifiedEmails', // the view to use
};

// Create pagination
// pagination can be reused without side-effects as a factory for async iterables, streams or pagers
const pagination = Pagination.newPagination(
  client, // Required: the Cloudant service client instance.
  PagerType.POST_VIEW, // Required: Pager type
  paginationParams // Required: pagination configuration params are fixed at pagination creation time
);

// Option: iterate rows with for await...of statement
(async () => {
  for await (const row of pagination.rows()) {
    // Do something with row
  }
})();
// Note: Alternatively to for await....of the iterator protocol functions and properties:
// `next()`, `done`, value`, can be also used on rows().
// As `next(`)` returns with a Promise, make sure using `await` or `.then()` on it.

from ibmcloudant import Pager, Pagination, PagerType
from ibmcloudant.cloudant_v1 import CloudantV1

## Initialize service
service = CloudantV1.new_instance()

## Setup options
opts = {
    'db': 'shoppers',  # example database name
    'limit': 50,  # limit option sets the page size
    'ddoc': 'allUsers',  # use the allUsers design document
    'view': 'getVerifiedEmails' # the view to use
}

## Create pagination
pagination = Pagination.new_pagination(
    service, PagerType.POST_VIEW, **opts)
## pagination can be reused without side-effects as a factory for iterables or pagers
## options are fixed at pagination creation time

## Option: iterate rows
## Ideal for using a for loop with each row.
## Each call to rows() returns a fresh iterator that can be traversed once.
for row in pagination.rows():
    # Do something with row
    pass

import (
	"github.com/IBM/cloudant-go-sdk/cloudantv1"
	"github.com/IBM/cloudant-go-sdk/features"
)

// Initialize service
service, err := cloudantv1.NewCloudantV1UsingExternalConfig(
	&cloudantv1.CloudantV1Options{},
)
if err != nil {
	panic(err)
}

// Setup options
opts := service.NewPostViewOptions("shoppers", "allUsers", "getVerifiedEmails")
opts.SetLimit(50)

// Create pagination
// pagination can be reused without side-effects as a factory for iterators or pagers
// options are fixed at pagination creation time
pagination := features.NewViewPagination(service, opts)

// Option: iterate rows
// Ideal for using a for/range loop with each row.
// The iter.Seq2 returned from Rows() has an error as a second element.
for row, err := range pagination.Rows() {
	// Break on err != nil
	// Do something with row
}

Paging on selector syntax queries

The following endpoints' responses contain a bookmark - a token that IBM Cloudant uses to determine where to resume from when later queries are made. To get the next set of query results, add the bookmark that was received in the previous response to your next request.

POST /{db}/_find
POST /{db}/_partition/{partition_key}/_find

To get the next set of query results for IBM Cloudant Query, add the bookmark that was received in the previous response to your next request. Remember to keep the selector and sort the same, otherwise you receive unexpected results.

The presence of a bookmark doesn’t guarantee more results. You can test whether you are at the end of the result set by comparing the number of results that are returned with the page size requested. If the results returned are less than limit, no more results are available in the result set.

When supplied an incorrect bookmark IBM Cloudant responds with an HTTP 400 Bad Request { error: 'invalid_bookmark'} response.

Example of paging on selector syntax queries

curl -X POST \
     -H "Authorization: Bearer A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" \
     -H 'Content-type: application/json' \
     -d '{"selector":{"country":{"$eq": "US"}},"limit":5}' \
     "https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud/cities/_find"

{
  "docs":[
    {"_id":"10104153","_rev":"1-32aab6258c65c5fc5af044a153f4b994","name":"Silver Lake","latitude":34.08668,"longitude":-118.27023,"country":"US","population":32890,"timezone":"America/Los_Angeles"},
    {"_id":"10104154","_rev":"1-125f589bf4e39d8e119b4b7b5b18caf6","name":"Echo Park","latitude":34.07808,"longitude":-118.26066,"country":"US","population":43832,"timezone":"America/Los_Angeles"},
    {"_id":"4046704","_rev":"1-2e4b7820872f108c077dab73614067da","name":"Fort Hunt","latitude":38.73289,"longitude":-77.05803,"country":"US","population":16045,"timezone":"America/New_York"},
    {"_id":"4048023","_rev":"1-744baaba02218fd84b350e8982c0b783","name":"Bessemer","latitude":33.40178,"longitude":-86.95444,"country":"US","population":27456,"timezone":"America/Chicago"},
    {"_id":"4048662","_rev":"1-e95c97013ece566b37583e451c1864ee","name":"Paducah","latitude":37.08339,"longitude":-88.60005,"country":"US","population":25024,"timezone":"America/Chicago"}
  ],
  "bookmark": "g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58"
}

curl -X POST \
     -H "Authorization: Bearer A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" \
     -H 'Content-type: application/json' \
     -d '{"selector":{"country":{"$eq": "US"}},"limit":5,"bookmark":"g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58"}' \
     "https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud/cities/_find"

{
  "docs":[
    {"_id":"4049979","_rev":"1-1fa2591477c774a07c230571568aeb66","name":"Birmingham","latitude":33.52066,"longitude":-86.80249,"country":"US","population":212237,"timezone":"America/Chicago"},
    {"_id":"4054378","_rev":"1-a750085697685e7bc0e49d103d2de59d","name":"Center Point","latitude":33.64566,"longitude":-86.6836,"country":"US","population":16921,"timezone":"America/Chicago"},
    {"_id":"4058219","_rev":"1-9b4eb183c9cdf57c19be660ec600330c","name":"Daphne","latitude":30.60353,"longitude":-87.9036,"country":"US","population":21570,"timezone":"America/Chicago"},
    {"_id":"4058553","_rev":"1-56100f7e7742028facfcc50ab6b07a04","name":"Decatur","latitude":34.60593,"longitude":-86.98334,"country":"US","population":55683,"timezone":"America/Chicago"},
    {"_id":"4059102","_rev":"1-612ae37d982dc71eeecf332c1e1c16aa","name":"Dothan","latitude":31.22323,"longitude":-85.39049,"country":"US","population":65496,"timezone":"America/Chicago"}
  ],
  "bookmark": "g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWhoaGIGkOWDSyBJZAO9qD40"
}

The SDK pagination feature is the recommended method to page results on these endpoints.

postFind
postPartitionFind
post_find
post_partition_find
PostFind
PostPartitionFind

The known limitations:
- Cannot reverse direction during pagination.

Example of paging on selector syntax queries

import java.util.Collections;
import java.util.List;
import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.Document;
import com.ibm.cloud.cloudant.v1.model.PostFindOptions;
import com.ibm.cloud.cloudant.features.pagination.Pager;
import com.ibm.cloud.cloudant.features.pagination.Pagination;

// Initialize service
Cloudant service = Cloudant.newInstance();

// Setup options
PostFindOptions options = new PostFindOptions.Builder()
  .db("shoppers") // Database name
  .limit(50) // limit option sets the page size
  .fields(List.of("_id", "type", "name", "email")) // return these fields
  .selector(Collections.singletonMap("email_verified", "true")) // select docs with verified emails
  .sort(Collections.singletonList(Collections.singletonMap("email", "desc"))) // sort descending by email
  .build();

// Create pagination
Pagination<PostFindOptions, Document> pagination = Pagination.newPagination(service, options);
// pagination can be reused without side-effects as a factory for iterables, streams or pagers
// options are fixed at pagination creation time

// Option: iterate rows
// Ideal for using an enhanced for loop with each row.
// The Iterable returned from rows() is reusable in that
// calling iterator() returns a new iterator each time.
// The returned iterators, however, are single use.
for (Document row : pagination.rows()) {
  // Do something with row
}

import { CloudantV1, Pagination, PagerType } from '@ibm-cloud/cloudant';
import { Writable } from 'node:stream';
import { pipeline } from 'node:stream/promises';

// Initialize service
const client = CloudantV1.newInstance();

// Setup params
const paginationParams = {
  db: 'shoppers', // Required: the database name.
  limit: 50, // Optional: limit parameter sets the page size. Default and max is 200.
  fields: ['_id', 'type', 'name', 'email'], // return these fields
  selector: { email_verified: { '$eq': true } }, // select docs with verified emails
  sort: [{ email: 'desc' }],
};

// Create pagination
// pagination can be reused without side-effects as a factory for async iterables, streams or pagers
const pagination = Pagination.newPagination(
  client, // Required: the Cloudant service client instance.
  PagerType.POST_FIND, // Required: Pager type
  paginationParams // Required: pagination configuration params are fixed at pagination creation time
);

// Option: iterate rows with for await...of statement
(async () => {
  for await (const row of pagination.rows()) {
    // Do something with row
  }
})();
// Note: Alternatively to for await....of the iterator protocol functions and properties:
// `next()`, `done`, value`, can be also used on rows().
// As `next(`)` returns with a Promise, make sure using `await` or `.then()` on it.

from ibmcloudant import Pager, Pagination, PagerType
from ibmcloudant.cloudant_v1 import CloudantV1

## Initialize service
service = CloudantV1.new_instance()

## Setup options
opts = {
    'db': 'shoppers',  # example database name
    'limit': 50,  # limit option sets the page size
    'fields': ['_id', 'type', 'name', 'email'],  # return these fields
    'selector': {'email_verified': True},  # select docs with verified emails
    'sort': [{'email': 'desc'}]  # sort descending by email
}

## Create pagination
pagination = Pagination.new_pagination(
    service, PagerType.POST_FIND, **opts)
## pagination can be reused without side-effects as a factory for iterables or pagers
## options are fixed at pagination creation time

## Option: iterate rows
## Ideal for using a for loop with each row.
## Each call to rows() returns a fresh iterator that can be traversed once.
for row in pagination.rows():
    # Do something with row
    pass

import (
	"github.com/IBM/cloudant-go-sdk/cloudantv1"
	"github.com/IBM/cloudant-go-sdk/features"
)

// Initialize service
service, err := cloudantv1.NewCloudantV1UsingExternalConfig(
	&cloudantv1.CloudantV1Options{},
)
if err != nil {
	panic(err)
}

// Setup options
opts := service.NewPostFindOptions("shoppers", map[string]any{"email_verified": true})
opts.SetLimit(50)
opts.SetFields([]string["_id", "type", "name", "email"])
opts.SetSort([]map[string]string{map[string]string{"email": "desc"}})

// Create pagination
// pagination can be reused without side-effects as a factory for iterators or pagers
// options are fixed at pagination creation time
pagination := features.NewFindPagination(service, opts)

// Option: iterate rows
// Ideal for using a for/range loop with each row.
// The iter.Seq2 returned from Rows() has an error as a second element.
for row, err := range pagination.Rows() {
	// Break on err != nil
	// Do something with row
}

Paging on search index queries

IBM Cloudant Search queries use bookmarks for pagination. Pass the bookmark parameter in the URL for GET requests or in the JSON body for POST requests. You must keep the same query (the same "q" in IBM Cloudant Search) to get the next page of results. If you change the query, you might get an empty result set in reply.

GET /{db}/_design/{ddoc}/_search/{index}
POST /{db}/_design/{ddoc}/_search/{index}
GET /{db}/_partition/{partition_key}/_design/{ddoc}/_search/{index}
POST /{db}/_partition/{partition_key}/_design/{ddoc}/_search/{index}

See the documentation about query parameters for further details.

Example of paging on search index queries

curl -H "Authorization: Bearer A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" "https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud/cities/_search/search/_search/freetext?q=country:US&limit=5"

{
  "total_rows": 65,
  "rows":[
    {"_id":"10104153","_rev":"1-32aab6258c65c5fc5af044a153f4b994","name":"Silver Lake","latitude":34.08668,"longitude":-118.27023,"country":"US","population":32890,"timezone":"America/Los_Angeles"},
    {"_id":"10104154","_rev":"1-125f589bf4e39d8e119b4b7b5b18caf6","name":"Echo Park","latitude":34.07808,"longitude":-118.26066,"country":"US","population":43832,"timezone":"America/Los_Angeles"},
    {"_id":"4046704","_rev":"1-2e4b7820872f108c077dab73614067da","name":"Fort Hunt","latitude":38.73289,"longitude":-77.05803,"country":"US","population":16045,"timezone":"America/New_York"},
    {"_id":"4048023","_rev":"1-744baaba02218fd84b350e8982c0b783","name":"Bessemer","latitude":33.40178,"longitude":-86.95444,"country":"US","population":27456,"timezone":"America/Chicago"},
    {"_id":"4048662","_rev":"1-e95c97013ece566b37583e451c1864ee","name":"Paducah","latitude":37.08339,"longitude":-88.60005,"country":"US","population":25024,"timezone":"America/Chicago"}
  ],
  "bookmark": "g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58"
}

curl -H "Authorization: Bearer A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" "https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud/cities/_search/search/_search/freetext?q=country:US&limit=5&bookmark=g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58"

{
  "total_rows": 65,
  "rows":[
    {"_id":"4049979","_rev":"1-1fa2591477c774a07c230571568aeb66","name":"Birmingham","latitude":33.52066,"longitude":-86.80249,"country":"US","population":212237,"timezone":"America/Chicago"},
    {"_id":"4054378","_rev":"1-a750085697685e7bc0e49d103d2de59d","name":"Center Point","latitude":33.64566,"longitude":-86.6836,"country":"US","population":16921,"timezone":"America/Chicago"},
    {"_id":"4058219","_rev":"1-9b4eb183c9cdf57c19be660ec600330c","name":"Daphne","latitude":30.60353,"longitude":-87.9036,"country":"US","population":21570,"timezone":"America/Chicago"},
    {"_id":"4058553","_rev":"1-56100f7e7742028facfcc50ab6b07a04","name":"Decatur","latitude":34.60593,"longitude":-86.98334,"country":"US","population":55683,"timezone":"America/Chicago"},
    {"_id":"4059102","_rev":"1-612ae37d982dc71eeecf332c1e1c16aa","name":"Dothan","latitude":31.22323,"longitude":-85.39049,"country":"US","population":65496,"timezone":"America/Chicago"}
  ],
  "bookmark": "g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWhoaGIGkOWDSyBJZAO9qD40",
}

The SDK pagination feature is the recommended method to page results on these endpoints.

postSearch
postPartitionSearch
post_search
post_partition_search
PostSearch
PostPartitionSearch

The known limitations:
- Cannot reverse direction during pagination.
- No pagination of grouped results.
- No pagination of faceted counts or ranges results.

Example of paging on search index queries

import java.util.List;
import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.SearchResultRow;
import com.ibm.cloud.cloudant.v1.model.PostSearchOptions;
import com.ibm.cloud.cloudant.features.pagination.Pager;
import com.ibm.cloud.cloudant.features.pagination.Pagination;

// Initialize service
Cloudant service = Cloudant.newInstance();

// Setup options
PostSearchOptions options = new PostSearchOptions.Builder()
  .db("shoppers") // example database name
  .limit(50) // limit option sets the page size
  .ddoc("allUsers") // use the allUsers design document
  .index("activeUsers") // search in this index
  .query("name:Jane* AND active:True") // Lucene search query
  .build();

// Create pagination
Pagination<PostSearchOptions, SearchResultRow> pagination = Pagination.newPagination(service, options);
// pagination can be reused without side-effects as a factory for iterables, streams or pagers
// options are fixed at pagination creation time

// Option: iterate rows
// Ideal for using an enhanced for loop with each row.
// The Iterable returned from rows() is reusable in that
// calling iterator() returns a new iterator each time.
// The returned iterators, however, are single use.
for (SearchResultRow row : pagination.rows()) {
  // Do something with row
}

import { CloudantV1, Pagination, PagerType } from '@ibm-cloud/cloudant';
import { Writable } from 'node:stream';
import { pipeline } from 'node:stream/promises';

// Initialize service
const client = CloudantV1.newInstance();

// Setup params
const paginationParams = {
  db: 'shoppers', // Required: the database name.
  limit: 50, // Optional: limit parameter sets the page size. Default and max is 200.
  ddoc: 'allUsers', // use the allUsers design document
  index: 'activeUsers', // search in this index
  query: 'name:Jane* AND active:True', // Lucene search query
};

// Create pagination
// pagination can be reused without side-effects as a factory for async iterables, streams or pagers
const pagination = Pagination.newPagination(
  client, // Required: the Cloudant service client instance.
  PagerType.POST_SEARCH, // Required: Pager type
  paginationParams // Required: pagination configuration params are fixed at pagination creation time
);

// Option: iterate rows with for await...of statement
(async () => {
  for await (const row of pagination.rows()) {
    // Do something with row
  }
})();
// Note: Alternatively to for await....of the iterator protocol functions and properties:
// `next()`, `done`, value`, can be also used on rows().
// As `next(`)` returns with a Promise, make sure using `await` or `.then()` on it.

from ibmcloudant import Pager, Pagination, PagerType
from ibmcloudant.cloudant_v1 import CloudantV1

## Initialize service
service = CloudantV1.new_instance()

## Setup options
opts = {
    'db': 'shoppers',  # example database name
    'limit': 50,  # limit option sets the page size
    'ddoc': 'allUsers',  # use the allUsers design document
    'index': 'activeUsers',  # search in this index
    'query': 'name:Jane* AND active:True'  # Lucene search query
}

## Create pagination
pagination = Pagination.new_pagination(
    service, PagerType.POST_SEARCH, **opts)
## pagination can be reused without side-effects as a factory for iterables or pagers
## options are fixed at pagination creation time

## Option: iterate rows
## Ideal for using a for loop with each row.
## Each call to rows() returns a fresh iterator that can be traversed once.
for row in pagination.rows():
    # Do something with row
    pass

import (
	"github.com/IBM/cloudant-go-sdk/cloudantv1"
	"github.com/IBM/cloudant-go-sdk/features"
)

// Initialize service
service, err := cloudantv1.NewCloudantV1UsingExternalConfig(
	&cloudantv1.CloudantV1Options{},
)
if err != nil {
	panic(err)
}

// Setup options
opts := service.NewPostSearchOptions("shoppers", "allUsers", "activeUsers", "name:Jane* AND active:True")
opts.SetLimit(50)

// Create pagination
// pagination can be reused without side-effects as a factory for iterators or pagers
// options are fixed at pagination creation time
pagination := features.NewSearchPagination(service, opts)

// Option: iterate rows
// Ideal for using a for/range loop with each row.
// The iter.Seq2 returned from Rows() has an error as a second element.
for row, err := range pagination.Rows() {
	// Break on err != nil
	// Do something with row
}

Paging the changes feed

Sending a request to /_changes endpoint returns a list of changes that were made to documents in the database, including insertions, updates, and deletions. The _changes endpoint has a limit parameter to control how many changes you would like to receive. The since parameter gets a list of changes that occurred after a specified sequence identifier.

The changes feed supplies result rows at least once and callers must expect potential duplicates.

Use limit and since to paginate the changes feed. To get the since parameter for the next page use the last_seq from the previous page of results.

If the since identifier is 0 (the default), or omitted, the request returns all changes. If the since identifier is now, the request asks for changes that are made after the current time.

Example of paging on the changes feed

curl -H "Authorization: Bearer A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" -X GET "https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud/orders/_changes?limit=5" -H "Content-Type: application/json"

{
    "results": [
        {"seq": "1-g1AAAA...", "id": "4eee973603bf77f30b1f880ed83df76a", "changes": [{"rev": "1-9d0c2..."}]},
        {"seq": "2-g1AAAA...", "id": "4eee973603bf77f30b1f880ed83f469a", "changes": [{"rev": "1-b1f67..."}]},
        ...
    ],
    "last_seq": "6-g1AAAA...",  // <-- This is the sequence we use as the since parameter of the next request
    "pending": 2998
}

curl -H "Authorization: Bearer A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" -X GET "https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud/orders/_changes?limit=5&since=6-g1AAAA..." -H "Content-Type: application/json"

{
    "results": [
        {"seq": "6-g1AAAA...", "id": "65fa623a384648740ec1f39b495d591c", "changes": [{"rev": "1-00203..."}]},
        {"seq": "7-g1AAAA...", "id": "d7404903579d6d5880514c22ad983529", "changes": [{"rev": "1-9410b..."}]},
        ...
    ],
    "last_seq": "10-g1AAAA...",
    "pending": 2993
}

The SDK provides a changes feed follower utility. This helper utility connects to the _changes endpoint and returns the individual change items. It removes some complexity of using the _changes endpoint by setting some options automatically and providing error suppression and retries.

The page size is not configurable in the SDK changes followers. It is set to an appropriate value for reasonable response sizes.

The limit parameter controls the total number of changes received by the SDK changes follower using multiple pages if necessary.

Example of paging with changes follower

import java.util.stream.Stream;
import com.ibm.cloud.cloudant.features.ChangesFollower;
import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.Change;
import com.ibm.cloud.cloudant.v1.model.ChangesResultItem;
import com.ibm.cloud.cloudant.v1.model.PostChangesOptions;

public class StartOneOffAndProcess {
    public static void main(String[] args) {

        Cloudant client = Cloudant.newInstance();

        // Start from a perviously persisted seq
        // Normally this would be read by the app from persistent storage
        // e.g. String previouslyPersistedSeq = yourAppPersistenceReadFunction();
        String previouslyPersistedSeq = "3-g1AG3...";
        PostChangesOptions options = new PostChangesOptions.Builder("example")
            .since(previouslyPersistedSeq)
            .build();
        ChangesFollower changesFollower = new ChangesFollower(client, options);
        Stream<ChangesResultItem> changesItems = changesFollower.startOneOff();
        changesItems.forEach(changesItem -> {
            // do something with changes
            System.out.println(changesItem.getId());
            for (Change change : changesItem.getChanges()) {
                System.out.println(change.getRev());
            }
            // when change item processing is complete app can store seq
            String seq = changesItem.getSeq();
            // write seq to persistent storage for use as since if required to resume later
            // e.g. call yourAppPersistenceWriteFunction(seq);
        });
        // Note: java.util.Stream terminal operations are blocking, code here will be unreachable
        // until all changes are processed (or another stop condition is reached).
    }
}

const client = CloudantV1.newInstance();
// Start from a previously persisted seq
// Normally this would be read by the app from persistent storage
// e.g. previouslyPersistedSeq = yourAppPersistenceReadFunc()
const previouslyPersistedSeq = '3-g1AG3...';
const changesParams = {
  db: 'example',
  since: previouslyPersistedSeq
};
const changesFollower = new ChangesFollower(client, changesParams);
const changesItemsStream = changesFollower.startOneOff();

const destinationStream = new Writable({
  objectMode: true,
  write(changesItem, _, callback) {
    // do something with change item
    console.log(changesItem.id);
    for (const change of changesItem.changes) {
      console.log(change.rev);
    }
    // when change item processing is complete app can store seq
    const seq = changesItem.seq;
    // write seq to persistent storage for use as since if required to resume later
    // e.g. yourAppPersistenceWriteFunc()
    callback();
  }
});

pipeline(changesItemsStream, destinationStream)
  .then(() => {
    console.log('All changes done');
  })
  .catch((err) => {
    console.log(err);
  });

// use for-async-loop feature for stream
/*
getChangesFromFollower(changesItemsStream);
async function getChangesFromFollower(changesItemsStream) {
  for await (const changesItem of changesItemsStream) {
    // do something with change item
    // write seq to persistent storage for use as since
    console.log(changesItem.id);
    for (const change of changesItem.changes) {
      console.log(change.rev);
    }
    // when change item processing is complete app can store seq
    seq = changesItem.seq;
    // write seq to persistent storage for use as since if required to resume later
    // e.g. yourAppPersistenceWriteFunc();
  }
}
*/

import ChangesFollower
from ibmcloudant.cloudant_v1 import CloudantV1

client = CloudantV1.new_instance()

## Start from a previously persisted seq
## Normally this would be read by the app from persistent storage
## e.g. previously_persisted_seq = your_app_persistence_read_func()
previously_persisted_seq = '3-g1AG3...'
changes_follower = ChangesFollower(
    service=client,
    **{'db': 'example', 'since': previously_persisted_seq})

changes_items = changes_follower.start_one_off()
for changes_item in changes_items:
    # do something with changes
    print(changes_item.id)
    for change in changes_item.changes:
        print(change.rev)
    # when change item processing is complete app can store seq
    seq = changes_item.seq
    # write seq to persistent storage for use as since if required to resume later
    # e.g. your_app_persistence_write_func(seq)

## Note: iterator above is blocking, code here will be unreachable
## until all changes are processed (or another stop condition is reached).

package main

import (
	"fmt"

	"github.com/IBM/cloudant-go-sdk/cloudantv1"
	"github.com/IBM/cloudant-go-sdk/features"
)

func main() {
	client, err := cloudantv1.NewCloudantV1UsingExternalConfig(
		&cloudantv1.CloudantV1Options{},
	)
	if err != nil {
		panic(err)
	}

	postChangesOptions := client.NewPostChangesOptions("example")

	// Start from a previously persisted seq
	// Normally this would be read by the app from persistent storage
	// e.g. prevSeq = yourAppPersistenceReadFunc()
	prevSeq := "3-g1AG3..."
	postChangesOptions.SetSince(prevSeq)

	follower, err := features.NewChangesFollower(client, postChangesOptions)
	if err != nil {
		panic(err)
	}

	changesCh, err := follower.StartOneOff()
	if err != nil {
		panic(err)
	}

	for changesItem := range changesCh {
		// changes item structure returns an error on failed requests
		item, err := changesItem.Item()
		if err != nil {
			panic(err)
		}

		// do something with changes
		fmt.Printf("%s\n", *item.ID)
		for _, change := range item.Changes {
			fmt.Printf("%s\n", *change.Rev)
		}

		// when change item processing is complete app can store seq
		seq := *item.Seq
		// write seq to persistent storage for use as since if required
		// to resume later, e.g. yourAppPersistenceWriteFunc(seq)
	}

	// Note: iterating the returned channel above is blocking, code here
	// will be unreachable until all changes are processed
	// or another stop condition is reached.
}

Rate limiting

Rate limits for API requests are enforced on a per-service-instance basis. If the number of requests for a particular request class (read, write or global query) reaches the limit within the given time window, no further requests of that class are accepted until the next time window.

If you want to learn more about these request classes, see the Request classes documentation.

You can view your usage with IBM Cloud Monitoring. For more information see monitoring documentation.

A 429 HTTP status code indicates that the rate limit has been exceeded.

The number of allowed requests varies by request class. The reference information for each endpoint and method specifies the request class that applies to the request. The rate limit for each request class is determined by the account plan.

Related APIs

Most requests and responses to and from IBM® Cloudant® for IBM Cloud® use JavaScript Object Notation (JSON) for formatting the content and structure of the data and responses.

In IBM Cloudant databases, the JSON object is used to represent various structures, including all documents in a database.

Parsing JSON into a JavaScript object is supported through the JSON.parse() function in JavaScript, or through various libraries that perform the parsing of the content into a JavaScript object for you. Libraries for parsing and generating JSON are available for many major programming languages.

JSON is used because it's the simplest and easiest solution for working with data that uses a web browser. As a result, JSON structures can be evaluated and used as JavaScript objects within the web browser environment. JSON also integrates with the server-side JavaScript used within IBM Cloudant. JSON documents are always UTF-8 encoded.

Be careful to follow these guidelines:

Your JSON structures are valid.
You normalize strings in JSON documents retrieved from IBM Cloudant.

JSON supports the same basic types that are supported by JavaScript: numbers, strings, Booleans, arrays, and objects.

Numbers

Numbers can be integer or floating point values.

Example of a number in JSON format

Strings

Strings must be enclosed by double quotation marks. Strings support Unicode characters and escaping a backslash.

Example of a string in JSON format

"A String"

Booleans

A true or false value.

Example of a boolean in JSON format

{
  "value": true
}

Arrays

A list of values enclosed in brackets. The values that are enclosed can be any valid JSON.

Example of an array in JSON format

[
    "one",
    2,
    "three",
    [],
    true,
    {
        "foo":
        "bar"
    }
]

Example of an array in JSON format (linear)

[ "one", 2, "three", [], true, { "foo": "bar" } ]

Objects

A set of key-value pairs, such as an associative array, or a hash. The key must be a string, but the value can be any of the supported JSON values.

Example of a JSON object

{
    "servings" : 4,
    "subtitle" : "Easy to make in advance, and then cook when ready",
    "cooktime" : 60,
    "title" : "Chicken Coriander"
}

Logging

The SDK provides a logging facility with levels Error, Info, Warn, and Debug. By default this logger outputs messages to the standard error stream. The default logging level is Error. With Debug level enabled HTTP messages and retry attempts become visible.

The Go SDK's core library also defines a Logger interface, where you can supply your own logging implementation. For example, you can direct the log messages to a file instead of the console. To use this advanced feature, implement the Logger interface and then call the SetLogger(yourLogger) function to set your implementation to handle the log messages.

The SDK uses the java.util.logging framework for logging messages. You can configure the logging framework to create and configure loggers, handlers (for example ConsoleHandler or FileHandler) and formatters. Configuring a ConsoleHandler for the com.ibm.cloud.sdk.core package outputs SDK logging messages to the standard error stream.

Configuring the level for your logger controls the message visibility. You can use the standard java.util.logging.Level value constants: OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL.

For additional HTTP activity logging configure com.ibm.cloud.sdk.core.http.HttpConfigOptions and call configureClient(options) with it. The logging detail levels are: NONE, BASIC, HEADERS,BODY. To view these messages both set the logger and handler levels for com.ibm.cloud.sdk.core.http to FINE or below.

You can also define the configuration in a file, then supply the name of the file to the logging framework when you run your application. To use a particular configuration file when running your java application, specify the name of the configuration file with the java.util.logging.config.file system property, like this

java -jar myapp.jar -Djava.util.logging.config.file=logging.properties mypackage.MyMainClass

The SDK uses the debug package for logging. To see the log output, enable debug with string built up of ibm-cloud-sdk-core: followed by the wanted log level. The available levels are: error, warning, info, verbose, and debug. To see messages from all available levels you can use * like ibm-cloud-sdk-core*. To configure debug logger for more than one library use a comma-separated string like ibm-cloud-sdk-core:debug,cloudant-node-sdk:debug. For example to obtain maximum logging you can set the environment variable DEBUG='ibm-cloud-sdk-core*,cloudant-node-sdk*'.

The debug package logs to the standard error stream. To change output you must override the log or the stderr stream.

The Python SDK uses Python's built-in logging module to perform logging messages with levels of: CRITICAL, ERROR, WARNING, INFO and DEBUG. To enable logging, import the logging package then set the preferred log level.

With DEBUG level enabled HTTP messages and retry attempts become visible.

By default the basic configuration outputs messages to the standard error stream.

Example of logging to the standard error stream

// Enable Debug logging
core.SetLoggingLevel(core.LevelDebug)

import java.util.logging.Logger;
import java.util.logging.ConsoleHandler;
import com.ibm.cloud.sdk.core.http.HttpConfigOptions;

// Set logger on core with FINE level
Logger sdkLogger = Logger.getLogger("com.ibm.cloud.sdk.core");
sdkLogger.setLevel(Level.FINE);

// Configure the logging output to the standard error stream with FINE level
ConsoleHandler handler = new ConsoleHandler();
handler.setLevel(Level.FINE);

// Set the HTTP logging level to BASIC
HttpConfigOptions options =
    new HttpConfigOptions.Builder()
        .loggingLevel(HttpConfigOptions.LoggingLevel.BASIC)
    .build();

service.configureClient(options);

import debug from 'debug'

// Enable debug logs on ibm-cloud-sdk-core and error logs on @ibm-cloud/cloudant packages
debug.enable('ibm-cloud-sdk-core:debug,cloudant-node-sdk:error');

// You must use dynamic imports (`await import(...)`) for monitored packages
// to ensure they load only after debug has been enabled.
const { CloudantV1 } = await import('@ibm-cloud/cloudant');
const { BasicAuthenticator } = await import('ibm-cloud-sdk-core');

import logging

## Enable DEBUG logging level which writes with a handler that display messages on the console
logging.basicConfig(level=logging.DEBUG)

Example of logging to a file

// Enable custom file logger
type FileLogger struct {
	logLevel core.LogLevel // use log levels defined in core
	logFile *os.File
}
func NewFileLogger(level core.LogLevel, filename string) *FileLogger {
	logFile, err := os.OpenFile(filename, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
	if err != nil {
        log.Fatalf("Failed to open log file: %v", err)
    }
	return &FileLogger{
		logLevel: level,
		logFile: logFile,
	}
}

// Implement the Log function of FileLogger from the Logger interface
func (l *FileLogger) Log(level core.LogLevel, format string, inserts ...interface{}) {
	if l.IsLogLevelEnabled(level) {
		logger := log.New(l.logFile, "", log.LstdFlags)
		logger.Printf(format, inserts...)
	}
}

// Implement all the other functions from the Logger interface for FileLogger
// func (l *FileLogger) Error(format string, inserts ...interface{}) { ... }
// func (l *FileLogger) Warn(format string, inserts ...interface{}) { ... }
// func (l *FileLogger) Info(format string, inserts ...interface{}) { ... }
// func (l *FileLogger) Debug(format string, inserts ...interface{}) { ... }
// func (l *FileLogger) SetLogLevel(level core.LogLevel) { ... }
// func (l *FileLogger) GetLogLevel() core.LogLevel { ... }
// func (l *FileLogger) IsLogLevelEnabled(level core.LogLevel) bool { ... }

// Create a new file logger with debug level
yourLogger := NewFileLogger(core.LevelDebug, "your_log_file.log")
core.SetLogger(yourLogger)

import java.util.logging.Logger;
import java.util.logging.FileHandler;
import com.ibm.cloud.sdk.core.http.HttpConfigOptions;

// Set logger on core with FINE level
Logger sdkLogger = Logger.getLogger("com.ibm.cloud.sdk.core");
sdkLogger.setLevel(Level.FINE);

// Use FileHandler if the target of logging is a file
FileHandler handler = new FileHandler("your_log_file.log")
handler.setLevel(Level.FINE);

// Set the HTTP logging level to BODY
HttpConfigOptions options =
    new HttpConfigOptions.Builder()
        .loggingLevel(HttpConfigOptions.LoggingLevel.BODY)
    .build();

service.configureClient(options);

import fs from 'fs';
import debug from 'debug';

// Create a writable stream for the log file
const logStream = fs.createWriteStream('./your_log_file.log', { flags: 'a' });
// Namespace for all kind of logs on ibm-cloud-sdk-core package
const namespace = 'ibm-cloud-sdk-core*';

// Override global log method of the debug package
Object.getPrototypeOf(debug(namespace)).log = (...args) => {
    logStream.write(args.join(' ') + '\n');
};
// Enable namespace
debug.enable(namespace);

// You must use dynamic imports (`await import(...)`) for monitored packages
// to ensure they load only after debug has been enabled.
const { CloudantV1 } = await import('@ibm-cloud/cloudant');
const { BasicAuthenticator } = await import('ibm-cloud-sdk-core');

import logging

## Enable DEBUG logging level and use filename parameter when the target of logging is a file
logging.basicConfig(level=logging.DEBUG, filename='your_log_file.log')

Cloudant Gen 2 | IBM Cloud API Docs