fts5

package
v0.35.4 Latest Latest
Warning

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

Go to latest
Published: Sep 1, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package fts5 provides the fts5 extension.

https://sqlite.org/fts5.html

Example
package main

import (
	"errors"
	"fmt"
	"log"
	"unicode"
	"unicode/utf8"

	"github.com/ncruces/go-sqlite3"
	"github.com/ncruces/go-sqlite3/driver"
	"github.com/ncruces/go-sqlite3/ext/fts5"
	"golang.org/x/text/cases"

	_ "github.com/ncruces/go-sqlite3/vfs/memdb"
)

func main() {
	db, err := driver.Open("file:/test.db?vfs=memdb", func(c *sqlite3.Conn) error {
		return fts5.RegisterCustom(c, func(a *fts5.API) error {
			return errors.Join(
				a.CreateTokenizer("utf8", func(arg []string) (fts5.Tokenizer, error) {
					return utf8Tokenizer{}, nil
				}),
				a.CreateFunction("hit_count", func(fts fts5.Context, ctx sqlite3.Context, arg ...sqlite3.Value) {
					if count, err := fts.InstCount(); err != nil {
						ctx.ResultError(err)
					} else {
						ctx.ResultInt(count)
					}
				}))
		})
	})
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	_, err = db.Exec(`
		CREATE VIRTUAL TABLE docs USING fts5(title, body, tokenize=utf8);
		INSERT INTO docs(title, body) VALUES 
			('Go Programming', 'An intensive guide to Go routines.'),
			('SQLite Tutorial', 'Learn how to use virtual tables efficiently.');
	`)
	if err != nil {
		log.Fatal(err)
	}

	var title string
	var hits int
	err = db.QueryRow("SELECT title, hit_count(docs) FROM docs WHERE docs MATCH 'go AND routines'").Scan(&title, &hits)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%s: %d hits\n", title, hits)
}

type utf8Tokenizer struct{}

func (utf8Tokenizer) Tokenize(flags fts5.TokenizeFlag, text, locale string, token fts5.TokenCallback) error {
	folder := cases.Fold()
	isToken := func(r rune) bool {
		return unicode.IsLetter(r) || unicode.IsNumber(r) || unicode.Is(unicode.Co, r)
	}

	var start int
	for start < len(text) {
		for start < len(text) {
			r, sz := utf8.DecodeRuneInString(text[start:])
			if isToken(r) {
				break
			}
			start += sz
		}

		end := start
		for end < len(text) {
			r, sz := utf8.DecodeRuneInString(text[end:])
			if !isToken(r) {
				break
			}
			end += sz
		}

		if start < end {
			err := token(0, folder.String(text[start:end]), start, end)
			if err != nil {
				return err
			}
			start = end
		}
	}
	return nil
}
Output:
Go Programming: 3 hits

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Register

func Register(db *sqlite3.Conn) error

Register registers the fts5 extension.

func RegisterCustom added in v0.35.4

func RegisterCustom(db *sqlite3.Conn, init func(*API) error) error

Register registers the fts5 extension, allowing you to register custom tokenizers, using API.CreateTokenizer.

Types

type API added in v0.35.4

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

API exposes methods to extend FTS5.

https://sqlite.org/fts5.html#extending_fts5

func (*API) CreateFunction added in v0.35.4

func (a *API) CreateFunction(name string, fn ExtensionFunction) error

CreateFunction registers a ExtensionFunction.

https://sqlite.org/fts5.html#custom_auxiliary_functions

func (*API) CreateTokenizer added in v0.35.4

func (a *API) CreateTokenizer(name string, fn TokenizerConstructor) error

CreateTokenizer registers a Tokenizer. If fn returns an io.Closer, it will be called to free resources.

https://sqlite.org/fts5.html#custom_tokenizers

type Context added in v0.35.4

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

Context is the context in which an ExtensionFunction executes. It is in no way related to a Go context.Context.

https://sqlite.org/fts5.html#custom_auxiliary_functions_api_overview

func (Context) ColumnCount added in v0.35.4

func (c Context) ColumnCount() int

ColumnCount returns the number of columns in the table.

https://sqlite.org/fts5.html#xColumnCount

func (Context) ColumnLocale added in v0.35.4

func (c Context) ColumnLocale(col int) (string, error)

ColumnLocale returns the locale of a column.

https://sqlite.org/fts5.html#xColumnLocale

func (Context) ColumnSize added in v0.35.4

func (c Context) ColumnSize(col int) (int, error)

ColumnSize returns the number of tokens in a column.

https://sqlite.org/fts5.html#xColumnSize

func (Context) ColumnText added in v0.35.4

func (c Context) ColumnText(col int) (string, error)

ColumnText returns the text of a column.

https://sqlite.org/fts5.html#xColumnText

func (Context) ColumnTotalSize added in v0.35.4

func (c Context) ColumnTotalSize(col int) (int64, error)

ColumnTotalSize returns the total number of tokens in a column.

https://sqlite.org/fts5.html#xColumnTotalSize

