search

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 15 Imported by: 0

README

search logo

Portable lexical search for Go, from an embedded index to a search service.

Go Reference CI Go 1.24 or newer Coverage Version v0.1.0 Executed unit tests, including subtests Executed integration tests, including subtests Merged statement coverage

Features · Quick Start · Drivers · Installation · Examples · API

Features

Feature What you get Example or API
Literal search Require every analyzed term, with explicit searchable fields. Typed search example
Typed filters Combine Boolean logic, exact values, integer ranges, and array membership. Filter example
Stable sorting Order by up to two declared fields, followed by the document ID. Sort
Pagination Use bounded offsets and limits with explicit total-count precision. Query
Term facets Count matching documents before pagination, deduplicating repeated array terms. Facet example
Structured highlights Render untrusted text segments with explicit match markers. Highlight example
Bulk operations Retain input positions and honest per-item or aggregate outcomes. Bulk example
Visibility receipts Wait for accepted writes to become searchable and retain recovery evidence. Receipt and Outcome
Typed documents Use typed Go values while keeping document IDs separate from JSON bodies. Typed search example
Explicit schemas Provision deliberately and detect schema drift without runtime migration. Definition
Safe observability Observe classified events with panic isolation and optional bounded async delivery. Observer · AsyncObserver
Isolated testing Script results and inspect recorded calls without running a search engine. Fake backend example

Quick Start

Go 1.25+, with no external service required.

git clone https://github.com/goforj/search.git
cd search
go run ./examples/quickstart
// Command quickstart demonstrates embedded indexing and search.
package main

import (
	"context"
	"fmt"

	"github.com/goforj/search"
	"github.com/goforj/search/driver/blevesearch"
)

// main demonstrates the complete embedded indexing and typed-query lifecycle.
func main() {
	ctx := context.Background()

	// Use an in-memory index so this example needs no files or search service.
	driver, err := blevesearch.Open(ctx, blevesearch.Config{Memory: true})
	if err != nil {
		panic(err)
	}
	defer driver.Close()

	// Declare which document fields participate in full-text search.
	definition := search.Definition{
		Name:   "products",
		Fields: []search.Field{{Name: "title", Type: search.TextField, Searchable: true}},
	}
	// Provision the schema explicitly before creating an application handle.
	if err := driver.CreateIndex(ctx, definition); err != nil {
		panic(err)
	}
	index, err := search.NewIndex(driver, definition)
	if err != nil {
		panic(err)
	}

	// Keep the document ID separate from the application JSON.
	type product struct {
		Title string `json:"title"`
	}
	receipt, err := search.Upsert(ctx, index, "mug-1", product{Title: "Blue mug"})
	if err != nil {
		panic(err)
	}
	// A receipt acknowledges the write; Wait establishes search visibility.
	outcome, err := index.Wait(ctx, receipt)
	if err != nil {
		panic(err)
	}
	if outcome.State != search.OutcomeSucceeded {
		panic(outcome.Error)
	}

	// Require both search terms and decode hits directly into the application type.
	page, err := search.SearchAs[product](ctx, index, search.Query{Text: "blue mug"})
	if err != nil {
		panic(err)
	}
	fmt.Println(page.Hits[0].ID, page.Hits[0].Value.Title)
	// mug-1 Blue mug
}

Drivers

Choose an embedded index, an existing SQL pool, or a shared search service.

Driver Tested version Mutation visibility Bulk precision Topology
Bleve v2.6.3 synchronous per item single process; memory or disk
Meilisearch v1.17.0 asynchronous receipt aggregate task shared service
Typesense 30.0 synchronous per item shared service
OpenSearch 3.9.0 refresh-waiting per item shared service
Elasticsearch 9.5.6 refresh-waiting per item shared service
PostgreSQL FTS 18.6 synchronous per item application-owned SQL pool
SQLite FTS5 3.54.1 synchronous per item embedded SQL; application-owned pool
Redis Search 8.10.3 synchronous per item standalone service; at most 4096 matches

All listed engines pass the same literal all-terms, typed-filter, stable-sort, pagination, facet, highlight, replacement, receipt, bulk, cancellation, and concurrent-call fixtures. See executed driver evidence for exact scenario names and the source fingerprint.

Driver behavior and limits

Meilisearch

Meilisearch facets support at most 4096 distinct terms per requested field after filtering. Higher cardinality returns ErrUnsupported; it does not return an incorrectly chosen top bucket. The driver collects a bounded complete distribution because the engine does not preserve portable lexical ties at its native count cutoff.

Meilisearch accepts at most ten backend words. Queries in scripts with finer native segmentation use a conservative rune bound to prevent silent truncation. Its validated server search cutoff exceeds the enforced 30-second maximum HTTP deadline, so the client fails before the engine can return a silently timed-out response. As with schema validation, this assumes administrators do not change settings behind a running client.

Elasticsearch and OpenSearch

Elasticsearch and OpenSearch each have an independent driver and tested version matrix. Their writes wait for refresh and active shard copies before reporting visibility. Native bulk responses retain per-item failures even when HTTP succeeds. Queries reject timeouts and partial shard responses. Multi-shard facet counts retain the engine's estimated precision when native error bounds are nonzero. Keyword values are limited to 16382 UTF-8 bytes because their ordered encoding must fit Lucene's term limit. Provisioning defaults to one primary shard and no replicas; configure replicas explicitly for a production cluster.

PostgreSQL FTS and SQLite FTS5

PostgreSQL FTS and SQLite FTS5 accept an application-owned *sql.DB. The application selects and registers its SQL client, configures the pool, and closes it. The search driver creates dedicated tables, native full-text projections, and schema ownership metadata. Writes and their projections commit in one transaction. Queries compute hits, totals, and facets from one database snapshot. PostgreSQL uses the simple text-search configuration and byte-order collation. SQLite requires an FTS5-enabled provider. Driver Close preserves the injected pool.

Redis Search targets standalone Redis with its native Search module. It uses native literal matching and typed filtering, then collects at most 4096 matching documents to provide deterministic multiple sorts and exact array facets. More matches return ErrUnsupported. Mutations execute as one Lua command, and interrupted or failed scripts report uncertainty rather than implying rollback. Native query timeout exceeds the enforced maximum client deadline to avoid accepting partial timed-out results. Cluster routing is not supported by this driver.

Bleve

Bleve owns a single index path in one process. Its ownership lock refuses a second writer. Use a shared service when querying and indexing from separate processes. Close concrete drivers at the application lifecycle boundary.

Installation

The root package and service drivers require Go 1.24+ and have no third-party dependencies. The optional Bleve module requires Go 1.25+.

Install the root package and the drivers you need:

go get github.com/goforj/search

# Bleve (embedded, Go 1.25+)
go get github.com/goforj/search/driver/blevesearch

# Meilisearch
go get github.com/goforj/search/driver/meilisearch

# Typesense
go get github.com/goforj/search/driver/typesensesearch

# OpenSearch
go get github.com/goforj/search/driver/opensearch

# Elasticsearch
go get github.com/goforj/search/driver/elasticsearch

# PostgreSQL FTS
go get github.com/goforj/search/driver/postgressearch

# SQLite FTS5
go get github.com/goforj/search/driver/sqlitesearch

# Redis Search
go get github.com/goforj/search/driver/redissearch

Install the drivers you need. All drivers except Bleve are packages in the root module and are included when you install search; their commands above are provided for convenient copying. Bleve is a separate optional module. See module ownership and release order.

See search behavior and recovery for write visibility, query semantics, and receipt lifetime.

Testing

Use searchfake to queue search results and inspect recorded calls in application tests. It implements search.Backend without a running search engine. The fake backend example shows the complete workflow.

Driver authors can reuse searchtest to verify the portable behavior contract. Integration tests run against real Bleve indexes and SQLite FTS5 databases, plus Testcontainers with pinned Meilisearch, Typesense, OpenSearch, Elasticsearch, PostgreSQL, and Redis images. Each service container starts once per run; tests use separate index namespaces. OpenSearch and Elasticsearch run with authentication enabled and execute the shared contract with one and two primary shards.

See the executed driver evidence, unit test inventory, and integration test inventory for the scenarios that actually ran.

Run make bench for allocation-aware document validation benchmarks and embedded search over 1,000 documents.

Runnable examples

Each program under examples/ is executed by a shared test runner that checks its expected output. Run these commands from the repository root with Go 1.25 or newer.

Example Run
Inspect bulk visibility go run ./examples/bulk
Count facets before pagination go run ./examples/facets
Test an application service go run ./examples/fake
Filter and sort results go run ./examples/filters
Escape structured highlights go run ./examples/highlights
Index and search a document go run ./examples/quickstart
Search typed documents go run ./examples/search
Construct service drivers go run ./examples/services

Development

make test
make test-race
make vet
make test-integration
make test-coverage
make generate
make check-generated

API descriptions come from GoDoc. Runnable examples and their expected output live in examples/<name>/main.go. A shared test runner executes those programs. Edit those sources and run make generate; generation refreshes the quick start, example index, feature badges, and API index. CI checks that regeneration produces no diff.

See development and release notes for focused driver tests, module boundaries, and publishing. Report problems or request features in GitHub issues.

API Index

Choose a backend in Drivers, then use these operations in your application. API names and example titles jump to tested usage below.

Task API Example
Define an index Definition · NewIndex Index and search a document
Write documents Upsert Index and search a document
Search documents SearchAs · Query Search typed documents
Filter results Index.Search · Keyword · Integer · And · Equal Filter and sort results
Sort and paginate Query · Sort Filter and sort results
Count facets TermFacet Count facets before pagination
Highlight matches Highlight Escape structured highlights
Write a batch Index.Bulk · DeleteMutation Inspect bulk visibility
Wait for visibility Index.Wait · Outcome Index and search a document · Inspect bulk visibility
Test application code searchfake.New · searchfake.Backend.QueueSearch · searchfake.Backend.Calls Test an application service

API examples

Find complete programs and setup in Runnable examples.

Inspect bulk visibility

first, err := search.DeleteMutation("one")
if err != nil {
	panic(err)
}
second, err := search.DeleteMutation("two")
if err != nil {
	panic(err)
}
batch, err := index.Bulk(ctx, []search.Mutation{first, second})
if err != nil {
	panic(err)
}
outcome, err := index.Wait(ctx, batch.Receipt)
if err != nil {
	panic(err)
}
for _, item := range outcome.Bulk.Items {
	fmt.Println(item.ID, item.Status)
	// one succeeded
	// two succeeded
}

Count facets before pagination

result, err := index.Search(ctx, search.Query{Limit: 1, Facets: []search.TermFacet{{Name: "categories", Field: "category"}}})
if err != nil {
	panic(err)
}
for _, bucket := range result.Facets[0].Buckets {
	value, _ := bucket.Value.Keyword()
	fmt.Println(value, bucket.Count)
	// kitchen 2
	// books 1
}

Test an application service

backend := searchfake.New()
backend.QueueSearch(search.Result{Total: search.Total{Value: 3, Relation: search.TotalExact}}, nil)
index, err := search.NewIndex(backend, search.Definition{
	Name:   "products",
	Fields: []search.Field{{Name: "title", Type: search.TextField, Searchable: true}},
})
if err != nil {
	panic(err)
}
result, err := index.Search(context.Background(), search.Query{Text: "mug"})
if err != nil {
	panic(err)
}
fmt.Println(result.Total.Value, backend.Calls()[0].Kind)
// 3 search

Filter and sort results

category, err := search.Keyword("kitchen")
if err != nil {
	panic(err)
}
maximum, err := search.Integer(1500)
if err != nil {
	panic(err)
}
result, err := index.Search(ctx, search.Query{
	Filter: search.And(search.Equal("category", category), search.LessThan("price", maximum)),
	Sort:   []search.Sort{{Field: "price", Direction: search.Ascending}},
	Limit:  1,
})
if err != nil {
	panic(err)
}
fmt.Println(result.Hits[0].Document.ID)
// two
fmt.Println(result.Total.Value)
// 2

Escape structured highlights

result, err := index.Search(ctx, search.Query{Text: "blue", Highlight: []search.Highlight{{Field: "title"}}})
if err != nil {
	panic(err)
}
for _, segment := range result.Hits[0].Highlights["title"][0].Segments {
	text := html.EscapeString(segment.Text)
	if segment.Matched {
		fmt.Print("<mark>" + text + "</mark>")
	} else {
		fmt.Print(text)
	}
}
fmt.Println()
// <mark>Blue</mark> mug

Index and search a document

ctx := context.Background()

// Use an in-memory index so this example needs no files or search service.
driver, err := blevesearch.Open(ctx, blevesearch.Config{Memory: true})
if err != nil {
	panic(err)
}
defer driver.Close()

// Declare which document fields participate in full-text search.
definition := search.Definition{
	Name:   "products",
	Fields: []search.Field{{Name: "title", Type: search.TextField, Searchable: true}},
}
// Provision the schema explicitly before creating an application handle.
if err := driver.CreateIndex(ctx, definition); err != nil {
	panic(err)
}
index, err := search.NewIndex(driver, definition)
if err != nil {
	panic(err)
}

// Keep the document ID separate from the application JSON.
type product struct {
	Title string `json:"title"`
}
receipt, err := search.Upsert(ctx, index, "mug-1", product{Title: "Blue mug"})
if err != nil {
	panic(err)
}
// A receipt acknowledges the write; Wait establishes search visibility.
outcome, err := index.Wait(ctx, receipt)
if err != nil {
	panic(err)
}
if outcome.State != search.OutcomeSucceeded {
	panic(outcome.Error)
}

// Require both search terms and decode hits directly into the application type.
page, err := search.SearchAs[product](ctx, index, search.Query{Text: "blue mug"})
if err != nil {
	panic(err)
}
fmt.Println(page.Hits[0].ID, page.Hits[0].Value.Title)
// mug-1 Blue mug

Search typed documents

page, err := search.SearchAs[struct {
	Title string `json:"title"`
}](ctx, index, search.Query{Text: "blue mug"})
if err != nil {
	panic(err)
}
fmt.Println(page.Hits[0].Value.Title)
// Blue mug
fmt.Println(page.Total.Value)
// 1

Construct service drivers

meili, err := meilisearch.New(meilisearch.Config{URL: "http://127.0.0.1:7700"})
if err != nil {
	panic(err)
}
defer meili.Close()
typesense, err := typesensesearch.New(typesensesearch.Config{URL: "http://127.0.0.1:8108"})
if err != nil {
	panic(err)
}
defer typesense.Close()
openSearch, err := opensearch.New(opensearch.Config{URL: "http://127.0.0.1:9200"})
if err != nil {
	panic(err)
}
defer openSearch.Close()
elastic, err := elasticsearch.New(elasticsearch.Config{URL: "http://127.0.0.1:9200"})
if err != nil {
	panic(err)
}
defer elastic.Close()
redis, err := redissearch.New(redissearch.Config{Addr: "127.0.0.1:6379"})
if err != nil {
	panic(err)
}
defer redis.Close()
fmt.Println("Clients constructed without backend I/O")
// Clients constructed without backend I/O

