fluidb/tutorial/0-getting-started.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "8dbeeb48-9ffe-45da-ad01-944c19f3f48c",
   "metadata": {},
   "source": [
    "# Getting started"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8b64f1cf-ed8e-43b4-9d68-ec33f228ad33",
   "metadata": {},
   "source": [
    "First we need to get the server running. Download the binary for your platform and decompress it. You should get an executable."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "87c5b9f4-2c03-4e68-bcbc-dbbcff572a2f",
   "metadata": {},
   "source": [
    "Run the executable from your command line. For example, under Bash:\n",
    "```bash \n",
    "./cozoserver tutorial_db\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5ef47d29-901f-4d59-9a5d-daef8ca5cc8f",
   "metadata": {},
   "source": [
    "You can pass `-h` to see what options are available.\n",
    "\n",
    "The server should prompt you to set up authentication. Note down your authentication as you will use it later. Then the database is available for query and mutation with an HTTP API."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d718d0e6-8e64-4b9a-8fff-e0823275b3e8",
   "metadata": {},
   "source": [
    "## Deciding how you want to interact with the database"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b1be03b1-e407-4bd1-9d2a-d48ad90df6b9",
   "metadata": {},
   "source": [
    "Querying the HTTP API directly is not very convenient for interactive use. But an interactive environment does come with baggages. Therefore we have devised two solutions for you to choose from: you can follow any one of the two subsections to continue with the tutorial series."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ba3c1ff8-afd8-46cc-bb2f-5fc1887b597a",
   "metadata": {},
   "source": [
    "In the following we shall attempt to execute the following query against the database, the meaning of which will be explained in later tutorials:"
   ]
  },
  {
   "cell_type": "raw",
   "id": "58ac2c49-6c9f-4ae3-a960-d33b0bb2e159",
   "metadata": {},
   "source": [
    "?[str, num] <- [['a', 1], ['b', 2]]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f98782ec-b1da-4149-8b57-0eb3c9eec5d9",
   "metadata": {},
   "source": [
    "### I have a recent version of Python on my machine and don't mind installing dependencies"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "353be466-caa8-4be7-a734-456ed0fcec3d",
   "metadata": {},
   "source": [
    "Then we assume that you know how to navigate Python's ecosystem. Install [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html) by following their instructions. Then install the [Cozo extension](https://pypi.org/project/pycozo/) by running"
   ]
  },
  {
   "cell_type": "raw",
   "id": "83d58518-1d78-4e2f-816b-fed8ab952331",
   "metadata": {},
   "source": [
    "pip install \"pycozo[pandas]\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ab051636-29e3-45dd-adb9-19729779be46",
   "metadata": {},
   "source": [
    "Now start your jupyter lab server by following their [instruction](https://jupyterlab.readthedocs.io/en/stable/getting_started/starting.html) and open the web UI for it. Start a Python 3 notebook. For the first line of the notebook, run the following instructions:"
   ]
  },
  {
   "cell_type": "raw",
   "id": "81436147-dd67-4f0e-a9c0-d6c18c37495c",
   "metadata": {},
   "source": [
    "%reload_ext pycozo.ipyext_direct"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8f65f94c-1c44-427a-a55c-7c2cd564af51",
   "metadata": {},
   "source": [
    "The username is the one you have set up earlier. It should prompt you for the password. If for any reason the password prompt has problem displaying itself on your system, you can also write the password directly after the username, separated by space. But in this case your password will be left on the UI. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e7436f95-1aec-43e3-ab36-cbde34b5ea64",
   "metadata": {},
   "source": [
    "Now you can run the query in a new cell:"
   ]
  },
  {
   "cell_type": "raw",
   "id": "564780de-90d5-4b95-a8fe-98a872d540ce",
   "metadata": {},
   "source": [
    "?[str, num] <- [['a', 1], ['b', 2]]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cc55fe45-6ffb-46a4-9c71-84b27c1e8368",
   "metadata": {},
   "source": [
    "If you get back something that looks like a table, congratulations. If you are in a rush, you can ignore the rest of this document and continue with the first tutorial now."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5b8a3f25-2fea-43bf-8dda-34c8b79f0442",
   "metadata": {},
   "source": [
    "For those who know how to use Jupyter notebooks: above we have loaded the extension `pycozo.ipyext_direct`, which enables the direct, or intrusive mode. Under this mode every cell is by default interpreted as CozoScript. If you want to execute python code, write `%%py` in the first line of the cell.\n",
    "\n",
    "There is also a non-intrusive version of the same extension. To use it, load `pycozo.ipyext` instead. Then you have to put `%%cozo` in the first line of every cell that you want to interpret as CozoScript. In addition, you can put in a variable name like this: `%%cozo result`, then the result, which is a pandas dataframe, will be stored inside the global variable you have named. You can use anything you are familiar with to visualize or further analyze the returned result in python.\n",
    "\n",
    "If you have run the server with non-default host/port, run this before you authenticate:"
   ]
  },
  {
   "cell_type": "raw",
   "id": "45592fa5-e747-4ba7-a904-2b19fc9b85e6",
   "metadata": {},
   "source": [
    "%cozo_host http://YOUR_HOST:YOUR_PORT"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "72445837-47b3-4fe1-a0fb-b3106f845e35",
   "metadata": {},
   "source": [
    "Finally, it is also possible to create a client manually and drive queries all without Jupyter:"
   ]
  },
  {
   "cell_type": "raw",
   "id": "bce5509f-a1c2-416c-b4a9-2aaa95d9dc8c",
   "metadata": {},
   "source": [
    "from pycozo import Client\n",
    "\n",
    "client = Client(username='YOUR_USERNAME', password='YOUR_PASSWORD')\n",
    "\n",
    "print(client.run('''\n",
    "    ?[str, num] <- [['a', 1], ['b', 2]]\n",
    "'''))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6051c731-0f7c-4b46-b961-947c4a6801fc",
   "metadata": {},
   "source": [
    "### I don't want to install anything on my machine!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e8fbc6d3-4684-442f-8130-43bea0ba4fd2",
   "metadata": {},
   "source": [
    "We sympathise with you. We don't like installing gigabytes of dependencies either. But you do have a modern browser on your machine, right? For the following to work, we recommend Firefox or Chrome, as they display colours more nicely than say, Safari."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bf5abcca-402a-4e41-a246-31ad0ed82ed7",
   "metadata": {},
   "source": [
    "Open this URL in your browser: [TODO]. Next, open your browser's developer console. This is usually done by right-click on the page and select \"Inspect\" or something like that from the menu."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c4c5998d-064a-4df2-9b43-3e42a0e047a3",
   "metadata": {},
   "source": [
    "Next choose 'Console' from the tabs that open up. In the console, run the following javascript to set up the client:"
   ]
  },
  {
   "cell_type": "raw",
   "id": "c5e466ec-8e8c-4718-93c6-e80f65d7bb09",
   "metadata": {},
   "source": [
    "client = Client({username: 'YOUR_USERNAME', password: 'YOUR_PASSWORD'})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "53c40e8d-5e9d-4f20-a24b-4bfdde14f17e",
   "metadata": {},
   "source": [
    "Now you can run your queries in the console:"
   ]
  },
  {
   "cell_type": "raw",
   "id": "b8c3cd97-acc9-475c-b7d7-8696384e85d8",
   "metadata": {},
   "source": [
    "await client.print(`\n",
    "    ?[str, num] <- [['a', 1], ['b', 2]]\n",
    "`)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1639064-e873-4d52-b1a4-1a1dead5bc23",
   "metadata": {},
   "source": [
    "If everything goes well, you should see something like the following:"
   ]
  },
  {
   "attachments": {
    "ed7649a2-4f38-4053-ad7b-b8d03e9bca38.png": {
     "image/png": "iVBORw0KGgoAAAANSUhEUgAABmoAAAIuCAYAAAC/wleHAAAKrWlDQ1BJQ0MgUHJvZmlsZQAASImVlwdUk8kWgOf/0xstIRQpoTfpLYCUEFro0sFGSEISSowJAcWuLCqwoqiIYFmBVREFKyBrxYJtUWzYF2RRUdbFgqiovB84hN1957133j3nnvnm5s69d+bM/OcGAAqNK5VmwWoAZEtyZDHB/oyk5BQG7jkgABVAA8bAlMuTS1nR0eEAkcnx7/LxHoDGxtu2Y7H+/ff/Kup8gZwHABSNcBpfzstG+Biib3hSWQ4AqFrEbpKXIx3jywjTZEiBCD8eY+EED45x2jij0eM+cTFshLUBwJO5XJkQALIpYmfk8oRIHHIAwg4SvliCMDIHPtnZ8/kII3mBJeIjRXgsPjPtL3GEf4uZpozJ5QqVPLGXccEHiOXSLO6i//M4/rdkZykmc5gjShbJQmKQkY6c2f3M+WFKlqRFRk2ymD/uP84iRUj8JPPk7JRJ5nMDwpRrsyLDJzldHMRRxsnhxE2yQB4YO8my+THKXOkyNmuSubKpvIrMeKVdJOAo4+eL4hInOVecEDnJ8szYsCkfttIuU8Qo6xdIgv2n8gYp954t/8t+xRzl2hxRXIhy79yp+gUS1lRMeZKyNr4gIHDKJ17pL83xV+aSZkUr/QVZwUq7PDdWuTYHuZBTa6OVZ5jBDY2eZBANQkA4YAB/EAAigAtwAG7AFYAcwcKxOwrY86WLZGKhKIfBQl6ZgMGR8OymM5wcnJwAGHuzE1dimDv+FqHF/lM2bhcATt6I8fCULQOJeWotAGpaUzbrYmTuBcA5AU8hy52wjT0ngAFEoIp8DXSAATABlsAWOCG1eQE/EAhCQRSIA8lgLuABEcgGMpAHloCVoBAUgw1gC6gEu0AN2AcOgiOgGZwE58AlcA3cBHfBI9AN+sBrMAg+ghEIgnAQBaJCOpAhZAbZQE4QE/KBAqFwKAZKhlIhISSBFNASaDVUDJVBldBuqA46DJ2AzkFXoE7oAdQD9UPvoC8wCibDNFgfNoftYSbMgsPgOHgOLIQXwPlwAbweroCr4QNwE3wOvgbfhbvh1/AQCqBIKDrKCGWLYqLYqChUCiodJUMtQxWhylHVqAZUK6oddRvVjRpAfUZj0VQ0A22L9kKHoOPRPPQC9DJ0CboSvQ/dhL6Avo3uQQ+iv2MoGD2MDcYTw8EkYYSYPEwhphyzB3MccxFzF9OH+YjFYulYC6w7NgSbjM3ALsaWYHdgG7FnsZ3YXuwQDofTwdngvHFROC4uB1eI24Y7gDuDu4Xrw33Ck/CGeCd8ED4FL8Gvwpfj9+NP42/hX+BHCGoEM4InIYrAJywilBJqCa2EG4Q+wghRnWhB9CbGETOIK4kVxAbiReJj4nsSiWRM8iDNJIlJK0gVpEOky6Qe0meyBtmazCbPJivI68l7yWfJD8jvKRSKOcWPkkLJoayn1FHOU55SPqlQVexUOCp8leUqVSpNKrdU3qgSVM1UWapzVfNVy1WPqt5QHVAjqJmrsdW4asvUqtROqHWpDalT1R3Vo9Sz1UvU96tfUX+pgdMw1wjU4GsUaNRonNfopaKoJlQ2lUddTa2lXqT20bA0CxqHlkErph2kddAGNTU0XTQTNBdqVmme0uymo+jmdA49i15KP0K/R/+ipa/F0hJordNq0LqlNaw9TdtPW6BdpN2ofVf7iw5DJ1AnU2ejTrPOE120rrXuTN083Z26F3UHptGmeU3jTSuadmTaQz1Yz1ovRm+xXo3edb0hfQP9YH2p/jb98/oDBnQDP4MMg80Gpw36DamGPoZiw82GZwxfMTQZLEYWo4JxgTFopGcUYqQw2m3UYTRibGEcb7zKuNH4iQnRhGmSbrLZpM1k0NTQNMJ0iWm96UMzghnTTGS21azdbNjcwjzRfI15s/lLC20LjkW+Rb3FY0uKpa/lAstqyztWWCumVabVDqub1rC1q7XIusr6hg1s42Yjttlh0zkdM91jumR69fQuW7ItyzbXtt62x45uF263yq7Z7o29qX2K/Ub7dvvvDq4OWQ61Do8cNRxDHVc5tjq+c7J24jlVOd1xpjgHOS93bnF+62LjInDZ6XLfleoa4brGtc31m5u7m8ytwa3f3dQ91X27exeTxoxmljAve2A8/D2We5z0+Ozp5pnjecTzTy9br0yv/V4vZ1jMEMyondHrbezN9d7t3e3D8En1+cmn29fIl+tb7fvMz8SP77fH7wXLipXBOsB64+/gL/M/7j/M9mQvZZ8NQAUEBxQFdARqBMYHVgY+DTIOEgbVBw0GuwYvDj4bggkJC9kY0sXR5/A4dZzBUPfQpaEXwshhsWGVYc/CrcNl4a0RcERoxKaIx5FmkZLI5igQxYnaFPUk2iJ6QfQvM7Ezo2dWzXwe4xizJKY9lho7L3Z/7Mc4/7jSuEfxlvGK+LYE1YTZCXUJw4kBiWWJ3Un2SUuTriXrJouTW1JwKQkpe1KGZgXO2jKrb7br7MLZ9+ZYzFk458pc3blZc0/NU53HnXc0FZOamLo/9Ss3ilvNHUrjpG1PG+SxeVt5r/l+/M38foG3oEzwIt07vSz9pdBbuEnYL/IVlYsGxGxxpfhtRkjGrozhzKjMvZmjWYlZjdn47NTsExINSabkwnyD+Qvnd0ptpIXS7gWeC7YsGJSFyfbIIfkceUsODWmOrissFT8oenJ9cqtyP+Ul5B1dqL5QsvD6IutF6xa9yA/K/3kxejFvcdsSoyUrl/QsZS3dvQxalrasbbnJ8oLlfSuCV+xbSVyZufLXVQ6rylZ9WJ24urVAv2BFQe8PwT/UF6oUygq71nit2bUWvVa8tmOd87pt674X8YuuFjsUlxd/LeGVXP3R8ceKH0fXp6/vKHUr3bkBu0Gy4d5G3437ytTL8st6N0VsatrM2Fy0+cOWeVuulLuU79pK3KrY2l0RXtGyzXTbhm1fK0WVd6v8qxq3621ft314B3/HrZ1+Oxt26e8q3vXlJ/FP93cH726qNq8ur8HW5NY8r02obf+Z+XPdHt09xXu+7ZXs7d4Xs+9CnXtd3X69/aX1cL2ivv/A7AM3DwYcbGmwbdjdSG8sPgQOKQ69Opx6+N6RsCNtR5lHG46ZHdt+nHq8qAlqWtQ02Cxq7m5Jbuk8EXqirdWr9fgvdr/sPWl0suqU5qnS08TTBadHz+SfGTorPTtwTniut21e26PzSefvXJh5oeNi2MXLl4IunW9ntZ+57H355BXPKyeuMq82X3O71nTd9frxX11/Pd7h1tF0w/1Gy02Pm62dMzpP3/K9de52wO1Ldzh3rt2NvNt5L/7e/a7ZXd33+fdfPsh68PZh7sORRyseYx4XPVF7Uv5U72n1b1a/NXa7dZ/qCei5/iz22aNeXu/r3+W/f+0reE55Xv7C8EXdS6eXJ/uD+m++mvWq77X09chA4R/qf2x/Y/nm2J9+f14fTBrseyt7O/qu5L3O+70fXD60DUUPPf2Y/XFkuOiTzqd9n5mf278kfnkxkvcV97Xim9W31u9h3x+PZo+OSrky7ngrgEIUTk8H4N1eACjJAFBvAkCcNdFTjws08T9gnMB/4om+e1zcAKg5C0A8opF+AOxcAYAFYqYg82BEQ/0A7Oys1Mn+d7xXHxMWGWmze5Awlztb7VeAf8hEH/+Xuv85AmXUv43/Agb7BZ+Fh8yGAAAAimVYSWZNTQAqAAAACAAEARoABQAAAAEAAAA+ARsABQAAAAEAAABGASgAAwAAAAEAAgAAh2kABAAAAAEAAABOAAAAAAAAAJAAAAABAAAAkAAAAAEAA5KGAAcAAAASAAAAeKACAAQAAAABAAAGaqADAAQAAAABAAACLgAAAABBU0NJSQAAAFNjcmVlbnNob3TXZ8mqAAAACXBIWXMAABYlAAAWJQFJUiTwAAAB12lUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iWE1QIENvcmUgNi4wLjAiPgogICA8cmRmOlJERiB4bWxu
    }
   },
   "cell_type": "markdown",
   "id": "fce5595b-5aa0-444e-9b12-ce8e78d20059",
   "metadata": {},
   "source": [
    "![Screen Shot 2022-09-20 at 15.49.50.png](attachment:ed7649a2-4f38-4053-ad7b-b8d03e9bca38.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d8d6d843-3df7-41ef-9622-5b0040991b22",
   "metadata": {},
   "source": [
    "This method is a bit hackish and the experience is not as nice as using Jupyter, but it is not too bad for a zero-install solution, we think. Now finally you can continue with the rest of the tutorial."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7f78a3a1-1d44-46dc-b1ee-7f37e00f439c",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}