Schema.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Schema: schema's in MongoDB\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Validator: (partieel) schema voor collection-documenten\n",
    "\n",
    "Elk document in een MongoDB collection heeft zijn eigen *structuur*: veldnamen en bijbehorende waarden (types).\n",
    "Deze grote vrijheid is niet handig als je een collectie wilt kunnen doorzoeken:\n",
    "daarvoor moet je weten welke namen en waarden de verschillende documenten gebruiken.\n",
    "Dit werkt beter als die documenten een bepaalde (minimale) gemeenschappelijke structuur hebben.\n",
    "\n",
    "Met behulp van een *validator* kun je een *minimale* structuur van de documenten in een collection beschrijven.\n",
    "MongoDB gebruikt deze validator bij het toevoegen of aanpassen van een document.\n",
    "Als dit document niet voldoet aan de beschrijving van de validator, wordt het niet toegevoegd.\n",
    "\n",
    "Je kunt de validator opgeven bij het aanmaken van de collection.\n",
    "Je kunt deze ook later toevoegen, met het db-commando `collMod` voor het aanpassen van de eigenschappen van een collection."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "De onderstaande opdracht is nodig als initialisatie in sommige omgevingen."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "os.environ[\"PATH\"]=os.environ[\"PATH\"] + \":/usr/local/bin\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Schema\n",
    "\n",
    "De structuur van de documenten in een collection noemen we een *schema*.\n",
    "In een MongoDB collection-schema bepaal je zelf welk deel van de structuur vastligt, \n",
    "en waar documenten kunnen verschillen.\n",
    "\n",
    "> In een SQL database beschrijft het (fysieke) schema de *volledige structuur* van de database: de tabellen, en de structuur van elke tabel (namen en types van de kolommen).\n",
    "Alle rijen (records) in een tabel hebben dezelfde structuur."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initialisaties"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import re\n",
    "import pandas as pd\n",
    "import numpy as np\n",
    "from IPython.core.display import display, HTML\n",
    "import pymongo\n",
    "\n",
    "pd.set_option('max_colwidth',160)\n",
    "\n",
    "userline = !echo $USER\n",
    "username = userline[0]\n",
    "dbname = username + \"-demodb\"\n",
    "print(\"Database name: \" + dbname)\n",
    "\n",
    "from pymongo import MongoClient\n",
    "print('Mongo version', pymongo.__version__)\n",
    "client = MongoClient('localhost', 27017)\n",
    "db = client[dbname]\n",
    "\n",
    "contacts = db.contacts\n",
    "contacts.drop()\n",
    "os.system('mongoimport -d ' + dbname + ' -c contacts adressen.json')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tegenvoorbeeld: toevoegen van een vreemd document\n",
    "\n",
    "MongoDB-collections hebben in eerste instantie geen structuur (schema).\n",
    "Dit betekent dat je willekeurige documenten kun toevoegen, zoals we hier demonstreren:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "contacts.insert_one({\"kleur\": \"groen\", \"prijs\": 400, \"beschrijving\": \"fiets\"})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "list(contacts.find())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Dit is natuurlijk niet de bedoeling.\n",
    "Als de database sterk gekoppeld is aan een enkele toepassing zal dit niet zo snel gebeuren.\n",
    "Maar een database wordt vaak door meerdere toepassingen gebruikt: je wilt dergelijke problemen dan voorkomen.\n",
    "\n",
    "Bovendien wil je weten welke velden (properties) gebruikt kunnen worden in de documenten in een bepaalde collection, zoals `contacts` of `agenda`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Toevoegen van de validator\n",
    "\n",
    "Met behulp van een *validator* controleert MongoDB bij het toevoegen of aanpassen van een document in een collection of dat document voldoet aan de regels van die collection.\n",
    "\n",
    "Je kunt een validator zien als een query-expressie waarmee je alle \"valide\" documenten in de database filtert.\n",
    "\n",
    "We kunnen de validator van een collection instellen met behulp van het db-commando `collMod`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Definiëren van de validator\n",
    "\n",
    "Als minimale eis voor de documenten in de `contacts`-collection stellen we dat er tenminste een `name`-veld (property) is, en een `email` of een `tel`-veld.\n",
    "Dit beschrijven we met het volgende schema: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "contact_schema = {\"name\": {\"$type\": \"string\"},\n",
    "                  \"$or\": [{\"email\": {\"$type\": \"string\"}},\n",
    "                          {\"tel\": {\"$type\": \"string\"}}\n",
    "\n",
    "                         ]}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We testen dit schema, door te zoeken naar de documenten die hier wel aan voldoen:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "list(contacts.find(contact_schema))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Toevoegen van de validator aan de collection\n",
    "\n",
    "We voegen dit schema toe als *validator*-schema voor de collection `contacts`.\n",
    "\n",
    "> Je kunt de validator definiëren bij de initialisatie van de collection, maar je kunt deze achteraf ook nog veranderen, zoals we hier doen."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "db.command(\"collMod\", \"contacts\", validator=contact_schema)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Voorbeeld: toevoegen van een valide document\n",
    "\n",
    "Het toevoegen van een document dat aan deze regels voldoet:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "contacts.insert_one({\"name\": \"Henk de Vries\", \"tel\": \"06 3333 8765\"})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Voorbeeld: toevoegen van een niet-valide document\n",
    "\n",
    "Het toevoegen van een document dat *niet* aan deze regels voldoet (door een foute keuze van het \"name\"-veld).\n",
    "\n",
    "> Dit geeft een foutmelding; later geven we een manier om hier handiger mee om te gaan in een programma."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "contacts.insert_one({\"naam\": \"Anne de Boer\", \"tel\": \"06 1234 8855\"})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Het is handiger om dergelijke fouten in het programma zelf op te vangen.\n",
    "Python biedt hiervoor de mogelijkheid met het exception-mechanisme, zie het voorbeeld hieronder:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    contacts.insert_one({\"naam\": \"Anne de Boer\", \"tel\": \"06 1234 8855\"})\n",
    "except pymongo.errors.WriteError as s:\n",
    "    print(\"Document not inserted: \" + str(s))\n",
    "else:\n",
    "    print(\"insert OK\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Vinden van niet-valide documenten\n",
    "\n",
    "Als je achteraf de validator aanpast, kan de database documenten bevatten die niet aan deze nieuwe validator voldoen.\n",
    "Met behulp van de volgende `\"$nor\"`-constructie kun je deze niet-valide documenten vinden.\n",
    "(Een `nor` met 1 alternatief is gelijk aan een `not` van dat alternatief.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "list(contacts.find({\"$nor\": [contact_schema]}))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Opdracht\n",
    "\n",
    "* breid het schema uit zodat naast een document naast de naam, een telefoonnummer of een emailadres of een fysiek adres  bevat. Dit fysieke adres heeft (tenminste) de eigenschappen (properties) `street` en `city`.\n",
    "  (Herdefinieer `contact_schema` voor deze voorwaarden.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* zoek alle documenten die aan dit schema voldoen."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* (her)definieer de collection-validator met dit nieuwe schema."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* zoek alle documenten die *niet* aan dit schema voldoen."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Demonstreer dat het schema goed werkt bij het toevoegen voor het volgende document.\n",
    "\n",
    "> Ga zelf na of dit aan het schema voldoet. Welk resultaat verwacht je?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "person = {\"name\": \"Henk de Vries\",\n",
    "          \"address\": {\"street\": \"Kastanjelaan 31\", \"city\": \"Almere\"}}\n",
    "try:\n",
    "    contacts.insert_one(person)\n",
    "except pymongo.errors.WriteError as s:\n",
    "    print(\"Document not inserted: \" + str(s))\n",
    "else:\n",
    "    print(\"insert OK\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Opdracht\n",
    "\n",
    "We willen alleen adressen met (tenminste) `street`, `city` en `postcode` toestaan.\n",
    "\n",
    "* Herdefinieer het `address_schema` zodat ook de postcode hierin opgenomen is als string.\n",
    "\n",
    "> *Opmerking*: je kunt met behulp van reguliere expressies nog preciezer beschrijven hoe een postcode eruit kan zien,\n",
    "maar dat later we hier buiten beschouwing. `string` is voldoende.\n",
    "Herdefinieer de validator met dit nieuwe `address_schema`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Geef een voorbeeld van een insert van een document dat voldoet aan deze validator."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Geef een voorbeeld van een insert van een document dat *niet* voldoet aan deze validator. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Opmerkingen\n",
    "\n",
    "* voor het beschrijven van een schema voor een validator biedt MongoDB twee mogelijkheden:\n",
    "    * de oorspronkelijke MongoDB-query-notatie, zoals hierboven gebruikt;\n",
    "    * JSON-schema, een (internet/IETF) draft-standaard voor JSON-documenten (zie https://json-schema.org, en https://json-schema.org/latest/json-schema-core.html)."
   ]
  }
 ],
 "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.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}