\n\n## Requirements\n\n- **Node.js 20 or later** (Node.js 18 support dropped as of October 31, 2025)\n- For browser support, all modern browsers are supported\n\n> ⚠️ **Node.js 18 Deprecation Notice**\n>\n> Node.js 18 reached end-of-life on April 30, 2025. As announced in [our deprecation notice](https://github.com/orgs/supabase/discussions/37217), support for Node.js 18 was dropped on October 31, 2025.\n\n## Features\n\n- **File Storage**: Upload, download, list, move, and delete files\n- **Access Control**: Public and private buckets with fine-grained permissions\n- **Signed URLs**: Generate time-limited URLs for secure file access\n- **Image Transformations**: On-the-fly image resizing and optimization\n- **Vector Embeddings**: Store and query high-dimensional embeddings with similarity search\n- **Analytics Buckets**: Iceberg table-based buckets optimized for analytical queries and data processing\n\n## Quick Start Guide\n\n### Installing the module\n\n```bash\nnpm install @supabase/storage-js\n```\n\n### Connecting to the storage backend\n\nThere are two ways to use the Storage SDK:\n\n#### Option 1: Via Supabase Client (Recommended)\n\nIf you're already using `@supabase/supabase-js`, access storage through the client:\n\n```js\nimport { createClient } from '@supabase/supabase-js'\n\n// Use publishable/anon key for frontend applications\nconst supabase = createClient('https://.supabase.co', '')\n\n// Access storage\nconst storage = supabase.storage\n\n// Access different bucket types\nconst regularBucket = storage.from('my-bucket')\nconst vectorBucket = storage.vectors.from('embeddings-bucket')\nconst analyticsBucket = storage.analytics // Analytics API\n```\n\n#### Option 2: Standalone StorageClient\n\nFor backend applications or when you need to bypass Row Level Security:\n\n```js\nimport { StorageClient } from '@supabase/storage-js'\n\nconst STORAGE_URL = 'https://.supabase.co/storage/v1'\nconst SERVICE_KEY = '' // Use secret key for backend operations\n\nconst storageClient = new StorageClient(STORAGE_URL, {\n apikey: SERVICE_KEY,\n Authorization: `Bearer ${SERVICE_KEY}`,\n})\n\n// Access different bucket types\nconst regularBucket = storageClient.from('my-bucket')\nconst vectorBucket = storageClient.vectors.from('embeddings-bucket')\nconst analyticsBucket = storageClient.analytics // Analytics API\n```\n\n> **When to use each approach:**\n>\n> - Use `supabase.storage` when working with other Supabase features (auth, database, etc.) in frontend applications\n> - Use `new StorageClient()` for backend applications, Edge Functions, or when you need to bypass RLS policies\n\n> **Note:** Refer to the [Storage Access Control guide](https://supabase.com/docs/guides/storage/access-control) for detailed information on creating RLS policies.\n\n### Understanding Bucket Types\n\nSupabase Storage supports three types of buckets, each optimized for different use cases:\n\n#### 1. Regular Storage Buckets (File Storage)\n\nStandard buckets for storing files, images, videos, and other assets.\n\n```js\n// Create regular storage bucket\nconst { data, error } = await storageClient.createBucket('my-files', {\n public: false,\n})\n\n// Upload files\nawait storageClient.from('my-files').upload('avatar.png', file)\n```\n\n**Use cases:** User uploads, media assets, documents, backups\n\n#### 2. Vector Buckets (Embeddings Storage)\n\nSpecialized buckets for storing and querying high-dimensional vector embeddings.\n\n```js\n// Create vector bucket\nawait storageClient.vectors.createBucket('embeddings-prod')\n\n// Create index and insert vectors\nconst bucket = storageClient.vectors.from('embeddings-prod')\nawait bucket.createIndex({\n indexName: 'documents',\n dimension: 1536,\n distanceMetric: 'cosine',\n})\n```\n\n**Use cases:** Semantic search, AI-powered recommendations, similarity matching\n\n**[See full Vector Embeddings documentation below](#vector-embeddings)**\n\n#### 3. Analytics Buckets\n\nSpecialized buckets using Apache Iceberg table format, optimized for analytical queries and large-scale data processing.\n\n```js\n// Create analytics bucket\nawait storageClient.analytics.createBucket('analytics-data')\n\n// List analytics buckets\nconst { data, error } = await storageClient.analytics.listBuckets()\n\n// Delete analytics bucket\nawait storageClient.analytics.deleteBucket('analytics-data')\n```\n\n**Use cases:** Time-series data, analytical queries, data lakes, large-scale data processing, business intelligence\n\n**[See full Analytics Buckets documentation below](#analytics-buckets)**\n\n---\n\n### Handling resources\n\n#### Handling Storage Buckets\n\n- Create a new Storage bucket:\n\n ```js\n const { data, error } = await storageClient.createBucket(\n 'test_bucket', // Bucket name (must be unique)\n { public: false } // Bucket options\n )\n ```\n\n- Retrieve the details of an existing Storage bucket:\n\n ```js\n const { data, error } = await storageClient.getBucket('test_bucket')\n ```\n\n- Update a new Storage bucket:\n\n ```js\n const { data, error } = await storageClient.updateBucket(\n 'test_bucket', // Bucket name\n { public: false } // Bucket options\n )\n ```\n\n- Remove all objects inside a single bucket:\n\n ```js\n const { data, error } = await storageClient.emptyBucket('test_bucket')\n ```\n\n- Delete an existing bucket (a bucket can't be deleted with existing objects inside it):\n\n ```js\n const { data, error } = await storageClient.deleteBucket('test_bucket')\n ```\n\n- Retrieve the details of all Storage buckets within an existing project:\n\n ```js\n // List all buckets\n const { data, error } = await storageClient.listBuckets()\n\n // List buckets with options (pagination, sorting, search)\n const { data, error } = await storageClient.listBuckets({\n limit: 10,\n offset: 0,\n sortColumn: 'created_at',\n sortOrder: 'desc',\n search: 'prod',\n })\n ```\n\n#### Handling Files\n\n- Upload a file to an existing bucket:\n\n ```js\n const fileBody = ... // load your file here\n\n const { data, error } = await storageClient.from('bucket').upload('path/to/file', fileBody)\n ```\n\n > Note: \n > The path in `data.Key` is prefixed by the bucket ID and is not the value which should be passed to the `download` method in order to fetch the file. \n > To fetch the file via the `download` method, use `data.path` and `data.bucketId` as follows:\n >\n > ```javascript\n > const { data, error } = await storageClient.from('bucket').upload('/folder/file.txt', fileBody)\n > // check for errors\n > const { data2, error2 } = await storageClient.from(data.bucketId).download(data.path)\n > ```\n\n > Note: The `upload` method also accepts a map of optional parameters. For a complete list see the [Supabase API reference](https://supabase.com/docs/reference/javascript/storage-from-upload).\n\n- Download a file from an exisiting bucket:\n\n ```js\n const { data, error } = await storageClient.from('bucket').download('path/to/file')\n ```\n\n- List all the files within a bucket:\n\n ```js\n const { data, error } = await storageClient.from('bucket').list('folder')\n ```\n\n > Note: The `list` method also accepts a map of optional parameters. For a complete list see the [Supabase API reference](https://supabase.com/docs/reference/javascript/storage-from-list).\n\n- Replace an existing file at the specified path with a new one:\n\n ```js\n const fileBody = ... // load your file here\n\n const { data, error } = await storageClient\n .from('bucket')\n .update('path/to/file', fileBody)\n ```\n\n > Note: The `upload` method also accepts a map of optional parameters. For a complete list see the [Supabase API reference](https://supabase.com/docs/reference/javascript/storage-from-upload).\n\n- Move an existing file:\n\n ```js\n const { data, error } = await storageClient\n .from('bucket')\n .move('old/path/to/file', 'new/path/to/file')\n ```\n\n- Delete files within the same bucket:\n\n ```js\n const { data, error } = await storageClient.from('bucket').remove(['path/to/file'])\n ```\n\n- Create signed URL to download file without requiring permissions:\n\n ```js\n const expireIn = 60\n\n const { data, error } = await storageClient\n .from('bucket')\n .createSignedUrl('path/to/file', expireIn)\n ```\n\n- Retrieve URLs for assets in public buckets:\n\n ```js\n const { data, error } = await storageClient.from('public-bucket').getPublicUrl('path/to/file')\n ```\n\n## Analytics Buckets\n\nSupabase Storage provides specialized analytics buckets using Apache Iceberg table format, optimized for analytical workloads and large-scale data processing. These buckets are designed for data lake architectures, time-series data, and business intelligence applications.\n\n### What are Analytics Buckets?\n\nAnalytics buckets use the Apache Iceberg open table format, providing:\n\n- **ACID transactions** for data consistency\n- **Schema evolution** without data rewrites\n- **Time travel** to query historical data\n- **Efficient metadata management** for large datasets\n- **Optimized for analytical queries** rather than individual file operations\n\n### When to Use Analytics Buckets\n\n**Use analytics buckets for:**\n\n- Time-series data (logs, metrics, events)\n- Data lake architectures\n- Business intelligence and reporting\n- Large-scale batch processing\n- Analytical workloads requiring ACID guarantees\n\n**Use regular storage buckets for:**\n\n- User file uploads (images, documents, videos)\n- Individual file management\n- Content delivery\n- Simple object storage needs\n\n### Quick Start\n\nYou can access analytics functionality through the `analytics` property on your storage client:\n\n#### Via Supabase Client\n\n```typescript\nimport { createClient } from '@supabase/supabase-js'\n\nconst supabase = createClient('https://your-project.supabase.co', 'your-publishable-key')\n\n// Access analytics operations\nconst analytics = supabase.storage.analytics\n\n// Create an analytics bucket\nconst { data, error } = await analytics.createBucket('analytics-data')\nif (error) {\n console.error('Failed to create analytics bucket:', error.message)\n} else {\n console.log('Created bucket:', data.name)\n}\n```\n\n#### Via StorageClient\n\n```typescript\nimport { StorageClient } from '@supabase/storage-js'\n\nconst storageClient = new StorageClient('https://your-project.supabase.co/storage/v1', {\n apikey: 'YOUR_API_KEY',\n Authorization: 'Bearer YOUR_TOKEN',\n})\n\n// Access analytics operations\nconst analytics = storageClient.analytics\n\n// Create an analytics bucket\nawait analytics.createBucket('analytics-data')\n```\n\n### API Reference\n\n#### Create Analytics Bucket\n\nCreates a new analytics bucket using Iceberg table format:\n\n```typescript\nconst { data, error } = await analytics.createBucket('my-analytics-bucket')\n\nif (error) {\n console.error('Error:', error.message)\n} else {\n console.log('Created bucket:', data)\n}\n```\n\n**Returns:**\n\n```typescript\n{\n data: {\n id: string\n type: 'ANALYTICS'\n format: string\n created_at: string\n updated_at: string\n } | null\n error: StorageError | null\n}\n```\n\n#### List Analytics Buckets\n\nRetrieves all analytics buckets in your project with optional filtering and pagination:\n\n```typescript\nconst { data, error } = await analytics.listBuckets({\n limit: 10,\n offset: 0,\n sortColumn: 'created_at',\n sortOrder: 'desc',\n search: 'prod',\n})\n\nif (data) {\n console.log(`Found ${data.length} analytics buckets`)\n data.forEach((bucket) => {\n console.log(`- ${bucket.id} (created: ${bucket.created_at})`)\n })\n}\n```\n\n**Parameters:**\n\n- `limit?: number` - Maximum number of buckets to return\n- `offset?: number` - Number of buckets to skip (for pagination)\n- `sortColumn?: 'id' | 'name' | 'created_at' | 'updated_at'` - Column to sort by\n- `sortOrder?: 'asc' | 'desc'` - Sort direction\n- `search?: string` - Search term to filter bucket names\n\n**Returns:**\n\n```typescript\n{\n data: AnalyticBucket[] | null\n error: StorageError | null\n}\n```\n\n**Example with Pagination:**\n\n```typescript\n// Fetch first page\nconst firstPage = await analytics.listBuckets({\n limit: 100,\n offset: 0,\n sortColumn: 'created_at',\n sortOrder: 'desc',\n})\n\n// Fetch second page\nconst secondPage = await analytics.listBuckets({\n limit: 100,\n offset: 100,\n sortColumn: 'created_at',\n sortOrder: 'desc',\n})\n```\n\n#### Delete Analytics Bucket\n\nDeletes an analytics bucket. The bucket must be empty before deletion.\n\n```typescript\nconst { data, error } = await analytics.deleteBucket('old-analytics-bucket')\n\nif (error) {\n console.error('Failed to delete:', error.message)\n} else {\n console.log('Bucket deleted:', data.message)\n}\n```\n\n**Returns:**\n\n```typescript\n{\n data: { message: string } | null\n error: StorageError | null\n}\n```\n\n> **Note:** A bucket cannot be deleted if it contains data. You must empty the bucket first.\n\n#### Get Iceberg Catalog for Advanced Operations\n\nFor advanced operations like creating tables, namespaces, and querying Iceberg metadata, use the `from()` method to get a configured [iceberg-js](https://github.com/supabase/iceberg-js) client:\n\n```typescript\n// Get an Iceberg REST Catalog client for your analytics bucket\nconst catalog = analytics.from('analytics-data')\n\n// Create a namespace\nawait catalog.createNamespace({ namespace: ['default'] }, { properties: { owner: 'data-team' } })\n\n// Create a table with schema\nawait catalog.createTable(\n { namespace: ['default'] },\n {\n name: 'events',\n schema: {\n type: 'struct',\n fields: [\n { id: 1, name: 'id', type: 'long', required: true },\n { id: 2, name: 'timestamp', type: 'timestamp', required: true },\n { id: 3, name: 'user_id', type: 'string', required: false },\n ],\n 'schema-id': 0,\n 'identifier-field-ids': [1],\n },\n 'partition-spec': {\n 'spec-id': 0,\n fields: [],\n },\n 'write-order': {\n 'order-id': 0,\n fields: [],\n },\n properties: {\n 'write.format.default': 'parquet',\n },\n }\n)\n\n// List tables in namespace\nconst tables = await catalog.listTables({ namespace: ['default'] })\nconsole.log(tables) // [{ namespace: ['default'], name: 'events' }]\n\n// Load table metadata\nconst table = await catalog.loadTable({ namespace: ['default'], name: 'events' })\n\n// Update table properties\nawait catalog.updateTable(\n { namespace: ['default'], name: 'events' },\n { properties: { 'read.split.target-size': '134217728' } }\n)\n\n// Drop table\nawait catalog.dropTable({ namespace: ['default'], name: 'events' })\n\n// Drop namespace\nawait catalog.dropNamespace({ namespace: ['default'] })\n```\n\n**Returns:** `IcebergRestCatalog` instance from [iceberg-js](https://github.com/supabase/iceberg-js)\n\n> **Note:** The `from()` method returns an Iceberg REST Catalog client that provides full access to the Apache Iceberg REST API. For complete documentation of available operations, see the [iceberg-js documentation](https://supabase.github.io/iceberg-js/).\n\n### Error Handling\n\nAnalytics buckets use the same error handling pattern as the rest of the Storage SDK:\n\n```typescript\nconst { data, error } = await analytics.createBucket('my-bucket')\n\nif (error) {\n console.error('Error:', error.message)\n console.error('Status:', error.status)\n console.error('Status Code:', error.statusCode)\n // Handle error appropriately\n}\n```\n\n#### Throwing Errors\n\nYou can configure the client to throw errors instead of returning them:\n\n```typescript\nconst analytics = storageClient.analytics\nanalytics.throwOnError()\n\ntry {\n const { data } = await analytics.createBucket('my-bucket')\n // data is guaranteed to be present\n console.log('Success:', data)\n} catch (error) {\n if (error instanceof StorageApiError) {\n console.error('API Error:', error.statusCode, error.message)\n }\n}\n```\n\n### TypeScript Types\n\nThe library exports TypeScript types for analytics buckets:\n\n```typescript\nimport type { AnalyticBucket, BucketType, StorageError } from '@supabase/storage-js'\n\n// AnalyticBucket type\ninterface AnalyticBucket {\n id: string\n type: 'ANALYTICS'\n format: string\n created_at: string\n updated_at: string\n}\n```\n\n### Common Patterns\n\n#### Checking if a Bucket Exists\n\n```typescript\nasync function bucketExists(bucketName: string): Promise {\n const { data, error } = await analytics.listBuckets({\n search: bucketName,\n })\n\n if (error) {\n console.error('Error checking bucket:', error.message)\n return false\n }\n\n return data?.some((bucket) => bucket.id === bucketName) ?? false\n}\n```\n\n#### Creating Bucket with Error Handling\n\n```typescript\nasync function ensureAnalyticsBucket(bucketName: string) {\n // Try to create the bucket\n const { data, error } = await analytics.createBucket(bucketName)\n\n if (error) {\n // Check if bucket already exists (conflict error)\n if (error.statusCode === '409') {\n console.log(`Bucket '${bucketName}' already exists`)\n return { success: true, created: false }\n }\n\n // Other error occurred\n console.error('Failed to create bucket:', error.message)\n return { success: false, error }\n }\n\n console.log(`Created new bucket: '${bucketName}'`)\n return { success: true, created: true, data }\n}\n```\n\n#### Listing All Buckets with Pagination\n\n```typescript\nasync function getAllAnalyticsBuckets() {\n const allBuckets: AnalyticBucket[] = []\n let offset = 0\n const limit = 100\n\n while (true) {\n const { data, error } = await analytics.listBuckets({\n limit,\n offset,\n sortColumn: 'created_at',\n sortOrder: 'desc',\n })\n\n if (error) {\n console.error('Error fetching buckets:', error.message)\n break\n }\n\n if (!data || data.length === 0) {\n break\n }\n\n allBuckets.push(...data)\n\n // If we got fewer results than the limit, we've reached the end\n if (data.length < limit) {\n break\n }\n\n offset += limit\n }\n\n return allBuckets\n}\n```\n\n## Vector Embeddings\n\nSupabase Storage provides built-in support for storing and querying high-dimensional vector embeddings, powered by S3 Vectors. This enables semantic search, similarity matching, and AI-powered applications without needing a separate vector database.\n\n> **Note:** Vector embeddings functionality is available in `@supabase/storage-js` v2.76 and later.\n\n### Features\n\n- **Vector Buckets**: Organize vector indexes into logical containers\n- **Vector Indexes**: Define schemas with configurable dimensions and distance metrics\n- **Batch Operations**: Insert/update/delete up to 500 vectors per request\n- **Similarity Search**: Query for nearest neighbors using cosine, euclidean, or dot product distance\n- **Metadata Filtering**: Store and filter vectors by arbitrary JSON metadata\n- **Pagination**: Efficiently scan large vector datasets\n- **Parallel Scanning**: Distribute scans across multiple workers for high throughput\n- **Cross-platform**: Works in Node.js, browsers, and edge runtimes\n\n### Quick Start\n\nYou can access vector functionality in three ways, depending on your use case:\n\n#### Option 1: Via Supabase Client (Most Common)\n\nIf you're using the full Supabase client:\n\n```typescript\nimport { createClient } from '@supabase/supabase-js'\n\nconst supabase = createClient('https://your-project.supabase.co', 'your-publishable-key')\n\n// Access vector operations through storage\nconst vectors = supabase.storage.vectors\n\n// Create a vector bucket\nawait vectors.createBucket('embeddings-prod')\n\n// Create an index\nconst bucket = vectors.from('embeddings-prod')\nawait bucket.createIndex({\n indexName: 'documents-openai',\n dataType: 'float32',\n dimension: 1536,\n distanceMetric: 'cosine',\n})\n\n// Insert vectors\nconst index = bucket.index('documents-openai')\nawait index.putVectors({\n vectors: [\n {\n key: 'doc-1',\n data: { float32: [0.1, 0.2, 0.3 /* ...1536 dimensions */] },\n metadata: { title: 'Introduction', category: 'docs' },\n },\n ],\n})\n\n// Query similar vectors\nconst { data, error } = await index.queryVectors({\n queryVector: { float32: [0.15, 0.25, 0.35 /* ...1536 dimensions */] },\n topK: 5,\n returnDistance: true,\n returnMetadata: true,\n})\n\nif (data) {\n data.matches.forEach((match) => {\n console.log(`${match.key}: distance=${match.distance}`)\n console.log('Metadata:', match.metadata)\n })\n}\n```\n\n#### Option 2: Via StorageClient\n\nIf you're using the standalone `StorageClient` for storage operations, access vectors through the `vectors` property:\n\n```typescript\nimport { StorageClient } from '@supabase/storage-js'\n\nconst storageClient = new StorageClient('https://your-project.supabase.co/storage/v1', {\n apikey: 'YOUR_API_KEY',\n Authorization: 'Bearer YOUR_TOKEN',\n})\n\n// Access vector operations\nconst vectors = storageClient.vectors\n\n// Use the same API as shown in Option 1\nawait vectors.createBucket('embeddings-prod')\nconst bucket = vectors.from('embeddings-prod')\n// ... rest of operations\n```\n\n#### Option 3: Standalone Vector Client\n\nFor vector-only applications that don't need regular file storage operations:\n\n```typescript\nimport { StorageVectorsClient } from '@supabase/storage-js'\n\n// Initialize standalone vector client\nconst vectorClient = new StorageVectorsClient('https://your-project.supabase.co/storage/v1', {\n headers: { Authorization: 'Bearer YOUR_TOKEN' },\n})\n\n// Use the same API as shown in Option 1\nawait vectorClient.createBucket('embeddings-prod')\nconst bucket = vectorClient.from('embeddings-prod')\n// ... rest of operations\n```\n\n> **When to use each approach:**\n>\n> - **Option 1**: When using other Supabase features (auth, database, realtime)\n> - **Option 2**: When working with both file storage and vectors\n> - **Option 3**: For dedicated vector-only applications without file storage\n\n### API Reference\n\n#### Client Initialization\n\n```typescript\nconst vectorClient = new StorageVectorsClient(url, options?)\n```\n\n**Options:**\n\n- `headers?: Record` - Custom HTTP headers (e.g., Authorization)\n- `fetch?: Fetch` - Custom fetch implementation\n\n#### Vector Buckets\n\nVector buckets are top-level containers for organizing vector indexes.\n\n##### Create Bucket\n\n```typescript\nconst { data, error } = await vectorClient.createBucket('my-bucket')\n```\n\n##### Get Bucket\n\n```typescript\nconst { data, error } = await vectorClient.getBucket('my-bucket')\nconsole.log('Created at:', new Date(data.vectorBucket.creationTime! * 1000))\n```\n\n##### List Buckets\n\n```typescript\nconst { data, error } = await vectorClient.listBuckets({\n prefix: 'prod-',\n maxResults: 100,\n})\n\n// Pagination\nif (data?.nextToken) {\n const next = await vectorClient.listBuckets({ nextToken: data.nextToken })\n}\n```\n\n##### Delete Bucket\n\n```typescript\n// Bucket must be empty (all indexes deleted first)\nconst { error } = await vectorClient.deleteBucket('my-bucket')\n```\n\n#### Vector Indexes\n\nVector indexes define the schema for embeddings including dimension and distance metric.\n\n##### Create Index\n\n```typescript\nconst bucket = vectorClient.from('my-bucket')\n\nawait bucket.createIndex({\n indexName: 'my-index',\n dataType: 'float32',\n dimension: 1536,\n distanceMetric: 'cosine', // 'cosine' | 'euclidean' | 'dotproduct'\n metadataConfiguration: {\n nonFilterableMetadataKeys: ['raw_text', 'internal_id'],\n },\n})\n```\n\n**Distance Metrics:**\n\n- `cosine` - Cosine similarity (normalized dot product)\n- `euclidean` - Euclidean distance (L2 norm)\n- `dotproduct` - Dot product similarity\n\n##### Get Index\n\n```typescript\nconst { data, error } = await bucket.getIndex('my-index')\nconsole.log('Dimension:', data?.index.dimension)\nconsole.log('Distance metric:', data?.index.distanceMetric)\n```\n\n##### List Indexes\n\n```typescript\nconst { data, error } = await bucket.listIndexes({\n prefix: 'documents-',\n maxResults: 100,\n})\n```\n\n##### Delete Index\n\n```typescript\n// Deletes index and all its vectors\nawait bucket.deleteIndex('my-index')\n```\n\n#### Vector Operations\n\n##### Insert/Update Vectors (Upsert)\n\n```typescript\nconst index = vectorClient.from('my-bucket').index('my-index')\n\nawait index.putVectors({\n vectors: [\n {\n key: 'unique-id-1',\n data: {\n float32: [\n /* 1536 numbers */\n ],\n },\n metadata: {\n title: 'Document Title',\n category: 'technical',\n page: 1,\n },\n },\n // ... up to 500 vectors per request\n ],\n})\n```\n\n**Limitations:**\n\n- 1-500 vectors per request\n- Vectors must match index dimension\n- Keys must be unique within index\n\n##### Get Vectors by Key\n\n```typescript\nconst { data, error } = await index.getVectors({\n keys: ['doc-1', 'doc-2', 'doc-3'],\n returnData: true, // Include embeddings\n returnMetadata: true, // Include metadata\n})\n\ndata?.vectors.forEach((v) => {\n console.log(v.key, v.metadata)\n})\n```\n\n##### Query Similar Vectors (ANN Search)\n\n```typescript\nconst { data, error } = await index.queryVectors({\n queryVector: {\n float32: [\n /* 1536 numbers */\n ],\n },\n topK: 10,\n filter: {\n category: 'technical',\n published: true,\n },\n returnDistance: true,\n returnMetadata: true,\n})\n\n// Results ordered by similarity\ndata?.matches.forEach((match) => {\n console.log(`${match.key}: distance=${match.distance}`)\n})\n```\n\n**Filter Syntax:**\nThe `filter` parameter accepts arbitrary JSON for metadata filtering. Non-filterable keys (configured at index creation) cannot be used in filters but can still be returned.\n\n##### List/Scan Vectors\n\n```typescript\n// Simple pagination\nlet nextToken: string | undefined\ndo {\n const { data } = await index.listVectors({\n maxResults: 500,\n nextToken,\n returnMetadata: true,\n })\n\n console.log('Batch:', data?.vectors.length)\n nextToken = data?.nextToken\n} while (nextToken)\n\n// Parallel scanning (4 workers)\nconst workers = [0, 1, 2, 3].map(async (segmentIndex) => {\n const { data } = await index.listVectors({\n segmentCount: 4,\n segmentIndex,\n returnMetadata: true,\n })\n return data?.vectors || []\n})\n\nconst results = await Promise.all(workers)\nconst allVectors = results.flat()\n```\n\n**Limitations:**\n\n- `maxResults`: 1-1000 (default: 500)\n- `segmentCount`: 1-16\n- Response may be limited by 1MB size\n\n##### Delete Vectors\n\n```typescript\nawait index.deleteVectors({\n keys: ['doc-1', 'doc-2', 'doc-3'],\n // ... up to 500 keys per request\n})\n```\n\n### Error Handling\n\nThe library uses a consistent error handling pattern:\n\n```typescript\nconst { data, error } = await vectorClient.createBucket('my-bucket')\n\nif (error) {\n console.error('Error:', error.message)\n console.error('Status:', error.status)\n console.error('Code:', error.statusCode)\n}\n```\n\n#### Error Codes\n\n| Code | HTTP | Description |\n| ---------------------------- | ---- | ----------------------- |\n| `InternalError` | 500 | Internal server error |\n| `S3VectorConflictException` | 409 | Resource already exists |\n| `S3VectorNotFoundException` | 404 | Resource not found |\n| `S3VectorBucketNotEmpty` | 400 | Bucket contains indexes |\n| `S3VectorMaxBucketsExceeded` | 400 | Bucket quota exceeded |\n| `S3VectorMaxIndexesExceeded` | 400 | Index quota exceeded |\n\n#### Throwing Errors\n\nYou can configure the client to throw errors instead:\n\n```typescript\nconst vectorClient = new StorageVectorsClient(url, options)\nvectorClient.throwOnError()\n\ntry {\n const { data } = await vectorClient.createBucket('my-bucket')\n // data is guaranteed to be present\n} catch (error) {\n if (error instanceof StorageVectorsApiError) {\n console.error('API Error:', error.statusCode)\n }\n}\n```\n\n### Advanced Usage\n\n#### Scoped Clients\n\nCreate scoped clients for cleaner code:\n\n```typescript\n// Bucket-scoped operations\nconst bucket = vectorClient.from('embeddings-prod')\nawait bucket.createIndex({\n /* ... */\n})\nawait bucket.listIndexes()\n\n// Index-scoped operations\nconst index = bucket.index('documents-openai')\nawait index.putVectors({\n /* ... */\n})\nawait index.queryVectors({\n /* ... */\n})\n```\n\n#### Custom Fetch\n\nProvide a custom fetch implementation:\n\n```typescript\nimport { StorageVectorsClient } from '@supabase/storage-js'\n\nconst vectorClient = new StorageVectorsClient(url, {\n fetch: customFetch,\n headers: {\n /* ... */\n },\n})\n```\n\n#### Batch Processing\n\nProcess large datasets in batches:\n\n```typescript\nasync function insertLargeDataset(vectors: VectorObject[]) {\n const batchSize = 500\n\n for (let i = 0; i < vectors.length; i += batchSize) {\n const batch = vectors.slice(i, i + batchSize)\n await index.putVectors({ vectors: batch })\n console.log(`Inserted ${i + batch.length}/${vectors.length}`)\n }\n}\n```\n\n#### Float32 Validation\n\nEnsure vectors are properly normalized to float32:\n\n```typescript\nimport { normalizeToFloat32 } from '@supabase/storage-js'\n\nconst vector = normalizeToFloat32([0.1, 0.2, 0.3 /* ... */])\n```\n\n### Type Definitions\n\nThe library exports comprehensive TypeScript types:\n\n```typescript\nimport type {\n VectorBucket,\n VectorIndex,\n VectorData,\n VectorObject,\n VectorMatch,\n VectorMetadata,\n DistanceMetric,\n ApiResponse,\n StorageVectorsError,\n} from '@supabase/storage-js'\n```\n\n## Development\n\nThis package is part of the [Supabase JavaScript monorepo](https://github.com/supabase/supabase-js). To work on this package:\n\n### Building\n\n#### Build Scripts Overview\n\n```bash\n# Build the package\nnpx nx build storage-js\n\n# Watch mode for development\nnpx nx build storage-js --watch\n\n# Generate documentation\nnpx nx docs storage-js\n```\n\n### Testing\n\n**Important:** The storage-js tests require a local Supabase stack running via the Supabase CLI. Docker must be running since the Supabase CLI uses it internally.\n\n#### Prerequisites\n\n1. **Docker** must be installed and running (used by Supabase CLI internally)\n2. **Supabase CLI** — installed automatically via `npx supabase`\n\n#### Test Scripts Overview\n\n| Script | Description | What it does |\n| ----------------- | --------------------------------- | ----------------------------------------------------------------- |\n| `test:storage` | **Complete test workflow** | Runs the full test cycle: clean → start infra → run tests → clean |\n| `test:suite` | **Jest tests only** | Runs Jest tests with coverage (requires infra to be running) |\n| `test:infra` | **Start test infrastructure** | Starts Supabase CLI stack (PostgreSQL, Storage API, Kong, etc.) |\n| `test:clean-post` | **Stop and clean infrastructure** | Stops the Supabase CLI stack |\n\n#### Running Tests\n\n##### Option 1: Complete Test Run (Recommended)\n\nThis handles everything automatically - starting infrastructure, running tests, and cleaning up:\n\n```bash\n# From monorepo root\nnpx nx test:storage storage-js\n```\n\nThis command will:\n\n1. Stop any existing test containers\n2. Build and start fresh test infrastructure\n3. Wait for services to be ready\n4. Run all Jest tests with coverage\n5. Clean up all containers after tests complete\n\n##### Option 2: Manual Infrastructure Management\n\nUseful for development when you want to run tests multiple times without restarting Docker:\n\n```bash\n# Step 1: Start the test infrastructure\n# From root\nnpx nx test:infra storage-js\n# This starts: PostgreSQL, Storage API, Kong Gateway, and imgproxy\n\n# Step 2: Run tests (can run multiple times)\nnpx nx test:suite storage-js\n\n# Step 3: When done, clean up the infrastructure\nnpx nx test:clean-post storage-js\n```\n\n##### Option 3: Development Mode\n\nFor actively developing and debugging tests:\n\n```bash\n# Start infrastructure once (from root)\nnpx nx test:infra storage-js\n\n# Run tests in watch mode\nnpx nx test:suite storage-js --watch\n\n# Clean up when done\nnpx nx test:clean-post storage-js\n```\n\n#### Test Infrastructure Details\n\nThe test infrastructure is managed via the Supabase CLI (`npx supabase start --workdir test`), which starts a local Supabase stack defined by the config in `test/`. This includes PostgreSQL, the Storage API, Kong Gateway, and supporting services.\n\n#### Common Issues and Solutions\n\n| Issue | Solution |\n| --------------------------------- | ------------------------------------------------------------------------------------------------ |\n| Port conflicts | Another service is using a required port. Run `npx nx test:clean-post storage-js` then try again |\n| \"request failed, reason:\" errors | Infrastructure isn't running. Run `npx nx test:infra storage-js` first |\n| Tests fail with connection errors | Ensure Docker is running (Supabase CLI requires Docker) |\n| Stack already running | Run `npx nx test:clean-post storage-js` to stop it before restarting |\n\n#### Understanding Test Failures\n\n- **StorageUnknownError with \"request failed\"**: Infrastructure not running\n- **Snapshot failures**: Expected test data has changed — review and update snapshots if needed\n\n### Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](../../../CONTRIBUTING.md) for details on how to get started.\n\nFor major changes or if you're unsure about something, please open an issue first to discuss your proposed changes.","users":{}}
![\"Supabase](\"https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/logo-preview.jpg\"){kind=logo}
\n