# gizmodel/sql/types/tsearch

Text search as PostgreSQL 16 does it: the tsvector and tsquery types and their canonical text (tsvector_parser.c, tsvector.c, tsquery.c), the default parser (wparser_def.c) and its tokens through the configurations and dictionaries of tsdict.giz, to_tsquery and its relatives, @@ (tsvector_op.c TS_execute), ts_rank and ts_rank_cd (tsrank.c) and the editing functions. A value of either type is its canonical text.

```gizlang
import * as Tsearch from "gizmodel/sql/types/tsearch";
```

## Types

### `QNode`

```gizlang
type QNode = { k: i64; word: string; weight: i64; prefix: bool; dist: i64; l: i64; r: i64; }
```

A tsquery node: an operand (QVAL: the lexeme, its weight mask, A 8 B 4 C 2 D 1, and its prefix flag), !, &, |
or <dist>. `l` and `r` index the operands in Query.nodes (! has `l` only). QSTOP holds a stop word's place
while to_tsquery builds a query.

- `k`: `i64`
- `word`: `string`
- `weight`: `i64`
- `prefix`: `bool`
- `dist`: `i64`
- `l`: `i64`
- `r`: `i64`

### `Query`

```gizlang
type Query = { nodes: Vec<QNode>; root: i64; }
```

A tsquery: its nodes and the root's index, -1 for the empty query.

- `nodes`: `Vec<M166.QNode>`
- `root`: `i64`

## Functions

### `tsvectorIn`

```gizlang
function tsvectorIn(input: string): string throws DbError
```

A tsvector's text in its canonical form.

Effects: fail, alloc.

### `tsvectorConcat`

```gizlang
function tsvectorConcat(a: string, b: string): string throws DbError
```

a || b: b's positions move past a's largest (tsvector_concat).

Effects: fail, alloc.

### `tsvectorStrip`

```gizlang
function tsvectorStrip(a: string): string throws DbError
```

strip(v): the lexemes without positions.

Effects: fail, alloc.

### `tsvectorLength`

```gizlang
function tsvectorLength(a: string): i64 throws DbError
```

length(v): the number of lexemes.

Effects: fail, alloc.

### `tsvectorSetweight`

```gizlang
function tsvectorSetweight(a: string, weight: string, only: Option<Vec<string>>): string throws DbError
```

setweight(v, weight [, lexemes]): every position of the lexemes named (all when `only` is none) gets the weight.

Effects: fail, alloc.

### `tsvectorDelete`

```gizlang
function tsvectorDelete(a: string, names: Vec<string>): string throws DbError
```

ts_delete(v, lexemes): v without the lexemes named.

Effects: fail, alloc.

### `tsvectorFilter`

```gizlang
function tsvectorFilter(a: string, weights: Vec<string>): string throws DbError
```

ts_filter(v, weights): the positions with one of the weights; a lexeme left without any is dropped.

Effects: fail, alloc.

### `tsvectorWords`

```gizlang
function tsvectorWords(a: string): Vec<string> throws DbError
```

tsvector_to_array(v): the lexemes.

Effects: fail, alloc.

### `wordsTsvector`

```gizlang
function wordsTsvector(words: Vec<string>): string throws DbError
```

array_to_tsvector(words): the words as lexemes without positions.

Effects: fail, alloc.

### `tsqueryIn`

```gizlang
function tsqueryIn(input: string): string throws DbError
```

A tsquery's text in its canonical form.

Effects: fail, alloc.

### `toTsquery`

```gizlang
function toTsquery(env: TsEnv, config: string, text: string, how: i64): string throws DbError
```

to_tsquery and its relatives: the canonical text of `text` read through `config`.

Effects: fail, alloc.

### `tsqueryNodes`

```gizlang
function tsqueryNodes(a: string): i64 throws DbError
```

numnode(q): the number of nodes.

Effects: fail, alloc.

### `tsqueryTree`

```gizlang
function tsqueryTree(a: string): string throws DbError
```

querytree(q): the part an index can use, T when that is nothing.

Effects: fail, alloc.

### `tsqueryAnd`

```gizlang
function tsqueryAnd(a: string, b: string): string throws DbError
```

The tsquery A & B.

Effects: fail, alloc.

### `tsqueryOr`

