### Load Example Data into Postgres

Source: https://github.com/chuckhend/pg_vectorize/blob/main/server/README.md

Connects to the local Postgres instance and executes an SQL script to populate the example products table.

```bash
psql postgres://postgres:postgres@localhost:5432/postgres -f sql/example.sql
```

--------------------------------

### Install Rust

Source: https://github.com/chuckhend/pg_vectorize/blob/main/INSTALLATION.md

Installs Rust using the official installation script. Ensure Rust is installed before proceeding with pgrx.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Install pgrx

Source: https://github.com/chuckhend/pg_vectorize/blob/main/INSTALLATION.md

Installs the pgrx tool and initializes it for a specific PostgreSQL version. This is a prerequisite for compiling and installing the extension.

```bash
cargo install cargo-pgrx --version 0.16.1 --locked
```

```bash
cargo pgrx init --pg18 $(which pg_config)
```

--------------------------------

### Load Example Dataset into Postgres

Source: https://github.com/chuckhend/pg_vectorize/blob/main/README.md

Load the provided example SQL script into your Postgres database using psql. This is an optional step to populate your database with sample data for testing.

```bash
psql postgres://postgres:postgres@localhost:5432/postgres -f server/sql/example.sql
```

--------------------------------

### List Installed Extensions

Source: https://github.com/chuckhend/pg_vectorize/blob/main/CONTRIBUTING.md

Displays a list of all installed PostgreSQL extensions, including pg_cron, pgmq, and vectorize.

```sql
\dx
```

--------------------------------

### Run Vector Serve with Docker

Source: https://github.com/chuckhend/pg_vectorize/blob/main/vector-serve/README.md

Use this command to start the vector-serve server using Docker.

```bash
make run.docker
```

--------------------------------

### Start Docker Compose

Source: https://github.com/chuckhend/pg_vectorize/blob/main/server/README.md

Launches the Postgres, embedding server, and HTTP search service containers using Docker Compose.

```bash
docker compose -f docker-compose.yml up -d
```

--------------------------------

### Connect to Postgres

Source: https://github.com/chuckhend/pg_vectorize/blob/main/extension/README.md

Connect to the running Postgres instance after starting with Docker Compose.

```bash
docker compose exec -it postgres psql
```

--------------------------------

### Clone Repo and Install Dependencies

Source: https://github.com/chuckhend/pg_vectorize/blob/main/INSTALLATION.md

Clones the pg_vectorize repository and installs necessary extension dependencies using make. Ensure you are in the extension directory before running.

```bash
git clone https://github.com/ChuckHend/pg_vectorize.git
```

```bash
cd pg_vectorize/extension
```

```bash
# install dependencies
make setup PGRX_PG_CONFIG=$(which pg_config)
```

--------------------------------

### Create and Populate Example Table

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/examples/openai_embeddings.md

Create a 'products' table and populate it with data from the 'vectorize.example_products' table. This table will be used for generating embeddings.

```sql
CREATE TABLE products (LIKE vectorize.example_products INCLUDING ALL);
INSERT INTO products SELECT * FROM vectorize.example_products;
```

--------------------------------

### GET /api/v1/search with Filters

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/server/api/search.md

Example of performing a hybrid search using GET request with multiple filter parameters. Filters are appended as URL query parameters.

```bash
curl -G "http://localhost:8080/api/v1/search" \
  --data-urlencode "job_name=my_job" \
  --data-urlencode "query=camping gear" \
  --data-urlencode "limit=2" \
  --data-urlencode "product_category=outdoor" \
  --data-urlencode "price=gt.10"
```

--------------------------------

### Search Data via HTTP API

Source: https://github.com/chuckhend/pg_vectorize/blob/main/README.md

Perform a search query using the GET /api/v1/search endpoint. This example searches for 'camping backpack' with a limit of 1 result and pipes the output to jq for pretty-printing.

```bash
curl -G \
  "http://localhost:8080/api/v1/search" \
  --data-urlencode "job_name=my_job" \
  --data-urlencode "query=camping backpack" \
  --data-urlencode "limit=1" \
  | jq .
```

--------------------------------

### Start Vector-Serve and Encode Text

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Start the `vector-serve` container and use its OpenAI-compatible embeddings API to encode text. Supports pre-cached models and on-demand model downloads.

```bash
# Start only the embeddings server
docker compose up vector-serve -d
```

```bash
# Encode text with a pre-cached model
curl -X POST http://localhost:3000/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{ "input": ["solar powered mobile electronics accessories without screens"], "model": "sentence-transformers/all-MiniLM-L12-v2" }'
# {"data":[{"embedding":[-0.079..., 0.028..., ...384 elements],"index":0}],"model":"all-MiniLM-L12-v2"}
```

```bash
# Use any Sentence-Transformers model (downloaded on first use)
curl -X POST http://localhost:3000/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{ "input": ["the quick brown fox"], "model": "sentence-transformers/sentence-t5-base" }'
```

--------------------------------

### Compile and Install pg_vectorize

Source: https://github.com/chuckhend/pg_vectorize/blob/main/INSTALLATION.md

Compiles and installs the pg_vectorize extension using pgrx. This command should be run after setting up dependencies.

```bash
cargo pgrx install
```

--------------------------------

### Start Ollama Server

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/models/index.md

Starts the Ollama server in detached mode using Docker Compose. Ensure the `wizardlm2:7b` model is pre-loaded.