Documentation

Overview

Package search provides portable lexical search over explicitly defined indexes. Indexes are derived data: keep an authoritative source from which to rebuild. Drivers select storage and ranking; applications retain their search contract.

Index

Constants

View Source
const (
	// KeywordValue represents an exact UTF-8 string.
	KeywordValue ValueKind = "keyword"
	// BooleanValue represents a Boolean.
	BooleanValue ValueKind = "boolean"
	// IntegerValue represents an exactly portable signed integer.
	IntegerValue ValueKind = "integer"
	// MaxInteger is the largest exactly portable integer.
	MaxInteger int64 = 1<<53 - 1
)

Variables

View Source
var ErrClosed = errors.New("search: closed")

ErrClosed identifies a closed driver.

View Source
var ErrConflict = errors.New("search: conflict")

ErrConflict identifies a competing owner or conflicting request.

View Source
var ErrIndexNotFound = errors.New("search: index not found")

ErrIndexNotFound identifies an unprovisioned index.

View Source
var ErrInvalidDefinition = errors.New("search: invalid definition")

ErrInvalidDefinition identifies an invalid schema.

View Source
var ErrInvalidDocument = errors.New("search: invalid document")

ErrInvalidDocument identifies invalid document input.

View Source
var ErrInvalidQuery = errors.New("search: invalid query")

ErrInvalidQuery identifies invalid query input.

View Source
var ErrInvalidReceipt = errors.New("search: invalid receipt")

ErrInvalidReceipt identifies a forged, foreign, or empty receipt.

View Source
var ErrMutationFailed = errors.New("search: mutation failed")

ErrMutationFailed identifies accepted work that failed.

View Source
var ErrNotFound = errors.New("search: document not found")

ErrNotFound identifies a missing document.

View Source
var ErrOutcomeUnknown = errors.New("search: mutation outcome unknown")

ErrOutcomeUnknown means work may have been accepted and must be reconciled.

View Source
var ErrRateLimited = errors.New("search: rate limited")

ErrRateLimited identifies throttling.

View Source
var ErrReceiptExpired = errors.New("search: receipt expired")

ErrReceiptExpired identifies accepted work whose result is no longer retained.

View Source
var ErrSchemaDrift = errors.New("search: schema drift")

ErrSchemaDrift identifies a difference from the provisioned schema.

View Source
var ErrUnauthorized = errors.New("search: unauthorized")

ErrUnauthorized identifies rejected credentials or permissions.

View Source
var ErrUnavailable = errors.New("search: unavailable")

ErrUnavailable identifies a failed connection or incomplete backend response.

View Source
var ErrUnsupported = errors.New("search: unsupported operation")

ErrUnsupported identifies an unavailable backend capability.

Functions

func Decode

func Decode[T any](d Document) (T, error)

Decode reads a document without requiring an ID field in the application type. @group Documents

func SafeError

func SafeError(err error) error

SafeError removes backend prose and unwrap chains while retaining known classifications. @group Backend

Types

type AsyncObserver

type AsyncObserver struct {
	// contains filtered or unexported fields
}

AsyncObserver delivers retained events in FIFO order from one bounded worker. Applications own Shutdown; an observer that blocks indefinitely also blocks its worker.

func NewAsyncObserver

func NewAsyncObserver(observer Observer, capacity int) (*AsyncObserver, error)

NewAsyncObserver starts a single delivery worker with capacity from 1 to 65536. @group Observability

func (*AsyncObserver) Dropped

func (a *AsyncObserver) Dropped() uint64

Dropped reports the cumulative number of events discarded by bounded delivery. @group Observability

func (*AsyncObserver) Observe

func (a *AsyncObserver) Observe(ctx context.Context, event Event)

Observe enqueues without blocking and counts full-queue or post-shutdown drops. @group Observability

func (*AsyncObserver) Shutdown

func (a *AsyncObserver) Shutdown(ctx context.Context) error

Shutdown closes admission once and waits for retained callbacks within the caller's deadline. @group Observability

type Backend

Backend is the consumer-owned request-path contract implemented by concrete drivers. Implementations must support concurrent calls and return caller-owned response collections.

type Bucket

type Bucket struct {
	Value Value
	Count uint64
}

Bucket counts documents, deduplicating repeated array terms within each document.

type BulkOutcome

type BulkOutcome struct {
	Items     []ItemResult
	Precision ItemOutcomePrecision
}

BulkOutcome retains terminal per-item evidence without inventing precision.

type BulkResult

type BulkResult struct {
	Receipt   Receipt
	Items     []ItemResult
	Precision ItemOutcomePrecision
}

BulkResult retains submission precision and accepted-work receipt.

type CountPrecision

type CountPrecision string

CountPrecision describes term-bucket count accuracy.

const (
	// CountExact reports complete term counts.
	CountExact CountPrecision = "exact"
	// CountEstimated reports approximate term counts.
	CountEstimated CountPrecision = "estimated"
)

type DecodeError

type DecodeError struct {
	ID DocumentID
}

