Add search-json examples (#1886)

5 files changed, 218 insertions, 180 deletions

diff --git a/docs/connections.rst b/docs/connections.rst
index cf4657b..ba39f33 100644
--- a/docs/connections.rst
+++ b/docs/connections.rst
@@ -41,3 +41,5 @@ Connection Pools
 *****************
 .. autoclass:: redis.connection.ConnectionPool
     :members:
+
+More connection examples can be found `here <examples/connection_examples.html>`_.
\ No newline at end of file
diff --git a/docs/examples.rst b/docs/examples.rst
index 7a328af..cf70c09 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -7,3 +7,4 @@ Examples
 
    examples/connection_examples
    examples/ssl_connection_examples
+   examples/search_json_examples
diff --git a/docs/examples/.ipynb_checkpoints/connection_example-checkpoint.ipynb b/docs/examples/.ipynb_checkpoints/connection_example-checkpoint.ipynb
deleted file mode 100644
index 04de8fe..0000000
--- a/docs/examples/.ipynb_checkpoints/connection_example-checkpoint.ipynb
+++ /dev/null
@@ -1,180 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Connect to redis running locally with default parameters "
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 40,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "True\n"
-     ]
-    }
-   ],
-   "source": [
-    "import redis\n",
-    "r = redis.Redis()\n",
-    "print(r.ping())"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Overwrite default parameters - connect to redis on specific host and port using username and password"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 39,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "True\n"
-     ]
-    }
-   ],
-   "source": [
-    "import redis\n",
-    "r = redis.Redis(host='localhost', port=6380, username='dvora', password='redis')\n",
-    "print(r.ping())"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Create a SSL wrapped TCP socket connection"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 38,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "True\n"
-     ]
-    }
-   ],
-   "source": [
-    "import redis\n",
-    "r = redis.Redis(host='localhost', port=6666, ssl=True, ssl_cert_reqs=\"none\")\n",
-    "print(r.ping())"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Add more parameters..."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 37,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "True\n"
-     ]
-    }
-   ],
-   "source": [
-    "import os\n",
-    "import redis\n",
-    "\n",
-    "ROOT = os.path.join(os.getcwd(), \"..\")\n",
-    "CERT_DIR = os.path.abspath(os.path.join(ROOT, \"docker\", \"stunnel\", \"keys\"))\n",
-    "\n",
-    "r = redis.Redis(\n",
-    "    host=\"localhost\",\n",
-    "    port=6666,\n",
-    "    ssl=True,\n",
-    "    ssl_certfile=os.path.join(CERT_DIR, \"server-cert.pem\"),\n",
-    "    ssl_keyfile=os.path.join(CERT_DIR, \"server-key.pem\"),\n",
-    "    ssl_cert_reqs=\"required\",\n",
-    "    ssl_ca_certs=os.path.join(CERT_DIR, \"server-cert.pem\"),\n",
-    ")\n",
-    "print(r.ping())"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Connect to redis client object configured from given URL\n",
-    "##### Three URL schemes are supported:\n",
-    "\n",
-    "##### - `redis://` creates a TCP socket connection. See more at:\n",
-    "##### <https://www.iana.org/assignments/uri-schemes/prov/redis>\n",
-    "##### - `rediss://` creates a SSL wrapped TCP socket connection. See more at:\n",
-    "##### <https://www.iana.org/assignments/uri-schemes/prov/rediss>\n",
-    "##### - ``unix://``: creates a Unix Domain Socket connection.\n",
-    "\n",
-    "##### Parameters are passed through querystring"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 36,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "True\n"
-     ]
-    }
-   ],
-   "source": [
-    "import redis\n",
-    "r = redis.from_url(\"rediss://localhost:6666?ssl_cert_reqs=none\")\n",
-    "print(r.ping())"
-   ]
-  }
- ],
- "metadata": {
-  "interpreter": {
-   "hash": "d45c99ba0feda92868abafa8257cbb4709c97f1a0b5dc62bbeebdf89d4fad7fe"
-  },
-  "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.9.9"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 2
-}
diff --git a/docs/examples/search_json_examples.ipynb b/docs/examples/search_json_examples.ipynb
new file mode 100644
index 0000000..6673663
--- /dev/null
+++ b/docs/examples/search_json_examples.ipynb
@@ -0,0 +1,214 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Indexing / querying JSON documents\n",
+    "## Adding a JSON document to an index"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "b'OK'"
+      ]
+     },
+     "execution_count": 1,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "import redis\n",
+    "from redis.commands.json.path import Path\n",
+    "import redis.commands.search.aggregation as aggregations\n",
+    "import redis.commands.search.reducers as reducers\n",
+    "from redis.commands.search.field import TextField, NumericField, TagField\n",
+    "from redis.commands.search.indexDefinition import IndexDefinition, IndexType\n",
+    "from redis.commands.search.query import NumericFilter, Query\n",
+    "\n",
+    "\n",
+    "r = redis.Redis(host='localhost', port=36379)\n",
+    "user1 = {\n",
+    "    \"user\":{\n",
+    "        \"name\": \"Paul John\",\n",
+    "        \"email\": \"paul.john@example.com\",\n",
+    "        \"age\": 42,\n",
+    "        \"city\": \"London\"\n",
+    "    }\n",
+    "}\n",
+    "user2 = {\n",
+    "    \"user\":{\n",
+    "        \"name\": \"Eden Zamir\",\n",
+    "        \"email\": \"eden.zamir@example.com\",\n",
+    "        \"age\": 29,\n",
+    "        \"city\": \"Tel Aviv\"\n",
+    "    }\n",
+    "}\n",
+    "user3 = {\n",
+    "    \"user\":{\n",
+    "        \"name\": \"Paul Zamir\",\n",
+    "        \"email\": \"paul.zamir@example.com\",\n",
+    "        \"age\": 35,\n",
+    "        \"city\": \"Tel Aviv\"\n",
+    "    }\n",
+    "}\n",
+    "r.json().set(\"user:1\", Path.rootPath(), user1)\n",
+    "r.json().set(\"user:2\", Path.rootPath(), user2)\n",
+    "r.json().set(\"user:3\", Path.rootPath(), user3)\n",
+    "\n",
+    "schema = (TextField(\"$.user.name\", as_name=\"name\"),TagField(\"$.user.city\", as_name=\"city\"), NumericField(\"$.user.age\", as_name=\"age\"))\n",
+    "r.ft().create_index(schema, definition=IndexDefinition(prefix=[\"user:\"], index_type=IndexType.JSON))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Searching"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Simple search"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Result{2 total, docs: [Document {'id': 'user:1', 'payload': None, 'json': '{\"user\":{\"name\":\"Paul John\",\"email\":\"paul.john@example.com\",\"age\":42,\"city\":\"London\"}}'}, Document {'id': 'user:3', 'payload': None, 'json': '{\"user\":{\"name\":\"Paul Zamir\",\"email\":\"paul.zamir@example.com\",\"age\":35,\"city\":\"Tel Aviv\"}}'}]}"
+      ]
+     },
+     "execution_count": 2,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "r.ft().search(\"Paul\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Filtering search results"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Result{1 total, docs: [Document {'id': 'user:3', 'payload': None, 'json': '{\"user\":{\"name\":\"Paul Zamir\",\"email\":\"paul.zamir@example.com\",\"age\":35,\"city\":\"Tel Aviv\"}}'}]}"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "q1 = Query(\"Paul\").add_filter(NumericFilter(\"age\", 30, 40))\n",
+    "r.ft().search(q1)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Projecting using JSON Path expressions "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[Document {'id': 'user:1', 'payload': None, 'city': 'London'},\n",
+       " Document {'id': 'user:3', 'payload': None, 'city': 'Tel Aviv'}]"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "r.ft().search(Query(\"Paul\").return_field(\"$.user.city\", as_field=\"city\")).docs"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Aggregation"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[[b'age', b'35'], [b'age', b'42']]"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "req = aggregations.AggregateRequest(\"Paul\").sort_by(\"@age\")\n",
+    "r.ft().aggregate(req).rows"
+   ]
+  }
+ ],
+ "metadata": {
+  "interpreter": {
+   "hash": "d45c99ba0feda92868abafa8257cbb4709c97f1a0b5dc62bbeebdf89d4fad7fe"
+  },
+  "kernelspec": {
+   "display_name": "Python 3.8.12 64-bit ('venv': venv)",
+   "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.8.12"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/docs/redismodules.rst b/docs/redismodules.rst
index 24be4da..07e756d 100644
--- a/docs/redismodules.rst
+++ b/docs/redismodules.rst
@@ -93,6 +93,7 @@ These are the commands for interacting with the `RedisJSON module <https://redis
     r = redis.Redis()
     r.json().set("mykey", ".", {"hello": "world", "i am": ["a", "json", "object!"]}
 
+Examples of how to combine search and json can be found `here <examples/search_json_examples.html>`_.
 
 .. automodule:: redis.commands.json.commands
     :members: JSONCommands