```bash
docker compose up ollama-serve -d
```

--------------------------------

### Install Extension Dependencies

Source: https://github.com/chuckhend/pg_vectorize/blob/main/CONTRIBUTING.md

Installs necessary PostgreSQL extensions like pg_cron, pgmq, and pgvector from within the pg_vectorize/extension directory.

```bash
make setup
```

--------------------------------

### Create pg_vectorize Project and Import Embeddings

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/api/index.md

This example demonstrates creating a pg_vectorize project using `vectorize.table()` and then importing pre-existing embeddings with `vectorize.import_embeddings()`. The embeddings must match the dimensions of the transformer model specified during project creation.

```sql
-- First create a vectorize project
SELECT vectorize.table(
    job_name => 'product_search',
    relation => 'products',
    primary_key => 'id',
    columns => ARRAY['description'],
    transformer => 'sentence-transformers/all-MiniLM-L6-v2'
);

-- Then import pre-existing embeddings
SELECT vectorize.import_embeddings(
    job_name => 'product_search',
    src_table => 'product_embeddings',
    src_primary_key => 'product_id',
    src_embeddings_col => 'embedding_vector'
);
```

--------------------------------

### Example Search Results

Source: https://github.com/chuckhend/pg_vectorize/blob/main/server/README.md

Sample JSON output from an HTTP API search query, showing ranked products with their details and scores.

```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"
  }
]
```

--------------------------------

### Run Postgres and HTTP Servers with Docker Compose

Source: https://github.com/chuckhend/pg_vectorize/blob/main/README.md

Use docker compose to quickly set up Postgres, the embeddings server, and the management API locally. This is the recommended starting point for the HTTP server mode.

```bash
docker compose up -d
```

--------------------------------

### Run SentenceTransformers Model Server Locally

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/models/index.md

Use Docker Compose to start the SentenceTransformers model server in detached mode.

```bash
docker compose up vector-serve -d
```

--------------------------------

### List Running Docker Containers

Source: https://github.com/chuckhend/pg_vectorize/blob/main/server/README.md

Displays the images and names of the running containers for the pg_vectorize setup.

```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
```

--------------------------------

### Set OpenAI API Key

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/examples/openai_embeddings.md

Configure your PostgreSQL instance with your OpenAI API key. This is a one-time setup. Ensure to reload the configuration after setting the parameter.

```sql
ALTER SYSTEM SET vectorize.openai_key TO '<your api key>';

SELECT pg_reload_conf();
```

--------------------------------

### Configure Existing Postgres Instance

Source: https://github.com/chuckhend/pg_vectorize/blob/main/server/README.md

Sets environment variables in a .env file to connect the search and embedding servers to an existing Postgres instance with pgvector installed.

```dotenv
DATABASE_URL=postgresql://user:password@your-postgres-host:5432/postgres
HF_API_KEY=your_huggingface_api_key
```

--------------------------------

### POST /api/v1/table

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Registers and starts an embedding job against a Postgres table from the HTTP server.

```APIDOC
## POST /api/v1/table

### Description
Registers and starts an embedding job against a Postgres table from the HTTP server. Continuously watches the table for inserts/updates and maintains embeddings automatically.

### Method
POST

### Endpoint
/api/v1/table

### Parameters
#### Request Body
- **job_name** (string) - Required - The name of the embedding job.
- **src_table** (string) - Required - The source table name.
- **src_schema** (string) - Optional - The schema of the source table (defaults to 'public').
- **src_columns** (array of strings) - Required - The columns from the source table to use for embedding.
- **primary_key** (string) - Required - The primary key of the source table.
- **update_time_col** (string) - Optional - The column to track updates for.
- **model** (string) - Required - The embedding model to use.

### Request Example
```bash
curl -X POST http://localhost:8080/api/v1/table \
  -H "Content-Type: application/json" \
  -d '{ 
    "job_name":        "my_job",
    "src_table":       "my_products",
    "src_schema":      "public",
    "src_columns":     ["product_name", "description"],
    "primary_key":     "product_id",
    "update_time_col": "updated_at",
    "model":           "sentence-transformers/all-MiniLM-L6-v2"
  }'
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created embedding job.

#### Response Example
```json
{
  "id":"16b80184-2e8e-4ee6-b7e2-1a068ff4b314"
}
```
```

--------------------------------

### Run Vector Serve Docker Container

Source: https://github.com/chuckhend/pg_vectorize/blob/main/CONTRIBUTING.md

Starts the vector-serve Docker container in detached mode, exposing port 3000. This is necessary for the embedding service.

```bash
docker run -d -p 3000:3000 ghcr.io/chuckhend/vector-serve:latest
```

--------------------------------

### POST /api/v1/search with JSON Filters

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/server/api/search.md

Example of performing a hybrid search using POST request with parameters and filters in the JSON body. Filters are provided within the 'filters' object.

```bash
curl -X POST "http://localhost:8080/api/v1/search" \
  -H "Content-Type: application/json" \
  -d '{
    "job_name": "my_job",
    "query": "camping gear",
    "limit": 2,
    "filters": {"product_category": "outdoor", "price": "gt.10"}
  }'
