A clean, idiomatic Go client library for hlquery, designed with a familiar and intuitive API structure.

What is the hlquery Go API?

The hlquery Go API is the official Go client for hlquery. It wraps the server's HTTP interface in a small, standard-library-friendly client that exposes collections, documents, search, SQL, and SAM helpers.

It is aimed at backend services, internal tools, and API servers that want hlquery integration without managing low-level HTTP details everywhere.

Why use it?

Use it when you want a small, idiomatic Go surface with response helpers for status checks and parsed bodies, consistent auth handling, and direct access to both convenience methods and raw request execution.

Install

$ go get github.com/hlquery/go-api/client

Or add it to go.mod:

require github.com/hlquery/go-api v0.1.0

Quick Start

package main

import (
    "fmt"
    "log"
    "os"

    hlquery "github.com/hlquery/go-api/client"
)

func main() {
    baseURL := os.Getenv("HLQ_BASE_URL")
    if baseURL == "" {
        baseURL = os.Getenv("HLQUERY_BASE_URL")
    }
    if baseURL == "" {
        baseURL = "http://localhost:9200"
    }

    client := hlquery.NewClient(baseURL)

    health, err := client.Health()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Status: %d\n", health.StatusCode)

    collections, err := client.ListCollections(0, 10)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(collections.Body)
}

Auth

client := hlquery.NewClient("http://localhost:9200", hlquery.ClientOptions{
    Token:      "your_token_here",
    AuthMethod: "bearer",
})

client.SetAuthToken("your_token_here", "bearer")
client.SetAuthToken("your_api_key_here", "api-key")

SAM

SAM is separate from vector search. It performs term and intent-style lookup, not vector similarity search.

sam := client.SAMAPI()

status, _ := sam.Status("music")
history, _ := sam.History("music", 5)
results, _ := sam.Search("music", "queen of pop", map[string]interface{}{
    "limit": 10,
})

fmt.Println(status.Body)
fmt.Println(history.Body)
fmt.Println(results.Body)

SQL

sqlAPI := client.SQLAPI()

rows, _ := sqlAPI.Query("SHOW COLLECTIONS;")
products, _ := sqlAPI.Search(
    "products",
    "SELECT id, title, price FROM products ORDER BY price DESC LIMIT 3;",
    nil,
)

fmt.Println(rows.Body)
fmt.Println(products.Body)

Reduce Text Example

Use the raw request helper for custom module routes:

moduleResponse, err := client.ExecuteRequest(
    "GET",
    "/modules/<name>/<route>?q=example",
    nil,
)
if err != nil {
    log.Fatal(err)
}

fmt.Println(moduleResponse.Body)

Contributing

We welcome contributions from the community! All contributions must be released under the BSD 3-Clause license.

How to Contribute

• Check existing issues or create new ones
• Contribute to client libraries (Node.js, Go, Java, Python, PHP, Ruby, Rust, Perl, C++)
• Test and report bugs
• Improve documentation

Community

• 📖 Documentation
• 🐦 X (Twitter)
• 📦 GitHub

License

hlquery is licensed under the BSD 3-Clause License.