> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parable.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed

> Use the first-party Embed Plot Plugin to create comparable text vectors from SQL.

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.

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

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

## Embed text

Only `input` is required. Omitted model coordinates use the Workspace's
configured default, and `purpose` defaults to `document`.

```sql Embed issue titles theme={null}
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.

```sql Embed a search query theme={null}
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:

```text theme={null}
parables.{parable_slug}.{plot_slug}__{column}
```

The sibling and its Plot table share `_plot_row_id`. See the
[Parable Pool](/protocols/sql/data-catalog/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](/protocols/sql/query-with-sdks).