7.3.57. select — Groonga v14.0.6ドキュメント

Skip to main content
`Ctrl`+`K`

# 7.3.57. `select`

## 7.3.57.1. 概要

`select` はテーブルから指定された条件にマッチするレコードを検索し、見つかったレコードを出力します。

`select` は最も重要なgroongaのコマンドです。Groongaの力を最大限に活かすためには `select` を理解する必要があります。

## 7.3.57.2. 構文

このコマンドにはたくさんの引数があります。

必須の引数は `table` だけです。残りは省略できます:

    select table
           [match_columns=null]
           [query=null]
           [filter=null]
           [scorer=null]
           [sortby=null]
           [output_columns="_id, _key, *"]
           [offset=0]
           [limit=10]
           [drilldown=null]
           [drilldown_sortby=null]
           [drilldown_output_columns="_key, _nsubrecs"]
           [drilldown_offset=0]
           [drilldown_limit=10]
           [cache=yes]
           [match_escalation_threshold=0]
           [query_expansion=null]
           [query_flags=ALLOW_PRAGMA|ALLOW_COLUMN]
           [query_expander=null]
           [adjuster=null]
           [drilldown_calc_types=NONE]
           [drilldown_calc_target=null]
           [drilldown_filter=null]
           [sort_keys=null]
           [drilldown_sort_keys=null]
           [match_escalation=auto]
           [load_table=null]
           [load_columns=null]
           [load_values=null]
           [drilldown_max_n_target_records=-1]
           [n_workers=0]
           [fuzzy_max_distance_ratio=0]
           [fuzzy_max_distance=0]
           [fuzzy_max_expansions=10]
           [fuzzy_prefix_length=0]
           [fuzzy_with_transposition=yes]
           [fuzzy_tokenize=no]

以下の名前付き引数で動的カラム機能を使うことができます。

> - `columns[${NAME}].stage=null`

> - `columns[${NAME}].flags=COLUMN_SCALAR`

> - `columns[${NAME}].type=null`

> - `columns[${NAME}].value=null`

> - `columns[${NAME}].window.sort_keys=null`

> - `columns[${NAME}].window.group_keys=null`

`${NAME}` には1つ以上のアルファベット、数字、 `_` を使うことができます。たとえば、 `column1` は有効な `${NAME}` です。これは通常のカラムと同じルールです。 name も見てください。

同じ `${NAME}` も持つ引数は同じグループになります。

たとえば、以下の引数は1つの動的カラムを指定しています。

> - `--columns[name].stage initial`

> - `--columns[name].type UInt32`

> - `--columns[name].value 29`

以下の引数は2つの動的カラムを指定しています。

> - `--columns[name1].stage initial`

> - `--columns[name1].type UInt32`

> - `--columns[name1].value 29`

> - `--columns[name2].stage filtered`

> - `--columns[name2].type Float`

> - `--columns[name2].value '_score * 0.1'`

このコマンドには高度なドリルダウン機能のために以下の名前付き引数があります。

> - `drilldowns[${LABEL}].keys=null`

> - `drilldowns[${LABEL}].sort_keys=null`

> - `drilldowns[${LABEL}].output_columns="_key, _nsubrecs"`

> - `drilldowns[${LABEL}].offset=0`

> - `drilldowns[${LABEL}].limit=10`

> - `drilldowns[${LABEL}].calc_types=NONE`

> - `drilldowns[${LABEL}].calc_target=null`

> - `drilldowns[${LABEL}].filter=null`

> - `drilldowns[${LABEL}].max_n_target_records=-1`

> - `drilldowns[${LABEL}].columns[${NAME}].stage=null`

> - `drilldowns[${LABEL}].columns[${NAME}].flags=COLUMN_SCALAR`

> - `drilldowns[${LABEL}].columns[${NAME}].type=null`

> - `drilldowns[${LABEL}].columns[${NAME}].value=null`

> - `drilldowns[${LABEL}].columns[${NAME}].window.sort_keys=null`

> - `drilldowns[${LABEL}].columns[${NAME}].window.group_keys=null`

バージョン 6.0.3 で非推奨: `drilldown[...]` 構文は非推奨になりました。代わりに `drilldowns[...]` を使用してください。

`${LABEL}` には1つ以上のアルファベット、数字、 `_` 、 `.` を使うことができます。たとえば、 `parent.sub1` は有効な `${LABEL}` です。

同じ `${LABEL}` も持つ引数は同じグループになります。

たとえば、以下の引数は1つのドリルダウンを指定しています。

> - `--drilldowns[label].keys column`

> - `--drilldowns[label].sort_keys -_nsubrecs`

以下の引数は2つのドリルダウンを指定しています。

> - `--drilldowns[label1].keys column1`

> - `--drilldowns[label1].sort_keys -_nsubrecs`

> - `--drilldowns[label2].keys column2`

> - `--drilldowns[label2].sort_keys _key`

## 7.3.57.3. 使い方

例を使いながら `select` の使い方を学びましょう。このセクションではよく使われる使い方を紹介します。

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

実行例:

    table_create Entries TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Entries content COLUMN_SCALAR Text
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Entries n_likes COLUMN_SCALAR UInt32
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Entries tag COLUMN_SCALAR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    table_create Terms TABLE_PAT_KEY ShortText --default_tokenizer TokenBigram --normalizer NormalizerAuto
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Terms entries_key_index COLUMN_INDEX|WITH_POSITION Entries _key
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Terms entries_content_index COLUMN_INDEX|WITH_POSITION Entries content
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table Entries
    [
    {"_key":    "The first post!",
     "content": "Welcome! This is my first post!",
     "n_likes": 5,
     "tag": "Hello"},
    {"_key":    "Groonga",
     "content": "I started to use Groonga. It's very fast!",
     "n_likes": 10,
     "tag": "Groonga"},
    {"_key":    "Mroonga",
     "content": "I also started to use Mroonga. It's also very fast! Really fast!",
     "n_likes": 15,
     "tag": "Groonga"},
    {"_key":    "Good-bye Senna",
     "content": "I migrated all Senna system!",
     "n_likes": 3,
     "tag": "Senna"},
    {"_key":    "Good-bye Tritonn",
     "content": "I also migrated all Tritonn system!",
     "n_likes": 3,
     "tag": "Senna"}
    ]
    # [[0,1337566253.89858,0.000355720520019531],5]

ブログエントリ用の `Entries` テーブルがあります。各エントリはタイトルと内容と「いいね！」数、タグを持っています。タイトルは `Entries` のキーとします。内容は `Entries.content` カラムの値とします。「いいね！」数は `Entries.n_likes` カラムの値とします。タグは `Entries.tag` カラムの値とします。

`Entries._key` カラムと `Entries.content` カラムには `TokenBigram` トークナイザーを使ったインデックスを作成します。そのため、 `Entries._key` と `Entries.content` は両方とも全文検索できます。

これで例を示すためのスキーマとデータの準備ができました。

### 7.3.57.3.1. 簡単な使い方

上記のスキーマとデータを使った一番簡単な使い方は以下の通りです。これは `Entries` テーブルのすべてのレコードを出力します。

実行例:

    select Entries
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1,
    #         "The first post!",
    #         "Welcome! This is my first post!",
    #         5,
    #         "Hello"
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ],
    #       [
    #         4,
    #         "Good-bye Senna",
    #         "I migrated all Senna system!",
    #         3,
    #         "Senna"
    #       ],
    #       [
    #         5,
    #         "Good-bye Tritonn",
    #         "I also migrated all Tritonn system!",
    #         3,
    #         "Senna"
    #       ]
    #     ]
    #   ]
    # ]

どうしてこのコマンドがすべてのレコードを出力するのでしょうか？理由は2つです。1つ目の理由はこのコマンドが検索条件を何も指定していないからです。検索条件を指定しないとすべてのレコードがマッチします。2つ目の理由は全レコード数が5だからです。 `select` コマンドはデフォルトでは最大10レコードを出力します。この例では5レコードしかありません。これは10よりも少ないのですべてのレコードを出力します。

### 7.3.57.3.2. 検索条件

検索条件は `query` または `filter` で指定します。 `query` と `filter` を両方指定することもできます。この場合は `query` と `filter` の両方の条件にマッチしたレコードが出力されます。

#### 7.3.57.3.2.1. 検索条件: `query`

`query` はWebページの検索ボックス用に用意されています。例えば、google.co.jpにあるような検索ボックスです。 `query` の検索条件はスペース区切りでキーワードを指定します。例えば、 `検索 エンジン` は `検索` と `エンジン` という2つのキーワードを含むレコードを検索します。

通常は `query` 引数は全文検索条件を指定するために使います。全文検索条件以外も指定できますが、その用途には `filter` 引数の方が向いています。

`query` 引数で全文検索条件を指定する場合は、 `match_columns` 引数と一緒に使います。 `match_columns` はどのカラムまたはインデックスを使って `query` を検索するかを指定します。

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

実行例:

    select Entries --match_columns content --query fast
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `Entries` テーブルの中から `content` カラムの値に `fast` を含んでいるレコードを検索します。

`query` はクエリー構文という構文を使いますが、詳細はここでは説明しません。詳細は クエリー構文 を参照してください。

#### 7.3.57.3.2.2. 検索条件: `filter`

`filter` は複雑な検索条件を指定するために用意されています。ECMAScriptのような構文で `filter` に検索条件を指定します。

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

実行例:

    select Entries --filter 'content @ "fast" && _key == "Groonga"'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `Entries` テーブルの中の `content` カラムの値に `fast` という単語を含んでいて、かつ、 `_key` が `Groonga` のレコードを検索します。このコマンドの中には `@` と `&&` と `==` という3つの演算子があります。 `@` は全文検索用の演算子です。 `&&` と `==` はECMAScriptと同じ意味です。 `&&` が論理積用の演算子で `==` が等価演算子です。

`filter` にはもっと演算子や構文があります。例えば、 `(...)` を使った検索条件のグループ化などです。しかし、ここでは詳細は説明しません。詳細は スクリプト構文 を参照してください。

### 7.3.57.3.3. ページング

`offset` と `limit` を指定することで出力されるレコードの範囲を指定できます。以下は2番目のレコードだけを出力する例です。

実行例:

    select Entries --offset 1 --limit 1
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ]
    #     ]
    #   ]
    # ]

`offset` は0始まりです。 `--offset 1` は2番目以降のレコードを出力するという意味になります。

`limit` は出力レコード数の最大値を指定します。 `--limit 1` は多くても1レコードを出力するという意味になります。もし、1つもレコードがマッチしていなければ `select` コマンドはどのレコードも出力しません。

### 7.3.57.3.4. 全レコード数

`--limit 0` を使うとレコードの内容は取得せずに全レコード数だけを取得できます。

実行例:

    select Entries --limit 0
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ]
    #     ]
    #   ]
    # ]

`--limit 0` はマッチしたレコード数だけを取得したいときにも便利です。

### 7.3.57.3.5. ドリルダウン

1回の `select` で検索結果だけでなく、検索結果をグループ化した結果も一緒に取得できます。SQLでは2回以上 `SELECT` を使わなければいけない場合でも、Groongaの場合は1回の `select` で実現できます。

Groongaではこの機能を ドリルダウン と呼んでいます。他の検索エンジンでは ファセット検索 とも呼ばれています。

例えば、以下の状況を考えてみましょう。

`fast` という単語を含むエントリーを探します。

実行例:

    select Entries --filter 'content @ "fast"'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ]
    #     ]
    #   ]
    # ]

`--filter 'content @ "fast" && tag == "???"` というように、追加の検索条件として `tag` を使いたいとします。しかし、 `content @ "fast"` の結果を見るまでは適切なタグはわかりません。

もし、有効なタグそれぞれについてマッチするレコード数がわかれば、その中から適切なタグを選ぶことができます。このような用途のためにドリルダウンを使えます。

実行例:

    select Entries --filter 'content @ "fast"' --drilldown tag
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ]
    #     ],
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Groonga",
    #         2
    #       ]
    #     ]
    #   ]
    # ]

`--drilldown tag` は「有効なタグ」と「そのタグを持っているレコード数」のペアをリストにして返します。このリストからタグを選ぶと「検索したけどヒット数0」という状況を避けることができます。また、リストの中からレコード数が少ないタグを選べば「検索結果が多すぎる」という状況も避けることができます。

ドリルダウン結果を使うと次のようなUIを作ることができます。

> - 検索結果を絞り込むリンク。（ユーザーはキーボードから検索クエリーを入力する必要がなくなります。単にリンクをクリックすればよいからです。)

多くのECサイトではこのUIを使っています。Amazonのサイドメニューを見てください。

Groongaはグループ化したレコードの数を数えるだけでなく、グループ化したレコードのカラムの値の中から最大値・最小値を見つけたり、合計値を計算したりすることができます。詳細は ドリルダウン関連の引数 を参照してください。

### 7.3.57.3.6. 動的カラム

1回の `select` 実行中に0個以上のカラムを動的に作ることができます。この機能を使うと計算した値に対してドリルダウンしたりウィンドウ関数を使ったりできます。

以下は計算した値に対してドリルダウンするために動的カラムを使う例です。この例では `n_likes_class` という名前のカラムを新しく作っています。 `n_likes_class` カラムには `Entry.n_likes` の値を分類した値を入れます。この例では `Entry.n_likes` カラムの値を `10` 刻みで分類し、一番小さい数値をその分類の代表値とします。もし、 `Entry.n_likes` の値が `3` や `5` のように `0` から `9` の間の値なら、 `n_likes_class` の値（分類した値）は `0` になります。もし、 `Entry.n_likes` の値が `10` や `15` のように `10` から `19` の間の値なら、 `n_likes_class` の値（分類した値）は `10` になります。

このような分類をするために number_classify 関数を使えます。 number_classify 関数を使うためには plugin_register コマンドで `functions/number` プラグインを登録する必要があります。

この例では `n_likes_class` の値でドリルダウンしています。このドリルダウン結果があるとデータの傾向がわかりやすくなるでしょう。

実行例:

    plugin_register functions/number
    # [[0,1337566253.89858,0.000355720520019531],true]
    select \
      --table Entries \
      --columns[n_likes_class].stage initial \
      --columns[n_likes_class].type UInt32 \
      --columns[n_likes_class].value 'number_classify(n_likes, 10)' \
      --drilldown n_likes_class \
      --drilldown_sort_keys _nsubrecs \
      --output_columns n_likes,n_likes_class
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "n_likes_class",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         5,
    #         0
    #       ],
    #       [
    #         10,
    #         10
    #       ],
    #       [
    #         15,
    #         10
    #       ],
    #       [
    #         3,
    #         0
    #       ],
    #       [
    #         3,
    #         0
    #       ]
    #     ],
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_key",
    #           "UInt32"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         10,
    #         2
    #       ],
    #       [
    #         0,
    #         3
    #       ]
    #     ]
    #   ]
    # ]

詳細は 動的カラム関連の引数 を見てください。

### 7.3.57.3.7. ウィンドウ関数

グループ化したレコードの値を使って各レコードの値を計算することができます。たとえば、グループ毎に合計を計算して、合計値をすべてのレコードに格納できます。ドリルダウンもグループ毎に合計を計算できますが、すべてのレコードに合計を格納するのではなく、各グループ合計を格納する点が違います。

以下はウィンドウ関数を使った結果の例です。すべてのレコードが合計値を持っています。

グループ番号 | 合計対象の値 | 合計結果
--- | --- | ---
1 | 5 | 5
2 | 10 | 25
2 | 15 | 25
3 | 3 | 8
3 | 5 | 8

以下はドリルダウンを使った結果の例です。各グループが合計値を持っています。

グループ番号 | 合計対象の値 | 合計結果
--- | --- | ---
1 | 5 | 5
2 | 10, 15 | 25
3 | 3, 5 | 8

ウィンドウ関数はデータ解析に有用です。

以下は `Entries.tag` 毎に `Entries.n_likes` の合計を計算する例です。

実行例:

    plugin_register functions/number
    # [[0,1337566253.89858,0.000355720520019531],true]
    select \
      --table Entries \
      --columns[n_likes_sum_per_tag].stage initial \
      --columns[n_likes_sum_per_tag].type UInt32 \
      --columns[n_likes_sum_per_tag].value 'window_sum(n_likes)' \
      --columns[n_likes_sum_per_tag].window.group_keys tag \
      --output_columns tag,n_likes,n_likes_sum_per_tag
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "tag",
    #           "ShortText"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "n_likes_sum_per_tag",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         "Hello",
    #         5,
    #         5
    #       ],
    #       [
    #         "Groonga",
    #         10,
    #         25
    #       ],
    #       [
    #         "Groonga",
    #         15,
    #         25
    #       ],
    #       [
    #         "Senna",
    #         3,
    #         6
    #       ],
    #       [
    #         "Senna",
    #         3,
    #         6
    #       ]
    #     ]
    #   ]
    # ]

詳細は ウィンドウ関数関連の引数 を見てください。

### 7.3.57.3.8. タイプミスの許容

タイプミスとして何文字許容するかを指定することでタイプミスを許容した検索を実現できます。指定されたクエリーでどのレコードにもマッチしない場合、Groongaは自動でタイプミスを修正したクエリーで再検索します。

デフォルトではタイプミスを許容する文字数は0です。つまり、デフォルトではタイプミスを許容した検索は無効になっています。

fuzzy_max_distance_ratio または fuzzy_max_distance を指定することでタイプミスを許容した検索を実行にできます。多くの場合、 `--fuzzy_max_distance_ratio 0.34` が適切なパラメーターになります。

fuzzy_max_distance_ratio は入力された各単語の文字数に応じて何文字のタイプミスを許容するかを指定します。

以下は `--fuzzy_max_distance_ratio 0.34` だとタイプミスとして何文字許容するかを示した表です。

単語の文字数 | 許容するタイプミスの文字数
--- | ---
1 | 0 (`floor(1 * 0.34) = floor(0.34) = 0`)
2 | 0 (`floor(2 * 0.34) = floor(0.68) = 0`)
3 | 1 (`floor(3 * 0.34) = floor(1.02) = 1`)
4 | 1 (`floor(4 * 0.34) = floor(1.36) = 1`)
5 | 1 (`floor(5 * 0.34) = floor(1.7) = 1`)
6 | 2 (`floor(6 * 0.34) = floor(2.04) = 2`)

まとめると、Groongaは短い単語（0文字から2文字の単語）ではタイプミスを許容せず、少し長い単語（3文字から5文字の単語）では1文字のタイプミスを許容し、長い単語（6文字以上の単語）では2文字以上のタイプミスを許容します。

