Inverted File Flat (`IVFFlat`) indexes in AlloyDB for PostgreSQL let you accelerate
vector similarity searches over stored embeddings while minimizing index build
time and memory usage. You can create `IVFFlat` indexes by using the `vector`
extension and query your indexed embeddings. For more information about storing
embeddings, see [Store vector embeddings](https://docs.cloud.google.com/alloydb/docs/ai/store-embeddings.md.txt).

> [!NOTE]
> **Note:** Before you create an index, verify that you add embedding vectors to a table in your AlloyDB database.

## Before you begin

Before you can start creating indexes, you must complete the following
prerequisites.

- [Embedding vectors are added to a table](https://docs.cloud.google.com/alloydb/docs/ai/store-embeddings.md.txt) in your
  AlloyDB database.

- The `vector` extension version `0.5.0` or later that is based on `pgvector`, extended by Google for
  AlloyDB is installed.

  ```sql
  CREATE EXTENSION IF NOT EXISTS vector;
  ```

  <br />

## Create an `IVFFlat` index

Stock `pgvector` also provides a version of the `IVF` index named
[`IVFFlat`](https://github.com/pgvector/pgvector?tab=readme-ov-file#ivfflat)
that provides faster build time and has a smaller memory footprint as
compared to the `hnsw` index.

To create an `IVFFlat` index, complete the following steps:

<br />

```sql
CREATE INDEX INDEX_NAME ON TABLE
  USING ivfflat (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (lists = LIST_COUNT);
```

Replace the following:

- `INDEX_NAME`: the name of the index you want to
  create---for example, `my-ivf-index`.

- `TABLE`: the table to add the index to.

- `EMBEDDING_COLUMN`: a column that stores `vector`
  data.

- `DISTANCE_FUNCTION`: the distance function to use
  with this index. Choose one of the following:

  - **L2 distance:** `vector_l2_ops`

  - **Inner product:** `vector_ip_ops`

  - **Cosine distance:** `vector_cosine_ops`

- `LIST_COUNT`: the number of lists to use with this
  index. For more information about how to decide this value, see [Tune an IVFFlat index](https://docs.cloud.google.com/alloydb/docs/ai/tune-indexes.md.txt).

  To create this index on an embedding column that uses the `real[]` data
  type instead of `vector`, cast the column into the `vector` data type:

<br />

```sql
CREATE INDEX INDEX_NAME ON TABLE
  USING ivfflat ((CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS))) DISTANCE_FUNCTION)
  WITH (lists = LIST_COUNT);
```

Replace `DIMENSIONS` with the dimensional width of the
embedding column. For more information about how to find the dimensions,
see the `vector_dims` function in [Vector
functions](https://github.com/pgvector/pgvector?tab=readme-ov-file#vector-functions).

To view the indexing progress, use the `pg_stat_progress_create_index` view:

```sql
SELECT * FROM pg_stat_progress_create_index;
```

The `phase` column shows the current state of your index creation.

To tune your index for a target recall and QPS balance, see [Tune an
`IVFFlat` index](https://docs.cloud.google.com/alloydb/docs/ai/tune-indexes).

## Run a query

After you store and index the embeddings in your database, you can start
querying using the [`pgvector` query functionality](https://github.com/pgvector/pgvector#querying).

To find the nearest semantic neighbors for an embedding vector, you can run the
following example query, where you set the same distance function that you used
during the index creation.

```sql
  SELECT * FROM TABLE
    ORDER BY EMBEDDING_COLUMN DISTANCE_FUNCTION_QUERY 'EMBEDDING'
    LIMIT ROW_COUNT;
```

<br />

Replace the following:

- `TABLE`: the table containing the embedding to compare the
  text to.

- `EMBEDDING_COLUMN`: the column containing the stored
  embeddings.

- `DISTANCE_FUNCTION_QUERY`: the distance function to use with this
  query. Choose one of the following based on the distance function used
  while creating the index:

  - **L2 distance:** `<->`

  - **Inner product:** `<#>`

  - **Cosine distance:** `<=>`

- `EMBEDDING`: the embedding vector you want to find the nearest stored
  semantic neighbors of.

- `ROW_COUNT`: the number of rows to return.

  Specify `1` if you want only the single best match.

For more information about other query examples, see
[Querying](https://github.com/pgvector/pgvector?tab=readme-ov-file#querying).

You can also use the [`embedding()`](https://docs.cloud.google.com/alloydb/docs/ai/work-with-embeddings.md.txt) function to translate the
text into a vector. You apply the vector to one of the
`pgvector` nearest-neighbor operators, `<->` for L2 distance, to find the database rows with the
most semantically similar embeddings.

Because `embedding()` returns a `real` array, you must explicitly cast the
`embedding()` call to `vector` in order to use these values with `pgvector`
operators.

## What's next

- [Create a ScaNN index](https://docs.cloud.google.com/alloydb/docs/ai/create-scann-index.md.txt#before-you-begin)
- [Run vector similarity searches](https://docs.cloud.google.com/alloydb/docs/ai/run-vector-similarity-search.md.txt)
- [Tune vector query performance](https://docs.cloud.google.com/alloydb/docs/ai/tune-indexes.md.txt)
- [Vector index metrics](https://docs.cloud.google.com/alloydb/docs/reference/vector-index-metrics.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).