7.16.4. escalate — Groonga v16.0.9 documentation

Skip to main content
`Ctrl`+`K`

# 7.16.4. `escalate`

Added in version 12.0.8.

## 7.16.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 strategy 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.16.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.16.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.16.4.4. Parameters

### 7.16.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.16.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.16.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.16.4.5. Return value

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