Use Links to Access Oracle NoSQL Database Cloud

Use links to access the Oracle NoSQL Database Cloud instance provided with Oracle IoT Cloud Service. You can use links from the analytics processors to retrieve data to perform the analytics, or to write data to Oracle NoSQL Database Cloud. You can also query links from the queries in your worksheets.

Before configuring a link to read or write to Oracle NoSQL Database Cloud, you must define an analytics object to store the data that you read or write. You can also use this object to create the table in Oracle NoSQL Database Cloud if you don’t have one already. Your analytics object must not contain complex types. For more information on how to create an analytics object, see Create Analytics Objects.

Go to your IoT application, select Analytics, and then select Links.
Create the link:
1. If this is your first link, click Create Link. Otherwise, the Add next to the Search field.
2. Enter a name to identify your link.
  The name must only contain alphanumeric characters and must not contain spaces.
3. (Optional) Enter a brief description.
  If you configure your link to expose it as a REST endpoint, this description will appear in the REST API documentation for this link.
4. Click Create.
From the Type list, select Oracle NoSQL.
The properties below the Type list change.
From the Analytics Object list, select an analytics object to store the result of the query.
The structure of the analytics object must match the structure of a row of an existing table, or define the structure of a new table if you haven’t created one yet.

This list only displays analytics objects of type object.
In the Table Name field enter the name of the table you want to query. If you haven’t created a table yet, use this field to define the name of your new table.

Note:
The name of your table must be 32 characters long, start with a letter, and only contain alphanumeric characters and underscores.
From the Primary Key list, select one or more fields from the analytics object to use as primary keys for your database table.
The list of primary keys corresponds to the fields in the analytics object that you selected before.
The primary key defines the primary key for the NoSQL table you’re creating. This key uniquely identifies each record in this table.

When you create new records from the analytics processor or using the application’s REST API, the primary key field is automatically generated.

You can use the primary key in the following situations:
- In the analytics processor code, use this primary key with the Spark API classes PairDataOutuput and JavaPairRDD.
- When obtaining (get), updating, or deleting records from the analytics processor or using the applications REST API, use the primary key to identify the record to use in the operation.
(Optional) From the Shard Key list, select one or more fields from the analytics object to use to partition the data.
For more information about sharding in Oracle NoSQL Database Cloud, see Introduction to Oracle NoSQL Database.
From the Time to Live list, select how long the messages are retained in the message store.
Available options are:
- Forever: The messages are never discarded from the message store.
- Hours: The messages are discarded after the specified number of hours has elapsed. To define the number of hours use the field Hours Count that appears after you select the Hours option.
- Days: The messages are discarded after the specified number of days has elapsed. To define the number of days use the field Days Count that appears after you select the Days option.
Click Test Connection to verify that Oracle IoT Cloud Service is able to access the specified table.
If you haven’t created the table yet, a message asking if you want to create a new table appears. If the table already exists, a message confirming the table was found appears.
If you’re creating a new table, click Yes to create a new table. If the table already exists, the confirmation message informs you if the schema you defined in the analytics object matches the one in the table and gives the options to drop the existing table, drop and re-create it with the schema defined in the selected analytics object, or continue using the existing table.
A status message indicating if the table was found or created appears next to the Test Connection button.
In the Resource URI feld, enter a valid URI (uniform resource identifier) to specify the REST path for the query and persistence service.
After you deploy the application, you can access the NoSQL table for this link using the REST API exposed by the deployed application.
(Optional) Select the methods associated to the resource URI you specified in the previous step.
You can choose to expose the following methods through the REST API of the application:
- GET: reads records from this link’s NoSQL table.
- PUT: updates records in this link’s NoSQL table.
- DELETE: deletes records from this link’s NoSQL table.
- POST: creates new records in this link’s NoSQL table.
If you don’t select any of these methods, you won’t be able to access the NoSQL table from an external application, you’ll only be able to access it from the analytics processors.
(Optional) Select Use from Worksheets to be able to query this link from the queries in your worksheets.
If you select this option, then you can use this link in the from clause of your query.
For example:
```
select * from MyLink
```
Click Save.

The NoSQL link is saved.

You can use this link in the following ways:

If you add this link to your analytics processor and generate the source template, the source template will include a line of code that injects this link into your analytics processor.
If you selected Use from Worksheets, you can use this link in the from clause of the queries in your worksheets.
If you specified a URI and associated method to that URI, after you deploy the IoT application, you can access the NoSQL table associated with this link using the REST API that the deployed application exposes.