```

--------------------------------

### GET /api/v1/search Response

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/server/api/search.md

Example JSON response for a GET hybrid search request, showing search results with associated metadata.

```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.015873015873015872,
    "semantic_rank": 3,
    "similarity_score": 0.3863893266436258,
    "updated_at": "2025-11-01T16:30:42.501294+00:00"
  }
]
```

--------------------------------

### Initialize pgrx Environment

Source: https://github.com/chuckhend/pg_vectorize/blob/main/CONTRIBUTING.md

Run this command to set up the pgrx environment for Rust-based PostgreSQL extension development.

```bash
cargo pgrx init
```

--------------------------------

### Create Vectorize Table and Import Embeddings

Source: https://github.com/chuckhend/pg_vectorize/blob/main/extension/README.md

First, create a vectorize project using `vectorize.table` specifying the relation, primary key, columns, and transformer model. Then, import pre-computed embeddings using `vectorize.import_embeddings`, linking to the source table and embedding column.

```sql
-- First create the vectorize project
SELECT vectorize.table(
    job_name    => 'my_search',
    relation    => 'my_table',
    primary_key => 'id',
    columns     => ARRAY['content'],
    transformer => 'sentence-transformers/all-MiniLM-L6-v2'
);

-- Then import your pre-computed embeddings
SELECT vectorize.import_embeddings(
    job_name            => 'my_search',
    src_table           => 'my_embeddings_table',
    src_primary_key     => 'id',
    src_embeddings_col  => 'embedding'
);
```

--------------------------------

### Hybrid Search with GET Request

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Perform hybrid semantic and full-text search using a GET request. Supports column-level filters and tuned weights for search components.

```bash
# Basic semantic search
curl -G "http://localhost:8080/api/v1/search" \
  --data-urlencode "job_name=my_job" \
  --data-urlencode "query=camping backpack" \
  --data-urlencode "limit=1" | jq .
# [{"product_id":6,"product_name":"Backpack","similarity_score":0.6296...,"rrf_score":0.0327...,...}]
```

```bash
# Hybrid search with column filters and tuned weights
curl -G "http://localhost:8080/api/v1/search" \
  --data-urlencode "job_name=my_job" \
  --data-urlencode "query=camping gear" \
  --data-urlencode "limit=2" \
  --data-urlencode "product_category=outdoor" \
  --data-urlencode "price=gt.10" \
  --data-urlencode "semantic_wt=0.7" \
  --data-urlencode "fts_wt=0.3" | jq .
# [{"product_name":"Hammock","price":40.0,"rrf_score":0.0158...,"semantic_rank":3,...}]
```

--------------------------------

### Create Vectorize Table from Existing Embeddings with vectorize.table_from()

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Combines project initialization and embedding import into a single call. This function creates the vectorize table structure, imports embeddings, and then enables the update schedule.

```sql
SELECT vectorize.table_from(
    relation           => 'products',
    columns            => ARRAY['description'],
    job_name           => 'product_search',
    primary_key        => 'product_id',
    src_table          => 'product_embeddings',
    src_primary_key    => 'product_id',
    src_embeddings_col => 'embedding_vector',
    transformer        => 'sentence-transformers/all-MiniLM-L6-v2',
    schedule           => 'realtime'
);
-- Creates table structure → imports embeddings → activates realtime triggers
```

--------------------------------

### Initialize Vector Embeddings with Sentence Transformers (Realtime)

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Use this to set up vector search on a table using Sentence Transformers for embeddings and realtime triggers for automatic updates. Ensure the vectorize extension is enabled and sample data is prepared.

```sql
CREATE EXTENSION vectorize CASCADE;

CREATE TABLE products (LIKE vectorize.example_products INCLUDING ALL);
INSERT INTO products SELECT * FROM vectorize.example_products;

SELECT vectorize.table(
    job_name    => 'product_search_hf',
    relation    => 'products',
    primary_key => 'product_id',
    columns     => ARRAY['product_name', 'description'],
    transformer => 'sentence-transformers/all-MiniLM-L6-v2',
    schedule    => 'realtime'
);
```

--------------------------------

### Initialize RAG Table with OpenAI Embeddings

Source: https://github.com/chuckhend/pg_vectorize/blob/main/extension/README.md

Initializes the RAG process for the 'products' table using the 'openai/text-embedding-3-small' model for embeddings and 'realtime' schedule for updates.

```sql
SELECT vectorize.table(
    job_name    => 'product_chat',
    relation    => 'products',
    primary_key => 'product_id',
    columns     => ARRAY['context'],
    transformer => 'openai/text-embedding-3-small',
    schedule    => 'realtime'
);
```

--------------------------------

### Select Products

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/examples/sentence_transformers.md

Retrieves the first two rows from the 'products' table to verify its contents.

```sql
SELECT * FROM products limit 2;
```

--------------------------------

### Hybrid Search (GET)

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Performs hybrid semantic and full-text search against an initialized job. Supports column-level filters with comparison operators.

```APIDOC
## GET /api/v1/search

### Description
Performs hybrid semantic + full-text search (Reciprocal Rank Fusion) against an initialized job. Supports column-level filters with comparison operators.

### Method
GET

### Endpoint
/api/v1/search

### Query Parameters
- **job_name** (string) - Required - The name of the initialized job.
- **query** (string) - Required - The search query.
- **limit** (integer) - Optional - The maximum number of results to return.
- **product_category** (string) - Optional - Filter by product category.
- **price** (string) - Optional - Filter by price using operators like `gt.10`.
- **semantic_wt** (float) - Optional - Weight for semantic search.
- **fts_wt** (float) - Optional - Weight for full-text search.

