The `google_ml_integration` extension in AlloyDB for PostgreSQL lets you generate
text embeddings directly in SQL by using functions in the `public` and
`google_ml` schemas. You can call the `embedding()` function in the `public`
schema with any Gemini Enterprise Agent Platform embedding model
without registering an endpoint. To pass custom parameters such as task types
or use third-party models,
[register the model endpoint](https://docs.cloud.google.com/alloydb/docs/ai/register-model-endpoint.md.txt) and
call the `google_ml.embedding()` function in the `google_ml` schema.

## How embeddings work

Imagine a database running on AlloyDB with the following characteristics:

- The database contains a table, `items`. Each row in this table describes an
  item that your business sells.

- The `items` table contains a column, `complaints`. This `TEXT` column stores
  buyer complaints logged about each item.

- The database integrates with the
  Model Garden, giving it access to the `gemini-embedding-001` English
  models.

Even though this database stores complaints about items, these complaints are
stored as plain text, making them difficult to query. For example,
to see which items have the most complaints from customers who received the
wrong color of merchandise, then you can perform ordinary SQL queries on the
table, that look for various keyword matches. However, this approach only matches
rows that contain those exact keywords.

For example, a basic SQL query such as `SELECT * FROM item WHERE complaints LIKE
"%wrong color%"` doesn't return a row whose `complaints` field contains only
`The picture shows a blue one, but the one I received was red`.

SQL queries using LLM-powered embeddings can help return semantically similar responses for such queries. By
applying embeddings, you can query the table in this example for items whose
complaints have semantic similarity to a given text prompt, such as `It was the
wrong color`.

> [!NOTE]
> **Note:** When monitoring your usage and quotas in the Google Cloud console, remember that the model names might differ from the ones used in the documentation.
>
> - For the `text-embedding-005` model, the `base_model` dimension in the Google Cloud console is `textembedding-gecko`.
>
>   The relevant quota is `Regional online prediction requests per base model per minute per region per base_model`.
> - For the `gemini-embedding-001` model, the `base_model` dimension is `gemini-embedding`.
>
>   The relevant quotas are `Embed content input tokens per minute per region per base_model` and `Regional online prediction requests per base model per minute per region per base_model`.

For basic embedding generation, select one of the following schemas.
<button value="google_ml" default="">google_ml schema</button> <button value="public">public schema</button>

> [!NOTE]
> **Note:** AlloyDB doesn't charge for AI function calls. However, when you call Gemini Enterprise Agent Platform, third-party, or self-hosted models and services (such as for hybrid search) from your database, the model or infrastructure provider charges you directly. For more information about Gemini Enterprise Agent Platform costs, see [Pricing](https://cloud.google.com/products/gemini-enterprise-agent-platform/pricing).

## Before you begin

To let AlloyDB generate embeddings, do the following:

- [Connect to your database using `psql`](https://docs.cloud.google.com/alloydb/docs/connect-psql.md.txt) or AlloyDB Studio as the `postgres` user.

- [Verify that the `google_ml_integration` extension is installed](https://docs.cloud.google.com/alloydb/docs/ai/configure-vertex-ai.md.txt#verify-installed-extension).

  To check your extension version with the following command:

  ```sql
  SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
  ```

  If you need to update the extension, use the `ALTER EXTENSION google_ml_integration UPDATE;` command.

  > [!NOTE]
  > **Note:** If you don't have the necessary permissions, contact your database administrator to perform the update. Alternatively, you can wait for the new version to be automatically rolled out to your cluster.

- Before you can generate embeddings from an AlloyDB database, you must configure AlloyDB to work with Agent Platform. For more information, see [Integrate your database with Agent Platform](https://docs.cloud.google.com/alloydb/docs/ai/configure-vertex-ai.md.txt).

- Grant permissions to database users to generate embeddings.

  If you use `psql`, connect to the database that you want to grant permissions
  to:

  ```sql
  \c DB_NAME
  GRANT EXECUTE ON FUNCTION embedding TO "USER_NAME";
  ```

  Replace the following:
  - `DB_NAME`: the name of the database that you want to grant
    permissions to.

  - `USER_NAME`: the name of the user that you want to grant
    permissions to.

  If you use AlloyDB Studio, select the name of the database that
  you want to grant permissions to in the **Database** list. Grant the `EXECUTE`
  permission on the `google_ml.embedding` function to the user:

  ```sql
  GRANT EXECUTE ON FUNCTION google_ml.embedding TO "USER_NAME";
  ```

  Replace `USER_NAME` with the name of the user to whom you
  want to grant permissions.

## Generate embeddings

Use the `google_ml.embedding()` SQL function to call text embedding models.

To call the model and generate embeddings, run the following query:

```sql
SELECT
 google_ml.embedding(
   model_id => 'MODEL_ID',
   content => 'CONTENT');
```

Replace the following:

- `MODEL_ID`: the qualified model ID-for example, `gemini-embedding-001`.

- `CONTENT`: the text to translate into a vector embedding.

> [!NOTE]
> **Note:** If you want to generate and manage vector embeddings for a large table column, you can use auto vector embeddings. For more information, see [Generate and manage auto vector embeddings for large tables](https://docs.cloud.google.com/alloydb/docs/ai/generate-manage-auto-embeddings-for-tables.md.txt).

## Examples for generating embeddings

Some examples for generating embeddings using registered model endpoint are listed in this section.

### Gemini embedding models

To generate embeddings for a registered `gemini-embedding-001` model endpoint, run the following statement:

> [!NOTE]
> **Note:** Agent Platform model support is governed by [Agent Platform model versioning, regional availability, and lifecycle](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/model-versions.md.txt) guidelines. Verify that the model you're trying is available in the region where your AlloyDB cluster is created.

```sql
   SELECT
     google_ml.embedding(
       model_id => 'gemini-embedding-001',
       content => 'AlloyDB is a managed, cloud-hosted SQL database service');
```

If your AlloyDB cluster and the Gemini Enterprise Agent Platform endpoint are
in different projects, follow these steps:

1. Run the following `CALL` statement.

   > [!NOTE]
   > **Note:** If your `google_ml_integration` extension is version 1.5.3 or later, then you don't need to use `model_in_transform_fn` and `model_out_transform_fn` for `gemini-embedding-001`.

   ```sql
      CALL
        google_ml.create_model(
          model_id => 'gemini-embedding-001',
          model_request_url => 'https://REGION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/gemini-embedding-001:predict',
          model_provider => 'google',
          model_type => 'text_embedding',
          model_auth_type => 'alloydb_service_agent_iam',
          model_in_transform_fn => 'google_ml.vertexai_text_embedding_input_transform',
          model_out_transform_fn => 'google_ml.vertexai_text_embedding_output_transform'
        );
   ```
2. To generate embeddings for a registered `gemini-embedding-001` model endpoint, run the following statement:

   ```sql
     SELECT
       google_ml.embedding(
         model_id => 'gemini-embedding-001',
         content => 'AlloyDB is a managed, cloud-hosted SQL database service');
   ```

### OpenAI embedding model

To generate embeddings for a [registered `text-embedding-ada-002` model endpoint](https://docs.cloud.google.com/alloydb/docs/ai/register-model-endpoint.md.txt#add-openai) by OpenAI, run the following statement:

```sql
   SELECT
     google_ml.embedding(
       model_id => 'text-embedding-ada-002',
       content => 'e-mail spam');
```

To generate embeddings for a registered `text-embedding-3-small` or `text-embedding-3-large` model endpoints by OpenAI, run the following statement:

```sql
 SELECT
   google_ml.embedding(
     model_id => 'text-embedding-3-small',
     content => 'Vector embeddings in AI');
```

## What's next

- [Run vector similarity searches](https://docs.cloud.google.com/alloydb/docs/ai/run-vector-similarity-search.md.txt).

- [Learn how to build a smart shopping assistant with AlloyDB, pgvector, and model endpoint management](https://codelabs.developers.google.com/smart-shop-agent-alloydb#0).

- [Create indexes and query vectors](https://docs.cloud.google.com/alloydb/docs/ai/create-scann-index.md.txt).

- [Perform a vector search](https://docs.cloud.google.com/alloydb/docs/ai/perform-vector-search.md.txt).

- Learn about the [model endpoint management reference](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt).