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.
Cozo is distributed as a single executable. To get started, download the executable for your platform and uncompress it. After decompression, you may also need to give it executable permission by ``chmod +x ./cozo`` on Unix-based systems.
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.
The pre-compiled distributions of Cozo support 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.
---------------
Running Cozo
@ -37,7 +37,7 @@ 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 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.
@ -54,9 +54,9 @@ As Cozo has a web-based API, it is accessible by all languages that are capable
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.
`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::
First, install JupyterLab by following the install instructions of the project. Then install the pycozo library by running::
pip install "pycozo[pandas]"
@ -64,25 +64,25 @@ Now, open the JupyterLab web interface, start a Python 3 kernel, and in a cell r
%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::
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::
%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::
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::
%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.
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.
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_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.
* ``%cozo_clear`` clears all set parameters.
* ``%cozo_params`` returns the parameters currently set.
@ -90,14 +90,14 @@ There are a few other useful magic commands:
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.
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 broswer for best display.
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 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::
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::
await run("<COZOSCRIPT>")
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 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.
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.
Ziyang Hu
2 years ago