DecodeError identifies a malformed typed hit without disclosing its contents.

func (*DecodeError) Error

func (e *DecodeError) Error() string

Error reports only the classification; callers may inspect ID under their disclosure policy. @group Results

func (*DecodeError) Unwrap

func (e *DecodeError) Unwrap() error

Unwrap preserves invalid-document classification. @group Results

type Definition

type Definition struct {
	Name              IndexName
	Fields            []Field
	DefaultSearchable []FieldName
	DefaultSort       []Sort
}

Definition describes rebuildable index data and default query behavior.

func (Definition) Fingerprint

func (d Definition) Fingerprint() (string, error)

Fingerprint returns a versioned canonical hash of the normalized search contract. @group Definitions

func (Definition) Validate

func (d Definition) Validate() error

Validate checks a definition with conservative default limits. @group Definitions

type Direction

type Direction string

Direction selects portable scalar order.

const (
	// Ascending orders strings by UTF-8 bytes, Booleans false first, and integers numerically.
	Ascending Direction = "ascending"
	// Descending reverses the portable scalar order.
	Descending Direction = "descending"
)

type Document

type Document struct {
	ID   DocumentID
	Body json.RawMessage
}

Document retains explicit identity separately from application-owned JSON.

func Encode

func Encode[T any](id DocumentID, value T) (Document, error)

Encode marshals a typed value into a validated JSON object. @group Documents

type DocumentID

type DocumentID string

DocumentID identifies a complete replacement document.

type Event

type Event struct {
	Kind          string
	ReceiptID     string
	Phase         EventPhase
	Index         IndexName
	Duration      time.Duration
	DocumentCount int
	HitCount      int
	TotalRelation TotalRelation
	ErrorCode     string
	Outcome       string
}

Event contains bounded metadata without document, query, or backend prose.

type EventPhase

type EventPhase string

EventPhase distinguishes submission latency from visibility and search latency.

const (
	// PhaseSubmission identifies accepted-work submission.
	PhaseSubmission EventPhase = "submission"
	// PhaseTerminal identifies terminal mutation observation.
	PhaseTerminal EventPhase = "terminal"
	// PhaseSearchComplete identifies a complete search call.
	PhaseSearchComplete EventPhase = "search_complete"
)

type FacetResult

type FacetResult struct {
	Name      string
	Field     FieldName
	Buckets   []Bucket
	Precision CountPrecision
	Truncated bool
}

FacetResult retains truncation separately from count precision.

type Field

type Field struct {
	Name       FieldName
	Path       JSONPointer
	Type       FieldType
	Required   bool
	Searchable bool
	Filterable bool
	Sortable   bool
	Facetable  bool
}

Field maps one declared name to an explicit document path.

type FieldName

type FieldName string

FieldName identifies a declared mapping, independently of its JSON path.

type FieldType

type FieldType string

FieldType defines the portable mapping shapes.

const (
	// TextField enables analyzed full-text matching only.
	TextField FieldType = "text"
	// KeywordField enables exact scalar operations.
	KeywordField FieldType = "keyword"
	// BooleanField enables Boolean filtering, ordering, and facets.
	BooleanField FieldType = "boolean"
	// IntegerField enables exact integer filtering and ordering.
	IntegerField FieldType = "integer"
	// KeywordsField enables array membership and term facets.
	KeywordsField FieldType = "keywords"
)

type Filter

type Filter struct {
	// contains filtered or unexported fields
}

Filter is an immutable expression. A zero filter means no predicate on Query only.

func And

func And(f ...Filter) Filter

And combines predicates without allowing caller mutation of the child slice. @group Filters

func Between

func Between(f FieldName, a, b Value) Filter

Between tests an inclusive, ordered integer range. @group Filters

func ContainsAll

func ContainsAll(f FieldName, v ...Value) Filter

ContainsAll tests whether an array contains a nonempty set. @group Filters

func ContainsAny

func ContainsAny(f FieldName, v ...Value) Filter

ContainsAny tests array intersection with a nonempty set. @group Filters

func Equal

func Equal(f FieldName, v Value) Filter

Equal tests scalar equality; absent and null values compare false. @group Filters

func Exists

func Exists(f FieldName) Filter

Exists tests non-null presence, independently of array membership. @group Filters

func GreaterThan

func GreaterThan(f FieldName, v Value) Filter

GreaterThan compares an integer against an exclusive lower bound. @group Filters

func GreaterThanOrEqual

func GreaterThanOrEqual(f FieldName, v Value) Filter

GreaterThanOrEqual compares an integer against an inclusive lower bound. @group Filters

func In

func In(f FieldName, v ...Value) Filter

In tests whether a scalar equals one of a nonempty set. @group Filters

func LessThan

func LessThan(f FieldName, v Value) Filter

LessThan compares an integer against an exclusive upper bound. @group Filters

func LessThanOrEqual

func LessThanOrEqual(f FieldName, v Value) Filter

LessThanOrEqual compares an integer against an inclusive upper bound. @group Filters

func Not

func Not(f Filter) Filter

Not complements a predicate; a zero child fails query validation. @group Filters

