Vector Search

The vector search endpoint provides typed, read-only pgvector similarity search brokered through the FoundryDB controller. It composes a single SELECT from validated inputs and executes it inside a READ ONLY transaction with a statement timeout and row cap. Your application never needs a direct database connection.

Vector search is available on PostgreSQL services only. The service must be in Running status.

How It Works

You send a POST request with a query vector (or text to embed server-side) and the name of the table and column to search. The controller validates all identifiers and parameters, then routes the query to the service's primary node via the agent. Results are returned synchronously, ordered by ascending distance.

Endpoints

POST /managed-services/{id}/vector-search

Authentication uses the same basic auth credentials as the rest of the platform API.

Request Body

Field	Type	Required	Description
table	string	Yes	Table containing the vector column.
database_name	string	No	Database to query. Defaults to the engine default, or the pipeline's database when query_text is used.
schema	string	No	Schema of the table. Defaults to public.
embedding_column	string	No	Name of the vector column. Defaults to embedding.
vector	float[]	Exactly one of vector or query_text	Query vector (max 8192 dimensions, all components must be finite).
query_text	string	Exactly one of vector or query_text	Text to embed server-side using the referenced pipeline. Requires pipeline_id. Max 8192 characters.
pipeline_id	UUID	When using query_text	Embedding pipeline used to embed the text. Must belong to this service.
top_k	integer	No	Number of rows to return. Range 1-100. Defaults to 10.
metric	string	No	Distance metric: cosine (default), l2, or ip.
filters	array	No	Equality filters ANDed into the WHERE clause. Max 32 filters.
include_columns	string[]	No	Columns to return. Defaults to all columns. Max 100.

Filters

Each filter object requires:

{ "column": "category", "op": "eq", "value": "security" }

Only equality (eq) is supported. Values can be string, number, or boolean.

Distance Metrics

Value	pgvector Operator	Use When
cosine	<=>	Normalized embeddings, semantic similarity (most common).
l2	<->	Euclidean distance, un-normalized vectors.
ip	<#>	Inner product (negated), max-margin retrieval.

Response

{
  "columns": [
    { "name": "id", "type": "int8" },
    { "name": "content", "type": "text" },
    { "name": "distance", "type": "float8" }
  ],
  "rows": [
    [42, "PostgreSQL supports TLS for all client connections.", 0.031]
  ],
  "row_count": 1,
  "truncated": false,
  "execution_ms": 4,
  "metric": "cosine",
  "top_k": 10
}

A distance column is always appended to the selected columns. truncated is true if a row or byte cap cut the result short.

Example: Query with a Pre-Computed Vector

curl -u $USER:$PASS \
  -X POST https://api.foundrydb.com/managed-services/$SERVICE_ID/vector-search \
  -H "Content-Type: application/json" \
  -d '{
    "table": "articles_embeddings",
    "embedding_column": "embedding",
    "vector": [0.021, -0.134, 0.007],
    "top_k": 5,
    "metric": "cosine",
    "include_columns": ["source_row_id", "text_content"],
    "filters": [
      { "column": "category", "op": "eq", "value": "security" }
    ]
  }'

Example: Query with Text (Server-Side Embedding)

When you provide query_text instead of vector, the controller embeds the text using the referenced pipeline's model and dimensions before running the search. This keeps embedding logic out of your application.

curl -u $USER:$PASS \
  -X POST https://api.foundrydb.com/managed-services/$SERVICE_ID/vector-search \
  -H "Content-Type: application/json" \
  -d '{
    "table": "articles_embeddings",
    "query_text": "how to secure a database connection",
    "pipeline_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "top_k": 5
  }'

The pipeline_id must belong to this service. The embedding is produced using the same provider, model, and dimensions that created the indexed vectors, so distances are comparable.

Setting Up Your Table

The vector column must be created with the pgvector extension. An HNSW index on the column is strongly recommended for production use:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE articles_embeddings (
    source_row_id BIGINT PRIMARY KEY,
    text_content  TEXT,
    category      TEXT,
    embedding     vector(1536)
);

CREATE INDEX ON articles_embeddings
    USING hnsw (embedding vector_cosine_ops)
    WITH (m = 16, ef_construction = 64);

Error Codes

HTTP Status	Meaning
400	Invalid request: wrong service type, missing table, unsupported metric, bad identifier, vector dimension mismatch, filter error, or embedding failure.
401	Authentication required.
404	Service not found, no VM instances, or referenced pipeline not found.
500	Storage, encryption, or token-metering failure.

What's Next

• Embedding Pipelines — automate the creation of vectors in your tables.
• Inference Proxy — call embedding models without hard-coding provider keys.