Using the %onesaitplatform interpreter

This tutorial includes a use example of the group of %onesaitplatform interpreters from the Notebooks.

To learn more about the functionalities of the interpreters you can consult the references: (Notebooks) (ES) %onesaitplatform Interpreter Reference.

Before starting

Before starting, bear in mind the following points:

• This tutorial is based on the Restaurants database, which is available by default on the platform.

• An ontology called RestaurantTutorialDB will be created to insert.

• A Digital Client called RestaurantTutorialClient will be created for communication with the Restaurant and RestaurantTutorialDB ontologies.

• A REST API called RestaurantTutorialAPI will be created on the RestaurantTutorial ontology.

If the components already exist, they must be deleted in the following order: RestaurantTutorialClient, RestaurantTutorialAPI and RestaurantTutorialDB.

• We strongly recommend to not do the tutorial done with an administrator user.

• The user must have the ANALYTICS role to have the Notebooks module.

Creating the necessary elements

Creating the RestaurantTutorialDB ontology

The first step is creating the RestaurantTutorialDB ontology with the same scheme as the Restaurants ontology. You can copy and paste the following scheme to define the ontology scheme:

Open

That way, you already have a new ontology with the same scheme as Restaurants.

Open

Creating the RestaurantTutorialClient Digital Client

Next, you will create a Digital Client with access to the Restaurants and RestaurantTutorialDB ontologies, to query and insert data. The token will be your DIGITAL_CLIENT_TOKEN in the Notebook.

Open

Now you already have a Client offor communication with the platform's Digital-Broker.

Creating the RestaurantTutorialAPI API REST

Lastly, create a REST API to query the ontology data by REST. Establish two types of operations: all and {id}

Open

Open

A query REST API is now available on the data that is inserted.

Set neccessary variables

With the recently-created elements, enter the Notebook called OnesaitPlatformZeppelinInterpretes or create a copy of it.

In the first cells, the necessary variables obtained from the creation of the elements and the user are established.

Insert them in the Zeppelin context (they will be accessible from all cells, regardless of the interpreter).

Open

Using the ﹪onesaitplatform interpreter

Below is an example of data exchange with the platform (queries and inserts).

Show help

Help is displayed if the word help or an unrecognizable expression is entered.

Open

Debug mode

The debug mode allows you to see the code execution trace.

Open

Enter credentials

The debug trace can be observed when debug mode is active for initConnection() execution.

Open

Perform a query

SQL query example:

Open

NATIVE query example:

Open

Query the data as a table

To perform a data query that Zeppelin can interpret:

Open

Perform a data insert

To perform a data insert, you must first save the serialized objects in context, from where they will be retrieved in the insert function:

Open

Open

Perform a paged query (batch)

In cases where large queries are made to download raw data, we recommended you to use the paged queries, which download data in batches. The the data batch configuration can be changed in the interpreter manager:

Open

An example of a query and save process in a variable:

Open

Generate a file from a query

To simplify the handling of queries, you can use the function, queryfile(“<ontology>”, “<query>”, “<queryType>”, “<responseType>”), this function is responsible for dumping the result of the query into a file.

Open

Check the status of the QueryFile process

To check whether the previously requested file has finished or is still in progress, use the queryFileStatus function, where you must provide the queryId returned by the queryFile function.

The function works as follows: it makes an initial request to obtain the status, which can be "in_progress" or "finished". If the status is "finished", it will be displayed on the screen. If the status is "in_progress", the function will make multiple requests during the time defined by the "timeout", pausing between requests according to the "timesleep" value. Once the "finished" status is received, it will be printed on the screen. If the "finished" status is not received by the end of the "timeout", it will return "in_progress".

This function can be used in different ways, depending on whether you want to customize the timeout or timesleep values. If you prefer to use the default values (timeout = 60, timesleep = 5), simply call:

queryFileStatus("<queryId>")

If you want to modify both parameters: → queryFileStatus("<queryId>", timeout, timesleep)

To modify only the timeout value: → queryFileStatusTimeout("<queryId>", timeout) )

To modify only the timesleep value: → queryFileStatusTimesleep("<queryId>", timesleep)

The function will return:

• IN_PROGRESS: The query is still being executed.

• FINISHED: The query has finished and the result has been fully written to the file.

Open

Using the ﹪onesaitplatform.apimanager interpreter

Below is an example of calls to the platform's API-Manager.

Show help

La ayuda se muestra si se introduce la palabra help o una expresión no reconocible.

Open

Debug mode

The debug mode allows you to see the code execution trace.

Open

Enter credentials

The token to be used for requests is set. In this %onesaitplatform.apimanager version, you can pass z.get() expressions for all arguments of their functions.

Open

List all APIs of that user

The APIs of our user are listed to obtain the basic information of the API. You can also list the APIs of other users (public and shared with the user that corresponds to the used token). It is possible to list all the APIs that the user has access to (using the provided token) by calling the following function → listAPIS()

Open

In the context, Java list objects are saved, so you have to access the list to get the results using indexes.

Open

Getting more information about an API

If you want to obtain more extensive information from an API, the following expression is used:

Open

Making a request to the API

An API call created to list the elements that we have inserted in the previous steps is made.

Open

Create a new API

To create a new API, use the function → createAPI("<json_object>"). This function takes a JSON object as a parameter and returns the following information:

• id: The unique identifier of the newly created API.

• identification: An additional identifier or name associated with the created API.

• version: The version of the API. If previous versions exist, the new version will be automatically incremented.

• msg: A confirmation message indicating successful creation, typically "OK".

Open

Open

Delete an API

You can also delete an existing API using the following function → deleteAPI("<api_name>", "<api_version>").You must provide the name of the API (api_name) and the version (api_version) you wish to delete.

If the operation is successful, the function will return a confirmation message indicating that the API has been deleted correctly.

Open