search

type Document ¶

type Document struct {
	// ID uniquely identifies the document within its index.
	ID string
	// Fields holds the searchable/filterable attributes. Keys are field names.
	Fields map[string]any
}

Document is a single indexable record: a stable ID plus a set of searchable fields. Field values may be strings, numbers, or bools; non-string values are stringified for the full-text index and kept verbatim for equality filters.

func Doc(id string, fields map[string]any) Document

type Engine ¶

type Engine interface {
	// Index inserts or replaces documents in the named index. Re-indexing a
	// document with an existing ID replaces it.
	Index(ctx context.Context, index string, docs ...Document) error
	// Delete removes documents by ID from the named index. Unknown IDs are
	// ignored.
	Delete(ctx context.Context, index string, ids ...string) error
	// Search runs query against the named index and returns a ranked,
	// paginated page of hits.
	Search(ctx context.Context, index, query string, opts Options) (Results, error)
}

Engine is the search backend contract. Implementations must be safe for concurrent use.

type Hit ¶

type Hit struct {
	ID     string
	Score  float64
	Fields map[string]any
}

Hit is a single search result: the matched document ID, its relevance score (higher is more relevant), and the original fields (when the engine retains them).

type Indexer ¶ added in v0.25.0

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

Indexer mirrors model writes into a search Engine. It is a thin, stateless adapter around an Engine that speaks in terms of Searchable models and index IDs, so application code never has to thread index names and Document construction through every call site. The zero value is not usable; build one with NewIndexer.

Indexer holds no state of its own and is safe for concurrent use whenever the underlying Engine is (both bundled engines are).

func NewIndexer(eng Engine) *Indexer

func (ix *Indexer) Backfill(ctx context.Context, items ...Searchable) error

func (ix *Indexer) Delete(ctx context.Context, index, id string) error

func (ix *Indexer) DeleteModel(ctx context.Context, m Searchable) error

func (ix *Indexer) Engine() Engine

func (ix *Indexer) Index(ctx context.Context, m Searchable) error

type Memory ¶

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

Memory is a dependency-free, in-memory search Engine. It keeps every indexed document in a per-index map and answers queries by tokenizing both the stored documents and the query, then scoring by term-frequency overlap. It is the default engine returned by NewMemory and is safe for concurrent use.

Ranking is intentionally simple: each query token contributes the number of times it appears across a document's fields (its term frequency). When Options.Prefix is set, a query token also matches any document token that has it as a prefix. Documents with a higher accumulated score rank first; ties break on document ID for a stable ordering.

package main

import (
	"context"
	"fmt"

	"github.com/devituz/lagodev/search"
)

func main() {
	ctx := context.Background()
	eng := search.NewMemory()

	_ = eng.Index(ctx, "posts",
		search.Doc("1", map[string]any{"title": "Hello World", "body": "first post"}),
		search.Doc("2", map[string]any{"title": "Goodbye World", "body": "last post"}),
		search.Doc("3", map[string]any{"title": "World World World", "body": "all about the world"}),
	)

	res, err := eng.Search(ctx, "posts", "world", search.Options{})
	if err != nil {
		fmt.Println("search:", err)
		return
	}

	fmt.Println("total:", res.Total)
	for _, hit := range res.Hits {
		fmt.Printf("%s score=%.0f\n", hit.ID, hit.Score)
	}

}

Output:
total: 3
3 score=4
1 score=1
2 score=1

func NewMemory() *Memory

func (m *Memory) Delete(_ context.Context, index string, ids ...string) error

func (m *Memory) Index(_ context.Context, index string, docs ...Document) error

func (m *Memory) Search(_ context.Context, index, query string, opts Options) (Results, error)

type Options ¶

type Options struct {
	// Page is 1-indexed; values < 1 are treated as 1.
	Page int
	// PerPage is the page size; values < 1 fall back to DefaultPerPage.
	PerPage int
	// Filters constrains results to documents whose field equals the given
	// value (string-compared). Multiple filters are AND-ed.
	Filters map[string]any
	// Prefix enables prefix matching in addition to exact term matching, so a
	// query token "hel" matches "hello". Affects the Memory engine; the
	// Postgres engine appends ":*" to query lexemes.
	Prefix bool
}

Options controls a Search call: pagination, equality filters, and prefix matching. The zero value is valid (first page, default size, term matching).

type PgConfig ¶

type PgConfig struct {
	// IDColumn is the primary-key column scanned into Hit.ID. Default: "id".
	IDColumn string
	// VectorColumn is the tsvector column matched against the tsquery and fed
	// to ts_rank for scoring. Default: "search".
	VectorColumn string
	// FieldsColumn, when non-empty, is selected and scanned into Hit.Fields via
	// a sql.Scanner-compatible destination supplied by the caller's driver.
	// Default: "" (Hit.Fields left nil).
	FieldsColumn string
	// Config is the Postgres text-search configuration passed to the tsquery/
	// tsvector functions (e.g. "english", "simple"). Default: "english".
	Config string
	// WebSearch selects websearch_to_tsquery instead of plainto_tsquery. It is
	// ignored when Prefix matching is requested, since websearch syntax does
	// not compose with the ":*" prefix operator.
	WebSearch bool
}

PgConfig customizes the SQL the Postgres engine emits. The zero value is valid and targets a conventional layout: one physical table per index, with a text "id" column, a generated/maintained tsvector "search" column, and a JSON/JSONB "fields" column scanned back into Hit.Fields.

type Postgres ¶

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

Postgres is a full-text search Engine backed by database/sql and Postgres' tsvector/tsquery machinery. It compiles parameterized SELECTs that rank rows with ts_rank and paginate with LIMIT/OFFSET. The engine never interpolates user input into SQL text: index names and column identifiers come from configuration, while the query and filter values are always bound parameters.

func NewPostgres(db querier, cfg PgConfig) *Postgres

func (p *Postgres) Delete(ctx context.Context, index string, ids ...string) error

func (p *Postgres) Index(_ context.Context, _ string, _ ...Document) error

func (p *Postgres) Search(ctx context.Context, index, query string, opts Options) (Results, error)

type Results ¶

type Results struct {
	Hits  []Hit
	Total int
}

Results is a page of search hits plus the total number of matches across all pages (before pagination).

type Searchable ¶ added in v0.25.0

type Searchable interface {
	// SearchIndex is the index name this model indexes into.
	SearchIndex() string
	// SearchDocument is the model's projection into an indexable Document.
	SearchDocument() Document
}

Searchable is implemented by a model that knows how to project itself into a search Document. It is deliberately ORM-agnostic: the search package never imports orm, so a model can opt into indexing by satisfying this interface without coupling the two packages. The wiring into ORM lifecycle hooks lives in application code (see the package docs and docs/SEARCH.md).

SearchIndex returns the name of the index the model belongs to (e.g. "posts"). All rows of the same model normally share one index.

SearchDocument returns the indexable projection of the model: a stable ID plus the searchable/filterable fields. The returned Document.ID is the value used to replace or evict the row, so it must be stable across saves (the primary key is the natural choice).