func Or

func Or(f ...Filter) Filter

Or combines alternatives, with zero alternatives matching nothing. @group Filters

func (Filter) View

func (f Filter) View() FilterView

View returns cloned collections so compilers cannot alter the expression. @group Filters

type FilterKind

type FilterKind string

FilterKind identifies an immutable expression node.

const (
	// FilterAnd applies conjunction, with an empty conjunction matching all.
	FilterAnd FilterKind = "and"
	// FilterOr applies disjunction, with an empty disjunction matching none.
	FilterOr FilterKind = "or"
	// FilterNot complements its child's two-valued result.
	FilterNot FilterKind = "not"
	// FilterEqual compares an exact scalar.
	FilterEqual FilterKind = "equal"
	// FilterIn tests membership in a scalar set.
	FilterIn FilterKind = "in"
	// FilterContainsAny tests at least one array member.
	FilterContainsAny FilterKind = "contains_any"
	// FilterContainsAll tests every requested array member.
	FilterContainsAll FilterKind = "contains_all"
	// FilterLessThan compares integers exclusively.
	FilterLessThan FilterKind = "less_than"
	// FilterLessThanOrEqual compares integers inclusively.
	FilterLessThanOrEqual FilterKind = "less_than_or_equal"
	// FilterGreaterThan compares integers exclusively.
	FilterGreaterThan FilterKind = "greater_than"
	// FilterGreaterThanOrEqual compares integers inclusively.
	FilterGreaterThanOrEqual FilterKind = "greater_than_or_equal"
	// FilterBetween tests an inclusive integer interval.
	FilterBetween FilterKind = "between"
	// FilterExists tests presence of a non-null value, including an empty array.
	FilterExists FilterKind = "exists"
)

type FilterView

type FilterView struct {
	Kind     FilterKind
	Field    FieldName
	Values   []Value
	Children []Filter
}

FilterView is a detached driver-facing expression view.

type Fragment

type Fragment struct {
	Segments []Segment
}

Fragment groups adjacent highlight segments.

type Highlight

type Highlight struct {
	Field FieldName
}

Highlight requests untrusted text segments for one searchable field.

type Hit

type Hit struct {
	Document   Document
	Score      *float64
	SortValues []Value
	Highlights map[FieldName][]Fragment
}

Hit is one document and its response-local ranking metadata.

type HitOf

type HitOf[T any] struct {
	ID         DocumentID
	Value      T
	Score      *float64
	SortValues []Value
	Highlights map[FieldName][]Fragment
}

HitOf is a typed hit whose document need not contain its identity.

type Index

type Index struct {
	// contains filtered or unexported fields
}

Index validates calls and owns its immutable definition. It is safe for concurrent use.

func NewIndex

func NewIndex(b Backend, d Definition, opts ...Option) (*Index, error)

NewIndex validates a definition without performing backend I/O or schema mutation. @group Construction

func (*Index) Bulk

func (i *Index) Bulk(ctx context.Context, ms []Mutation) (BulkResult, error)

Bulk rejects duplicate IDs and validates the entire bounded batch before submission. @group Mutations

func (*Index) Definition

func (i *Index) Definition() Definition

Definition returns an owned copy of the normalized definition. @group Definitions

func (*Index) Delete

func (i *Index) Delete(ctx context.Context, id DocumentID) (Receipt, error)

Delete removes an ID idempotently; visibility is established through Wait. @group Mutations

func (*Index) Search

func (i *Index) Search(ctx context.Context, q Query) (Result, error)

Search validates literal text, filters, limits, and result documents before exposure. @group Queries

func (*Index) Upsert

func (i *Index) Upsert(ctx context.Context, d Document) (Receipt, error)

Upsert replaces the complete document and returns accepted-work evidence. @group Mutations

func (*Index) Wait

func (i *Index) Wait(ctx context.Context, r Receipt) (Outcome, error)

Wait returns terminal failure as Outcome data; method errors mean no trustworthy outcome yet. @group Receipts

type IndexName

type IndexName string

IndexName identifies an application-owned logical index.

type ItemOutcomePrecision

type ItemOutcomePrecision string

ItemOutcomePrecision prevents aggregate success from implying individual success.

const (
	// PerItem means every item has an individually proven outcome.
	PerItem ItemOutcomePrecision = "per_item"
	// BatchOnly means only the aggregate outcome is known.
	BatchOnly ItemOutcomePrecision = "batch_only"
)

type ItemResult

type ItemResult struct {
	Position int
	ID       DocumentID
	Status   ItemStatus
	Error    error
}

ItemResult preserves the input position even when the backend reorders work.

type ItemStatus

type ItemStatus string

ItemStatus retains submission and terminal states separately.

const (
	// ItemAccepted reports proven submission only.
	ItemAccepted ItemStatus = "accepted"
	// ItemRejected reports a submission rejection.
	ItemRejected ItemStatus = "rejected"
	// ItemUnknown reports an unprovable individual outcome.
	ItemUnknown ItemStatus = "unknown"
	// ItemSucceeded reports proven per-item visibility.
	ItemSucceeded ItemStatus = "succeeded"
	// ItemFailed reports proven per-item failure.
	ItemFailed ItemStatus = "failed"
)

