vania-janet/multiturn-rag-retrieval-data huggingface dataset:
See the following example JSON response with the current and target capacity:

{
"current": {
"throughput": {
"read": 500,
"write": 250,
"blocks": 5,
"query": 25
}
},
"target": {
"throughput": {
"read": 1000,
"write": 500,
"blocks": 10,
"query": 50
}
}
}
Show more





 Set the target provisioned throughput capacity setting 

Use a PUT to the /_api/v2/user/capacity/throughput endpoint to set the target provisioned throughput capacity for an IBM Cloudant instance. When you change the target capacity, the current capacity asynchronously changes to meet the target capacity.

Method
: PUT

Path
: /_api/v2/user/capacity/throughput

Response
: Both the current and target capacity setting, including the number of capacity blocks and total reads/sec, writes/sec, and global queries/sec.

See the following example request to set the target capacity by using HTTP:

PUT $SERVICE_URL/_api/v2/user/capacity/throughput
Content-Type: application/json

See the following example JSON object to set target capacity:

{
"blocks": $NUMBER_OF_BLOCKS
}

Here a block consists of 100 reads/sec, 50 writes/sec, and 5 global queries/sec of provisioned throughput capacity. The $NUMBER_OF_BLOCKS field must be an integer in the range of 1 to 100. Larger capacity sizes can be obtained by contacting IBM Cloudant support.

See the following example request to set the target capacity:



* Curl
* Java
* Node
* Python
* Go



curl -X PUT "$SERVICE_URL/_api/v2/user/capacity/throughput" -H "Content-Type: application/json" --data '{"blocks": 1}'
* Curl
* Java
* Node
* Python
* Go



curl -X PUT "$SERVICE_URL/readings?partitioned=true"

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.Ok;
import com.ibm.cloud.cloudant.v1.model.PutDatabaseOptions;

Cloudant service = Cloudant.newInstance();

PutDatabaseOptions databaseOptions = new PutDatabaseOptions.Builder()
.db("readings")
.partitioned(true)
.build();

Ok response =
service.putDatabase(databaseOptions).execute()
.getResult();

System.out.println(response);

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

const service = CloudantV1.newInstance({});

service.putDatabase({
db: 'readings',
partitioned: true
}).then(response => {
console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.put_database(db='readings', partitioned=True).get_result()

print(response)

putDatabaseOptions := service.NewPutDatabaseOptions(
"readings",
)
putDatabaseOptions.SetPartitioned(true)

ok, response, err := service.PutDatabase(putDatabaseOptions)
if err != nil {
panic(err)
}

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

The previous Go example requires the following import block:

import (
So far, our API interactions were triggered by the dashboard or by using curl from the command line. In the following section, we see how IBM Cloudant is accessed programmatically.

The examples use Node.js, so if you want to try the code yourself, you need to install node and npm from nodejs.org.

We can then install the official IBM Cloudant Node.js library with npm install @cloudant/cloudant. (Npm is the package manager that comes with Node.js - allowing you to access thousands of open source projects and build them into your application for free).

Once the IBM Cloudant library is installed, we can build some source code. Let's go through this code snippet line-by line:

The IBM Cloudant service URL is gleaned from the environment variable that we created earlier.

The @cloudant/cloudant library is loaded into your Node.js app with the built-in required functions. We then create an instance of the library that is configured with the credentials we stored in the first line. We use the IBM Cloudant object to get a reference to the books database and store it in a variable database. We haven't made any API calls - only created data structures that store credentials and which database that we are working on. The main function calls db.list, which maps 1-1 with the _all_docs endpoint we saw earlier. The parameters passed to db.list must be familiar as the options that _all_docs expects to limit the result set and to return document bodies for each ID.

See another code snippet that writes a document.

You can see from the first line that standard JavaScript objects can be used in your code and sent to IBM Cloudant with no conversion, as they turn into JSON natively in JavaScript.

Writing a document is simply a matter of calling db.insert, which maps to a PUT/POST API call or to _bulk_docs.

To summarize, the official libraries for IBM Cloudant are Java™, Python, and Nodejs. They are thin wrappers around the IBM Cloudant HTTP API - so it's worth understanding the underlying API to understand all the parameters.
b, _ := json.MarshalIndent(changesResult, "", " ")
fmt.Println(string(b))

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

const service = CloudantV1.newInstance({});

service.postChanges({
db: 'orders'
}).then(response => {
console.log(response.result);
});

The previous Go example requires the following import block:

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

All Go examples require the service object to be initialized. For more information, see the API documentation's [Authentication section](https://cloud.ibm.com/apidocs/cloudant?code=goauthentication-with-external-configuration) for examples.

When you POST to the _changes endpoint, you see an example similar to the following JSON object:

{"results":[
{"seq":"1-g1AAAA...","id":"0007741142412418284","changes":{"rev":"1-9d0c2676941ec3a3b3cc2f08fe9a51e0"}]},
{"seq":"2-g1AAAA...","id":"_design/applianceId","changes":{"rev":"1-b1f67a8b672c1324680d6d7dc1e1fd3c"}]},
...
],
"last_seq":"18-g1AAAA...","pending":0}
It uses the details from the [Service credential JSON examples for each option](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-managing-access-for-cloudantservice-credential-json-examples-for-each-option-ai).

IBM Cloud IAM requires that an IAM API key is exchanged for a time-limited access token before you make a request to a resource or service. The access token is then included in the Authorization HTTP header to the service. When the access token expires, the consuming application must handle getting a new one from the IAM token service. For more information, see [Getting an IBM Cloud IAM token by using an API key](https://cloud.ibm.com/docs/account?topic=account-iamtoken_from_apikey) documentation for more details.

IBM Cloudant's official client libraries handle obtaining a token from an API key for you. You can access IBM Cloudant directly by using an HTTP client rather than an IBM Cloudant client library. However, you must handle exchanging and refreshing a time-limited access token by using an IAM API key with the IAM token service. After a token expires, IBM Cloudant returns an HTTP 401 status code.



 Required client library versions 

IAM connectivity is available in the latest release of all supported client libraries. For more information, see [Client libraries](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-client-libraries).



 Java 

The following link provides the latest supported version of the IBM Cloudant Java™ library:



* [cloudant-java-sdk](https://github.com/IBM/cloudant-java-sdk/releases)



For an example that uses IBM Cloudant SDK for Java, see the [API and SDK documentation](https://cloud.ibm.com/apidocs/cloudant?code=javaauthentication).





 Node.js 

The following link provides the latest supported version of the IBM Cloudant Node.js library:
In your browser, log in to IBM Cloud and go to the Dashboard. Select Create resource.
2. Search for IBM Cloudant, and select the service.
3. For Available authentication methods, select Use both legacy credentials and IAM. You can leave the default settings for the other fields. Click Create to create the service.
4. In the navigation, go to Connections, then click Create connection. Select your app, and click Connect.
5. Using the default values, click Connect & restage app to connect the database to your app. Click Restage when prompted.

IBM Cloud will restart your app and provide the database credentials to your app using the VCAP_SERVICES environment variable. This environment variable is available to the app only when it is running on IBM Cloud.



Environment variables enable you to separate deployment settings from your source code. For example, instead of specifying a database password in your source code, you can store it in an environment variable that you reference in your source code.





 Step 6: Use the database locally 

We're now going to update your local code to point to this database. We'll store the credentials for the services in a JSON file. This file will get used ONLY when the app is running locally. When running in IBM Cloud, the credentials will be read from the VCAP_SERVICES environment variable.



1. In the src/GetStartedDotnet directory, create a vcap-local.json file.
2. Copy and paste the following JSON object into the vcap-local.json file, and save your changes.

{
"services": {
"cloudantNoSQLDB": [
{
"credentials": {
"url":"CLOUDANT_DATABASE_URL"
},
"label": "cloudantNoSQLDB"
}
]
}
}
3. Find your app in the IBM Cloud [Resource List](https://cloud.ibm.com/resources). On the Service Details page for your app, click Connections in the sidebar.
You can query the API by using one of the following methods: URI, IBM Cloudant Dashboard, curl, or a browser plug-in, such as Postman or RESTClient.

See the following example design document that defines a search index:

{
"_id": "_design/search_example",
"indexes": {
"animals": {
"index": "function(doc){ ... }"
}
}
}



 Search index partitioning type 

A search index inherits the partitioning type from the options.partitioned field of the design document that contains it.





 Index functions 

If you attempt to index by using a data field that doesn't exist, it fails. To avoid this problem, use an appropriate [guard clause](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-cloudant-searchindex-guard-clauses).

Your indexing functions operate in a memory-constrained environment where the document itself forms a part of the memory that is used in that environment. Your code's stack and document must fit inside this memory. Documents are limited to a maximum size of 64 MB.

Within a search index, don't index the same field name with more than one data type. If the same field name is indexed with different data types in the same search index function, you might get an error. This error occurs when you query the search index that says the field was indexed without position data. For example, don't include both of these lines in the same search index function. These lines index the myfield field as two different data types, a string "this is a string" and a number 123.

index("myfield", "this is a string");
index("myfield", 123);

The function that is contained in the index field is a JavaScript function that is called for each document in the database. The function takes the document as a parameter, extracts some data from it, and then calls the function that is defined in the index field to index that data.

The index function takes three parameters, where the third parameter is optional.
: Your [API key](https://cloud.ibm.com/docs/account?topic=account-manapikey) value or a reference to the API Key file used when logging in. For example, ibmcloud login --apikey $KEYFILE

--output JSON
: If specified, output will be returned in JSON format. If JSON is not specified, output will be returned in a tabular format.

help | --help | -h
: List options available for the command.





 Example 

The following is an example using the ibmcloud atracker target create --name my-target --type cloud-object-storage --endpoint s3.us-west.cloud-object-storage.appdomain.cloud --bucket cloud-object-storage-my-cos --target-crn crn:v1:staging:public:cloud-object-storage:global:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:: --api-key yyyyyyyyyyyyyyyyyyyyyyyyyyyyy command.

This example shows an example successful target creation.

Target
Name: my-target
ID: 000000000-00000000-0000-0000-00000000
CRN: crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Type: cloud_object_storage
COS Endpoint: s3.us-west.cloud-object-storage.appdomain.cloud
COS Target CRN: crn:v1:staging:public:cloud-object-storage:global:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:
COS Bucket: cloud-object-my-target
COS API Key: REDACTED
COS Write Status: success
For more information, see the [selector field](https://cloud.ibm.com/apidocs/cloudantpostfind) documentation.

See the following example of a filter function:

function(doc, req) {
return !!(doc.type && doc.type == "foo");
}

Filters are stored under the topmost filters key of the design document.

See the following example of storing a filter function in a design document:

{
"_id": "_design/myddoc",
"filters": {
"myfilter": "function goes here"
}
}

A filtered replication is started by using a JSON statement that identifies the following items:



* The source database.
* The target database.
* The name of the filter that is stored under the filters key of the design document.



See example JSON for starting a filtered replication:

{
"source": "https://$USERNAME:$PASSWORD@example.org/example-database",
"target": "https://$USERNAME:$PASSWORD@$ACCOUNT.cloudant.com/example-database",
"filter": "myddoc/myfilter"
}

Arguments can be supplied to the filter function by including key: value pairs in the query_params field of the invocation.

See example JSON for starting a filtered replication with supplied parameters:

{
"source": "https://$USERNAME:$PASSWORD@example.org/example-database",
"target": "https://$USERNAME:$PASSWORD@$ACCOUNT.cloudant.com/example-database",
"filter": "myddoc/myfilter",
"query_params": {
"key": "value"
}
}

The selector option provides performance benefits when compared with using the filter option. Use the selector option whenever possible. For more information, see the [selector](https://cloud.ibm.com/apidocs/cloudantpostfind) documentation.
Any IBM Cloudant account or API key that is generated outside an EU-managed environment can't be granted access to an EU-managed IBM Cloudant instance. For more information about IBM Cloudant in an EU-managed environment, see [Locations and tenancy](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-ibm-cloud-publiclocations-and-tenancy).



 Creating API keys 

An earlier method of generating API keys by issuing the POST command to the https://cloudant.com/api/generate_api_key endpoint is deprecated.

You can create an API key in the following two ways:



1. Use the dashboard.
2. Use the IBM Cloudant API to [modify the permissions](https://cloud.ibm.com/apidocs/cloudantpostapikeys).



No matter what method you choose, remember to record the key name and password. These values are both randomly generated, and can't be retrieved if lost or forgotten.





 Using API keys 

API keys are typically generated by using an account that has at least one database. It's possible to use the API key with other databases, or even with other accounts.

By default, an API key has no permissions. It must be given permissions explicitly.

After you generate the API key, grant the key access-specific permissions for a specific database by sending a PUT request to https://$ACCOUNT.cloudant.com/_api/v2/db/$DATABASE/_security.

The database isn't required to be in the same account as the account used for generating the API key initially.

To give an existing API key permission to access a database in another account, follow these steps:



1. Retrieve the existing [security permissions](https://cloud.ibm.com/apidocs/cloudantgetsecurity) for the database.
2. [Add](https://cloud.ibm.com/apidocs/cloudantputsecurity) the details of the API key to the database security permissions, along with the roles required.
If JSON is not specified, output will be returned in a tabular format.help | --help | -h: List options available for the command.<-- </section "id="section-target-update-options-cos" "> --><-- <section "id="section-target-update-example-cos" "> --> Example The following is an example using the ibmcloud atracker target update --target my-target --name new-target-name command. Target
Name: 		new-target-name
ID: 		xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CRN: 		crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Type: 		cloud_object_storage
COS Endpoint: 		s3.us-west.cloud-object-storage.appdomain.cloud
COS Target CRN: 		crn:v1:staging:public:cloud-object-storage:global:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:
COS Bucket: 		cloud-object-my-target
Service to Service Enabled:	true
Write Status: 		success
Created: 		2021-07-21T16:04:15.174Z
Updated: 		2021-07-21T17:49:56.452Z
<-- </section "id="section-target-update-example-cos" "> --><-- </section "class="ph" id="section-target-update-cli-cos" "> --><-- <section "class="ph" id="section-target-delete-cli-cos" "> --> Deleting a target using the CLI Use this command to delete a target. ibmcloud atracker target rm --target TARGET --force] ! !
* [Getting help and support for IBM Cloudant](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-help-and-support)



* [Go to product UI](https://cloud.ibm.com/docs/Cloudant) [About this product](https://www.ibm.com/cloud/cloudant)



Expand all | Collapse all

Collapse



1. [IBM Cloud Docs](https://cloud.ibm.com/docs)
2. [Cloudant](https://cloud.ibm.com/docs/Cloudant)
3.



Search in collection

Search in collection





LangSwitcher dropdown

English

Close menu

DeutschEnglish

EspañolFrançaisItaliano日本語한국어Português/Brasil简体中文繁體中文





 How HTTP works with IBM Cloudant * Last updated 2022-11-09 

Learn details about the HTTP headers you need to know when you use IBM® Cloudant® for IBM Cloud®.



 HTTP headers 

Because IBM Cloudant uses HTTP for all external communication, you need to ensure that the correct HTTP request headers are supplied and processed on retrieval. 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, you must be as specific as possible.



 Request headers 

The supported HTTP request headers are shown in the following list:



* Accept
* Content-Type
* Content-Encoding
* If-None-Match





 Accept 

The Accept header specifies the list of potential data types that are returned by the server that would be accepted and understood by the client. The format is a list of one or more MIME types, which are 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 all file types are supported.
documentResult, _, err := service.PutDesignDocument(putDesignDocumentOptions)
if err != nil {
panic(err)
}

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

The previous Go example requires the following import block:

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

All Go examples require the service object to be initialized. For more information, see the API documentation's [Authentication section](https://cloud.ibm.com/apidocs/cloudant?code=goauthentication-with-external-configuration) for examples.
};

const bulkGetDocs = [bulkGetDoc1, bulkGetDoc2];

const postBulkGetParams = {
db: 'orders',
docs: bulkGetDocs,
};

service.postBulkGet(postBulkGetParams)
.then(response => {
console.log(response.result);
});

The previous Go example requires the following import block:

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

All Go examples require the service object to be initialized. For more information, see the API documentation's [Authentication section](https://cloud.ibm.com/apidocs/cloudant?code=goauthentication-with-external-configuration) for examples.

See an example of a JSON object that uses POST to the _bulk_get endpoint:

{
"docs": [
{
"id": "doc1"
},
{
"id": "doc3"
}
]
}

See an example JSON structure that is returned after bulk get:

{
"results": [
{
"id": "doc01",
"docs":
{
"ok": {
"_id": "doc01",
"_rev": "1-f3751e2db1d92e13b0baa6bdeb874c8c",
"simplekey": "somedata"
}
}
]
},
{
"id": "doc03",
"docs":
{
"ok": {
"_id": "doc03",
const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.getAllDbs().then(response => {
console.log(response.result);
});

The previous Go example requires the following import block:

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

All Go examples require the service object to be initialized. For more information, see the API documentation's [Authentication section](https://cloud.ibm.com/apidocs/cloudant?code=goauthentication-with-external-configuration) for examples.

See the following example response that is a JSON array with all the database names:

[
"_users",
"contacts",
"docs",
"invoices",
"locations"
]
panic(err)
}

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

The previous Go example requires the following import block:

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

See the following example response that includes the deleted document ID and revision:

{
"id": "_design/allusers",
"ok": true,
"rev": "3-7a05370bff53186cb5d403f861aca154"
}



 The structure of the delete command 

Method
: DELETE /db/_design/$DDOC

Request
: None.

Response
: JSON of deleted design document.

Roles permitted
: _design

Query Arguments

Argument
: rev

Description
: Current revision of the document for validation.

Optional
: Yes, if If-Match header exists.

Type
: String.

HTTP Headers

Header
: If-Match

Description
: Current revision of the document for validation.

Optional
: Yes, if rev query argument exists.







 Views 

An important use of design documents is for creating views. For more information about creating views, see [Views (MapReduce)](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-creating-views-mapreduce).





 Indexes 

All queries operate on pre-defined indexes that are defined in design documents. These indexes are defined in the following list:



* [Search](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-cloudant-search)
* [MapReduce](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-creating-views-mapreduce)