vania-janet/multiturn-rag-retrieval-data huggingface dataset:
import com.ibm.cloud.cloudant.v1.model.Selector;

import java.util.HashMap;
import java.util.Map;

Cloudant service = Cloudant.newInstance();

Map equalWithDeviceID = new HashMap<>();
equalWithDeviceID.put("$eq", "device-123456");

Map greaterThanOrEqualWithTs = new HashMap<>();
greaterThanOrEqualWithTs.put("$gte", "20181213");

Selector selector = new Selector();
selector.put("deviceID", equalWithDeviceID);
selector.put("ts", greaterThanOrEqualWithTs);

PostPartitionFindOptions findOptions =
new PostPartitionFindOptions.Builder()
.db("readings")
.partitionKey("bridge-9876")
.selector(selector)
.build();

FindResult response =
service.postPartitionFind(findOptions).execute()
.getResult();

System.out.println(response);

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

const service = CloudantV1.newInstance({});

const selector: CloudantV1.Selector = {
deviceID: {'$eq': 'device-123456'},
ts: {'$gte': '20181213'}
}
service.postPartitionFind({
db: 'readings',
partitionKey: 'bridge-9876',
selector: selector
}).then(response => {
console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.post_partition_find(
db='readings',
"ok": true,
"rev": "2-8b904347bfe52e0f388ef6f39d6ba84f"
}
2. To see the update, fetch the document again.

ibmcloud fn action invoke /_/myCloudant/read --blocking --result --param dbname test --param id color

Example document

{
"_id": "color",
"_rev": "2-8b904347bfe52e0f388ef6f39d6ba84f",
"name": "blue",
"shade": "indigo"
}









 Create a trigger by using the filter function 

You can use the changes feed to configure a service to fire a trigger on every change to your IBM Cloudant database.

Before you begin

Create a /whisk.system/cloudant[package binding](https://cloud.ibm.com/docs/openwhisk?topic=openwhisk-pkg_cloudantcloudant_db) that is configured for your IBM Cloudant account.

Parameters that are used in this example.



Table 2. Parameters that are used the following code examples

 Parameter Description 

 dbname (Required) The name of the IBM Cloudant database. 
 iamApiKey (Optional) The IAM API key for the Cloudant database. If specified, this value is used as the credentials instead of username and password. 
 iamUrl (Optional) The IAM token service URL that is used when iamApiKey is specified. The default value is https://iam.cloud.ibm.com/identity/token. 
 maxTriggers (Optional) Stop firing triggers when this limit is reached. Defaults to infinite. 
 filter (Optional) The filter function that is defined in a design document. 
 query_params (Optional) Any additional query parameters that might be needed for the filter function.
"firstname": "Greg",
"lastname": "Greene",
"age": 35,
"location": "San Diego, CA",
"_id": "doc3"
}

Use the following sample text for document 4:

{
"firstname": "Anna",
"lastname": "Greene",
"age": 44,
"location": "Baton Rouge, LA",
"_id": "doc4"
}

Use the following sample text for document 5:

{
"firstname": "Lois",
"lastname": "Brown",
"age": 33,
"location": "New York City, NY",
"_id": "doc5"
}

You populated the dashboard-demo with five documents. You can see the documents from the Table view in the following screen capture:

Zoom

![Example documents shown in the Table view.](https://cloud.ibm.com/docs-content/v1/content/522c6f62358b063f921283400a601c3f9bc66f08/Cloudant/images/docs1.png)

Figure 1. Sample documents





 Running a simple query 

This example demonstrates how IBM Cloudant Query finds documents based on the lastname and the firstname.



1. Click Query.
2. Copy the following sample JSON and replace the existing text in the new query window:

{
"selector": {
"lastname" : "Greene",
"firstname" : "Anna"
}
}
3. Click Run Query.

The query displays the results. You can see them from the Table view in the following screen capture:

Zoom

!
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)



For example, to create a design document that is used for searching, you must ensure that two conditions are true:



1. You defined the document as a design document when you started the _id with _design/.
2. You created a [search index](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-cloudant-search) within the document where you [updated](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-documentsupdate) the document with the appropriate field or [created](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-documentscreate-document) a new document that includes the search index.



As soon as the search index design document exists and the index is built, you can make queries by using it.



 General notes on functions in design documents 

Functions in design documents are run on multiple nodes for each document, and might be run several times. To avoid inconsistencies, they need to be [idempotent](https://en.wikipedia.org/wiki/IdempotenceComputer_science_meaning), meaning they need to behave identically when run multiple times or on different nodes. In particular, you must not use functions that generate random numbers or return the current time.







 Filter functions 

Design documents with options.partitioned set to true can't contain a filters field.

Filter functions are design documents that filter the [changes feed](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-databasesget-changes). They work by applying tests to each of the objects included in the changes feed.
In this example, an IBM Cloudant Query selector is being sent to the book partition. This action means you exercise only a fraction of the IBM Cloudant infrastructure (only the shard that hosts the book partition is used, the rest of the cluster remains idle).

This scenario makes for faster query performance, cheaper query costs, and better scalability.

The key to great partitioned query performance is the choice of partition key:

It needs to be a value that repeats within your data set. For example, several items exist in the book partition. There needs to be many partitions. If you have only a few categories, then category is a bad choice of partition key. It needs to be something that has many values, for example, deviceId in an IoT application or orderId in an e-commerce system. It needs to match the queries that your application is making. If the most common use-case is searching within a product category, then partitioning by category might be a good fit. Avoid hot partitions - traffic must be evenly spread across your partitions. If your choice of partition key is likely to lead to a large increase in traffic that hits a few partitions, then this scenario makes for a poor choice of partition key.

To summarize, partitioned databases are created with the partitioned=true flag, and documents have a two-part ID where the partition key and document key are joined by a colon character.

Documents in the same partition are stored in document key order in the same database shard. Knowing this method of storage, we can make queries that are directed at a single partition that runs faster and more cheaply.

It's still possible to query across partitions in a partitioned database. When you create a secondary index, you choose whether its purpose is for per-partition or global scope.

That's the end of this part. The next part is called IBM Cloudant Search.







 IBM Cloudant Search video 

Learn how to use IBM Cloudant Search, as well as Lucene query language and faceting.



* IBM Cloudant Search video script

Welcome to the Introduction to IBM Cloudant course, an 17-part video series that gives you an overview of the IBM Cloudant database-as-a-service.
"warning": "no matching index found, create an index to optimize query time"
}
Show more
This time, you get the next five cities and a new bookmark ready for the next request.<-- </section "id="section-use-cloudant-query-search" "> --><-- <section "id="section-how-cloudant-search-works" "> --> How does IBM Cloudant Search work? Pagination works in the same way for IBM Cloudant Search]IBM Cloudant Search 1] ! ! queries. Pass the bookmark parameter in the URL for GET requests or in the JSON body for POST requests. See the following example:<-- <ul> --> * Curl * Java * Node * Python * Go<-- </ul> --> curl -H "Authorization: Bearer $API_BEARER_TOKEN" "$SERVICE_URL/cities/_search/search/_search/freetext?q=country:US&limit=5"
import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostSearchOptions;
import com.ibm.cloud.cloudant.v1.model.SearchResult;

