Go Backend Integration

Series: Elasticsearch 101 | Article: 06

---

Overview

The official Go client for Elasticsearch is github.com/elastic/go-elasticsearch/v9. It offers two API styles: a low-level client that works with raw JSON and an HTTP-level DSL, and a typed API (added in v8) that provides fully generated Go types for every request and response.

This article uses the typed API. It removes the guesswork from query construction and makes IDE completion actually useful when building complex queries.

---

Setup

go mod init github.com/yourhandle/articles-api
go get github.com/elastic/go-elasticsearch/v9@latest

Verify the import resolves:

go list -m github.com/elastic/go-elasticsearch/v9

---

Client Initialization

package elastic

import (
    "github.com/elastic/go-elasticsearch/v9"
)

// NewClient creates a typed Elasticsearch client.
// In production, addresses and credentials come from environment variables.
func NewClient(address, username, password string) (*elasticsearch.TypedClient, error) {
    cfg := elasticsearch.Config{
        Addresses: []string{address},
        Username:  username,
        Password:  password,
    }
    return elasticsearch.NewTypedClient(cfg)
}

TypedClient wraps all APIs with generated request/response structs. You never need to manually marshal JSON for standard operations.

For production with API key authentication (preferred over username/password):

cfg := elasticsearch.Config{
    Addresses: []string{address},
    APIKey:    apiKey,  // "id:api_key" base64 encoded
}

---

Index Creation

Define the mapping as a Go struct using the types package, then create the index:

package elastic

import (
    "context"

    "github.com/elastic/go-elasticsearch/v9"
    "github.com/elastic/go-elasticsearch/v9/typedapi/indices/create"
    "github.com/elastic/go-elasticsearch/v9/typedapi/types"
)

func CreateArticlesIndex(ctx context.Context, es *elasticsearch.TypedClient) error {
    dynamicStrict := types.DynamicMappingStrict

    trueVal := true
    _, err := es.Indices.Create("articles").
        Request(&create.Request{
            Settings: &types.IndexSettings{
                NumberOfShards:   "1",
                NumberOfReplicas: "0",
            },
            Mappings: &types.TypeMapping{
                Dynamic: &dynamicStrict,
                Properties: map[string]types.Property{
                    "id": types.NewKeywordProperty(),
                    "title": types.NewTextProperty(func(p *types.TextProperty) {
                        p.Analyzer = strPtr("english")
                        p.Fields = map[string]types.Property{
                            "keyword": types.NewKeywordProperty(),
                        }
                    }),
                    "body":        types.NewTextProperty(func(p *types.TextProperty) { p.Analyzer = strPtr("english") }),
                    "slug":        types.NewKeywordProperty(),
                    "author_id":   types.NewKeywordProperty(),
                    "author_name": types.NewTextProperty(),
                    "tags":        types.NewKeywordProperty(),
                    "is_published": types.NewBooleanProperty(),
                    "view_count":  types.NewIntegerNumberProperty(),
                    "published_at": types.NewDateProperty(func(p *types.DateProperty) {
                        p.Format = strPtr("strict_date_optional_time")
                    }),
                    "updated_at": types.NewDateProperty(func(p *types.DateProperty) {
                        p.Format = strPtr("strict_date_optional_time")
                    }),
                },
            },
        }).
        Do(ctx)
    _ = trueVal
    return err
}

func strPtr(s string) *string { return &s }

---

Document Types

Define Go structs that represent the document shape. These align exactly with the mapping:

package model

import "time"

// Article is the Elasticsearch document schema for the articles index.
type Article struct {
    ID          string    `json:"id"`
    Title       string    `json:"title"`
    Slug        string    `json:"slug"`
    Body        string    `json:"body"`
    AuthorID    string    `json:"author_id"`
    AuthorName  string    `json:"author_name"`
    Tags        []string  `json:"tags"`
    IsPublished bool      `json:"is_published"`
    ViewCount   int       `json:"view_count"`
    PublishedAt *time.Time `json:"published_at,omitempty"`
    UpdatedAt   time.Time `json:"updated_at"`
}

---

Indexing a Single Document

package elastic

import (
    "context"
    "time"

    "github.com/elastic/go-elasticsearch/v9"
    "github.com/yourhandle/articles-api/model"
)

func IndexArticle(ctx context.Context, es *elasticsearch.TypedClient, article model.Article) error {
    _, err := es.Index("articles").
        Id(article.ID).
        Request(article).
        Do(ctx)
    return err
}

The typed client handles JSON serialization. Pass the struct directly.

---

Bulk Indexing

For ingesting or synchronizing large sets of documents, use the BulkIndexer helper from esutil:

package elastic

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "log"
    "runtime"

    "github.com/elastic/go-elasticsearch/v9"
    "github.com/elastic/go-elasticsearch/v9/esutil"
    "github.com/yourhandle/articles-api/model"
)

func BulkIndexArticles(ctx context.Context, es *elasticsearch.TypedClient, articles []model.Article) error {
    // esutil.BulkIndexer works with the low-level client; get it from TypedClient:
    bi, err := esutil.NewBulkIndexer(esutil.BulkIndexerConfig{
        Client:     es,
        Index:      "articles",
        NumWorkers: runtime.NumCPU(),
        FlushBytes: 5 * 1024 * 1024, // 5 MB
    })
    if err != nil {
        return fmt.Errorf("creating bulk indexer: %w", err)
    }

    for _, article := range articles {
        data, err := json.Marshal(article)
        if err != nil {
            return fmt.Errorf("marshaling article %s: %w", article.ID, err)
        }

        err = bi.Add(ctx, esutil.BulkIndexerItem{
            Action:     "index",
            DocumentID: article.ID,
            Body:       bytes.NewReader(data),
            OnFailure: func(ctx context.Context, item esutil.BulkIndexerItem, res esutil.BulkIndexerResponseItem, err error) {
                if err != nil {
                    log.Printf("bulk index failure: doc=%s err=%v", item.DocumentID, err)
                } else {
                    log.Printf("bulk index error: doc=%s type=%s reason=%s", item.DocumentID, res.Error.Type, res.Error.Reason)
                }
            },
        })
        if err != nil {
            return fmt.Errorf("adding item to bulk indexer: %w", err)
        }
    }

    return bi.Close(ctx) // flushes pending items and waits for completion
}

The BulkIndexer batches requests internally. The OnFailure callback is critical — failed individual documents do not cause the overall Close to return an error, so you must handle them explicitly.

---

Searching Documents

Build a typed search request. The following implements a paginated full-text search with filter and aggregation:

package elastic

import (
    "context"
    "fmt"

    "github.com/elastic/go-elasticsearch/v9"
    "github.com/elastic/go-elasticsearch/v9/typedapi/core/search"
    "github.com/elastic/go-elasticsearch/v9/typedapi/types"
    "github.com/elastic/go-elasticsearch/v9/typedapi/types/enums/operator"
    "github.com/yourhandle/articles-api/model"
)

type SearchParams struct {
    Query  string
    Tags   []string
    From   int
    Size   int
}

type SearchResult struct {
    Total    int64
    Articles []model.Article
    TagFacets []TagFacet
}

type TagFacet struct {
    Tag   string
    Count int64
}