以下は `Moronga` （2文字のタイプミス）で `Groonga` を検索する例です。

実行例:

    select \
      --table Entries \
      --fuzzy_max_distance_ratio 0.34 \
      --match_columns content \
      --query Moronga \
      --output_columns content,_score
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "I started to use Groonga. It's very fast!",
    #         1
    #       ],
    #       [
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         2
    #       ]
    #     ]
    #   ]
    # ]

fuzzy_max_distance を使ってタイプミスを許容する文字数を固定値で指定することもできます。たとえば、 `--fuzzy_max_distance 2` と指定するとすべての単語でタイプミスとして2文字許容します。しかし、多くのケースでは `--fuzzy_max_distance_ratio` の方が適切です。

タイプミスを許容した検索をするためには正しい単語が必要です。Groongaは語彙表の中の単語を正しい単語として使います。このケースでは `Terms` が語彙表です。語彙表の中の単語はトークナイザーが生成します。データが英語のようなアルファベットベースの言語の場合、 TokenNgram を使えます。なぜなら、 TokenNgram はアルファベットベースの言語ではテクストを（ほぼ）単語にトークナイズするからです。データが日本語のような非アルファベットベースの言語の場合、 TokenNgram は使えません。なぜなら TokenNgram は非アルファベットベースの言語ではテキストをN文字毎にトークナイズするからです。非アルファベットベースの言語では形態素解析器ベースのトークナイザーを使う必要があります。たとえば、日本語には TokenMecab を使えます。（適切な辞書を用意すれば日本語以外でも TokenMecab を使えます。）

以下は日本語テキストでタイプミスを許容した検索をする例です。 `JapaneseTerms` の `--default_tokenizer TokenMecab` が重要です。この例では `JapaneseTerms` が語彙表になります。

    .. groonga-command
    .. include:: ../../example/reference/commands/select/usage_typo_tolerance_japanese.log
    .. table_create JapaneseEntries TABLE_NO_KEY
    .. column_create JapaneseEntries content COLUMN_SCALAR Text
    .. table_create JapaneseTerms TABLE_PAT_KEY ShortText \
    ..   --default_tokenizer TokenMecab \
    ..   --normalizer NormalizerNFKC150
    .. column_create JapaneseTerms japanese_entries_content \
    ..   COLUMN_INDEX|WITH_POSITION JapaneseEntries content
    .. load --table JapaneseEntries
    .. [
    .. {"content": "ようこそ！これが最初の投稿です！"},
    .. {"content": "Groongaを使い始めました。とても速いですね！"},
    .. {"content": "Mroongaも使い始めました。これもとても速いですね！本当に速い！"},
    .. {"content": "Sennaのシステムをすべて移行しました！"},
    .. {"content": "Tritonnのシステムもすべて移行しました！"}
    .. ]
    .. select \
    ..   --table JapaneseEntries \
    ..   --fuzzy_max_distance_ratio 0.34 \
    ..   --match_columns content \
    ..   --query ともて \
    ..   --output_columns content,_score

詳細は あいまいクエリー関連の引数 を見てください。

## 7.3.57.4. 引数

このセクションではすべての引数について説明します。引数はカテゴリわけしています。

### 7.3.57.4.1. 必須引数

`table` だけが必須の引数です。

#### 7.3.57.4.1.1. `table`

検索対象のテーブルを指定します。 `table` は必ず指定しなければいけません。

存在しないテーブルを指定するとエラーが返ります。

実行例:

    select Nonexistent
    # [
    #   [
    #     -22,
    #     1337566253.89858,
    #     0.000355720520019531,
    #     "[select][table] invalid name: <Nonexistent>",
    #     [
    #       [
    #         "execute",
    #         "lib/proc/proc_select.cpp",
    #         5002
    #       ]
    #     ]
    #   ]
    # ]

### 7.3.57.4.2. 検索関係の引数

検索関係の引数がいくつかあります。一般的には、検索ボックスを実装するために `match_columns` と `query` 引数を使い、複雑な検索機能を実装するために `filter` 引数を使います。

`query` と `filter` を指定した場合は、 `query` と `filter` にマッチしたレコードが選択されます。 `query` と `filter` のどちらも指定しなかった場合はすべてのレコードが選択されます。

#### 7.3.57.4.2.1. `match_columns`

`query` 引数の値で全文検索をするときに使うデフォルトの検索対象カラムを指定します。全文検索対象のカラムは `query` 引数でも指定できます。検索対象カラムを `match_columns` で指定する場合と `query` で指定する場合の違いは重みとスコアー関数を指定できるかどうかです。 `match_columns` では指定できますが、 `query` では指定できません。

重みは検索対象カラムの相対的な重要度です。重みの大きい検索対象カラムでマッチした場合は小さい検索対象カラムでマッチした場合よりも多くのヒットスコアがつきます。デフォルトの重みは1です。

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

実行例:

    select Entries --match_columns content --query fast --output_columns '_key, _score'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Groonga",
    #         1
    #       ],
    #       [
    #         "Mroonga",
    #         2
    #       ]
    #     ]
    #   ]
    # ]

`--match_columns content` はデフォルトの全文検索対象カラムに `content` カラムを使用し、その重みは1、という意味になります。 `--output_columns '_key, _score'` はこの `select` コマンドがマッチしたレコードの `_key` の値と `_score` の値を出力する、ということを指定しています。

`_score` の値に注目してください。 `_score` の値は `query` 引数の値に何個マッチしたかになっています。この例では、 `query` 引数の値は `fast` です。 `_score` の値が1ということは `content` カラムの中に `fast` が1つだけあるということです。 `_score` の値が2ということは `content` カラムの中に `fast` が2つあるということです。

重みを指定するためには `column * weight` という構文を使います。以下は重みの使用例です。

実行例:

    select Entries --match_columns 'content * 2' --query fast --output_columns '_key, _score'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Groonga",
    #         2
    #       ],
    #       [
    #         "Mroonga",
    #         4
    #       ]
    #     ]
    #   ]
    # ]

`--match_columns 'content * 2'` はデフォルトの全文検索用カラムとして `content` カラムを使い、その重みは2という意味です。

`_score` の値に注目してください。 `_score` の値が2倍になっています。これは重みを2にしたからです。

デフォルトの全文検索対象カラムとして複数のカラムを指定することができます。複数のカラムを指定した場合はすべてのカラムに対して全文検索が行われ、ヒットスコアが積算されます。つまり、 `query` 引数の値がどれか1つでも全文検索対象カラムにマッチしたら、そのレコードはマッチしたものとして扱われます。

複数のカラムを指定するには `column1 * weight1 || column2 * weight2 || ...` という構文を使います。 `* weight` は省略することができます。省略した場合は重みが1になります。以下は複数カラムの使用例です。

実行例:

    select Entries --match_columns '_key * 10 || content' --query groonga --output_columns '_key, _score'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Groonga",
    #         11
    #       ]
    #     ]
    #   ]
    # ]

`--match_columns '_key * 10 || content'` はデフォルト検索対象カラムが `_key` カラムと `content` カラムで、 `_key` カラムの重みは10、 `content` カラムの重みは1という意味です。この重み付けは `_key` カラムの値は `content` カラムの値よりも重要だという意味になります。この例では、ブログエントリのタイトルはブログエントリの内容よりも重要だということです。

スコアー関数を指定することもできます。詳細は スコアラー を参照してください。

スコアー関数と scorer パラメーターは関係ないので注意してください。

`--match_columns` にはインデックスカラムを指定することもできます。その場合、どのインデックスが使われ、どのデータカラムを検索するのかを明示的に制御することができます。

もし、データカラムが `--match_columns` へと指定されていたら、Groongaは自動的に関連するインデックスカラムを探します。しかし、どのインデックスカラムが実際に選択されるかは仕様として定義されていません。つまり、もし複数のインデックスカラムが1つのデータカラムに対して作成された場合、事前にどのインデックスカラムが選択されるかはわからないということです。(多くの場合は最後に作成されたインデックスカラムが選択されますが、これはドキュメント化されていない振る舞いです。)

以下はインデックスカラムをどのように指定するかの例です。

- 1つのデータカラム用のインデックスカラム

- 複数のデータカラム用のインデックスカラム

1つのデータカラム用のインデックスカラムを使う場合、データカラムに対応したインデックスカラムを指定します。つまり、 `TERMS_TABLE.INDEX_COLUMN` を指定するということです。一方で複数のデータカラムに対するインデックスカラムを使う場合、デフォルトではすべてのデータカラムが検索されます。もし特定のインデックスを使い、特定のデータカラムのみを検索したいなら、インデックスカラム名にデータカラム名を付与します。例えば、 `TERMS_TABLE.INDEX_COLUMN.DATA_COLUMN` といった具合にです。詳しい例は インデックス名を指定した全文検索 を参照してください。

#### 7.3.57.4.2.2. `query`

クエリーテキストを指定します。通常、全文検索をするために `match_columns` 引数と一緒に使います。 `query` 引数はWebページにある全文検索フォームで使いやすいように設計されています。クエリーテキストは クエリー構文 という書式を使います。この書式はGoogleの検索フォームのように一般的な検索フォームと似ています。例えば、 `word1 word2` は `word1` と `word2` を含んでいるレコードを検索するという意味になります。 `word1 OR word2` は `word1` または `word2` を含んでいるレコードを検索するという意味になります。

以下は論理積を使った検索の簡単な例です。

実行例:

    select Entries --match_columns content --query "fast groonga"
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `Entries` テーブルの中から `content` カラムの値に `fast` と `groonga` の2つの単語を含んでいるレコードを検索します。

以下は論理和を使った検索の簡単な例です。

実行例:

    select Entries --match_columns content --query "groonga OR mroonga"
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `Entries` テーブルの中から `content` カラムの値に `fast` または `groonga` のどちらかの単語を含んでいるレコードを検索します。

他の構文は クエリー構文 を参照してください。

`query` では全文検索だけではなく他の条件も使えます。例えば、 `column:value` は `column` の値が `value` と等しいという意味です。 `column:<value` は `column` の値が `value` より小さいという意味です。

以下は等価演算子を使った検索の簡単な例です。

実行例:

    select Entries --query _key:Groonga
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `Entries` テーブルの中から `_key` カラムの値が `Groonga` であるレコードを検索します。

以下は比較演算子を使った検索の簡単な例です。

実行例:

    select Entries --query n_likes:<11
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         4
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1,
    #         "The first post!",
    #         "Welcome! This is my first post!",
    #         5,
    #         "Hello"
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ],
    #       [
    #         4,
    #         "Good-bye Senna",
    #         "I migrated all Senna system!",
    #         3,
    #         "Senna"
    #       ],
    #       [
    #         5,
    #         "Good-bye Tritonn",
    #         "I also migrated all Tritonn system!",
    #         3,
    #         "Senna"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `Entries` テーブルの中から `n_likes` カラムの値が `11` より小さいレコードを検索します。

他の演算子は クエリー構文 を参照してください。

#### 7.3.57.4.2.3. `filter`

フィルターテキストを指定します。通常、 `filter` は複雑な条件を指定するために使います。 `filter` は `query` 引数と一緒に使うこともできます。 `filter` と `query` を両方指定した場合はそれらを論理積で組み合わせます。つまり、マッチするレコードは `filter` にも `query` にもマッチしなければいけないということです。

`filter` 引数は複雑な条件用に設計されています。フィルターテキストは スクリプト構文 書式で指定します。この書式はECMAScriptに似ています。例えば、 `column == "value"` は `column` カラムの値が `"value"` と等しいという意味です。 `column < value` は `column` カラムの値が `value` よりも小さいという意味です。

以下は等価演算子を使った検索の簡単な例です。

実行例:

    select Entries --filter '_key == "Groonga"'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `Entries` テーブルの中から `_key` カラムの値が `Groonga` であるレコードを検索します。

以下は比較演算子を使った検索の簡単な例です。

実行例:

    select Entries --filter 'n_likes < 11'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         4
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1,
    #         "The first post!",
    #         "Welcome! This is my first post!",
    #         5,
    #         "Hello"
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ],
    #       [
    #         4,
    #         "Good-bye Senna",
    #         "I migrated all Senna system!",
    #         3,
    #         "Senna"
    #       ],
    #       [
    #         5,
    #         "Good-bye Tritonn",
    #         "I also migrated all Tritonn system!",
    #         3,
    #         "Senna"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `Entries` テーブルの中から `n_likes` カラムの値が `11` より小さいレコードを検索します。

他の演算子は スクリプト構文 を参照してください。

#### 7.3.57.4.2.4. `load_table`

Added in version 9.0.1.

`--load_table` 、 `--load_columns` 、 `--load_values` を使って、`select` の結果を指定したテーブルに格納できます。 `--load_table` は、`select` の結果を格納するテーブルの名前を指定します。

既に存在するテーブルを指定する必要があります。

この引数は、 load_columns と load_values と一緒に使う必要があります。

以下は、 `--load_table` で指定したLogsテーブルに `select` の結果である `_id` と `timestamp` を格納する例です。

実行例:

    table_create Logs_20150203 TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Logs_20150203 timestamp COLUMN_SCALAR Time
    # [[0,1337566253.89858,0.000355720520019531],true]
    table_create Logs TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Logs original_id COLUMN_SCALAR UInt32
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Logs timestamp_text COLUMN_SCALAR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table Logs_20150203
    [
    {
      "_key": "2015-02-03:1",
      "timestamp": "2015-02-03 10:49:00"
    },
    {
      "_key": "2015-02-03:2",
      "timestamp": "2015-02-03 12:49:00"
    }
    ]
    # [[0,1337566253.89858,0.000355720520019531],2]
    select \
      --table Logs_20150203 \
      --load_table Logs \
      --load_columns "_key, original_id, timestamp_text" \
      --load_values "_key, _id, timestamp"
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "timestamp",
    #           "Time"
    #         ]
    #       ],
    #       [
    #         1,
    #         "2015-02-03:1",
    #         1422928140.0
    #       ],
    #       [
    #         2,
    #         "2015-02-03:2",
    #         1422935340.0
    #       ]
    #     ]
    #   ]
    # ]
    select --table Logs
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "original_id",
    #           "UInt32"
    #         ],
    #         [
    #           "timestamp_text",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1,
    #         "2015-02-03:1",
    #         1,
    #         "1422928140000000"
    #       ],
    #       [
    #         2,
    #         "2015-02-03:2",
    #         2,
    #         "1422935340000000"
    #       ]
    #     ]
    #   ]
    # ]

#### 7.3.57.4.2.5. `load_columns`

Added in version 9.0.1.

`--load_table` で指定したテーブルのカラムを指定します。load_values で指定したカラムの値をこの引数で指定したカラムに格納します。既に存在するカラムを指定する必要があります。

この引数は、 load_table と load_values と一緒に使う必要があります。

この引数の使い方は、 `--load_table` の例を参照してください。

#### 7.3.57.4.2.6. `load_values`

Added in version 9.0.1.

`select` の結果のカラムを指定します。 load_columns で指定したカラムに値を格納するカラムを指定します。既に存在するカラムを指定する必要があります。

この引数は、 load_table と load_columns と一緒に使う必要があります。

この引数の使い方は、 `--load_table` の例を参照してください。

### 7.3.57.4.3. 高度な検索のための引数

#### 7.3.57.4.3.1. `match_escalation_threshold`

Added in version 8.0.1.

検索方法をエスカレーションするかどうかを決定するための閾値を指定します。この閾値はマッチしたレコード数との比較に使われます。マッチしたレコード数がこの閾値以下の場合は検索方法をエスカレーションします。検索方法のエスカレーションについては 検索 を参照してください。

デフォルトの閾値は0です。これは1つもレコードがマッチしなかったときだけ検索方法をエスカレーションするということです。

デフォルトの閾値は以下の方法でカスタマイズできます。

> - configureの `--with-match-escalation-threshold` オプション

> - groongaコマンドの `--match-escalation-threshold` オプション

> - 設定ファイルの `match-escalation-threshold` 設定項目

以下は簡単な `match_escalation_threshold` の使用例です。最初の `select` は `match_escalation_threshold` 引数がありません。2番目の `select` は `match_escalation_threshold` 引数があります。

実行例:

    select Entries --match_columns content --query groo
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ]
    #     ]
    #   ]
    # ]
    select Entries --match_columns content --query groo --match_escalation_threshold -1
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         0
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ]
    #     ]
    #   ]
    # ]

最初の `select` コマンドは `Entries` テーブルから `content` カラムの値に `groo` という単語を含むレコードを検索します。しかし、この検索ではどのレコードにもマッチしません。これは、 `TokenBigram` トークナイザーは `groonga` を `gr|ro|oo|on|ng|ga` ではなく `groonga` にトークナイズするからです。（ `TokenBigramSplitSymbolAlpha` は `groonga` を `gr|ro|oo|on|ng|ga` にトークナイズします。詳細は トークナイザー を見てください。）つまり、 `groonga` はインデックスに登録されていますが、 `groo` はインデックスに登録されていないということです。インデックスに登録されていないので完全一致検索では `groo` はどのレコードにもマッチしません。このケースでは検索方法のエスカレーションが行われています。なぜならばマッチしたレコード数（0）が `match_escalation_threshold` （0）の値と等しいからです。非分かち書き検索では `groo` で1つのレコードがマッチします。

2番目の `select` コマンドも `Entries` テーブルから `content` カラムの値に `groo` という単語を含むレコードを検索します。そして、この `select` コマンドもマッチしません。この場合、マッチしたレコード数（0）が `match_escalation_threshold` （-1）より大きいので、検索方法をエスカレーションしません。そして、1つもレコードがマッチしません。

#### 7.3.57.4.3.2. `match_escalation`

検索方法のエスカレーションをどのように使うかを指定します。検索方法のエスカレーションについては match_escalation と 検索 を参照してください。

指定可能な値は以下の通りです。

値 | 説明
--- | ---
`auto` | Groongaは match_escalation_threshold を使って検索方法をエスカレーションするかどうかを決めます。 これがデフォルトです。
`yes` | Groongaは常に検索方法のエスカレーションします。
`no` | Groongaは絶対に検索方法をエスカレーションしません。

`--match_escalation yes` は `--match_escalation_threshold 9999...999` よりも強力です。 `--match_escalation yes` を指定した場合は `--filter 'true && column @ "query"` を実行するときに検索方法をエスカレーションします。 `--match_escalation_threshold 9999...999` を指定した場合は `--filter 'true && column @ "query"` を実行するときに検索方法をエスカレーションしません。

以下は簡単な `match_escalation` の使用例です。最初の `select` は `match_escalation` 引数がありません。2番目の `select` は `match_escalation` 引数があります。

実行例:

    select Entries --filter 'true && content @ "groo"'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         0
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ]
    #     ]
    #   ]
    # ]
    select Entries --filter 'true && content @ "groo"' --match_escalation yes
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ]
    #     ]
    #   ]
    # ]

最初の `select` コマンドは `Entries` テーブルから `content` カラムの値に `groo` という単語を含むレコードを検索します。しかし、この検索ではどのレ"コードにもマッチしません。これは、 `TokenBigram` トークナイザーは `groonga` を `gr|ro|oo|on|ng|ga` ではなく `groonga` にトークナイズするからです。

2番目の `select` コマンドも `Entries` テーブルから `content` カラムの値に `groo` という単語を含むレコードを検索します。しかし、この `select` コマンドは検索方法をエスカレーションします。そのため、この `select` コマンドはマッチします。

#### 7.3.57.4.3.3. `query_expansion`

バージョン 3.0.2 で非推奨: 代わりに query_expander を使ってください。

#### 7.3.57.4.3.4. `query_flags`

`query` パラメーターの構文をカスタマイズします。デフォルトでは `query` パラメーターでカラムの値を更新することはできません。しかし、 `query_flags` に `ALLOW_COLUMN|ALLOW_UPDATE` を指定することで `query` でカラムの値を更新することができます。

指定可能な値は以下の通りです。

- `ALLOW_PRAGMA`

- `ALLOW_COLUMN`

- `ALLOW_UPDATE`

- `ALLOW_LEADING_NOT`

- `QUERY_NO_SYNTAX_ERROR`

- `NONE`

`ALLOW_PRAGMA` を指定すると `query` の先頭でプラグマを指定することができます。この機能はまだ実装されていません。

`ALLOW_COLUMN` を指定すると `match_columns` で指定していないカラムでも検索できるように成ります。カラムを指定するには `COLUMN:...` というような構文を使います。

`ALLOW_UPDATE` を指定すると `COLUMN:=NEW_VALUE` という構文を使って `query` でカラムの値を更新できます。カラム更新用の構文ではカラムを指定する必要があるため、 `ALLOW_COLUMN` も一緒に指定する必要があります。

`ALLOW_LEADING_NOT` を指定すると `-WORD` という構文を使って最初の条件として否定条件を指定できます。このクエリーは `WORD` にマッチしないレコードを検索します。最初の条件に否定条件を使ったクエリーは多くの場合重いクエリーになります。これは多くのレコードにマッチするからです。そのため、このフラグはデフォルトでは無効になっています。もし、このフラグを使う場合は重いクエリーとなるということを十分気をつけてください。

`QUERY_NO_SYNTAX_ERROR` を指定すると、クエリーは構文エラーにならなくなります。このフラグは、アプリケーションがユーザーの入力を直接使う時や、構文エラーをユーザーに見せたくない時、ログに記録したくない時に便利です。このフラグは、デフォルトで無効になっています。

`NONE` は単に無視されます。フラグを指定しないときに `NONE` を使えます。

これらのフラグは `ALLOW_COLUMN|ALLOW_UPDATE` のように `|` で区切って同時に指定することができます。

デフォルト値は `ALLOW_PRAGMA|ALLOW_COLUMN` です。

以下は `ALLOW_COLUMN` の使用例です。

実行例:

    select Entries --query content:@mroonga --query_flags ALLOW_COLUMN
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `Entries` テーブルの中から `content` カラムの値に `mroonga` を含んでいるレコードを検索します。

以下は `ALLOW_UPDATE` の使用例です。

実行例:

    table_create Users TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Users age COLUMN_SCALAR UInt32
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table Users
    [
    {"_key": "alice", "age": 18},
    {"_key": "bob",   "age": 20}
    ]
    # [[0,1337566253.89858,0.000355720520019531],2]
    select Users --query age:=19 --query_flags ALLOW_COLUMN|ALLOW_UPDATE
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "age",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         1,
    #         "alice",
    #         19
    #       ],
    #       [
    #         2,
    #         "bob",
    #         19
    #       ]
    #     ]
    #   ]
    # ]
    select Users
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "age",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         1,
    #         "alice",
    #         19
    #       ],
    #       [
    #         2,
    #         "bob",
    #         19
    #       ]
    #     ]
    #   ]
    # ]

最初の `select` コマンドは全てのレコードの `age` カラムの値を `19` にします。二番目の `select` コマンドは `age` カラムの値を出力します。

以下は `ALLOW_LEADING_NOT` の使用例です。

実行例:

    select Entries --match_columns content --query -mroonga --query_flags ALLOW_LEADING_NOT
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         4
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1,
    #         "The first post!",
    #         "Welcome! This is my first post!",
    #         5,
    #         "Hello"
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ],
    #       [
    #         4,
    #         "Good-bye Senna",
    #         "I migrated all Senna system!",
    #         3,
    #         "Senna"
    #       ],
    #       [
    #         5,
    #         "Good-bye Tritonn",
    #         "I also migrated all Tritonn system!",
    #         3,
    #         "Senna"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `Entries` テーブルの中から `content` カラムの値に `mroonga` を含んでいないレコードを検索します。

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

実行例:

    table_create --name Magazine --flags TABLE_HASH_KEY --key_type ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create --table Magazine --name title --type ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table Magazine
    [
    {"_key":"http://test.jp/magazine/webplus","title":"WEB+"},
    {"_key":"http://test.jp/magazine/database","title":"DataBase"},
    ]
    # [[0,1337566253.89858,0.000355720520019531],2]

以下は `QUERY_NO_SYNTAX_ERROR` の使用例です。

実行例:

    select Magazine --match_columns title --query 'WEB +'  --query_flags ALLOW_PRAGMA|ALLOW_COLUMN|QUERY_NO_SYNTAX_ERROR
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "title",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1,
    #         "http://test.jp/magazine/webplus",
    #         "WEB+"
    #       ]
    #     ]
    #   ]
    # ]

このフラグを指定しない場合は、このクエリーは次のように構文エラーになります。

実行例:

    select Magazine --match_columns title --query 'WEB +'  --query_flags ALLOW_PRAGMA|ALLOW_COLUMN
    # [
    #   [
    #     -63,
    #     1337566253.89858,
    #     0.000355720520019531,
    #     "Syntax error: <WEB +||>",
    #     [
    #       [
    #         "yy_syntax_error",
    #         "lib/grn_ecmascript.lemon",
    #         168
    #       ]
    #     ]
    #   ]
    # ]

以下は `NONE` の使用例です。

実行例:

    select Entries --match_columns content --query 'mroonga OR _key:Groonga' --query_flags NONE
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `Entries` テーブルの中から `content` カラムの値に `mroonga` または `_key:Groonga` のどちらかの単語を含んでいるレコードを検索します。 `_key:Groonga` が `_key` カラムの値が `Groonga` という条件にはならないことに注意してください。これは `ALLOW_COLUMN` フラグが指定されていないからです。

クエリー構文 も見てください。

#### 7.3.57.4.3.5. `query_expander`

クエリー展開用の引数です。クエリー展開はクエリー中の特定の単語を別の単語に置換します。通常は類義語検索に使います。

`query` 引数の値を置換するために使うカラムを指定します。この引数の値の書式は「 `${TABLE}.${COLUMN}` 」です。例えば、 「 `Terms.synonym` 」は `Terms` テーブルの `synonym` カラムを指定しています。

クエリー展開用のテーブルを「置換テーブル」と呼びます。置換テーブルのキーは `ShortText` にしてください。そのため、配列テーブル（ `TABLE_NO_KEY` ）は置換テーブルに使うことはできません。なぜなら、配列テーブルにはキーがないからです。

クエリー展開用のカラムを「置換カラム」と呼びます。置換カラムの値の型は `ShortText` にしてください。カラムの種類はベクター（ `COLUMN_VECTOR` ）にしてください。

クエリー展開はクエリーの中にある置換テーブルのキーを置換カラムの値で置換します。 `query` の中にある単語が置換テーブルのキーだったら、キーに対応する置換カラムの値でその単語を置換します。置換は再帰的に実行しません。これは、置換されたクエリー内に置換対象の単語があっても置換されないということです。

以下は `query_expander` の簡単な使用例を示すためのサンプル置換テーブルです。

実行例:

    table_create Thesaurus TABLE_PAT_KEY ShortText --normalizer NormalizerAuto
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Thesaurus synonym COLUMN_VECTOR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table Thesaurus
    [
    {"_key": "mroonga", "synonym": ["mroonga", "tritonn", "groonga mysql"]},
    {"_key": "groonga", "synonym": ["groonga", "senna"]}
    ]
    # [[0,1337566253.89858,0.000355720520019531],2]

`Thesaurus` 置換テーブルは2つの類義語があります。 `"mroonga"` と `"groonga"` です。ユーザが `"mroonga"` で検索すると、Groongaは `"((mroonga) OR (tritonn) OR (groonga mysql))"` で検索します。ユーザーが `"groonga"` で検索すると、Groongaは `"((groonga) OR (senna))"` で検索します。

通常、置換テーブルにはノーマライザーを指定したほうがよいです。たとえば、ノーマライザーを指定すると、置換対象の単語に対して大文字小文字区別せずにマッチするようになります。利用可能なノーマライザーは ノーマライザー を参照してください。

これらの類義語の値の中に `"mroonga"` や `"groonga"` といったキーの値も含まれていることに注意してください。このように類義語にキーの値も含めることを推奨します。もしキーの値を含めないと、置換した値には元の置換対象の値が含まれません。通常、元の値が含まれていた方がよい検索結果になります。もし、検索してほしくない単語がある場合は、元の単語を含めないでください。例えば、空のベクター値を指定することで「ストップワード」機能を実現することもできます。

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

実行例:

    select Entries --match_columns content --query "mroonga"
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ]
    #     ]
    #   ]
    # ]
    select Entries --match_columns content --query "mroonga" --query_expander Thesaurus.synonym
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ],
    #       [
    #         5,
    #         "Good-bye Tritonn",
    #         "I also migrated all Tritonn system!",
    #         3,
    #         "Senna"
    #       ]
    #     ]
    #   ]
    # ]
    select Entries --match_columns content --query "((mroonga) OR (tritonn) OR (groonga mysql))"
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ],
    #       [
    #         5,
    #         "Good-bye Tritonn",
    #         "I also migrated all Tritonn system!",
    #         3,
    #         "Senna"
    #       ]
    #     ]
    #   ]
    # ]

最初の `select` コマンドはクエリー展開を使いません。そのため、 `"tritonn"` という単語を含んでいるレコードは見つかりません。2番目の `select` コマンドはクエリー展開を使っています。そのため、 `"tritonn"` という単語を含んでいるレコードが見つかります。3番目の `select` コマンドはクエリー展開を使っていませんが、2番目の `select` コマンドと同じ結果になります。これは、3番目の `select` コマンドは展開後のクエリーを使っているからです。

それぞれの置換する値は `(...)` や `OR` といった クエリー構文 を使えます。これらの構文を使うことにより複雑な置換をすることができます。

以下はクエリー構文を使った複雑な置換の使用例です。

実行例:

    load --table Thesaurus
    [
    {"_key": "popular", "synonym": ["popular", "n_likes:>=10"]}
    ]
    # [[0,1337566253.89858,0.000355720520019531],1]
    select Entries --match_columns content --query "popular" --query_expander Thesaurus.synonym
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ]
    #     ]
    #   ]
    # ]

この `load` コマンドは新しく `"popular"` という類義語を登録しています。これは `((popular) OR (n_likes:>=10))` に置換されます。置換されたクエリーは、「popular」というのは「popular」という単語を含んでいるか10以上の「いいね！」数を持つエントリという意味になります。

この `select` コマンドは `Entries` テーブルの中から `n_likes` カラムの値が `10` 以上のレコードを出力します。

#### 7.3.57.4.3.6. `n_workers`

Added in version 12.0.5.

注釈

この機能は実験的な機能です。現状、この機能はまだ安定していません。

コマンドバージョン 3 以降を指定する必要があります。

Apache Arrow が有効である必要があります。

パッケージの提供元によりApache Arrowが有効かどうかは異なります。

Apache Arrow が有効かどうかは、 status コマンドの結果で `apache_arrow` が `true` かどうかで確認することができます。

Apache Arrow が無効な場合、 インストール の手順にしたがい、Apache Arrowを有効にしてソースコードからビルドするか、パッケージの提供元にApache Arrowを有効にするよう依頼をしてください。

このパラメータの値に `-1` または `2` 以上を指定すると、 drilldown と drilldowns および スライス を並列で実行します。

デフォルトでは各 `drilldown` 、 `drilldowns` 、 `slices` を直列に実行します。つまり、1つの処理が終わったら次の処理を実行します。そのため、 `drilldown` 、 `drilldowns` 、 `slices` がたくさんある場合は、クエリーの実行時間が長くなる傾向にあります。

`n_workers` を使うと依存関係のない複数の `drilldown` 、 `drilldowns` 、 `slices` を並列に実行できます。そのため、従来はすべての処理の総和分の実行時間がかかっていたところが並列に実行する分短縮できます。この並列実行は、 `select` コマンドごとに行います。

依存関係がないとは、 `dorilldowns.table` を使用して他のドリルダウンやスライスの結果を参照していないことです。

依存関係がある場合、つまり、 `drilldowns.table` を使用している場合、依存するドリルダウンやスライスの処理の終了を待ちます。したがって依存関係がある場合は並列度が下がります。

並列に実行するということは、複数のCPUを同時に使用するということです。CPUのリソースに空きがないのに並列に実行しようとするとかえって遅くなることがあります。対象のCPUが実行している別処理が終わるのを待たないといけないからです。

CPUのリソースに空きがあるかどうか、どのくらいの `n_workers` を指定すべきかの判断基準はどのようなシステム構成かに依存します。

たとえば、CPUが6個のシステムで Groonga HTTPサーバー を使うケースを考えます。

Groonga HTTPサーバー は各リクエストごとに1スレッド（= 1CPU）を割り当てて処理します。

平均同時接続数が6のとき、CPUを既に6つ使用しているのでCPUのリソースに空きはありません。各リクエストを処理するためにすべてのCPUが使われているからです。

平均同時接続数が2のとき、リクエストを処理するためにはCPUを2つしか使用していないので、4つ空きがあります。`n_workers` に `2` を指定すると、 `select` コマンドはリクエストを処理するためのスレッドを含んで最大で3つのCPUを使用します。そのため、 `n_workers` に `2` を指定した `select` コマンドが2つ同時にリクエストされると、合計で最大で6つのCPUを使用することになりリソースをすべて使って高速に処理できます。 `2` より大きな値を指定すると、CPUのリソースよりも高い並列度になってしまうので、かえって実行が遅くなる可能性があります。

`n_workers` は指定した値に応じて以下の動作をします。

- `0` または `1` を指定した場合

  - 並列実行しません。

- `2` 以上を指定した場合

  - 指定したスレッド数以下で並列実行します。

- `-1` 以下を指定した場合

  - CPUのコア数以下のスレッドで並列実行します。

デフォルト値は `0` です。つまり並列実行しません。

注釈

環境変数 `GRN_SELECT_N_WORKERS_DEFAULT` を指定することでデフォルト値を変更することができます。

### 7.3.57.4.4. 出力関連の引数

#### 7.3.57.4.4.1. `output_columns`

出力するカラムを `,` 区切りで指定します。

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

実行例:

    select Entries --output_columns '_id, _key' --limit 1
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1,
    #         "The first post!"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `_id` と `_key` カラムの値だけを出力します。

`*` は特別な値で 擬似カラム 以外のすべてのカラムという意味です。

以下は `*` の使用例です。

実行例:

    select Entries --output_columns '_key, *' --limit 1
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         "The first post!",
    #         "Welcome! This is my first post!",
    #         5,
    #         "Hello"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `_key` 擬似カラム、 `content` カラム、 `n_likes` カラムの値を出力しますが、 `_id` 擬似カラムの値は出力しません。

デフォルト値は `_id, _key, *` です。これは `_score` 以外の全てのカラムを出力するという意味です。

#### 7.3.57.4.4.2. `sortby`

バージョン 6.0.3 で非推奨: 代わりに sort_keys を使ってください。

#### 7.3.57.4.4.3. `sort_keys`

ソートキーを `,` 区切りで指定します。それぞれのソートキーにはカラム名を指定します。

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

実行例:

    select Entries --sort_keys 'n_likes, _id'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         4,
    #         "Good-bye Senna",
    #         "I migrated all Senna system!",
    #         3,
    #         "Senna"
    #       ],
    #       [
    #         5,
    #         "Good-bye Tritonn",
    #         "I also migrated all Tritonn system!",
    #         3,
    #         "Senna"
    #       ],
    #       [
    #         1,
    #         "The first post!",
    #         "Welcome! This is my first post!",
    #         5,
    #         "Hello"
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `n_likes` カラムの値で昇順にソートします。 `n_likes` の値が同じレコードについては `_id` カラムの値で昇順にソートします。 `"Good-bye Senna"` と `"Good-bye Tritonn"` が `_id` カラムの値でソートしているケースです。

降順でソートしたい場合はカラム名の前に `-` をつけてください。

以下は降順の `sort_keys` の使用例です。

実行例:

    select Entries --sort_keys '-n_likes, _id'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ],
    #       [
    #         1,
    #         "The first post!",
    #         "Welcome! This is my first post!",
    #         5,
    #         "Hello"
    #       ],
    #       [
    #         4,
    #         "Good-bye Senna",
    #         "I migrated all Senna system!",
    #         3,
    #         "Senna"
    #       ],
    #       [
    #         5,
    #         "Good-bye Tritonn",
    #         "I also migrated all Tritonn system!",
    #         3,
    #         "Senna"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `n_likes` カラムの値で降順にソートします。しかし、 `_id` でソートするときは昇順でソートします。

もし、 `query` または `filter` 引数を使っているときは、 `sort_keys` の中で `_score` 擬似カラムを使うことができます。

実行例:

    select Entries --match_columns content --query fast --sort_keys -_score --output_columns '_key, _score'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Mroonga",
    #         2
    #       ],
    #       [
    #         "Groonga",
    #         1
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドはマッチしたレコードをヒットスコアで降順にソートし、レコードのキーとヒットスコアを出力します。