### Request Example
```bash
curl -G "http://localhost:8080/api/v1/search" \
  --data-urlencode "job_name=my_job" \
  --data-urlencode "query=camping backpack" \
  --data-urlencode "limit=1"
```

### Response
#### Success Response (200)
- **product_id** (integer) - Product identifier.
- **product_name** (string) - Name of the product.
- **similarity_score** (float) - Score indicating semantic similarity.
- **rrf_score** (float) - Reciprocal Rank Fusion score.

#### Response Example
```json
[{"product_id":6,"product_name":"Backpack","similarity_score":0.6296...,"rrf_score":0.0327...,...}]
```

**Supported filter operators:** `eq` (default), `gt`, `gte`, `lt`, `lte`
```

--------------------------------

### vectorize.table_from()

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Combines project initialization and embedding import into one call.

```APIDOC
## vectorize.table_from()

### Description
Combines project initialization and embedding import into one call. Creates the vectorize table structure, imports embeddings, then enables the update schedule.

### Method
SQL Function Call

### Parameters
- **relation** (string) - Required - The source table name.
- **columns** (array of strings) - Required - The columns to use for embedding generation.
- **job_name** (string) - Required - The name of the vectorize job.
- **primary_key** (string) - Required - The primary key of the source table.
- **src_table** (string) - Required - The source table containing pre-computed embeddings.
- **src_primary_key** (string) - Required - The primary key column in the source embedding table.
- **src_embeddings_col** (string) - Required - The column in the source embedding table containing the embedding vectors.
- **transformer** (string) - Required - The embedding model to use.
- **schedule** (string) - Optional - The update schedule ('realtime' or cron expression).

### Request Example
```sql
SELECT vectorize.table_from(
    relation           => 'products',
    columns            => ARRAY['description'],
    job_name           => 'product_search',
    primary_key        => 'product_id',
    src_table          => 'product_embeddings',
    src_primary_key    => 'product_id',
    src_embeddings_col => 'embedding_vector',
    transformer        => 'sentence-transformers/all-MiniLM-L6-v2',
    schedule           => 'realtime'
);
```

### Response
#### Success Response
- (string) - Confirmation message indicating table creation, embedding import, and schedule activation.
```

--------------------------------

### Call OpenAI text-embedding-3-large via SQL

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/models/index.md

Use the `pg_vectorize.transform_embeddings` SQL function to get embeddings from OpenAI's text-embedding-3-large model.

```sql
select vectorize.transform_embeddings(
    input => 'the quick brown fox jumped over the lazy dogs',
    model_name => 'openai/text-embedding-3-large'
);
```

--------------------------------

### Call OpenAI text-embedding-ada-002 via SQL

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/models/index.md

Use the `pg_vectorize.transform_embeddings` SQL function to get embeddings from OpenAI's text-embedding-ada-002 model.

```sql
select vectorize.transform_embeddings(
    input       => 'the quick brown fox jumped over the lazy dogs',
    model_name  => 'openai/text-embedding-ada-002'
);
```

--------------------------------

### Set Shared Preload Libraries

Source: https://github.com/chuckhend/pg_vectorize/blob/main/extension/README.md

Configure Postgres to load the vectorize and pg_cron libraries on startup. Requires a Postgres restart.

```sql
alter system set shared_preload_libraries = 'vectorize,pg_cron';
alter system set cron.database_name = 'postgres';
```

--------------------------------

### Generate Text with LLM

Source: https://github.com/chuckhend/pg_vectorize/blob/main/extension/README.md

Use the `vectorize.generate` function to get text output from a specified LLM. Ensure the model name is correctly formatted.

```sql
select vectorize.generate(
  input => 'Tell me the difference between a cat and a dog in 1 sentence',
  model => 'openai/gpt-4o'
);
```

--------------------------------

### Compile and Run pg_vectorize

Source: https://github.com/chuckhend/pg_vectorize/blob/main/CONTRIBUTING.md

Compiles the pg_vectorize extension and launches a psql session to interact with it.

```bash
make run
```

--------------------------------

### Hybrid Search (POST)

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Provides the same hybrid search capability as the GET endpoint but accepts parameters as a JSON body, including a structured `filters` object.

```APIDOC
## POST /api/v1/search

### Description
Same hybrid search capability as GET but accepts parameters as a JSON body, including a structured `filters` object.

### Method
POST

### Endpoint
/api/v1/search

### Request Body
- **job_name** (string) - Required - The name of the initialized job.
- **query** (string) - Required - The search query.
- **limit** (integer) - Optional - The maximum number of results to return.
- **window_size** (integer) - Optional - Size of the search window.
- **rrf_k** (float) - Optional - Parameter for Reciprocal Rank Fusion.
- **semantic_wt** (float) - Optional - Weight for semantic search.
- **fts_wt** (float) - Optional - Weight for full-text search.
- **filters** (object) - Optional - An object containing filter criteria.
  - **product_category** (string) - Optional - Filter by product category.
  - **price** (string) - Optional - Filter by price using operators like `gt.10`.

### Request Example
```bash
curl -X POST "http://localhost:8080/api/v1/search" \
  -H "Content-Type: application/json" \
  -d 
'{ 
  "job_name":    "my_job",
  "query":       "camping gear",
  "limit":       2,
  "window_size": 50,
  "rrf_k":       60.0,
  "semantic_wt": 1.0,
  "fts_wt":      1.0,
  "filters": {
    "product_category": "outdoor",
    "price":            "gt.10"
  }
}'
```

