Go SDK

The Go SDK gospice is the easiest way to query Spice.ai from Go.

It uses Apache Arrow Flight to efficiently stream data to the client and Apache Arrow Records as data frames.

GoDocs are available at: pkg.go.dev/github.com/spiceai/gospice.

Requirements

• Go 1.22 (or later)

Installation

Get the gospice package.

go get github.com/spiceai/gospice/v7

Usage

1. Import the package.

import "github.com/spiceai/gospice/v7"

2. Create a SpiceClient by providing your API key. Get your free API key at spice.ai.

spice := gospice.NewSpiceClient()
defer spice.Close()

3. Initialize the SpiceClient.

if err := spice.Init(
    spice.WithApiKey(ApiKey),
    spice.WithSpiceCloudAddress()
); err != nil {
    panic(fmt.Errorf("error initializing SpiceClient: %w", err))
}

4. Execute a query and get back an Apache Arrow Record Reader.

reader, err := spice.Query(context.Background(), "SELECT * FROM tpch.lineitem LIMIT 10")
if err != nil {
    panic(fmt.Errorf("error querying: %w", err))
}
defer reader.Release()

5. Iterate through the reader to access the records.

for reader.Next() {
    record := reader.Record()
    defer record.Release()
    fmt.Println(record)
}

Usage with local Spice runtime

Follow the quickstart guide to install and run spice locally.

spice := gospice.NewSpiceClient()
defer spice.Close()

if err := spice.Init(); err != nil {
    panic(fmt.Errorf("error initializing SpiceClient: %w", err))
}

Or using custom flight address:

spice := gospice.NewSpiceClient()
defer spice.Close()

if err := spice.Init(
    spice.WithFlightAddress("grpc://localhost:50052")
); err != nil {
    panic(fmt.Errorf("error initializing SpiceClient: %w", err))
}

Check Spice OSS documentation to learn more.

Example

Run go run . to execute a sample query and print the results to the console.

Connection retry

The SpiceClient implements connection retry mechanism (3 attempts by default). The number of attempts can be configured via SetMaxRetries:

spice := NewSpiceClient()
spice.SetMaxRetries(5) // Setting to 0 will disable retries

Retries are performed for connection and system internal errors. It is the SDK user's responsibility to properly handle other errors, for example RESOURCE_EXHAUSTED (HTTP 429).

Contributing

Contribute to or file an issue with the gospice library at: https://github.com/spiceai/gospice