Cozo is distributed as a single executable. To get started, download the executable for your platform and uncompress it. You may also need to give it executable permission by ``chmod +x ./cozo`` on Unix-based systems after decompression.
The pre-compiled distributions of Cozo supports Linux, Mac and Windows. As building on Windows is very different from building on UNIX-based systems, the Windows build hasn't received as much attention as the other builds and may suffer from inferior performance and Windows-specific bugs. For Windows users, we recommend running Cozo under `WSL <https://learn.microsoft.com/en-us/windows/wsl/install>`_ if possible, especially if your workload is heavy.
If ``PATH_TO_DATA_DIRECTORY`` does not exist, it will be created. Cozo will then start a web server and bind to address ``127.0.0.1`` and port ``9070``. These two can be customized: run the executable with the ``-h`` option to learn how.
To stop Cozo, type ``CTRL-C`` in the terminal, or send ``SIGTERM`` to the process with e.g. ``kill``.
-----------------------
The query API
-----------------------
Queries are run by sending HTTP POST requests to the server. By default, the API endpoint is ``http://127.0.0.1:9070/text-query``. The structure of the expected JSON payload is::
{
"script": "<COZOSCRIPT QUERY STRING>",
"params": {}
}
``params`` should be an object of named parameters. For example, if you have ``params`` set up to be ``{"num": 1}``, then ``$num`` can be used anywhere in your query string where an expression is expected. Always use ``params`` instead of constructing query strings yourself when you have parametrized queries.
---------------
Security
---------------
Cozo is currently designed to run in a trusted environment and be used by trusted clients, therefore it does not come with elaborate authentication and security features. If you must access Cozo remotely, you are responsible for setting up firewalls, encryptions and proxies yourself.
As a guard against users carelessly binding Cozo to any address other than ``127.0.0.1`` and potentially exposing content to everyone on the Internet, in this case Cozo will refuse to start unless you also set up the environment variable ``COZO_AUTH``. With the variable set, Cozo will then require all queries to provide the content of the set variable in the HTTP header field ``x-cozo-auth`` for verification. Please note that this "security measure" is not considered sufficient for any purpose and is only a last defense when every other security measure that you are responsible for setting up fails.
As Cozo has a web-based API, it is accessible by all languages that are capable of making web requests. The structure of the API is also deliberately kept minimal so that no dedicated clients are necessary. The return values of requests are JSON when requests are successful, or text descriptions when errors occur, so a language only needs to be able to process JSON to use Cozo.
^^^^^^^^^^^^^^^^^^^^^^^^^
JupyterLab
^^^^^^^^^^^^^^^^^^^^^^^^^
`JupyterLab <https://jupyterlab.readthedocs.io/en/stable/>`_ is a web-based notebook interface in the python ecosystem heavily used by data scientists, and is the recommended "IDE" of Cozo.
First install JupyterLab by following the install instructions of the project. Then install the pycozo library by running::
pip install "pycozo[pandas]"
Now, open the JupyterLab web interface, start a Python 3 kernel, and in a cell run the following `magic command <https://ipython.readthedocs.io/en/stable/interactive/magics.html>`_::
%load_ext pycozo.ipyext_direct
If you need to connect to Cozo using non-default address or port, or you require an authentication string, you need to run the following magic commands as well::
%cozo_host http://<BIND_ADDRESS>:<PORT>
%cozo_auth <YOUR_AUTH_STRING>
Now you can execute cells as you usually do in JupyterLab, and the content of the cells will be sent to Cozo and interpreted as CozoScript. Returned relations will be formatted as `Pandas dataframe <https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html>`_.
The above sets up the notebook in the Direct Cozo mode, where cells are interpreted by default to be CozoScript. You can still execute python code by starting the first line of a cell by the ``%%py``. There is also an Indirect Cozo mode, started by::
%load_ext pycozo.ipyext
In this mode, only cells with first line content ``%%cozo`` are interpreted as CozoScript. Other cells are interpreted in the normal way (by default, python code). Which mode you use depends on your workflow. If you have lots of post-processing and visualizations to do, we recommend the Indirect mode.
There are a few other useful magic commands:
*``%cozo_run_file <PATH_TO_FILE>`` runs a local file as CozoScript.
*``%cozo_run_string <VARIABLE>`` runs variable containing string as CozoScript.
*``%cozo_set <KEY> <VALUE>`` sets a parameter with name ``<KEY>`` to the expression ``<VALUE>``. The set parameters will be used by a subsequent queries.
*``%cozo_set_params <PARAM_MAP>`` replace all parameters by the given expression, which must evaluate to a dict with string keys.
*``%cozo_clear`` clears all set parameters.
*``%cozo_params`` returns the parameters currently set.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Makeshift JavaScript Console
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Python and JupyterLab ecosystem is rather heavy-weight. If you are just testing out, or running Cozo in an environment that only occassionally requires manual queries, you may be reluctant to install them. In this case you may find the Makeshift JavaScript Console helpful.
As Cozo is running an HTTP service, we assume that the browser on your local machine can reach its network. We recommend `Firefox <https://www.mozilla.org/en-US/firefox/new/>`_, `Chrome <https://www.google.com/chrome/>`_, or any Chromium-based broswer for best display.
If Cozo is running under the default configuration, navigate to ``http://127.0.0.1:9070``. You should be greated with a mostly empty page telling you that Cozo is running. Now open the Developer Console (for `Firefox <https://firefox-source-docs.mozilla.org/devtools-user/browser_console/index.html>`_ or `Chrome <https://developer.chrome.com/docs/devtools/console/javascript/>`_) and switch to the "Console" tab. Now you can execute CozoScript by running::
The returned tables will be properly formatted. If you need to pass in parameters, provide a second parameter with a JavaScript object. If you need to set an auth string, modify the global variable ``COZO_AUTH``.
The JavaScript Console is not as nice to use as Jupyter notebooks, but we think that it actually provides a much better experience than hand-rolled CLI consoles, since you can use JavaScript to manipulate the results.