```gizlang
function tsqueryOr(a: string, b: string): string throws DbError
```

The tsquery A | B.

Effects: fail, alloc.

### `tsqueryPhrase`

```gizlang
function tsqueryPhrase(a: string, b: string, dist: i64): string throws DbError
```

The tsquery A <DIST> B: B follows A at distance DIST.

Effects: fail, alloc.

### `tsqueryNot`

```gizlang
function tsqueryNot(a: string): string throws DbError
```

!! a.

Effects: fail, alloc.

### `tsqueryContains`

```gizlang
function tsqueryContains(a: string, b: string): bool throws DbError
```

a @> b: every operand of b is one of a's (tsq_mcontains).

Effects: fail, alloc.

### `tsMatch`

```gizlang
function tsMatch(vector: string, query: string): bool throws DbError
```

v @@ q: an empty query matches nothing.

Effects: fail, alloc.

### `tsRank`

```gizlang
function tsRank(weights: Vec<f64>, vector: string, query: string, method: i64): f64 throws DbError
```

ts_rank(weights, v, q, normalization) (calc_rank).

Effects: fail, alloc.

### `tsRankCd`

```gizlang
function tsRankCd(weights: Vec<f64>, vector: string, query: string, method: i64): f64 throws DbError
```

ts_rank_cd(weights, v, q, normalization) (calc_rank_cd).

Effects: fail, alloc.

### `jsonTsvector`

```gizlang
function jsonTsvector(env: TsEnv, config: string, strings: Vec<string>): string throws DbError
```

json(b)_to_tsvector of the document's chosen strings: each string's words, and one position more after a string
that gave any, so that a phrase does not cross two strings.

Effects: fail, alloc.

### `toTsvector`

```gizlang
function toTsvector(env: TsEnv, config: string, input: string): string throws DbError
```

to_tsvector(config, text).

Effects: fail, alloc.

### `recordText`

```gizlang
function recordText(cells: Vec<Option<string>>): string
```

A row's text as record_out writes it: a field with a quote, backslash, parenthesis, comma or space, or an
empty one, in quotes; NULL as nothing.

Effects: fail, alloc.

### `textSearchRows`

```gizlang
function textSearchRows(env: TsEnv, name: string, args: Vec<string>): Vec<Vec<Option<string>>> throws DbError
```

The rows of the text search set-returning functions: unnest(tsvector) (lexeme, positions, weights),
ts_token_type(parser), ts_parse(parser, text) and ts_debug(config, text); a NULL cell is none.

Effects: fail, alloc.

### `tsHeadline`

```gizlang
function tsHeadline(env: TsEnv, config: string, input: string, query: string, options: string): string throws DbError
```

ts_headline(config, document, query, options): the document's best part with the query's words marked.

Effects: fail, alloc.

### `textSearchCompare`

```gizlang
function textSearchCompare(a: string, b: string, vector: bool): i64 throws DbError
```

tsquery_cmp and tsvector_cmp: -1, 0 or 1.

Effects: fail, alloc.

### `tsRewrite`

```gizlang
function tsRewrite(query: string, target: string, substitute: string): string throws DbError
```

ts_rewrite(query, target, substitute).

Effects: fail, alloc.

### `tsRewriteRows`

```gizlang
function tsRewriteRows(query: string, targets: Vec<Option<string>>, substitutes: Vec<Option<string>>): string throws DbError
```

ts_rewrite(query, select): each (target, substitute) row applied in order, then the result flattened and sorted.

Effects: fail, alloc.

## Constants

### `TSQ_STANDARD`

```gizlang
const TSQ_STANDARD: i64 = 0
```

How to_tsquery reads its text.

### `TSQ_PLAIN`

```gizlang
const TSQ_PLAIN: i64 = 1
```

How plainto_tsquery reads its text.

### `TSQ_PHRASE`

```gizlang
const TSQ_PHRASE: i64 = 2
```

How phraseto_tsquery reads its text.

### `TSQ_WEB`

```gizlang
const TSQ_WEB: i64 = 3
```

How websearch_to_tsquery reads its text.

### `T_FLOAT`

```gizlang
const T_FLOAT: i64 = 20
```

Token type of the text search parser: a decimal number.

### `T_INT`

```gizlang
const T_INT: i64 = 21
```

Token type of the text search parser: a signed integer.

