JavaScript

1. Install The Dependencies

Install the required package using npm:

npm install @aws-sdk/client-s3-vectors

2. Setup The Environment

Set your AIOZ Storage credentials as environment variables. You can find these values in the AIOZ Storage dashboard (opens in a new tab).

export ACCESS_KEY=<your-access-key>
export SECRET_KEY=<your-secret-key>

3. Create a Vector Bucket

A vector bucket is a dedicated namespace that holds your vector indexes. Create one before creating any indexes:

import { S3VectorsClient, CreateVectorBucketCommand } from '@aws-sdk/client-s3-vectors'
 
const client = new S3VectorsClient({
  region: 'us-east-1',
  credentials: {
    accessKeyId: 'YOUR_ACCESS_KEY',
    secretAccessKey: 'YOUR_SECRET_KEY'
  },
  endpoint: 'AIOZ_STORAGE_ENDPOINT_URL'
})
 
await client.send(new CreateVectorBucketCommand({
  vectorBucketName: 'YOUR_BUCKET_NAME'
}))

4. Create a Vector Index

A vector index is where your embeddings are stored. You must create one before inserting any vectors. Set the dimension to match the output size of your embedding model (e.g. 1536 for OpenAI text-embedding-3-small).

import { CreateIndexCommand } from '@aws-sdk/client-s3-vectors'
 
await client.send(new CreateIndexCommand({
  vectorBucketName: 'YOUR_BUCKET_NAME',
  indexName: 'my-index',
  dataType: 'float32',
  dimension: 1536,
  distanceMetric: 'cosine'
}))

5. Put Vectors

Store vector embeddings along with optional metadata:

import { PutVectorsCommand } from '@aws-sdk/client-s3-vectors'
 
await client.send(new PutVectorsCommand({
  vectorBucketName: 'YOUR_BUCKET_NAME',
  indexName: 'my-index',
  vectors: [
    {
      key: 'doc-001',
      data: { float32: [0.12, 0.87, 0.45] },
      metadata: { title: 'Introduction to AI', source: 'blog' }
    },
    {
      key: 'doc-002',
      data: { float32: [0.33, 0.61, 0.72] },
      metadata: { title: 'Vector Search Explained', source: 'docs' }
    }
  ]
}))

6. Query Vectors

Find the most similar vectors to a given query embedding:

import { QueryVectorsCommand } from '@aws-sdk/client-s3-vectors'
 
const response = await client.send(new QueryVectorsCommand({
  vectorBucketName: 'YOUR_BUCKET_NAME',
  indexName: 'my-index',
  queryVector: { float32: [0.11, 0.85, 0.47] },
  topK: 5,
  includeMetadata: true
}))
 
for (const match of response.vectors) {
  console.log(match.key, match.distance, match.metadata)
}

7. Delete Vectors

Remove vectors from the index by their keys:

import { DeleteVectorsCommand } from '@aws-sdk/client-s3-vectors'
 
await client.send(new DeleteVectorsCommand({
  vectorBucketName: 'YOUR_BUCKET_NAME',
  indexName: 'my-index',
  keys: ['doc-001', 'doc-002']
}))

Minimal Code Example

import {
  S3VectorsClient,
  CreateVectorBucketCommand,
  CreateIndexCommand,
  PutVectorsCommand,
  QueryVectorsCommand
} from '@aws-sdk/client-s3-vectors'
 
const client = new S3VectorsClient({
  region: 'us-east-1',
  credentials: {
    accessKeyId: 'YOUR_ACCESS_KEY',
    secretAccessKey: 'YOUR_SECRET_KEY'
  },
  endpoint: 'AIOZ_STORAGE_ENDPOINT_URL'
})
 
// Create vector bucket
await client.send(new CreateVectorBucketCommand({
  vectorBucketName: 'YOUR_BUCKET_NAME'
}))
 
// Create index
await client.send(new CreateIndexCommand({
  vectorBucketName: 'YOUR_BUCKET_NAME',
  indexName: 'my-index',
  dataType: 'float32',
  dimension: 3,
  distanceMetric: 'cosine'
}))
 
// Store vectors
await client.send(new PutVectorsCommand({
  vectorBucketName: 'YOUR_BUCKET_NAME',
  indexName: 'my-index',
  vectors: [
    {
      key: 'doc-001',
      data: { float32: [0.12, 0.87, 0.45] },
      metadata: { title: 'Example document' }
    }
  ]
}))
 
// Query similar vectors
const response = await client.send(new QueryVectorsCommand({
  vectorBucketName: 'YOUR_BUCKET_NAME',
  indexName: 'my-index',
  queryVector: { float32: [0.11, 0.85, 0.47] },
  topK: 5,
  includeMetadata: true
}))
 
for (const match of response.vectors) {
  console.log(match.key, match.distance, match.metadata)
}

PreviousPython NextGolang