Golang

1. Install The Dependencies

Add the S3 Vectors SDK to your Go module:

go get github.com/aws/aws-sdk-go-v2/service/s3vectors

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:

package main
 
import (
    "context"
    "log"
 
    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3vectors"
    "github.com/aws/aws-sdk-go-v2/service/s3vectors/types"
)
 
func main() {
    resolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
        return aws.Endpoint{
            URL:           "AIOZ_STORAGE_ENDPOINT_URL",
            SigningRegion: "us-east-1",
        }, nil
    })
 
    credentials := aws.CredentialsProviderFunc(func(ctx context.Context) (aws.Credentials, error) {
        return aws.Credentials{
            AccessKeyID:     "YOUR_ACCESS_KEY",
            SecretAccessKey: "YOUR_SECRET_KEY",
        }, nil
    })
 
    cfg, err := config.LoadDefaultConfig(context.TODO(),
        config.WithCredentialsProvider(credentials),
        config.WithEndpointResolverWithOptions(resolver),
    )
    if err != nil {
        log.Fatal(err)
    }
 
    client := s3vectors.NewFromConfig(cfg)
 
    _, err = client.CreateVectorBucket(context.TODO(), &s3vectors.CreateVectorBucketInput{
        VectorBucketName: aws.String("YOUR_BUCKET_NAME"),
    })
    if err != nil {
        log.Fatal(err)
    }
}

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).

dimension := int32(1536)
_, err = client.CreateIndex(context.TODO(), &s3vectors.CreateIndexInput{
    VectorBucketName: aws.String("YOUR_BUCKET_NAME"),
    IndexName:        aws.String("my-index"),
    DataType:         types.VectorDataTypeFloat32,
    Dimension:        &dimension,
    DistanceMetric:   types.DistanceMetricCosine,
})
if err != nil {
    log.Fatal(err)
}

5. Put Vectors

Store vector embeddings along with optional metadata:

_, err = client.PutVectors(context.TODO(), &s3vectors.PutVectorsInput{
    VectorBucketName: aws.String("YOUR_BUCKET_NAME"),
    IndexName:        aws.String("my-index"),
    Vectors: []types.PutInputVector{
        {
            Key:  aws.String("doc-001"),
            Data: &types.VectorDataMemberFloat32{Value: []float32{0.12, 0.87, 0.45}},
            Metadata: map[string]interface{}{
                "title":  "Introduction to AI",
                "source": "blog",
            },
        },
        {
            Key:  aws.String("doc-002"),
            Data: &types.VectorDataMemberFloat32{Value: []float32{0.33, 0.61, 0.72}},
            Metadata: map[string]interface{}{
                "title":  "Vector Search Explained",
                "source": "docs",
            },
        },
    },
})
if err != nil {
    log.Fatal(err)
}

6. Query Vectors

Find the most similar vectors to a given query embedding:

topK := int32(5)
response, err := client.QueryVectors(context.TODO(), &s3vectors.QueryVectorsInput{
    VectorBucketName: aws.String("YOUR_BUCKET_NAME"),
    IndexName:        aws.String("my-index"),
    QueryVector:      &types.VectorDataMemberFloat32{Value: []float32{0.11, 0.85, 0.47}},
    TopK:             &topK,
    ReturnMetadata:   true,
    ReturnDistance:   true,
})
if err != nil {
    log.Fatal(err)
}
 
for _, match := range response.Vectors {
    log.Printf("Key: %s  Distance: %f  Metadata: %v\n", *match.Key, *match.Distance, match.Metadata)
}

7. Delete Vectors

Remove vectors from the index by their keys:

_, err = client.DeleteVectors(context.TODO(), &s3vectors.DeleteVectorsInput{
    VectorBucketName: aws.String("YOUR_BUCKET_NAME"),
    IndexName:        aws.String("my-index"),
    Keys:             []string{"doc-001", "doc-002"},
})
if err != nil {
    log.Fatal(err)
}

Minimal Code Example

package main
 
import (
    "context"
    "log"
 
    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3vectors"
    "github.com/aws/aws-sdk-go-v2/service/s3vectors/types"
)
 
func main() {
    resolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
        return aws.Endpoint{
            URL:           "AIOZ_STORAGE_ENDPOINT_URL",
            SigningRegion: "us-east-1",
        }, nil
    })
 
    credentials := aws.CredentialsProviderFunc(func(ctx context.Context) (aws.Credentials, error) {
        return aws.Credentials{
            AccessKeyID:     "YOUR_ACCESS_KEY",
            SecretAccessKey: "YOUR_SECRET_KEY",
        }, nil
    })
 
    cfg, err := config.LoadDefaultConfig(context.TODO(),
        config.WithCredentialsProvider(credentials),
        config.WithEndpointResolverWithOptions(resolver),
    )
    if err != nil {
        log.Fatal(err)
    }
 
    client := s3vectors.NewFromConfig(cfg)
 
    // Create vector bucket
    _, err = client.CreateVectorBucket(context.TODO(), &s3vectors.CreateVectorBucketInput{
        VectorBucketName: aws.String("YOUR_BUCKET_NAME"),
    })
    if err != nil {
        log.Fatal(err)
    }
 
    // Create index
    dimension := int32(3)
    _, err = client.CreateIndex(context.TODO(), &s3vectors.CreateIndexInput{
        VectorBucketName: aws.String("YOUR_BUCKET_NAME"),
        IndexName:        aws.String("my-index"),
        DataType:         types.VectorDataTypeFloat32,
        Dimension:        &dimension,
        DistanceMetric:   types.DistanceMetricCosine,
    })
    if err != nil {
        log.Fatal(err)
    }
 
    // Store vectors
    _, err = client.PutVectors(context.TODO(), &s3vectors.PutVectorsInput{
        VectorBucketName: aws.String("YOUR_BUCKET_NAME"),
        IndexName:        aws.String("my-index"),
        Vectors: []types.PutInputVector{
            {
                Key:  aws.String("doc-001"),
                Data: &types.VectorDataMemberFloat32{Value: []float32{0.12, 0.87, 0.45}},
                Metadata: map[string]interface{}{
                    "title": "Example document",
                },
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }
 
    // Query similar vectors
    topK := int32(5)
    response, err := client.QueryVectors(context.TODO(), &s3vectors.QueryVectorsInput{
        VectorBucketName: aws.String("YOUR_BUCKET_NAME"),
        IndexName:        aws.String("my-index"),
        QueryVector:      &types.VectorDataMemberFloat32{Value: []float32{0.11, 0.85, 0.47}},
        TopK:             &topK,
        ReturnMetadata:   true,
        ReturnDistance:   true,
    })
    if err != nil {
        log.Fatal(err)
    }
 
    for _, match := range response.Vectors {
        log.Printf("Key: %s  Distance: %f  Metadata: %v\n", *match.Key, *match.Distance, match.Metadata)
    }
}

Learn More

To learn how vector storage works and why AIOZ Storage supports it through the S3 API, read the Vector Database concept page.