usearch

package module
v0.0.0-...-e414f46 Latest Latest
Warning

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

 Go to latest Published: Apr 16, 2025 License: Apache-2.0 Imports: 3 Imported by: 2

README

USearch for GoLang

Installation

Linux

Download and install the Debian package from the latest release. Substitute <release_tag>, <arch>, and <usearch_version> with your settings.

wget https://github.com/unum-cloud/usearch/releases/download/<release_tag>/usearch_linux_<arch>_<usearch_version>.deb
dpkg -i usearch_<arch>_<usearch_version>.deb
Windows

Run the winlibinstaller.bat script from the main repository in the folder where you will run go run. This will install the USearch library and include it in the same folder where the script was run.

.\usearch\winlibinstaller.bat
MacOS

Download and unpack the zip archive from the latest release. Move the USearch library and the include file to their respective folders.

wget https://github.com/unum-cloud/usearch/releases/download/<release_tag>/usearch_macos_<arch>_<usearch_version>.zip
unzip usearch_macos_<arch>_<usearch_version>.zip
sudo mv libusearch_c.dylib /usr/local/lib && sudo mv usearch.h /usr/local/include

Quickstart

  1. Create a go.mod file:
module usearch_example

go <go_version>
  1. Create an example.go:
package main

import (
	"fmt"
	usearch "github.com/unum-cloud/usearch/golang"
)

func main() {

   	// Create Index
   	vectorSize := 3
   	vectorsCount := 100
   	conf := usearch.DefaultConfig(uint(vectorSize))
   	index, err := usearch.NewIndex(conf)
   	if err != nil {
   		panic("Failed to create Index")
   	}
   	defer index.Destroy()

   	// Add to Index
   	err = index.Reserve(uint(vectorsCount))
   	for i := 0; i < vectorsCount; i++ {
   		err = index.Add(usearch.Key(i), []float32{float32(i), float32(i + 1), float32(i + 2)})
      	if err != nil {
      		panic("Failed to add")
      	}
   	}

   	// Search
   	keys, distances, err := index.Search([]float32{0.0, 1.0, 2.0}, 3)
   	if err != nil {
    	panic("Failed to search")
   	}
   	fmt.Println(keys, distances)
}
  1. Get USearch:
go get github.com/unum-cloud/usearch/golang
  1. Run:
go run example.go

Serialization

To save and load the index from disk, use the following methods:

err := index.Save("index.usearch")
if err != nil {
    panic("Failed to save index")
}

err = index.Load("index.usearch")
if err != nil {
    panic("Failed to load index")
}

err = index.View("index.usearch")
if err != nil {
    panic("Failed to view index")
}

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Distance 

func Distance(vec1 []float32, vec2 []float32, dims uint, metric Metric) (float32, error)

Distance computes the distance between two vectors

Types

type Index 

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

Index represents a USearch index.

func NewIndex 

func NewIndex(conf IndexConfig) (index *Index, err error)

NewIndex initializes a new instance of the index with the specified configuration.

func (*Index) Add 

func (index *Index) Add(key Key, vec []float32) error

Add adds a vector with a specified key to the index.

func (*Index) Capacity 

func (index *Index) Capacity() (cap uint, err error)

Capacity returns the capacity (maximum number of vectors) of the index.

func (*Index) ChangeExpansionAdd 

func (index *Index) ChangeExpansionAdd(val uint) error

ChangeExpansionAdd sets the expansion value used during index creation

func (*Index) ChangeExpansionSearch 

func (index *Index) ChangeExpansionSearch(val uint) error

ChangeExpansionSearch sets the expansion value used during search

func (*Index) ChangeThreadsAdd 

func (index *Index) ChangeThreadsAdd(val uint) error

ChangeThreadsAdd sets the threads limit for add

func (*Index) ChangeThreadsSearch 

func (index *Index) ChangeThreadsSearch(val uint) error

ChangeThreadsSearch sets the threads limit for search

func (*Index) Connectivity 

func (index *Index) Connectivity() (con uint, err error)

Connectivity returns the connectivity parameter of the index.

func (*Index) Contains 

func (index *Index) Contains(key Key) (found bool, err error)

Contains checks if the index contains a vector with a specific key.

func (*Index) Destroy 

func (index *Index) Destroy() error

Destroy frees the resources associated with the index.

func (*Index) Dimensions 

func (index *Index) Dimensions() (dim uint, err error)

Dimensions returns the number of dimensions of the vectors in the index.

func (*Index) ExpansionAdd 

func (index *Index) ExpansionAdd() (val uint, err error)

ExpansionAdd returns the expansion value used during index creation

