Documentation
¶
Overview ¶
Package fts5 provides the fts5 extension.
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 ¶
- func Register(db *sqlite3.Conn) error
- func RegisterCustom(db *sqlite3.Conn, init func(*API) error) error
- type API
- type Context
- func (c Context) ColumnCount() int
- func (c Context) ColumnLocale(col int) (string, error)
- func (c Context) ColumnSize(col int) (int, error)
- func (c Context) ColumnText(col int) (string, error)
- func (c Context) ColumnTotalSize(col int) (int64, error)
- func (c Context) GetAuxdata(clear bool) any
- func (c Context) Inst(idx int) (phrase, col, off int, err error)
- func (c Context) InstCount() (int, error)
- func (c Context) InstToken(idx, token int) (string, error)
- func (c Context) PhraseCount() int
- func (c Context) PhraseIter(phrase int) (iter.Seq2[int, int], error)
- func (c Context) PhraseIterColumn(phrase int) (iter.Seq[int], error)
- func (c Context) PhraseSize(phrase int) int
- func (c Context) QueryToken(phrase, token int) (string, error)
- func (c Context) RowCount() (int64, error)
- func (c Context) RowID() int64
- func (c Context) SetAuxdata(aux any) error
- func (c Context) Tokenize(text, locale string, token TokenCallback) error
- type ExtensionFunction
- type TokenCallback
- type TokenFlag
- type TokenizeFlag
- type Tokenizer
- type TokenizerConstructor
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RegisterCustom ¶ added in v0.35.4
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.
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.
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
ColumnCount returns the number of columns in the table.
func (Context) ColumnLocale ¶ added in v0.35.4
ColumnLocale returns the locale of a column.
func (Context) ColumnSize ¶ added in v0.35.4
ColumnSize returns the number of tokens in a column.
func (Context) ColumnText ¶ added in v0.35.4
ColumnText returns the text of a column.
func (Context) ColumnTotalSize ¶ added in v0.35.4
ColumnTotalSize returns the total number of tokens in a column.
func (Context) GetAuxdata ¶ added in v0.35.4
GetAuxdata gets the extension function's auxiliary data.
func (Context) Inst ¶ added in v0.35.4
Inst returns the details of phrase match idx within the current row.
func (Context) InstCount ¶ added in v0.35.4
InstCount returns the number of occurrences of all phrases within the query within the current row.
func (Context) InstToken ¶ added in v0.35.4
InstToken returns a token from a phrase hit of the current query.
func (Context) PhraseCount ¶ added in v0.35.4
PhraseCount returns the number of phrases in the current query.
func (Context) PhraseIter ¶ added in v0.35.4
PhraseIter returns a single-use iterator over all instances of a query phrase within the current row.
func (Context) PhraseIterColumn ¶ added in v0.35.4
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.
func (Context) PhraseSize ¶ added in v0.35.4
PhraseSize returns the number of tokens in the given phrase.
func (Context) QueryToken ¶ added in v0.35.4
QueryToken returns a token from the current query.
func (Context) SetAuxdata ¶ added in v0.35.4
SetAuxdata sets the extension function's auxiliary data.
type ExtensionFunction ¶ added in v0.35.4
ExtensionFunction is a custom auxiliary function.
type TokenCallback ¶ added in v0.35.4
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.
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.
type TokenizerConstructor ¶ added in v0.35.4
TokenizerConstructor allocates and initializes a Tokenizer instance.