avs

package module
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 11, 2025 License: Apache-2.0 Imports: 24 Imported by: 0

README

codecov

Aerospike Vector Search Go Client

⚠ The go client is currently in development. APIs will break in the future!

Overview

This repository contains the Go client for interacting with Aerospike Vector Search (AVS) capabilities. It is designed to provide an easy-to-use interface for performing vector searches with an Aerospike cluster.

Current Functionality

  • Connection to Aerospike clusters
  • Create, List, Drop Indexes

Installation

To install the Aerospike Vector Search Go Client, use the following command:

go get github.com/aerospike/avs-client-go

Example Usage

Here's a quick example to get you started:

package main

import (
	"context"
	"fmt"
	"log/slog"
	"os"
	"time"

	avs "github.com/aerospike/avs-client-go"
	"github.com/aerospike/avs-client-go/protos"
)

func main() {
	connectCtx, cancel := context.WithTimeout(context.Background(), time.Second*5)
	hostPort := NewHostPort("127.0.0.1", 5000)
	loadBalancer := true
	credentials := NewCredentialsFromUserPass("admin", "admin")
	logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelDebug}))

	var (
		listenerName *string
		tlsConfig *tls.Config
	)

	client, err := avs.NewClient(
		connectCtx,
		HostPortSlice{hostPort},
		listenerName,
		loadBalancer,
		credentials
		tlsConfig,
		logger,
	)
	cancel()

	if err != nil {
		logger.Error("failed to create admin client", slog.Any("error", err))
		return
	}

	logger.Info("successfully connected to server")
	defer client.Close()

	namespace := "test"
	indexName := "bookIndex"
	vectorField := "vector"
	dimensions := uint32(10)
	distanceMetric := protos.VectorDistanceMetric_MANHATTAN
	indexOpts := &IndexCreateOpts{
		Set: []string{"testset"}
	}

	err = client.IndexCreate(
		context.Background(),
		namespace,
		indexName,
		vectorField,
		dimensions,
		distanceMetric,
		indexOpts,
	)
	if err != nil {
		logger.Error("failed to create index", slog.Any("error", err))
		return
	}

	logger.Info("successfully created index")

	indexes, err := client.IndexList(context.Background(), true)
	if err != nil {
		logger.Error("failed to list indexes", slog.Any("error", err))
		return
	}

	for _, index := range indexes.GetIndices() {
		fmt.Println(index.String())
	}

	err = client.IndexDrop(context.Background(), namespace, indexName)
	if err != nil {
		logger.Error("failed to drop index", slog.Any("error", err))
		return
	}

	logger.Info("successfully dropped index")
	logger.Info("done!")
}

License

This project is licensed under the Apache License 2.0

Documentation

Overview

Package avs provides a client for managing Aerospike Vector Indexes.

Package avs provides a connection provider for connecting to Aerospike servers.

Index

Constants

This section is empty.

Variables

View Source 
var AerospikeEpoch = time.Date(2010, 1, 1, 0, 0, 0, 0, time.UTC)
View Source 
var ErrNotImplemented = errors.New("not implemented")

Functions

This section is empty.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a client for managing Aerospike Vector Indexes.

func NewClient 

func NewClient(
	ctx context.Context,
	seeds HostPortSlice,
	listenerName *string,
	isLoadBalancer bool,
	credentials *UserPassCredentials,
	tlsConfig *tls.Config,
	logger *slog.Logger,
) (*Client, error)

NewClient creates a new Client instance.

Args: 

ctx (context.Context): The context for the operation.
seeds (HostPortSlice): A list of seed hosts to connect to.
listenerName (*string): The name of the listener to connect to as configured on the server.
isLoadBalancer (bool): Whether the client should consider the seed a load balancer.
Only the first seed is considered. Subsequent seeds are ignored.
credentials (*UserPassCredentials): The credentials to authenticate with.
tlsConfig (*tls.Config): The TLS configuration to use for the connection.
logger (*slog.Logger): The logger to use for logging.

Returns: 

*Client: A new Client instance.
error: An error if the client creation fails, otherwise nil.

func (*Client) About 

func (c *Client) About(ctx context.Context, nodeID *protos.NodeId) (*protos.AboutResponse, error)

About returns information about the provided node.

Args: 

ctx (context.Context): The context for the operation.
nodeID (*protos.NodeId): The ID of the node. If nil, the seed node is used.