### Response
#### Success Response (200)
- **product_id** (integer) - Product identifier.
- **product_name** (string) - Name of the product.
- **price** (float) - Price of the product.
- **rrf_score** (float) - Reciprocal Rank Fusion score.
- **semantic_rank** (integer) - Rank based on semantic similarity.

#### Response Example
```json
[
  {
    "description":        "Sling made of fabric or netting...",
    "fts_rank":           null,
    "price":              40.0,
    "product_category":   "outdoor",
    "product_id":         39,
    "product_name":       "Hammock",
    "rrf_score":          0.015873015873015872,
    "semantic_rank":      3,
    "similarity_score":   0.3863893266436258,
    "updated_at":         "2025-11-01T16:30:42.501294+00:00"
  }
]
```
```

--------------------------------

### Call SentenceTransformers Model via SQL

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/models/index.md

Use the `pg_vectorize.transform_embeddings` SQL function to get embeddings from a SentenceTransformers model. Model name rules apply.

```sql
select vectorize.transform_embeddings(
    input       => 'the quick brown fox jumped over the lazy dogs',
    model_name  => 'sentence-transformers/multi-qa-MiniLM-L6-dot-v1'
);
```

--------------------------------

### GET /api/v1/search

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/server/api/search.md

Performs a hybrid search using URL query parameters. Accepts parameters like job_name, query, limit, and optional filters.

```APIDOC
## GET /api/v1/search

### Description
Performs a hybrid semantic and full-text search against a vectorize job using URL query parameters.

### Method
GET

### Endpoint
/api/v1/search

### Parameters
#### Query Parameters
- **job_name** (string) - Required - Name of the vectorize job to search.
- **query** (string) - Required - The user's search query string.
- **limit** (int) - Optional - Maximum number of results to return. Default: 10.
- **window_size** (int) - Optional - Internal window size used by the hybrid search algorithm. Default: 5 * limit.
- **rrf_k** (float) - Optional - Reciprocal Rank Fusion parameter. Default: 60.0.
- **semantic_wt** (float) - Optional - Weight applied to the semantic score. Default: 1.0.
- **fts_wt** (float) - Optional - Weight applied to the full-text-search score. Default: 1.0.
- **filters** (object) - Optional - Additional filters passed as separate query parameters (e.g., `product_category=outdoor`, `price=gt.10`).

### Request Example
```bash
curl -G "http://localhost:8080/api/v1/search" \
  --data-urlencode "job_name=my_job" \
  --data-urlencode "query=camping gear" \
  --data-urlencode "limit=2" \
  --data-urlencode "product_category=outdoor" \
  --data-urlencode "price=gt.10"
```

### Response
#### Success Response (200)
Returns an array of search results, each containing fields like description, price, product_name, etc.

#### Response Example
```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.015873015873015872,
    "semantic_rank": 3,
    "similarity_score": 0.3863893266436258,
    "updated_at": "2025-11-01T16:30:42.501294+00:00"
  }
]
```
```

--------------------------------

### Create Product Search Vectorization Job

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/examples/sentence_transformers.md

Sets up a vectorization job named 'product_search_hf' for the 'products' table. It specifies the primary key, columns for embedding, the transformer model, and the scheduler type.

```sql
SELECT vectorize.table(
    job_name    => 'product_search_hf',
    relation    => 'products',
    primary_key => 'product_id',
    columns     => ARRAY['product_name', 'description'],
    transformer => 'sentence-transformers/multi-qa-MiniLM-L6-dot-v1',
    scheduler   => 'realtime'
);
```

--------------------------------

### Initialize Vector Embeddings with OpenAI (Global GUC)

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Set the OpenAI API key globally using a GUC (Grand Unified Configuration) and then initialize vector search. This simplifies configuration if the key is consistent across jobs.

```sql
ALTER SYSTEM SET vectorize.openai_key TO 'sk-...';
SELECT pg_reload_conf();

SELECT vectorize.table(
    job_name    => 'product_search_oai',
    relation    => 'products',
    primary_key => 'product_id',
    columns     => ARRAY['product_name', 'description'],
    transformer => 'openai/text-embedding-3-small'
);
```

--------------------------------

### Call SentenceTransformers Model Server with Curl

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/models/index.md

Send a POST request to the local model server to get embeddings for input text. Specify the model to use.

```bash
curl -X POST http://localhost:3000/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{"input": ["solar powered mobile electronics accessories without screens"],
   "model": "sentence-transformers/all-MiniLM-L12-v2"}'
```

--------------------------------

### Ask Question using Ollama Chat Model

Source: https://github.com/chuckhend/pg_vectorize/blob/main/extension/README.md

Queries the 'product_chat' RAG agent with a question about pencils, using a locally hosted Ollama service ('ollama/wizardlm2:7b') as the chat model.

```sql
SELECT vectorize.rag(
    job_name    => 'product_chat',
    query       => 'What is a pencil?',
    chat_model  => 'ollama/wizardlm2:7b'
) -> 'chat_response';
```

--------------------------------

### Set Embedding Service URL

Source: https://github.com/chuckhend/pg_vectorize/blob/main/extension/README.md

Configure the URL for the embedding service. The host may need adjustment based on your container setup. This setting requires a Postgres configuration reload.

```sql
alter system set vectorize.embedding_service_url = 'http://localhost:3000/v1';