`query` 引数も `filter` 引数も指定しないで `_score` を使った場合は、 `_score` を無視して、ログファイルに警告を出力します。

#### 7.3.57.4.4.4. `offset`

出力するレコードの範囲を決めるためのオフセットを指定します。オフセットは0始まりです。 `--offset 1` は2番目以降のレコードを出力するという意味になります。

実行例:

    select Entries --sort_keys _id --offset 3 --output_columns _key
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         "Good-bye Senna"
    #       ],
    #       [
    #         "Good-bye Tritonn"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは4番目以降のレコードを出力します。

負の値を指定することもできます。負の値の場合は `マッチしたレコード数 + offset` 番目のレコードから始まる範囲という意味になります。もし、マッチしたレコードが3つあり、 `--offset -2` を指定した場合は2番目（ `3 + -2 = 1` 。 `1` は2番目という意味です。オフセットは0始まりということを思い出してください。） のレコードから3番目のレコードを取得します。

実行例:

    select Entries --sort_keys _id --offset -2 --output_columns _key
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         "Good-bye Senna"
    #       ],
    #       [
    #         "Good-bye Tritonn"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは4番目以降のレコードを出力します。なぜなら、全レコード数が `5` だからです。

デフォルト値は `0` です。

#### 7.3.57.4.4.5. `limit`

`limit` は出力レコード数の最大値を指定します。 もし、マッチしたレコード数が `limit` よりも小さい場合はすべてのレコードが出力されます。

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

実行例:

    select Entries --sort_keys _id --offset 2 --limit 3 --output_columns _key
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         "Mroonga"
    #       ],
    #       [
    #         "Good-bye Senna"
    #       ],
    #       [
    #         "Good-bye Tritonn"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは3番目、4番目、5番目のレコードを出力します。

負の値を指定することもできます。負の値の場合は、最大で `マッチしたレコード数 + limit + 1` 件のレコードを出力するという意味になります。 例えば、 `--limit -1` はすべてのレコードを出力します。これはすべてのレコードを表示する場合にとても便利です。

以下は負の値を使った `limit` の簡単な使用例です。

実行例:

    select Entries --limit -1
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1,
    #         "The first post!",
    #         "Welcome! This is my first post!",
    #         5,
    #         "Hello"
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ],
    #       [
    #         4,
    #         "Good-bye Senna",
    #         "I migrated all Senna system!",
    #         3,
    #         "Senna"
    #       ],
    #       [
    #         5,
    #         "Good-bye Tritonn",
    #         "I also migrated all Tritonn system!",
    #         3,
    #         "Senna"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドはすべてのレコードを出力します。

デフォルト値は `10` です。

#### 7.3.57.4.4.6. `scorer`

TODO: write in English and add example.

検索条件にマッチする全てのレコードに対して適用するgrn_exprをscript形式で指定します。

scorerは、検索処理が完了し、ソート処理が実行される前に呼び出されます。従って、各レコードのスコアを操作する式を指定しておけば、検索結果のソート順序をカスタマイズできるようになります。

### 7.3.57.4.5. あいまいクエリー関連の引数

Added in version 13.0.8.

注釈

この機能は実験的な機能です。現状、この機能はまだ安定していません。

このセクションではあいまいクエリー関連の引数を説明します。あいまいクエリーの利用例として タイプミスの許容 も参照してください。

あいまいクエリーを使うには少なくとも fuzzy_max_distance_ratio または fuzzy_max_distance を指定する必要があります。

あいまいクエリーは元のクエリーでどのレコードもヒットしないときに自動で実行されます。これはあいまいクエリーはマッチエスカレーションの方法の1つとして実現されているということです。マッチエスカレーションについては match_escalation_threshold も参照してください。

#### 7.3.57.4.5.1. `fuzzy_max_distance_ratio`

Added in version 13.0.8.

注釈

この機能は実験的な機能です。現状、この機能はまだ安定していません。

デフォルト値は `0` です。

あいまいクエリーを有効にするには fuzzy_max_distance_ratio または fuzzy_max_distance を指定する必要があります。もし、どちらも指定した場合は fuzzy_max_distance_ratio が使われます。

対象のクエリーをもとに許容する編集距離を指定できます。多くの場合、 fuzzy_max_distance よりもこの引数の方が適切です。

一般的に、短いクエリーに立ちして長い編集距離を許容することは適切ではありません。なぜなら、不適切な結果を増やすからです。たとえば、 `hye` と編集距離 `3` では次の単語を許容します。

- `hey` （適切な結果）

- `eye` （適切な結果）

- `bye` （適切な結果）

- `hyper` （適切な結果？）

- `hyphen` （適切な結果？）

fuzzy_max_distance はすべてのクエリー（短いクエリーにも長いクエリーにも）固定長の編集距離を指定します。

この引数を使うことで対象のクエリーの文字数に応じて各クエリーで許容する編集距離を指定できます。たとえば、 `--fuzzy_max_distance_ratio 0.34` の場合、 `hye` で許容する編集距離は `1` です。 `--fuzzy_max_distance_ratio 0.34` の場合、 `hypehn` で許容する編集距離は `2` です。これは `floor(${文字数} * ${FUZZY_MAX_DISTANCE_RATIO})` （ `floor()` は切り捨てする関数）で計算しています。

- `hye`: `floor(3 * 0.34) = floor(1.02) = 1`

- `hypehn`: `floor(6 * 0.34) = floor(2.04) = 2`

多くの場合、 `--fuzzy_max_distance_ratio 0.34` が適切な値です。もしこの値があなたの使い方に合わない場合は、この値を変えることができます。

以下は `--fuzzy_max_distance_ratio 0.34` だとタイプミスとして何文字許容するかを示した表です。

単語の文字数 | 許容するタイプミスの文字数
--- | ---
1 | 0 (`floor(1 * 0.34) = floor(0.34) = 0`)
2 | 0 (`floor(2 * 0.34) = floor(0.68) = 0`)
3 | 1 (`floor(3 * 0.34) = floor(1.02) = 1`)
4 | 1 (`floor(4 * 0.34) = floor(1.36) = 1`)
5 | 1 (`floor(5 * 0.34) = floor(1.7) = 1`)
6 | 2 (`floor(6 * 0.34) = floor(2.04) = 2`)

以下は、 `vary` では1文字のタイプミスを許容して、 `Gnoonag` では2文字のタイプミスを許容する例です。この例では match_escalation に `yes` を指定してすべてのクエリー（ `vary` と `Gnoonag` ）であいまいクエリーを有効にしています。多くの場合、 `--match_escalation yes` を指定するべきではありません。なぜなら不適切な結果が増えるかもしれないからです。

実行例:

    select \
      --table Entries \
      --fuzzy_max_distance_ratio 0.34 \
      --match_columns content \
      --query 'vary Gnoonag' \
      --match_escalation yes \
      --output_columns content,_score
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "I started to use Groonga. It's very fast!",
    #         2
    #       ]
    #     ]
    #   ]
    # ]

#### 7.3.57.4.5.2. `fuzzy_max_distance`

Added in version 13.0.8.

注釈

この機能は実験的な機能です。現状、この機能はまだ安定していません。

デフォルト値は `0` です。

あいまいクエリーを有効にするには fuzzy_max_distance_ratio または fuzzy_max_distance を指定する必要があります。もし、どちらも指定した場合は fuzzy_max_distance_ratio が使われます。

この引数を使うと許容する編集距離を固定値で指定できます。多くの場合はこの引数よりも fuzzy_max_distance の方が適切です。

以下は `vary` に1文字のタイプミスがあっても許容する例です。

実行例:

    select \
      --table Entries \
      --fuzzy_max_distance 1 \
      --match_columns content \
      --query vary \
      --output_columns content,_score
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "I started to use Groonga. It's very fast!",
    #         1
    #       ],
    #       [
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         1
    #       ]
    #     ]
    #   ]
    # ]

#### 7.3.57.4.5.3. `fuzzy_max_expansions`

Added in version 13.0.8.

注釈

この機能は実験的な機能です。現状、この機能はまだ安定していません。

デフォルト値は `10` です。

修正後の単語として最大で何単語を使うかを指定できます。もし、指定されたクエリーが `hye` で、この引数で `2` を指定して、 `hey` と `eye` と `hyper` が修正後の単語の候補だった場合、 `hey` と `eye` （2単語）だけが修正後の単語として使われます。

以下は `alx` の修正後の単語は1単語だけ使う例です。 `all` だけ使われて `also` は使われません。

実行例:

    select \
      --table Entries \
      --fuzzy_max_distance 2 \
      --fuzzy_max_expansions 1 \
      --match_columns content \
      --query alx \
      --output_columns content,_score
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "I migrated all Senna system!",
    #         2
    #       ],
    #       [
    #         "I also migrated all Tritonn system!",
    #         2
    #       ]
    #     ]
    #   ]
    # ]

#### 7.3.57.4.5.4. `fuzzy_prefix_length`

Added in version 13.0.8.

注釈

この機能は実験的な機能です。現状、この機能はまだ安定していません。

デフォルト値は `0` です。

プレフィックスとして使う文字数を指定します。この値が `1` で、指定された単語が `hye` の場合、プレフィックスは `h` になります。修正後の単語は `h` から始まらないといけません。たとえば、 `hey` は修正後の単語として使えますが、 `eye` や `bye` は使えません。

語彙表内の単語数が多いときにこの引数を使うと性能を向上できることがあります。

以下はクエリー `groonag` の修正後の単語のプレフィックスとして `gr` を必須にする例です。 `Groonga` （この例では NormalizerAuto を使っているので大文字小文字を無視する）は修正後の単語として使えますが、 `Mroonga` は使えません。なぜなら `Mroonga` は `gr` から始まっていないからです。

実行例:

    select \
      --table Entries \
      --fuzzy_max_distance 2 \
      --fuzzy_prefix_length 2 \
      --match_columns content \
      --query groonag \
      --output_columns content,_score
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "I started to use Groonga. It's very fast!",
    #         2
    #       ]
    #     ]
    #   ]
    # ]

#### 7.3.57.4.5.5. `fuzzy_with_transposition`

Added in version 13.0.9.

注釈

この機能は実験的な機能です。現状、この機能はまだ安定していません。

デフォルト値は `yes` です。

隣接文字の交換操作の場合の編集距離として `1` か `2` を選べます。隣接文字の交換の一例は `hello` と `ehllo` です。 `h` と `e` を交換することで同じ文字列になりますこの引数が `yes` の場合、この操作の編集距離は `1` です。そうでない場合、 `2` になります。（挿入操作と削除操作が必要になるため。）

以下は隣接文字の交換操作の編集距離に `2` を使う例です。この例では、 `groonag` の修正後の単語として `Mroonga` を使うことはできません。なぜなら、編集距離が `3` になるからです。

1. `g` を `M` で置換： `groonag` → `Mroonag`

2. `a` を追加： `Mroonag` → `Mroonaga`

3. `a` を削除： `Mroonaga` → `Mroonga`

実行例:

    select \
      --table Entries \
      --fuzzy_max_distance 2 \
      --fuzzy_with_transposition no \
      --match_columns content \
      --query groonag \
      --output_columns content,_score
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "I started to use Groonga. It's very fast!",
    #         1
    #       ]
    #     ]
    #   ]
    # ]

#### 7.3.57.4.5.6. `fuzzy_with_tokenize`

Added in version 13.0.9.

注釈

この機能は実験的な機能です。現状、この機能はまだ安定していません。

デフォルト値は `no` です。

あいまいクエリーの前に指定された単語をトークナイズするかどうかを選ぶことができます。トークナイザーが TokenNgram で指定された単語が `he11o` の場合、 `he` と `11` と `o` にトークナイズされます。この値が `yes` の場合、各トークナイズされたトークン毎に修正された単語を探します。たとえば、 `he` の修正された単語として `hi` が見つかり、 `11` の修正された単語として `12` が見つかり、 `o` の修正された単語として `x` が見つかります。そして、 `hi12x` で検索します。この値が `no` の場合、 `he11o` そのものに対して検索された単語を探します。たとえば、 `he11o` の修正された単語として `hello` が見つかり、 `hello` で検索します。

あいまいクエリーを実行する前に、1つ以上の空白文字で各単語に区切られることに注意してください。たとえば、クエリーパーサーは `hello world` を `hello` と `world` に区切ります。（ クエリー構文 も参照してください。） `hello` と `world` は別々に処理されます。

TokenMecab のような形態素解析器ベースのトークナイザーでは `no` が適切です。なぜなら、多くの場合、タイプミスがある単語は期待通りにトークナイズされないからです。たとえば、 `ともて` （ `とても` のタイプミス）は `ともて` （副詞）ではなく、 `とも `` （形容詞） と ``て` （接続助詞）にトークナイズされるかもしれません。

以下はあいまいクエリーの前に指定された単語をトークナイズする例です。この例では `gr00nga` の修正された単語として `Groonga` を使うことができません。なぜなら、 `gr` と `00` と `nga` がそれぞれ別々に処理されるからです。

実行例:

    select \
      --table Entries \
      --fuzzy_max_distance 2 \
      --fuzzy_tokenize yes \
      --match_columns content \
      --query gr00nga \
      --output_columns content,_score
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         0
    #       ],
    #       [
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ]
    #     ]
    #   ]
    # ]

### 7.3.57.4.6. 動的カラム関連の引数

Added in version 6.0.6.

このセクションは動的カラム関連の引数について説明します。ウィンドウ関数を使うために動的カラムを使うこともできますが、このセクションではウィンドウ関数については説明しません。ウィンドウ関数については ウィンドウ関数関連の引数 を参照してください。

`select` 実行中に0個以上のカラムを作ってそこに値を入れることができます。これらのカラムのことを「動的カラム」と呼びます。動的カラムが作られた後は通常のカラムと同じように使えます。

動的カラムは一度計算した値を使いまわすのでパフォーマンス上のメリットがあります。

動的カラムを使うとメモリー使用量が増えます。 `select` 実行中にカラムの値を保存し続ける必要があるからです。

以下のケースでは動的カラムを使う必要があります。

> - SQLの `AS` のように値に名前をつけたい場合。

> - 計算した値をドリルダウンしたい場合。Groongaにはドリルダウン中に値を計算する機能はありません。

> - ウィンドウ関数を使いたい場合。

いくつか動的カラムを作るタイミングがあります。各動的カラムには `stage` を指定する必要があります。これはどのタイミングで動的カラムを作るかを制御するためです。よりよい性能を出すために適切なタイミングを選ぶことが重要です。

たとえば、出力対象のレコードだけに必要な動的カラムを全レコードに対して作成することはオススメしません。通常、たとえテーブル内に大量のレコードがあったとしても、出力対象のレコードは少なくなります。これは、多くの場合は、テーブル内のレコードをフィルターしてソートしてレコード数を制限して、制限したレコードだけを出力するからです。

`stage` の詳細は columns[${NAME}].stage を見てください。

以下は動的カラムの引数です。ウィンドウ関数関連の引数は入っていません。ウィンドウ関数関連の引数については ウィンドウ関数関連の引数 を見てください。

名前 | デフォルト値 | 必須か省略可能か
--- | --- | ---
`columns[${NAME}].stage` | `null` | 必須
`columns[${NAME}].flags` | `COLUMN_SCALAR` | 省略可能
`columns[${NAME}].type` | `null` | 必須
`columns[${NAME}].value` | `null` | 必須

1つの動的カラムに対して複数のパラメーターを指定する必要があります。同じ `${NAME}` を使っているパラメーターは同じ動的カラムのパラメーターとして扱われます。以下は2つの動的カラム（ `name1` と `name2` ）用のパラメーターを指定する例です。:

    --columns[name1].stage initial
    --columns[name1].type UInt32
    --columns[name1].value 29

    --columns[name2].stage filtered
    --columns[name2].type ShortText
    --columns[name2].value "29"

#### 7.3.57.4.6.1. `columns[${NAME}].stage`

Added in version 6.0.6.

どのタイミング（どのステージ）で動的カラムを作るかを指定します。動的カラムを作る場合はこのパラメーターは必須です。

指定可能なステージは以下の通りです。

名前 | 説明
--- | ---
`initial` | 最初に動的カラムを作成します。
`filtered` | query と filter を評価してから動的カラムを作成します。
`output` | output_columns を評価する前に動的カラムを作成します。

以下は動的カラム作成タイミング入りの `select` の処理の流れです。できるだけ後のステージを選ぶべきです。

> 1. `initial` ステージの動的カラムを作ります。すべてのレコードはこの動的カラムを持ちます。

> 2. query と filter を評価します。 `initial` ステージで作った動的カラムを使えます。

> 3. `filtered` ステージの動的カラムを作ります。フィルター後のレコードだけがこの動的カラムを持ちます。

> 4. adjuster を評価します。 `initial` ステージと `filtered` ステージで作った動的カラムを使えます。

> 5. scorer を評価します。 `initial` ステージと `filtered` ステージで作った動的カラムを使えます。

> 6. sort_keys 、 offset 、 limit を評価します。 `initial` ステージと `filtered` ステージで作った動的カラムを使えます。

> 7. スライス関連の引数 を評価します。 `initial` ステージと `filtered` ステージで作った動的カラムを使えます。

> 8. ドリルダウン関連の引数 と 高度なドリルダウン関連のパラメーター を評価します。 `initial` ステージと `filtered` ステージで作った動的カラムを使えます。各ドリルダウン内でも個別に動的カラムを作れるので混同しないように注意してください。

> 9. `output` ステージの動的カラムを作ります。最大 limit 件のレコードだけがこの動的カラムを持ちます。

> 10. output_columns を評価します。 `initial` ステージと `filtered` ステージと `output` ステージで作った動的カラムを使えます。

以下は `initial` ステージで `is_popular` カラムを作る例です。作成した `is_popular` カラムは `filter` や `output_columns` を含むすべてのパラメーターで使えます。

実行例:

    select Entries \
      --columns[is_popular].stage initial \
      --columns[is_popular].type Bool \
      --columns[is_popular].value 'n_likes >= 10' \
      --filter is_popular \
      --output_columns _id,is_popular,n_likes
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "is_popular",
    #           "Bool"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         2,
    #         true,
    #         10
    #       ],
    #       [
    #         3,
    #         true,
    #         15
    #       ]
    #     ]
    #   ]
    # ]

#### 7.3.57.4.6.2. `columns[${NAME}].flags`

