API ReferenceGo API Documentation

Cagra Package

View as Markdown

Go package: cagra

Sources: go/cagra

Constants

BuildAlgo Constants

1const (
2IvfPq BuildAlgo = iota
3NnDescent
4AutoSelect
5)

Source: go/cagra/index_params.go:23

HashmapMode Constants

1const (
2HashmapModeHash HashmapMode = iota
3HashmapModeSmall
4HashmapModeAuto
5)

Source: go/cagra/search_params.go:28

SearchAlgo Constants

1const (
2SearchAlgoSingleCta SearchAlgo = iota
3SearchAlgoMultiCta
4SearchAlgoMultiKernel
5SearchAlgoAuto
6)

Source: go/cagra/search_params.go:19

Types

BuildAlgo

1type BuildAlgo int

Source: go/cagra/index_params.go:21

CagraIndex

1type CagraIndex struct { ... }

Cagra ANN Index

Source: go/cagra/cagra.go:14

CompressionParams

1type CompressionParams struct { ... }

Supplemental parameters to build CAGRA Index

Source: go/cagra/index_params.go:17

ExtendParams

1type ExtendParams struct { ... }

Parameters to extend CAGRA Index

Source: go/cagra/extend_params.go:11

HashmapMode

1type HashmapMode int

Source: go/cagra/search_params.go:26

IndexParams

1type IndexParams struct { ... }

Source: go/cagra/index_params.go:12

SearchAlgo

1type SearchAlgo int

Source: go/cagra/search_params.go:17

SearchParams

1type SearchParams struct { ... }

Supplemental parameters to search CAGRA Index

Source: go/cagra/search_params.go:13

Functions

BuildIndex

1func BuildIndex[T any](Resources cuvs.Resource, params *IndexParams, dataset *cuvs.Tensor[T], index *CagraIndex) error

Builds a new Index from the dataset for efficient search.

Arguments

  • Resources - Resources to use
  • params - Parameters for building the index
  • dataset - A row-major Tensor on either the host or device to index
  • index - CagraIndex to build

Source: go/cagra/cagra.go:38

CreateCompressionParams

1func CreateCompressionParams() (*CompressionParams, error)

Creates a new CompressionParams

Source: go/cagra/index_params.go:36

CreateExtendParams

1func CreateExtendParams() (*ExtendParams, error)

Creates a new ExtendParams

Source: go/cagra/extend_params.go:16

CreateIndex

1func CreateIndex() (*CagraIndex, error)

Creates a new empty Cagra Index

Source: go/cagra/cagra.go:20

CreateIndexParams

1func CreateIndexParams() (*IndexParams, error)

Creates a new IndexParams

Source: go/cagra/index_params.go:99

CreateSearchParams

1func CreateSearchParams() (*SearchParams, error)

Creates a new SearchParams

Source: go/cagra/search_params.go:35

ExtendIndex

1func ExtendIndex[T any](Resources cuvs.Resource, params *ExtendParams, additional_dataset *cuvs.Tensor[T], index *CagraIndex) error

Extends the index with additional data

Arguments

  • Resources - Resources to use
  • params - Parameters for extending the index
  • additional_dataset - A row-major Tensor on the device to extend the index with
  • index - CagraIndex to extend

Source: go/cagra/cagra.go:55

SearchIndex

1func SearchIndex[T any](Resources cuvs.Resource, params *SearchParams, index *CagraIndex, queries *cuvs.Tensor[T], neighbors *cuvs.Tensor[uint32], distances *cuvs.Tensor[T], allowList []uint32) error

Perform a Approximate Nearest Neighbors search on the Index

Arguments

  • Resources - Resources to use
  • params - Parameters to use in searching the index
  • queries - A tensor in device memory to query for
  • neighbors - Tensor in device memory that receives the indices of the nearest neighbors
  • distances - Tensor in device memory that receives the distances of the nearest neighbors
  • allowList - List of indices to allow in the search, if nil, no filtering is applied

Source: go/cagra/cagra.go:85

Methods

CagraIndex.Close

1func (index *CagraIndex) Close() error

Destroys the Cagra Index

Source: go/cagra/cagra.go:67

CompressionParams.SetKMeansNIters

1func (p *CompressionParams) SetKMeansNIters(kmeans_n_iters uint32) (*CompressionParams, error)

The number of iterations searching for kmeans centers (both VQ & PQ phases).

Source: go/cagra/index_params.go:76

CompressionParams.SetPQBits

1func (p *CompressionParams) SetPQBits(pq_bits uint32) (*CompressionParams, error)

The bit length of the vector element after compression by PQ.

Source: go/cagra/index_params.go:52

CompressionParams.SetPQDim

1func (p *CompressionParams) SetPQDim(pq_dim uint32) (*CompressionParams, error)

The dimensionality of the vector after compression by PQ. When zero, an optimal value is selected using a heuristic.

Source: go/cagra/index_params.go:60

CompressionParams.SetPQKMeansTrainsetFraction

1func (p *CompressionParams) SetPQKMeansTrainsetFraction(pq_kmeans_trainset_fraction float64) (*CompressionParams, error)

The fraction of data to use during iterative kmeans building (PQ phase). When zero, an optimal value is selected using a heuristic.

Source: go/cagra/index_params.go:92

CompressionParams.SetVQKMeansTrainsetFraction

1func (p *CompressionParams) SetVQKMeansTrainsetFraction(vq_kmeans_trainset_fraction float64) (*CompressionParams, error)

The fraction of data to use during iterative kmeans building (VQ phase). When zero, an optimal value is selected using a heuristic.