func (Context) GetAuxdata added in v0.35.4

func (c Context) GetAuxdata(clear bool) any

GetAuxdata gets the extension function's auxiliary data.

https://sqlite.org/fts5.html#xGetAuxdata

func (Context) Inst added in v0.35.4

func (c Context) Inst(idx int) (phrase, col, off int, err error)

Inst returns the details of phrase match idx within the current row.

https://sqlite.org/fts5.html#xInst

func (Context) InstCount added in v0.35.4

func (c Context) InstCount() (int, error)

InstCount returns the number of occurrences of all phrases within the query within the current row.

https://sqlite.org/fts5.html#xInstCount

func (Context) InstToken added in v0.35.4

func (c Context) InstToken(idx, token int) (string, error)

InstToken returns a token from a phrase hit of the current query.

https://sqlite.org/fts5.html#xInstToken

func (Context) PhraseCount added in v0.35.4

func (c Context) PhraseCount() int

PhraseCount returns the number of phrases in the current query.

https://sqlite.org/fts5.html#xPhraseCount

func (Context) PhraseIter added in v0.35.4

func (c Context) PhraseIter(phrase int) (iter.Seq2[int, int], error)

PhraseIter returns a single-use iterator over all instances of a query phrase within the current row.

https://sqlite.org/fts5.html#xPhraseFirst

func (Context) PhraseIterColumn added in v0.35.4

func (c Context) PhraseIterColumn(phrase int) (iter.Seq[int], error)

PhraseIterColumn returns a single-use iterator over the set of columns in the current row that contain one or more instances of a specified phrase.

https://sqlite.org/fts5.html#xPhraseFirstColumn

func (Context) PhraseSize added in v0.35.4

func (c Context) PhraseSize(phrase int) int

PhraseSize returns the number of tokens in the given phrase.

https://sqlite.org/fts5.html#xPhraseSize

func (Context) QueryToken added in v0.35.4

func (c Context) QueryToken(phrase, token int) (string, error)

QueryToken returns a token from the current query.

https://sqlite.org/fts5.html#xQueryToken

func (Context) RowCount added in v0.35.4

func (c Context) RowCount() (int64, error)

RowCount returns the number of rows in the table.

https://sqlite.org/fts5.html#xRowCount

func (Context) RowID added in v0.35.4

func (c Context) RowID() int64

RowID returns the rowid of the current row.

https://sqlite.org/fts5.html#xRowid

func (Context) SetAuxdata added in v0.35.4

func (c Context) SetAuxdata(aux any) error

SetAuxdata sets the extension function's auxiliary data.

https://sqlite.org/fts5.html#xSetAuxdata

func (Context) Tokenize added in v0.35.4

func (c Context) Tokenize(text, locale string, token TokenCallback) error

Tokenize tokenizes text using the tokenizer of the table.

https://sqlite.org/fts5.html#xTokenize_v2

type ExtensionFunction added in v0.35.4

type ExtensionFunction func(fts Context, ctx sqlite3.Context, arg ...sqlite3.Value)

ExtensionFunction is a custom auxiliary function.

https://sqlite.org/fts5.html#custom_auxiliary_functions

type TokenCallback added in v0.35.4

type TokenCallback func(tflags TokenFlag, token string, start, end int) error

TokenCallback is a callback invoked to emit a token. For tokens that are substrings of the input text, token can be an empty string, enabling zero copy tokenization.

https://sqlite.org/fts5.html#custom_tokenizers

type TokenFlag added in v0.35.4

type TokenFlag uint32

TokenizeFlag is a flag may be passed by the tokenizer implementation back to FTS5 as an argument to the supplied xToken callback.

https://sqlite.org/fts5.html#custom_tokenizers

const (
	TOKEN_COLOCATED TokenFlag = 0x0001 /* Same position as prev. token */
)

type TokenizeFlag added in v0.35.4

type TokenizeFlag uint32

TokenizeFlag are flags that may be passed as the argument to Tokenizer.Tokenize.

https://sqlite.org/fts5.html#custom_tokenizers

const (
	TOKENIZE_QUERY    TokenizeFlag = 0x0001
	TOKENIZE_PREFIX   TokenizeFlag = 0x0002
	TOKENIZE_DOCUMENT TokenizeFlag = 0x0004
	TOKENIZE_AUX      TokenizeFlag = 0x0008
)

type Tokenizer added in v0.35.4

type Tokenizer interface {
	// This function is expected to tokenize text.
	// For each token in the input string, the supplied callback must be invoked.
	Tokenize(flags TokenizeFlag, text, locale string, xToken TokenCallback) error
}

Tokenizer is the interface implemented by tokenizer instances.

https://sqlite.org/fts5.html#custom_tokenizers

type TokenizerConstructor added in v0.35.4

type TokenizerConstructor func(arg []string) (Tokenizer, error)

TokenizerConstructor allocates and initializes a Tokenizer instance.

https://sqlite.org/fts5.html#custom_tokenizers

Jump to

Keyboard shortcuts

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