SELECT pg_reload_conf();
```

--------------------------------

### Ask Question using OpenAI Chat Model

Source: https://github.com/chuckhend/pg_vectorize/blob/main/extension/README.md

Queries the 'product_chat' RAG agent with a question about pencils, using the 'openai/gpt-3.5-turbo' chat model. The '-> 'chat_response'' selects only the chat response from the JSON output.

```sql
SELECT vectorize.rag(
    job_name    => 'product_chat',
    query       => 'What is a pencil?',
    chat_model  => 'openai/gpt-3.5-turbo'
) -> 'chat_response';
```

--------------------------------

### Direct LLM Text Generation with vectorize.generate()

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Calls a text-generation LLM directly from SQL. Specify the input text and the desired model. Supports models like OpenAI GPT-4o and local Ollama models.

```sql
-- Call OpenAI GPT-4o for text generation
SELECT vectorize.generate(
    input => 'Tell me the difference between a cat and a dog in 1 sentence',
    model => 'openai/gpt-4o'
);
/*
 Cats are generally more independent and solitary, while dogs tend to be more social and loyal companions.
*/

-- Use Ollama locally
SELECT vectorize.generate(
    input => 'What is PostgreSQL?',
    model => 'ollama/wizardlm2:7b'
);
```

--------------------------------

### Initialize Vector Embeddings with OpenAI (Cron Schedule)

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Configure vector search using OpenAI embeddings, providing the API key via arguments and setting a cron schedule for updates. This method is suitable when API keys should not be set globally.

```sql
SELECT vectorize.table(
    job_name    => 'product_search_oai',
    relation    => 'products',
    primary_key => 'product_id',
    columns     => ARRAY['product_name', 'description'],
    transformer => 'openai/text-embedding-ada-002',
    args        => '{"api_key": "sk-..."}',
    schedule    => '* * * * *'   -- cron: check every minute
);
```

--------------------------------

### Create Embedding Job via HTTP Server API POST /api/v1/table

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Registers and starts an embedding job against a Postgres table using the HTTP server API. This process continuously monitors the table for inserts/updates and automatically maintains embeddings.

```bash
# Start all services
docker compose up -d

# Load example dataset
psql postgres://postgres:postgres@localhost:5432/postgres -f server/sql/example.sql

# Create embedding job
curl -X POST http://localhost:8080/api/v1/table \
  -H "Content-Type: application/json" \
  -d '{
    "job_name":        "my_job",
    "src_table":       "my_products",
    "src_schema":      "public",
    "src_columns":     ["product_name", "description"],
    "primary_key":     "product_id",
    "update_time_col": "updated_at",
    "model":           "sentence-transformers/all-MiniLM-L6-v2"
  }'
# {"id":"16b80184-2e8e-4ee6-b7e2-1a068ff4b314"}

# Connect to an existing managed Postgres (e.g., RDS) via .env
# DATABASE_URL=postgresql://user:password@your-rds-host:5432/postgres
```

--------------------------------

### Configure Embedding Service URL for Postgres Extension

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Point the Postgres extension to the `vector-serve` service by setting the `vectorize.embedding_service_url` GUC. Reloads configuration to apply changes.

```sql
ALTER SYSTEM SET vectorize.embedding_service_url TO 'http://localhost:3000/v1';
SELECT pg_reload_conf();
```

--------------------------------

### Import Pre-computed Embeddings with vectorize.import_embeddings()

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Imports pre-computed embeddings from a source table into an existing vectorize project. Ensure the dimensions of the embeddings match the transformer specified in vectorize.table().

```sql
-- Step 1: create the vectorize project (no computation yet)
SELECT vectorize.table(
    job_name    => 'product_search',
    relation    => 'products',
    primary_key => 'product_id',
    columns     => ARRAY['description'],
    transformer => 'sentence-transformers/all-MiniLM-L6-v2'
);

