Client

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

Parameter	Type	Description
`baseURL`	`string`	Base URL of the CyborgDB microservice endpoint
`apiKey`	`string`	Service authentication credential, sent as the `X-API-Key` header. Pass `""` when the service runs unauthenticated
`verifySSL`	`...bool`	(Optional) SSL verification setting. If omitted, auto-detects based on URL

apiKey is the service authentication credential — the root key or a per-user cdbk_ token, sent as X-API-Key. It is required only when the service runs with CYBORGDB_SERVICE_ROOT_KEY set; against an unauthenticated service (the default), pass "". This is distinct from the service’s CYBORGDB_API_KEY license key. See Managing Keys.

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 (
    "context"
    "errors"
    "fmt"

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

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

    _, 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
}

Introduction

Encrypted Index

Types & Helpers

Client

Constructor

Parameters

Example Usage

Error Handling

Type Safety

Error Variables

Client Errors

EncryptedIndex Errors

Example Usage

​Constructor

​Parameters

​Example Usage

​Error Handling

​Type Safety

​Error Variables

​Client Errors

​EncryptedIndex Errors

​Example Usage

Constructor

Parameters

Example Usage

Error Handling

Type Safety

Error Variables

Client Errors

EncryptedIndex Errors

Example Usage