Skip to content

Document vector query helpers #3078

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
atharva-appwrite wants to merge 1 commit into
base: main
Choose a base branch
from
+128 −1
Open

Document vector query helpers #3078

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions src/routes/changelog/(entries)/2026-07-03.markdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
layout: changelog
title: 'Vector query helpers are now available across Appwrite SDKs'
date: 2026-07-03
---

Appwrite SDKs now include `Query.vectorDot()`, `Query.vectorCosine()`, and `Query.vectorEuclidean()` helpers for vector similarity queries.

Use these helpers with VectorsDB document list endpoints to query vector attributes with dot product, cosine similarity, or Euclidean distance metrics.

{% arrow_link href="/docs/products/databases/queries#vector-queries" %}
View vector query examples
{% /arrow_link %}
116 changes: 115 additions & 1 deletion src/routes/docs/products/databases/queries/+page.markdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2043,6 +2043,121 @@ Query::updated_after("2025-01-01T00:00:00Z").to_string()
{"method":"updatedAfter","values":["2025-01-01T00:00:00Z"]}
```
{% /multicode %}

# Vector queries {% #vector-queries %}

Vector query helpers search vector attributes by similarity to a query vector. Use them with VectorsDB document list endpoints and pass a numeric vector with the same dimensions as the stored embeddings.

@greptile-apps greptile-apps Bot Jul 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 "VectorsDB document list endpoints" terminology is inconsistent with the rest of the page

This page's description and all code examples refer exclusively to TablesDB / listRows. Calling out "VectorsDB document list endpoints" here implies these helpers only work with a separate VectorsDB product — but there's no other mention of VectorsDB anywhere on the page, and the same phrasing appears in the changelog entry. If VectorsDB is a distinct product, the cross-linking and context need clarification; if it's not, the reference should be updated to match the TablesDB terminology used throughout.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!


Choose the helper that matches the similarity metric you want to use:

| Helper | Similarity metric |
|--------|-------------------|
| `vectorDot` | Dot product |
| `vectorCosine` | Cosine similarity |
| `vectorEuclidean` | Euclidean distance |

You can include one vector similarity query per request. Vector queries can be combined with standard filters and pagination helpers such as `Query.equal()` and `Query.limit()`.

{% multicode %}
```client-web
Query.vectorDot("embeddings", [0.12, 0.24, 0.48])
Query.vectorCosine("embeddings", [0.12, 0.24, 0.48])
Query.vectorEuclidean("embeddings", [0.12, 0.24, 0.48])
```
```client-flutter
Query.vectorDot("embeddings", [0.12, 0.24, 0.48])
Query.vectorCosine("embeddings", [0.12, 0.24, 0.48])
Query.vectorEuclidean("embeddings", [0.12, 0.24, 0.48])
```
```client-react-native
Query.vectorDot("embeddings", [0.12, 0.24, 0.48])
Query.vectorCosine("embeddings", [0.12, 0.24, 0.48])
Query.vectorEuclidean("embeddings", [0.12, 0.24, 0.48])
```
```client-apple
Query.vectorDot("embeddings", vector: [0.12, 0.24, 0.48])
Query.vectorCosine("embeddings", vector: [0.12, 0.24, 0.48])
Query.vectorEuclidean("embeddings", vector: [0.12, 0.24, 0.48])
```
Comment on lines +2077 to +2081

@greptile-apps greptile-apps Bot Jul 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 server-swift uses labeled parameter inconsistent with geo-query convention

The existing geo-query server-swift examples omit the parameter label (e.g., Query.distanceEqual("location", [-73.9851, 40.7589], 200)), but the new vector-query server-swift examples use vector: (e.g., Query.vectorDot("embeddings", vector: [0.12, 0.24, 0.48])). Meanwhile the client-apple (iOS SDK) block correctly uses the label for both. If the server Swift SDK's vectorDot method follows the same unlabeled convention as distanceEqual, the generated docs would show incorrect call syntax that won't compile for users copying the snippet. Could you confirm the actual server-swift SDK method signature?

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

```client-android-kotlin
Query.vectorDot("embeddings", listOf(0.12, 0.24, 0.48))
Query.vectorCosine("embeddings", listOf(0.12, 0.24, 0.48))
Query.vectorEuclidean("embeddings", listOf(0.12, 0.24, 0.48))
```
```client-android-java
Query.vectorDot("embeddings", Arrays.asList(0.12, 0.24, 0.48))
Query.vectorCosine("embeddings", Arrays.asList(0.12, 0.24, 0.48))
Query.vectorEuclidean("embeddings", Arrays.asList(0.12, 0.24, 0.48))
```
```server-nodejs
const sdk = require('node-appwrite');

sdk.Query.vectorDot("embeddings", [0.12, 0.24, 0.48])
sdk.Query.vectorCosine("embeddings", [0.12, 0.24, 0.48])
sdk.Query.vectorEuclidean("embeddings", [0.12, 0.24, 0.48])
```
```server-python
Query.vector_dot("embeddings", [0.12, 0.24, 0.48])
Query.vector_cosine("embeddings", [0.12, 0.24, 0.48])
Query.vector_euclidean("embeddings", [0.12, 0.24, 0.48])
```
```server-ruby
Query.vector_dot("embeddings", [0.12, 0.24, 0.48])
Query.vector_cosine("embeddings", [0.12, 0.24, 0.48])
Query.vector_euclidean("embeddings", [0.12, 0.24, 0.48])
```
```server-deno
Query.vectorDot("embeddings", [0.12, 0.24, 0.48])
Query.vectorCosine("embeddings", [0.12, 0.24, 0.48])
Query.vectorEuclidean("embeddings", [0.12, 0.24, 0.48])
```
```server-php
Query::vectorDot("embeddings", [0.12, 0.24, 0.48])
Query::vectorCosine("embeddings", [0.12, 0.24, 0.48])
Query::vectorEuclidean("embeddings", [0.12, 0.24, 0.48])
```
```server-dotnet
Query.VectorDot("embeddings", new List<double> { 0.12, 0.24, 0.48 })
Query.VectorCosine("embeddings", new List<double> { 0.12, 0.24, 0.48 })
Query.VectorEuclidean("embeddings", new List<double> { 0.12, 0.24, 0.48 })
```
```server-go
query.VectorDot("embeddings", []float64{0.12, 0.24, 0.48})
query.VectorCosine("embeddings", []float64{0.12, 0.24, 0.48})
query.VectorEuclidean("embeddings", []float64{0.12, 0.24, 0.48})
```
```server-dart
Query.vectorDot("embeddings", [0.12, 0.24, 0.48])
Query.vectorCosine("embeddings", [0.12, 0.24, 0.48])
Query.vectorEuclidean("embeddings", [0.12, 0.24, 0.48])
```
```server-swift
Query.vectorDot("embeddings", vector: [0.12, 0.24, 0.48])
Query.vectorCosine("embeddings", vector: [0.12, 0.24, 0.48])
Query.vectorEuclidean("embeddings", vector: [0.12, 0.24, 0.48])
```
```server-kotlin
Query.vectorDot("embeddings", listOf(0.12, 0.24, 0.48))
Query.vectorCosine("embeddings", listOf(0.12, 0.24, 0.48))
Query.vectorEuclidean("embeddings", listOf(0.12, 0.24, 0.48))
```
```server-java
Query.vectorDot("embeddings", Arrays.asList(0.12, 0.24, 0.48))
Query.vectorCosine("embeddings", Arrays.asList(0.12, 0.24, 0.48))
Query.vectorEuclidean("embeddings", Arrays.asList(0.12, 0.24, 0.48))
```
```server-rust
Query::vector_dot("embeddings", serde_json::json!([0.12, 0.24, 0.48])).to_string()
Query::vector_cosine("embeddings", serde_json::json!([0.12, 0.24, 0.48])).to_string()
Query::vector_euclidean("embeddings", serde_json::json!([0.12, 0.24, 0.48])).to_string()
```
```http
{"method":"vectorDot","column":"embeddings","values":[[0.12,0.24,0.48]]}
{"method":"vectorCosine","column":"embeddings","values":[[0.12,0.24,0.48]]}
{"method":"vectorEuclidean","column":"embeddings","values":[[0.12,0.24,0.48]]}
```
{% /multicode %}

# Geo queries and spatial operations {% #geo-queries %}

Geo queries enable geographic operations on [spatial columns](/docs/products/databases/spatial). Coordinates are specified as `[longitude, latitude]` arrays. Distance measurements can be specified in meters or degrees.
Expand Down Expand Up @@ -3072,4 +3187,3 @@ let rows = tables_db.list_rows(

This example demonstrates how to combine `OR` and `AND` operations. The query uses `Query.or()` to match either condition: books under $20 OR magazines under $10.
Each condition within the OR is composed of two AND conditions - one for the category and one for the price threshold. The database will return rows that match either of these combined conditions.

Loading