Authenticating to Cloudant
There are two authentication methods available for connecting to Cloudant: IBM Cloudant Legacy and IBM Cloud IAM.
Authenticating with IBM Cloudant Legacy
Set the User and Password to your service credentials.
To create an IBM Cloudant service credential:
- In the IBM Cloud dashboard, go to the Menu icon > Resource List, and open your IBM Cloudant service instance.
- In the menu, click Service credentials.
- Click the New credential button and enter a name for the new credential in the Add new credential window.
- Click the Add button. Your credentials are added to the Service credentials table.
- Click View credentials under Actions and extract the User and Password from the json file.
Authenticating with IBM Cloud IAM
If you to use the IBM Cloud IAM authentication flow, see IBM Cloud IAM Authentication for an authentication guide.
IBM Cloud IAM Authentication
To connect with IBM Cloud, you will need the ApiKey and the Url of Cloudant instance ( i.e https://0c9d3837-8304-4aab-a65a-648169970943-bluemix.cloudant.com). After setting InitiateOAuth to GETANDREFRESH (default), you are ready to connect.
When you connect, the provider completes the OAuth process.
- Extracts the access token and authenticates requests.
- Saves OAuth values in OAuthSettingsLocation to be persisted across connections.
After you have created an account in IBM Cloud you should follow the procedure below to retrieve the connection properties:
To obtain the ApiKey, take the following steps:
- Log in to your IBM Cloud account.
- Navigate to Platform API Keys page.
- On the middle right corner click "Create an IBM Cloud API Key" in order to create a new API Key.
- In the pop-up window, specify the API Key name and click "Create". Save the ApiKey somewhere as you can never access it again from the dashboard.
Register a new instance of Cloudant
If you do not already have Cloud Object Storage in your IBM Cloud account, you can follow the procedure below to install an instance of SQL Query in your account:
- Log in to your IBM Cloud account.
- Navigate to the Cloudant page, choose a name for your instance and click Create. You will be redirected to the instance of Cloudant.
Accessing NoSQL Tables
The provider implements Automatic Schema Discovery that is highly configurable. The following sections outline the provider's default connection property values. See NoSQL Database for other mechanisms to access schemaless Cloudant data with SQL.
Flattening Nested JSON
By default, the provider projects columns over the properties of objects. Arrays are returned as JSON strings, by default. You can use the following properties to access array elements, including objects nested in arrays.
- FlattenArrays: Set this property to the number of array elements that you want to return as column values. You can also use this property with FlattenObjects to extract the properties of objects nested in arrays.
FlattenObjects: By default, this is true; that is, the properties of objects and nested objects are returned as columns. When you set FlattenArrays, objects nested in the specified array elements are also flattened and returned as columns.
Fine-Tuning Data Access
You can use the following properties to gain control over column behavior in Automatic Schema Discovery.
- RowScanDepth: This property determines the number of rows that will be scanned to detect column data types when generating table metadata.
- TypeDetectionScheme: This property allows more control over the strategy implemented by the RowScanDepth property.
Connecting Through a Firewall or Proxy
To connect through a proxy-based firewall, set FirewallType, FirewallServer, and FirewallPort. To tunnel the connection, set FirewallType to TUNNEL. To authenticate specify FirewallUser and FirewallPassword. To authenticate to a SOCKS proxy, set FirewallType to SOCKS5.
Troubleshooting the Connection
To show provider activity from query execution to HTTP calls, use Logfile and Verbosity. The examples of common connection errors below show how to use these properties to get more context. Contact the support team for help tracing the source of an error or circumventing a performance issue.
- Authentication errors: Typically, recording a Logfile at Verbosity 4 is necessary to get full details on an authentication error.
- Queries time out: A server that takes too long to respond will exceed the provider's client-side timeout. Often, setting the Timeout property to a higher value will avoid a connection error. Another option is to disable the timeout by setting the property to 0. Setting Verbosity to 2 will show where the time is being spent.