The SA Engine documentation is structured into different sections for easy browsing.
- Overview: A high-level overview of SA Engine, information about how to get started and information on how the documentation website is structured.
- Guides: The system tutorial for learning more about SA Engine, and various guides describing how to achieve particular tasks.
- Manuals: The SA Engine and SA Studio manuals.
- Modules: Documentation for the SA Engine modules (data communication modules, AI/ML modules, etc).
- Reference: The SA Engine reference documentation. Here you find the OSQL reference, API documentation, etc.
The SA Engine documentation offers a level of interactivity that is rare among similar products. Much of the documentation contains interactive code blocks in which you can run the examples directly in your browser without having to download, install or sign up for any product or service!
There are two types of interactive code blocks in which you can run OSQL queries. Wasm code blocks and Studio code blocks.
Wasm code blocks
There is a lightweight version of SA Engine that can run on Wasm locally in your browser. To interact with the SA Engine Wasm instance we have Wasm code blocks. Every time you load a page with a Wasm code block, an SA Engine Wasm instance fires up and is ready to run the code.
Pages that contain Wasm code blocks are marked a Wasm code badge.
Here is an example of a Wasm code block:
from Integer i
where i in range(10,15)
A Wasm code block is a full text editor with syntax highlighting and tab completion. It has a play button play_circle in the top left corner which will execute the code when pressed. You can also execute the code with
Ctrl+Return while editing. To edit the code simply click in the editor and you will get a cursor.
Output generated from Wasm code blocks end up below the code block. You can specify on what format you want the output to be displayed with the
//plot: <vis-format> directive. For example, you can use
//plot: Text for text output or
//plot: Line plot for a line plot. A full list of available visualization formats can be found in the Visualization chapter of the SA Studio manual.
There are a few things to think about when following a guide or tutorial that contain Wasm code blocks:
- 📋 Execute code blocks in order: Code blocks in interactive guides are often designed to be executed in the order they appear. So if you skip a codeblock subsequent codeblocks might fail due to missing dependencies.
- 📝 Edit examples: You can edit the code in the code blocks if you you want to try changing the example.
- 📈 Change Visualization: You can change how the output of a query is visualized by specifying
//plot: <vis-format>at the top of the code block. Available visualization formats are described in the Visualization chapter of the SA Studio manual.
- 🔃 Page reload clears state: The SA Engine instance is cleared every time the page is reloaded. So if you are partway through a guide or tutorial and reload the page, you have to execute the code blocks from the beginning again before you continue with the rest of the guide. Otherwise remaining codeblocks might fail due to missing dependencies.
Wasm code blocks do not require you to download or install any program, or sign up for any service. All you need is a browser that can run Wasm.
Studio code blocks
There is a second type of interactive code block called Studio code block. A Studio code block connects directly a SA Studio instance in the cloud and allows you to run more complex queries than what is possible in Wasm code blocks.
Pages that contain Studio code blocks are marked a Studio code badge.
Some of the benefits with Studio code blocks compared to Wasm code blocks is that Studio code blocks allow you to:
- Run more complex queries
- Use plugins
- Interact with edge devices
Here is an example of a Studio code block:
from Integer i
where i in range(10,15)
To run this code block you must be logged in and your studio instance must be started.
A Studio code block works basically the same as a Wasm code block but with a few minor differences.
✍️ Requires SA Studio: Instead of using the SA Engine Wasm instance it connects to a full SA Engine instance run by SA Studio. SA Studio is a SaaS cloud solution and does not require any download or installation. But you will have to sign up for SA Studio to be able to run the Studio code blocks (the community edition is free but you need to register with a valid e-mail address).
The documentation automatically connects to your SA Studio instance, but you need to be logged in for it to work. There is a SA Studio connection indicator on the navigation bar that shows "Active" if you are logged in, or "Log in" if you need to log in (you can press the button to get to the log in page).
Each Studio code block also has a connection indicator. It will say "Connected to studio" when you are connected to your SA Studio instance, otherwise it will say "Not connected".
🤖 Can run code on edge devices: Studio code blocks have access to all edge devices that are connected to your SA Studio instance. So to interact with an edge device simply connect it to your SA Studio instance and then you can specify which edge device to run the code block on by putting
//peer: <edge-id>at the top of the code block. How you connect edge devices to SA Studio is described in the Connecting edge devices in the SA Studio manual.
🌍 Shares state between documentation pages: Since Studio code blocks connect to your SA Studio instance, the state will not be lost when you reload a page with Studio code blocks. You can browse the documentation and Studio code blocks on different pages will therefore all share the same state since they are only an interface to your SA Studio.
Studio code blocks do not require you to download or install any program, but do require that you sign up for SA Studio (free).