Using the UltraTimeSeries Python SDK

Introduction

This is a simple guide on how to get started using UltraTimeSeries (UTS) Python REST API.

The motives behind this wrapper around UltraTimeSeries REST API were to reduce even more the complexity of the system and make it as accessible as possible. Python was chosen due to being a language with a low learning curve and all-around easy to read.

We assembled this simple introductory script in order to teach you how to get data flowing as soon as possible. The operations used assume familiarity with the UltraTimeSeries data model and concepts.

To start interacting with UltraTimeSeries we need to have access to an instance either locally or remotely with some data loaded there.

UltraTimeSeries Python REST API Setup

You’ll need this API to interact with UltraTimeSeries through Jupyter Notebook. This API can be downloaded here through pip with the command: pip install ultratimeseries-api

Instantiate a Node object

To get it started, we’ll need to indicate in Python where this UltraTimeSeries is running: we’ll need to instantiate a UltraTimeSeries object that indicates where the instance is running, both with the URL and the host.
#node = uts.UTS(URL,Host)
node = uts.UTS('http://localhost:8080','localhost')

OR

node = uts.UTS()

The second one is valid for the given parameters since the values are defaulted to: URL = 'http://localhost:8080' AND Host = 'localhost'.

Authentication

UltraTimeSeries uses JSON Web Token authentication. JSON Web Token is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed.

If your UltraTimeSeries instance supports authentication every action regarding UltraTimeSeries will require authentication.

If it doesn’t support authentication this step can be skipped. Authentication can be done this way:

#node.login(apikey)
node.login('apikey')

Actor Insertion

An actor is an entity capable of producing/generating data. We’ll create an actor giving it a unique key.

actors = node.Actors()
actors.addActor('ETHEUR')
node.actorCreate(actors)

Role Insertion

Roles are how we store actors’ metadata (data that is not time-related).

We’ll create a role with a unique key and the properties we want.

roleKey = 'Coin'
role = node.Role(roleKey)
properties = [['Slug','text']]
role.addProperties(properties)
node.roleCreate(role)

Role/Actor Association

Any actor can be associated with one or more roles. This links the actor to its metadata.

actorRole = node.ActorRole('Coin','ETHEUR')
properties = [['Slug','ETH']]
actorRole.addProperties(properties)
node.roleAddActor(actorRole)

Message Insertion

Messages like actors are one of the atomic units in UltraTimeSeries. A message should be seen as a single event whereas a list of events is a time series.

Message can be added individually or as a collection. Adding multiple messages in one go is more efficient than iterating and adding a single at a time.

For this example, a Message follows this structure:

#unique identifier of the actor who produced this data
actor = 'ETHEUR'
#name of the time series, the action that we're monitoring
action = 'Value'
#a dimension is a measure of a physical variable (without numerical values).
#a unit is a way to assign a number or measurement to that dimension.
#by identifying the dimension and the unit, the system can now do automatic conversion (e.g meters to yards).
#when combined they become a measure
measure = uts.CurrencyMoney()
#unit of measure - actual value
#This value is set as an example since we will be reading it from the messages
value = 3000
#date when the event occured, must be in Coordinated Universal Time (UTC)
#This value is set as an example since we will be reading it from the messages
date = '2021-08-25T22:55:57.8253388Z'

Feed on the records.csv (shown above) and populate the database with Messages:

#Insert messages in the database
with open('records.csv','r') as records:
content = csv.reader(records)
next(content)
#Instanciate a Messages object
messages = node.Messages()
#Create the messages you pretend to insert
for line in content:
#addMessage takes as arguments, the actor, action, measure, value and date respectively
messages.addMessage(line[0],'Value',uts.CurrencyMoney(),line[1],line[2])
node.messageCreate(messages)

The records.csv file for this:

records.csv

SDK Demos

You can see how to use this SDK with some demos here.