7.15.4. escalate

New in version 12.0.8.

7.15.4.1. 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 検索 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 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.

7.15.4.2. Syntax

escalate requires one or more parameters.

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.

7.15.4.3. Usage

Here are a schema definition and sample data to show usage.

Sample schema:

Execution example:

table_create Users TABLE_HASH_KEY ShortText
# [[0,1337566253.89858,0.000355720520019531],true]
column_create Users age COLUMN_SCALAR Int32
# [[0,1337566253.89858,0.000355720520019531],true]
table_create Ages TABLE_HASH_KEY Int32
# [[0,1337566253.89858,0.000355720520019531],true]
column_create Ages user_age COLUMN_INDEX Users age
# [[0,1337566253.89858,0.000355720520019531],true]

Sample data:

Execution example:

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}
]
# [[0,1337566253.89858,0.000355720520019531],6]

Here is a simple example.

Execution example:

select Users --filter "escalate('age >= 65', 0, 'age >= 60', 0, 'age >= 50', 0, 'age >= 40', 0, 'age >= 30', 0, 'age >= 20')"
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         2
#       ],
#       [
#         [
#           "_id",
#           "UInt32"
#         ],
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "age",
#           "Int32"
#         ]
#       ],
#       [
#         5,
#         "Eric",
#         20
#       ],
#       [
#         6,
#         "Frank",
#         21
#       ]
#     ]
#   ]
# ]

7.15.4.4. Parameters

7.15.4.4.1. 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”.

7.15.4.4.2. 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”.

7.15.4.4.3. 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.

7.15.4.5. Return value

escalate returns whether a record is matched or not as boolean.