Using the UltraTimeSeries Python SDK
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 objectTo 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')
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'.
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:
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)
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)
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)
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 dataactor = 'ETHEUR'#name of the time series, the action that we're monitoringaction = '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 measuremeasure = uts.CurrencyMoney()#unit of measure - actual value#This value is set as an example since we will be reading it from the messagesvalue = 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 messagesdate = '2021-08-25T22:55:57.8253388Z'
Feed on the records.csv (shown above) and populate the database with Messages:
#Insert messages in the databasewith open('records.csv','r') as records:content = csv.reader(records)next(content)#Instanciate a Messages objectmessages = node.Messages()#Create the messages you pretend to insertfor line in content:#addMessage takes as arguments, the actor, action, measure, value and date respectivelymessages.addMessage(line,'Value',uts.CurrencyMoney(),line,line)node.messageCreate(messages)
The records.csv file for this:
ℹ️ You can see how to use this SDK with some demos here.