Objectives

This tutorial provides a series of Python language instructions, suitable for the following tasks:

1. Connecting to an IBM Cloudant service instance on IBM Cloud®.
2. Creating a database within the service instance.
3. Storing a small collection of data as documents within the database.
4. Retrieving data.
5. Deleting the database.

Before you begin

Connecting to a service instance

1. Run these import statements to load the necessary SDK classes.

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

2. Find host and apikey in your service credentials and replace the values in service_host and service_api_key in the following example.

   service_host = '{host}'
   service_api_key = '{apikey}'
   

   Don't store your credentials in source code files. For real applications consider configuring your client from the environment.

3. Create a client configured with the service instance details.

   client = CloudantV1(IAMAuthenticator(service_api_key))
   client.set_service_url(f'https://{service_host}')
   

   Here https:// is prefixed to the host to make the service URL. Alternatively use the url from the service credentials, but if your instance is not IAM only be sure to remove the user information after the protocol and before the hostname.

4. Get the server information with the get_server_information API to validate the connection.

   client.get_server_information().get_result()
   

   Validate the output is similar to the following example:

   {'couchdb': 'Welcome', 'version': '3.3.3+cloudant', 'vendor': {'name': 'IBM Cloudant', 'version': '8521', 'variant': 'paas'}, 'features': ['search', 'access-ready', 'iam', 'partitioned', 'pluggable-storage-engines', 'scheduler'], 'features_flags': ['partitioned']}
   

Now, your Python application can access the service instance on IBM Cloud.

Creating a database within the service instance

Next, you create a database within the service instance, called databasedemo.

1. Define the database name with a variable in the Python application.

   database_name = 'databasedemo'
   

2. Create the database using the put_database API.

   client.put_database(db=database_name).get_result()
   

   Validate the database was created successfully with output:

   {'ok': True}
   

Storing a small collection of data as documents within the database

You want to store a small, simple collection of data in the database. Use these data in other tutorials, like Using IBM Cloudant Query to find data.

1. Create sample data.

   sample_data = [
       [1, 'one', 'boiling', 100],
       [2, 'two', 'hot', 40],
       [3, 'three', 'hot', 75],
       [4, 'four', 'hot', 97],
       [5, 'five', 'warm', 20],
       [6, 'six', 'cold', 10],
       [7, 'seven', 'freezing', 0],
       [8, 'eight', 'freezing', -5]
   ]
   

2. Initialize a list of documents.

   sample_docs = []
   

3. Iterate the sample data to make document data

   For each row of the sample_data list create a dictionary mapping field names to the values from the row elements. Append each dictionary to the sample_docs list.

   for row in sample_data:
       # Make a dictionary for each row
       document = {
           'numberField': row[0],
           'nameField': row[1],
           'descriptionField': row[2],
           'temperatureField': row[3]
       }
       # Append the dictionary to the list of documents
       sample_docs.append(document)
   

   Python dictionaries are suitable for making JSON documents.

4. Create documents using the post_document API.

   for doc in sample_docs:
       client.post_document(db=database_name, document=doc).get_result()
   

   This use of the post_document API automatically generates document IDs on the server. Alternatively include an ID in the document body or use the put_document API to choose a specific document ID.

   For creating or modifying large numbers of documents in a single request there is a post_bulk_docs API.

   Validate that the output is similar to the following example.

   {'ok': True, 'id': '43bb97b841c5b16c5ee44f4768e42efa', 'rev': '1-f998fc7b89d4466c1e7bb204b1b00f74'}
   {'ok': True, 'id': '480d1073dca0bf7bc9f28c2ad2f1383e', 'rev': '1-08b940a61ee2f4a013ba8f4abb307c70'}
   {'ok': True, 'id': '06266c9793afac3b5740872bc0f83d52', 'rev': '1-7de3d45186982b76243ce5879ccdbef4'}
   {'ok': True, 'id': '40867bf98071981da37d266d23b681ca', 'rev': '1-60206efd94ac6434740acd53c4278646'}
   {'ok': True, 'id': '622a70b1e0e9a0311284cd8bf5c439db', 'rev': '1-6d98db97adc12d2e4b114f96d2383a2d'}
   {'ok': True, 'id': '8c07fdbbf67d5173adc3b3034cd9202c', 'rev': '1-d97d8d0b6928bc743ccbe12b0621ad58'}
   {'ok': True, 'id': '4afb0c4e8d0c96d729dbf7081cbbe84c', 'rev': '1-462c5395df71106d903bedd29970ddeb'}
   {'ok': True, 'id': '33376a6ea0644abeef5462ff394755ef', 'rev': '1-523c33f6c5f82a2ae51a8df6366ee92b'}
   

Retrieving data

1. Retrieve a list of documents in the database using the post_all_docs API.

   all_docs_result = client.post_all_docs(db=database_name).get_result()
   

2. Iterate the returned rows to view document metadata.

   for row in all_docs_result['rows']:
       print(row['id'])
   

   Validate that the output is similar to the following example.

   43bb97b841c5b16c5ee44f4768e42efa
   480d1073dca0bf7bc9f28c2ad2f1383e
   06266c9793afac3b5740872bc0f83d52
   40867bf98071981da37d266d23b681ca
   622a70b1e0e9a0311284cd8bf5c439db
   8c07fdbbf67d5173adc3b3034cd9202c
   4afb0c4e8d0c96d729dbf7081cbbe84c
   33376a6ea0644abeef5462ff394755ef
   

   These IDs will match those from the previous creation step.

In a relational database, the first document stored in a database is always the first document returned in a list of results. This notion doesn't necessarily apply to document-oriented databases, such as IBM Cloudant.

Deleting the database

1. Delete the database using the delete_database API.

   try:
       client.delete_database(db=database_name).get_result()
   except ApiException as ae:
       print(f'There was a problem deleting database {database_name}. HTTP status code {ae.status_code}. Error message {ae.message}.')
   

   Validate the database was deleted successfully with output:

   {'ok': True}
   

2. Review the basic error handling demonstrating one way to handle problems.

Finishing up

1. End the interactive Python interpreter session by issuing an EOF for example with Ctrl+D.

2. Optionally deactivate and delete the Python virtual environment.

   a. Deactivate the virtual environment

   deactivate
   

   b. Delete the virtual environment.

   rm -r cloudantdemo