func SearchArticles(ctx context.Context, es *elasticsearch.TypedClient, params SearchParams) (*SearchResult, error) {
    // --- build the query ---
    var mustClauses []types.Query
    if params.Query != "" {
        mustClauses = append(mustClauses, types.Query{
            MultiMatch: &types.MultiMatchQuery{
                Query:    params.Query,
                Fields:   []string{"title^2", "body"},
                Operator: &operator.And,
            },
        })
    }

    filterClauses := []types.Query{
        {Term: map[string]types.TermQuery{"is_published": {Value: true}}},
    }
    if len(params.Tags) > 0 {
        values := make([]types.FieldValue, len(params.Tags))
        for i, t := range params.Tags {
            values[i] = t
        }
        filterClauses = append(filterClauses, types.Query{
            Terms: &types.TermsQuery{
                TermsQuery: map[string]types.TermsQueryField{"tags": values},
            },
        })
    }

    query := &types.Query{
        Bool: &types.BoolQuery{
            Must:   mustClauses,
            Filter: filterClauses,
        },
    }

    // --- build aggregations ---
    termSize := 20
    aggs := map[string]types.Aggregations{
        "tags_facet": {
            Terms: &types.TermsAggregation{
                Field: strPtr("tags"),
                Size:  &termSize,
            },
        },
    }

    // --- source filtering ---
    sourceFilter := types.NewSourceFilter()
    sourceFilter.Includes = []string{"id", "title", "slug", "author_name", "tags", "published_at", "view_count"}

    // --- execute ---
    from := params.From
    size := params.Size
    if size == 0 {
        size = 10
    }

    res, err := es.Search().
        Index("articles").
        Request(&search.Request{
            Query:   query,
            Aggs:    aggs,
            From:    &from,
            Size:    &size,
            Source_: sourceFilter,
            Sort: []types.SortCombinations{
                types.SortOptions{SortOptions: map[string]types.FieldSort{
                    "published_at": {Order: &sortDesc},
                }},
            },
        }).
        Do(ctx)
    if err != nil {
        return nil, fmt.Errorf("search: %w", err)
    }

    // --- parse hits ---
    result := &SearchResult{
        Total: res.Hits.Total.Value,
    }
    for _, hit := range res.Hits.Hits {
        var article model.Article
        if err := json.Unmarshal(hit.Source_, &article); err != nil {
            return nil, fmt.Errorf("unmarshal hit: %w", err)
        }
        result.Articles = append(result.Articles, article)
    }

    // --- parse aggregations ---
    if tagAgg, ok := res.Aggregations["tags_facet"]; ok {
        if sterms, ok := tagAgg.(*types.StringTermsAggregate); ok {
            for _, bucket := range sterms.Buckets.Array {
                result.TagFacets = append(result.TagFacets, TagFacet{
                    Tag:   bucket.Key.String(),
                    Count: bucket.DocCount,
                })
            }
        }
    }

    return result, nil
}

var sortDesc = sortorder.Desc

---

HTTP Handler Example

Wire the search function into an HTTP handler. I use the standard library net/http with encoding/json:

package handler

import (
    "encoding/json"
    "net/http"
    "strconv"
    "strings"

    "github.com/yourhandle/articles-api/elastic"
)

type SearchHandler struct {
    ES *elasticsearch.TypedClient
}

func (h *SearchHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    q := r.URL.Query()
    params := elastic.SearchParams{
        Query: q.Get("q"),
        From:  parseIntDefault(q.Get("from"), 0),
        Size:  parseIntDefault(q.Get("size"), 10),
    }
    if rawTags := q.Get("tags"); rawTags != "" {
        params.Tags = strings.Split(rawTags, ",")
    }

    result, err := elastic.SearchArticles(r.Context(), h.ES, params)
    if err != nil {
        http.Error(w, "search failed", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(result)
}

func parseIntDefault(s string, def int) int {
    if v, err := strconv.Atoi(s); err == nil {
        return v
    }
    return def
}

---

Deleting a Document

func DeleteArticle(ctx context.Context, es *elasticsearch.TypedClient, id string) error {
    _, err := es.Delete("articles", id).Do(ctx)
    return err
}

---

Partial Update

func UpdateViewCount(ctx context.Context, es *elasticsearch.TypedClient, id string, count int) error {
    _, err := es.Update("articles", id).
        Request(&update.Request{
            Doc: map[string]any{"view_count": count},
        }).
        Do(ctx)
    return err
}

---

Error Handling Pattern

The typed client returns typed errors. Check for *types.ElasticsearchError to distinguish Elasticsearch-level errors (like index not found or document already exists) from transport errors:

import "github.com/elastic/go-elasticsearch/v9/typedapi/types"

func isNotFound(err error) bool {
    var esErr *types.ElasticsearchError
    if errors.As(err, &esErr) {
        return esErr.Status == 404
    }
    return false
}

---

Summary

• Use elasticsearch.NewTypedClient for full type safety on request/response structs.

• Store the client as a dependency; initialize it once at application startup.

• Pass struct values directly to .Request() — the client handles JSON serialization.

• Use esutil.BulkIndexer for batch operations; always handle OnFailure.

• Parse aggregation results via type assertions on res.Aggregations[name].

• Use errors.As with *types.ElasticsearchError for structured error handling.

---

Previous: Aggregations and Analytics | Next: React Frontend Integration