docs(storage): topK 10_000 and nextToken (#50087)

Signed-off-by: Ferhat Elmas <elmas.ferhat@gmail.com>

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.

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
 
 <Admonition type="note" title="Local driver">
 
-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.
 
 </Admonition>
 ## Setting up local vector buckets

apps/docs/content/guides/storage/vector/querying-vectors.mdx

@@ -107,6 +107,51 @@ LIMIT 5;
 </TabPanel>
 </Tabs>
 
+## 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`)
+```
+
+<Admonition type="note" title="Local query limit">
+
+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.
+
+</Admonition>
+
 ## Semantic search
 
 Find documents similar to a query by embedding the query text: