7.15.4. escalate — Groonga v14.0.9ドキュメント

Skip to main content
`Ctrl`+`K`

# 7.15.4. `escalate`

Added in version 12.0.8.

## 7.15.4.1. 概要

注釈

この関数は実験的です。

これは、既存のマッチエスカレーションの仕組みと似ていますが、より一般的です。

マッチエスカレーションとは自動で条件のゆるい検索をする機能のことです。ヒット数が `match_escalation_threshold` で指定したしきい値よりも小さい時、自動で条件のゆるい検索をします。これがマッチエスカレーションです。

検索方法のエスカレーションについては 検索 を参照してください。

`match_escalation_threshold` は `select` の引数です。また、デフォルト値は `0` です。`match_escalation_threshold` については、 select を参照してください。

既存のマッチエスカレーションでは、一つの全文検索インデックスが対象です。そのため、例えば、厳密に検索するインデックスで検索して結果が取得できなかった場合、もう一度ゆるく検索するインデックスで検索を実行する必要がありました。この方法はオーバヘッドが大きい方法です。

しかし、 `escalate` は複数のインデックスにも対応しています。そのため、厳密に検索するインデックスを使った検索とゆるく検索するインデックスを使った検索を一つのクエリーで実行できます。`escalate` を使うことによって、オーバーヘッドを減らすことができます。

## 7.15.4.2. 構文

`escalate` は一つ以上の引数を持ちます。

>     escalate(CONDITION_1,
>              THRESHOLD_2, CONDITION_2,
>              ...,
>              THRESHOLD_N, CONDITION_N)

`CONDITION_N` と `THRESHOLD_N` はペアです。ただし、 `CONDITION_1` はペアとなるしきい値はありません。この条件は常に実行されるためです。

## 7.15.4.3. 使い方

使い方を示すために使うスキーマ定義とサンプルデータは以下の通りです。

サンプルスキーマ:

実行例:

    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]

サンプルデータ:

実行例:

    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]

以下は簡単な使用例です。

実行例:

    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. 引数

### 7.15.4.4.1. `CONDITION_1`

`CONDITION_1` は必須です。

`CONDITION_1` に指定した条件は常に実行されます。そのため、 `CONDITION_1` はペアとなるしきい値を持ちません。

通常、最も検索結果を絞り込める条件を指定します。

`CONDITION_1` は "number_column > 29" のようなスクリプト構文の文字列です。

### 7.15.4.4.2. `CONDITION_N`

`CONDITION_N` は省略可能です。

一つ前の条件での検索結果がしきい値以下だった場合に、 `escalate` は `CONDITION_N` を評価します。

`CONDITION_N` は "number_column > 29" のようなスクリプト構文の文字列です。

### 7.15.4.4.3. `THRESHOLD_N`

`THRESHOLD_N` は省略可能ですが、 `CONDITION_N` がある場合は、 `THRESHOLD_N` は必須です。(ただし、 `CONDITION_1` はペアとなるしきい値はありません。)

`CONDITION_N-1` で検索した結果が `THRESHOLD_N` 以下の場合、 `escalate` は `CONDITION_N` を評価します。`CONDITION_N-1` で検索した結果が `THRESHOLD_N` より大きい場合、 `escalate` は `CONDITION_N` を評価しません。

`THRESHOLD_N` は `0` や `29` のような `0` 以上の正の整数です。

## 7.15.4.5. 戻り値

`escalate` は対象レコードがマッチしたかどうかを真偽値で返します。