-- Step 2: import 384-dim pre-computed embeddings from another table
SELECT vectorize.import_embeddings(
    job_name            => 'product_search',
    src_table           => 'product_embeddings',
    src_primary_key     => 'product_id',
    src_embeddings_col  => 'embedding_vector'
);
-- Validates dimensions, cleans up pending realtime jobs, populates index.
```

--------------------------------

### Initialize Vector Table

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/api/search.md

Initializes a table for vector search, generating embeddings and an index. It also sets up triggers for automatic updates. Configure parameters like relation, columns, primary_key, and transformer.

```sql
vectorize."table"(
    "relation" TEXT,
    "columns" TEXT[],
    "job_name" TEXT,
    "primary_key" TEXT,
    "schema" TEXT DEFAULT 'public',
    "update_col" TEXT DEFAULT 'last_updated_at',
    "transformer" TEXT DEFAULT 'sentence-transformers/all-MiniLM-L6-v2',
    "index_dist_type" vectorize.IndexDist DEFAULT 'pgv_hnsw_cosine',
    "table_method" vectorize.TableMethod DEFAULT 'join',
    "schedule" TEXT DEFAULT '* * * * *'
) RETURNS TEXT
```

--------------------------------

### Create Table Vectorize Job

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/server/api/table.md

Use this endpoint to create a new vectorization job. Provide details about the source table, columns, primary key, update timestamp column, and the embedding model. The server validates the timestamp column type and initializes the job.

```bash
curl -X POST http://localhost:8080/api/v1/table -d '{
  "job_name": "my_job",
  "src_table": "my_products",
  "src_schema": "public",
  "src_columns": ["product_name", "description"],
  "primary_key": "product_id",
  "update_time_col": "updated_at",
  "model": "sentence-transformers/all-MiniLM-L6-v2"
}' -H "Content-Type: application/json"
```

--------------------------------

### Configure Vectorize to Run on a Non-Default Database

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Specify a non-default database for `vectorize` and `cron` operations using `vectorize.database_name` and `cron.database_name` GUCs. Requires restarting Postgres and creating the extension in the new database.

```sql
-- Run vectorize on a non-default database
ALTER SYSTEM SET vectorize.database_name TO 'my_app_db';
ALTER SYSTEM SET cron.database_name      TO 'my_app_db';
-- Then restart Postgres, connect to the new DB, and:
CREATE EXTENSION vectorize CASCADE;
```

--------------------------------

### Check Running Docker Containers

Source: https://github.com/chuckhend/pg_vectorize/blob/main/CONTRIBUTING.md

Verifies that the Docker containers are running, including the vector-serve container.

```bash
docker ps
```

--------------------------------

### Create Vectorization Job

Source: https://github.com/chuckhend/pg_vectorize/blob/main/extension/README.md

Creates a vectorization job named 'product_search_hf' for the 'products' table. It specifies the primary key, columns to vectorize, the embedding transformer ('sentence-transformers/all-MiniLM-L6-v2'), and sets the schedule to 'realtime'.

```sql
SELECT vectorize.table(
    job_name    => 'product_search_hf',
    relation    => 'products',
    primary_key => 'product_id',
    columns     => ARRAY['product_name', 'description'],
    transformer => 'sentence-transformers/all-MiniLM-L6-v2',
    schedule    => 'realtime'
);
```

--------------------------------

### Enable Vectorize Extension

Source: https://github.com/chuckhend/pg_vectorize/blob/main/CONTRIBUTING.md

Enables the 'vectorize' extension and any dependent extensions within a psql console.

```sql
create extension vectorize cascade
```

--------------------------------

### Clone pg_vectorize Repository

Source: https://github.com/chuckhend/pg_vectorize/blob/main/CONTRIBUTING.md

Clones the pg_vectorize project from GitHub and navigates into the extension directory.

```bash
git clone https://github.com/tembo-io/pg_vectorize.git

cd pg_vectorize/extension
```

--------------------------------

### Set Custom OpenAI-Compatible Base URL

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Configure a custom base URL for OpenAI-compatible services (e.g., vLLM, Azure OpenAI) by setting the `vectorize.openai_service_url` GUC.

```sql
-- Custom OpenAI-compatible base URL (e.g., vLLM, Azure OpenAI)
ALTER SYSTEM SET vectorize.openai_service_url TO 'https://api.myserver.com/v1';
```

--------------------------------

### Initialize Vector Embeddings with Append Table Method

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Configure vector search to store embeddings directly within the source table by using the 'append' table method. This is an alternative to creating a separate joined table for embeddings.

```sql
SELECT vectorize.table(
    job_name     => 'product_search_append',
    relation     => 'products',
    primary_key  => 'product_id',
    columns      => ARRAY['product_name', 'description'],
    transformer  => 'sentence-transformers/all-MiniLM-L6-v2',
    table_method => 'append',
    schedule     => 'realtime'
);
```

--------------------------------

### Initialize Table

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/api/search.md

Initializes a table for vector search, generating embeddings and an index. It also creates triggers to maintain up-to-date embeddings.

```APIDOC
## vectorize.table()

### Description
Initializes a table for vector search, generating embeddings and an index. Creates triggers to keep embeddings up-to-date.

### Signature
vectorize."table"(
    "relation" TEXT,
    "columns" TEXT[],
    "job_name" TEXT,
    "primary_key" TEXT,
    "schema" TEXT DEFAULT 'public',
    "update_col" TEXT DEFAULT 'last_updated_at',
    "transformer" TEXT DEFAULT 'sentence-transformers/all-MiniLM-L6-v2',
    "index_dist_type" vectorize.IndexDist DEFAULT 'pgv_hnsw_cosine',
    "table_method" vectorize.TableMethod DEFAULT 'join',
    "schedule" TEXT DEFAULT '* * * * *'
) RETURNS TEXT

### Parameters
#### Path Parameters
- **relation** (text) - Required - The name of the table to be initialized.
- **columns** (text[]) - Required - The name of the columns that contains the content that is used for context for RAG. Multiple columns are concatenated.
- **job_name** (text) - Required - A unique name for the project.
- **primary_key** (text) - Required - The name of the column that contains the unique record id.
- **schema** (text) - Optional - The name of the schema where the table is located. Defaults to 'public'.
- **update_col** (text) - Optional - Column specifying the last time the record was updated. Required for cron-like schedule. Defaults to `last_updated_at`.
- **transformer** (text) - Optional - The name of the transformer to use for the embeddings. Defaults to 'text-embedding-ada-002'.
- **index_dist_type** (vectorize.IndexDist) - Optional - The name of index type to build. Defaults to 'pgv_hnsw_cosine'.
- **table_method** (vectorize.TableMethod) - Optional - `join` to store embeddings in a new table in the vectorize schema. `append` to create columns for embeddings on the source table. Defaults to `join`.
- **schedule** (text) - Optional - Accepts a cron-like input for a cron based updates. Or `realtime` to set up a trigger.

