Text Analytics with REST APIs for Autonomous Databases

Text analytics is a very interesting topic and not that obvious.

Oracle recently announced the Oracle Machine Learning Services in their public cloud. With this comes a set of REST APIs to access the capabilities available.

To summarize, there are 3 families of APIs:

• Machine Learning models “market place”: list, discover, and store models (even those created using open source frameworks: Tensorflow, Keras… thanks to the ONNX format)
• Machine Learning models deployment: deploy the models inside Oracle databases for real-time scoring… very useful for MLOps!
• Cognitive Text: the subject of this post!

These APIs can be accessed from PL/SQL using the APEX_WEB_SERVICE package (from Autonomous Databases for example).

OAuth2 Authentication

The very first step is to authenticate in order to get a token for all the next REST API calls (this token will last one hour and then will need to be refreshed).

For this very first step, you’ll need to gather the following information:

• database username: easy
• database password: my_super_password2021
• autonomous database cloud service instance URL: this is adb.<region>.oraclecloud.com (see a list of the available regions here)
• OCI tenant OCID: see the documentation
• database name: this is the name of your database (example with loic in the screenshot, the case is not important)

With these information, you can now build your REST API call as following:

The body will be a JSON document:

{"grant_type":"password","username":"easy","password":"my_super_password2021"}

The URL will be:

https://adb.eu-frankfurt-1.oraclecloud.com/omlusers/tenants/ocid1.tenancy.oc1..../databases/loic/api/oauth2/v1/token

Two headers:

Content-Type: application/json
Accept: application/json

Now you can perform the call and retrieve your OAuth 2.0 token:

curl -i -k -X POST --header 'Content-Type: application/json' --header 'Accept: application/json'\ 
-d '{"grant_type":"password", "username":"easy", "password":"my_super_password2021"}'\
 "<autonomous-database-cloud-service-instance-url>/omlusers/tenants/${tenant_name}/databases/${database_name}/api/oauth2/v1/token"

Response example:

{
  "accessToken": "eyJhb...==",  
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

The accessToken field contains the token to keep. You’ll use it for your next REST API calls for Bearer authentication this time.

Cognitive Text APIS

And now the fun, you have now access to the following REST APIs:

• Get Endpoints: list all the following Cognitive Text REST API endpoints
• Get Most Relevant Keywords: retrieves the top N (default: 5) most relevant keyword from the text passed in parameter
• Get Most Relevant Topics: extract the most relevant topics
• Get Numeric Features: returns numeric features (one per word in the text)
• Get Semantic Similarities: return semantic similarity score given a probe text (test if the text is related to a word, a topic, a category, etc…)
• Get Sentiments: performs sentiment analysis over some text
• Get Summaries: returns summaries for the provided list of text strings

Note that several languages are supported such as AMERICAN, FRENCH, and SPANISH.

Example of Sentiment Analysis