examples/notebooks/getting-started/03 - Storing.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:19.036357Z",
     "start_time": "2019-09-23T18:50:19.031896Z"
    }
   },
   "source": [
    "# Storing\n",
    "\n",
    "This notebook demonstrates [Storing](https://nexus-forge.readthedocs.io/en/latest/interaction.html#storing) features. Storing allows users to persist and manage Resources in the configured store."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:20.068658Z",
     "start_time": "2019-09-23T18:50:19.054054Z"
    }
   },
   "outputs": [],
   "source": [
    "from kgforge.core import KnowledgeGraphForge"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A configuration file is needed in order to create a KnowledgeGraphForge session. A configuration can be generated using the notebook [00-Initialization.ipynb](00%20-%20Initialization.ipynb)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [],
   "source": [
    "forge = KnowledgeGraphForge(\"../../configurations/forge.yml\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "from kgforge.core import Resource"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Registration"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### resources"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "jane = Resource(type=\"Person\", name=\"Jane Doe\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "    type: Association\n",
      "    agent:\n",
      "    {\n",
      "        type: Person\n",
      "        name: Jane Doe\n",
      "    }\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "association = Resource(type=\"Association\", agent=jane)\n",
    "print(association)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.048776Z",
     "start_time": "2019-09-23T18:50:21.037127Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<action> _register_one\n",
      "<succeeded> True\n"
     ]
    }
   ],
   "source": [
    "forge.register(association)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.101282Z",
     "start_time": "2019-09-23T18:50:21.090545Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "association._synchronized"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.086424Z",
     "start_time": "2019-09-23T18:50:21.078142Z"
    },
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Action(error=None, message=None, operation='_register_one', succeeded=True)"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "association._last_action"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.074512Z",
     "start_time": "2019-09-23T18:50:21.061121Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'id': 'https://bbp.epfl.ch/nexus/v1/resources/dke/kgforge/_/24dbbd9e-92e0-4519-99d7-ec9bae56f7ea',\n",
       " '_constrainedBy': 'https://bluebrain.github.io/nexus/schemas/unconstrained.json',\n",
       " '_createdAt': '2022-04-12T15:54:23.358Z',\n",
       " '_createdBy': 'https://bbp.epfl.ch/nexus/v1/realms/bbp/users/sy',\n",
       " '_deprecated': False,\n",
       " '_incoming': 'https://bbp.epfl.ch/nexus/v1/resources/dke/kgforge/_/24dbbd9e-92e0-4519-99d7-ec9bae56f7ea/incoming',\n",
       " '_outgoing': 'https://bbp.epfl.ch/nexus/v1/resources/dke/kgforge/_/24dbbd9e-92e0-4519-99d7-ec9bae56f7ea/outgoing',\n",
       " '_project': 'https://bbp.epfl.ch/nexus/v1/projects/dke/kgforge',\n",
       " '_rev': 1,\n",
       " '_schemaProject': 'https://bbp.epfl.ch/nexus/v1/projects/dke/kgforge',\n",
       " '_self': 'https://bbp.epfl.ch/nexus/v1/resources/dke/kgforge/_/24dbbd9e-92e0-4519-99d7-ec9bae56f7ea',\n",
       " '_updatedAt': '2022-04-12T15:54:23.358Z',\n",
       " '_updatedBy': 'https://bbp.epfl.ch/nexus/v1/realms/bbp/users/sy'}"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "association._store_metadata"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### automatic status update"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "john = Resource(type=\"Person\", name=\"John Smith\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.109091Z",
     "start_time": "2019-09-23T18:50:21.105159Z"
    }
   },
   "outputs": [],
   "source": [
    "association.agent = john"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.121071Z",
     "start_time": "2019-09-23T18:50:21.112867Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "association._synchronized # _synchronized becomes False whenever the resource is updated"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### error handling"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "persons = [jane, john]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.132160Z",
     "start_time": "2019-09-23T18:50:21.123851Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<action> _register_one\n",
      "<succeeded> True\n"
     ]
    }
   ],
   "source": [
    "forge.register(jane)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.141175Z",
     "start_time": "2019-09-23T18:50:21.134967Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<count> 1\n",
      "<action> _register_many\n",
      "<succeeded> False\n",
      "<error> RegistrationError: resource should not be synchronized\n",
      "\n",
      "<count> 1\n",
      "<action> _register_many\n",
      "<succeeded> True\n"
     ]
    }
   ],
   "source": [
    "forge.register(persons) # it is not allowed to register an already registered resource without local change"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.150719Z",
     "start_time": "2019-09-23T18:50:21.143812Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "jane._synchronized"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.159904Z",
     "start_time": "2019-09-23T18:50:21.153635Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "john._synchronized"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note: DemoStore doesn't implement file operations yet. Please use another store for this section."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "distribution = forge.attach(\"../../data/persons.csv\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "jane = Resource(type=\"Person\", name=\"Jane Doe\", distribution=distribution)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<action> _register_one\n",
      "<succeeded> True\n"
     ]
    }
   ],
   "source": [
    "forge.register(jane)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### custom content type"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "distribution = forge.attach(\"../../data/my_data.xwz\", content_type=\"application/xwz\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "    type: Person\n",
      "    distribution: LazyAction(operation=Store.upload, args=['../../data/my_data.xwz', 'application/xwz'])\n",
      "    name: John Smith\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "john = Resource(type=\"Person\", name=\"John Smith\", distribution=distribution)\n",
    "print(john)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<action> _register_one\n",
      "<succeeded> True\n"
     ]
    }
   ],
   "source": [
    "forge.register(john)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Updating"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [],
   "source": [
    "jane = Resource(type=\"Person\", name=\"Jane Doe\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "association = Resource(type=\"Association\", agent=jane)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<action> _register_one\n",
      "<succeeded> True\n"
     ]
    }
   ],
   "source": [
    "forge.register(association)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    # DemoStore\n",
    "    print(association._store_metadata.version)\n",
    "except:\n",
    "    # BlueBrainNexus\n",
    "    print(association._store_metadata._rev)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [],
   "source": [
    "john = Resource(type=\"Person\", name=\"John Smith\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [],
   "source": [
    "association.agent = john"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.190111Z",
     "start_time": "2019-09-23T18:50:21.182709Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<action> _update_one\n",
      "<succeeded> True\n"
     ]
    }
   ],
   "source": [
    "forge.update(association)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.199561Z",
     "start_time": "2019-09-23T18:50:21.192465Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "association.agent._synchronized"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.217024Z",
     "start_time": "2019-09-23T18:50:21.208547Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    # DemoStore\n",
    "    print(association._store_metadata.version)\n",
    "except:\n",
    "    # BlueBrainNexus\n",
    "    print(association._store_metadata._rev)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Deprecation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "    type: Person\n",
      "    name: Jane Doe\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "jane = Resource(type=\"Person\", name=\"Jane Doe\")\n",
    "print(jane)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<action> _register_one\n",
      "<succeeded> True\n"
     ]
    }
   ],
   "source": [
    "forge.register(jane)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 38,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "jane._synchronized"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.276769Z",
     "start_time": "2019-09-23T18:50:21.266848Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "False\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    # DemoStore\n",
    "    print(jane._store_metadata.deprecated)\n",
    "except:\n",
    "    # BlueBrainNexus\n",
    "    print(jane._store_metadata._deprecated)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.286647Z",
     "start_time": "2019-09-23T18:50:21.279510Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<action> _deprecate_one\n",
      "<succeeded> True\n"
     ]
    }
   ],
   "source": [
    "forge.deprecate(jane)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-23T18:50:21.297768Z",
     "start_time": "2019-09-23T18:50:21.290504Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    # DemoStore\n",
    "    print(jane._store_metadata.deprecated)\n",
    "except:\n",
    "    # BlueBrainNexus\n",
    "    print(jane._store_metadata._deprecated)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.7 (nexusforgelatest)",
   "language": "python",
   "name": "nexusforgelatest"
  },
  "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.7.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}