Returns: 

*protos.AboutResponse: Information about the node.
error: An error if the retrieval fails, otherwise nil.

func (*Client) Close 

func (c *Client) Close() error

Close closes the Client and releases any resources associated with it.

Returns: 

error: An error if the closure fails, otherwise nil.

func (*Client) ClusterEndpoints 

func (c *Client) ClusterEndpoints(
	ctx context.Context,
	nodeID *protos.NodeId,
	listenerName *string,
) (*protos.ClusterNodeEndpoints, error)

ClusterEndpoints returns the endpoints of all the nodes in the cluster according to the specified node.

Args: 

ctx (context.Context): The context for the operation.
nodeID (*protos.NodeId): The ID of the node. If nil, the seed node is used.
listenerName (*string): The name of the listener. If nil, the default listener is used.

Returns: 

*protos.ClusterNodeEndpoints: The cluster node endpoints.
error: An error if the retrieval fails, otherwise nil.

func (*Client) ClusteringState 

func (c *Client) ClusteringState(ctx context.Context, nodeID *protos.NodeId) (*protos.ClusteringState, error)

ClusteringState returns the state of the cluster according to the given node.

Args: 

ctx (context.Context): The context for the operation.
nodeID (*protos.NodeId): The ID of the node. If nil, the seed node is used.

Returns: 

*protos.ClusteringState: The clustering state.
error: An error if the retrieval fails, otherwise nil.

func (*Client) ConnectedNodeEndpoint 

func (c *Client) ConnectedNodeEndpoint(
	ctx context.Context,
	nodeID *protos.NodeId,
) (*protos.ServerEndpoint, error)

ConnectedNodeEndpoint returns the endpoint used to connect to a node.

Args: 

ctx (context.Context): The context for the operation.
nodeID (*protos.NodeId): The ID of the node. If nil, the seed (or LB) node is used.

Returns: 

*protos.ServerEndpoint: The server endpoint.
error: An error if the retrieval fails, otherwise nil.

func (*Client) CreateUser 

func (c *Client) CreateUser(ctx context.Context, username, password string, roles []string) error

CreateUser creates a new user with the provided username, password, and roles.

Args: 

ctx (context.Context): The context for the operation.
username (string): The username of the new user.
password (string): The password for the new user.
roles ([]string): The roles to assign to the new user.

Returns: 

error: An error if the user creation fails, otherwise nil.

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, namespace string, set *string, key any) error

Delete removes a record from the database.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the record to delete.
set (*string): The set within the namespace where the record resides.
key (any): The key of the record to delete.

Returns: 

error: An error if the deletion fails, otherwise nil.

func (*Client) DropUser 

func (c *Client) DropUser(ctx context.Context, username string) error

DropUser deletes the user with the provided username.

Args: 

ctx (context.Context): The context for the operation.
username (string): The username of the user to delete.

Returns: 

error: An error if the user deletion fails, otherwise nil.

func (*Client) Exists 

func (c *Client) Exists(
	ctx context.Context,
	namespace string,
	set *string,
	key any,
) (bool, error)

Exists checks if a record exists in the specified namespace and set.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the record to check.
set (*string): The set within the namespace where the record resides.
key (any): The key of the record to check.

Returns: 

bool: True if the record exists, false otherwise.
error: An error if the existence check fails, otherwise nil.

func (*Client) GcInvalidVertices 

func (c *Client) GcInvalidVertices(ctx context.Context, namespace, indexName string, cutoffTime time.Time) error

GcInvalidVertices garbage collects invalid vertices in an Aerospike Vector Index.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the index.
indexName (string): The name of the index.
cutoffTime (time.Time): The cutoff time for the garbage collection.

Returns: 

error: An error if the garbage collection fails, otherwise nil.

func (*Client) Get 

func (c *Client) Get(ctx context.Context,
	namespace string,
	set *string,
	key any,
	includeFields []string,
	excludeFields []string,
) (*Record, error)

Get retrieves a record from the specified namespace and set. If the record does not exist, an error is returned.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the record to retrieve.
set (*string): The set within the namespace where the record resides.
key (any): The key of the record to retrieve.
includeFields ([]string): Fields to include in the response. Default is all.
excludeFields ([]string): Fields to exclude from the response. Default is none.

Returns: 

