super
super is the command-line tool for interacting with and managing SuperDB.
The command is organized as a hierarchy of sub-commands similar to
docker
or kubectl.
The dependency-free command is easy to install.
SuperDB does not have a REPL like SQLite.
Instead, your shell is your REPL and the super command lets you:
- run SuperSQL queries detached from a database,
- run SuperSQL queries attached to a database,
- compile and inspect query plans,
- run a SuperDB service endpoint,
- or access built-in dev tooling when you want to dive deep.
The super command is invoked either by itself to run a query:
super [ -c <query> | -I <query-file> ] [ options ] [ <path> ... ]
or with a sub-command:
super [ options ] <sub-command> ...
Running a Query
When invoked at the top level without a sub-command (and either
a query or input paths are specified), super executes the
SuperDB query engine detached from the database storage layer.
The input data may be specified as command-line paths or referenced within the query.
For built-in command help and a listing of all available options,
simply run super without any arguments.
Options
When running a query detached from the database, the options include:
An optional SuperSQL
query may be present via a -c or -I option.
If no query is provided, the input paths are scanned
and output is produced in accordance with -f to specify a serialization format
and -o to specify an optional output (file or directory).
Errors
Fatal errors like “file not found” or “file system full” are reported
as soon as they happen and cause the super process to exit.
On the other hand, runtime errors resulting from the query itself do not halt execution. Instead, these error conditions produce first-class errors in the data output stream interleaved with any valid results. Such errors are easily queried with the is_error function.
This approach provides a robust technique for debugging complex queries, where errors can be wrapped in one another providing stack-trace-like debugging output alongside the output data. This approach has emerged as a more powerful alternative to the traditional technique of looking through logs for errors or trying to debug a halted query with a vague error message.
For example, this query
echo '1 2 0 5' | super -s -c '10/this' -
produces
10
5
error("divide by zero")
2
and
echo '1 2 0 5' | super -c '10/this' - | super -s -c 'is_error(this)' -
produces just
error("divide by zero")
Debugging
If you are ever stumped about how the super compiler is parsing your query,
you can always run super -C to compile and display your query in canonical form
without running it.
This can be especially handy when you are learning the language and its
shortcuts.
For example, this query
super -C -c 'has(foo)'
is an implied where operator, which matches values
that have a field foo, i.e.,
where has(foo)
while this query
super -C -c 'a:=x+1'
is an implied put operator, which creates a new field a
with the value x+1, i.e.,
put a:=x+1