gqlalchemy/query_builder.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "b50a0dba",
   "metadata": {},
   "source": [
    "# How to use the GQLAlchemy query builder? \n",
    "\n",
    "Through this short tutorial, you will learn how to install Memgraph, connect to it from a Jupyter Notebook and use the GQLAlchemy library to build Cypher queries.\n",
    "\n",
    "## 1. Prerequisites\n",
    "\n",
    "For this tutorial, you will need to install:\n",
    "- [Jupyter](https://jupyter.org/install)\n",
    "- [Docker](https://docs.docker.com/get-docker/)\n",
    "\n",
    "Docker is used because Memgraph is a native Linux application and cannot be installed on Windows and macOS."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d81bb720",
   "metadata": {},
   "source": [
    "## 2. Installation using Docker\n",
    "\n",
    "After you install Docker, you can set up Memgraph by running:\n",
    "\n",
    "```\n",
    "docker run -it -p 7687:7687 -p 3000:3000 memgraph/memgraph-platform\n",
    "```\n",
    "\n",
    "This command will start the download and after it finishes, run the Memgraph container."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2c53ab73",
   "metadata": {},
   "source": [
    "## 3. Connecting to Memgraph with GQLAlchemy\n",
    "\n",
    "We will be using the **GQLAlchemy** object graph mapper (OGM) to connect to Memgraph and execute **Cypher** queries easily. GQLAlchemy also serves as a Python driver/client for Memgraph. You can install it using:\n",
    "\n",
    "```\n",
    "pip install gqlalchemy\n",
    "```\n",
    "\n",
    "> **Hint**: You may need to install [CMake](https://cmake.org/download/) before installing GQLAlchemy.\n",
    "\n",
    "Maybe you got confused when I mentioned Cypher. You can think of Cypher as SQL for graph databases. It contains many of the same language constructs like `CREATE`, `UPDATE`, `DELETE`... and it's used to query the database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "id": "d6e35b90",
   "metadata": {},
   "outputs": [],
   "source": [
    "from gqlalchemy import Memgraph"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "id": "17b8101a",
   "metadata": {},
   "outputs": [],
   "source": [
    "memgraph = Memgraph(\"127.0.0.1\", 7687)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "743d7b6b",
   "metadata": {},
   "source": [
    "Let's make sure that Memgraph is empty before we start with anything else."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "id": "5746a3bb",
   "metadata": {},
   "outputs": [],
   "source": [
    "memgraph.drop_database()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a322639d",
   "metadata": {},
   "source": [
    "## 4. Define a graph schema\n",
    "\n",
    "We are going to create Python classes that will represent our graph schema. This way, all the objects that are returned from Memgraph will be of the correct type if the class definition can be found."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "id": "85305a0a",
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Optional\n",
    "from gqlalchemy import Field, Node, Relationship\n",
    "\n",
    "\n",
    "class User(Node):\n",
    "    id: int = Field(index=True, unique=True, db=memgraph)\n",
    "    name: Optional[str] = Field()\n",
    "        \n",
    "class Follows(Relationship, type='FOLLOWS'):\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5010d156",
   "metadata": {},
   "source": [
    "## 5. Creating and returning nodes\n",
    "\n",
    "We are going to create a `User`, save it to the database and return it to our program:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "id": "b34cac6b",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'user': <User id=1979 labels={'User'} properties={'id': 0, 'name': 'Ron'}>}\n"
     ]
    }
   ],
   "source": [
    "from gqlalchemy import create\n",
    "\n",
    "\n",
    "results = create().node(labels=\"User\", id=0, name=\"Ron\", variable=\"user\").return_().execute()\n",
    "user = next(results)\n",
    "print(user)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "348b694e",
   "metadata": {},
   "source": [
    "What’s going on here:\n",
    "\n",
    "- The class `create()` is the base for the query. Other classes can also be imported and used as bases: `match()`, `merge()`, `call()`, `unwind()` and `with()`.\n",
    "- The method `node()` creates a node with the label `User` and properties `id` and `name`.\n",
    "- You need to specify the `variable` argument in order to return the results."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d46b4c05",
   "metadata": {},
   "source": [
    "## 6. Finding nodes\n",
    "\n",
    "First, we will need to create a class that will inherit from `gqlalchemy.Relationship`. Then, we can just create instances of the class and call their `save()` method to store them in the database:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "id": "7da3d5a7",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'user': <User id=1979 labels={'User'} properties={'id': 0, 'name': 'Ron'}>}\n"
     ]
    }
   ],
   "source": [
    "from gqlalchemy import match\n",
    "\n",
    "\n",
    "results = match().node(id=0, variable=\"user\").return_().execute()\n",
    "user = next(results)\n",
    "print(user)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b23b64f6",
   "metadata": {},
   "source": [
    "What’s going on here:\n",
    "\n",
    "- The class `create()` is the base for the query. It's used to find nodes and relationships in the database.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fbbd74c8",
   "metadata": {},
   "source": [
    "## What's next?\n",
    "\n",
    "Now it's time for you to use Memgraph on a graph problem!\n",
    "\n",
    "You can always check out [Memgraph Playground](https://playground.memgraph.com/) for some cool use cases and examples.\n",
    "If you need some help with GQLAlchemy, don't forget to check out the docs"
   ]
  }
 ],
 "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.9.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}