Using models
Models are collections of your OSQL functions. Typically they are designed to do the analytics that take you from some sensor input to a desired result stream. Models can contain trained ML models, but can just a well be built with more traditional analytics methods.
A minimal model in SA Engine is a folder with a master.osql file in it, where the name of the folder corresponds to the model name.
The master file can contain the functions that constitute the model, or it can load other files in the model folder.
A model can also have dependencies on another model, which it then loads in the master file.
Creating models​
Models must be placed inside a folder named models in your SA_HOME folder.
To verify which folder is set as SA_HOME, run sa_home().
sa_home();
To run this code block you must be logged in and your studio instance must be started.
To set SA_HOME, set the environment variable SA_HOME to the full path of the desired folder.
In VS Code, it is also possible to create a custom SA_HOME for each project. See Startup settings.
Models can be created with the models:create(Charstring model_name) function.
models:create("my_model");
To run this code block you must be logged in and your studio instance must be started.
The command will create a folder named my_model with a file master.osql in it.
Models can also be created by manually adding the model folder and the master file.
Add a model by creating a folder in the models folder in SA_HOME
For more instructions on how to add models in our graphical interfaces, refer to the manuals of VS Code or SA Studio.
You can use the function models:list() to list all models in your models folder.
This corresponds to the names of the subfolders of models.
models:list();
To run this code block you must be logged in and your studio instance must be started.
Running models​
To run a model, it has to be loaded into an SA Engine instance.
To load a model into the SA Engine instance you are currently running, use the function models:load(charstring model).
models:load("my_model");
To run this code block you must be logged in and your studio instance must be started.
To load a model is to run the master.osql file in the model, defining the functions that are defined there, and calling the functions that are called there.
The models:load() function will also change the current working directory to the model folder while loading the model.
To see which models have been loaded into SA Engine:
models:loaded();
To run this code block you must be logged in and your studio instance must be started.
A summary of functions for creating, listing and loading models:
A summary of functions for creating, listing and loading models
Writing models​
It is common to start working on a model by writing queries and running them directly from the master file. As functionality, such as sensor reading and parsing, gets finished and put in a function, it is convenient to move it to another file.
To load another file, use load_osql(charstring path).
Since the code inside a model is executed with the model folder as current working directory, it is enough to use the relative path from there.
The path to the model folder can also be accessed with models:folder(charstring model_name).
models:folder("my_model");
To run this code block you must be logged in and your studio instance must be started.
For example, if the model "my_model" wants to load an OSQL file extra.osql, we can load it from master.osql either by relative path:
load_osql("extra.osql");
or by it's full path:
load_osql(models:folder("my_model") + "extra.osql");
As functions get finalized, it is good practice to add tests that verify that they behave as expected for defined input.
OSQL support unit testing with the validate check syntax, which is described in OSQL Testing.
validate statements can be exexuted manually, but if they are placed in a file with a name that ends with test.osql inside the folder of a model,
they can also be executed with models:test(charstring model_name).
Deploying models to an edge​
To use a model on an edge, it should be deployed in a federation.
Consider the federation below. A nameserver is running on a server or in the cloud. An analyst developing models on a laptop is using a local client that is connected to the nameserver. There is also an edge instance connected to the federation, which is where the model will ultimately be used.
A small federation with a nameserver in the cloud, a client on a local computer and an edge.
You can deploy a model in development directly to one or more edge devices with models:deploy.
For example, the following query deploys the model "my-model" to the edge "my-edge".
models:deploy("my-edge", "my-model")
The model is deployed from the local model folder ($SA_HOME/models). Both the local machine and the edge device must be connected to the same federation.
You can also deploy a model directly to multiple edge devices at the same time by providing a vector of edge names. For example, the following query deploys the model "my-model" to the edges "my-edge-1" and "my-edge-2":
models:deploy(["my-edge-1", "my-edge-2"], "my-model")
All SA Engine instances have an SA_HOME folder associated to them. This is always a path to a folder on the same machine as where the SA Engine instance is running. Often similar paths are used on eg. the client and the edges, but the physical location is different.
After a model has been deployed to an edge, it is also available in that edges models folder. This means it can be loaded locally on the edge:
//peer: my-edge
models:load("my-model");
This can be useful for example if the SA Engine instance on the edge is restarted.
A summary of function for deploying and loading models on the edge:
A summary of function for deploying and loading models on the edge