Search functions

These functions are used in conjunction with the @@ operator (the ‘matches’ operator) to either collect the relevance score or highlight the searched keywords within the content.

The examples below assume the following queries:

CREATE book:1 SET title = "Rust Web Programming";
DEFINE ANALYZER book_analyzer TOKENIZERS blank, class, camel, punct FILTERS snowball(english);
DEFINE INDEX book_title ON book FIELDS title SEARCH ANALYZER book_analyzer BM25;

search::analyze

The search_analyze function returns the outut of a defined search analyzer on an input string.

API DEFINITION
search::analyze(analyzer, string) -> array<string>

First define the analyzer using the DEFINE ANALYZER statement

Define book analyzer
DEFINE ANALYZER book_analyzer TOKENIZERS blank, class, camel, punct FILTERS snowball(english);

Next you can pass the analyzer to the search::analyzefunction. The following example shows this function, and its output, when used in a RETURN statement:

RETURN search::analyze("book_analyzer", "A hands-on guide to developing, packaging, and deploying fully functional Rust web applications");

Output
[
	'a',
	'hand',
	'-',
	'on',
	'guid',
	'to',
	'develop',
	',',
	'packag',
	',',
	'and',
	'deploy',
	'fulli',
	'function',
	'rust',
	'web',
	'applic'
]

search::score

The search::score function returns the relevance score corresponding to the given ‘matches’ predicate reference numbers.

API DEFINITION
search::score(number) -> number

The following example shows this function, and its output, when used in a RETURN statement:

SELECT id, title, search::score(1) AS score FROM book
	WHERE title @1@ 'rust web'
	ORDER BY score DESC;

Output
[
	{
		id: book:1,
		score: 0.9227996468544006,
		title: [ 'Rust Web Programming' ],
	}
]

search::highlight

The search::highlight function highlights the matching keywords for the predicate reference number.

API DEFINITION
search::highlight(string, string, number, [boolean]) -> string | string[]

The following example shows this function, and its output, when used in a RETURN statement:

SELECT id, search::highlight('<b>', '</b>', 1) AS title
	FROM book WHERE title @1@ 'rust web';

Output
[
	{
		id: book:1,
		title: [ '<b>Rust</b> <b>Web</b> Programming' ]
	}
]

The optional Boolean parameter can be set to true to explicitly request that the whole found term be highlighted, or set to false to highlight only the sequence of characters we are looking for. This must be used with an edgengram or ngram filter. The default value is true.

search::offsets

The search::offsets function returns the position of the matching keywords for the predicate reference number.

API DEFINITION
search::offsets(number, [boolean]) -> object

The following example shows this function, and its output, when used in a RETURN statement:

SELECT id, title, search::offsets(1) AS title_offsets
	FROM book WHERE title @1@ 'rust web';

Output
[
	{
		id: book:1,
		title: [ 'Rust Web Programming' ],
		title_offsets: {
			0: [
				{ e: 4, s: 0 },
				{ e: 8, s: 5 }
			]
		}
	}
]

The output returns the start s and end e positions of each matched term found within the original field.

The full-text index is capable of indexing both single strings and arrays of strings. In this example, the key 0 indicates that we’re highlighting the first string within the title field, which contains an array of strings.

The optional Boolean parameter can be set to true to explicitly request that the whole found term be highlighted, or set to false to highlight only the sequence of characters we are looking for. This must be used with an edgengram or ngram filter. The default value is true.