xapian

README

go-xapian

A thin, dependency-free cgo binding over the Xapian C++ search library. It exposes writable/read databases, documents, queries and search results — with no application-domain assumptions — so any Go program can build full-text search on top of Xapian.

Because cgo cannot call C++ directly (name mangling, templates, exceptions, RAII), every call crosses through a small extern "C" shim (shim.cc / shim.h) that converts Xapian C++ exceptions into Go errors. All handles are opaque pointers owned by the caller until the matching Close/Free.

Requirements

• Go 1.26+
• Xapian with development headers at build time:
  • Debian/Ubuntu: sudo apt-get install libxapian-dev
  • macOS (Homebrew): brew install xapian

Usage

package main

import (
	"fmt"

	"github.com/0kaba0hub/go-xapian"
)

func main() {
	w, err := xapian.OpenWDB("/tmp/idx")
	if err != nil {
		panic(err)
	}
	doc := xapian.NewDoc()
	_ = doc.AddTerm("hello")
	_ = w.ReplaceDocument(1, doc)
	doc.Free()
	_ = w.Commit()
	w.Close()

	db, _ := xapian.OpenDBMulti([]string{"/tmp/idx"})
	defer db.Close()
	q, _ := xapian.QueryTerm("hello")
	defer q.Free()
	hits, _ := db.Search(q)
	fmt.Println(hits) // [{1 ...}]
}

API surface

• WDB — writable database: OpenWDB, Commit, Close, ReplaceDocument, DeleteDocument, SetMetadata, GetMetadata, DocCount, DocExists.
• DB — read database (combines shards): OpenDBMulti, Close, LastDocID, DocIDs, Compact, Search.
• Doc — document builder: NewDoc, Free, AddTerm, AddBooleanTerm.
• Query — query tree: QueryWildcard, QueryTerm, QueryMatchAll, QueryCombine, Free.
• MSetEntry — one search hit (DocID, Weight).

License

GPL-2.0-or-later — see LICENSE. (Xapian itself is GPL-2.0-or-later; linking it makes this binding GPL too.)

Documentation

Overview

Package xapian is a thin cgo binding over the Xapian C++ search library. It exposes only writable/read databases, documents, queries and search results, with no application-domain assumptions, so it can be reused by any Go program that needs full-text search on top of Xapian.

cgo cannot call C++ directly (name mangling, templates, exceptions, RAII), so every call crosses through the extern "C" shim in shim.cc / shim.h, which converts Xapian C++ exceptions into malloc'd error strings. All handles are opaque pointers owned by the caller until the matching Close/Free.

The package requires libxapian with its development headers at build time.

Index

• Constants
• type DB
  • func OpenDBMulti(paths []string) (*DB, error)
  • func (d *DB) Close()
  • func (d *DB) Compact(dest string) error
  • func (d *DB) DocIDs() ([]uint32, error)
  • func (d *DB) LastDocID() (uint32, error)
  • func (d *DB) Search(q *Query) ([]MSetEntry, error)
• type Doc
  • func NewDoc() *Doc
  • func (d *Doc) AddBooleanTerm(term string) error
  • func (d *Doc) AddTerm(term string) error
  • func (d *Doc) Free()
• type MSetEntry
• type Op
• type Query
  • func QueryCombine(op Op, a, b *Query) (*Query, error)
  • func QueryMatchAll() (*Query, error)
  • func QueryTerm(term string) (*Query, error)
  • func QueryWildcard(pattern string) (*Query, error)
  • func (q *Query) Free()
• type WDB
  • func OpenWDB(path string) (*WDB, error)
  • func (w *WDB) Close()
  • func (w *WDB) Commit() error
  • func (w *WDB) DeleteDocument(docid uint32) (existed bool, err error)
  • func (w *WDB) DocCount() (uint32, error)
  • func (w *WDB) DocExists(docid uint32) (bool, error)
  • func (w *WDB) GetMetadata(key string) (string, error)
  • func (w *WDB) ReplaceDocument(docid uint32, d *Doc) error
  • func (w *WDB) SetMetadata(key, value string) error