Added in version 6.0.6.

動的カラムのフラグを指定します。これは column_create の `flags` パラメーターと同じです。利用可能なフラグは flags を見てください。

デフォルト値は `COLUMN_SCALAR` です。

以下は `columns[${NAME}].flags` の使用例です。この例では `COLUMN_VECTOR` フラグを指定してベクターカラムを作成しています。 `plugin_register functions/vector` は vector_new 関数を使うために実行しています。:

実行例:

    plugin_register functions/vector
    # [[0,1337566253.89858,0.000355720520019531],true]
    select Entries \
      --columns[vector].stage initial \
      --columns[vector].flags COLUMN_VECTOR \
      --columns[vector].type UInt32 \
      --columns[vector].value 'vector_new(1, 2, 3)' \
      --output_columns _id,vector
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "vector",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         1,
    #         [
    #           1,
    #           2,
    #           3
    #         ]
    #       ],
    #       [
    #         2,
    #         [
    #           1,
    #           2,
    #           3
    #         ]
    #       ],
    #       [
    #         3,
    #         [
    #           1,
    #           2,
    #           3
    #         ]
    #       ],
    #       [
    #         4,
    #         [
    #           1,
    #           2,
    #           3
    #         ]
    #       ],
    #       [
    #         5,
    #         [
    #           1,
    #           2,
    #           3
    #         ]
    #       ]
    #     ]
    #   ]
    # ]

#### 7.3.57.4.6.3. `columns[${NAME}].type`

Added in version 6.0.6.

動的カラムの値の型を指定します。 column_create の `type` パラメーターと同じです。利用可能な型は type を見てください。

必須の引数です。

以下は `ShortText` 型のカラムを作る例です。保存された値は自動的に `ShortText` にキャストされます。この例では数値が `ShortText` にキャストされています。

実行例:

    select Entries \
      --columns[n_likes_string].stage initial \
      --columns[n_likes_string].type ShortText \
      --columns[n_likes_string].value n_likes \
      --output_columns _id,n_likes,n_likes_string
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "n_likes_string",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1,
    #         5,
    #         "5"
    #       ],
    #       [
    #         2,
    #         10,
    #         "10"
    #       ],
    #       [
    #         3,
    #         15,
    #         "15"
    #       ],
    #       [
    #         4,
    #         3,
    #         "3"
    #       ],
    #       [
    #         5,
    #         3,
    #         "3"
    #       ]
    #     ]
    #   ]
    # ]

#### 7.3.57.4.6.4. `columns[${NAME}].value`

Added in version 6.0.6.

この動的カラムの値を生成する式を指定します。式には スクリプト構文 を使います。この構文は filter と同じです。たとえば、 `1 + 1` 、 `string_length("Hello")` 、 `column * 1.08` などは妥当な式です。

ウィンドウ関数を使う場合は、 `value` の値に ウィンドウ関数 を指定し、他のウィンドウ関数のパラメーターも指定する必要があります。詳細は ウィンドウ関数関連の引数 を見てください。

必須の引数です。

以下は内容の文字数を格納するための動的カラムを1つ作る例です。この例では文字数を数えるために `functions/string` プラグイン内の string_length 関数を使っています。 `functions/string` プラグインを登録するために plugin_register を使っています。

実行例:

    plugin_register functions/string
    # [[0,1337566253.89858,0.000355720520019531],true]
    select Entries \
      --columns[content_length].stage initial \
      --columns[content_length].type UInt32 \
      --columns[content_length].value 'string_length(content)' \
      --output_columns _id,content,content_length
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "content_length",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         1,
    #         "Welcome! This is my first post!",
    #         31
    #       ],
    #       [
    #         2,
    #         "I started to use Groonga. It's very fast!",
    #         41
    #       ],
    #       [
    #         3,
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         64
    #       ],
    #       [
    #         4,
    #         "I migrated all Senna system!",
    #         28
    #       ],
    #       [
    #         5,
    #         "I also migrated all Tritonn system!",
    #         35
    #       ]
    #     ]
    #   ]
    # ]

### 7.3.57.4.7. ウィンドウ関数関連の引数

Added in version 6.0.6.

このセクションはウィンドウ関数関連の引数について説明します。ウィンドウ関数を使うためには動的カラムを使う必要があります。動的カラムについては 動的カラム関連の引数 を見てください。

Groongaのウィンドウ関数はSQLのウィンドウ関数と似ています。通常の関数は現在のレコードだけを使って結果を計算します。一方、ウィンドウ関数は複数のレコードを使って結果を計算します。複数のレコードを処理できるのでウィンドウ関数はデータ解析に有用です。

サポートしているウィンドウ関数は ウィンドウ関数 で確認できます。たとえば、 window_sum はウィンドウ関数です。このウィンドウ関数は対象レコードの数値の合計を計算します。

ウィンドウ関数は指定したグループキーでグループ化したレコードを処理します。たとえば、以下のケースではウィンドウ関数は3つのグループ（ `Hello` グループ、 `Groonga` グループ、 `Senna` グループ）を処理します。 window_sum は各グループ毎に `n_likes` の値の合計を計算します。

グループ番号 | グループキーの値 | `n_likes` の値 | window_sum の結果
--- | --- | --- | ---
1 | `Hello` | 5 | 5
2 | `Groonga` | 10 | 25
2 | `Groonga` | 15 | 25
3 | `Senna` | 3 | 6
3 | `Senna` | 3 | 6

グループキーを指定しないこともできます。この場合、ウィンドウ関数はすべてのレコードを含んだ1つのグループだけを処理します。以下のケースでは window_sum はすべての `n_likes` の値の合計を計算します。

グループ番号 | `n_likes` の値 | window_sum の結果
--- | --- | ---
1 | 5 | 36
1 | 10 | 36
1 | 15 | 36
1 | 3 | 36
1 | 3 | 36

ウィンドウ関数は各グループのレコードを指定された順に処理します。前述のグループキーの例のようにソートキーを指定しないこともできます。

ソートキーを指定しなかったときの挙動は各ウィンドウ関数の仕様に依存します。たとえば、 window_sum はソートキーを指定したときと指定しないときで挙動が変わります。ソートキーを指定しなかったときは、 window_sum はグループの全レコードの値の合計を計算し、すべての対象レコードに合計値を格納します。これは前述のグループキーの例での挙動です。ソートキーを指定したときは、 window_sum は累積和を計算します。 window_sum はグループの全レコードの合計を順番に計算し、各レコードにはそのレコードを処理した時点の合計値を格納します。以下に例を示します。

グループ番号 | グループキーの値 | ソートキーの値 | `n_likes` の値 | window_sum の結果 | 備考
--- | --- | --- | --- | --- | ---
1 | `Hello` | 1 | 5 | 5 | グループ番号1の最初のレコード。（ `5 = 5` ）
2 | `Groonga` | 90 | 10 | 10 | グループ番号2の最初のレコード。（ `10 = 10` ）
2 | `Groonga` | 91 | 15 | 25 | グループ番号2の2つ目のレコード。（ `10 + 15 = 25` ）
3 | `Senna` | 200 | 3 | 8 | グループ番号3の2つ目のレコード。（ `5 + 3 = 8` ）
3 | `Senna` | 100 | 5 | 5 | グループ番号3の最初のレコード。（ `5 = 5` ）

以下はウィンドウ関数のパラメーターです。ウィンドウ関数関連のパラメーターと動的カラム関連のパラメーターを指定する必要があります。なぜならウィンドウ関数は動的カラムの上に実装されているからです。動的カラム関連のパラメーターについては 動的カラム関連の引数 を見てください。

名前 | 必須か省略可能か | 備考
--- | --- | ---
`columns[${NAME}].value` | 必須 | ウィンドウ関数 を使います。
`columns[${NAME}].window.sort_keys` | `columns[${NAME}].window.group_keys` を指定しない場合は必須です。 |
`columns[${NAME}].window.group_keys` | `columns[${NAME}].window.sort_keys` を指定しない場合は必須です。 |

#### 7.3.57.4.7.1. `columns[${NAME}].window.sort_keys`

Added in version 6.0.6.

各グループでのソートキーを指定します。ウィンドウ関数は各グループのレコードを指定された順に処理します。

ソートキーを `,` 区切りで指定します。それぞれのソートキーにはカラム名を指定します。これは sort_keys と同じです。

ウィンドウ関数を使う場合は columns[${NAME}].window.sort_keys または columns[${NAME}].window.group_keys を使う必要があります。

以下は `Entries.tag` 毎に累積和を計算する例です。各グループ内のレコードは `Entries._key` でソートします。

実行例:

    select \
      --table Entries \
      --columns[n_likes_cumulative_sum_per_tag].stage initial \
      --columns[n_likes_cumulative_sum_per_tag].type UInt32 \
      --columns[n_likes_cumulative_sum_per_tag].value 'window_sum(n_likes)' \
      --columns[n_likes_cumulative_sum_per_tag].window.sort_keys _key \
      --columns[n_likes_cumulative_sum_per_tag].window.group_keys tag \
      --sort_keys _key \
      --output_columns tag,_key,n_likes,n_likes_cumulative_sum_per_tag
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "tag",
    #           "ShortText"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "n_likes_cumulative_sum_per_tag",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         "Senna",
    #         "Good-bye Senna",
    #         3,
    #         3
    #       ],
    #       [
    #         "Senna",
    #         "Good-bye Tritonn",
    #         3,
    #         6
    #       ],
    #       [
    #         "Groonga",
    #         "Groonga",
    #         10,
    #         10
    #       ],
    #       [
    #         "Groonga",
    #         "Mroonga",
    #         15,
    #         25
    #       ],
    #       [
    #         "Hello",
    #         "The first post!",
    #         5,
    #         5
    #       ]
    #     ]
    #   ]
    # ]

#### 7.3.57.4.7.2. `columns[${NAME}].window.group_keys`

Added in version 7.0.0.

グループキーを指定します。ウィンドウ関数は各グループのレコードを処理します。グループキーを指定しない場合はウィンドウ関数はすべてのレコードを含んだ1つのグループを処理します。

グループキーを `,` 区切りで指定します。それぞれのグループキーにはカラム名を指定します。これは drilldown と同じです。

ウィンドウ関数を使う場合は columns[${NAME}].window.sort_keys または columns[${NAME}].window.group_keys を使う必要があります。

以下は `Entries.tag` 毎に合計を計算する例です。

実行例:

    select \
      --table Entries \
      --columns[n_likes_sum_per_tag].stage initial \
      --columns[n_likes_sum_per_tag].type UInt32 \
      --columns[n_likes_sum_per_tag].value 'window_sum(n_likes)' \
      --columns[n_likes_sum_per_tag].window.group_keys tag \
      --sort_keys _key \
      --output_columns tag,_key,n_likes,n_likes_sum_per_tag
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "tag",
    #           "ShortText"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "n_likes_sum_per_tag",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         "Senna",
    #         "Good-bye Senna",
    #         3,
    #         6
    #       ],
    #       [
    #         "Senna",
    #         "Good-bye Tritonn",
    #         3,
    #         6
    #       ],
    #       [
    #         "Groonga",
    #         "Groonga",
    #         10,
    #         25
    #       ],
    #       [
    #         "Groonga",
    #         "Mroonga",
    #         15,
    #         25
    #       ],
    #       [
    #         "Hello",
    #         "The first post!",
    #         5,
    #         5
    #       ]
    #     ]
    #   ]
    # ]

### 7.3.57.4.8. ドリルダウン関連の引数

このセクションでは基本的なドリルダウン関連の引数について説明します。高度なドリルダウン関連の引数は他のセクションで説明します。

#### 7.3.57.4.8.1. `drilldown`

グループ化するときに使うキーを `,` 区切りで指定します。

指定した検索条件にマッチしたレコードを指定したキーのそれぞれでグループ化します。検索条件を指定していない場合はすべてのレコードを指定したキーのそれぞれでグループ化します。

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

実行例:

    select Entries \
      --output_columns _key,tag \
      --drilldown tag
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         "The first post!",
    #         "Hello"
    #       ],
    #       [
    #         "Groonga",
    #         "Groonga"
    #       ],
    #       [
    #         "Mroonga",
    #         "Groonga"
    #       ],
    #       [
    #         "Good-bye Senna",
    #         "Senna"
    #       ],
    #       [
    #         "Good-bye Tritonn",
    #         "Senna"
    #       ]
    #     ],
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Hello",
    #         1
    #       ],
    #       [
    #         "Groonga",
    #         2
    #       ],
    #       [
    #         "Senna",
    #         2
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは次の情報を出力します。

> - 「Hello」タグを持つレコードが1つある。

> - 「Groonga」タグを持つレコードが2つある。

> - 「Senna」タグを持つレコードが2つある。

以下は検索条件付きで `drilldown` を使う例です。

実行例:

    select Entries \
      --output_columns _key,tag \
      --filter 'n_likes >= 5' \
      --drilldown tag
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         "The first post!",
    #         "Hello"
    #       ],
    #       [
    #         "Groonga",
    #         "Groonga"
    #       ],
    #       [
    #         "Mroonga",
    #         "Groonga"
    #       ]
    #     ],
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Hello",
    #         1
    #       ],
    #       [
    #         "Groonga",
    #         2
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは次の情報を出力します。

> - `n_likes` の値が5以上のレコードの中には…

>   - 「Hello」タグを持つレコードが1つある。

>   - 「Groonga」タグを持つレコードが2つある。

以下は複数のグループ化キーを指定する `drilldown` の例です。

実行例:

    select Entries \
      --limit 0 \
      --output_columns _id \
      --drilldown tag,n_likes
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ]
    #       ]
    #     ],
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Hello",
    #         1
    #       ],
    #       [
    #         "Groonga",
    #         2
    #       ],
    #       [
    #         "Senna",
    #         2
    #       ]
    #     ],
    #     [
    #       [
    #         4
    #       ],
    #       [
    #         [
    #           "_key",
    #           "UInt32"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         5,
    #         1
    #       ],
    #       [
    #         10,
    #         1
    #       ],
    #       [
    #         15,
    #         1
    #       ],
    #       [
    #         3,
    #         2
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは次の情報を出力します。

> - `tag` について:

>   - 「Hello」タグを持つレコードが1つある。

>   - 「Groonga」タグを持つレコードが2つある。

>   - 「Senna」タグを持つレコードが2つある。

> - `n_likes` について:

>   - 「Hello」タグを持つレコードが1つある。

>   - 「Groonga」タグを持つレコードが2つある。

>   - 「Senna」タグを持つレコードが2つある。

#### 7.3.57.4.8.2. `drilldown_sortby`

バージョン 6.0.3 で非推奨: drilldown_sort_keys を代わりに使ってください

#### 7.3.57.4.8.3. `drilldown_sort_keys`

ドリルダウン結果のソートキーを `,` 区切りで指定します。それぞれのソートキーはカラム名を指定します。

グループ化されたレコード数は `_nsubrecs` 擬似カラム 擬似カラムで参照できます。

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

実行例:

    select Entries \
      --limit 0 \
      --output_columns _id \
      --drilldown 'tag, n_likes' \
      --drilldown_sort_keys '-_nsubrecs, _key'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ]
    #       ]
    #     ],
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Groonga",
    #         2
    #       ],
    #       [
    #         "Senna",
    #         2
    #       ],
    #       [
    #         "Hello",
    #         1
    #       ]
    #     ],
    #     [
    #       [
    #         4
    #       ],
    #       [
    #         [
    #           "_key",
    #           "UInt32"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         3,
    #         2
    #       ],
    #       [
    #         5,
    #         1
    #       ],
    #       [
    #         10,
    #         1
    #       ],
    #       [
    #         15,
    #         1
    #       ]
    #     ]
    #   ]
    # ]

ドリルダウン結果は「グループに含まれるレコード数」（= `_nsubrecs` ）で降順にソートします。「グループに含まれるレコード数」が同じグループが複数あった場合は、グループ化に使ったキー（= `_key` ）で昇順にソートします。

`drilldown` で指定したすべてのグループキーで同じソートキーを使います。

実行例:

    select Entries \
      --limit 0 \
      --output_columns _id \
      --drilldown 'tag, n_likes' \
      --drilldown_sort_keys '-_nsubrecs, _key'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ]
    #       ]
    #     ],
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Groonga",
    #         2
    #       ],
    #       [
    #         "Senna",
    #         2
    #       ],
    #       [
    #         "Hello",
    #         1
    #       ]
    #     ],
    #     [
    #       [
    #         4
    #       ],
    #       [
    #         [
    #           "_key",
    #           "UInt32"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         3,
    #         2
    #       ],
    #       [
    #         5,
    #         1
    #       ],
    #       [
    #         10,
    #         1
    #       ],
    #       [
    #         15,
    #         1
    #       ]
    #     ]
    #   ]
    # ]

`tag` のドリルダウンでも `n_likes` のドリルダウンでも同じソートキーを使っています。

それぞれのドリルダウンで異なるソートキーを使いたい場合は 高度なドリルダウン関連のパラメーター を参照してください。

#### 7.3.57.4.8.4. `drilldown_output_columns`

ドリルダウン結果から出力するカラムを `,` 区切りで指定します。

以下は `drilldown_output_columns` の使用例です。

実行例:

    select Entries \
      --limit 0 \
      --output_columns _id \
      --drilldown tag \
      --drilldown_output_columns _key
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ]
    #       ]
    #     ],
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         "Hello"
    #       ],
    #       [
    #         "Groonga"
    #       ],
    #       [
    #         "Senna"
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドはグループ化したキーを出力していくだけです。

グループ化したキーが参照型のカラム（型がテーブルのカラム）だった場合、参照型のカラムが参照しているテーブルのカラムにもアクセスできます。

参照型に対してドリルダウンする方法を示すために使うスキーマ定義とサンプルデータは以下の通りです。

実行例:

    table_create Tags TABLE_HASH_KEY ShortText --normalizer NormalizerAuto
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Tags label COLUMN_SCALAR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Tags priority COLUMN_SCALAR Int32
    # [[0,1337566253.89858,0.000355720520019531],true]
    table_create Items TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Items tag COLUMN_SCALAR Tags
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table Tags
    [
    {"_key": "groonga", label: "Groonga", priority: 10},
    {"_key": "mroonga", label: "Mroonga", priority: 5}
    ]
    # [[0,1337566253.89858,0.000355720520019531],2]
    load --table Items
    [
    {"_key": "A", "tag": "groonga"},
    {"_key": "B", "tag": "groonga"},
    {"_key": "C", "tag": "mroonga"}
    ]
    # [[0,1337566253.89858,0.000355720520019531],3]

