AACsearch
SDKs

Go SDK

Install and use the aacsearch-go SDK for search, index management, synonyms, curations, and analytics.

Go SDK (aacsearch-go)

The github.com/aacsearch/aacsearch-go Go module provides two clients:

ClientScopeKey PrefixUse Case
SearchClientsearch-onlyss_search_*Public search from backend services
AdminClientfull CRUDaa_admin_*Server-side management, CLI tools

Installation

go get github.com/aacsearch/aacsearch-go

Requires Go 1.21+.

Quick Start

SearchClient (public)

Use with a search-scope API key (ss_search_*).

package main

import (
    "log"
    "github.com/aacsearch/aacsearch-go"
)

func main() {
    client, err := aacsearch.NewSearchClient(aacsearch.SearchClientOptions{
        BaseURL:   "https://app.aacsearch.com",
        APIKey:    "ss_search_...",
        IndexSlug: "products",
    })
    if err != nil {
        log.Fatal(err)
    }

    // Basic search
    result, err := client.Search(aacsearch.SearchParams{Q: "laptop"})
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Found %d results", result.Found)

    // Multi-search
    results, err := client.MultiSearch([]aacsearch.SearchParams{
        {Q: "nike", QueryBy: "title"},
        {Q: "adidas", QueryBy: "title", FilterBy: "in_stock:=true"},
    })
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Got %d result sets", len(results.Results))
}

AdminClient (server-side)

Use with an admin-scope API key (aa_admin_*). Never bundle in browser code.

package main

import (
    "log"
    "github.com/aacsearch/aacsearch-go"
)

func boolPtr(b bool) *bool { return &b }

func main() {
    admin, err := aacsearch.NewAdminClient(aacsearch.AdminClientOptions{
        BaseURL:   "https://app.aacsearch.com",
        APIKey:    "aa_admin_...",
        ProjectID: "org_xxx",
    })
    if err != nil {
        log.Fatal(err)
    }

    // Create an index
    index, err := admin.CreateIndex(aacsearch.CreateIndexInput{
        Slug:        "products",
        DisplayName: "Products",
        Fields: []aacsearch.FieldDefinition{
            {Name: "title", Type: "string"},
            {Name: "price", Type: "float", Facet: boolPtr(true)},
            {Name: "category", Type: "string", Facet: boolPtr(true)},
        },
        DefaultSortingField: "price",
    })
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Created index: %s", index.ID)

    // Batch upsert documents
    _, err = admin.BatchUpsertDocuments(index.ID, []map[string]interface{}{
        {"id": "doc_1", "title": "Running Shoes", "price": 89.99},
        {"id": "doc_2", "title": "T-Shirt", "price": 29.99},
    })
    if err != nil {
        log.Fatal(err)
    }

    // List indexes
    indexes, err := admin.ListIndexes()

    // Get analytics
    analytics, err := admin.GetAnalytics("7d")
    log.Printf("Total searches: %d, CTR: %.2f", analytics.TotalSearches, analytics.CTR)

    // Create API key
    key, err := admin.CreateKey(aacsearch.CreateKeyInput{
        Name:      "My Search Key",
        Scopes:    []aacsearch.KeyScope{aacsearch.KeyScopeSearch},
        IndexSlug: "products",
    })
    log.Printf("Created key: %s...", key.Prefix[:8])
}

Error Handling

import (
    "errors"
    "github.com/aacsearch/aacsearch-go"
)

result, err := client.Search(aacsearch.SearchParams{Q: "laptop"})
if err != nil {
    var sdkErr *aacsearch.SDKError
    if errors.As(err, &sdkErr) {
        switch sdkErr.Code {
        case "rate_limited":
            // Back off and retry
        case "unauthorized":
            // API key is invalid
        case "not_found":
            // Index not found
        default:
            log.Printf("Error %d: %s", sdkErr.Status, sdkErr.Message)
        }
    }
}

API Reference

CategoryMethods
ProjectGetProject, CreateProject, GetProjectByID
Index ManagementListIndexes, GetIndex, CreateIndex, UpdateIndex, DeleteIndex, GetIndexStats
DocumentsListDocuments, UpsertDocument, BatchUpsertDocuments, DeleteDocument, BatchDeleteDocuments
SearchSearch, MultiSearch
API KeysListKeys, CreateKey, RevokeKey
AnalyticsGetAnalytics, GetUsage
SynonymsListSynonyms, CreateSynonym, UpsertSynonyms, DeleteSynonym
CurationsListCurations, CreateCuration, UpsertCurations, DeleteCuration
Sorting FieldsListSortingFields, CreateSortingField, ReplaceSortingFields, DeleteSortingField
FacetsListFacets

On this page