Cloudant service = Cloudant.newInstance();

PostSearchOptions.Builder searchOptions = new PostSearchOptions.Builder()
.db("cities")
.ddoc("search")
.index("freetext")
.query("country:US");
.limit(5);

SearchResult response = service.postSearch(searchOptions.build()).execute().getResult();
while (response.getRows().size() > 0) {
System.out.println(response.getRows());
// The bookmark of the next request becomes the bookmark of this response
searchOptions.bookmark(response.getBookmark());
Cloudant service = Cloudant.newInstance();

AllDocsQuery query1 = new AllDocsQuery.Builder()
.keys(Arrays.asList("small-appliances:1000042",
"small-appliances:1000043"))
.build();

AllDocsQuery query2 = new AllDocsQuery.Builder()
.limit(3)
.skip(2)
.build();

PostAllDocsQueriesOptions queriesOptions =
new PostAllDocsQueriesOptions.Builder()
.queries(Arrays.asList(query1, query2))
.db("products")
.build();

AllDocsQueriesResult response =
service.postAllDocsQueries(queriesOptions).execute()
.getResult();

System.out.println(response);

from ibmcloudant.cloudant_v1 import AllDocsQuery, CloudantV1

service = CloudantV1.new_instance()

all_docs_query1 = AllDocsQuery(
keys=['small-appliances:1000042', 'small-appliances:1000043']
)

all_docs_query2 = AllDocsQuery(
limit=3,
skip=2
)

response = service.post_all_docs_queries(
db='products',
queries=[all_docs_query1, all_docs_query2]
).get_result()

print(response)

allDocsQueries := []cloudantv1.AllDocsQuery{
{
Keys: []string{
"small-appliances:1000042",
"small-appliances:1000043",
},
},
{
Limit: core.Int64Ptr(3),
Skip: core.Int64Ptr(2),
},
}
IBM Cloudant Query Parameters 

The $text operator is based on a Lucene search with a standard analyzer. The operator isn't case-sensitive, and matches on any words. However, the $text operator doesn't support full Lucene syntax, such as wildcards, fuzzy matches, or proximity detection.

For more information, see the [Search documentation](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-cloudant-search). The $text operator applies to all strings found in the document. If you place this operator in the context of a field name, it's invalid.

The format of the selector field is as described in the [selector syntax](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-queryselector-syntax), except for the $text operator.

The fields array is a list of fields that must be returned for each document. The provided field names can use dotted notation to access subfields.

See the following example JSON document that uses all available query parameters:

{
"selector": {
"year": {
"$gt": 2010
}
},
"fields": ["_id", "_rev", "year", "title"],
"sort": [{"year": "asc"}],
"limit": 10,
"skip": 0
}
curl -X POST "$SERVICE_URL/readings/_design/infrastructure-mapping/_view/by-device' -H 'Content-Type: application/json' --data '{
"keys": ["device-123456"], "limit": 1
}'