`Tags` テーブルは参照されているテーブルです。 `Items.tag` は参照型のカラムです。

`Tags.label` は `drilldown_output_columns` の中では `label` で参照できます。

実行例:

    select Items \
      --limit 0 \
      --output_columns _id \
      --drilldown tag \
      --drilldown_output_columns '_key, label'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ]
    #       ]
    #     ],
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "label",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         "groonga",
    #         "Groonga"
    #       ],
    #       [
    #         "mroonga",
    #         "Mroonga"
    #       ]
    #     ]
    #   ]
    # ]

`*` を使うと、参照されているテーブル（= `Tags` ）のすべてのカラムを参照できます。

実行例:

    select Items \
      --limit 0 \
      --output_columns _id \
      --drilldown tag \
      --drilldown_output_columns '_key, *'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ]
    #       ]
    #     ],
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "label",
    #           "ShortText"
    #         ],
    #         [
    #           "priority",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "groonga",
    #         "Groonga",
    #         10
    #       ],
    #       [
    #         "mroonga",
    #         "Mroonga",
    #         5
    #       ]
    #     ]
    #   ]
    # ]

`*` は `label, priority` に展開されます。

`drilldown_output_columns` のデフォルト値は `_key, _nsubrecs` です。グループ化に使ったキーとグループのレコード数を出力する、ということです。

drilldown_calc_types を使うと、 `drilldown_output_columns` の中で `_max` 、 `_min` 、 `_sum` 、 `_avg` といった 擬似カラム も使えるようになります。詳細は `drilldown_calc_types` のドキュメントを参照してください。

#### 7.3.57.4.8.5. `drilldown_offset`

ドリルダウン結果を出力するレコードの範囲を決めるためのオフセットを指定します。オフセットは0始まりです。 `--offset 1` は2番目以降のレコードを出力するという意味になります。

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

実行例:

    select Entries \
      --limit 0 \
      --output_columns _id \
      --drilldown tag \
      --drilldown_sort_keys _key \
      --drilldown_offset 1
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ]
    #       ]
    #     ],
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Hello",
    #         1
    #       ],
    #       [
    #         "Senna",
    #         2
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは2番目以降のレコードを出力します。

負の値を指定することもできます。負の値の場合は `グループの数 + offset` 番目のレコードから始まる範囲という意味になります。もし、グループの数が3つあり、 `--offset -2` を指定した場合は1番目（ `3 + -2 = 1` 。 `1` は2番目です。オフセットは0始まりということを思い出してください。） のグループから3番目のグループが出力されます。

実行例:

    select Entries \
      --limit 0 \
      --output_columns _id \
      --drilldown tag \
      --drilldown_sort_keys _key \
      --drilldown_offset -2
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ]
    #       ]
    #     ],
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Hello",
    #         1
    #       ],
    #       [
    #         "Senna",
    #         2
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは2番目以降のグループを出力します。なぜなら、全グループ数が `3` だからです。

`drilldown_offset` のデフォルト値は `0` です。

#### 7.3.57.4.8.6. `drilldown_limit`

`drilldown_limit` は出力グループ数の最大値を指定します。もし、グループ数 `limit` よりも小さい場合はすべてのグループが出力されます。

以下は `drilldown_limit` の使用例です。

実行例:

    select Entries \
      --limit 0 \
      --output_columns _id \
      --drilldown tag \
      --drilldown_sort_keys _key \
      --drilldown_offset 1 \
      --drilldown_limit 2
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ]
    #       ]
    #     ],
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Hello",
    #         1
    #       ],
    #       [
    #         "Senna",
    #         2
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは2番目、3番目のレコードを出力します。

負の値を指定することもできます。負の値の場合は、最大で `マッチしたレコード数 + drilldown_limit + 1` 件のレコードを出力するという意味になります。 例えば、 `--drilldown_limit -1` はすべてのレコードを出力します。これはすべてのレコードを表示する場合にとても便利です。

以下は `drilldown_limit` に負の値を指定する例です。

実行例:

    select Entries \
      --limit 0 \
      --output_columns _id \
      --drilldown tag \
      --drilldown_sort_keys _key \
      --drilldown_limit -1
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ]
    #       ]
    #     ],
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Groonga",
    #         2
    #       ],
    #       [
    #         "Hello",
    #         1
    #       ],
    #       [
    #         "Senna",
    #         2
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドはすべてのグループを出力します。

`drilldown_limit` のデフォルト値は `10` です。

#### 7.3.57.4.8.7. `drilldown_calc_types`

ドリルダウンでグループ内のレコードの値を計算（集計）する方法を指定します。「 `,` 」で区切ることで複数の計算タイプを指定することもできます。たとえば、 `MAX,MIN` といった具合です。

計算対象の値はグループ内のレコードのカラムから取得します。このカラムは drilldown_calc_target で指定します。

計算した値は drilldown_output_columns の中で `_max` や `_min` のような 擬似カラム を指定すると取得できます。

以下の計算タイプを使えます。

タイプ名 | 擬似カラム 名 | drilldown_calc_target が必要か | 説明
--- | --- | --- | ---
`NONE` | なし。 | 必要ない。 | 無視されます。
`COUNT` | `_nsubrecs` | 必要ない。 | グループ内のレコードの数を数える。常に有効なので指定する必要はない。
`MAX` | `_max` | 必要。 | グループ内のレコードの整数値の中で最大の値を見つける。
`MIN` | `_min` | 必要。 | グループ内のレコードの整数値の中で最小の値を見つける。
`SUM` | `_sum` | 必要。 | グループ内のレコードの整数値の合計を計算する。
`AVG` | `_avg` | 必要。 | グループ内のレコードの整数値・浮動小数点数値の平均を計算する。

以下は `MAX` の使用例です。

実行例:

    select Entries \
      --limit -1 \
      --output_columns _id,n_likes \
      --drilldown tag \
      --drilldown_calc_types MAX \
      --drilldown_calc_target n_likes \
      --drilldown_output_columns _key,_max
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         1,
    #         5
    #       ],
    #       [
    #         2,
    #         10
    #       ],
    #       [
    #         3,
    #         15
    #       ],
    #       [
    #         4,
    #         3
    #       ],
    #       [
    #         5,
    #         3
    #       ]
    #     ],
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_max",
    #           "Int64"
    #         ]
    #       ],
    #       [
    #         "Hello",
    #         5
    #       ],
    #       [
    #         "Groonga",
    #         15
    #       ],
    #       [
    #         "Senna",
    #         3
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `tag` カラムの値ですべてのレコードをグループ化します。その後、各グループについて最大の `n_likes` カラムの値を探し、「グループ化に使ったキー」と「 `n_likes` カラムの値の最大値」のペアのリストを出力します。 `n_likes` カラムの値の最大値を参照するために `_max` 擬似カラム を使っています。

以下は `MIN` の使用例です。

実行例:

    select Entries \
      --limit -1 \
      --output_columns _id,n_likes \
      --drilldown tag \
      --drilldown_calc_types MIN \
      --drilldown_calc_target n_likes \
      --drilldown_output_columns _key,_min
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         1,
    #         5
    #       ],
    #       [
    #         2,
    #         10
    #       ],
    #       [
    #         3,
    #         15
    #       ],
    #       [
    #         4,
    #         3
    #       ],
    #       [
    #         5,
    #         3
    #       ]
    #     ],
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_min",
    #           "Int64"
    #         ]
    #       ],
    #       [
    #         "Hello",
    #         5
    #       ],
    #       [
    #         "Groonga",
    #         10
    #       ],
    #       [
    #         "Senna",
    #         3
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `tag` カラムの値ですべてのレコードをグループ化します。その後、各グループについて最小の `n_likes` カラムの値を探し、「グループ化に使ったキー」と「 `n_likes` カラムの値の最小値」のペアのリストを出力します。 `n_likes` カラムの値の最小値を参照するために `_min` 擬似カラム を使っています。

以下は `SUM` の使用例です。

実行例:

    select Entries \
      --limit -1 \
      --output_columns _id,n_likes \
      --drilldown tag \
      --drilldown_calc_types SUM \
      --drilldown_calc_target n_likes \
      --drilldown_output_columns _key,_sum
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         1,
    #         5
    #       ],
    #       [
    #         2,
    #         10
    #       ],
    #       [
    #         3,
    #         15
    #       ],
    #       [
    #         4,
    #         3
    #       ],
    #       [
    #         5,
    #         3
    #       ]
    #     ],
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_sum",
    #           "Int64"
    #         ]
    #       ],
    #       [
    #         "Hello",
    #         5
    #       ],
    #       [
    #         "Groonga",
    #         25
    #       ],
    #       [
    #         "Senna",
    #         6
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `tag` カラムの値ですべてのレコードをグループ化します。その後、各グループについて `n_likes` カラムの合計を計算し、「グループ化に使ったキー」と「 `n_likes` カラムの値の合計」のペアのリストを出力します。 `n_likes` カラムの値の合計を参照するために `_sum` 擬似カラム を使っています。

以下は `AVG` の使用例です。

実行例:

    select Entries \
      --limit -1 \
      --output_columns _id,n_likes \
      --drilldown tag \
      --drilldown_calc_types AVG \
      --drilldown_calc_target n_likes \
      --drilldown_output_columns _key,_avg
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         1,
    #         5
    #       ],
    #       [
    #         2,
    #         10
    #       ],
    #       [
    #         3,
    #         15
    #       ],
    #       [
    #         4,
    #         3
    #       ],
    #       [
    #         5,
    #         3
    #       ]
    #     ],
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_avg",
    #           "Float"
    #         ]
    #       ],
    #       [
    #         "Hello",
    #         5.0
    #       ],
    #       [
    #         "Groonga",
    #         12.5
    #       ],
    #       [
    #         "Senna",
    #         3.0
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは `tag` カラムの値ですべてのレコードをグループ化します。その後、各グループについて `n_likes` カラムの平均を計算し、「グループ化に使ったキー」と「 `n_likes` カラムの値の平均」のペアのリストを出力します。 `n_likes` カラムの値の合計を参照するために `_avg` 擬似カラム を使っています。

以下はすべての計算タイプを使う例です。

実行例:

    select Entries \
      --limit -1 \
      --output_columns _id,n_likes \
      --drilldown tag \
      --drilldown_calc_types MAX,MIN,SUM,AVG \
      --drilldown_calc_target n_likes \
      --drilldown_output_columns _key,_nsubrecs,_max,_min,_sum,_avg
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         1,
    #         5
    #       ],
    #       [
    #         2,
    #         10
    #       ],
    #       [
    #         3,
    #         15
    #       ],
    #       [
    #         4,
    #         3
    #       ],
    #       [
    #         5,
    #         3
    #       ]
    #     ],
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ],
    #         [
    #           "_max",
    #           "Int64"
    #         ],
    #         [
    #           "_min",
    #           "Int64"
    #         ],
    #         [
    #           "_sum",
    #           "Int64"
    #         ],
    #         [
    #           "_avg",
    #           "Float"
    #         ]
    #       ],
    #       [
    #         "Hello",
    #         1,
    #         5,
    #         5,
    #         5,
    #         5.0
    #       ],
    #       [
    #         "Groonga",
    #         2,
    #         15,
    #         10,
    #         25,
    #         12.5
    #       ],
    #       [
    #         "Senna",
    #         2,
    #         3,
    #         3,
    #         6,
    #         3.0
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドは複数の計算タイプを `MAX,MIN,SUM,AVG` というように「 `,` 」で区切って指定しています。 drilldown_output_columns で `COUNT` を指定していなくても `_nsubrecs` 擬似カラム を使えます。これは、 `COUNT` は常に有効だからです。

`drilldown_calc_types` のデフォルト値は `NONE` です。これは、 `COUNT` だけが有効になっているという意味です。なぜなら、 `NONE` は単に無視されて、 `COUNT` は常に有効だからです。

#### 7.3.57.4.8.8. `drilldown_calc_target`

Added in version 6.0.3.

drilldown_calc_types の計算対象のカラムを指定します。

drilldown_calc_types で `MAX` のように計算対象のカラムが必要な計算タイプを指定したにも関わらず `drilldown_calc_target` を省略すると、計算結果は常に `0` になります。

`--drilldown_calc_target n_likes` というように1つのカラム名だけしか指定できません。 `--drilldown_calc_target _key,n_likes` というように複数のカラムを指定することはできません。

`--drilldown_calc_target reference_column.nested_reference_column.value` というように「 `.` 」でつなげることで対象レコードから参照している値を使うことができます。

`drilldown_calc_target` の使い方は drilldown_calc_types を参照してください。

`drilldown_calc_target` のデフォルト値は `null` です。これは計算対象カラムは何も指定されていないということです。

#### 7.3.57.4.8.9. `drilldown_filter`

Added in version 6.0.3.

ドリルダウン結果に対するフィルター条件を指定します。

構文は スクリプト構文 です。これは filter と同じです。

以下は1回しか出現していないタグを除く例です。

実行例:

    select Entries \
      --limit -1 \
      --output_columns _id,tag \
      --drilldown tag \
      --drilldown_filter '_nsubrecs > 1' \
      --drilldown_output_columns _key,_nsubrecs
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1,
    #         "Hello"
    #       ],
    #       [
    #         2,
    #         "Groonga"
    #       ],
    #       [
    #         3,
    #         "Groonga"
    #       ],
    #       [
    #         4,
    #         "Senna"
    #       ],
    #       [
    #         5,
    #         "Senna"
    #       ]
    #     ],
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Groonga",
    #         2
    #       ],
    #       [
    #         "Senna",
    #         2
    #       ]
    #     ]
    #   ]
    # ]

#### 7.3.57.4.8.10. `drilldown_max_n_target_records`

Added in version 12.0.0.

ドリルダウン対象のテーブル（フィルター結果）の中のうち最大で何レコードをドリルダウンに使うかを指定します。もし、フィルター結果のレコード数が指定した値より大きかったらフィルターした結果内のいくつかのレコードはドリルダウンには使われません。

指定した値が負の場合は limit と同じように処理されます。たとえば、 `-1` はすべてのレコードを使います。デフォルト値は `-1` です。つまり、デフォルトではフィルター結果のすべてのレコードを使ってドリルダウンを実行します。

この機能はフィルター結果が非常に大きくなるかもしれない場合に有用です。大きなフィルター結果に対するドリルダウンは遅くなることがあります。この機能を使うことでドリルダウンに使うレコード数を制限できます。

以下はドリルダウンに使う最大レコード数を制限する例です。最後の2レコード（ `{"_id": 4, "tag": "Senna"}` と `{"_id": 5, "tag": "Senna"}` ）は使われていません。

実行例:

    select Entries \
      --limit -1 \
      --output_columns _id,tag \
      --drilldown tag \
      --drilldown_max_n_target_records 3
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1,
    #         "Hello"
    #       ],
    #       [
    #         2,
    #         "Groonga"
    #       ],
    #       [
    #         3,
    #         "Groonga"
    #       ],
    #       [
    #         4,
    #         "Senna"
    #       ],
    #       [
    #         5,
    #         "Senna"
    #       ]
    #     ],
    #     [
    #       [
    #         2
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "_nsubrecs",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Hello",
    #         1
    #       ],
    #       [
    #         "Groonga",
    #         2
    #       ]
    #     ]
    #   ]
    # ]

### 7.3.57.4.9. 高度なドリルダウン関連のパラメーター

Added in version 4.0.8.

drilldown に複数のグループキーを指定することで複数のドリルダウン結果を取得できます。しかし、すべてのドリルダウンで同じ設定を使う必要があります。例えば、すべてのドリルダウンで同じ drilldown_output_columns の値が使われます。

以下の引数を使うことで、各ドリルダウンで別々の設定を使うことができます。

> - `drilldowns[${LABEL}].keys`

> - `drilldowns[${LABEL}].table`

> - `drilldowns[${LABEL}].sort_keys`

> - `drilldowns[${LABEL}].output_columns`

> - `drilldowns[${LABEL}].offset`

> - `drilldowns[${LABEL}].limit`

> - `drilldowns[${LABEL}].calc_types`

> - `drilldowns[${LABEL}].calc_target`

> - `drilldowns[${LABEL}].filter`

> - `drilldowns[${LABEL}].max_n_target_records`

> - `drilldowns[${LABEL}].key_vector_expansion`

> - `drilldowns[${LABEL}].columns[${NAME}].stage=null`

> - `drilldowns[${LABEL}].columns[${NAME}].flags=COLUMN_SCALAR`

> - `drilldowns[${LABEL}].columns[${NAME}].type=null`

> - `drilldowns[${LABEL}].columns[${NAME}].value=null`

> - `drilldowns[${LABEL}].columns[${NAME}].window.sort_keys=null`

> - `drilldowns[${LABEL}].columns[${NAME}].window.group_keys=null`

`${LABEL}` は変数です。 `${LABEL}` には次の文字を使うことができます。

> - アルファベット

> - 数字

> - `.`

> - `_`

`${NAME}` は変数です。 `${NAME}` には次の文字を使うことができます。

> - アルファベット

> - 数字

> - `_`

注釈

他の文字も使えますが、これらの文字だけを使ってください。

同じ `${LABEL}` の値を持つ引数は同じグループになります。1つのドリルダウンで同じグループの引数を一緒に使います。

例えば、以下の引数は2つのグループにわかれます。

> - `--drilldowns[label1].keys _key`

> - `--drilldowns[label1].output_columns _nsubrecs`

> - `--drilldowns[label2].keys tag`

> - `--drilldowns[label2].output_columns _key,_nsubrecs`

`drilldowns[label1].keys` と `drilldowns[label1].output_columns` が同じグループです。 `drilldowns[label2].keys` と `drilldowns[label2].output_columns` は別のグループです。

`label1` グループでは、グループキーとして `_key` を使って、出力カラムとして `_nsubrecs` を使います。

`label2` グループでは、グループキーとして `tag` を使って、出力カラムとして `_key,_nsubrecs` を使います。

以下の引数の使い方は対応する `drilldown_XXX` 引数のドキュメントを参照してください。

> - `drilldowns[${LABEL}].sort_keys`: drilldown_sort_keys

> - `drilldowns[${LABEL}].offset`: drilldown_offset

> - `drilldowns[${LABEL}].limit`: drilldown_limit

> - `drilldowns[${LABEL}].calc_types`: drilldown_calc_types