*Record: The retrieved record.
error: An error if the retrieval fails, otherwise nil.

func (*Client) GetUser 

func (c *Client) GetUser(ctx context.Context, username string) (*protos.User, error)

GetUser returns the user with the provided username.

Args: 

ctx (context.Context): The context for the operation.
username (string): The username of the user to retrieve.

Returns: 

*protos.User: The retrieved user.
error: An error if the user retrieval fails, otherwise nil.

func (*Client) GrantRoles 

func (c *Client) GrantRoles(ctx context.Context, username string, roles []string) error

GrantRoles grants the provided roles to the user with the provided username.

Args: 

ctx (context.Context): The context for the operation.
username (string): The username of the user.
roles ([]string): The roles to grant to the user.

Returns: 

error: An error if the role grant fails, otherwise nil.

func (*Client) IndexCreate 

func (c *Client) IndexCreate(
	ctx context.Context,
	namespace string,
	indexName string,
	vectorField string,
	dimensions uint32,
	vectorDistanceMetric protos.VectorDistanceMetric,
	opts *IndexCreateOpts,
) error

IndexCreate creates a new Aerospike Vector Index.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the index.
indexName (string): The name of the index.
vectorField (string): The field to create the index on.
dimensions (uint32): The number of dimensions in the vector.
vectorDistanceMetric (protos.VectorDistanceMetric): The distance metric to use for the index.
opts (*IndexCreateOpts): Optional fields to configure the index.

Returns: 

error: An error if the index creation fails, otherwise nil.

func (*Client) IndexCreateFromIndexDef 

func (c *Client) IndexCreateFromIndexDef(
	ctx context.Context,
	indexDef *protos.IndexDefinition,
) error

IndexCreateFromIndexDef creates an HNSW index in AVS from an index definition.

Args: 

ctx (context.Context): The context for the operation.
indexDef (*protos.IndexDefinition): The index definition to create the index from.

Returns: 

error: An error if the index creation fails, otherwise nil.

func (*Client) IndexDrop 

func (c *Client) IndexDrop(ctx context.Context, namespace, indexName string) error

IndexDrop drops an existing Aerospike Vector Index and blocks until it is fully removed.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the index to drop.
indexName (string): The name of the index to drop.

Returns: 

error: An error if the index drop fails, otherwise nil.

func (*Client) IndexGet 

func (c *Client) IndexGet(
	ctx context.Context,
	namespace,
	indexName string,
	applyDefaults bool,
) (*protos.IndexDefinition, error)

IndexGet returns the definition of an Aerospike Vector Index.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the index.
indexName (string): The name of the index.
applyDefaults (bool): Whether to apply server default values to the index definition.

Returns: 

*protos.IndexDefinition: The index definition.
error: An error if the retrieval fails, otherwise nil.

func (*Client) IndexGetStatus 

func (c *Client) IndexGetStatus(ctx context.Context, namespace, indexName string) (*protos.IndexStatusResponse, error)

IndexGetStatus returns the status of an Aerospike Vector Index.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the index.
indexName (string): The name of the index.

Returns: 

*protos.IndexStatusResponse: The index status.
error: An error if the retrieval fails, otherwise nil.

func (*Client) IndexList 

func (c *Client) IndexList(ctx context.Context, applyDefaults bool) (*protos.IndexDefinitionList, error)

IndexList returns a list of all Aerospike Vector Indexes.

Args: 

ctx (context.Context): The context for the operation.
applyDefaults (bool): Whether to apply server default values to the index definitions.

Returns: 

*protos.IndexDefinitionList: A list of index definitions.
error: An error if the list retrieval fails, otherwise nil.

func (*Client) IndexUpdate 

func (c *Client) IndexUpdate(
	ctx context.Context,
	namespace string,
	indexName string,
	labels map[string]string,
	hnswParams *protos.HnswIndexUpdate,
	mode *protos.IndexMode,
) error

IndexUpdate updates an existing Aerospike Vector Index's dynamic configuration parameters.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the index.
name (string): The name of the index.
labels (map[string]string): Labels to update on the index.
hnswParams (*protos.HnswIndexUpdate): The HNSW parameters to update.
mode (*protos.IndexMode): The mode to change the index to.

Returns: 

error: An error if the update fails, otherwise nil.

func (*Client) Insert 

