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 defence 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 <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.
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>`_::
If you need to connect to Cozo using a non-default address or port, or you require an authentication string, you need to run the following magic commands as well::
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 default interpreted as CozoScript. You can still execute python code by starting the first line of a cell with the ``%%py``. There is also an Indirect Cozo mode, started by::
In this mode, only cells with the 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. We recommend the Indirect mode if you have lots of post-processing and visualizations.
When a query is successfully executed, the result will be bound to the python variable ``_`` as a Pandas dataframe (this is a feature of Jupyter notebooks: the Cozo extension didn't do anything extra).
*``%cozo_set <KEY> <VALUE>`` sets a parameter with the name ``<KEY>`` to the expression ``<VALUE>``. The set parameters will be used by subsequent queries.
*``%cozo_set_params <PARAM_MAP>`` replace all parameters by the given expression, which must evaluate to a dictionary with string keys.
The Python and JupyterLab ecosystem is rather heavy-weight. If you are just testing out or running Cozo in an environment that only occasionally 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 browser for best display.
If Cozo is running under the default configuration, navigate to ``http://127.0.0.1:9070``. You should be greeted with a mostly empty page telling you that Cozo is running. Now open the Developer Console (`Firefox console <https://firefox-source-docs.mozilla.org/devtools-user/browser_console/index.html>`_ or `Chrome console <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 provides a much better experience than hand-rolled CLI consoles, since you can use JavaScript to manipulate the results.