> - `drilldowns[${LABEL}].calc_target`: drilldown_calc_target

> - `drilldowns[${LABEL}].filter`: drilldown_filter

> - `drilldowns[${LABEL}].max_n_target_records`: drilldown_max_n_target_records

以下の引数の使い方は対応する `columns[${NAME}].XXX` 引数のドキュメントを参照してください。

> - `drilldowns[${LABEL}].columns[${NAME}].flags=COLUMN_SCALAR`: columns[${NAME}].flags

> - `drilldowns[${LABEL}].columns[${NAME}].type=null`: columns[${NAME}].type

> - `drilldowns[${LABEL}].columns[${NAME}].value=null`: columns[${NAME}].value

> - `drilldowns[${LABEL}].columns[${NAME}].window.sort_keys=null`: columns[${NAME}].window.sort_keys

> - `drilldowns[${LABEL}].columns[${NAME}].window.group_keys=null`: columns[${NAME}].window.group_keys

以下の引数は追加の説明が必要です。

> - `drilldowns[${LABEL}].keys`

> - `drilldowns[${LABEL}].table`

> - `drilldowns[${LABEL}].output_columns`

> - `drilldowns[${LABEL}].columns[${NAME}].stage=null`

出力フォーマットは少し違います。これも追加の説明が必要です。

#### 7.3.57.4.9.1. `drilldowns[${LABEL}].keys`

Added in version 4.0.8.

drilldown は複数のキーを指定して複数のドリルダウンを指定できます。しかし、1つのドリルダウンに複数のキーを指定することはできません。

`drilldowns[${LABEL}].keys` は複数のキーを指定して複数のドリルダウンを指定することはできません。しかし、1つのドリルダウンに複数のキーを指定することができます。

複数のキーを「`,` 」区切りで指定します。

以下は `tag` カラムと `n_likes` カラムの値を使った複数キーでのグループ化の例です。

実行例:

    select Entries \
      --limit -1 \
      --output_columns tag,n_likes \
      --drilldowns[tag.n_likes].keys tag,n_likes \
      --drilldowns[tag.n_likes].output_columns _value.tag,_value.n_likes,_nsubrecs
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "tag",
    #           "ShortText"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         "Hello",
    #         5
    #       ],
    #       [
    #         "Groonga",
    #         10
    #       ],
    #       [
    #         "Groonga",
    #         15
    #       ],
    #       [
    #         "Senna",
    #         3
    #       ],
    #       [
    #         "Senna",
    #         3
    #       ]
    #     ],
    #     {
    #       "tag.n_likes": [
    #         [
    #           4
    #         ],
    #         [
    #           [
    #             "tag",
    #             "ShortText"
    #           ],
    #           [
    #             "n_likes",
    #             "UInt32"
    #           ],
    #           [
    #             "_nsubrecs",
    #             "Int32"
    #           ]
    #         ],
    #         [
    #           "Hello",
    #           5,
    #           1
    #         ],
    #         [
    #           "Groonga",
    #           10,
    #           1
    #         ],
    #         [
    #           "Groonga",
    #           15,
    #           1
    #         ],
    #         [
    #           "Senna",
    #           3,
    #           2
    #         ]
    #       ]
    #     }
    #   ]
    # ]

`tag.n_likes` はドリルダウン引数グループのラベルです。グループ化に使ったそれぞれのキーを参照するときは drilldowns[${LABEL}].output_columns で `_value.${KEY_NAME}` という構文を使います。 `${KEY_NAME}` にはグループキーを指定したときに使ったカラム名を使います。この場合は `${KEY_NAME}` に `tag` と `n_keys` を使います。

`--drilldowns[tag].keys tag` のように `drilldowns[${LABEL}].keys` にキーを1つだけしか指定していない場合は `_value.${KEY_NAME}` 構文を使うことはできません。この場合は `_key` を使ってください。これは、 drilldown_output_columns と同じルールです。

#### 7.3.57.4.9.2. `drilldowns[${LABEL}].table`

Added in version 6.0.2.

他の `drilldowns` または `slices` の `${LABLE}` を指定します。

指定した `${LABLE}` の結果をドリルダウンします。つまり、このパラメータを使うと多段ドリルダウンができます。

以下は、多段ドリルダウンを行う例です。最初に `tag` でドリルダウンし、次にそのドリルダウン結果を `category` でドリルダウンしたものが最終的な結果です。

実行例:

    table_create NestedDrilldownTags TABLE_PAT_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create NestedDrilldownTags category COLUMN_SCALAR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    table_create NestedDrilldownMemos TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create NestedDrilldownMemos tag COLUMN_SCALAR NestedDrilldownTags
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table NestedDrilldownMemos
    [
    {"_key": "Groonga is fast!", "tag": "Groonga"},
    {"_key": "Groonga sticker!", "tag": "Groonga"},
    {"_key": "Mroonga sticker!", "tag": "Mroonga"},
    {"_key": "Rroonga is fast!", "tag": "Rroonga"}
    ]
    # [[0,1337566253.89858,0.000355720520019531],4]
    load --table NestedDrilldownTags
    [
    {"_key": "Groonga", "category": "C/C++"},
    {"_key": "Mroonga", "category": "C/C++"},
    {"_key": "PGroonga", "category": "C/C++"},
    {"_key": "Rroonga", "category": "Ruby"}
    ]
    # [[0,1337566253.89858,0.000355720520019531],4]
    select NestedDrilldownMemos \
      --drilldowns[Tag].keys tag \
      --drilldowns[Tag].output_columns _key \
      --drilldowns[Category].table Tag \
      --drilldowns[Category].keys category \
      --drilldowns[Category].output_columns _key,_nsubrecs
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         4
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "tag",
    #           "NestedDrilldownTags"
    #         ]
    #       ],
    #       [
    #         1,
    #         "Groonga is fast!",
    #         "Groonga"
    #       ],
    #       [
    #         2,
    #         "Groonga sticker!",
    #         "Groonga"
    #       ],
    #       [
    #         3,
    #         "Mroonga sticker!",
    #         "Mroonga"
    #       ],
    #       [
    #         4,
    #         "Rroonga is fast!",
    #         "Rroonga"
    #       ]
    #     ],
    #     {
    #       "Tag": [
    #         [
    #           3
    #         ],
    #         [
    #           [
    #             "_key",
    #             "ShortText"
    #           ]
    #         ],
    #         [
    #           "Groonga"
    #         ],
    #         [
    #           "Mroonga"
    #         ],
    #         [
    #           "Rroonga"
    #         ]
    #       ],
    #       "Category": [
    #         [
    #           2
    #         ],
    #         [
    #           [
    #             "_key",
    #             "ShortText"
    #           ],
    #           [
    #             "_nsubrecs",
    #             "Int32"
    #           ]
    #         ],
    #         [
    #           "C/C++",
    #           2
    #         ],
    #         [
    #           "Ruby",
    #           1
    #         ]
    #       ]
    #     }
    #   ]
    # ]

この例のスキーマでは、 `NestedDrilldownMemo` テーブルに `tag` カラムを作成し、 `NestedDrilldownTags` テーブルに `category` カラムを作成しています。

`Tag` は `NestedDrilldownMemos` を `tag` でドリルダウンしています。したがって、 `Tag` の結果には `Groonga` 、 `Mroonga` および `Rroonga` が1件ずつ含まれています。そして `Category` は `Tag` を `category` でドリルダウンしています。したがって、 `Category` の結果には `C/C++` が2件、 `Ruby` が1件含まれています。

#### 7.3.57.4.9.3. `drilldowns[${LABEL}].key_vector_expansion`

Added in version 12.1.1.

ドリルダウン対象のキーがベクターのときの、キーの展開方法を指定します。現状は `NONE` または `POWER_SET` が指定可能です。

ドリルダウン対象のキーが1つの場合にのみ使用可能です。キーが2つ以上の場合は無視されます。

##### 7.3.57.4.9.3.1. `NONE`

`key_vector_expansion` に何も指定しない場合と同じ動作です。

キーを展開しません。ベクター内の各要素がそれぞれキーとなります。

以下は `Groonga` 、 `Mroonga` 、 `PGroonga` という３つのタグに対して、これらのタグの登場回数を集計する例です。

実行例:

    table_create NoneExpantionDrilldownMemos TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create NoneExpantionDrilldownMemos tags COLUMN_VECTOR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table NoneExpantionDrilldownMemos
    [
    {"_key": "Groonga is fast!", "tags": ["Groonga"]},
    {"_key": "Mroonga uses Groonga!", "tags": ["Groonga", "Mroonga"]},
    {"_key": "PGroonga uses Groonga!", "tags": ["Groonga", "PGroonga"]},
    {"_key": "Mroonga and PGroonga are Groonga family", "tags": ["Groonga", "Mroonga", "PGroonga"]}
    ]
    # [[0,1337566253.89858,0.000355720520019531],4]
    select NoneExpantionDrilldownMemos \
      --drilldowns[tags].keys tags \
      --drilldowns[tags].key_vector_expansion NONE \
      --drilldowns[tags].columns[none_expantion].stage initial \
      --drilldowns[tags].columns[none_expantion].value _key \
      --drilldowns[tags].columns[none_expantion].flags COLUMN_VECTOR \
      --drilldowns[tags].sort_keys 'none_expantion' \
      --drilldowns[tags].output_columns 'none_expantion, _nsubrecs' \
      --limit 0
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         4
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "tags",
    #           "ShortText"
    #         ]
    #       ]
    #     ],
    #     {
    #       "tags": [
    #         [
    #           3
    #         ],
    #         [
    #           [
    #             "none_expantion",
    #             "Text"
    #           ],
    #           [
    #             "_nsubrecs",
    #             "Int32"
    #           ]
    #         ],
    #         [
    #           [
    #             "Groonga"
    #           ],
    #           4
    #         ],
    #         [
    #           [
    #             "Mroonga"
    #           ],
    #           2
    #         ],
    #         [
    #           [
    #             "PGroonga"
    #           ],
    #           2
    #         ]
    #       ]
    #     }
    #   ]
    # ]

実行結果から以下のことがわかります。

タグ | 登場回数 ( `_nsubrecs` )
`Groonga` | 4
`Mroonga` | 2
`PGroonga` | 2

##### 7.3.57.4.9.3.2. `POWER_SET`

ベクターをべき集合に展開して集計します。 このとき、対象のベクターを多重集合とみなします。 多重集合とみなすので、同じ値の要素が複数ある場合、それぞれ別の要素とみなします。

ベクター `[A, B, C]` を例に考えます。この場合、対象となる集合は `{A, B, C}` です。 べき集合は、集合のすべての部分集合の集合なので、まず、 `{A, B, C}` のすべての部分集合を以下に示します。 ただし、Groongaは要素数が0の集合（空集合）は使いません。ドリルダウン結果に使うには有益ではないからです。 空集合も使ったほうがよいユースケースがある場合は issue で報告してください。

- 要素数1の部分集合

  - `{A}`

  - `{B}`

  - `{C}`

- 要素数2の部分集合

  - `{A, B}`

  - `{B, C}`

  - `{A, C}`

- 要素数3の部分集合

  - `{A, B, C}`

以上が `{A, B, C}` のすべての部分集合です。 べき集合は、これらの部分集合の集合なので、 `{{A}, {B}, {C}, {A, B}, {B, C}, {A, C}, {A, B, C}}` がこのベクターのべき集合となります。

`POWER_SET` は、この `{{A}, {B}, {C}, {A, B}, {B, C}, {A, C}, {A, B, C}}` の各部分集合で集計します。

例として、 `[A, B, C]` と `[B, C, D]` をべき集合で集計する場合を考えます。

`[A, B, C]` のべき集合は前述の通り `{{A}, {B}, {C}, {A, B}, {B, C}, {A, C}, {A, B, C}}` で、 `[B, C, D]` のべき集合は同様に `{{B}, {C}, {D}, {B, C}, {C, D}, {B, D}, {B, C, D}}` となります。

この各べき集合で登場した部分集合ごとに集計します。登場回数を集計した場合は以下の結果になります。

部分集合 | 登場回数 ( `_nsubrecs` )
`{A}` | 1
`{B}` | 2
`{C}` | 2
`{D}` | 1
`{A, B}` | 1
`{A, C}` | 1
`{B, C}` | 2
`{B, D}` | 1
`{C, D}` | 1
`{A, B, C}` | 1
`{B, C, D}` | 1

この集計方法は、例えばタグの登場回数と、タグの組み合わせの登場回数を一度に集計したい場合に便利です。

以下は `Groonga` 、 `Mroonga` 、 `PGroonga` という３つのタグに対して、これらのタグの登場回数と、 これらの組み合わせの登場回数を集計する例です。

実行例:

    table_create PowerSetDrilldownMemos TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create PowerSetDrilldownMemos tags COLUMN_VECTOR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table PowerSetDrilldownMemos
    [
    {"_key": "Groonga is fast!", "tags": ["Groonga"]},
    {"_key": "Mroonga uses Groonga!", "tags": ["Groonga", "Mroonga"]},
    {"_key": "PGroonga uses Groonga!", "tags": ["Groonga", "PGroonga"]},
    {"_key": "Mroonga and PGroonga are Groonga family", "tags": ["Groonga", "Mroonga", "PGroonga"]}
    ]
    # [[0,1337566253.89858,0.000355720520019531],4]
    select PowerSetDrilldownMemos \
      --drilldowns[tags].keys tags \
      --drilldowns[tags].key_vector_expansion POWER_SET \
      --drilldowns[tags].columns[power_set].stage initial \
      --drilldowns[tags].columns[power_set].value _key \
      --drilldowns[tags].columns[power_set].flags COLUMN_VECTOR \
      --drilldowns[tags].sort_keys 'power_set' \
      --drilldowns[tags].output_columns 'power_set, _nsubrecs' \
      --limit 0
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         4
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "tags",
    #           "ShortText"
    #         ]
    #       ]
    #     ],
    #     {
    #       "tags": [
    #         [
    #           7
    #         ],
    #         [
    #           [
    #             "power_set",
    #             "Text"
    #           ],
    #           [
    #             "_nsubrecs",
    #             "Int32"
    #           ]
    #         ],
    #         [
    #           [
    #             "Groonga"
    #           ],
    #           4
    #         ],
    #         [
    #           [
    #             "Mroonga"
    #           ],
    #           2
    #         ],
    #         [
    #           [
    #             "PGroonga"
    #           ],
    #           2
    #         ],
    #         [
    #           [
    #             "Groonga",
    #             "Mroonga"
    #           ],
    #           2
    #         ],
    #         [
    #           [
    #             "Groonga",
    #             "PGroonga"
    #           ],
    #           2
    #         ],
    #         [
    #           [
    #             "Mroonga",
    #             "PGroonga"
    #           ],
    #           1
    #         ],
    #         [
    #           [
    #             "Groonga",
    #             "Mroonga",
    #             "PGroonga"
    #           ],
    #           1
    #         ]
    #       ]
    #     }
    #   ]
    # ]

この集計結果から、以下のことがわかります。

タグ | 登場回数 ( `_nsubrecs` )
`Groonga` | 4
`Mroonga` | 2
`PGroonga` | 2
`Groonga` かつ `Mroonga` | 2
`Groonga` かつ `PGroonga` | 2
`Mroonga` かつ `PGroonga` | 1
`Groonga` かつ `Mroonga` かつ `PGroonga` | 1

この結果から、どのタグの組み合わせがよく使われているかといった相関関係を分析できます。 例えば、 `Groonga` と `Mroonga` が同時に使われている回数は2回で、そのうち更に `PGroonga` が同時に使われている回数が1回、というような分析ができます。

#### 7.3.57.4.9.4. `drilldowns[${LABEL}].output_columns`

Added in version 4.0.8.

`drilldowns[${LABEL}].output_columns` はほとんど drilldown_output_columns と同じです。 drilldown_output_columns と `drilldowns[${LABEL}].output_columns` の違いはグループキーの参照方法です。

drilldown_output_columns はグループキーを参照するために `_key` 擬似カラム を使います。 `drilldowns[${LABEL}].output_columns` も drilldowns[${LABEL}].keys で1つだけしかグループキーを指定していない場合は、グループキーを参照するために `_key` 擬似カラム を使います。

以下は1つだけ指定したグループキーを参照するために `_key` 擬似カラム を使う例です。

実行例:

    select Entries \
      --limit 0 \
      --output_columns _id \
      --drilldowns[tag.n_likes].keys tag \
      --drilldowns[tag.n_likes].output_columns _key
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ]
    #       ]
    #     ],
    #     {
    #       "tag.n_likes": [
    #         [
    #           3
    #         ],
    #         [
    #           [
    #             "_key",
    #             "ShortText"
    #           ]
    #         ],
    #         [
    #           "Hello"
    #         ],
    #         [
    #           "Groonga"
    #         ],
    #         [
    #           "Senna"
    #         ]
    #       ]
    #     }
    #   ]
    # ]

`drilldownss[${LABEL}].output_columns` で各グループキーを参照するために `_key` 擬似カラム を使うことはできません。 `_value.${KEY_NAME}` 構文を使います。 `${KEY_NAME}` には drilldowns[${LABEL}].keys でグループキーを指定するために使ったカラム名を使います。

以下は複数のグループキーを使ったときに `_value.${KEY_NAME}` 構文でそれぞれのグループキーを参照する例です。

実行例:

    select Entries \
      --limit 0 \
      --output_columns _id \
      --drilldowns[tag.n_likes].keys tag,n_likes \
      --drilldowns[tag.n_likes].output_columns _value.tag,_value.n_likes
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ]
    #       ]
    #     ],
    #     {
    #       "tag.n_likes": [
    #         [
    #           4
    #         ],
    #         [
    #           [
    #             "tag",
    #             "ShortText"
    #           ],
    #           [
    #             "n_likes",
    #             "UInt32"
    #           ]
    #         ],
    #         [
    #           "Hello",
    #           5
    #         ],
    #         [
    #           "Groonga",
    #           10
    #         ],
    #         [
    #           "Groonga",
    #           15
    #         ],
    #         [
    #           "Senna",
    #           3
    #         ]
    #       ]
    #     }
    #   ]
    # ]

Tip

どうして `_value.${KEY_NAME}` 構文なの？

これは実装よりの情報です。

`_key` はベクターの値です。このベクターの値はすべてのグループキーから成ります。 `drilldowns[${LABEL}].output_columns` で `_key` を参照するとこのベクターの値のバイト列を確認することができます。

