example: finalize the example and README

Author: badmonster0

examples/paper_metadata/README.md

@@ -29,7 +29,7 @@ We appreciate a star ⭐ at [CocoIndex Github](https://github.com/cocoindex-io/c
 
 1.  [Install Postgres](https://cocoindex.io/docs/getting_started/installation#-install-postgres) if you don't have one.
 
-2.  dependencies:
+2.  Install dependencies:
 
     ```bash
     pip install -e .

examples/postgres_embedding/.env

@@ -1,6 +1,7 @@
 # Database Configuration
-# CocoIndex Database (for storing embeddings)
+
+# CocoIndex Database, for CocoIndex internal storage and target
 COCOINDEX_DATABASE_URL=postgres://cocoindex:cocoindex@localhost/cocoindex
 
-# Source Database (for reading data - can be different from CocoIndex DB)
+# Source Database, for data source
 SOURCE_DATABASE_URL=postgres://cocoindex:cocoindex@localhost/cocoindex

examples/postgres_embedding/README.md

@@ -2,153 +2,46 @@
 
 [![GitHub](https://img.shields.io/github/stars/cocoindex-io/cocoindex?color=5B5BD6)](https://github.com/cocoindex-io/cocoindex)
 
-This example demonstrates the **PostgreSQL table source** feature in CocoIndex. It reads data from existing PostgreSQL tables, generates embeddings, and stores them in a separate CocoIndex database with pgvector for semantic search.
+This example demonstrates how to use Postgres tables as the source for CocoIndex.
+It reads structured data from existing PostgreSQL tables, performs calculations, generates embeddings, and stores them in a separate CocoIndex table.
 
 We appreciate a star ⭐ at [CocoIndex Github](https://github.com/cocoindex-io/cocoindex) if this is helpful.
 
-## What This Example Does
+This example contains two flows:
 
-### 📊 Data Flow
-```
-Source PostgreSQL Table (messages)
-    ↓ [Postgres Source]
-Text Processing & Embedding Generation
-    ↓ [SentenceTransformer]
-CocoIndex Database (message_embeddings) with pgvector
-    ↓ [Semantic Search]
-Query Results
-```
+1. `postgres_message_indexing_flow`: Read from a simpler table `source_messages` (single primary key), and generate embeddings for the `message` column. 
+2. `postgres_product_indexing_flow`: Read from a more complex table `source_products` (composite primary key), compute additional fields and generates embeddings.
 
-### 🔧 Key Features
-- **PostgreSQL Source**: Read from existing database tables
-- **Separate Databases**: Source data and embeddings stored in different databases
-- **Automatic Schema**: CocoIndex creates target tables automatically
-- **pgvector Integration**: Store embeddings for semantic search
 
 ## Prerequisites
 
 Before running the example, you need to:
 
-1. **PostgreSQL with pgvector**: Follow the [CocoIndex PostgreSQL setup guide](https://cocoindex.io/docs/getting_started/quickstart) to install and configure PostgreSQL with pgvector extension.
-
-2. **Two databases**: You'll need two separate databases (names can be anything you choose):
-   - One database for your source table data
-   - One database for storing embeddings
-
-3. **Environment file**: Create a `.env` file with your database configuration:
-   ```bash
-   cp .env.example .env
-   $EDITOR .env
-   ```
-
-## Installation
-
-Install dependencies:
-
-```bash
-pip install -e .
-```
-
-## Quick Start
-
-### Environment Variables Explained
-
-The example uses these environment variables to configure the PostgreSQL source:
-
-- **`SOURCE_DATABASE_URL`**: Connection string to your source database containing the table you want to index
-- **`COCOINDEX_DATABASE_URL`**: Connection string to the database where CocoIndex will store embeddings
-- **`TABLE_NAME`**: Name of the table in your source database to read from
-- **`INDEXING_COLUMN`**: The text column to generate embeddings for (this example focuses on one column, but you can index multiple columns)
-- **`KEY_COLUMN_FOR_SINGLE_KEY`**: Primary key column name (for tables with single primary key)
-- **`KEY_COLUMNS_FOR_MULTIPLE_KEYS`**: Comma-separated primary key columns (for tables with composite primary key)
-- **`INCLUDED_COLUMNS`**: Optional - specify which columns to include (defaults to all)
-- **`ORDINAL_COLUMN`**: Optional - use for incremental updates
-
-### Option A: Test with Sample Data (Recommended for first-time users)
-
-1. **Setup test database with sample data**:
-   ```bash
-   python setup_test_database.py
-   ```
-   This will create both `test_simple` (single primary key) and `test_multiple` (composite primary key) tables with sample data.
-
-2. **Copy the generated environment configuration** to your `.env` file (the script will show you exactly what to copy).
-
-3. **Run the example**:
-   ```bash
-   python main.py
-   ```
+1.  Install dependencies:
 
-4. **Test semantic search** by entering queries in the interactive prompt
+    ```bash
+    pip install -e .
+    ```
 
-### Option B: Use Your Existing Database
+2.  Follow the [CocoIndex PostgreSQL setup guide](https://cocoindex.io/docs/getting_started/quickstart) to install and configure PostgreSQL with pgvector extension.
 
-1. **Update your `.env` file** with your database URLs and table configuration:
-   ```env
-   # CocoIndex Database (for storing embeddings)
-   COCOINDEX_DATABASE_URL=postgresql://username:password@localhost:5432/cocoindex
+3.  Create source tables `source_messages` and `source_products` with sample data:
 
-   # Source Database (for reading data)
-   SOURCE_DATABASE_URL=postgresql://username:password@localhost:5432/your_source_db
+    ```bash
+    $ psql "postgres://cocoindex:cocoindex@localhost/cocoindex" -f ./prepare_source_data.sql
+    ```
 
-   # Table Configuration
-   TABLE_NAME=your_table_name
-   KEY_COLUMN_FOR_SINGLE_KEY=id  # or KEY_COLUMNS_FOR_MULTIPLE_KEYS=col1,col2
-   INDEXING_COLUMN=your_text_column
-   ORDINAL_COLUMN=your_timestamp_column  # optional
-   ```
+    For simplicity, we use the same database for source and target. You can also setup a separate Postgres database to use as the source database.
+    Remember to update the `SOURCE_DATABASE_URL` in `.env` file if you use a separate database.
 
-2. **Run the example**:
-   ```bash
-   python main.py
-   ```
+## Run
 
-## How It Works
+Update index, which will also setup the tables at the first time:
 
-The example demonstrates a simple flow:
-
-1. **Read from Source**: Uses `cocoindex.sources.Postgres` to read from your existing table
-2. **Generate Embeddings**: Processes text and creates embeddings using SentenceTransformers
-3. **Store Embeddings**: Exports to the CocoIndex database with automatic table creation
-4. **Search**: Provides interactive semantic search over the stored embeddings
-
-**Note**: This example indexes one text column for simplicity, but you can modify the flow to index multiple columns or add more complex transformations.
-
-### Key Benefits
-
-- **Separate Databases**: Keep your source data separate from embeddings
-- **Automatic Setup**: CocoIndex creates target tables automatically
-- **Real-time Updates**: Live updates as source data changes
-- **Interactive Search**: Built-in search interface for testing
-
-## Database Configuration
-
-The example uses two separate databases:
-
-1. **Source Database**: Contains your existing data table
-2. **CocoIndex Database**: Stores generated embeddings with pgvector support
-
-This separation allows you to:
-- Keep your production data unchanged
-- Scale embeddings independently
-- Use different database configurations for each purpose
-
-## Advanced Usage
-
-### Primary Key Configuration
-
-**Single Primary Key**:
-```env
-KEY_COLUMN_FOR_SINGLE_KEY=id
-```
-
-**Composite Primary Key**:
-```env
-KEY_COLUMNS_FOR_MULTIPLE_KEYS=product_category,product_name
+```bash
+cocoindex update --setup main.py
 ```
 
-
-
 ## CocoInsight
 CocoInsight is in Early Access now (Free) 😊 You found us! A quick 3 minute video tutorial about CocoInsight: [Watch on YouTube](https://youtu.be/ZnmyoHslBSc?si=pPLXWALztkA710r9).
 

examples/postgres_embedding/main.py

@@ -2,8 +2,8 @@
 import os
 
 
-@cocoindex.flow_def(name="PostgresMessageEmbedding")
-def postgres_message_embedding_flow(
+@cocoindex.flow_def(name="PostgresMessageIndexing")
+def postgres_message_indexing_flow(
     flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.DataScope
 ) -> None:
     """
@@ -42,7 +42,7 @@ def postgres_message_embedding_flow(
         )
 
     message_embeddings.export(
-        "message_embeddings",
+        "output",
         cocoindex.targets.Postgres(),
         primary_key_fields=["id"],
         vector_indexes=[
@@ -71,8 +71,8 @@ def make_full_description(
     return f"Category: {category}\nName: {name}\n\n{description}"
 
 
-@cocoindex.flow_def(name="PostgresProductEmbedding")
-def postgres_product_embedding_flow(
+@cocoindex.flow_def(name="PostgresProductIndexing")
+def postgres_product_indexing_flow(
     flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.DataScope
 ) -> None:
     """
@@ -122,7 +122,7 @@ def postgres_product_embedding_flow(
         )
 
     product_embeddings.export(
-        "product_embeddings",
+        "output",
         cocoindex.targets.Postgres(),
         primary_key_fields=["product_category", "product_name"],
         vector_indexes=[