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.

Embed is currently an internal Plot Plugin. Its SQL and materialization contracts may change before it is included in customer documentation.

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

Embed text

Only input is required. Omitted model coordinates use the Workspace’s configured default, 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; defaults to `vertex`.
`purpose`	Optional	Defaults to `document`.

The output dimensions come from the configured model identity. They are not a call-site argument. With the built-in defaults, the return type is a nullable, unit-normalized FixedSizeList<Float32, 768>. NULL or empty input returns NULL. If a provider batch fails, the affected cells become NULL and the rest of the query continues.

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

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.

Keep vector identities compatible

Vectors are comparable only when they share provider, name, version, dimensions, and normalization. server controls routing and does not change vector identity. When a Plot materializes an embed() column, the Plot table exposes the vector and Parable creates a Lance sibling for approximate nearest-neighbor search:

parables.{parable_slug}.{plot_slug}__{column}

The sibling and its Plot table share _plot_row_id. See the Parable Pool for the canonical table addressing model.

Execution and limits

Interactive queries batch inputs and cap concurrent provider requests. Scheduled Plot runs pin model identity and purpose, account successful embedding work, and persist vectors with their model metadata. The service rejects calls above its configured row cap. Model and purpose must be constant for the invocation, while input varies by row. 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