{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting Started with Triplet Store\n",
    "\n",
    "This notebook introduces the **Semantica Triplet Store** module, which allows you to store and query knowledge graph data using industry-standard RDF Triple Stores.\n",
    "\n",
    "## What is a Triplet Store?\n",
    "\n",
    "A Triplet Store (or RDF Store) is a database optimized for storing and retrieving triples: **Subject - Predicate - Object**.\n",
    "For example: `Alice` (Subject) `knows` (Predicate) `Bob` (Object).\n",
    "\n",
    "Semantica supports:\n",
    "- **Blazegraph** (Default, High Performance)\n",
    "- **Apache Jena** (Great for inference)\n",
    "- **RDF4J** (Standard Java framework)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sys\n",
    "import os\n",
    "\n",
    "# Add the project root to the path so we can import the local version of semantica\n",
    "sys.path.append(os.path.abspath('../../'))\n",
    "\n",
    "# If running in Google Colab, uncomment the following line to install dependencies\n",
    "# !pip install -q semantica"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import the TripletStore class\n",
    "from semantica.triplet_store import TripletStore\n",
    "from semantica.semantic_extract.triplet_extractor import Triplet"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Connecting to a Store\n",
    "\n",
    "To use the Triplet Store, you need a backend running. In this example, we assume a Blazegraph instance is running locally.\n",
    "\n",
    "> **Note:** If you don't have a store running, the code below shows how you *would* connect."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Connect to a Blazegraph instance\n",
    "# You can also use backend=\"jena\" or backend=\"rdf4j\"\n",
    "store = TripletStore(\n",
    "    backend=\"blazegraph\",\n",
    "    endpoint=\"http://localhost:9999/blazegraph\"\n",
    ")\n",
    "\n",
    "# Check connection status\n",
    "if hasattr(store._store_backend, 'connected') and store._store_backend.connected:\n",
    "    print(f\"Successfully connected to {store.backend_type} store at {store.endpoint}\")\n",
    "else:\n",
    "    print(f\"Warning: Could not connect to {store.backend_type} at {store.endpoint}\")\n",
    "    print(\"Operations requiring a live store connection will be skipped or fail.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Creating Triplets\n",
    "\n",
    "We use the `Triplet` class to define our data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Define a single triplet\n",
    "triplet1 = Triplet(\n",
    "    subject=\"http://example.org/Alice\",\n",
    "    predicate=\"http://xmlns.com/foaf/0.1/knows\",\n",
    "    object=\"http://example.org/Bob\"\n",
    ")\n",
    "\n",
    "print(f\"Created triplet: {triplet1.subject} -> {triplet1.predicate} -> {triplet1.object}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Adding Data\n",
    "\n",
    "You can add triplets one by one or in bulk."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from semantica.utils.exceptions import ProcessingError\n",
    "\n",
    "try:\n",
    "    # Add a single triplet\n",
    "    store.add_triplet(triplet1)\n",
    "    print(\"Added single triplet successfully.\")\n",
    "\n",
    "    # Create more triplets\n",
    "    triplets = [\n",
    "        Triplet(\n",
    "            subject=\"http://example.org/Bob\",\n",
    "            predicate=\"http://xmlns.com/foaf/0.1/knows\",\n",
    "            object=\"http://example.org/Charlie\"\n",
    "        ),\n",
    "        Triplet(\n",
    "            subject=\"http://example.org/Charlie\",\n",
    "            predicate=\"http://xmlns.com/foaf/0.1/knows\",\n",
    "            object=\"http://example.org/David\"\n",
    "        )\n",
    "    ]\n",
    "\n",
    "    # Bulk add\n",
    "    store.add_triplets(triplets)\n",
    "    print(\"Added bulk triplets successfully.\")\n",
    "\n",
    "except ProcessingError as e:\n",
    "    print(f\"Operation skipped: {e}\")\n",
    "except Exception as e:\n",
    "    print(f\"An error occurred: {e}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Querying Data (SPARQL)\n",
    "\n",
    "Use SPARQL queries to retrieve data from the store."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Simple query to get all triplets (limited to 10)\n",
    "query = \"\"\"\n",
    "SELECT ?s ?p ?o\n",
    "WHERE {\n",
    "  ?s ?p ?o\n",
    "}\n",
    "LIMIT 10\n",
    "\"\"\"\n",
    "\n",
    "try:\n",
    "    results = store.execute_query(query)\n",
    "    print(\"Query Results:\", results)\n",
    "except ProcessingError as e:\n",
    "    print(f\"Query skipped: {e}\")\n",
    "except Exception as e:\n",
    "    print(f\"An error occurred: {e}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Deleting Data\n",
    "\n",
    "Remove triplets when they are no longer needed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "store.delete_triplet(triplet1)\n",
    "print(\"Deleted triplet1\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next Steps\n",
    "\n",
    "Check out the **Advanced Triplet Store** guide in the `cookbook/advanced` folder for more complex operations like bulk loading optimization, transactions, and advanced SPARQL features."
   ]
  }
 ],
 "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.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
