vania-janet/multiturn-rag-retrieval-data huggingface dataset:
Updating a document 

To update a document, send a PUT or POST request with the updated JSON content and the latest _rev value to https://$ACCOUNT.cloudant.com/$DATABASE/$DOCUMENT_ID. You can also use this PUT method to create a document, in which case you don't need to supply the most recent _rev value.

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

If you fail to provide the most recent _rev when you attempt to update an existing document, IBM Cloudant responds with a [409 error](https://cloud.ibm.com/apidocs/cloudantlist-of-http-codes). This error prevents you from overwriting data that were changed by other processes. If the write [quorum](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-documents&code=curlquorum-writing-and-reading-data) can't be met, a [202 response](https://cloud.ibm.com/apidocs/cloudantlist-of-http-codes) is returned.

Any document update can lead to a conflict, especially when you replicate updated documents. For more information about avoiding and resolving conflicts, see the [Document versioning and MVCC guide](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-document-versioning-and-mvccdocument-versioning-and-mvcc).

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

See an example of updating a document by using HTTP:

POST /$DATABASE HTTP/1.1

See examples of updating a document:



* Curl
* Java
* Python
* Go
* Node
(https://cloud.ibm.com/docs-content/v1/content/b6066ebcc4ff31f2a8b558531f2ee791d108a7e1/cloud-pak-multicloud-management/images/buckets_v2.png)

Figure 3. Example Standard type bucket created
2. Upload the Infrastructure management installation image (file name: cp4mcm-im-rhos-2.1.x86_64.qcow2) to your IBM Cloud Object Storage. Select your bucket and click Add Objects to upload the images. For more information, see [Uploading data by using the console](https://cloud.ibm.com/docs/services/cloud-object-storage?topic=cloud-object-storage-uploadupload-console).

Note: You can use the Aspera high-speed transfer plug-in to upload images larger than 200 MB.

Zoom

![Figure showing example that uses Aspera uploaded file to bucket.](https://cloud.ibm.com/docs-content/v1/content/b6066ebcc4ff31f2a8b558531f2ee791d108a7e1/cloud-pak-multicloud-management/images/upload_images_to_bucket_v2.png)

Figure 4. Example using Aspera uploaded file to bucket
3. From IBM Cloud Identity and Access Management (IAM), create an authorization between the Virtual Private Cloud (VPC) Infrastructure (source service) > Image Service for VPC (resource type) and Cloud Object Storage (target service). For more information, see [Create an authorization](https://cloud.ibm.com/docs/iam?topic=iam-serviceauthserviceauth).

Important: The configuration must be set up as this example or permissions can fail.

Zoom

![Figure showing example IAM authorization.]
How is data stored in IBM Cloudant? 

Every database in IBM® Cloudant® for IBM Cloud® is formed of one or more distinct shards, where the number of shards is referred to as Q. A shard is a distinct subset of documents from the database.



 Concepts 

All Q shards together contain the data within a database. Each shard is stored in three separate copies. Each shard copy is called a shard replica. Each shard replica is stored on a different server. The servers are available within a single Region. If the Region supports Availability Zones, the replicas are stored on servers in different Zones. The collection of servers in a Region is called a cluster.

Zoom

![A single database is split into Q shards, which are each stored in triplicate on three separate servers.](https://cloud.ibm.com/docs-content/v1/content/522c6f62358b063f921283400a601c3f9bc66f08/Cloudant/images/sharding_database.svg)

Figure 1. Data storage

A document is assigned to a particular shard by using consistent hashing of its ID. This assignment means that a document is always stored on a known shard and a known set of servers.

Zoom

![A single document is assigned to a single shard so ends up on three replicas on three separate servers.](https://cloud.ibm.com/docs-content/v1/content/522c6f62358b063f921283400a601c3f9bc66f08/Cloudant/images/sharding_document.svg)

Figure 2. Document consistent hashing

Occasionally, shards are rebalanced. Rebalancing involves moving replicas to different servers. Rebalancing occurs for several reasons, for example, when server monitoring suggests that a server is more heavily or lightly used than other servers, or when a server must be taken out of service temporarily for maintenance.
* ibmcloud is image-export-jobs 72251a2e-d6c5-42b4-97b0-b5f8e8d1f479
* ibmcloud is image-export-jobs my-image







 Command options 



* IMAGE: ID or name of the image.
* --output: Specify output format, only JSON is supported. One of: JSON.
* -q, --quiet: Suppress verbose output.



--------------------







 ibmcloud is image-export-job-create 

Create an image export job.

ibmcloud is image-export-job-create IMAGE --bucket BUCKET [--name NEW_NAME] [--format qcow2 | vhd] [--output JSON] [-q, --quiet]



 Command examples 



* ibmcloud is image-export-job-create 72251a2e-d6c5-42b4-97b0-b5f8e8d1f479 --name my-export-job --format qcow2 --bucket my-bucket
* ibmcloud is image-export-job-create my-image --name my-export-job --format qcow2 --bucket my-bucket







 Command options 



* IMAGE: ID or name of the image.
* --name: New name of the image export job.
* --format: The format to use for the exported image. If the image is encrypted, only qcow2 is supported. One of: qcow2, vhd. (default: qcow2).
* --bucket: The Cloud Object Storage bucket to export the image to. The bucket must exist and an IAM service authorization must grant Image Service for VPC of VPC Infrastructure Services writer access to the bucket.
* --output: Specify output format, only JSON is supported. One of: JSON.
* -q, --quiet: Suppress verbose output.



--------------------
{:step: data-tutorial-type="step"} {:hide-dashboard: .hide-dashboard} {:apikey: data-credential-placeholder="apikey"}



 Developing a web application 

This tutorial shows you how to build a simple image gallery using IBM Cloud® Object Storage, bringing together many different concepts and practices key to web development.

From beginning to end, building a web application covers a lot of different concepts and is a great way to introduce yourself to the features of IBM Cloud Object Storage. Your application uses IBM Cloud Object Storage for storage in a Node.js application that allows a user to upload and view JPEG image files.



 The Scenario 

The scenario for this tutorial involves many moving parts:



* A web server to host the web application
* Use of the command line
* A storage instance for the images in the gallery
* A version control system integrated into continuous delivery
* Client-side application bindings in both scripts and markup
* Images to upload and display



And if you are looking for all that in one package, this tutorial will provide a complete, start-to-finish, example for you. However, this instruction can only temporarily set aside principles of security and secure code. Web applications actually put into production require proper security, or they won't be suitable for possible visitors.





 Before you begin 

Ensure that you have what you need to start:



* An account for the IBM Cloud Platform
* Docker, as part of the IBM Cloud Developer Tools
* Node.js
* Git (both desktop and command line)





 Using the Command Line 

Let's start by opening a tool familiar to experienced developers, and a new best friend to those just getting started: the command line. For many, the graphic user interface (GUI) relegated your computer's command-line interface to second-class status. But now, it's time to bring it back (although the GUI isn't going away anytime soon, especially when we need to browse the web to download instructions for the command-line toolset).

Open a shell and create a directory. Change your own reference directory to the new one you created.
To open an IBM Cloudant service's Dashboard, log in to IBM Cloud, find your IBM Cloudant service, and click Launch IBM Cloudant Dashboard button. A new window opens, logging you into your IBM Cloudant Dashboard.

If you leave the dashboard window unattended for a length of time, you find yourself logged out (for security purposes) and must click Launch again.

The dashboard has a number of tabs. Its default tab, Databases, lists the databases that you created in groups of 20. Each database is shown with the number of documents that it is storing and how much disk space is being used. Click a database name to examine its contents.

To create a database, click Create Database and supply the name of the database to create.

We now have a new empty database. The database's documents would be listed here in ID order. However, since this database is new, no documents exist. To add a document, click Create Document.

The IBM Cloudant Dashboard created a template document for you with a pre-generated _id. Complete the rest of the attributes yourself to complete the JSON document, and click Create Document to save.

Now it's time for another practical exercise. Create a database called books, and in that database, create three or more documents with fields: title, author, date, publisher, and ISBN - each representing a book of your choice.

Once created, edit one of the documents, modifying the publication date.

Then, delete one of the documents.

To summarize, the IBM Cloudant Dashboard is a web app that is built into the IBM Cloudant service and is part of the CouchDB open source offering. It is used to manage databases, documents, indexes, queries, and replication jobs. It can also be used to monitor service throughput. The Dashboard is simply an API client - anything that can be achieved with the dashboard can be scripted by you using the HTTP API.

That's the end of this part. The next part is called HTTP API Basics.







 HTTP API Basics video 

Learn how to use the command line to make HTTP requests and to add, edit, and delete documents.



* HTTP API Basics video script
Replace /_/myCloudant with your package name, replace <database_name> with the name of your database, <document_id> with your document ID, and <test_name> with a custom name.

Command syntax

ibmcloud fn action invoke /_/myCloudant/write --blocking --result --param <database_name> test --param doc "{"_id":"<document_id>","name":"<test_name>"}"

Example write action to a test database

ibmcloud fn action invoke /_/myCloudant/write --blocking --result --param dbname test --param doc "{"_id":"color","name":"blue"}"

Example output

ok: invoked /_/myCloudant/write with id 62bf696b38464fd1bcaff216a68b8287

{
"id": "color",
"ok": true,
"rev": "1-9a94fb93abc88d8863781a248f63c8c3"
}
2. Verify that the document exists in the IBM Cloudant dashboard. The dashboard URL for the test database is in the following format: https://<mycloudantaccount>.cloudant.com/dashboard.htmldatabase/test/_all_docs?limit=100.

Example document in IBM Cloudant dashboard

{
"_id": "color",
"_rev": "1-f413f4b74a724e391fa5dd2e9c8e9d3f",
"name": "blue"
}







 Updating a document 

You can use the /update-document action to update a document in your IBM Cloudant database.

Before you begin
Content-Encoding: gzip

See the following example of sending a gzip-encoded request body to create a document by using the command line:

curl "https://example.cloudant.com/db/doc" 	-X PUT 	-T doc.gzip 	-H "Content-Encoding: gzip"

By default, the SDKs compress the request body.





 If-None-Match 

The If-None-Match header is optional. You might send it to determine whether a document was modified since it was last read or updated. The value of the If-None-Match header must match the last [Etag](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-how-http-works-with-cloudantetag) value received. If the value matches the current revision of the document, the server sends a [304 Not Modified](https://cloud.ibm.com/apidocs/cloudantlist-of-http-codes) status code, and the response itself has no body.

If the document was modified, you get a normal [200 response](https://cloud.ibm.com/apidocs/cloudantlist-of-http-codes), provided the document still exists and no other errors occurred.







 Response headers 

Response headers are returned by the server when you send back 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 as shown in the following list.



* Cache-Control
* Content-Length
* Content-Type
* Etag





 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-Length 

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





 Content-Type for response headers
import com.ibm.cloud.cloudant.v1.model.Document;
import com.ibm.cloud.cloudant.v1.model.DocumentResult;
import com.ibm.cloud.cloudant.v1.model.PostDocumentOptions;

Cloudant service = Cloudant.newInstance();

Document productsDocument = new Document();
productsDocument.setId("small-appliances:1000042");
productsDocument.setRev("1-967a00dff5e02add41819138abb3284d");
productsDocument.put("type", "product");
productsDocument.put("productid", "1000042");
productsDocument.put("brand", "Salter");
productsDocument.put("name", "Digital Kitchen Scales");
productsDocument.put("description", "Slim Colourful Design Electronic"
+ "Cooking Appliance for Home/Kitchen, Weigh up to 5kg + Aquatronic"
+ "for Liquids ml + fl. oz. 15Yr Guarantee - Green");
productsDocument.put("price", 14.99);
productsDocument.put("image", "assets/img/0gmsnghhew.jpg");

PostDocumentOptions documentOptions =
new PostDocumentOptions.Builder()
.db("products")
.document(productsDocument)
.build();

DocumentResult response =
service.postDocument(documentOptions).execute()
.getResult();

System.out.println(response);

from ibmcloudant.cloudant_v1 import Document, CloudantV1

service = CloudantV1.new_instance()

products_doc = Document(
id="small-appliances:1000042",
Cloudant 

With the preinstalled /whisk.system/cloudant package from IBM Cloud® Functions, you can work with an [IBM Cloudant](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-getting-started-with-cloudant) database.



 Available entities for Cloudant 

The following table shows a selection of the entities available in the whisk.system/cloudant package. You can use the whisk.system/cloudant package to read, write, update, or delete documents. You can also use the changes feed to listen for changes to an IBM Cloudant database.

For a full list of the entities that are available in the /whisk.system/cloudant package, run ibmcloud fn package get /whisk.system/cloudant.



Table 1. Entities that are available in the cloudant package

 Entity Type Parameters Description 

 /whisk.system/cloudant Package dbname, host, username, password Work with a Cloudant database. 
 /whisk.system/cloudant/read Action dbname, id Read a document from a database. 
 /whisk.system/cloudant/write Action dbname, overwrite, doc Write a document to a database. 
 /whisk.system/cloudant/update-document Action dbname, doc Update a document in a database. 
 /whisk.system/cloudant/changes Feed dbname, iamApiKey, iamUrl, filter, query_params, maxTriggers Fire trigger events on changes to a database. 



The includeDoc parameter is no longer supported for use with /whisk.system/cloudant/changes feed. If you created triggers that use this parameter, you must re-create them without the includeDoc parameter.





 Binding the /whisk.system/cloudant package to your IBM Cloudant database. 

If you're using IBM Cloud® Functions from the IBM Cloud, you can use the IBM Cloud® Functions CLI plug-in to bind a service to an action or package. If you do not bind your service, you must pass your credentials each time you use the action or package.

Before you begin
For any image that is less than 10 GB, the size is rounded up to 10 GB.







 Operating system considerations 



* Make sure that your image is supported as an [x86 stock image](https://cloud.ibm.com/docs/vpc?topic=vpc-about-images) or an [s390x stock image](https://cloud.ibm.com/docs/vpc?topic=vpc-vsabout-images) on IBM Cloud® Virtual Private Cloud.
* If you choose to create a custom image with your own license, specify the appropriate operating system version that appends -byol to the name when you import the image. For more information, see [Bring your own license](https://cloud.ibm.com/docs/vpc?topic=vpc-byol-vpc-about).
* ISO images of licensed operating systems, such as Windows® and Linux®, and open source operating systems, such as CentOS and Ubuntu, aren't provided by IBM Cloud®. If you need these ISO images, you can download them from the respective vendor website.







 IBM Cloud Object Storage considerations 

If you plan to import an image from a file, you must provision an instance of IBM Cloud Object Storage if you don't already have one. You can then upload the file to a bucket there. You must also create an IAM authorization between the Image Service for VPC and IBM Cloud Object Storage. For more information, see [Granting access to IBM Cloud Object Storage to import images](https://cloud.ibm.com/docs/vpc?topic=vpc-object-storage-prereq&interface=cli).







 Custom image lifecycle 

You can use the UI, CLI, API, and Terraform to manage the lifecycle of your custom images with three statuses. You can move the image back and forth through all the statuses and set dates to automatically change an image status. All status changes are tracked as an Activity Tracker event. You can filter your list of images based on status to aid in clean-up or tracking of your images.
You can work with the IBM Cloudant API endpoints directly, from within a Python application.

In this example code, you again request a list of all the documents, including their content. However, this time you do so by invoking the IBM Cloudant [/_all_docs](https://cloud.ibm.com/apidocs/cloudantpostalldocs) endpoint.



1. Identify the endpoint to contact and any parameters to supply with it.

end_point = '{0}/{1}'.format(serviceURL, databaseName + "/_all_docs")
params = {'include_docs': 'true'}
2. Send the request to the service instance and show the results.

response = client.r_session.get(end_point, params=params)
print("{0}n".format(response.json()))
3. See the result that is similar to the following abbreviated example.

{
"rows": [{
"value": {
"rev": "1-b2c48b89f48f1dc172d4db3f17ff6b9a"
},
"id": "14746fe384c7e2f06f7295403df89187",
"key": "14746fe384c7e2f06f7295403df89187",
"doc": {
"temperatureField": 10,
"descriptionField": "cold",
"numberField": 6,
"nameField": "six",
"_id": "14746fe384c7e2f06f7295403df89187",
"_rev": "1-b2c48b89f48f1dc172d4db3f17ff6b9a"
}
},
...{
"value": {
From the Dashboard in [IBM Cloud console](https://cloud.ibm.com/), create an image template by clicking menu![Menu icon](https://cloud.ibm.com/docs-content/v1/content/icons/icon_hamburger.svg) > Classic Infrastructure > Devices > Device List.
2. Click the backup virtual server that you previously customized for IBM Cloud VPC.
3. From the Actions menu, select Create Image Template.







 Step 5 - Export the image template to IBM Cloud Object Storage 

To export the new image template that you created from the modified virtual server instance to IBM Cloud Object Storage, complete the following steps.



1. Locate the new image template that you created on the Image Templates page by selecting Devices > Manage > Images.
2. From the Image Templates page, click ... for the image template that you want to export and select Export to IBM COS. For more information, see [Exporting an image to IBM Cloud Object Storage](https://cloud.ibm.com/docs/image-templates?topic=image-templates-exporting-an-image-to-ibm-cloud-object-storage).







 Step 6 - Import the custom image to the IBM Cloud VPC infrastructure 



1. In IBM Cloud console, go to menu icon ![Menu icon](https://cloud.ibm.com/docs-content/v1/content/f02b9c9adcbb7328d95a45e105cec371d50f15eb/icons/icon_hamburger.svg) > VPC Infrastructure > Compute > Images.
2. On the Custom images tab, click Import Custom Image. For more information, see [Importing a custom image](https://cloud.ibm.com/docs/vpc?topic=vpc-managing-imagesimport-custom-image).







 Step 7 - Use the custom image to create a virtual server instance in IBM Cloud VPC 



1.
For more information, see [Migrating from a Lite plan to a Standard plan](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-migrating-from-a-lite-plan-to-a-standard-plan).
* Can I back up my data before I migrate?

The IBM Cloudant team advises that you use the [couchbackup](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-ibm-cloudant-backup-and-recoveryibm-cloudant-backup-and-recovery) utility to export data to disk. Or use [IBM Cloud Object Storage](https://www.ibm.com/cloud/object-storage), which is an inexpensive, scalable solution for storing the exported files.
* Can I keep my username.cloudant.com domain and redirect it to the new service on IBM Cloudant?

No, it's not possible to keep your domain. You must plan to update your applications to use the new account URL and credentials that are generated for the IBM Cloudant instances.
* Who do I contact if I have questions?

Go to the [IBM Cloud Support portal](https://www.ibm.com/cloud/support), or open a ticket from within the IBM Cloudant Dashboard if you have any questions about migration. IBM Cloudant support is happy to provide more details.
* Modeling data to scale FAQ

 Modeling data to scale FAQ 

The way you model data on IBM® Cloudant® for IBM Cloud® significantly impacts how your application can scale. The underlying data model differs substantially from a relational model, and ignoring this distinction can be the cause of performance issues down the road.

As always, successful modeling involves achieving a balance between ease of use versus the performance characteristics you're hoping to achieve.

(The FAQ for modeling data to scale is based on a blog article by Mike Rhodes, My top five tips for modeling your data to scale.)



If you're changing the same piece of state at a rate of once per second or more, consider making your documents immutable. This practice significantly reduces the chance that you create conflicted documents.