func (*Index) ExpansionSearch 

func (index *Index) ExpansionSearch() (val uint, err error)

ExpansionSearch returns the expansion value used during search

func (*Index) Get 

func (index *Index) Get(key Key, count uint) (vectors []float32, err error)

Get retrieves the vectors associated with the given key from the index.

func (*Index) HardwareAcceleration 

func (index *Index) HardwareAcceleration() (string, error)

HardwareAcceleration returns a string showing the SIMD capability for the index

func (*Index) Len 

func (index *Index) Len() (len uint, err error)

Len returns the number of vectors in the index.

func (*Index) Load 

func (index *Index) Load(path string) error

Load loads the index from a specified file.

func (*Index) LoadBuffer 

func (index *Index) LoadBuffer(buf []byte, buffer_size uint) error

Loads the index from a specified buffer.

func (*Index) MemoryUsage 

func (index *Index) MemoryUsage() (len uint, err error)

MemoryUsage reports the memory usage of the index

func (*Index) Remove 

func (index *Index) Remove(key Key) error

Remove removes the vector associated with the given key from the index.

func (*Index) Rename 

func (index *Index) Rename(from Key, to Key) error

Rename the vector at key from to key to

func (*Index) Reserve 

func (index *Index) Reserve(capacity uint) error

Reserve reserves memory for a specified number of incoming vectors.

func (*Index) Save 

func (index *Index) Save(path string) error

Save saves the index to a specified file.

func (*Index) SaveBuffer 

func (index *Index) SaveBuffer(buf []byte, buffer_size uint) error

Save saves the index to a specified buffer.

func (*Index) Search 

func (index *Index) Search(query []float32, limit uint) (keys []Key, distances []float32, err error)

Search performs k-Approximate Nearest Neighbors Search for the closest vectors to the query vector.

func (*Index) SerializedLength 

func (index *Index) SerializedLength() (len uint, err error)

SerializedLength reports the expected file size after serialization.

func (*Index) View 

func (index *Index) View(path string) error

View creates a view of the index from a specified file without loading it into memory.

func (*Index) ViewBuffer 

func (index *Index) ViewBuffer(buf []byte, buffer_size uint) error

Loads the index from a specified buffer without copying the data.

type IndexConfig 

type IndexConfig struct {
	Quantization    Quantization // The scalar kind used for quantization of vector data during indexing.
	Metric          Metric       // The metric kind used for distance calculation between vectors.
	Dimensions      uint         // The number of dimensions in the vectors to be indexed.
	Connectivity    uint         // The optional connectivity parameter that limits connections-per-node in the graph.
	ExpansionAdd    uint         // The optional expansion factor used for index construction when adding vectors.
	ExpansionSearch uint         // The optional expansion factor used for index construction during search operations.
	Multi           bool         // Indicates whether multiple vectors can map to the same key.
}

IndexConfig represents the configuration options for initializing a USearch index.

func DefaultConfig 

func DefaultConfig(dimensions uint) IndexConfig

DefaultConfig returns an IndexConfig with default values for the specified number of dimensions.

func Metadata 

func Metadata(path string) (c IndexConfig, err error)

Metadata loads the metadata from a specified file.

func MetadataBuffer 

func MetadataBuffer(buf []byte, buffer_size uint) (c IndexConfig, err error)

Loads the metadata from a specified buffer.

type Key 

type Key = uint64

Key represents the type for keys used in the USearch index.

func ExactSearch 

func ExactSearch(dataset []float32, queries []float32, dataset_size uint, queries_size uint,
	dataset_stride uint, queries_stride uint, dims uint, metric Metric,
	count uint, threads uint, keys_stride uint, distances_stride uint) (keys []Key, distances []float32, err error)

ExactSearch is a multithreaded exact nearest neighbors search

type Metric 

type Metric uint8

Metric represents the type for different metrics used in distance calculations. 

const (
	InnerProduct Metric = iota
	Cosine
	L2sq
	Haversine
	Divergence
	Pearson
	Hamming
	Tanimoto
	Sorensen
)

Different metric kinds supported by the USearch library.

func (Metric) CValue 

func (m Metric) CValue() C.usearch_metric_kind_t

func (Metric) String 

func (m Metric) String() string

String returns the string representation of the Metric.

type Quantization 

type Quantization uint8

Quantization represents the type for different scalar kinds used in quantization. 

const (
	F32 Quantization = iota
	BF16
	F16
	F64
	I8
	B1
)

Different quantization kinds supported by the USearch library.

func (Quantization) String 

func (a Quantization) String() string

String returns the string representation of the Quantization.

Source Files

View all Source files

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.