Vane Data / Reference

vane.ai.embed

vane.ai.embed creates a row-preserving text embedding operation. It returns a fixed-size FLOAT[n] Expression, or a Relation with an appended embedding column when a Relation is supplied.

Signatures

example.py

vane.ai.embed(
    text: Expression,
    /,
    *,
    provider: str | Provider = "openai",
    model: str | None = None,
    dimensions: int | None = None,
    on_error: Literal["raise", "ignore"] = "raise",
    **options: Unpack[EmbedOptions],
) -> Expression


vane.ai.embed(
    rel: Relation,
    /,
    text: Expression,
    *,
    provider: str | Provider = "openai",
    model: str | None = None,
    dimensions: int | None = None,
    on_error: Literal["raise", "ignore"] = "raise",
    output_column: str = "embedding",
    **options: Unpack[EmbedOptions],
) -> Relation

Equivalent keyword-only forms are also supported. A Relation has the convenience method rel.embed(text, ...).

Parameters

Name	Type	Description	Default
text	Expression	Text input. The Expression must return VARCHAR	Required
provider	Registered provider name or Provider	Embedding provider adapter	"openai"
model	Non-empty str or None	Model ID. None uses provider metadata or a provider default	None
dimensions	Positive int or None	Fixed result width and, where supported, requested output width	None
on_error	"raise" or "ignore"	Row execution failure policy	"raise"
output_column	Non-empty str	Relation-only output name	"embedding"
**options	EmbedOptions	Provider request and execution options listed below	Provider-specific

Expression calls do not accept output_column; use .alias(...). Relation calls keep all input columns and replace an existing output column with the same case-insensitive name.

Options

Option	Type	Availability	Default	Description
normalize	bool	All	False	L2-normalize every non-NULL, non-zero final vector; leave zero vectors unchanged
batch_size	Positive int	All	64	Rows submitted in an execution batch
actor_number	Positive int	All	1	Embedder actor count
max_retries	Non-negative int	All	3	Retries after the first attempt
execution_backend	Backend name or None	Relation only	Runner choice	subprocess_task, subprocess_actor, ray_task, or ray_actor
max_chunk_chars	Positive int or None	Relation only	None	Split long text into character windows
chunk_overlap_chars	Non-negative int	Relation only	200	Window overlap; requires and must be smaller than max_chunk_chars

actor_number cannot be combined with a task backend. SQL and Expression calls do not accept the Relation-only backend and character-chunking options.

Provider request options:

Provider	Option	Type and rules
OpenAI	encoding_format	'float' or 'base64'; default 'float'
OpenAI	base_url, timeout	HTTP(S) endpoint or None; finite positive timeout or None
OpenAI	batch_token_limit	Positive int controlling client-side request batching
OpenAI	input_text_token_limit	Positive int or None; cannot be combined with max_chunk_chars
Google	task_type	Supported Gemini embedding task string or None
Google	title	Non-empty str or None; valid only with task_type='RETRIEVAL_DOCUMENT'
Transformers	cache_folder, device, revision	Non-empty str or None
Transformers	local_files_only	bool
Transformers	trust_remote_code	bool; True requires revision as a full 40-character commit SHA

Supported Google task_type values are RETRIEVAL_QUERY, RETRIEVAL_DOCUMENT, SEMANTIC_SIMILARITY, CLASSIFICATION, CLUSTERING, QUESTION_ANSWERING, FACT_VERIFICATION, and CODE_RETRIEVAL_QUERY. The default gemini-embedding-2 model accepts neither task_type nor title; select another Google embedding model before using either option.

Dimensions and result validation

Vane must know dimensions before the query runs. It uses an explicit value first, then built-in metadata for known models or metadata from a custom Provider. Vane does not load a model or contact an endpoint to discover the size. Pass dimensions=... for unknown models and compatible endpoints.

Every non-NULL provider result must be a finite, one-dimensional vector of exactly the expected width. Provider batches must return the same number of embeddings in input order. Vane validates the count and vector shape, but it cannot detect an equal-length batch that a custom Provider has reordered. A custom Provider is responsible for preserving order.

Example

This example uses the Transformers provider. Install vane-ai[transformers] before running it.

example.py

import vane


documents = vane.sql(
    "SELECT * FROM (VALUES (1, 'How do I reset my password?'), "
    "(2, 'Where can I update my billing address?')) AS t(id, text)"
)


embedded = vane.ai.embed(
    documents,
    vane.col("text"),
    provider="transformers",
    model="sentence-transformers/all-MiniLM-L6-v2",
)


print(embedded.select("id, text, len(embedding)").order("id").fetchall())
vane.close()

Output:

text

[(1, 'How do I reset my password?', 384),
 (2, 'Where can I update my billing address?', 384)]

Relation-only text chunking

Set max_chunk_chars on a Relation call to split long text into overlapping character windows. chunk_overlap_chars defaults to 200 and must be smaller than the chunk size. Vane embeds the chunks and computes a chunk-length-weighted mean. A non-zero mean is L2-normalized, while a zero vector remains unchanged. normalize=True applies the same rule to final vectors produced without multi-chunk aggregation.

max_chunk_chars and chunk_overlap_chars are unavailable on Expression and SQL calls. For every API form, OpenAI still splits oversized inputs by token count using the configured input_text_token_limit or Vane's built-in limit. On Relation calls, max_chunk_chars and input_text_token_limit are mutually exclusive.

Errors

Invalid input types, unresolved dimensions, unsupported providers, and invalid options raise before the query runs. Provider failures and invalid returned vectors raise during execution. on_error="ignore" converts only row execution failures to NULL while preserving the vector type.

A NULL input returns NULL with the resolved vector type without calling the provider. Transient failures are retried three times by default. With on_error="ignore", a failed batch is isolated into individual rows so successful rows are retained. A ProviderCapabilityError returns NULL for the affected batch without resubmitting the request; configuration errors still raise.

Edit this page