Embed - Parable

Embed is a first-party Plot Plugin that turns text into unit-normalized vectors. Use it to prepare Plot data for retrieval, similarity, classification, and clustering workflows.

Embedding consumes an external model service. Filter invalid input and keep a LIMIT while developing, then set budgets on Pipelines.

Embed text

Only input is required. Omitted model coordinates use the platform’s default embedding model, and purpose defaults to document.

Embed issue titles

SELECT
  id,
  title,
  embed(input => title) AS vec
FROM providers.linear.issues
WHERE title IS NOT NULL
LIMIT 50

Named arguments use => and cannot be mixed with positional arguments.

Argument	Requirement	Meaning
`input`	Required	A `Utf8` or `LargeUtf8` expression evaluated for each row.
`provider`	Optional	Defaults to `google`.
`name`	Optional	Defaults to `gemini-embedding`.
`version`	Optional	Defaults to `001`.
`server`	Optional	Routing coordinate: `vertex` or `openrouter`. Defaults to `vertex`.
`purpose`	Optional	Defaults to `document`.

The defaults are the platform’s default embedding model in the Workspace’s AI policy. Embedding models are platform-wide: a Workspace sets no default for embed(). The output dimensions come from that model identity and are not a call-site argument. With the platform default, the return type is a nullable, unit-normalized FixedSizeList<Float32, 768>. server => 'vertex' runs on Vertex, in the Workspace’s own Vertex project when it has one. The Workspace’s AI policy lists the processors embed() may use. Parable allows only vertex. A call the policy refuses, and any call while the Workspace’s policy cannot be read, is refused while the query is planned with QL-MP-001 or QL-MP-002, as for Ponder. NULL or empty input returns NULL. If a provider batch fails, the affected cells become NULL and the rest of the query continues. A call that cannot reach its provider at all fails the query with its cause and returns no vectors. A scheduled run fails with QR-QU-010 and is charged nothing. A call whose inputs are all NULL or empty sends no request, so it still returns NULL vectors. A scheduled run also fails with QR-QU-010 when the provider answers a request with HTTP 401, 403 or 404: credentials it does not accept, a project without access to the model, or a model it does not serve. No retry changes that answer, so the run stops at the first such request instead of retrying every row.

Match the embedding purpose

Use document for stored source text and query for a search phrase.

Embed a search query

SELECT embed(
  provider => 'google',
  name => 'gemini-embedding',
  version => '001',
  server => 'vertex',
  purpose => 'query',
  input => 'issues about billing'
) AS query_vec

Compare each row with one search phrase by giving the phrase its own call. The phrase is a constant input, so it is embedded once, not once per row:

Rank issues by distance from a search phrase

SELECT
  id,
  title,
  array_distance(
    embed(input => title),
    embed(input => 'customer billing problem', purpose => 'query')
  ) AS distance
FROM (
  SELECT id, title
  FROM providers.linear.issues
  WHERE title IS NOT NULL
  LIMIT 200
) AS issues
ORDER BY distance
LIMIT 20

Supported purposes are:

Purpose	Use
`document`	Content that will be searched.
`query`	Search text compared with document vectors.
`similarity`	General semantic comparison.
`classification`	Inputs used as classification features.
`clustering`	Inputs grouped by semantic proximity.

Parable maps these values onto each embedding service’s task vocabulary. A service that does not expose task types receives no service-specific value. Any other purpose, an unknown argument name, or a server other than vertex or openrouter is refused while the query is planned. The query returns gRPC INVALID_ARGUMENT with error code QL-PL-013 (INVALID_FUNCTION_ARGUMENT). The message names the argument and what it must be, never the value you gave.

Keep vector identities compatible

Vectors are comparable only when they share provider, name, variant, version, dimensions, and normalization. server controls routing and does not change vector identity. embed() stamps that identity on its output column. A query that compares vectors from two different models fails while it plans, before any input is embedded, with INVALID_ARGUMENT and error code QL-PL-008 (INCOMPARABLE_EMBEDDING_MODELS). The message names both models. Equal dimensions are not enough:

Refused: two model versions

SELECT array_distance(
  embed(input => 'alpha', version => '001'),
  embed(input => 'alpha', version => '002', purpose => 'query')
) AS distance

The check covers array_distance. A vector without an identity, such as a literal vector, is compared on its dimensions alone. A Pipeline keeps its embed() vectors in its stored output. Parable does not create a separate vector table for them. The Plot records the vector type and the model that wrote the column, so a query reads the column back as a FixedSizeList<Float32> of the model’s dimensions, and the check judges it like any embed() output:

Refused: a Plot column and another model version

SELECT array_distance(
  vec,
  embed(input => 'billing', version => '002', purpose => 'query')
) AS distance
FROM parables.support.issue_vectors

If a query cannot read a Plot’s vector column, run its Report again.

Execution and limits

Interactive queries and Report runs batch inputs, up to 32 texts a request, and cap concurrent provider requests. Vertex reads at most 2,048 tokens of each text and embeds a longer one from its start. Report runs pin model identity and purpose, account successful embedding work, and persist the vectors and the model identity in the Plot’s stored output. embed() is Stable: the same text under the same model and purpose gives the same vector. A query that names the same call twice in one SELECT list sends each text once. A query sends the texts twice when the same call is in both its SELECT and its WHERE. A scheduled run sends each distinct text once wherever the call sits. A constant input, such as a search phrase, is one text. A query sends it once for each batch of rows the engine passes to embed(), at most 128 rows by default, and every row reads its vector. A scheduled run sends it once. A NULL or empty constant returns NULL on every row without a request. The service rejects calls above its configured row cap. Model and purpose must be constant for the invocation; input can vary by row or be constant. Run embed() with the same SDK query method as any other Parable SQL. See Query with the SDKs.

​Embed text

​Match the embedding purpose

​Keep vector identities compatible

​Execution and limits

Embed text

Match the embedding purpose

Keep vector identities compatible

Execution and limits