Constants

const (
	OpAND    = Op(C.FCX_OP_AND)
	OpOR     = Op(C.FCX_OP_OR)
	OpANDNOT = Op(C.FCX_OP_AND_NOT)
)

Types

type DB

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

DB is a read-only Xapian database, optionally combining several on-disk shards into one searchable view.

func OpenDBMulti

func OpenDBMulti(paths []string) (*DB, error)

OpenDBMulti opens paths as one combined read-only database. An empty paths slice returns (nil, nil).

func (*DB) Close

func (d *DB) Close()

Close releases the handle. Idempotent.

func (*DB) Compact

func (d *DB) Compact(dest string) error

Compact writes a single optimized copy of the combined database to dest.

func (*DB) DocIDs

func (d *DB) DocIDs() ([]uint32, error)

DocIDs returns every document id in ascending order.

func (*DB) LastDocID

func (d *DB) LastDocID() (uint32, error)

LastDocID returns the highest document id across the combined shards.

func (*DB) Search

func (d *DB) Search(q *Query) ([]MSetEntry, error)

Search runs q against the read database and returns the ranked hits.

type Doc

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

Doc is a Xapian document under construction.

func NewDoc

func NewDoc() *Doc

NewDoc allocates an empty document. The caller must Free it (or hand it to WDB.ReplaceDocument, which does not take ownership — Free it afterwards).

func (*Doc) AddBooleanTerm

func (d *Doc) AddBooleanTerm(term string) error

AddBooleanTerm indexes a boolean (filter) term.

func (*Doc) AddTerm

func (d *Doc) AddTerm(term string) error

AddTerm indexes a free-text term.

func (*Doc) Free

func (d *Doc) Free()

Free releases the document. Idempotent.

type MSetEntry

type MSetEntry struct {
	DocID  uint32
	Weight float64
}

MSetEntry is one search hit: a document id and its relevance weight.

type Op

type Op int

Op selects how QueryCombine joins two subqueries.

type Query

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

Query is a Xapian query tree node.

func QueryCombine

func QueryCombine(op Op, a, b *Query) (*Query, error)

QueryCombine joins a and b under op. It consumes a and b (both are freed here) and returns the combined query.

func QueryMatchAll

func QueryMatchAll() (*Query, error)

QueryMatchAll builds a query that matches every document.

func QueryTerm

func QueryTerm(term string) (*Query, error)

QueryTerm builds an exact-term query.

func QueryWildcard

func QueryWildcard(pattern string) (*Query, error)

QueryWildcard builds a wildcard (prefix) query from pattern.

func (*Query) Free

func (q *Query) Free()

Free releases the query. Safe on a nil receiver or nil handle.

type WDB

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

WDB is a writable Xapian database handle.

func OpenWDB

func OpenWDB(path string) (*WDB, error)

OpenWDB opens (creating if absent) a writable database at path.

func (*WDB) Close

func (w *WDB) Close()

Close releases the handle. Idempotent.

func (*WDB) Commit

func (w *WDB) Commit() error

Commit flushes pending changes to disk.

func (*WDB) DeleteDocument

func (w *WDB) DeleteDocument(docid uint32) (existed bool, err error)

DeleteDocument removes docid. existed reports whether it was present; a not-found document is not an error.

func (*WDB) DocCount

func (w *WDB) DocCount() (uint32, error)

DocCount returns the number of documents in the writable database.

func (*WDB) DocExists

func (w *WDB) DocExists(docid uint32) (bool, error)

DocExists reports whether docid is present.

func (*WDB) GetMetadata

func (w *WDB) GetMetadata(key string) (string, error)

GetMetadata reads a metadata value; a missing key returns "".

func (*WDB) ReplaceDocument

func (w *WDB) ReplaceDocument(docid uint32, d *Doc) error

ReplaceDocument stores d under docid, replacing any existing document.

func (*WDB) SetMetadata

func (w *WDB) SetMetadata(key, value string) error

SetMetadata stores an arbitrary key/value pair in the database metadata.