Skip to content

feat(storage): add vector buckets support#1585

Merged
spydon merged 10 commits into
mainfrom
feat/storage-vector-buckets
Jul 14, 2026
Merged

feat(storage): add vector buckets support#1585
spydon merged 10 commits into
mainfrom
feat/storage-vector-buckets

Conversation

@spydon

@spydon spydon commented Jul 13, 2026

Copy link
Copy Markdown
Contributor

What

Implements the Storage Vector Buckets subsystem in storage_client, closing all 14 storage.vector_buckets.* gaps in the compliance matrix.

Reachable through supabase.storage.vectors, mirroring the supabase-js StorageVectorsClient structure while staying idiomatic to the Dart storage client (operations return parsed data directly and throw StorageException on failure instead of a {data, error} envelope).

final vectors = supabase.storage.vectors;
await vectors.createBucket('embeddings');

final bucket = vectors.from('embeddings');
await bucket.createIndex(
  name: 'documents',
  dimension: 1536,
  distanceMetric: DistanceMetric.cosine,
);

final index = bucket.index('documents');
await index.putVectors([
  Vector(key: 'doc-1', data: [0.1, 0.2, 0.3], metadata: {'title': 'Intro'}),
]);

final result = await index.queryVectors(queryVector: [0.1, 0.2, 0.3], topK: 5);

Capabilities

Bucket & index management (SupabaseVectorsClient, StorageVectorBucketApi):

  • create / list / delete vector bucket, get bucket metadata
  • scope to a bucket via .from(name) and to an index via .index(name)
  • create / get / list / delete index

Vector data operations (StorageVectorIndexApi):

  • put / get / list / query / delete vectors
  • parallel scan via listVectors' segmentCount / segmentIndex

Idiomatic Dart choices

  • dataType and distanceMetric are enums (VectorDataType, DistanceMetric), parsed leniently (unknown values decode to null for forward compatibility).
  • metadataConfiguration is flattened to a nonFilterableMetadataKeys parameter.
  • Batch sizes (put/delete 1-500) and parallel-scan segments (1-16) are validated client-side with ArgumentError.

Tests

  • 20 self-contained unit tests using the mock HTTP client, verifying request URLs/bodies and response parsing for every operation, plus the validation paths.

Compliance matrix

  • All 14 storage.vector_buckets.* features set to implemented with every new public symbol registered. The symbol check and compliance-file validator both pass locally.

Closes SDK-1307.

Implement the Storage Vectors subsystem, reachable through
supabase.storage.vectors. Adds vector bucket management, index
management scoped via .from(bucket), and vector data operations
(put, get, list, query, delete, parallel scan) scoped via .index(name).

Closes all 14 storage.vector_buckets.* capabilities in the compliance
matrix.
@spydon
spydon requested a review from a team as a code owner July 13, 2026 08:22
@github-actions github-actions Bot added the storage This issue or pull request is related to storage label Jul 13, 2026
spydon added 5 commits July 13, 2026 10:37
…es from name

The Storage Vectors API is a public alpha, so annotate every public
vector type and the storage.vectors entry point with @experimental.

Drop the enum value fields in favour of a value getter derived from
name, so DistanceMetric.dotProduct still serializes to 'dotproduct'.
The server returns creationTime as a unix timestamp in seconds; parse
it into a UTC DateTime for VectorBucket and VectorIndex.
Exercise the vector bucket, index and data operations against a real
Supabase stack. Enable [storage.vector] in the local config and bump the
pinned Supabase CLI to 2.109.1, whose storage-api image (v1.62.5) serves
the vector routes over the local pgvector backend.

Also return null for empty success bodies in the storage fetch, since the
vector mutation endpoints respond with an empty body.
spydon added 4 commits July 13, 2026 11:34
Make the vector client constructors const, drop inferrable type
arguments in vector metadata parsing and a pre-existing gotrue scopes
cast, and rename shadowing closure parameters in the vector integration
tests.
Replace the top-level _vectorDataTypeFromValue/_distanceMetricFromValue
helpers with static VectorDataType.fromValue/DistanceMetric.fromValue
methods on the enums themselves.
@spydon
spydon merged commit 4f7fcc6 into main Jul 14, 2026
36 checks passed
@spydon
spydon deleted the feat/storage-vector-buckets branch July 14, 2026 13:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

storage This issue or pull request is related to storage

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants