From 83c33e903c920aa40cfc811e2a5bd81c40e0412d Mon Sep 17 00:00:00 2001 From: Ferhat Elmas Date: Wed, 9 Sep 2026 13:03:07 +0200 Subject: [PATCH] docs(storage): topK 10_000 and nextToken (#50087) Signed-off-by: Ferhat Elmas --- .../content/guides/storage/vector/limits.mdx | 12 +++++ .../storage/vector/local-development.mdx | 7 +-- .../storage/vector/querying-vectors.mdx | 45 +++++++++++++++++++ 3 files changed, 61 insertions(+), 3 deletions(-) diff --git a/apps/docs/content/guides/storage/vector/limits.mdx b/apps/docs/content/guides/storage/vector/limits.mdx index 71bacfcf935..9d6d63d1071 100644 --- a/apps/docs/content/guides/storage/vector/limits.mdx +++ b/apps/docs/content/guides/storage/vector/limits.mdx @@ -19,3 +19,15 @@ Vector buckets have default limits during the alpha phase. These limits are desi | **Indexes per bucket** | 10 | Maximum number of indexes per bucket | | **Vector dimensions** | Max 4096 | Maximum dimension size for embeddings | | **Batch size** | 1000 vectors | Maximum vectors per single insert/update request | + +## Query limits + +The `queryVectors` limits differ between hosted and local vector buckets. + +| Limit | Hosted vector buckets | Local vector buckets | +| -------------------------------- | --------------------- | -------------------- | +| **Maximum `topK`** | 10,000 | 100 | +| **Maximum results per response** | 100 | 100 | +| **`nextToken` query pagination** | Supported | Not supported | + +Hosted vector buckets use Amazon S3 Vectors. When a response includes a `nextToken`, send the same query again with that token to retrieve the next page. Local vector buckets use pgvector and return the requested results in one response. diff --git a/apps/docs/content/guides/storage/vector/local-development.mdx b/apps/docs/content/guides/storage/vector/local-development.mdx index e81fbab3e91..77b2d383c85 100644 --- a/apps/docs/content/guides/storage/vector/local-development.mdx +++ b/apps/docs/content/guides/storage/vector/local-development.mdx @@ -16,10 +16,11 @@ Make sure you have the latest version of the Supabase CLI installed to access th -In local development, vector buckets uses pg_vector as the underlying storage engine under the hood. -The Hosted version uses S3Vectors as the Storage engine for vectors, which is optimized for large-scale vector storage and similarity search. This means that while you can develop and test your vector bucket integrations locally, there may be differences in performance and behavior compared to the cloud environment. +Local vector buckets use pgvector as their storage engine. Hosted vector buckets use Amazon S3 Vectors, so query behavior and performance can differ between environments. -The API remain consistent between local and hosted environments, so you can build your application logic against the local pg_vector implementation and expect it to work with the S3Vectors engine in production. +Hosted `queryVectors` requests accept `topK` values up to 10,000 and return results in pages of at most 100. Use `nextToken` to retrieve each additional page. Local requests accept `topK` values up to 100 and reject `nextToken`. + +See [Vector Bucket limits](/docs/guides/storage/vector/limits) for the full comparison. ## Setting up local vector buckets diff --git a/apps/docs/content/guides/storage/vector/querying-vectors.mdx b/apps/docs/content/guides/storage/vector/querying-vectors.mdx index 42fc7e3622b..00be2fcc9b1 100644 --- a/apps/docs/content/guides/storage/vector/querying-vectors.mdx +++ b/apps/docs/content/guides/storage/vector/querying-vectors.mdx @@ -107,6 +107,51 @@ LIMIT 5; +## Retrieve more than 100 results + +Hosted vector buckets return at most 100 query results per response. To retrieve more nearest-neighbor results, set `topK` to the total number of results you need, up to 10,000, and follow `nextToken` until the response omits it. Keep the other query parameters unchanged between requests. + +```typescript +import { createClient } from '@supabase/supabase-js' + +const supabase = createClient('https://your-project-id.supabase.co', 'your-service-key') +const index = supabase.storage.vectors.from('embeddings').index('documents-openai') + +const query = { + queryVector: { + float32: [0.1, 0.2, 0.3 /* ... embedding of 1536 dimensions ... */], + }, + topK: 1000, + returnDistance: true, + returnMetadata: true, +} + +const matches = [] +let nextToken: string | undefined + +do { + const { data, error } = await index.queryVectors({ + ...query, + ...(nextToken ? { nextToken } : {}), + }) + + if (error) { + throw error + } + + matches.push(...data.vectors) + nextToken = data.nextToken +} while (nextToken) + +console.log(`Retrieved ${matches.length} matches`) +``` + + + +Local vector buckets use pgvector. They accept `topK` values up to 100 and do not support `nextToken` for `queryVectors`. See [Vector Bucket limits](/docs/guides/storage/vector/limits) for the provider-specific limits. + + + ## Semantic search Find documents similar to a query by embedding the query text: