12_Implementing_a_Key_Value_Database.ipynb

{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "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.2"
    },
    "colab": {
      "name": "12-Implementing-a-Key-Value-Database.ipynb",
      "provenance": [],
      "include_colab_link": true
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "view-in-github",
        "colab_type": "text"
      },
      "source": [
        "<a href=\"https://colab.research.google.com/github/lis-r-barreto/Data-Engineering/blob/main/12_Implementing_a_Key_Value_Database.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "g8-Py4mvXc9j"
      },
      "source": [
        "## Implementing an efficient Key-Value Database through tree data structures\n",
        "\n",
        "In this project, we'll use a [B-tree](https://en.wikipedia.org/wiki/B-tree) data structure as a building block for a fully functioning key-value store.\n",
        "\n",
        "Trees generally allow elements to have more than one successor. We use the term binary when the number of successors is at most equal to two. In a tree, an element can have more than one successor. We call the elements in a tree __nodes__, and successors are called __children__. We call the top node the __root__ of the tree. Nodes that don't have children (no successors) are called __leaves__. The reason why we call this data structure a tree is that it somewhat resembles an upside-down tree.\n",
        "\n",
        "B-trees allows us to store key-value pairs like a dictionary. However, they also allow us to perform range searches that dictionaries do not allow. A range search corresponds to a query where we want to retrieve all entries for which the key falls within a given range. Unlike binary trees, B-trees aren't necessarily binary. This means that a node can have more than two children.\n",
        "\n",
        "A key-value store is a database that operates similar to a Python dictionary. Our key-value store will work like a Python dictionary, but it will also allow users to perform range queries. Our goal will be to create an easy-to-use, flexible, and adaptable key value store that other developers could use in their projects.\n",
        "\n",
        "There are multiple implementations of the key-value store used in production-grade systems worldwide. Some examples of open-source implementations are Redis, CouchDB, Mongo, and Cassandra (which uses a B-tree as the underlying data structure). \n",
        "\n",
        "### 1. Building the necessary structures\n",
        "\n",
        "#### 1.1 Previous classes: Node"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "5avSSFr3Xc9r"
      },
      "source": [
        "import bisect\n",
        "\n",
        "class Node:\n",
        "\n",
        "    def __init__(self, keys=None, values=None, children=None, parent=None):\n",
        "        self.keys = keys or []\n",
        "        self.values = values or []\n",
        "        self.parent = parent\n",
        "        self.set_children(children)\n",
        "        \n",
        "    def set_children(self, children):\n",
        "        self.children = children or []\n",
        "        for child in self.children:\n",
        "            child.parent = self\n",
        "\n",
        "    def is_leaf(self):\n",
        "        return len(self.children) == 0\n",
        "\n",
        "    def contains_key(self, key):\n",
        "        return key in self.keys\n",
        "\n",
        "    def get_value(self, key):\n",
        "        for i, k in enumerate(self.keys):\n",
        "            if k == key:\n",
        "                return self.values[i]\n",
        "        return None\n",
        "\n",
        "    def get_insert_index(self, key):\n",
        "        return bisect.bisect(self.keys, key)\n",
        "\n",
        "    def insert_entry(self, key, value):\n",
        "        insert_index = self.get_insert_index(key)\n",
        "        self.keys.insert(insert_index, key)\n",
        "        self.values.insert(insert_index, value)\n",
        "        return insert_index\n",
        "\n",
        "    def split(self):\n",
        "        if self.parent is None:\n",
        "            return self.split_no_parent()\n",
        "        return self.split_with_parent()\n",
        "\n",
        "    def split_no_parent(self):\n",
        "        split_index = len(self) // 2\n",
        "        key_to_move_up = self.keys[split_index]\n",
        "        value_to_move_up = self.values[split_index]\n",
        "        # Create right node\n",
        "        right_node = Node(self.keys[split_index+1:], self.values[split_index+1:], self.children[split_index+1:])\n",
        "        # Update left node (self)\n",
        "        self.keys = self.keys[:split_index]\n",
        "        self.values = self.values[:split_index]\n",
        "        self.children = self.children[:split_index+1]\n",
        "        # Create parent\n",
        "        parent = Node([key_to_move_up], [value_to_move_up], [self, right_node])\n",
        "        return parent\n",
        "\n",
        "    def insert_child(self, insert_index, child):\n",
        "        self.children.insert(insert_index, child)\n",
        "        child.parent = self\n",
        "\n",
        "    def split_with_parent(self):\n",
        "        split_index = len(self) // 2\n",
        "        key_to_move_up = self.keys[split_index]\n",
        "        value_to_move_up = self.values[split_index]\n",
        "        # Create right node\n",
        "        right_node = Node(self.keys[split_index+1:], self.values[split_index+1:], self.children[split_index+1:])\n",
        "        # Update left node (self)\n",
        "        self.keys = self.keys[:split_index]\n",
        "        self.values = self.values[:split_index]\n",
        "        self.children = self.children[:split_index+1]\n",
        "        # Add new child to parent\n",
        "        insert_index = self.parent.insert_entry(key_to_move_up, value_to_move_up)\n",
        "        self.parent.insert_child(insert_index + 1, right_node)\n",
        "        return self.parent\n",
        "\n",
        "    def __len__(self):\n",
        "        return len(self.values)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "x7tPrifDXc90"
      },
      "source": [
        "#### 1.2 Previous classes: B-tree"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "mG6B9LAVXc92"
      },
      "source": [
        "class BTree:\n",
        "    \n",
        "    def __init__(self, split_threshold):\n",
        "        self.root = Node()\n",
        "        self.split_threshold = split_threshold\n",
        "        self.height = 0\n",
        "        self.size = 0\n",
        "\n",
        "    def __len__(self):\n",
        "        return self.size\n",
        "\n",
        "    def _find_node(self, current_node, key):\n",
        "        if current_node.contains_key(key):\n",
        "            return current_node\n",
        "        if current_node.is_leaf():\n",
        "            return None\n",
        "        child_index = current_node.get_insert_index(key)\n",
        "        return self._find_node(current_node.children[child_index], key)\n",
        "\n",
        "    def contains(self, key):\n",
        "        node = self._find_node(self.root, key)\n",
        "        if node is None:\n",
        "            return False\n",
        "        return True\n",
        "\n",
        "    def _add(self, current_node, key, value):\n",
        "        if current_node.is_leaf():\n",
        "            current_node.insert_entry(key, value)\n",
        "        else:\n",
        "            child_index = current_node.get_insert_index(key)\n",
        "            self._add(current_node.children[child_index], key, value)\n",
        "        if len(current_node) > self.split_threshold:\n",
        "            parent = current_node.split()\n",
        "            if current_node == self.root:\n",
        "                self.root = parent\n",
        "                self.height += 1\n",
        "\n",
        "    def add(self, key, value):\n",
        "        self._add(self.root, key, value)\n",
        "        self.size += 1\n",
        "\n",
        "    def get_value(self, key):\n",
        "        node = self._find_node(self.root, key)\n",
        "        if node is None:\n",
        "            return None\n",
        "        return node.get_value(key)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "56nZ5QoMXc95"
      },
      "source": [
        "#### 1.3 Main class: KVStore"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "eab-KxD1Xc97"
      },
      "source": [
        "class KVStore(BTree):\n",
        "    \n",
        "    def __init__(self):\n",
        "        super().__init__(split_threshold=2)\n",
        "        \n",
        "    def add(self, key, value):\n",
        "        node = self._find_node(self.root, key)\n",
        "        if node is None:\n",
        "            super().add(key, value)\n",
        "        else:\n",
        "            for i, k in enumerate(node.keys):\n",
        "                if key == k:\n",
        "                    node.values[i] = value\n",
        "                    \n",
        "    def __getitem__(self, key):\n",
        "        return self.get_value(key)\n",
        "    \n",
        "    def __setitem__(self, key, value):\n",
        "        return self.add(key, value)\n",
        "    \n",
        "    def __contains__(self, key):\n",
        "        return self.contains(key)\n",
        "    \n",
        "    def _range_query(self, range_start, range_end, current_node, min_key, max_key):\n",
        "        if range_start > max_key or range_end < min_key:\n",
        "            return []\n",
        "        results = []\n",
        "        for i, key in enumerate(current_node.keys):\n",
        "            if range_start <= key and key <= range_end:\n",
        "                results.append(current_node.values[i])\n",
        "        if not current_node.is_leaf():\n",
        "            for i, child in enumerate(current_node.children):\n",
        "                new_min_key = current_node.keys[i - 1] if i > 0 else min_key\n",
        "                new_max_key = current_node.keys[i] if i < len(current_node) else max_key\n",
        "                results += self._range_query(range_start, range_end, child, new_min_key, new_max_key)\n",
        "        return results \n",
        "\n",
        "    def range_query(self, range_start, range_end):\n",
        "        return self._range_query(range_start, range_end, self.root, float('-inf'), float('inf'))"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "yzWpakcaXc99"
      },
      "source": [
        "### 2. Testing the implementation\n",
        "\n",
        "First, let's ensure that we can add values to the KVStore and that if we use repeated keys, the values get replaced."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "ayfaCry6Xc9_"
      },
      "source": [
        "kv = KVStore()\n",
        "kv.add(1, 'hello')\n",
        "kv.add(2, 'world')\n",
        "\n",
        "assert kv.split_threshold == 2, \"The split is not equal to 2\"\n",
        "assert kv.get_value(1) == 'hello', \"Wrong test 1\"\n",
        "assert kv.get_value(2) == 'world', \"Wrong test 2\"\n",
        "\n",
        "kv.add(1, 'goodbye')\n",
        "\n",
        "assert kv.get_value(1) == 'goodbye', \"Wrong test 3\""
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "GQTOeeZkXc-C"
      },
      "source": [
        "By now, we know that we can use the key-value store to add entries and retrieve values.\n",
        "\n",
        "We have made KVStore easier to use by allowing users to use the bracket syntax to add entries and retrieve values. Let's check this behaviour."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "_FqYvDmpXc-G"
      },
      "source": [
        "kv[3] = 'this'\n",
        "kv[4] = 'is'\n",
        "\n",
        "assert 'this' == kv[3], \"Wrong test 4\"\n",
        "assert 'is' == kv[4], \"Wrong test 5\"\n",
        "\n",
        "kv[3] = 'and'\n",
        "\n",
        "assert 'and' == kv[3], \"Wrong test 6\""
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ku9Wmdf9Xc-J"
      },
      "source": [
        "Another nice feature of the dictionary to have is the ability to use the in operator to check whether a given key is stored. We have performed this implementation and we will check it."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "qa-Mr2oOXc-L"
      },
      "source": [
        "assert 1 in kv, \"Wrong test 7\""
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "62sPnfgiXc-O"
      },
      "source": [
        "So far, we've implemented and checked the same functionality as a dictionary. Now it is time to make it more powerful by implementing range queries. Let's check this implementation."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "vr0ZO50PXc-P"
      },
      "source": [
        "assert kv.range_query(2, 4) == ['world', 'and', 'is'], \"Wrong test 8\""
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "VkQI5STYXc-R"
      },
      "source": [
        "When we're dealing with new data structures, one way to test them is to compare them with a simpler implementation that we know is correct. We perform the same operations on both and see if both provide the same results.\n",
        "\n",
        "Here below is an implementation of a key-value store that uses a dictionary as the base data structure. We will use it to test the implementation of the new structure."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "AnHh-_BJXc-T"
      },
      "source": [
        "class DictKVStore(dict):\n",
        "\n",
        "    def range_query(self, range_start, range_end):\n",
        "        result = []\n",
        "        for key in self.keys():\n",
        "            if range_start <= key and key <= range_end:\n",
        "                result.append(self[key])\n",
        "        return result"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "6MT-W99IXc-U"
      },
      "source": [
        "import random\n",
        "\n",
        "def generate_randoms(start_range, end_range, samples):\n",
        "    try:\n",
        "        return random.sample(range(start_range, end_range), samples)\n",
        "    except ValueError:\n",
        "        print('Sample size exceeded population size.')\n",
        "    \n",
        "\n",
        "    \n",
        "dict_kv = DictKVStore()\n",
        "custom_kv = KVStore()\n",
        "random_values = generate_randoms(1, 100, 10)\n",
        "\n",
        "for i in random_values:\n",
        "    dict_kv[i] = i\n",
        "    custom_kv[i] = i\n",
        "\n",
        "for range_start, range_end in [(1, 15), (32, 58), (62, 85), (90, 100)]:\n",
        "    dict_res = sorted(dict_kv.range_query(range_start, range_end))\n",
        "    custom_res = sorted(custom_kv.range_query(range_start, range_end))\n",
        "    assert dict_res == custom_res, \"Both data structures does not return the same range query result.\""
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "4p9x22xIXc-Y"
      },
      "source": [
        "Note that when we compare the result of a range query, we need to sort the values beforehand because the data structures can return the values in a different order.\n",
        "\n",
        "### 3. Performance testing\n",
        "\n",
        "The main reason to implement a new data structure to perform these operations having a much simpler implementation (Python dictionary) is the performance of range queries. \n",
        "\n",
        "While there are several ways to compare the performance of both data structures, we will follow these steps:\n",
        "\n",
        "- Generate many entries (about 50,000 should be enough).\n",
        "- Generate many query intervals. It's better to generate in a way that increases the number of query results from 1 to some given value. This way, we can see the impact of the number of results in the performance gained.\n",
        "- For each query, compute the ratio between the runtime using the dictionary-based implementation and the B-tree-based implementation. A ratio of 1 means that both took the same time, a ratio of 2 means that the B-tree implementation was two times faster, and so on.\n",
        "- Plot the runtime ratios to better visualize the results.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "nrswIlqKXc-Z"
      },
      "source": [
        "import time\n",
        "\n",
        "dict_kv = DictKVStore()\n",
        "custom_kv = KVStore()\n",
        "random_entries_keys = generate_randoms(1, 99999, 50000)\n",
        "random_entries_values = generate_randoms(1, 99999, 50000)\n",
        "\n",
        "for k, v in zip(random_entries_keys, random_entries_values):\n",
        "    dict_kv[k] = v\n",
        "    custom_kv[k] = v\n",
        "\n",
        "random_queries = generate_randoms(1, 99999, 1000)\n",
        "rand_queries = []\n",
        "\n",
        "for i in range(1000):\n",
        "    start_range = random_queries[i]\n",
        "    end_range = random_queries[i] + i\n",
        "    rand_queries.append((start_range, end_range))"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "fd3_sa9lXc-b",
        "outputId": "11ef02a0-29de-4c88-cf77-a79ac7b9c64f"
      },
      "source": [
        "time_ratios = []\n",
        "\n",
        "for range_start, range_end in rand_queries:\n",
        "    start = time.time()\n",
        "    dict_res = dict_kv.range_query(range_start, range_end)\n",
        "    end = time.time()\n",
        "    runtime_dict = end - start\n",
        "    \n",
        "    start = time.time()\n",
        "    custom_res = custom_kv.range_query(range_start, range_end)\n",
        "    end = time.time()\n",
        "    runtime_res = end - start\n",
        "    \n",
        "    runtime = runtime_dict / runtime_res\n",
        "    time_ratios.append(runtime)\n",
        "    \n",
        "%matplotlib inline\n",
        "import matplotlib.pyplot as plt\n",
        "plt.plot(time_ratios)\n",
        "plt.xlabel('Query range result size')\n",
        "plt.ylabel('Runtime ratio')\n",
        "plt.show()"
      ],
      "execution_count": null,
      "outputs": [
        {
          "data": {
            "image/png": "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\n",
            "text/plain": [
              "<Figure size 600x400 with 1 Axes>"
            ]
          },
          "metadata": {},
          "output_type": "display_data"
        }
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "8Upe_aCoXc-d"
      },
      "source": [
        "Analysing the results obtained, it can be seen that the new data structure is much faster than the standard Python dictionary implementation in obtaining results through a query. This speed is much more significant for small query ranges, while, as the ranges increase, the response times of both approaches converge."
      ]
    }
  ]
}