func (c *Client) Insert(
	ctx context.Context,
	namespace string,
	set *string,
	key any,
	recordData map[string]any,
	ignoreMemQueueFull bool,
) error

Insert inserts a new record into the specified namespace and set. If the record already exists, it will fail.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the record to insert.
set (*string): The set within the namespace where the record resides.
key (any): The key of the record to insert.
recordData (map[string]any): The data of the record to insert.
ignoreMemQueueFull (bool): Whether to ignore the in-memory queue full error.

Returns: 

error: An error if the insertion fails, otherwise nil.

func (*Client) IsIndexed 

func (c *Client) IsIndexed(
	ctx context.Context,
	namespace string,
	set *string,
	indexName string,
	key any,
) (bool, error)

IsIndexed checks if a record is indexed in the specified namespace and index.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the record to check.
set (*string): The set within the namespace where the record resides.
indexName (string): The name of the index.
key (any): The key of the record to check.

Returns: 

bool: True if the record is indexed, false otherwise.
error: An error if the index check fails, otherwise nil.

func (*Client) ListRoles 

func (c *Client) ListRoles(ctx context.Context) (*protos.ListRolesResponse, error)

ListRoles returns a list of all roles.

Args: 

ctx (context.Context): The context for the operation.

Returns: 

*protos.ListRolesResponse: A list of all roles.
error: An error if the list retrieval fails, otherwise nil.

func (*Client) ListUsers 

func (c *Client) ListUsers(ctx context.Context) (*protos.ListUsersResponse, error)

ListUsers returns a list of all users.

Args: 

ctx (context.Context): The context for the operation.

Returns: 

*protos.ListUsersResponse: A list of all users.
error: An error if the list retrieval fails, otherwise nil.

func (*Client) NodeIDs 

func (c *Client) NodeIDs(ctx context.Context) []*protos.NodeId

NodeIDs returns a list of all the node IDs that the client is connected to. If load-balancer is set true no NodeIDs will be returned. If a node is accessible but not a part of the cluster it will not be returned.

Args: 

ctx (context.Context): The context for the operation.

Returns: 

[]*protos.NodeId: A list of node IDs.

func (*Client) RevokeRoles 

func (c *Client) RevokeRoles(ctx context.Context, username string, roles []string) error

RevokeRoles revokes the provided roles from the user with the provided username.

Args: 

ctx (context.Context): The context for the operation.
username (string): The username of the user.
roles ([]string): The roles to revoke from the user.

Returns: 

error: An error if the role revocation fails, otherwise nil.

func (*Client) Update 

func (c *Client) Update(
	ctx context.Context,
	namespace string,
	set *string,
	key any,
	recordData map[string]any,
	ignoreMemQueueFull bool,
) error

Update updates a record in the specified namespace and set. If the record does not already exist, it will fail.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the record to update.
set (*string): The set within the namespace where the record resides.
key (any): The key of the record to update.
recordData (map[string]any): The data of the record to update.
ignoreMemQueueFull (bool): Whether to ignore the in-memory queue full error.

Returns: 

error: An error if the update fails, otherwise nil.

func (*Client) UpdateCredentials 

func (c *Client) UpdateCredentials(ctx context.Context, username, password string) error

UpdateCredentials updates the password for the provided username.

Args: 

ctx (context.Context): The context for the operation.
username (string): The username of the user.
password (string): The new password for the user.

Returns: 

error: An error if the credential update fails, otherwise nil.

func (*Client) Upsert 

func (c *Client) Upsert(
	ctx context.Context,
	namespace string,
	set *string,
	key any,
	recordData map[string]any,
	ignoreMemQueueFull bool,
) error

Upsert inserts or updates a record into the specified namespace and set, regardless of whether the record exists.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the record to upsert.
set (*string): The set within the namespace where the record resides.
key (any): The key of the record to upsert.
recordData (map[string]any): The data of the record to upsert.
ignoreMemQueueFull (bool): Whether to ignore the in-memory queue full error.

Returns: 

error: An error if the upsert fails, otherwise nil.

func (*Client) VectorSearchBool 

func (c *Client) VectorSearchBool(ctx context.Context,
	namespace,
	indexName string,
	query []bool,
	limit uint32,
	searchParams *protos.HnswSearchParams,
	includeFields,
	excludeFields []string,
) ([]*Neighbor, error)