type JSONPointer

type JSONPointer string

JSONPointer addresses a value using RFC 6901.

type Limits

type Limits struct {
	NameBytes        int
	DefinitionBytes  int
	DocumentBytes    int
	JSONDepth        int
	ObjectMembers    int
	ArrayLength      int
	DefinitionFields int
	JSONPointerDepth int
	TextBytes        int
	QueryBytes       int
	QueryTerms       int
	QueryFields      int
	FilterNodes      int
	FilterDepth      int
	FilterValues     int
	FilterValueBytes int
	FacetNameBytes   int
	ResultLimit      uint64
	ResultWindow     uint64
	Facets           int
	HighlightFields  int
	BulkDocuments    int
	BulkBytes        int
}

Limits bounds work before it reaches a backend. Zero option fields inherit defaults.

func DefaultLimits

func DefaultLimits() Limits

DefaultLimits returns conservative allocation and backend-work budgets. @group Construction

type MultiObserver

type MultiObserver []Observer

MultiObserver delivers events in registration order with independent panic isolation.

func (MultiObserver) Observe

func (m MultiObserver) Observe(ctx context.Context, e Event)

Observe ensures a failed observer does not suppress later observers. @group Observability

type Mutation

type Mutation struct {
	// contains filtered or unexported fields
}

Mutation is an immutable tagged operation whose zero value is invalid.

func DeleteMutation

func DeleteMutation(id DocumentID) (Mutation, error)

DeleteMutation validates an ID for idempotent deletion. @group Mutations

func UpsertMutation

func UpsertMutation(d Document) (Mutation, error)

UpsertMutation takes ownership of document bytes after structural validation. @group Mutations

func (Mutation) Document

func (m Mutation) Document() (Document, bool)

Document returns owned data only for upserts. @group Mutations

func (Mutation) ID

func (m Mutation) ID() DocumentID

ID returns the explicit document identity. @group Mutations

func (Mutation) Kind

func (m Mutation) Kind() MutationKind

Kind identifies which operation this mutation contains. @group Mutations

type MutationKind

type MutationKind string

MutationKind distinguishes complete replacement from idempotent deletion.

const (
	// MutationUpsert replaces a complete document.
	MutationUpsert MutationKind = "upsert"
	// MutationDelete removes an ID if present.
	MutationDelete MutationKind = "delete"
)

type Observer

type Observer interface{ Observe(context.Context, Event) }

Observer receives synchronous events after driver locks have been released.

type ObserverFunc

type ObserverFunc func(context.Context, Event)

ObserverFunc adapts an application callback to an Observer.

func (ObserverFunc) Observe

func (f ObserverFunc) Observe(ctx context.Context, e Event)

Observe invokes the application callback. @group Observability

type Option

type Option func(*Index) error

Option configures domain limits or safe observation before the handle is published.

func WithLimits

func WithLimits(l Limits) Option

WithLimits replaces nonzero limits, up to sixteen times each default ceiling. @group Construction

func WithObserver

func WithObserver(o Observer) Option

WithObserver attaches synchronous, panic-isolated observation without retaining contexts. @group Construction

type Outcome

type Outcome struct {
	State     OutcomeState
	VisibleAt time.Time
	Bulk      *BulkOutcome
	Error     error
}

Outcome returns terminal failure as data, keeping any bulk details available.

type OutcomeState

type OutcomeState string

OutcomeState describes a trustworthy terminal mutation outcome.

const (
	// OutcomeSucceeded proves visibility to subsequent queries on this index.
	OutcomeSucceeded OutcomeState = "succeeded"
	// OutcomeFailed identifies terminal failure.
	OutcomeFailed OutcomeState = "failed"
	// OutcomeUnknown identifies accepted work whose terminal result cannot be proved.
	OutcomeUnknown OutcomeState = "unknown"
)

type Page

type Page[T any] struct {
	Hits   []HitOf[T]
	Total  Total
	Facets []FacetResult
	Took   time.Duration
}

Page is a typed complete search response.

func SearchAs

func SearchAs[T any](ctx context.Context, index *Index, q Query) (Page[T], error)

SearchAs decodes every hit and preserves its separate identity and metadata. @group Results

type Query

type Query struct {
	Text      string
	Fields    []FieldName
	Filter    Filter
	Sort      []Sort
	Facets    []TermFacet
	Highlight []Highlight
	Offset    uint64
	Limit     uint64
}

Query specifies literal all-terms text, typed filtering, and bounded pagination.

type Receipt

type Receipt struct {
	// contains filtered or unexported fields
}

Receipt is an opaque, immutable process-local accepted-work token.

func NewReceipt

func NewReceipt(token []byte) (Receipt, error)

NewReceipt creates a bounded driver token without attaching it to an Index. @group Receipts

func Upsert

func Upsert[T any](ctx context.Context, index *Index, id DocumentID, value T) (Receipt, error)

Upsert encodes a typed value before replacing the complete document. @group Documents

func (Receipt) Token

func (r Receipt) Token() []byte

