forked from supabase/supabase
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
13 changed files
with
207 additions
and
49 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,43 @@ | ||
import Layout from '~/layouts/DefaultGuideLayout' | ||
|
||
export const meta = { | ||
id: 'ai-vector-indexes', | ||
title: 'Vector indexes', | ||
description: 'Understanding vector indexes', | ||
sidebar_label: 'Vector indexes', | ||
} | ||
|
||
Once your vector table starts to grow, you will likely want to add an index to speed up queries. Without indexes, you'll be performing a sequential scan which can be a resource-intensive operation when you have many records. | ||
|
||
## Choosing an index | ||
|
||
Today `pgvector` supports two types of indexes: | ||
|
||
- [HNSW](/docs/guides/ai/vector-indexes/hnsw-indexes) | ||
- [IVFFlat](/docs/guides/ai/vector-indexes/ivf-indexes) | ||
|
||
In general we recommend using [HNSW](/docs/guides/ai/vector-indexes/hnsw-indexes) because of its [performance gain](/blog/increase-performance-pgvector-hnsw#hnsw-performance-1536-dimensions) and [robustness against changing data](/docs/guides/ai/vector-indexes/hnsw-indexes#when-should-you-create-hnsw-indexes). | ||
|
||
## Distance operators | ||
|
||
The type of index required depends on the distance operator you are using. `pgvector` includes 3 distance operators: | ||
|
||
| Operator | Description | [**Operator class**](https://www.postgresql.org/docs/current/sql-createopclass.html) | | ||
| -------- | ---------------------- | ------------------------------------------------------------------------------------ | | ||
| `<->` | Euclidean distance | `vector_l2_ops` | | ||
| `<#>` | negative inner product | `vector_ip_ops` | | ||
| `<=>` | cosine distance | `vector_cosine_ops` | | ||
|
||
Use the following SQL commands to create an index for the operator(s) used in your queries. | ||
|
||
Currently vectors with up to 2,000 dimensions can be indexed. | ||
|
||
If you are using the `vecs` Python library, follow the instructions in [Managing collections](/docs/guides/ai/managing-collections#create-an-index) to create indexes. | ||
|
||
## Resources | ||
|
||
Read more about indexing on `pgvector`'s [GitHub page](https://github.com/pgvector/pgvector#indexing). | ||
|
||
export const Page = ({ children }) => <Layout meta={meta} children={children} /> | ||
|
||
export default Page |
101 changes: 101 additions & 0 deletions
101
apps/docs/pages/guides/ai/vector-indexes/hnsw-indexes.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,101 @@ | ||
import Layout from '~/layouts/DefaultGuideLayout' | ||
|
||
export const meta = { | ||
id: 'ai-hnsw-indexes', | ||
title: 'HNSW indexes', | ||
description: 'Understanding HNSW indexes in pgvector', | ||
sidebar_label: 'HNSW indexes', | ||
} | ||
|
||
HNSW is a type of vector index for approximate nearest neighbor search, used in high-dimensional spaces like those found in embeddings. | ||
|
||
## Usage | ||
|
||
The way you create an HNSW index depends on the distance operator you are using. `pgvector` includes 3 distance operators: | ||
|
||
| Operator | Description | [**Operator class**](https://www.postgresql.org/docs/current/sql-createopclass.html) | | ||
| -------- | ---------------------- | ------------------------------------------------------------------------------------ | | ||
| `<->` | Euclidean distance | `vector_l2_ops` | | ||
| `<#>` | negative inner product | `vector_ip_ops` | | ||
| `<=>` | cosine distance | `vector_cosine_ops` | | ||
|
||
Use the following SQL commands to create an HNSW index for the operator(s) used in your queries. | ||
|
||
### Euclidean L2 distance (`vector_l2_ops`) | ||
|
||
```sql | ||
create index on items using hnsw (column_name vector_l2_ops); | ||
``` | ||
|
||
### Inner product (`vector_ip_ops`) | ||
|
||
```sql | ||
create index on items using hnsw (column_name vector_ip_ops); | ||
``` | ||
|
||
### Cosine distance (`vector_cosine_ops`) | ||
|
||
```sql | ||
create index on items using hnsw (column_name vector_cosine_ops); | ||
``` | ||
|
||
Currently vectors with up to 2,000 dimensions can be indexed. | ||
|
||
If you are using the `vecs` Python library, follow the instructions in [Managing collections](/docs/guides/ai/managing-collections#create-an-index) to create indexes. | ||
|
||
## How does HNSW work? | ||
|
||
HNSW uses proximity graphs (graphs connecting nodes based on distance between them) to approximate nearest-neighbor search. To understand HNSW, we can break it down into 2 parts: | ||
|
||
- **Hierarchical (H):** The algorithm operates over multiple layers | ||
- **Navigable Small World (NSW):** Each vector is a node within a graph and is connected to several other nodes | ||
|
||
### Hierarchical | ||
|
||
The hierarchical aspect of HNSW builds off of the idea of skip lists. | ||
|
||
Skip lists are multi-layer linked lists. The bottom layer is a regular linked list connecting an ordered sequence of elements. Each new layer above removes some elements from the underlying layer (based on a fixed probability), producing a sparser subsequence that “skips” over elements. | ||
|
||
<div> | ||
<img | ||
alt="visual of an example skip list (light)" | ||
className="dark:hidden" | ||
src="/docs/img/ai/vector-indexes/hnsw-indexes/skip-list--light.png" | ||
/> | ||
<img | ||
alt="visual of an example skip list (dark)" | ||
className="hidden dark:block" | ||
src="/docs/img/ai/vector-indexes/hnsw-indexes/skip-list--dark.png" | ||
/> | ||
</div> | ||
|
||
When searching for an element, the algorithm begins at the top layer and traverses its linked list horizontally. If the target element is found, the algorithm stops and returns it. Otherwise if the next element in the list is greater than the target (or NIL), the algorithm drops down to the next layer below. Since each layer below is less sparse than the layer above (with the bottom layer connecting all elements), the target will eventually be found. Skip lists offer O(log n) average complexity for both search and insertion/deletion. | ||
|
||
### Navigable Small World | ||
|
||
A navigable small world (NSW) is a special type of proximity graph that also includes long-range connections between nodes. These long-range connections support the “small world” property of the graph, meaning almost every node can be reached from any other node within a few hops. Without these additional long-range connections, many hops would be required to reach a far-away node. | ||
|
||
<img | ||
alt="visual of an example navigable small world graph" | ||
src="/docs/img/ai/vector-indexes/hnsw-indexes/nsw.png" | ||
/> | ||
|
||
The “navigable” part of NSW specifically refers to the ability to logarithmically scale the greedy search algorithm on the graph, an algorithm that attempts to make only the locally optimal choice at each hop. Without this property, the graph may still be considered a small world with short paths between far-away nodes, but the greedy algorithm tends to miss them. Greedy search is ideal for NSW because it is quick to navigate and has low computational costs. | ||
|
||
### **Hierarchical +** Navigable Small World | ||
|
||
HNSW combines these two concepts. From the hierarchical perspective, the bottom layer consists of a NSW made up of short links between nodes. Each layer above “skips” elements and creates longer links between nodes further away from each other. | ||
|
||
Just like skip lists, search starts at the top layer and works its way down until it finds the target element. However instead of comparing a scalar value at each layer to determine whether or not to descend to the layer below, a multi-dimensional distance measure (such as Euclidean distance) is used. | ||
|
||
## When should you create HNSW indexes? | ||
|
||
Unlike IVFFlat indexes, you are safe to build an HNSW index immediately after the table is created. HNSW indexes are based on graphs which inherently are not affected by the same limitations as IVFFlat. As new data is added to the table, the index will be filled automatically and the index structure will remain optimal. | ||
|
||
## Resources | ||
|
||
Read more about indexing on `pgvector`'s [GitHub page](https://github.com/pgvector/pgvector#indexing). | ||
|
||
export const Page = ({ children }) => <Layout meta={meta} children={children} /> | ||
|
||
export default Page |
95 changes: 52 additions & 43 deletions
95
...docs/pages/guides/ai/managing-indexes.mdx → .../guides/ai/vector-indexes/ivf-indexes.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+16.7 KB
apps/docs/public/img/ai/vector-indexes/hnsw-indexes/skip-list--dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+16.6 KB
apps/docs/public/img/ai/vector-indexes/hnsw-indexes/skip-list--light.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters