add search doc (#235)

* add search doc

* fmt

Author: ChuckHend

core/src/query.rs

@@ -121,7 +121,7 @@ pub fn update_search_tokens_trigger_queries(
     );
     let apply_trigger = format!(
         "
-        CREATE TRIGGER {job_name}_search_tokens_trigger
+        CREATE OR REPLACE TRIGGER {job_name}_search_tokens_trigger
         AFTER INSERT OR UPDATE OR DELETE ON {src_schema}.{src_table}
         FOR EACH ROW
         EXECUTE FUNCTION {trigger_fn_name}();"

docker-compose.server.yml

@@ -35,7 +35,7 @@ services:
     environment:
         <<: *default-env
         RUST_LOG: debug
-        VECTORIZE_PROXY_ENABLED: ${VECTORIZE_PROXY_ENABLED}
+        VECTORIZE_PROXY_ENABLED: ${VECTORIZE_PROXY_ENABLED:-1}
     command: vectorize-server
   vector-serve:
     restart: always

server/README.md

@@ -0,0 +1,119 @@
+# Instant Search on any Postgres
+
+An HTTP server that sits in between your application and Postgres.
+
+## Features
+- Quickly sets up semantic and full text search on any Postgres table.
+- Generate embeddings from OpenAI, Hugging Face, and many other embedding model providers.
+- Updates embeddings and full text search token indices whenever data changes
+- Compatible with any Postgres that has [pgvector](https://github.com/pgvector/pgvector) installed (RDS, CloudSQL, etc)
+
+## Getting started
+
+Run Postgres and the HTTP servers in separate containers locally:
+
+```bash
+# docker-compose.server.yml is located in the root of this repository
+docker compose -f docker-compose.server.yml up -d
+```
+
+There are three contains; postgres, a local embedding server, and the HTTP search service.
+
+```plaintext
+docker ps --format "table {{.Image}}\t{{.Names}}"
+
+IMAGE                                   NAMES
+pg_vectorize-server                     pg_vectorize-server-1
+pgvector/pgvector:0.8.0-pg17            pg_vectorize-postgres-1
+ghcr.io/chuckhend/vector-serve:latest   pg_vectorize-vector-serve-1
+```
+
+## Create a table and insert some data
+
+`sql/example.sql` contains an example products data set.
+
+```bash
+psql postgres://postgres:postgres@localhost:5432/postgres -f sql/example.sql
+```
+
+## Generating embeddings
+
+We'll use the API to create a job that will  generate embeddings for the `description` column in the `my_products` table. Anytime we insert or update a row in this table, the embeddings will automatically be updated.
+
+```bash
+curl -X POST http://localhost:8080/api/v1/table -d '{
+        "job_name": "my_job",
+        "src_table": "my_products",
+        "src_schema": "public",
+        "src_column": "description",
+        "primary_key": "product_id",
+        "update_time_col": "updated_at",
+        "model": "sentence-transformers/all-MiniLM-L6-v2"
+    }' \
+    -H "Content-Type: application/json"
+```
+
+## Search with HTTP API
+
+```bash
+curl -X GET "http://localhost:8080/api/v1/search?job_name=my_job&query=camping%20grear&limit=2" | jq .
+```
+
+```json
+[
+  {
+    "description": "Sling made of fabric or netting, suspended between two points for relaxation",
+    "fts_rank": null,
+    "price": 40.0,
+    "product_category": "outdoor",
+    "product_id": 39,
+    "product_name": "Hammock",
+    "rrf_score": 0.01639344262295082,
+    "semantic_rank": 1,
+    "similarity_score": 0.3192296909597241,
+    "updated_at": "2025-06-25T19:57:22.410561+00:00"
+  },
+  {
+    "description": "Container for holding plants, often with drainage",
+    "fts_rank": null,
+    "price": 12.0,
+    "product_category": "garden",
+    "product_id": 8,
+    "product_name": "Plant Pot",
+    "rrf_score": 0.016129032258064516,
+    "semantic_rank": 2,
+    "similarity_score": 0.3032694847366062,
+    "updated_at": "2025-06-25T19:57:22.410561+00:00"
+  }
+]
+```
+
+## SQL proxy example
+
+We can also use the SQL proxy to perform the same search query, but using SQL instead of the HTTP API. This is useful if you have additional joins are advanced SQL queries that you want to perform.
+
+Note that this query routes through the proxy on port 5433.
+
+```sql
+psql postgres://postgres:postgres@localhost:5433/postgres -c \
+"SELECT * FROM (
+    SELECT t0.*, t1.similarity_score
+    FROM (
+        SELECT
+            product_id,
+            1 - (embeddings <=> vectorize.embed('plants', 'my_job')) as similarity_score
+        FROM vectorize._embeddings_my_job
+        ) t1
+    INNER JOIN public.my_products t0 on t0.product_id = t1.product_id
+) t
+ORDER BY t.similarity_score DESC
+LIMIT 2;"
+```
+
+```plaintext
+ product_id |   product_name   |                    description                    | product_category | price |          updated_at           |  similarity_score   
+------------+------------------+---------------------------------------------------+------------------+-------+-------------------------------+---------------------
+          8 | Plant Pot        | Container for holding plants, often with drainage | garden           | 12.00 | 2025-06-25 20:27:07.725765+00 | 0.46105278002586925
+         35 | Gardening Gloves | Handwear for protection during gardening tasks    | garden           |  8.00 | 2025-06-25 20:27:07.725765+00 |  0.2909192990160845
+(2 rows)
+```

server/sql/example.sql

@@ -0,0 +1,51 @@
+CREATE TABLE my_products (
+    product_id SERIAL PRIMARY KEY,
+    product_name TEXT NOT NULL,
+    description TEXT,
+    product_category TEXT NOT NULL,
+    price DECIMAL(10, 2) NOT NULL,
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+INSERT INTO my_products(product_name, description, product_category, price, updated_at) VALUES
+('Pencil', 'Utensil used for writing and often works best on paper', 'stationery', 1.50, NOW()),
+('Laptop Stand', 'Elevated platform for laptops, enhancing ergonomics', 'electronics', 35.99, NOW()),
+('Desk Lamp', 'Illumination device for workspaces, often adjustable', 'furniture', 22.50, NOW()),
+('Bluetooth Speaker', 'Portable audio device with wireless connectivity', 'electronics', 99.99, NOW()),
+('Water Bottle', 'Reusable container for liquids, often insulated', 'kitchenware', 15.00, NOW()),
+('Backpack', 'Storage solution for carrying personal items on one’s back', 'accessories', 45.00, NOW()),
+('Wireless Mouse', 'Pointing device without the need for a physical connection', 'electronics', 25.00, NOW()),
+('Plant Pot', 'Container for holding plants, often with drainage', 'garden', 12.00, NOW()),
+('Sunglasses', 'Protective eyewear to shield eyes from UV rays', 'accessories', 50.00, NOW()),
+('Notebook', 'Bound sheets of paper for note-taking or sketching', 'stationery', 3.99, NOW()),
+('Stylus Pen', 'Tool for touchscreen devices, mimics finger touch', 'electronics', 18.50, NOW()),
+('Travel Mug', 'Insulated container for beverages on-the-go', 'kitchenware', 10.99, NOW()),
+('Phone Charger', 'Device to replenish the battery of mobile phones', 'electronics', 20.00, NOW()),
+('Yoga Mat', 'Cushioned surface for practicing yoga or exercise', 'sports', 30.00, NOW()),
+('Wall Clock', 'Time-telling device meant to hang on walls', 'furniture', 15.50, NOW()),
+('Keychain', 'Small device for holding keys together', 'accessories', 5.00, NOW()),
+('Desk Organizer', 'Tool for sorting and storing desk items', 'furniture', 12.50, NOW()),
+('Earbuds', 'Small headphones that fit directly inside the ear', 'electronics', 49.99, NOW()),
+('Calendar', 'Physical representation of days and months, often used for scheduling', 'stationery', 10.00, NOW()),
+('Umbrella', 'Protective gear against rain or intense sun', 'accessories', 8.99, NOW()),
+('Hand Sanitizer', 'Liquid or gel used to decrease infectious agents on hands', 'personal care', 2.50, NOW()),
+('Sketchbook', 'Paper-filled book used for drawing or painting', 'stationery', 6.99, NOW()),
+('Flash Drive', 'Portable storage device for digital files', 'electronics', 12.00, NOW()),
+('Tablet Holder', 'Stand or grip for holding tablets or e-readers', 'electronics', 22.99, NOW()),
+('Shampoo', 'Hair care product designed to cleanse the scalp and hair', 'personal care', 7.50, NOW()),
+('Wristwatch', 'Time-telling device worn around the wrist', 'accessories', 120.00, NOW()),
+('Basketball', 'Spherical sporting equipment used in basketball games', 'sports', 20.00, NOW()),
+('Guitar Picks', 'Small flat tool used to strum or pick a guitar', 'music', 5.00, NOW()),
+('Thermal Flask', 'Insulated bottle for keeping beverages hot or cold', 'kitchenware', 18.99, NOW()),
+('Slippers', 'Soft and light footwear intended for indoor use', 'footwear', 10.00, NOW()),
+('Easel', 'Upright support for artists to display or work on canvases', 'art supplies', 45.00, NOW()),
+('Bicycle Helmet', 'Protective headgear for cyclists', 'sports', 35.00, NOW()),
+('Candle Holder', 'Accessory to safely hold candles when they burn', 'home decor', 15.00, NOW()),
+('Cutting Board', 'Durable board on which to place materials for cutting', 'kitchenware', 10.50, NOW()),
+('Gardening Gloves', 'Handwear for protection during gardening tasks', 'garden', 8.00, NOW()),
+('Alarm Clock', 'Time-telling device with a feature to sound at a specified time', 'electronics', 25.00, NOW()),
+('Spatula', 'Flat tool used in cooking for flipping or spreading', 'kitchenware', 3.99, NOW()),
+('Jigsaw Puzzle', 'Picture printed on cardboard or wood and cut into pieces to be reassembled', 'toys', 12.99, NOW()),
+('Hammock', 'Sling made of fabric or netting, suspended between two points for relaxation', 'outdoor', 40.00, NOW()),
+('Luggage Tag', 'Accessory attached to luggage for identification purposes', 'travel', 7.50, NOW())
+;

server/src/routes/table.rs

@@ -40,7 +40,11 @@ pub async fn table(
         &payload.src_table,
         &payload.update_time_col,
     )
-    .await?;
+    .await
+    .map_err(|e| match e {
+        vectorize_core::errors::VectorizeError::NotFound(msg) => ServerError::NotFoundError(msg),
+        _ => ServerError::from(e),
+    })?;
     if datatype != "timestamp with time zone" {
         return Err(ServerError::InvalidRequest(format!(
             "Column {} in table {}.{} must be of type 'timestamp with time zone'",