For more language examples that show querying a global view, see the [Query a MapReduce view in API Docs](https://cloud.ibm.com/apidocs/cloudantpostview).

The previous command returns the following response:

{
"total_rows": 5,
"offset": 0,
"rows": [
{
"id": "bridge-9876:device-123456-20181211T11:13:24.123456Z",
"key": "device-123456",
"value": "bridge-9876"
}
]
}

The partition key is in the value field of the included row: bridge-9876.





 Querying for all results for a device 

To get the results for a device, you issue a partition query for the device within the bridge-9876 partition. A standard IBM Cloudant Query selector is used, as if one were issuing a global query.

The partition is embedded in the HTTP path when you issue the request to IBM Cloudant:



* Curl
* Java
* Node
* Python
* Go



curl -X POST "$SERVICE_URL/readings/_partition/bridge-9876/_find" -H 'Content-Type:
application/json' --data '{
"selector": {
"deviceID": {
"$eq": "device-123456"
}
}
}'

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.FindResult;
import com.ibm.cloud.cloudant.v1.model.PostPartitionFindOptions;
Indexing and querying 

The Index and querying document is the second best practice document in the series. It shows you the following best practices:



* How to understand the different results between emitting data into a view or not.
* Why you must never rely on IBM Cloudant Query's ability to query without creating explicit indexes.
* Why you must limit the number of fields with IBM Cloudant Search (or IBM Cloudant Query indexes of type text).
* How to manage design documents.
* Why partitioned queries are faster and cheaper.
* How to use the primary index as a free search index.



For more information, see [Data modeling](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-data-modeling) or [IBM Cloudant in practice](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-cloudant-in-practice).

The content in this document was originally written by Stefan Kruger as a [Best and worst practice](https://blog.cloudant.com/2019/11/21/Best-and-Worst-Practices.html) blog post on 21 November 2019.



 Understand the tradeoffs in emitting data or not into a view 

As the document that is referenced by a view is always available by using include_docs=true, it is possible to do something like the following example to allow lookups on indexed_field:

emit(doc.indexed_field, null);

This example has the following advantages and disadvantages:



* The index is compact. This index size is good, since index size contributes to storage costs.
* The index is robust. Since the index does not store the document, you can access any field without thinking ahead about what to store in the index.
* The disadvantage is that getting the document back is more costly than the alternative of emitting data into the index itself. First, the database has to look up the requested key in the index and then read the associated document. Also, if you’re reading the whole document, but need only a single field, you’re making the database read and transmit data that you don’t need.
console.log(response3.result);
});
from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

 get me 5 documents from _id order00057 onwards
response1 = service.post_all_docs(
db='orders',
start_key='order00057',
limit=5
).get_result()
print(response1)

 get me 5 documents between _id order00057 --> order00077
response2 = service.post_all_docs(
db='orders',
start_key='order00057',
end_key='order00077',
limit=5
).get_result()
print(response2)

 get me 5 documents up to _id order00077
response3 = service.post_all_docs(
db='orders',
end_key='order00077',
limit=5
).get_result()
print(response3)
// get me 5 documents from _id order00057 onwards
postAllDocsOptions1 := cloudantv1.PostAllDocsOptions{
Db: core.StringPtr("orders"),
StartKey: core.StringPtr("order00057"),
Limit: core.Int64Ptr(5),
}
allDocsResult1, response1, err := service.PostAllDocs(postAllDocsOptions1)
if err = nil {
panic(err)
}
b, _ := json.MarshalIndent(allDocsResult1, "", " ")
fmt.Println(string(b))

// get me 5 documents between _id order00057 --> order00077
postAllDocsOptions2 := cloudantv1.PostAllDocsOptions{
"selector": {
"deviceID": {
"$eq": "device-123456"
}
}
}'

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.FindResult;
import com.ibm.cloud.cloudant.v1.model.PostPartitionFindOptions;
import com.ibm.cloud.cloudant.v1.model.Selector;

import java.util.HashMap;
import java.util.Map;

Cloudant service = Cloudant.newInstance();

Map equalWithDeviceID = new HashMap<>();
equalWithDeviceID.put("$eq", "device-123456");

Selector selector = new Selector();
selector.put("deviceID", equalWithDeviceID);

PostPartitionFindOptions findOptions =
new PostPartitionFindOptions.Builder()
.db("readings")
.partitionKey("bridge-9876")
.selector(selector)
.build();

FindResult response =
service.postPartitionFind(findOptions).execute()
.getResult();

System.out.println(response);

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

const service = CloudantV1.newInstance({});

