Update Jupyter notebook contents

* Use %pip instead of !pip
* Add more explanation

Author: yujiyokoo

languages/python/jupyter_notebook/CipherStash-Getting-Started.ipynb

@@ -16,6 +16,7 @@
     "* [Jupyter Notebook](https://jupyter.org/install)\n",
     "* [Docker](https://docs.docker.com/get-started/get-docker/)\n",
     "* [Docker compose](https://docs.docker.com/compose/install/)\n",
+    "* [curl](https://curl.se)\n",
     "* [CipherStash account](https://cipherstash.com/signup)\n",
     "* [CipherStash CLI](https://github.com/cipherstash/cli-releases/releases/latest)"
    ]
@@ -276,6 +277,18 @@
     "! docker compose up postgres -d"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "7f68e37d-210d-468d-b267-1b6930ba7957",
+   "metadata": {},
+   "source": [
+    "The command above should start PostgreSQL.\n",
+    "At any point, you can check the logs to see if there are any errors in your terminal window.\n",
+    "From the directory where your docker-copmose.yml is located (`jupyter_notebook/` by default):\n",
+    "\n",
+    "> docker compose logs -f postgres"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "d9df0769-503c-4921-bb83-f4ff2a5f8a6d",
@@ -293,7 +306,7 @@
    "id": "85888d9c-388b-4026-aaac-d72cedbec99f",
    "metadata": {},
    "source": [
-    "### Install database extensions"
+    "### Install database extensions and EQL"
    ]
   },
   {
@@ -303,25 +316,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "! PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres cipherstash_getting_started < install.sql # should output messages like `CREATE *`"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "d91bc1e4-9a22-4561-bc37-052adaaf4cef",
-   "metadata": {},
-   "source": [
-    "### Install EQL"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "dbfe2a97-f392-48e9-be64-e906684015b3",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "! PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres cipherstash_getting_started < cipherstash_encrypt_eql.sql # should output messages like `CREATE *`"
+    "! curl https://raw.githubusercontent.com/cipherstash/encrypt-query-language/refs/heads/main/release/cipherstash-encrypt-dsl.sql | PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres cipherstash_getting_started"
    ]
   },
   {
@@ -380,6 +375,18 @@
     "! docker compose up proxy -d"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "97fde254-3eb5-4036-bf82-b49ec2a77f30",
+   "metadata": {},
+   "source": [
+    "The command above should start CipherStash Proxy.\n",
+    "At any point, you can check the logs to see if there are any errors in your terminal window.\n",
+    "From the directory where your docker-copmose.yml is located (`jupyter_notebook/` by default):\n",
+    "\n",
+    "> docker compose logs -f proxy"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "0400e206-a337-404c-acc9-9706e626e94e",
@@ -401,20 +408,8 @@
     "\n",
     "There are classes prefixed with `Cs` defined in `cs_types.py` which handles conversion between the format CypherStash Proxy requires and the format for Python.\n",
     "\n",
-    "In order to encrypt and store plaintext values, CipherStash Proxy requires encrypted columns to be in JSONB format like:\n",
-    "```\n",
-    "{\n",
-    "  \"k\": \"pt\",\n",
-    "  \"p\": \"hell, world\",\n",
-    "  \"i\": {\n",
-    "    \"t\": \"examples\",\n",
-    "    \"c\": \"encrypted_utf8_str\"\n",
-    "  },\n",
-    "  \"v\": 1,\n",
-    "}\n",
-    "```\n",
-    "\n",
-    "In Python, this conversion can be done by creating an object of `CsText` as:\n",
+    "In order to encrypt and store plaintext values, CipherStash Proxy requires encrypted columns in its specific format.\n",
+    "In Python, this conversion is done by creating an object of `CsText` as:\n",
     "```\n",
     "txt = CsText(\"hell, world\", \"examples\", \"encrypted_utf8_str\")\n",
     "txt.to_db_format()\n",
@@ -440,7 +435,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "! pip install psycopg2 sqlalchemy"
+    "%pip install psycopg2 sqlalchemy"
    ]
   },
   {
@@ -462,37 +457,21 @@
    "outputs": [],
    "source": [
     "from cs_types import *\n",
-    "from psycopg2.extras import RealDictCursor"
+    "from psycopg2.extras import RealDictCursor\n",
+    "\n",
+    "print(\"Importing done.\")"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "6ac472ff-81d1-418a-998b-975b2b3f3a05",
    "metadata": {},
    "source": [
-    "## Insert end query encrypted data\n",
+    "## Insert test record\n",
     "\n",
     "With the database extensions, EQL, and application specific data types installed together with the type definitions for Python, your setup is now ready to encrypt and decrypt data."
    ]
   },
-  {
-   "cell_type": "markdown",
-   "id": "0bd5e34e-4840-4398-be46-3cc6b5969e5f",
-   "metadata": {},
-   "source": [
-    "To check what the JSONB format looks like, run the following:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "d2111106-e117-46c2-b1a1-ae8b4bb8598e",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "CsText(\"hello, python\", \"examples\", \"encrypted_utf8_str\").to_db_format()"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "3c571924-c592-447b-88a7-fef6b50f2114",
@@ -539,7 +518,14 @@
    "id": "524c68bc-be47-4887-881b-1af0b365e259",
    "metadata": {},
    "source": [
-    "Check What it looks like from both regular PostgreSQL running on port 5432 and CipherStash Proxy running on port 6432:"
+    "This should insert a single row in the encrypted `examples` table as:\n",
+    "\n",
+    "|encrypted_int|encrypted_boolean|encrypted_date|encrypted_float|encrypted_utf8_str|\n",
+    "|---|-----|--------------|----|------------|\n",
+    "|-51|false|<current_date>|-0.5|hello, world|\n",
+    "\n",
+    "You can check what it looks like from both regular PostgreSQL running on port 5432 and CipherStash Proxy running on port 6432.\n",
+    "To look at the data through CipherStash Proxy, run the following:"
    ]
   },
   {
@@ -553,6 +539,14 @@
     "!printf '\\\\x \\n select * from examples limit 1;' | PGPASSWORD=postgres psql -h localhost -p 6432 -U postgres cipherstash_getting_started"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "802cbfb3-9869-43ce-adae-1367b23ea52e",
+   "metadata": {},
+   "source": [
+    "To look at the data directly on the PostgreSQL server, run the following:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -569,7 +563,7 @@
    "id": "564d2bc7-0c45-4e5f-ba0a-5919961ee9ce",
    "metadata": {},
    "source": [
-    "In the above example, not all fields are populated, but the populated fields should contain JSONB values including the encrypted values, with \"k\" set to \"ct\" indicating \"cipher text\"."
+    "In the above example, not all fields are populated, but the populated fields contain JSONB values including the encrypted values."
    ]
   },
   {
@@ -668,14 +662,31 @@
     "print(\"created data for MATCH and ORE queries\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "4e67be50-948d-4832-80e9-6411538cf974",
+   "metadata": {},
+   "source": [
+    "The example code above should insert rows like these in the examples table:\n",
+    "\n",
+    "|  | encrypted_utf_data | encrypted_float| encrypted_jsonb | |\n",
+    "|--|---|---|---|---|\n",
+    "|  |hello, python| | | |\n",
+    "|  |hello, jupyter| | | |\n",
+    "|  |   | 100.1 | | |\n",
+    "|  |   | 100.2 | | |\n",
+    "|  |   |       | {\"top\": {\"level1\": {\"level2\": [\"a\", \"b\", \"c\"]}}} | |\n",
+    "|  |   |       | {\"top\": {\"level1\": {\"another_key\": [\"a\"]}}}  |  |\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "c2a6b812-980c-4958-a55e-45551cb474c2",
    "metadata": {},
    "source": [
     "### Partial matching\n",
     "\n",
-    "Now, a query can be run to look for a record in the `examples` table where `encrypted_utf_8_str` field contains text `\"pyth\"`:"
+    "Now, a query can be run to look for a record in the `examples` table where `encrypted_utf_8_str` field contains text `\"pyth\"`, which should match `\"hello, python\"`:"
    ]
   },
   {
@@ -726,7 +737,7 @@
    "source": [
     "### ORE queries\n",
     "\n",
-    "Finally, a query for a record with `encrypted_float` that is larger than `100.15`:"
+    "Finally, a query for a record with `encrypted_float` that is larger than `100.15` which should match `100.2`:"
    ]
   },
   {
@@ -751,7 +762,8 @@
     "### JSONB\n",
     "\n",
     "A record can be found using the JSONB path.\n",
-    "This only works with a path from the root with no missing nodes in the middle."
+    "This only works with a path from the root with no missing nodes in the middle.\n",
+    "The following matches the JSONB field containing keys `top`, `level1` and `level2`:"
    ]
   },
   {