Skip to content

Commit 7ee16e9

Browse files
marcelomendoncasoaresSandPod
marcelomendoncasoares
and
SandPod
authored
docs: Add docs for new Vector type support (#282)
Co-authored-by: Alexander Sandor <[email protected]>
1 parent 232aa76 commit 7ee16e9

File tree

4 files changed

+236
-1
lines changed

4 files changed

+236
-1
lines changed

‎docs/06-concepts/02-models.md

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ fields:
1818
employees: List<Employee>
1919
```
2020
21-
Supported types are [bool](https://api.dart.dev/dart-core/bool-class.html), [int](https://api.dart.dev/dart-core/int-class.html), [double](https://api.dart.dev/dart-core/double-class.html), [String](https://api.dart.dev/dart-core/String-class.html), [Duration](https://api.dart.dev/dart-core/Duration-class.html), [DateTime](https://api.dart.dev/dart-core/DateTime-class.html), [ByteData](https://api.dart.dev/dart-typed_data/ByteData-class.html), [UuidValue](https://pub.dev/documentation/uuid/latest/uuid_value/UuidValue-class.html), [Uri](https://api.dart.dev/dart-core/Uri-class.html), [BigInt](https://api.dart.dev/dart-core/BigInt-class.html) and other serializable [classes](#class), [exceptions](#exception) and [enums](#enum). You can also use [List](https://api.dart.dev/dart-core/List-class.html)s, [Map](https://api.dart.dev/dart-core/Map-class.html)s and [Set](https://api.dart.dev/dart-core/Set-class.html)s of the supported types, just make sure to specify the types. All supported types can also be used inside [Record](https://api.dart.dev/dart-core/Record-class.html)s. Null safety is supported. Once your classes are generated, you can use them as parameters or return types to endpoint methods.
21+
Supported types are [bool](https://api.dart.dev/dart-core/bool-class.html), [int](https://api.dart.dev/dart-core/int-class.html), [double](https://api.dart.dev/dart-core/double-class.html), [String](https://api.dart.dev/dart-core/String-class.html), [Duration](https://api.dart.dev/dart-core/Duration-class.html), [DateTime](https://api.dart.dev/dart-core/DateTime-class.html), [ByteData](https://api.dart.dev/dart-typed_data/ByteData-class.html), [UuidValue](https://pub.dev/documentation/uuid/latest/uuid_value/UuidValue-class.html), [Uri](https://api.dart.dev/dart-core/Uri-class.html), [BigInt](https://api.dart.dev/dart-core/BigInt-class.html), [Vector](#vector-fields) and other serializable [classes](#class), [exceptions](#exception) and [enums](#enum). You can also use [List](https://api.dart.dev/dart-core/List-class.html)s, [Map](https://api.dart.dev/dart-core/Map-class.html)s and [Set](https://api.dart.dev/dart-core/Set-class.html)s of the supported types, just make sure to specify the types. All supported types can also be used inside [Record](https://api.dart.dev/dart-core/Record-class.html)s. Null safety is supported. Once your classes are generated, you can use them as parameters or return types to endpoint methods.
2222
2323
### Limiting visibility of a generated class
2424
@@ -133,6 +133,36 @@ fields:
133133
employees: List<Employee>
134134
```
135135

136+
## Vector fields
137+
138+
The `Vector` type is used for storing high-dimensional vectors, which are specially useful for similarity search operations.
139+
140+
```yaml
141+
class: Document
142+
table: document
143+
fields:
144+
### The category of the document (e.g., article, tutorial).
145+
category: String
146+
147+
### The contents of the document.
148+
content: String
149+
150+
### A vector field for storing document embeddings
151+
embedding: Vector(1536)
152+
```
153+
154+
The number in parentheses specifies the vector dimensions. Common dimensions include:
155+
156+
- 1536 (OpenAI embeddings)
157+
- 768 (many sentence transformers)
158+
- 384 (smaller models)
159+
160+
Vector fields support specialized distance operations for similarity search and filtering. See the [Vector distance operators](database/filter#vector-distance-operators) section for details.
161+
162+
:::info
163+
The usage of Vector fields requires the pgvector PostgreSQL extension to be installed, which comes by default on new Serverpod projects. To upgrade an existing project, see the [Upgrading to pgvector support](../upgrading/upgrade-to-pgvector) guide.
164+
:::
165+
136166
## Generated code
137167

138168
Serverpod generates some convenience methods on the Dart classes.
@@ -365,6 +395,8 @@ fields:
365395
| [**indexes**](database/indexing) | Create indexes on your fields / columns. | ✅ | | |
366396
| [**fields (index)**](database/indexing) | List the fields to create the indexes on. | ✅ | | |
367397
| [**type (index)**](database/indexing) | The type of index to create. | ✅ | | |
398+
| [**parameters (index)**](database/indexing#vector-indexes) | Parameters for specialized index types like HNSW and IVFFLAT vector indexes. | ✅ | | |
399+
| [**distanceFunction (index)**](database/indexing#vector-indexes) | Distance function for vector indexes (l2, innerProduct, cosine, l1). | ✅ | | |
368400
| [**unique**](database/indexing) | Boolean flag to make the entries unique in the database. | ✅ | | |
369401
| [**default**](#default-values) | Sets the default value for both the model and the database. This keyword cannot be used with **relation**. | ✅ | | |
370402
| [**defaultModel**](#default-values) | Sets the default value for the model side. This keyword cannot be used with **relation**. | ✅ | | |

‎docs/06-concepts/06-database/04-indexing.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,3 +62,74 @@ indexes:
6262
```
6363

6464
If no type is specified the default is `btree`. All [PostgreSQL index types](https://www.postgresql.org/docs/current/indexes-types.html) are supported, `btree`, `hash`, `gist`, `spgist`, `gin`, `brin`.
65+
66+
### Vector indexes
67+
68+
To enhance the performance of vector similarity search, it is possible to create specialized vector indexes on `Vector` fields. Serverpod supports both `HNSW` and `IVFFLAT` index types with full parameter specification.
69+
70+
:::info
71+
Each vector index can only be created on a single `Vector` field. It is not possible to create a vector index on multiple fields of any kind.
72+
:::
73+
74+
#### HNSW indexes
75+
76+
Hierarchical Navigable Small World (HNSW) indexes provide fast approximate nearest neighbor search:
77+
78+
```yaml
79+
class: Document
80+
table: document
81+
fields:
82+
content: String
83+
embedding: Vector(1536)
84+
indexes:
85+
document_embedding_hnsw_idx:
86+
fields: embedding
87+
type: hnsw
88+
distanceFunction: cosine
89+
parameters:
90+
m: 16
91+
ef_construction: 64
92+
```
93+
94+
Available HNSW parameters:
95+
- `m`: Maximum number of bi-directional links for each node (default: 16)
96+
- `efConstruction`: Size of the dynamic candidate list (default: 64)
97+
98+
#### IVFFLAT indexes
99+
100+
Inverted File with Flat compression (IVFFLAT) indexes are suitable for large datasets:
101+
102+
```yaml
103+
class: Document
104+
table: document
105+
fields:
106+
content: String
107+
embedding: Vector(1536)
108+
indexes:
109+
document_embedding_ivfflat_idx:
110+
fields: embedding
111+
type: ivfflat
112+
distanceFunction: innerProduct
113+
parameters:
114+
lists: 100
115+
```
116+
117+
Available IVFFLAT parameters:
118+
- `lists`: Number of inverted lists (default: 100)
119+
120+
#### Distance functions
121+
122+
Supported distance functions for vector indexes (`distanceFunction` parameter):
123+
124+
| Distance Function | Description | Use Case |
125+
|-------------------|-------------------------------|------------------------------|
126+
| `l2` | Euclidean distance | Default for most embeddings |
127+
| `innerProduct` | Inner product | When vectors are normalized |
128+
| `cosine` | Cosine distance | Text embeddings |
129+
| `l1` | Manhattan or taxicab distance | Sparse/high-dimensional data |
130+
131+
:::tip
132+
If more than one distance function is going to be frequently used on the same vector field, consider creating one index for each distance function to ensure optimal performance.
133+
:::
134+
135+
For more details on vector indexes and its configuration, refer to the [pgvector extension documentation](https://github.com/pgvector/pgvector/tree/master?tab=readme-ov-file#indexing).

‎docs/06-concepts/06-database/06-filter.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,49 @@ await User.db.find(
194194

195195
In the example we fetch all users that has a name that starts with A *or* B.
196196

197+
### Vector distance operators
198+
199+
Vector fields support specialized distance operations for similarity search. Available vector distance operations:
200+
201+
- `distanceL2` - Euclidean (L2) distance.
202+
- `distanceInnerProduct` - Inner product distance.
203+
- `distanceCosine` - Cosine distance.
204+
- `distanceL1` - Manhattan or taxicab (L1) distance.
205+
206+
You can use vector distance operations with numeric comparisons for filtering and ordering:
207+
208+
```dart
209+
// The vector to compare against
210+
var queryVector = Vector([0.1, 0.2, 0.3, ...]);
211+
212+
// Find top documents similar to a query vector
213+
var similarDocs = await Document.db.find(
214+
session,
215+
where: (t) => t.embedding.distanceCosine(queryVector) < 0.5,
216+
orderBy: (t) => t.embedding.distanceCosine(queryVector),
217+
limit: 10,
218+
);
219+
220+
// Filter by distance range
221+
var mediumSimilarity = await Document.db.find(
222+
session,
223+
where: (t) => t.embedding.distanceL2(queryVector).between(0.3, 0.8),
224+
);
225+
226+
// Combine with other filters
227+
var filteredSimilarity = await Document.db.find(
228+
session,
229+
where: (t) => t.category.equals('article') &
230+
(t.embedding.distanceCosine(queryVector) < 0.7),
231+
orderBy: (t) => t.embedding.distanceCosine(queryVector),
232+
limit: 10,
233+
);
234+
```
235+
236+
:::tip
237+
For optimal performance with vector similarity searches, consider creating specialized vector indexes (HNSW or IVFFLAT) on your vector fields. See the [Vector indexes](indexing#vector-indexes) section for more details.
238+
:::
239+
197240
## Relation operations
198241

199242
If a relation between two models is defined a [one-to-one](relations/one-to-one) or [one-to-many](relations/one-to-many) object relation, then relation operations are supported in Serverpod.

‎docs/08-upgrading/05-upgrade-to-pgvector.md

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Upgrading to pgvector support
2+
3+
New Serverpod projects automatically include pgvector support through the `pgvector/pgvector` PostgreSQL Docker image. However, existing projects need to be upgraded to use vector functionality.
4+
5+
:::info
6+
This upgrade is only necessary if you want to use vector fields in your models. If you do not plan to use vector fields, you can skip this upgrade.
7+
:::
8+
9+
:::warning
10+
If trying to use vector fields without upgrading, you will encounter an error when applying migrations.
11+
:::
12+
13+
## For Docker-based environments
14+
15+
1. Update your `docker-compose.yml` to use a PostgreSQL image with pgvector (e.g., `pgvector/pgvector:pg16`):
16+
17+
```yaml
18+
services:
19+
postgres:
20+
image: pgvector/pgvector:pg16 # <-- Change from postgres image here
21+
ports:
22+
- '8090:5432'
23+
environment:
24+
POSTGRES_USER: postgres
25+
POSTGRES_DB: <projectname>
26+
POSTGRES_PASSWORD: <DB_PASSWORD>
27+
volumes:
28+
- <projectname>_data:/var/lib/postgresql/data
29+
30+
# Other services...
31+
32+
postgres_test:
33+
image: pgvector/pgvector:pg16 # <-- Change from postgres image here
34+
ports:
35+
- '9090:5432'
36+
environment:
37+
POSTGRES_USER: postgres
38+
POSTGRES_DB: <projectname>_test
39+
POSTGRES_PASSWORD: <DB_TEST_PASSWORD>
40+
volumes:
41+
- <projectname>_test_data:/var/lib/postgresql/data
42+
```
43+
44+
<!-- markdownlint-disable-next-line MD029-->
45+
2. Recreate your containers to use the new image:
46+
47+
```bash
48+
docker-compose down
49+
docker-compose up -d
50+
```
51+
52+
<!-- markdownlint-disable-next-line MD029-->
53+
3. Create your first vector field in a model:
54+
55+
```yaml
56+
class: Document
57+
table: document
58+
fields:
59+
content: String
60+
embedding: Vector(1536)
61+
```
62+
63+
<!-- markdownlint-disable-next-line MD029-->
64+
4. Generate and apply a migration:
65+
66+
```bash
67+
$ serverpod create-migration
68+
$ dart run bin/main.dart --apply-migrations
69+
```
70+
71+
For more details on creating and applying migrations, see the [Migrations](../concepts/database/migrations) section.
72+
73+
The pgvector extension will be automatically enabled during the first migration that includes a vector column.
74+
75+
## For managed PostgreSQL services
76+
77+
For cloud providers (AWS RDS, Google Cloud SQL, Azure Database, etc.), ensure that **pgvector extension is available** on your PostgreSQL instance. Most managed services already support pgvector with no additional setup required. If available, the extension will be enabled automatically when applying the migration.
78+
79+
:::tip
80+
If the cloud provider instructions is to run a `CREATE EXTENSION vector;` command, you can skip this step as Serverpod will handle it automatically during migration.
81+
:::
82+
83+
## Troubleshooting
84+
85+
If you encounter issues with pgvector:
86+
87+
- Verify that your PostgreSQL version supports pgvector 0.7.0+ (PostgreSQL 12+).
88+
- Check that the pgvector extension is properly installed.
89+
- Ensure your database user has the necessary permissions to create extensions.

0 commit comments

Comments
 (0)