opensearch

opensearch-go

Go client for OpenSearch and OpenSearch-compatible clusters.

⚠️ v4 is a complete rewrite of the library. Expect breaking changes from v3. Review the v4 migration guide before upgrading. Import paths change from v3 to v4, and most APIs have new signatures.

• Type-safe interfaces for all 16 OpenSearch API groups
• Fluent query-builder DSL (querydsl/) — no raw JSON required
• Struct-literal configuration (value semantics, no pointer surprise)
• Built on resty — middleware, retries, timeouts
• Structured logging via logrus
• OpenTelemetry tracing middleware (trace/opentelemetry/)

Install

go get github.com/disaster37/opensearch/v4

Requires Go 1.18+ (uses generics in api/ and querydsl/).

Quick Start

package main

import (
    "context"
    "log"

    os "github.com/disaster37/opensearch/v4"
    "github.com/sirupsen/logrus"
)

func main() {
    logger := logrus.NewEntry(logrus.StandardLogger())

    client, err := os.New(&os.Config{
        URL:      "https://localhost:9200",
        Username: "admin",
        Password: "admin",
    }, logger)
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Index a document
    doc := map[string]any{
        "name":  "OpenSearch",
        "stars": 10000,
    }
    resp, err := client.Document().Index(ctx, "repos", nil, doc, nil)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Indexed %s/%s\n", resp.Index, resp.ID)
}

Using the Query DSL

Build type-safe queries without raw JSON maps:

import "github.com/disaster37/opensearch/v4/querydsl"

// Bool query with must/should/filter clauses
query := querydsl.Bool{
    Must: []querydsl.Query{
        querydsl.Match{"status": "published"},
    },
    Should: []querydsl.Query{
        querydsl.Term{"Field": "featured", "Value": true, "Boost": ptr(1.5)},
    },
    Filter: []querydsl.Query{
        querydsl.Range{
            Field:     "date",
            Gte:       "2024-01-01",
            Format:    "yyyy-MM-dd",
        },
    },
    MinimumShouldMatch: "1",
}

Aggregations

// Terms aggregation with sub-aggregation
agg := querydsl.TermsAggregation("genre").
    Size(20).
    SubAggregation("avg_rating", querydsl.AvgAggregation("rating"))

// Date histogram for time-series
histogram := querydsl.DateHistogramAggregation("timestamp").
    CalendarInterval("1d").
    MinDocCount(0).
    SubAggregation("total_sales", querydsl.SumAggregation("amount"))

Available Services

All services are accessed through the Client interface:

Error Handling

All API errors are returned as *types.OpenSearchError:

result, err := client.Document().Get(ctx, "my-index", "doc-id", nil)
if err != nil {
    if os.IsNotFound(err) {
        log.Println("Document not found")
    } else if os.IsConflict(err) {
        log.Println("Version conflict — retry or refresh")
    } else {
        var osErr *types.OpenSearchError
        if errors.As(err, &osErr) {
            log.Printf("OpenSearch error %d: %s\n",
                osErr.Status, osErr.Details.Reason)
        } else {
            log.Fatal(err)
        }
    }
}

Optimistic Concurrency

Use DocumentVersion to prevent overwrites:

// First fetch
doc, err := client.Document().Get(ctx, "my-index", "doc-id", nil)

// Update with version
_, err = client.Document().Update(ctx, "my-index", "doc-id", newDoc,
    &os.DocumentVersion{
        SeqNo:       doc.SeqNo,
        PrimaryTerm: doc.PrimaryTerm,
    },
    nil)

Configuration

import (
    "time"

    os "github.com/disaster37/opensearch/v4"
)

client, err := os.New(&os.Config{
    URL:           "https://localhost:9200",
    Username:      "admin",
    Password:      "admin",
    TLSSkipVerify: false, // production: always false
    CACert:        caCertPEM,
    Timeout:       30 * time.Second,
}, logger)

OpenTelemetry Tracing

Wrap the client with the OTel trace middleware:

import (
    otel "github.com/disaster37/opensearch/v4/trace/opentelemetry"
)

client, _ := os.New(cfg, logger)
otel.WrapClient(client.RestyClient(), otel.WithServiceName("my-service"))

Testing

go test ./...

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.

Project Structure

opensearch-go/
├── client.go          # Client interface + New()
├── common.go          # Re-exported type aliases
├── errors.go          # Error helpers
├── types/             # Common types (ShardsInfo, OpenSearchError, etc.)
├── api/               # 16 service interfaces + models
│   ├── document_service.go
│   ├── search_service.go
│   ├── indices_service.go
│   └── ...
├── querydsl/          # Query and aggregation builder DSL
│   ├── search_queries_*.go
│   ├── search_aggs_*.go
│   └── search_source.go
└── trace/opentelemetry/