本文へスキップ
`Ctrl`+`K`

# 7.15.14. `in_values`

## 7.15.14.1. 概要

Added in version 4.0.7.

`in_values` は 複数の `OR` や `==` を使っているクエリを簡略化できます。複数の `OR` や `==` を使うよりは `in_values` を使うのがパフォーマンスの観点からおすすめです。

## 7.15.14.2. 構文

`in_values` には2つ以上の引数を指定する必要があります。 `target_value` を1つと 1つ以上の `value` を指定します。

    in_values(target_value, value1, ..., valueN)
    in_values(target_value, value1, ..., valueN, {"option": "value of option"}

## 7.15.14.3. 使い方

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

サンプルスキーマ:

実行例:

    table_create Tags TABLE_PAT_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    table_create Memos TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Memos tag COLUMN_SCALAR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Tags memos_tag COLUMN_INDEX Memos tag
    # [[0,1337566253.89858,0.000355720520019531],true]

サンプルデータ:

実行例:

    load --table Memos
    [
    {"_key": "Groonga is fast",          "tag": "groonga"},
    {"_key": "Mroonga is fast",          "tag": "mroonga"},
    {"_key": "Rroonga is fast",          "tag": "rroonga"},
    {"_key": "Droonga is fast",          "tag": "droonga"},
    {"_key": "Groonga is a HTTP server", "tag": "groonga"}
    ]
    # [[0,1337566253.89858,0.000355720520019531],5]

`in_values` 関数を使って `tag` カラムの値が "groonga" 、 "mroonga" あるいは "droonga" であるものを選択する例を示します。

実行例:

    select Memos --output_columns _key,tag --filter 'in_values(tag, "groonga", "mroonga", "droonga")' --sort_keys _id
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         4
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         "Groonga is fast",
    #         "groonga"
    #       ],
    #       [
    #         "Mroonga is fast",
    #         "mroonga"
    #       ],
    #       [
    #         "Droonga is fast",
    #         "droonga"
    #       ],
    #       [
    #         "Groonga is a HTTP server",
    #         "groonga"
    #       ]
    #     ]
    #   ]
    # ]

クエリを実行すると、"rroonga"を除いた結果を得られます。"rroonga"は `in_values` には指定していないからです。

また、 `in_values` はオプションも指定できます。現在は、 `too_many_index_match_ratio` のみ指定できます。この値は、 `double` 型です。

`too_many_index_match_ratio` を使って、 `GRN_IN_VALUES_TOO_MANY_INDEX_MATCH_RATIO` の値を変更できます。`GRN_IN_VALUES_TOO_MANY_INDEX_MATCH_RATIO` のデフォルト値は `0.01` です。`GRN_IN_VALUES_TOO_MANY_INDEX_MATCH_RATIO` は、 `in_values` がインデックスを使うかどうかを決定するために使います。

`in_values` とANDで絞り込むと予想されるレコード数よりも、絞り込んだレコード数が十分に小さい場合は、インデックスを使った検索より、シーケンシャルサーチの方が速いことがあります。

例えば、 `--filter` でレコードを絞り込んだあと、さらに `in_values` で絞り込むとします。

デフォルトでは、以下のケースでは、 `in_values` はシーケンシャルサーチを使います。

> 1. `--filter` で絞り込んだレコード数が1000で `in_values` 対象のレコード数が500,000の場合。

>        1,000/500,000 = 0.002 < 0.01(GRN_IN_VALUES_TOO_MANY_INDEX_MATCH_RATIO) -> in_values use sequential search.

一方、以下のケースでは、 `in_values` はインデックスを使います。

> 2. `--filter` で絞り込んだレコード数が1000で `in_values` 対象のレコード数が50,000の場合。

>        1,000/50,000 = 0.02 > 0.01(GRN_IN_VALUES_TOO_MANY_INDEX_MATCH_RATIO) -> in_values use index.

`in_values` のオプションを設定するクエリーは以下の通りです。:

実行例:

    select Memos --output_columns _key,tag --filter 'in_values(tag, "groonga", "mroonga", "droonga", {"too_many_index_match_ratio":0.001})' --sort_keys _id
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         4
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         "Groonga is fast",
    #         "groonga"
    #       ],
    #       [
    #         "Mroonga is fast",
    #         "mroonga"
    #       ],
    #       [
    #         "Droonga is fast",
    #         "droonga"
    #       ],
    #       [
    #         "Groonga is a HTTP server",
    #         "groonga"
    #       ]
    #     ]
    #   ]
    # ]

## 7.15.14.4. 引数

二つ以上の引数が必須です。 `target_valule` と 1つ以上の `value` です。

### 7.15.14.4.1. `target_value`

`select` 対象の `table` に指定されたテーブルのカラムを指定します。

### 7.15.14.4.2. `value`

選択したいカラムの値を指定します。

### 7.15.14.4.3. `{"option": "value of option"}`

`in_values` のオプションを指定します。現在は、 `too_many_index_match_ratio` のみ指定できます。この値は、 `double` 型です。

## 7.15.14.5. 戻り値

`in_values` は対象となるカラムに指定した値が含まれるかを返します。

もし該当するレコードがあれば、 `true` を返します。そうでなければ `false` を返します。