feat: added example for document saver (#164)

Author: vishwarajanand

docs/document_loader.ipynb

@@ -150,7 +150,7 @@
         "id": "f8f2830ee9ca1e01"
       },
       "source": [
-        "## Basic Usage"
+        "## Create PostgresLoader"
       ]
     },
     {
@@ -187,7 +187,7 @@
         "id": "QuQigs4UoFQ2"
       },
       "source": [
-        "### Cloud SQL Engine\n",
+        "### Cloud SQL Engine Connection Pool\n",
         "\n",
         "One of the requirements and arguments to establish PostgreSQL as a document loader is a `PostgresEngine` object. The `PostgresEngine`  configures a connection pool to your Cloud SQL for PostgreSQL database, enabling successful connections from your application and following industry best practices.\n",
         "\n",
@@ -229,6 +229,34 @@
         ")"
       ]
     },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Create a table (if not already exists)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from langchain_google_cloud_sql_pg import Column\n",
+        "\n",
+        "await engine.ainit_document_table(\n",
+        "    table_name=TABLE_NAME,\n",
+        "    content_column=\"product_name\",\n",
+        "    metadata_columns=[\n",
+        "        Column(\"id\", \"SERIAL\", nullable=False),\n",
+        "        Column(\"content\", \"VARCHAR\", nullable=False),\n",
+        "        Column(\"description\", \"VARCHAR\", nullable=False),\n",
+        "    ],\n",
+        "    metadata_json_column=\"metadata\",\n",
+        "    store_metadata=True,\n",
+        ")"
+      ]
+    },
     {
       "cell_type": "markdown",
       "metadata": {
@@ -260,7 +288,9 @@
       "source": [
         "### Load Documents via default table\n",
         "The loader returns a list of Documents from the table using the first column as page_content and all other columns as metadata. The default table will have the first column as\n",
-        "page_content and the second column as metadata (JSON). Each row becomes a document. Please note that if you want your documents to have ids you will need to add them in."
+        "page_content and the second column as metadata (JSON). Each row becomes a document. \n",
+        "\n",
+        "Please note that if you want your documents to have ids you will need to add them in.\n"
       ]
     },
     {
@@ -325,13 +355,109 @@
       "source": [
         "loader = await PostgresLoader.create(\n",
         "    engine,\n",
-        "    table_name=\"products\",\n",
+        "    table_name=TABLE_NAME,\n",
         "    content_columns=[\"product_name\", \"description\"],\n",
         "    format=\"YAML\",\n",
         ")\n",
         "docs = await loader.aload()\n",
         "print(docs)"
       ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Create PostgresSaver\n",
+        "The `PostgresSaver` allows for saving of pre-processed documents to the table using the first column as page_content and all other columns as metadata. This table can easily be loaded via a Document Loader or updated to be a VectorStore. The default table will have the first column as page_content and the second column as metadata (JSON)."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from langchain_google_cloud_sql_pg import PostgresDocumentSaver\n",
+        "\n",
+        "# Creating a basic PostgresDocumentSaver object\n",
+        "saver = await PostgresDocumentSaver.create(\n",
+        "    engine,\n",
+        "    table_name=TABLE_NAME,\n",
+        "    content_column=\"product_name\",\n",
+        "    metadata_columns=[\"description\", \"content\"],\n",
+        "    metadata_json_column=\"metadata\",\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Save Documents to default table\n",
+        "Each document becomes a row in the table."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from langchain_core.documents import Document\n",
+        "\n",
+        "test_docs = [\n",
+        "    Document(\n",
+        "        page_content=\"Red Apple\",\n",
+        "        metadata={\"description\": \"red\", \"content\": \"1\", \"category\": \"fruit\"},\n",
+        "    ),\n",
+        "    Document(\n",
+        "        page_content=\"Banana Cavendish\",\n",
+        "        metadata={\"description\": \"yellow\", \"content\": \"2\", \"category\": \"fruit\"},\n",
+        "    ),\n",
+        "    Document(\n",
+        "        page_content=\"Orange Navel\",\n",
+        "        metadata={\"description\": \"orange\", \"content\": \"3\", \"category\": \"fruit\"},\n",
+        "    ),\n",
+        "]\n",
+        "await saver.aadd_documents(test_docs)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Load the documents with PostgresLoader\n",
+        "PostgresLoader can be used with `TABLE_NAME` to query and load the whole table."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "loader = await PostgresLoader.create(engine, table_name=TABLE_NAME)\n",
+        "docs = await loader.aload()\n",
+        "\n",
+        "print(docs)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Delete Documents from default table\n",
+        "The saver deletes a list of Documents, one document at a time internally."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "await saver.adelete(test_docs)"
+      ]
     }
   ],
   "metadata": {
@@ -359,4 +485,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 4
-}
+}

src/langchain_google_cloud_sql_pg/engine.py

@@ -371,6 +371,9 @@ async def ainit_vectorstore_table(
             overwrite_existing (bool): Whether to drop existing table. Default: False.
             store_metadata (bool): Whether to store metadata in the table.
                 Default: True.
+
+        Raises:
+            :class:`DuplicateTableError <asyncpg.exceptions.DuplicateTableError>`: if table already exists and overwrite flag is not set.
         """
         await self._aexecute("CREATE EXTENSION IF NOT EXISTS vector")
 
@@ -482,10 +485,16 @@ async def ainit_document_table(
         Args:
             table_name (str): The PgSQL database table name.
             content_column (str): Name of the column to store document content.
+                Default: "page_content".
             metadata_columns (List[sqlalchemy.Column]): A list of SQLAlchemy Columns
                 to create for custom metadata. Optional.
+            metadata_json_column (str): The column to store extra metadata in JSON format.
+                Default: "langchain_metadata". Optional.
             store_metadata (bool): Whether to store extra metadata in a metadata column
                 if not described in 'metadata' field list (Default: True).
+
+        Raises:
+            :class:`DuplicateTableError <asyncpg.exceptions.DuplicateTableError>`: if table already exists.
         """
 
         query = f"""CREATE TABLE "{table_name}"(