{ "cells": [ { "cell_type": "markdown", "id": "3df9ce6e-3722-4334-abf9-703d62c27eab", "metadata": {}, "source": [ "# The Cozo database tutorial" ] }, { "cell_type": "markdown", "id": "63c695dc-6e85-42bb-b39b-1f0fd14ed5eb", "metadata": {}, "source": [ "This tutorial will teach you the basics of using the Cozo database with the query language CozoScript.\n", "There are no database-specific prerequisites, \n", "though it would be helpful if you already know some other databases, \n", "especially SQL databases." ] }, { "cell_type": "markdown", "id": "c2bfcfe4-c06c-4b02-a040-6fd840b77820", "metadata": {}, "source": [ "## Setup" ] }, { "cell_type": "markdown", "id": "eb1fefcf-81b5-4ccf-8179-631fdb011bae", "metadata": {}, "source": [ "The best way to learn from this tutorial is to run the queries as they are introduced.\n", "For this, you need to install the Cozo database on your local machine." ] }, { "cell_type": "markdown", "id": "7f26f0f5-a3ff-4145-a9d5-84c65e368afa", "metadata": {}, "source": [ "Cozo is distributed as a single gzipped/zipped binary. \n", "Go to https://github.com/cozodb/cozo/releases and download the latest release binary for your operating system to a local directory.\n", "\n", "If your operating system is Linux/Mac, \n", "open a terminal command prompt, \n", "`cd` into the directory of your download,\n", "and run" ] }, { "cell_type": "raw", "id": "72a21b8e-d66a-48d3-b684-e9554ea382cc", "metadata": {}, "source": [ "gunzip cozoserver-*.gz\n", "mv cozoserver-* cozoserver\n", "chmod +x cozoserver" ] }, { "cell_type": "markdown", "id": "536fb265-e25f-469d-843e-935b272c7298", "metadata": {}, "source": [ "If you are on Windows instead, open a PowerShell and run" ] }, { "cell_type": "raw", "id": "a11f0388-dd7b-49a2-825f-0dde834ceb6b", "metadata": {}, "source": [ "Expand-Archive -Path .\\cozoserver-*.zip -DestinationPath ." ] }, { "cell_type": "markdown", "id": "12da9726-3c18-4011-98ea-e2aae105ee08", "metadata": {}, "source": [ "To run the server, you need to specify a directory to store persistent data on your file system. \n", "In the following we will use a directory called `tutorial-data` in the same directory as the binary executable.\n", "In the terminal, run" ] }, { "cell_type": "raw", "id": "b4f837e4-6f26-4c57-a7a9-fb5765e4bc92", "metadata": {}, "source": [ "./cozoserver ./tutorial-data" ] }, { "cell_type": "markdown", "id": "41820cf5-a800-4c81-8a17-227e9692aae2", "metadata": {}, "source": [ "The same command should work in powershell as well.\n", "\n", "If you see something like `Database web API running at ...` displayed in your terminal, \n", "then the server is successfully started. \n", "Keep the server running when you are following the tutorial.\n", "When you are done, `CTRL-C` in the terminal will stop the server.\n", "You can restart the server again by running the command again.\n", "\n", "More options when starting the server is available. Run" ] }, { "cell_type": "raw", "id": "e7bd8545-8d42-43a4-ae3b-e946fc5ff19b", "metadata": {}, "source": [ "./cozoserver -h" ] }, { "cell_type": "markdown", "id": "f192cf0b-a30d-46ad-85a1-d81f7590b78b", "metadata": {}, "source": [ "for more details." ] }, { "cell_type": "markdown", "id": "2ec06d2e-1187-48c8-8777-f84b4c71c741", "metadata": {}, "source": [ "## A place to run queries\n", "\n", "Cozo exposes an HTTP API, so theoretically you can follow along using tools like `curl`. \n", "If you are interested, consult the manual for the request format the API expects.\n", "For better user experience, though, we suggest following one of the following two subsections instead." ] }, { "cell_type": "markdown", "id": "c4e8b790-7c0f-4538-b20e-2c3fb4065dc8", "metadata": {}, "source": [ "### Option 1: the JupyterLab notebook\n", "\n", "This option provides the best user experience but also requires you to install quite a lot of things, \n", "though you may already have them installed on your computer if you use the python data science stack.\n", "First you will need python installed. \n", "Then install JupyterLab by following the instruction at https://jupyter.org/install.\n", "Next, run the following to install a Jupyter extension to help querying Cozo:" ] }, { "cell_type": "raw", "id": "6ffa6d95-101b-4229-900a-ce9b14685439", "metadata": {}, "source": [ "pip install pycozo pandas" ] }, { "cell_type": "markdown", "id": "9c07f306-9abc-4dd2-b78c-5b46a823982e", "metadata": {}, "source": [ "While you are at it, go to the source of this tutorial at https://github.com/cozodb/cozo/blob/main/tutorial/tutorial.ipynb, \n", "right-click on `Raw` and save the tutorial document to your disk.\n", "\n", "Then run jupyter lab, open a the saved tutorial document, and follow along." ] }, { "cell_type": "markdown", "id": "5154e084-d997-4f22-97fb-ce5808fb1da3", "metadata": {}, "source": [ "We need to enable the extension in the notebook. Run" ] }, { "cell_type": "code", "execution_count": 1, "id": "2e0d11d7-64d7-4577-a28d-7541ee8875fa", "metadata": {}, "outputs": [], "source": [ "%load_ext pycozo.ipyext_direct" ] }, { "cell_type": "markdown", "id": "c3f0d80d-9854-4a21-9121-3220e7bcc73b", "metadata": {}, "source": [ "Then the \"hello world\" query:" ] }, { "cell_type": "code", "execution_count": 6, "id": "f3dfb8a1-35f0-4dc2-b8d7-e81fa3d45b75", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
Completed in 0ms
" ], "text/plain": [ "\n", " | 0 | \n", "1 | \n", "2 | \n", "
---|---|---|---|
0 | \n", "hello | \n", "world | \n", "Cozo! | \n", "
Completed in 0ms
" ], "text/plain": [ "\n", " | 0 | \n", "1 | \n", "2 | \n", "
---|---|---|---|
0 | \n", "hello | \n", "world | \n", "Cozo! | \n", "
Completed in 0ms
" ], "text/plain": [ "\n", " | 0 | \n", "1 | \n", "2 | \n", "
---|---|---|---|
0 | \n", "1 | \n", "2 | \n", "3 | \n", "
1 | \n", "a | \n", "b | \n", "c | \n", "
Completed in 0ms
" ], "text/plain": [ "\n", " | 0 | \n", "1 | \n", "2 | \n", "3 | \n", "4 | \n", "
---|---|---|---|---|---|
0 | \n", "True | \n", "False | \n", "None | \n", "-0.014000 | \n", "A string with double quotes | \n", "
1 | \n", "1.500000 | \n", "2.500000 | \n", "3 | \n", "4 | \n", "5.500000 | \n", "
2 | \n", "aA | \n", "bB | \n", "cC | \n", "dD | \n", "eE | \n", "
Completed in 0ms
" ], "text/plain": [ "\n", " | 0 | \n", "
---|---|
0 | \n", "1 | \n", "
1 | \n", "2 | \n", "