Vector Tables

Vector tables link a source database table to its vector representation, defining which columns to embed and how to store the results.

Create Vector Table

POST /v1/vector-tables

Request Body:

Field	Type	Required	Description
name	string	Yes	Vector table name (1-100 chars)
connection_id	string	Yes	Source database connection
embedding_provider_id	string	Conditional	Required for managed mode and PostgreSQL platform mode
source_table	string	Yes	Source table name in the database
primary_key_column	string	Yes	Primary key column in source table
columns	array	Yes	Column configuration (at least one embedding column)
embedding_model	string	Yes	Embedding model name
embedding_dimensions	integer	Yes	Vector dimensions
mode	string	No	managed (default) or platform
sync_mode	string	No	batch (default) or cdc

Column Configuration

Field	Type	Required	Description
name	string	Yes	Column name in source table
role	string	Yes	embedding or metadata
ordinal	integer	No	Order for multi-column embedding concatenation
name_prefix	string	No	Prefix for embedding text (e.g., "title: ")
filter_type	string	Conditional	Required for metadata columns: keyword, integer, float, boolean

Example:

curl -X POST https://api.embedd.to/v1/vector-tables \
  -H "Authorization: Bearer sk_your_key" \
  -H "X-Environment-Id: env_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-search",
    "connection_id": "conn_abc123",
    "embedding_provider_id": "ep_abc123",
    "source_table": "PRODUCTS",
    "primary_key_column": "ID",
    "columns": [
      {"name": "TITLE", "role": "embedding", "ordinal": 1, "name_prefix": "title: "},
      {"name": "DESCRIPTION", "role": "embedding", "ordinal": 2},
      {"name": "CATEGORY", "role": "metadata", "filter_type": "keyword"},
      {"name": "PRICE", "role": "metadata", "filter_type": "float"},
      {"name": "IN_STOCK", "role": "metadata", "filter_type": "boolean"}
    ],
    "embedding_model": "text-embedding-3-small",
    "embedding_dimensions": 1536,
    "mode": "managed",
    "sync_mode": "cdc"
  }'

Response (201):

{
  "id": "vt_abc123",
  "org_id": "org_xyz",
  "environment_id": "env_abc123",
  "connection_id": "conn_abc123",
  "embedding_provider_id": "ep_abc123",
  "name": "product-search",
  "source_table": "PRODUCTS",
  "primary_key_column": "ID",
  "columns": [...],
  "embedding_model": "text-embedding-3-small",
  "embedding_dimensions": 1536,
  "mode": "managed",
  "sync_mode": "cdc",
  "sync_status": "pending",
  "qdrant_collection": "vt_abc12345_product-search",
  "platform_vector_ref": null,
  "total_rows": 0,
  "synced_rows": 0,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z"
}

List Vector Tables

GET /v1/vector-tables

Get Vector Table

GET /v1/vector-tables/{vector_table_id}

Update Vector Table

PUT /v1/vector-tables/{vector_table_id}

Request Body:

Field	Type	Description
name	string	Updated name
columns	array	Updated column configuration
embedding_model	string	New embedding model (triggers re-backfill)
embedding_dimensions	integer	New dimensions (triggers re-backfill)

Changing columns, embedding_model, or embedding_dimensions sets sync_status to pending_rebackfill. The next backfill performs an atomic swap to replace vectors with zero downtime.

Delete Vector Table

DELETE /v1/vector-tables/{vector_table_id}

Deletes the vector table record and cleans up vector storage (Qdrant collection or platform table).

Response: 204 No Content

Trigger Backfill

POST /v1/vector-tables/{vector_table_id}/backfill

Starts an asynchronous backfill that reads all rows from the source table, generates embeddings, and stores vectors.

Returns 409 Conflict if a backfill is already running.

Response (200):

{
  "vector_table_id": "vt_abc123",
  "status": "backfilling",
  "total_rows": 10000,
  "synced_rows": 0
}

Get Source Schema

GET /v1/vector-tables/{vector_table_id}/schema

Returns the column schema of the source table.

Response (200):

{
  "columns": [
    {"name": "ID", "type": "NUMBER", "nullable": false},
    {"name": "TITLE", "type": "VARCHAR", "nullable": false},
    {"name": "DESCRIPTION", "type": "VARCHAR", "nullable": true}
  ]
}