drilldowns[${LABEL}].keys に複数のグループキーを指定したとき、各グループの値を参照するために `_value` にグループのレコードが1つだけ保存されています。そのため、各グループキーを参照するために `_value.${KEY_NAME}` 構文を使えます。

一方、 drilldowns[${LABEL}].keys に1つのグループキーしか指定していない場合は、 `_value` にグループのレコードを保存しません。そのため、 `_value.${KEY_NAME}` 構文でグループキーを参照できません。

#### 7.3.57.4.9.5. `drilldowns[${LABEL}].columns[${NAME}].stage`

Added in version 6.0.5.

どのタイミング（どのステージ）で動的カラムを作るかを指定します。動的カラムを作る場合はこのパラメーターは必須です。

指定可能なステージは以下の通りです。

名前 | 説明
--- | ---
`initial` | 最初に動的カラムを作成します。
`filtered` | `drilldowns[${LABEL}].filter` を評価してから動的カラムを作成します。
`output` | drilldowns[${LABEL}].output_columns を評価する前に動的カラムを作成します。

注釈

`filtered` ステージと `output` ステージは10.0.3以降で使用できます。

以下は動的カラム作成タイミング入りの各ドリルダウンの処理の流れです。できるだけ後のステージを選ぶべきです。

> 1. drilldowns[${LABEL}].keys 、 `drilldowns[${LABEL}].calc_types` 、 `drilldowns[${LABEL}].calc_target` を評価します。

> 2. `initial` ステージの動的カラムを作ります。すべてのドリルダウン結果レコードはこの動的カラムを持ちます。

> 3. `drilldowns[${LABEL}].filter` を評価します。 `initial` ステージで作った動的カラムを使えます。

> 4. `filtered` ステージの動的カラムを作ります。フィルター後のレコードだけがこの動的カラムを持ちます。

> 5. `drilldowns[${LABEL}].sort_keys` 、 `drilldowns[${LABEL}].offset` 、 `drilldowns[${LABEL}].limit` を評価します。 `initial` と`filtered` ステージで作った動的カラムを使えます。

> 6. `output` ステージの動的カラムを作ります。最大 `drilldowns[${LABEL}].limit` 件のレコードだけがこの動的カラムを持ちます。

> 7. drilldowns[${LABEL}].output_columns を評価します。 `initial` ステージと `filtered` ステージと `output` ステージで作った動的カラムを使えます。

以下は `drilldowns[${LABEL}].columns[${NAME}].stage` の使用例です。この例では `initial` ステージで `is_popular` カラムを作っています。作成した `is_popular` カラムは `drilldowns[${LABEL}].filter` と `drilldowns[${LABEL}].output_columns` で使えます。

実行例:

    select Entries \
      --drilldowns[tag].keys tag \
      --drilldowns[tag].columns[is_popular].stage initial \
      --drilldowns[tag].columns[is_popular].type Bool \
      --drilldowns[tag].columns[is_popular].value '_nsubrecs > 1' \
      --drilldowns[tag].filter is_popular \
      --drilldowns[tag].output_columns _key,is_popular,_nsubrecs
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1,
    #         "The first post!",
    #         "Welcome! This is my first post!",
    #         5,
    #         "Hello"
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ],
    #       [
    #         4,
    #         "Good-bye Senna",
    #         "I migrated all Senna system!",
    #         3,
    #         "Senna"
    #       ],
    #       [
    #         5,
    #         "Good-bye Tritonn",
    #         "I also migrated all Tritonn system!",
    #         3,
    #         "Senna"
    #       ]
    #     ],
    #     {
    #       "tag": [
    #         [
    #           2
    #         ],
    #         [
    #           [
    #             "_key",
    #             "ShortText"
    #           ],
    #           [
    #             "is_popular",
    #             "Bool"
    #           ],
    #           [
    #             "_nsubrecs",
    #             "Int32"
    #           ]
    #         ],
    #         [
    #           "Groonga",
    #           true,
    #           2
    #         ],
    #         [
    #           "Senna",
    #           true,
    #           2
    #         ]
    #       ]
    #     }
    #   ]
    # ]

Added in version 4.0.8.

#### 7.3.57.4.9.6. `drilldowns[${LABEL}]` スタイルの出力フォーマット

drilldown と drilldowns[${LABEL}].keys には出力フォーマットに違いがあります。 drilldown は複数のドリルダウン結果を出力するために配列を使います。 drilldowns[${LABEL}].keys は「ラベル」と「ドリルダウン結果」のペアの集まりを使います。

drilldown の出力フォーマットは以下の通りです:

    [
      HEADER,
      [
        SEARCH_RESULT,
        DRILLDOWN_RESULT1,
        DRILLDOWN_RESULT2,
        ...
      ]
    ]

drilldowns[${LABEL}].keys の出力フォーマットは以下の通りです:

    [
      HEADER,
      [
        SEARCH_RESULT,
        {
          "LABEL1": DRILLDOWN_RESULT1,
          "LABEL2": DRILLDOWN_RESULT2,
          ...
        }
      ]
    ]

### 7.3.57.4.10. スライス関連の引数

Added in version 6.0.3.

このセクションではスライス関連のパラメーターについて説明します。

TODO

スライスのパラメーターは以下の通りです。

名前 | 必須
--- | ---
`--slices[${LABEL}].match_columns` | 省略可能
`--slices[${LABEL}].query` | `--slices[${LABEL}].filter` を指定していないときは必須です。
`--slices[${LABEL}].filter` | `--slices[${LABEL}].query` を指定していないときは必須です。
`--slices[${LABEL}].query_expander` | 省略可能
`--slices[${LABEL}].query_flags` | 省略可能
`--slices[${LABEL}].sort_keys` | 省略可能
`--slices[${LABEL}].output_columns` | 省略可能
`--slices[${LABEL}].offset` | 省略可能
`--slices[${LABEL}].limit` | 省略可能

#### 7.3.57.4.10.1. `slices[${LABEL}].match_columns`

TODO

#### 7.3.57.4.10.2. `slices[${LABEL}].query`

TODO

#### 7.3.57.4.10.3. `slices[${LABEL}].filter`

TODO

#### 7.3.57.4.10.4. `slices[${LABEL}].query_expander`

TODO

#### 7.3.57.4.10.5. `slices[${LABEL}].query_flags`

TODO

#### 7.3.57.4.10.6. `slices[${LABEL}].sort_keys`

TODO

#### 7.3.57.4.10.7. `slices[${LABEL}].output_columns`

TODO

#### 7.3.57.4.10.8. `slices[${LABEL}].offset`

TODO

#### 7.3.57.4.10.9. `slices[${LABEL}].limit`

TODO

### 7.3.57.4.11. キャッシュ関連の引数

#### 7.3.57.4.11.1. `cache`

このクエリーの結果をキャッシュするかどうかを指定します。

このクエリーの結果がキャッシュしてあると、次に同じクエリーを実行するときはキャッシュを使って高速にレスポンスを返すことができます。

これは既存のキャッシュされた結果を使うかどうかを指定するものではありません。

指定可能な値は以下の通りです。

値 | 説明
--- | ---
`no` | このクエリーの出力をキャッシュしない。
`yes` | このクエリーの出力をキャッシュする。デフォルト値。

このクエリーの結果をキャッシュしないようにする例です。

実行例:

    select Entries --cache no
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1,
    #         "The first post!",
    #         "Welcome! This is my first post!",
    #         5,
    #         "Hello"
    #       ],
    #       [
    #         2,
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         10,
    #         "Groonga"
    #       ],
    #       [
    #         3,
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         15,
    #         "Groonga"
    #       ],
    #       [
    #         4,
    #         "Good-bye Senna",
    #         "I migrated all Senna system!",
    #         3,
    #         "Senna"
    #       ],
    #       [
    #         5,
    #         "Good-bye Tritonn",
    #         "I also migrated all Tritonn system!",
    #         3,
    #         "Senna"
    #       ]
    #     ]
    #   ]
    # ]

デフォルト値は `yes` です。

### 7.3.57.4.12. スコアー関連の引数

スコアー関連のパラメーターは `adjuster` だけです。

#### 7.3.57.4.12.1. `adjuster`

1つ以上のスコアー調整式（score adjust expression）を指定します。 `adjuster` は `query` または `filter` と一緒に使います。検索しないリクエストでは `adjuster` は動きません。

`adjuster` を使うと特定のレコードのスコアーを増やすことができます。重要なレコードに高いスコアーをつけるために `adjuster` を使えます。

例えば、 `groonga` タグがついたレコードのスコアーを増やすために `adjuster` を使えます。

以下が構文です:

    --adjuster "SCORE_ADJUST_EXPRESSION1 + SCORE_ADJUST_EXPRESSION2 + ..."

以下が `SCORE_ADJUST_EXPRESSION` の構文です:

    COLUMN @ "KEYWORD" * FACTOR

以下のことに注意してください:

> - `COLUMN` にはインデックスが張っていないといけません。

> - `"KEYWORD"` は文字列でないといけません。

> - `FACTOR` は正の整数でないといけません。

以下は1つだけ `SCORE_ADJUST_EXPRESSION` を使った `adjuster` の使用例です。

実行例:

    select Entries \
      --filter true \
      --adjuster 'content @ "groonga" * 5' \
      --output_columns _key,content,_score
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "The first post!",
    #         "Welcome! This is my first post!",
    #         1
    #       ],
    #       [
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         6
    #       ],
    #       [
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         1
    #       ],
    #       [
    #         "Good-bye Senna",
    #         "I migrated all Senna system!",
    #         1
    #       ],
    #       [
    #         "Good-bye Tritonn",
    #         "I also migrated all Tritonn system!",
    #         1
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドはすべてのレコードにマッチします。それから、 `adjuster` を適用します。このアジャスターは `Entries.content` カラムの中に `"groonga"` を含むレコードのスコアーを5増やします。 `Entries.content` カラムに `"groonga"` が含まれているレコードは1つだけです。 `"Groonga"` というキーのレコードです。このレコードのスコアーは6（ `= 1 + 5` ）になります。

`FACTOR` は省略できます。 `FACTOR` を省略すると、1を指定したとみなします。

`FACTOR` を省略した `adjuster` の使用例です。

実行例:

    select Entries \
      --filter true \
      --adjuster 'content @ "groonga"' \
      --output_columns _key,content,_score
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "The first post!",
    #         "Welcome! This is my first post!",
    #         1
    #       ],
    #       [
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         2
    #       ],
    #       [
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         1
    #       ],
    #       [
    #         "Good-bye Senna",
    #         "I migrated all Senna system!",
    #         1
    #       ],
    #       [
    #         "Good-bye Tritonn",
    #         "I also migrated all Tritonn system!",
    #         1
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドの `adjuster` は `FACTOR` がありません。そのため、係数は1になります。 `Entries.content` カラムに `"groonga"` を含むレコードは1つだけです。キーが `"Groonga"` のレコードです。このレコードのスコアーは2（ `= 1 + 1` ）になります。

複数の `SCORE_ADJUST_EXPRESSION` を使った `adjuster` の使用例です。

実行例:

    select Entries \
      --filter true \
      --adjuster 'content @ "groonga" * 5 + content @ "started" * 3' \
      --output_columns _key,content,_score
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "content",
    #           "Text"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "The first post!",
    #         "Welcome! This is my first post!",
    #         1
    #       ],
    #       [
    #         "Groonga",
    #         "I started to use Groonga. It's very fast!",
    #         9
    #       ],
    #       [
    #         "Mroonga",
    #         "I also started to use Mroonga. It's also very fast! Really fast!",
    #         4
    #       ],
    #       [
    #         "Good-bye Senna",
    #         "I migrated all Senna system!",
    #         1
    #       ],
    #       [
    #         "Good-bye Tritonn",
    #         "I also migrated all Tritonn system!",
    #         1
    #       ]
    #     ]
    #   ]
    # ]

この `select` コマンドの `adjuster` には2つの `SCORE_ADJUST_EXPRESSION` があります。最終的なスコアーの増分はすこれらの `SCORE_ADJUST_EXPRESSION` のスコアーの合計になります。この `select` コマンドのすべての `SCORE_ADJUST_EXPRESSION` はキーが `"Groonga"` のレコードに適用されます。そのため、このレコードの最終的なスコアーの増分はすべての `SCORE_ADJUST_EXPRESSION` の合計になります。

最初の `SCORE_ADJUST_EXPRESSION` は `content @ "groonga" * 5` です。これは、スコアーを5増やします。

2番目の `SCORE_ADJUST_EXPRESSION` は `content @ "started" * 3` です。これはスコアーを3増やします。

最終的なスコアーの増分は9（ `= 1 + 5 + 3` ）です。

1つの `SCORE_ADJUST_EXPRESSION` は `"KEYWORD"` に対して1つの係数を持ちます。これは、 `"KEYWORD"` を持つすべてのレコードでスコアーの増加分は同じということです。 `"KEYWORD"` を持つそれぞれのレコード毎にスコアーの増加分を変えることができます。これは検索スコアーをチューニングするときに便利です。詳細は 重み付きベクターカラム を参照してください。

## 7.3.57.5. 戻り値

このコマンドは以下のフォーマットのレスポンスを返します。:

    [
      HEADER,
      [
        SEARCH_RESULT,
        DRILLDOWN_RESULT_1,
        DRILLDOWN_RESULT_2,
        ...,
        DRILLDOWN_RESULT_N
      ]
    ]

このコマンドが失敗すると、 `HEADER` にエラーの詳細が含まれます。

`HEADER` については 出力形式 を参照してください。

0個以上の `DRILLDOWN_RESULT` があります。もし、 `drilldown` も `drilldowns[${LABEL}].keys` も指定していない場合、次のように `DRILLDOWN_RESULT` は出力されません:

    [
      HEADER,
      [
        SEARCH_RESULT
      ]
    ]

`--drilldown "_key, column1, column2"` というように `drilldown` に2つ以上のキーがある場合、複数の `DRILLDOWN_RESULT` が存在します:

    [
      HEADER,
      [
        SEARCH_RESULT,
        DRILLDOWN_RESULT_FOR_KEY,
        DRILLDOWN_RESULT_FOR_COLUMN1,
        DRILLDOWN_RESULT_FOR_COLUMN2
      ]
    ]

もし `drilldowns[${LABEL}].keys` を使っているなら、 `DRILLDOWN_RESULT` が1つだけ存在します:

    [
      HEADER,
      [
        SEARCH_RESULT,
        DRILLDOWN_RESULT_FOR_LABELED_DRILLDOWN
      ]
    ]

`DRILLDOWN_RESULT` のフォーマットは `drilldown` と `drilldowns[${LABEL}].keys` で違います。これについては後述します。

`SEARCH_RESULT` は以下のフォーマットです:

    [
      [N_HITS],
      COLUMNS,
      RECORDS
    ]

このフォーマットの具体例は 簡単な使い方 を見てください。

`N_HITS` は limit を適用する前のマッチしたレコード数です。

`COLUMNS` は output_columns で指定した出力カラムの情報を表しています。これは次のフォーマットになっています:

    [
      [COLUMN_NAME_1, COLUMN_TYPE_1],
      [COLUMN_NAME_2, COLUMN_TYPE_2],
      ...,
      [COLUMN_NAME_N, COLUMN_TYPE_N]
    ]

`COLUMNS` は1つ以上の出力カラムの情報を含んでいます。各出力カラムの情報は次の情報を含んでいます。

> - カラム名（文字列）

> - カラムの型（文字列または `null` ）

カラム名は output_columns で指定された値から抽出しています。

カラムの方はGroongaでの型名または `null` です。カラムがベクターかスカラーかの情報は持っていません。実際のカラムの値が配列かどうかで判断する必要があります。

型の詳細は データ型 を見てください。

`null` になるときはカラムの値の型を決められないときです。たとえば、 `--output_columns "snippet_html(content)"` というように output_columns の中で関数呼び出しを使ったときは `null` になります。

以下は `COLUMNS` の使用例です:

    [
      ["_id",     "UInt32"],
      ["_key",    "ShortText"],
      ["n_likes", "UInt32"],
    ]

`RECORDS` はマッチした各レコードのカラムの値を含んでいます。 `RECORDS` に含まれるレコードは offset と limit で選択されたレコードです。 `RECORDS` は次のフォーマットです:

    [
      [
        RECORD_1_COLUMN_1,
        RECORD_1_COLUMN_2,
        ...,
        RECORD_1_COLUMN_N
      ],
      [
        RECORD_2_COLUMN_1,
        RECORD_2_COLUMN_2,
        ...,
        RECORD_2_COLUMN_N
      ],
      ...
      [
        RECORD_N_COLUMN_1,
        RECORD_N_COLUMN_2,
        ...,
        RECORD_N_COLUMN_N
      ]
    ]

以下は `RECORDS` の例です:

    [
      [
        1,
        "The first post!",
        5
      ],
      [
        2,
        "Groonga",
        10
      ],
      [
        3,
        "Mroonga",
        15
      ]
    ]

`DRILLDOWN_RESULT` のフォーマットは `drilldown` と `drilldowns[${LABEL}].keys` で違います。

`drilldown` は `SEARCH_RESULT` と同じフォーマットです:

    [
      [N_HITS],
      COLUMNS,
      RECORDS
    ]

drilldown で1つ以上のキーを指定すると、 `drilldown` は1つ以上の `DRILLDOWN_RESULT` を出力します。

`drilldowns[${LABEL}].keys` は次のフォーマットを使います。複数の `drilldowns[${LABEL}].keys` は1つのオブジェクト（キーと値のペアの集合）になります:

    {
      "LABEL_1": [
        [N_HITS],
        COLUMNS,
        RECORDS
      ],
      "LABEL_2": [
        [N_HITS],
        COLUMNS,
        RECORDS
      ],
      ...,
      "LABEL_N": [
        [N_HITS],
        COLUMNS,
        RECORDS
      ]
    }

各 `drilldowns[${LABEL}].keys` は次の部分に対応します:

    "LABEL": [
      [N_HITS],
      COLUMNS,
      RECORDS
    ]

以下の値の部分は `SEARCH_RESULT` と同じフォーマットです:

    [
      [N_HITS],
      COLUMNS,
      RECORDS
    ]

`drilldownss[${LABEL}]` スタイルのドリルダウンの出力形式については drilldowns[${LABEL}] スタイルの出力フォーマット も見てください。

## 7.3.57.6. 参考

> - クエリー構文

> - スクリプト構文