Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt

Use this file to discover all available pages before exploring further.

Client is the main struct exposed by the CyborgDB Go SDK. It provides a high-level interface to interact with the CyborgDB vector database service, allowing you to create and manage encrypted indexes.

​
Constructor

func NewClient(baseURL, apiKey string, verifySSL ...bool) (*Client, error)
Creates a new CyborgDB Client instance for connecting to a CyborgDB microservice.

​
Parameters

ParameterTypeDescription
baseURLstringBase URL of the CyborgDB microservice endpoint
apiKeystringAPI key for authentication with the microservice
verifySSL...bool(Optional) SSL verification setting. If omitted, auto-detects based on URL
You can get an API key from the CyborgDB Admin Dashboard. For more info, follow this guide.

​
Example Usage

package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/cyborginc/cyborgdb-go"
)

func main() {
    // Create client with API key
    client, err := cyborgdb.NewClient("http://localhost:8000", "your-api-key")
    if err != nil {
        log.Fatal(err)
    }
    
    // Test the connection
    ctx := context.Background()
    health, err := client.GetHealth(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Service health: %+v\n", health)
}

​
Error Handling

The Client struct includes comprehensive error handling that processes different types of API errors:
  • HTTP Errors: Status codes and response details are logged and converted to meaningful error messages
  • Validation Errors: Field validation failures are formatted with detailed information
  • Network Errors: Connection and timeout issues are handled gracefully
All methods return Go-idiomatic error values as the second return parameter for easy error checking and handling in your application.

​
Type Safety

The Go SDK provides full type safety with strongly typed method parameters and return values, IDE support with autocomplete and documentation, and compile-time validation of API usage.

​
Error Variables

The SDK exports specific error variables that you can check for particular error conditions:

​
Client Errors

import "github.com/cyborginc/cyborgdb-go"

// ErrInvalidKeyLength is returned when an index key is not exactly 32 bytes
var ErrInvalidKeyLength = fmt.Errorf("index key must be exactly 32 bytes")

// ErrKeyGeneration is returned when key generation fails
var ErrKeyGeneration = fmt.Errorf("failed to generate key")

// ErrInvalidURL is returned when the base URL is invalid
var ErrInvalidURL = fmt.Errorf("invalid base URL")

​
EncryptedIndex Errors

// ErrQueryVectorsInvalidType is returned when query vectors have invalid types
var ErrQueryVectorsInvalidType = errors.New("queryVectors must be []float32 for single vector queries or [][]float32 for batch queries")

// ErrMissingQueryInput is returned when no query input is provided
var ErrMissingQueryInput = errors.New("either queryVectors or queryContents must be provided")

// ErrUnexpectedTrainingStatus is returned when training status response is unexpected
var ErrUnexpectedTrainingStatus = errors.New("unexpected training status response format")

// ErrEmptyIDs is returned when IDs slice is empty
var ErrEmptyIDs = errors.New("IDs cannot be empty")

// ErrEmptyVectors is returned when vectors slice is empty
var ErrEmptyVectors = errors.New("vectors cannot be empty")

// ErrEmptyQueryVectors is returned when query vectors slice is empty
var ErrEmptyQueryVectors = errors.New("queryVectors cannot be empty")

// ErrIDsVectorsLengthMismatch is returned when IDs and vectors have different lengths
var ErrIDsVectorsLengthMismatch = errors.New("IDs length must match vectors length")

// ErrMetadataLengthMismatch is returned when metadata length doesn't match IDs length
var ErrMetadataLengthMismatch = errors.New("metadata length must match IDs length")

// ErrContentsLengthMismatch is returned when contents length doesn't match IDs length
var ErrContentsLengthMismatch = errors.New("contents length must match IDs length")

// ErrUnsupportedUpsertType is returned when Upsert receives an unsupported input type
var ErrUnsupportedUpsertType = errors.New("unsupported upsert input type")

// ErrUnsupportedQueryType is returned when Query receives an unsupported params type
var ErrUnsupportedQueryType = errors.New("unsupported query input type")

​
Example Usage

import (
    "errors"
    "fmt"
    "log"

    "github.com/cyborginc/cyborgdb-go"
)

func createIndex(client *cyborgdb.Client, key []byte) error {
    params := &cyborgdb.CreateIndexParams{
        IndexName: "my-index",
        IndexKey:  key,
        IndexConfig: cyborgdb.IndexIVFFlat(768),
    }

    _, err := client.CreateIndex(context.Background(), params)
    if err != nil {
        // Check for specific error types
        if errors.Is(err, cyborgdb.ErrInvalidKeyLength) {
            return fmt.Errorf("provided key has wrong length: %w", err)
        }
        return fmt.Errorf("failed to create index: %w", err)
    }

    return nil
}