### Request Example
```sql
select vectorize.table(
    job_name    => 'product_search',
    relation    => 'products',
    primary_key => 'product_id',
    columns     => ARRAY['product_name', 'description'],
    transformer =>  'openai/text-embedding-ada-002',
    args        => '{"api_key": "my-openai-key"}'
);
```

### Response
#### Success Response (200)
- **result** (text) - A confirmation message indicating the table initialization status.
```

--------------------------------

### Set OpenAI API Key

Source: https://github.com/chuckhend/pg_vectorize/blob/main/extension/README.md

Configure the OpenAI API key for the vectorize extension. This is required for using OpenAI's chat-completion models.

```sql
ALTER SYSTEM SET vectorize.openai_key TO '<your api key>';
SELECT pg_reload_conf();
```

--------------------------------

### vectorize.generate()

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Calls a text-generation LLM directly from SQL without a RAG context step.

```APIDOC
## vectorize.generate()

### Description
Calls a text-generation LLM directly from SQL without a RAG context step.

### Method
SQL Function Call

### Parameters
- **input** (string) - Required - The text to generate content from.
- **model** (string) - Required - The LLM model to use (e.g., 'openai/gpt-4o', 'ollama/wizardlm2:7b').

### Request Example
```sql
SELECT vectorize.generate(
    input => 'Tell me the difference between a cat and a dog in 1 sentence',
    model => 'openai/gpt-4o'
);
```

### Response
#### Success Response
- (string) - The generated text from the LLM.
```

--------------------------------

### Initialize Vector Table with OpenAI

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/api/search.md

Initializes a vector table using OpenAI's text-embedding-ada-002 model. The API key can be provided directly in the arguments or set globally via GUC.

```sql
select vectorize.table(
    job_name    => 'product_search',
    relation    => 'products',
    primary_key => 'product_id',
    columns     => ARRAY['product_name', 'description'],
    transformer =>  'openai/text-embedding-ada-002',
    args        => '{"api_key": "my-openai-key"}'
);
```

```sql
ALTER SYSTEM SET vectorize.openai_key TO 'my-openai-key';
SELECT pg_reload_conf();
```

```sql
select vectorize.table(
    job_name    => 'product_search',
    relation    => 'products',
    primary_key => 'product_id',
    columns     => ARRAY['product_name', 'description'],
    transformer =>  'openai/text-embedding-ada-002'
);
```

--------------------------------

### Perform a Basic Search

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/api/search.md

Executes a vector similarity search using the `search` function. Specify the job name, query string, desired return columns, and the number of results.

```sql
SELECT * FROM vectorize.search(
    job_name        => 'product_search',
    query           => 'mobile electronic devices',
    return_columns  => ARRAY['product_id', 'product_name'],
    num_results     => 3
);
```

--------------------------------

### Create Index for Search Filtering

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Create a partial index to speed up frequent where_sql conditions in vectorize.search().

```sql
CREATE INDEX idx_product_electronics ON products (product_name)
WHERE product_category = 'electronics';
```

--------------------------------

### Show Embedding Service URL

Source: https://github.com/chuckhend/pg_vectorize/blob/main/docs/extension/examples/sentence_transformers.md

Displays the current configuration for the embedding service URL. Ensure this is set correctly for your vector-serve container.

```sql
SHOW vectorize.embedding_service_url;
```

--------------------------------

### Perform Retrieval-Augmented Generation with vectorize.rag()

Source: https://context7.com/chuckhend/pg_vectorize/llms.txt

Use vectorize.rag() to retrieve context documents and pass them to an LLM for generation. Returns both context and the generated answer. You can extract only the chat response using '-> 'chat_response''.

```sql
ALTER TABLE products
ADD COLUMN context TEXT GENERATED ALWAYS AS (product_name || ': ' || description) STORED;
```

```sql
SELECT vectorize.table(
    job_name    => 'product_chat',
    relation    => 'products',
    primary_key => 'product_id',
    columns     => ARRAY['context'],
    transformer => 'openai/text-embedding-3-small',
    schedule    => 'realtime'
);
```

```sql
ALTER SYSTEM SET vectorize.openai_key TO 'sk-...';
SELECT pg_reload_conf();
```

```sql
SELECT vectorize.rag(
    job_name    => 'product_chat',
    query       => 'What is a pencil?',
    chat_model  => 'openai/gpt-3.5-turbo'
);
```

```sql
SELECT vectorize.rag(
    job_name    => 'product_chat',
    query       => 'What is a pencil?',
    chat_model  => 'openai/gpt-3.5-turbo'
) -> 'chat_response';
```

```sql
ALTER SYSTEM SET vectorize.ollama_service_url TO 'http://localhost:3001';
SELECT pg_reload_conf();
```

```sql
SELECT vectorize.rag(
    job_name    => 'product_chat',
    query       => 'What is a pencil?',
    chat_model  => 'ollama/wizardlm2:7b'
) -> 'chat_response';
```

```sql
SELECT vectorize.rag(
    job_name    => 'product_chat',
    query       => 'What items are good for outdoor camping?',
    chat_model  => 'openai/gpt-3.5-turbo',
    num_context => 5,
    force_trim  => true
) -> 'chat_response';
```