VectorSearchBool searches for the nearest neighbors of the query vector in the specified index.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the index.
indexName (string): The name of the index.
query ([]bool): The query vector.
limit (uint32): The maximum number of neighbors to return.
searchParams (*protos.HnswSearchParams): Extra options to configure the behavior of the HNSW algorithm.
includeFields ([]string): Fields to include in the response. Default is all.
excludeFields ([]string): Fields to exclude from the response. Default is none.

Returns: 

[]*Neighbor: A list of the nearest neighbors.
error: An error if the search fails, otherwise nil.

func (*Client) VectorSearchFloat32 

func (c *Client) VectorSearchFloat32(
	ctx context.Context,
	namespace,
	indexName string,
	query []float32,
	limit uint32,
	searchParams *protos.HnswSearchParams,
	includeFields,
	excludeFields []string,
) ([]*Neighbor, error)

VectorSearchFloat32 searches for the nearest neighbors of the query vector in the specified index.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the index.
indexName (string): The name of the index.
query ([]float32): The query vector.
limit (uint32): The maximum number of neighbors to return.
searchParams (*protos.HnswSearchParams): Extra options to configure the behavior of the HNSW algorithm.
includeFields ([]string): Fields to include in the response. Default is all.
excludeFields ([]string): Fields to exclude from the response. Default is none.

Returns: 

[]*Neighbor: A list of the nearest neighbors.
error: An error if the search fails, otherwise nil.

func (*Client) WaitForIndexCompletion 

func (c *Client) WaitForIndexCompletion(
	ctx context.Context,
	namespace,
	indexName string,
	waitInterval time.Duration,
) error

WaitForIndexCompletion waits for an index to be fully created. USE WITH CAUTION. This API will likely break in the future as a mechanism for correctly determining index completion is figured out. The wait interval determines the number of times the unmerged record queue must be of size 0. If the unmerged queue size is not zero, it will immediately return the next time a the unmerged queue size is zero. We have found that a good waitInterval is roughly 12 seconds. If you are expected to have many concurrent writers or a consistent stream of writes this will cause your application to hang.

Args: 

ctx (context.Context): The context for the operation.
namespace (string): The namespace of the index.
indexName (string): The name of the index.
waitInterval (time.Duration): The interval to wait between checks.

Returns: 

error: An error if waiting for the index to complete fails, otherwise nil.

type Error 

type Error struct {
	// contains filtered or unexported fields
}

func NewAVSError 

func NewAVSError(msg string, err error) *Error

func NewAVSErrorFromGrpc 

func NewAVSErrorFromGrpc(msg string, gErr error) *Error

func (*Error) Error 

func (e *Error) Error() string

type HostPort 

type HostPort struct {
	Host string
	Port int
}

func NewHostPort 

func NewHostPort(host string, port int) *HostPort

func (*HostPort) String 

func (hp *HostPort) String() string

type HostPortSlice 

type HostPortSlice []*HostPort

func (HostPortSlice) String 

func (hps HostPortSlice) String() string

type IndexCreateOpts 

type IndexCreateOpts struct {
	Storage    *protos.IndexStorage
	HnswParams *protos.HnswParams
	Mode       *protos.IndexMode
	Labels     map[string]string
	Sets       []string
}

IndexCreateOpts are optional fields to further configure the behavior of your index.

  • Sets: The sets to create the index on. Currently, only one set is supported.
  • Metadata: Extra metadata that can be attached to the index.
  • Storage: The storage configuration for the index. This allows you to configure your index and data to be stored in separate namespaces and/or sets.
  • HNSWParams: Extra options sent to the server to configure behavior of the HNSW algorithm.

type Neighbor 

type Neighbor struct {
	Record    *Record // The record data.
	Set       *string // The set within the namespace where the record resides.
	Key       any     // The key of the record.
	Namespace string  // The namespace of the record.
	Distance  float32 // The distance from the query vector.
}

Neighbor represents a record that is a neighbor to a query vector.

type Record 

type Record struct {
	Data       map[string]any // The data of the record. This includes the vector
	Expiration *time.Time     // The expiration time of the record.
	Generation uint32         // The generation of the record.
}

Record represents a record in the database.

type UserPassCredentials 

type UserPassCredentials struct {
	// contains filtered or unexported fields
}

func NewCredentialsFromUserPass 

func NewCredentialsFromUserPass(username, password string) *UserPassCredentials

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.