Source: go/cagra/index_params.go:84

CompressionParams.SetVQNCenters

1func (p *CompressionParams) SetVQNCenters(vq_n_centers uint32) (*CompressionParams, error)

Vector Quantization (VQ) codebook size - number of “coarse cluster centers”. When zero, an optimal value is selected using a heuristic.

Source: go/cagra/index_params.go:68

ExtendParams.Close

1func (p *ExtendParams) Close() error

Source: go/cagra/extend_params.go:40

ExtendParams.SetMaxChunkSize

1func (p *ExtendParams) SetMaxChunkSize(max_chunk_size uint32) (*ExtendParams, error)

The additional dataset is divided into chunks and added to the graph. This is the knob to adjust the tradeoff between the recall and operation throughput. Large chunk sizes can result in high throughput, but use more working memory (O(max_chunk_size*degree^2)). This can also degrade recall because no edges are added between the nodes in the same chunk. Auto select when 0.

Source: go/cagra/extend_params.go:35

IndexParams.Close

1func (p *IndexParams) Close() error

Destroys IndexParams

Source: go/cagra/index_params.go:152

IndexParams.SetBuildAlgo

1func (p *IndexParams) SetBuildAlgo(build_algo BuildAlgo) (*IndexParams, error)

ANN algorithm to build knn graph

Source: go/cagra/index_params.go:126

IndexParams.SetCompression

1func (p *IndexParams) SetCompression(compression *CompressionParams) (*IndexParams, error)

Compression parameters

Source: go/cagra/index_params.go:145

IndexParams.SetGraphDegree

1func (p *IndexParams) SetGraphDegree(intermediate_graph_degree uintptr) (*IndexParams, error)

Degree of output graph

Source: go/cagra/index_params.go:119

IndexParams.SetIntermediateGraphDegree

1func (p *IndexParams) SetIntermediateGraphDegree(intermediate_graph_degree uintptr) (*IndexParams, error)

Degree of input graph for pruning

Source: go/cagra/index_params.go:113

IndexParams.SetNNDescentNiter

1func (p *IndexParams) SetNNDescentNiter(nn_descent_niter uint32) (*IndexParams, error)

Number of iterations to run if building with NN_DESCENT

Source: go/cagra/index_params.go:138

SearchParams.Close

1func (p *SearchParams) Close() error

Destroys SearchParams

Source: go/cagra/search_params.go:157

SearchParams.SetAlgo

1func (p *SearchParams) SetAlgo(algo SearchAlgo) (*SearchParams, error)

Which search implementation to use.

Source: go/cagra/search_params.go:67

SearchParams.SetHashmapMaxFillRate

1func (p *SearchParams) SetHashmapMaxFillRate(hashmap_max_fill_rate float32) (*SearchParams, error)

Upper limit of hashmap fill rate. More than 0.1, less than 0.9.

Source: go/cagra/search_params.go:139

SearchParams.SetHashmapMinBitlen

1func (p *SearchParams) SetHashmapMinBitlen(hashmap_min_bitlen uintptr) (*SearchParams, error)

Lower limit of hashmap bit length. More than 8.

Source: go/cagra/search_params.go:133

SearchParams.SetHashmapMode

1func (p *SearchParams) SetHashmapMode(hashmap_mode HashmapMode) (*SearchParams, error)

Hashmap type. Auto selection when AUTO.

Source: go/cagra/search_params.go:113

SearchParams.SetItopkSize

1func (p *SearchParams) SetItopkSize(itopk_size uintptr) (*SearchParams, error)

Number of intermediate search results retained during the search. This is the main knob to adjust trade off between accuracy and search speed. Higher values improve the search accuracy

Source: go/cagra/search_params.go:55

SearchParams.SetMaxIterations

1func (p *SearchParams) SetMaxIterations(max_iterations uintptr) (*SearchParams, error)

Upper limit of search iterations. Auto select when 0.

Source: go/cagra/search_params.go:61

SearchParams.SetMaxQueries

1func (p *SearchParams) SetMaxQueries(max_queries uintptr) (*SearchParams, error)

Maximum number of queries to search at the same time (batch size). Auto select when 0

Source: go/cagra/search_params.go:47

SearchParams.SetMinIterations

1func (p *SearchParams) SetMinIterations(min_iterations uintptr) (*SearchParams, error)

Lower limit of search iterations.

Source: go/cagra/search_params.go:95

SearchParams.SetNumRandomSamplings

1func (p *SearchParams) SetNumRandomSamplings(num_random_samplings uint32) (*SearchParams, error)

Number of iterations of initial random seed node selection. 1 or more.

Source: go/cagra/search_params.go:145

SearchParams.SetRandXorMask

1func (p *SearchParams) SetRandXorMask(rand_xor_mask uint64) (*SearchParams, error)

Bit mask used for initial random seed node selection.

Source: go/cagra/search_params.go:151

SearchParams.SetSearchWidth

1func (p *SearchParams) SetSearchWidth(search_width uintptr) (*SearchParams, error)

How many nodes to search at once. Auto select when 0.

Source: go/cagra/search_params.go:101

SearchParams.SetTeamSize

1func (p *SearchParams) SetTeamSize(team_size uintptr) (*SearchParams, error)

Number of threads used to calculate a single distance. 4, 8, 16, or 32.

Source: go/cagra/search_params.go:89

SearchParams.SetThreadBlockSize

1func (p *SearchParams) SetThreadBlockSize(thread_block_size uintptr) (*SearchParams, error)

Thread block size. 0, 64, 128, 256, 512, 1024. Auto selection when 0.

Source: go/cagra/search_params.go:107