Token returns an owned copy for the issuing backend. @group Receipts

type Result

type Result struct {
	Hits   []Hit
	Total  Total
	Facets []FacetResult
	Took   time.Duration
}

Result contains one complete backend search response.

type Segment

type Segment struct {
	Text    string
	Matched bool
}

Segment is untrusted text; UIs escape Text even when Matched is true.

type Sort

type Sort struct {
	Field     FieldName
	Direction Direction
}

Sort selects a required, sortable field. Drivers append an ascending ID tie-break.

type TermFacet

type TermFacet struct {
	Name  string
	Field FieldName
	Limit uint64
}

TermFacet counts distinct per-document terms before hit pagination.

type Total

type Total struct {
	Value    uint64
	Relation TotalRelation
}

Total retains count precision independently of pagination.

type TotalRelation

type TotalRelation string

TotalRelation describes the accuracy of a result count.

const (
	// TotalExact reports a complete count.
	TotalExact TotalRelation = "exact"
	// TotalEstimated reports an approximate count.
	TotalEstimated TotalRelation = "estimated"
	// TotalLowerBound reports a proven minimum.
	TotalLowerBound TotalRelation = "lower_bound"
)

type UnknownOutcomeError

type UnknownOutcomeError struct {
	// contains filtered or unexported fields
}

UnknownOutcomeError retains recoverable accepted-work evidence without exposing backend prose.

func NewUnknownOutcomeError

func NewUnknownOutcomeError(receipt Receipt) *UnknownOutcomeError

NewUnknownOutcomeError lets a driver return recoverable evidence after uncertain submission. @group Receipts

func (*UnknownOutcomeError) Error

func (e *UnknownOutcomeError) Error() string

Error reports uncertainty without serializing the opaque token. @group Receipts

func (*UnknownOutcomeError) Receipt

func (e *UnknownOutcomeError) Receipt() (Receipt, bool)

Receipt returns immutable recovery evidence when the driver obtained a trustworthy token. @group Receipts

func (*UnknownOutcomeError) Unwrap

func (e *UnknownOutcomeError) Unwrap() error

Unwrap preserves the stable uncertainty classification. @group Receipts

type Value

type Value struct {
	// contains filtered or unexported fields
}

Value is an immutable typed filter, facet, or sort scalar. Its zero value is invalid.

func Boolean

func Boolean(v bool) Value

Boolean constructs a Boolean scalar. @group Values

func Integer

func Integer(v int64) (Value, error)

Integer rejects values outside the exact common integer range. @group Values

func Keyword

func Keyword(v string) (Value, error)

Keyword constructs a literal string without normalization. @group Values

func (Value) Boolean

func (v Value) Boolean() (bool, bool)

Boolean returns the Boolean only for Boolean values. @group Values

func (Value) Integer

func (v Value) Integer() (int64, bool)

Integer returns the integer only for integer values. @group Values

func (Value) Keyword

func (v Value) Keyword() (string, bool)

Keyword returns the string only for keyword values. @group Values

func (Value) Kind

func (v Value) Kind() ValueKind

Kind reports the scalar's discriminator. @group Values

func (Value) MarshalJSON

func (v Value) MarshalJSON() ([]byte, error)

MarshalJSON preserves a Value's scalar JSON shape for typed result DTOs and rejects its invalid zero value. @group Values

type ValueKind

type ValueKind string

ValueKind distinguishes portable scalar types.

Directories

Path Synopsis
driver
elasticsearch
Package elasticsearch implements service-backed lexical search with Elasticsearch.
Package elasticsearch implements service-backed lexical search with Elasticsearch.
meilisearch
Package meilisearch implements asynchronous service-backed lexical search.
Package meilisearch implements asynchronous service-backed lexical search.
opensearch
Package opensearch implements service-backed lexical search with OpenSearch.
Package opensearch implements service-backed lexical search with OpenSearch.
postgressearch
Package postgressearch implements portable lexical search using PostgreSQL full-text search.
Package postgressearch implements portable lexical search using PostgreSQL full-text search.
redissearch
Package redissearch implements bounded, exact lexical search with Redis Search on a standalone Redis service.
Package redissearch implements bounded, exact lexical search with Redis Search on a standalone Redis service.
sqlitesearch
Package sqlitesearch implements portable lexical search using SQLite FTS5.
Package sqlitesearch implements portable lexical search using SQLite FTS5.
typesensesearch
Package typesensesearch implements service-backed search with Typesense.
Package typesensesearch implements service-backed search with Typesense.
blevesearch module
internal
driverutil
Package driverutil implements physical encoding shared by first-party drivers.
Package driverutil implements physical encoding shared by first-party drivers.
sqlsearch
Package sqlsearch implements transactional storage shared by native SQL full-text drivers.
Package sqlsearch implements transactional storage shared by native SQL full-text drivers.
Package searchfake supplies a scripted backend for isolated application tests.
Package searchfake supplies a scripted backend for isolated application tests.
Package searchtest supplies reusable semantic fixtures for real backend drivers.
Package searchtest supplies reusable semantic fixtures for real backend drivers.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL