A clean, idiomatic Go client library for hlquery with a familiar service-based API.

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, and SQL 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.

Installation

$ 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)
}

Authentication

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")

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)

Custom Module Routes

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 Go API issues or open a new one
• Contribute Go client changes to hlquery/go-api
• Contribute shared server/API changes to hlquery/hlquery
• Test and report bugs against the Go client
• Improve Go-specific documentation and examples

Search all collections

result, err := client.Search().SearchAll(map[string]interface{}{"q": "research", "limit": 20})
selected, err := client.Search().SearchAllGET(map[string]interface{}{"q": "research", "collections": "universities,science"})

Global and GlobalGET remain available as equivalent names. Results are globally merged and each hit includes document._collection.

Community

• 📖 Documentation
• 🐦 X (Twitter)
• ⚡ Go API GitHub
• 📦 hlquery GitHub

License

The hlquery Go API is licensed under the BSD 3-Clause License.