Skill Level: Intermediate

Recipe expects usage skills on IBM Watson IoT Platform and Cloudant NoSQL DB Service on IBM Bluemix

In this recipe, we describe about how the device data gets stored on Cloudant NoSQL DB and showcase how to configure and store device data on to Cloudant NoSQL DB as Historian Data Storage


  1. Introduction

    Connecting a IBM® Cloudant® NoSQL DB for Bluemix® service to IBM® Watson™ IoT Platform allows us to store and access device data. Device data is stored in daily, weekly, or monthly databases depending on selected bucket interval.

    When we begin using a Cloudant NoSQL DB to store device data three databases are automatically created, one database is created for the current bucket interval, one for the upcoming interval, and one configuration database. Design documents can be added to the configuration database and will be copied to new databases as they are created. When the end of an interval is reached device data is stored in the bucket database for the new interval, and a new database is created for the following interval.

    When device data is sent to a database it can be stored in one of two ways. If the data is valid JSON and the format of the device event is set to JSON, the device data will be stored in the following format:


    If the device data is not valid JSON or if the format is not set to JSON the device data will be stored as a base64 encoded string under the payload field in the following format:



    Next section, we’ll see how we can configure and store device data on to Cloudant NoSQL DB as Historian Data Storage.

  2. Before we begin

    Before connecting a Cloudant NoSQL DB to IBM Watson™ IoT Platform service, please complete the following tasks:

    The IoT Recipe discussed here, makes use of the Create Toolchain button to help deploy the necessary services on to Bluemix. Click on the Create Toolchain button provided below, provide a Custom Name to your application and choose to click on Create button, to quickly deploy the Watson IoT Platform, Node.js runtime ( and Node-RED application on top of it) and Cloudant NoSQL DB, as part of the Bluemix starter app. Post successful deployment, you shall have all three of the above mentioned services, up & running in your Bluemix environment.


    Note: If you are a User using the United Kingdom Region in your Bluemix environment, then please make use of the steps mentioned in the IoT Recipe Deploy Internet of Things Platform Starter service on Bluemix to deploy the setup. Alternatively, you can also try using the Deploy to Bluemix button, to deploy the setup under your United Kingdom Region, provided your Jazzhub account is validated. Users of US South Region can ignore this step.


    • Visualizing Data in Watson IoT Platform

      The above mentioned Create Toolchain button shall take care of the first 2 steps in the mentioned IoT Recipe and that you now need to continue to refer it starting Step #3 onwards. Open the Bluemix Dashboard and click on the Application service that you have currently deployed. You should see the Watson IoT Platform listed under the Connections. Click on the WIoTP service and choose the click on Launch button to launch the WIoTP Dashboard.

    • Set up a Cloudant NoSQL DB in the same Bluemix space as Watson IoT Platform by using the Bluemix Catalog

    Ensure that we have developer privileges in the Bluemix organization and we are signed in via Bluemix. If we are not signed in through Bluemix, or do not have developer privileges in this Bluemix organization, we will not be able to authorize the binding of the Cloudant NoSQL DB and the Watson IoT Platform.

  3. Connecting a Cloudant NoSQL DB with IBM Watson IoT Platform

    Here are the steps to connect Cloudant NoSQL DB with Watson IoT Platform and configure Historian Service to use Cloudant NoSQL DB:

    1. On Watson™ IoT Platform dashboard, click Extensions in the navigation bar.
    2. In the Historical Data Storage tile, click Setup.
    3. All available Cloudant NoSQL DB services within the same Bluemix space as our Watson™ IoT Platform service are listed in the Configure historical data storage section.
    4. Select the Cloudant NoSQL DB service that we wish to connect.
    5. Select Cloudant NoSQL DB configuration options:
      1. Select a bucket interval.
      2. Select a time zone.
      3. Choose options that determine the database name.
    6. Clicking on Done, we should see a popup window asking for authorize the connection to Cloudant Service. Note: If Popup windows are blocked by browser, then you may not see the below shown popup window asking for “Confirm Authrorization”. In that case, enable allow pop-ups in the browser and try again.
    7. Clicking on CONFIRM in authorization dialog box, we should see Authorization Success message in the popup window.
    8. With successful completion of configuring the Cloudant NoSQL DB to be used as Historian Service for Watson IoT, we should see Historical Data Storage status as configured:
    9. Our device data is now being stored in Cloudant® NoSQL DB

    In this section, we have described the steps required to configure Cloudant NoSQL DB as Historian Service for IBM Watson IoT Platform. Coming sections, we’ll see how to view device data stored in Cloudant NoSQL DB and query the device data.


  4. Conclusion & Next Steps

    This recipe is good starting point for the audience who wants to explore on connecting Cloudant NoSQL DB as Historian Data Storage for IBM Watson IoT Platform. In this recipe, we have described about:

    • Details about the format of the data stored in Cloudant NoSQL DB.
    • Configuring Cloudant NoSQL DB to be used as Historian Data Storage for IBM Watson IoT Platform.

    To know about:

    • Sample queries to retrieve device data from configured Cloudant NoSQL DB using cURL statements.
    • Sample queries and data processing operations on the device data retrieved from Cloudant NoSQL DB using Python Code.
    • Device Data processing from multiple Cloudant NoSQL databases in Python.

    Refer to the recipe: Query and Process Watson IoT Device Data from Cloudant NoSQL DB.

    To know, how to link between Line Chart Cards and Historian Data Storage to display device data on Watson IoT Platform Dashboard, refer to Visualize Watson IoT Device Data stored in Cloudant NoSQL DB.

2 comments on"Configure Cloudant NoSQL DB as Historian Data Storage for IBM Watson IoT"

  1. mblechner June 21, 2017

    The “Create toolchain” button successfully created an app and services (IoTP and Cloudant). However, these services were not bound to the app. I am not sure if they were supposed to be… I think so because the app did not start correctly, its status was “interrupted”. I was able to manually bind the services to the app, but it would still not start correctly. Since this app is not actually used in this recipe, there is no big deal, but I thought it was important to point out.

  2. Josef Sevcik August 18, 2020

    Hello guys, I have the same issue as mblechner. In IBM Watson IoT there no functionality to configure Cloudant. Is there anyone who is able to help to show me how to enable historian data storage?
    Thank you.

Join The Discussion