Go SDK

The official Torque Go SDK provides an HTTP client and TCP binary ingest client. Zero external dependencies — uses only the Go standard library. Requires Go 1.23+.

Installation

Download the Go SDK and add it as a local module:

# Download the SDK
curl -LO https://api.truespar.com/api/versions/torque-sdk-go/latest/download
tar xzf torque-sdk-go-*.tar.gz

# Add to your project
go mod edit -require truespar.com/torque-go@v0.0.0
go mod edit -replace truespar.com/torque-go=./torque-sdk-go-0.5.0

Or download from truespar.com/releases.

HTTP Client

The HttpClient provides full access to the Torque REST API:

package main

import (
    "context"
    "fmt"
    torque "truespar.com/torque-go"
)

func main() {
    client := torque.NewHttpClient("http://localhost:8108", &torque.Options{
        ApiKey: "YOUR_API_KEY",
    })
    defer client.Close()

    // Health check
    health, _ := client.Health(context.Background())
    fmt.Println(health)

    // Search
    result, _ := client.Search(context.Background(), "products", map[string]string{
        "q":        "running shoes",
        "query_by": "title,description",
    })
    for _, hit := range result.Hits {
        fmt.Println(hit.Document["title"])
    }
}

Multi-Node with Failover

client := torque.NewHttpClient("", &torque.Options{
    ApiKey: "YOUR_API_KEY",
    Nodes: []torque.NodeConfig{
        {Host: "node1.example.com", Port: 8108, Protocol: "https"},
        {Host: "node2.example.com", Port: 8108, Protocol: "https"},
    },
    NumRetries: 3,
})

Collection Management

ctx := context.Background()

// Create a collection
schema := map[string]any{
    "name": "products",
    "fields": []map[string]any{
        {"name": "title", "type": "string"},
        {"name": "price", "type": "float", "sort": true},
        {"name": "category", "type": "string", "facet": true},
    },
    "default_sorting_field": "price",
}
client.CreateCollection(ctx, schema)

// List collections
collections, _ := client.ListCollections(ctx)

// Delete a collection
client.DeleteCollection(ctx, "products")

Document Operations

// Import documents (JSONL string, one JSON object per line)
jsonl := `{"id":"1","title":"Running Shoes","price":89.99}
{"id":"2","title":"Laptop Stand","price":49.99}`
results, _ := client.ImportDocuments(ctx, "products", jsonl, "upsert")

// Export documents (returns io.ReadCloser)
exported, _ := client.ExportDocuments(ctx, "products")

// CRUD
client.CreateDocument(ctx, "products", map[string]any{"id": "3", "title": "Mouse"})
doc, _ := client.GetDocument(ctx, "products", "3")
client.UpdateDocument(ctx, "products", "3", map[string]any{"price": 24.99})
client.DeleteDocument(ctx, "products", "3")

TCP Binary Ingestion

The IngestClient provides high-throughput document streaming via the binary TCP protocol:

fields := []torque.FieldDef{
    {Name: "title", Type: "string"},
    {Name: "price", Type: "float"},
    {Name: "category", Type: "string"},
}

var ingest torque.IngestClient
ingest.Connect("localhost", 8109)
defer ingest.Close()

ingest.StartIngest("products")

// Send documents in batches — encoder uses schema for binary encoding
batch := make([]map[string]any, 0, 5000)
for i := 0; i < 100000; i++ {
    batch = append(batch, map[string]any{
        "id":       fmt.Sprintf("product_%d", i),
        "title":    fmt.Sprintf("Product %d", i),
        "price":    9.99 + float64(i)*0.01,
        "category": "Electronics",
    })
    if len(batch) == 5000 {
        ingest.SendBatch(batch, fields)
        batch = batch[:0]
    }
}
if len(batch) > 0 {
    ingest.SendBatch(batch, fields)
}

docsIndexed, _ := ingest.Commit()
fmt.Printf("Indexed %d docs\n", docsIndexed)

TQBF Binary File Writer

The Go SDK can write TQBF binary files for bulk import:

writer := torque.NewBinaryWriter(fields, "output.tqbf")
for i := 0; i < 100000; i++ {
    writer.Write(map[string]any{
        "id":    fmt.Sprintf("p_%d", i),
        "title": fmt.Sprintf("Product %d", i),
        "price": 9.99,
    })
}
writer.Finalize()

// Upload: POST /collections/products/documents/import-binary --data-binary @output.tqbf

Error Handling

The SDK uses typed error structs for different HTTP status codes:

import "errors"

_, err := client.GetCollection(ctx, "nonexistent")
var notFound *torque.ObjectNotFoundError
if errors.As(err, ¬Found) {
    fmt.Println("Collection not found")
}

TCP protocol errors use ProtocolError with an error code and message.