const selector: CloudantV1.Selector = {
deviceID: {'$eq': 'device-123456'}
}
service.postPartitionFind({
db: 'readings',
partitionKey: 'bridge-9876',
selector: selector
}).then(response => {
console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
Monitoring an IBM Cloudant cluster 

A key part of ensuring best performance, or troubleshooting any problems, is monitoring the affected system.

The monitoring API is only available to IBM® Cloudant® for IBM Cloud® Enterprise customers with dedicated clusters and not to IBM Cloud® Public customers.

You want to be able to answer the question:

In what way has the system behavior changed as a result of any configuration or application modifications?

To answer the question, you need data. The data comes from monitoring the system. Monitoring the system while it replicates can be performed by using the _active_tasks endpoint, which is described in more detail in the [Active tasks](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-active-tasksactive-tasks) documentation.

For more detailed system information, use the cluster monitoring API.



 Monitoring metrics overview 

When you monitor the cluster, you can obtain data about how it is performing. Details such as the number of HTTP requests processed per second, or how many documents are processed per second, can all be obtained through the monitoring API. The API can be invoked only by an administrative user, and is applied to a specific monitoring endpoint.

For example, if you wanted to monitor the number of documents processed by a map function each second, you would direct the request to the map_doc endpoint.

For more information, see a full list of the available [endpoints](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-monitoring-an-ibm-cloudant-clustermonitoring-endpoints).

The data is returned in JSON format by default. You can specify a raw format if you prefer.





 Syntax of the monitoring request 

All requests to the monitoring API have the following form:

curl -u $ADMIN_USER "https://$ADMIN_USER.cloudant.com/_api/v2/monitoring/$END_POINT?cluster=$CLUSTER[&format=(json|raw)]"

The fields are described in the following table:



Table 1. Monitoring API request fields

 Field Meaning 

 ADMIN_USER The account name. The account must have administrative privileges.
import { CloudantV1 } from '@ibm-cloud/cloudant';

const service = CloudantV1.newInstance({});

const viewQueries: CloudantV1.ViewQuery[] = [
{
include_docs: true,
limit: 5
},
{
descending: true,
skip: 1
}
];
service.postViewQueries({
db: 'users',
ddoc: 'allusers',
queries: viewQueries,
view: 'getVerifiedEmails'
}).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.

The previous example requires the getVerifiedEmails view to exist. To create the design document with this view, see [Create or modify a design document](https://cloud.ibm.com/apidocs/cloudantputdesigndocument).The previous Go example also requires an import for github.com/IBM/go-sdk-core/v5/core.

Multiple queries are supported by the _view endpoint, /$DATABASE/_design/$DDOC/_view/$VIEW/queries.

The request JSON object must have a queries field. It represents an array of query objects with fields for the parameters of each individual view query to be executed. The field names and their meaning are the same as the query parameters of a regular _view request.
Understanding the environment variables

 Variable Description 

 CLOUDANT_HOSTNAME <username>.cloudantnosqldb.appdomain.cloud 
 CLOUDANT_USERNAME Your IBM Cloudant username. 
 CLOUDANT_PASSWORD Your IBM Cloudant password. 
 CLOUDANT_DATABAS The name of your IBM Cloudant database: cats. 
 PACKAGE_NAME A custom name for the package 
 RULE_NAME A custom name for the rule. 
 TRIGGER_NAME A custom name for the trigger. 



Find this information in the console by navigating to your IBM Cloudant instance and then selecting Service Credentials. You can also find service credentials by running the ibmcloud resource command.



1. Find the credentials for your IBM Cloudant instance.

ibmcloud resource service-keys --instance-name <Cloudant-name>

Example output

Name State Created At
Cloudant-cred active Fri Nov 1 17:40:13 UTC 2019
2. Retrieve the details of the service key. Replace Cloudant-cred with the credentials that you retrieved in the previous step.

ibmcloud resource service-key Cloudant-cred

Example output

Name: Cloudant-cred
ID: crn:v1:bluemix:public:cloudantnosqldb:us-south:a/6ef045fd2b43266cfe8e6388dd2ec098:397b3dbc-abd3-46cf-a3de-c1d556c8959f:resource-key:a3db5b84-7fe9-4ddb-bf67-e556a278833f
Created At: Fri Nov 1 17:40:13 UTC 2019
State: active
Credentials:
apikey: uYowcbhwgOMzO61AJTHzCsPMmG0lB69pzr6helVlE6JF
host: 37c53a06-5193-23f3-b681-7c8b76ce7qaa-bluemix.cloudantnosqldb.appdomain.cloud
import com.ibm.cloud.cloudant.v1.model.PostSearchOptions;
import com.ibm.cloud.cloudant.v1.model.SearchResult;

import java.util.Arrays;

Cloudant service = Cloudant.newInstance();

PostSearchOptions searchOptions = new PostSearchOptions.Builder()
.db("movies")
.ddoc("searches")
.index("movies")
.query("movie_name:Azazel")
.highlightFields(Arrays.asList("["movie_name"]"))
.highlightPreTag("" "")
.highlightPostTag("" "")
.highlightSize(30)
.highlightNumber(2)
.build();

SearchResult response =
service.postSearch(searchOptions).execute()
.getResult();

System.out.println(response);

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

const service = CloudantV1.newInstance({});

service.postSearch({
db: 'movies',
ddoc: 'searches',
index: 'movies',
query: 'movie_name:Azazel',
highlightFields: ['"movie_name"]'],
highlightPreTag: '" "',
highlightPostTag: '" "',
highlightSize: 30,
highlightNumber: 2
}).then(response => {
console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.post_search(
db='movies',
ddoc='searches',
index='movies',
query='movie_name:Azazel',
highlight_fields=['"movie_name"]'],
See the following example that uses the command line to test the keyword analyzer:



* Curl
* Java
* Node
* Python
* Go



curl "https://$ACCOUNT.cloudant.com/_search_analyze" 	-H "Content-Type: application/json" 	-d '{"analyzer":"keyword", "text":"ablanks@renovations.com"}'

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostSearchAnalyzeOptions;
import com.ibm.cloud.cloudant.v1.model.SearchAnalyzeResult;

Cloudant service = Cloudant.newInstance();

PostSearchAnalyzeOptions searchAnalyzerOptions =
new PostSearchAnalyzeOptions.Builder()
.analyzer("keyword")
.text("ablanks@renovations.com")
.build();

SearchAnalyzeResult response =
service.postSearchAnalyze(searchAnalyzerOptions).execute()
.getResult();

System.out.println(response);

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

const service = CloudantV1.newInstance({});

service.postSearchAnalyze({
analyzer: 'keyword',
text: 'ablanks@renovations.com',
}).then(response => {
console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.post_search_analyze(
analyzer='keyword',
text='ablanks@renovations.com'
).get_result()

print(response)

postSearchAnalyzeOptions := service.NewPostSearchAnalyzeOptions(