1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
.. -*- rst -*-
.. groonga-command
.. database: functions_escalate
``escalate``
============
.. versionadded:: 12.0.8
Summary
-------
.. note::
This function is experimental.
This `escalate` function is similar to the existing match escalation mechanism but is more close to common approach.
Match escalation is auto loose search.
If the number of matched records is equal or less than the threshold specified by ``match_escalation_threshold``, loose search is done automatically. It's match escalation.
Please refer to :doc:`/spec/search` about the search storategy escalation.
``match_escalation_threshold`` is ``select``'s argument. In addition, the default value of ``match_escalation_threshold`` is `0`.
Please refer to :doc:`/reference/commands/select` about ``match_escalation_threshold``.
The existing match escalation mechanism is just for one full text search by inverted index.
Therefore, for example, if we can't get record in a search with a index that execute search strictly, we need to search with a index that execute search loosely once again.
Those processes take more.
However, ``escalate`` is for multiple full text search by inverted index.
Therefore, we can execute a search with a index that execute search strictly and a search with a index that execute search loosely in one query.
We can reduce overhead by using ``escalate``.
Syntax
------
``escalate`` requires one or more parameters.
.. code-block::
escalate(CONDITION_1,
THRESHOLD_2, CONDITION_2,
...,
THRESHOLD_N, CONDITION_N)
``CONDITION_N`` and ``THRESHOLD_N`` are pair.
However, ``CONDITION_1`` doesn't have a threshold as pair. Because this condition is always executed.
Usage
-----
Here are a schema definition and sample data to show usage.
Sample schema:
.. groonga-command
.. include:: ../../example/reference/functions/escalate/usage_setup_schema.log
.. table_create Users TABLE_HASH_KEY ShortText
.. column_create Users age COLUMN_SCALAR Int32
.. table_create Ages TABLE_HASH_KEY Int32
.. column_create Ages user_age COLUMN_INDEX Users age
Sample data:
.. groonga-command
.. include:: ../../example/reference/functions/escalate/usage_setup_data.log
.. load --table Users
.. [
.. {"_key": "Alice", "age": 12},
.. {"_key": "Bob", "age": 13},
.. {"_key": "Calros", "age": 15},
.. {"_key": "Dave", "age": 16},
.. {"_key": "Eric", "age": 20},
.. {"_key": "Frank", "age": 21}
.. ]
Here is a simple example.
.. groonga-command
.. include:: ../../example/reference/functions/escalate/usage_age.log
.. select Users --filter "escalate('age >= 65', 0, 'age >= 60', 0, 'age >= 50', 0, 'age >= 40', 0, 'age >= 30', 0, 'age >= 20')"
Parameters
----------
``CONDITION_1``
~~~~~~~~~~~~~~~
``CONDITION_1`` is required.
A condition that we specify ``CONDITION_1`` is always executed.
Therefore, ``CONDITION_1`` doesn't have a threshold as pair.
Normally, we specify the condition that we can the most narrow down search results.
``CONDITION_1`` is a string that uses script syntax such as "number_column > 29".
``CONDITION_N``
~~~~~~~~~~~~~~~
``CONDITION_N`` is optional.
If the number of searched results with the one before condition in threshold or less, ``escalate`` evaluate ``CONDITION_N``.
``CONDITION_N`` is a string that uses script syntax such as "number_column > 29".
``THRESHOLD_N``
~~~~~~~~~~~~~~~
``THRESHOLD_N`` is optional. However, when ``CONDITION_N`` exists ``THRESHOLD_N`` is required. (However, ``CONDITION_1`` doesn't have a threshold as pair.)
If the number of results that we search with ``CONDITION_N-1`` in ``THRESHOLD_N`` or less, ``escalate`` evaluate ``CONDITION_N``.
If the number of results that we search with ``CONDITION_N-1`` in more than ``THRESHOLD_N``, ``escalate`` doesn't evaluate ``CONDITION_N``.
``THRESHOLD_N`` is an integer not less than ``0`` such as ``0`` and ``29``.
Return value
------------
``escalate`` returns whether a record is matched or not as boolean.
|
