`Ctrl`+`K`

# 7.3.34. `logical_range_filter`

## 7.3.34.1. 概要

バージョン 5.0.0 で追加.

`logical_range_filter` は range_filter のシャーディングバージョンです。 `logical_range_filter` は複数のテーブルからレコードを検索し、マッチしたレコードを出力します。

`logical_range_filter` は logical_select に似ています。どちらも複数のテーブルからレコードを検索し、見つかったレコードを出力します。 `logical_range_filter` は要求されたレコード数分のレコードが見つかったらそこで検索を終了します。 logical_select はすべてのレコードを検索し、必要なレコードだけ出力します。

`logical_range_filter` の方が性能面で有利ですがいくつか制約があります。

大量のレコードがマッチし、要求されているレコード数が小さい場合、 `logical_range_filter` の方が logical_select よりも速いです。

`logical_range_filter` はドリルダウンをサポートしていません。なぜなら、ドリルダウンをするためにはマッチしたレコードがすべて必要だからです。 `logical_range_filter` はマッチするレコードをすべて検索しないかもしれません。そのため、 `logical_range_filter` はドリルダウンをサポートしていません。

`logical_range_filter` はマッチしたレコードの総数を返しません。なぜなら、 `logical_range_filter` はマッチするレコードをすべて検索しないかもしれないからです。

このコマンド は `sharding` プラグインに含まれているので、 `sharding` プラグインを plugin_register する必要があります。

## 7.3.34.2. 構文

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

必須引数は2つあります。 `logical_table` と `shard_key` です。

    logical_range_filter
      logical_table
      shard_key
      [min=null]
      [min_border="include"]
      [max=null]
      [max_border="include"]
      [order="ascending"]
      [filter=null]
      [offset=0]
      [limit=10]
      [output_columns="_key, *"]
      [use_range_index=null]
      [post_filter=null]
      [sort_keys=null]

いくつか名前付き引数としてしか使えない引数があります。これらの引数を「○番目の引数」として使うことはできません。必ず名前を指定する必要があります。

名前付き引数としてしか使えない引数は次の通りです。

> - `cache=no`

バージョン 7.0.9 で追加: 以下の名前付き引数で動的カラム機能を使うことができます。

> - `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'`

## 7.3.34.3. 使い方

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

このコマンドは `sharding` プラグインに含まれているので `sharding` プラグインを登録する必要があります。

実行例:

    plugin_register sharding
    # [[0, 1337566253.89858, 0.000355720520019531], true]

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

実行例:

    table_create Entries_20150708 TABLE_HASH_KEY ShortText
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Entries_20150708 created_at COLUMN_SCALAR Time
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Entries_20150708 content COLUMN_SCALAR Text
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Entries_20150708 n_likes COLUMN_SCALAR UInt32
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Entries_20150708 tag COLUMN_SCALAR ShortText
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    table_create Entries_20150709 TABLE_HASH_KEY ShortText
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Entries_20150709 created_at COLUMN_SCALAR Time
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Entries_20150709 content COLUMN_SCALAR Text
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Entries_20150709 n_likes COLUMN_SCALAR UInt32
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Entries_20150709 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_20150708 \
      COLUMN_INDEX|WITH_POSITION Entries_20150708 _key
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Terms entries_content_index_20150708 \
      COLUMN_INDEX|WITH_POSITION Entries_20150708 content
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Terms entries_key_index_20150709 \
      COLUMN_INDEX|WITH_POSITION Entries_20150709 _key
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Terms entries_content_index_20150709 \
      COLUMN_INDEX|WITH_POSITION Entries_20150709 content
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    load --table Entries_20150708
    [
    {"_key":       "The first post!",
     "created_at": "2015/07/08 00:00:00",
     "content":    "Welcome! This is my first post!",
     "n_likes":    5,
     "tag":        "Hello"},
    {"_key":       "Groonga",
     "created_at": "2015/07/08 01:00:00",
     "content":    "I started to use Groonga. It's very fast!",
     "n_likes":    10,
     "tag":        "Groonga"},
    {"_key":       "Mroonga",
     "created_at": "2015/07/08 02:00:00",
     "content":    "I also started to use Mroonga. It's also very fast! Really fast!",
     "n_likes":    15,
     "tag":        "Groonga"}
    ]
    # [[0, 1337566253.89858, 0.000355720520019531], 3]
    load --table Entries_20150709
    [
    {"_key":       "Good-bye Senna",
     "created_at": "2015/07/09 00:00:00",
     "content":    "I migrated all Senna system!",
     "n_likes":    3,
     "tag":        "Senna"},
    {"_key":       "Good-bye Tritonn",
     "created_at": "2015/07/09 01:00:00",
     "content":    "I also migrated all Tritonn system!",
     "n_likes":    3,
     "tag":        "Senna"}
    ]
    # [[0, 1337566253.89858, 0.000355720520019531], 2]

ブログエントリー用に `Entries_20150708` と `Entries_20150709` の2つのテーブルがあります。

注釈

テーブル名には `${論理テーブル名}_${YYYYMMDD}` という命名規則を使う必要があります。この例では、 `論理テーブル名` は `Entries` で `YYYYMMDD` は `20150708` または `20150709` です。

各エントリはタイトルと作成日時と内容と「いいね！」数、タグを持っています。タイトルは `Entries_YYYYMMDD` のキーとします。作成日時は `Entries_YYYYMMDD.created_at` カラムの値とします。内容は `Entries_YYYYMMDD.content` カラムの値とします。「いいね！」数は `Entries_YYYYMMDD.n_likes` カラムの値とします。タグは `Entries_YYYYMMDD.tag` カラムの値とします。

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

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

### 7.3.34.3.1. 簡単な使い方

TODO

## 7.3.34.4. 引数

このセクションでは `logical_range_filter` の引数について説明します。

### 7.3.34.4.1. 必須引数

必須引数は二つあります。 `logical_table` と `shard_key` です。

#### 7.3.34.4.1.1. `logical_table`

論理テーブル名を指定します。これは `_YYYYMMDD` をテーブル名からのぞいたものです。実際のテーブルが `Entries_20150708` や `Entries_20150709` といったものなら、論理テーブル名は `Entries` です。

実行例:

    logical_range_filter --logical_table Entries --shard_key created_at

    # [
    #   [
    #     0,
    #     1519131606.676006,
    #     0.0006020069122314453
    #   ],
    #   [
    #     [
    #       [
    #         "_key",
    #         "ShortText"
    #       ],
    #       [
    #         "content",
    #         "Text"
    #       ],
    #       [
    #         "created_at",
    #         "Time"
    #       ],
    #       [
    #         "n_likes",
    #         "UInt32"
    #       ],
    #       [
    #         "tag",
    #         "ShortText"
    #       ]
    #     ],
    #     [
    #       "The first post!",
    #       "Welcome! This is my first post!",
    #       1436281200.0,
    #       5,
    #       "Hello"
    #     ],
    #     [
    #       "Groonga",
    #       "I started to use Groonga. It's very fast!",
    #       1436284800.0,
    #       10,
    #       "Groonga"
    #     ],
    #     [
    #       "Mroonga",
    #       "I also started to use Mroonga. It's also very fast! Really fast!",
    #       1436288400.0,
    #       15,
    #       "Groonga"
    #     ],
    #     [
    #       "Good-bye Senna",
    #       "I migrated all Senna system!",
    #       1436367600.0,
    #       3,
    #       "Senna"
    #     ],
    #     [
    #       "Good-bye Tritonn",
    #       "I also migrated all Tritonn system!",
    #       1436371200.0,
    #       3,
    #       "Senna"
    #     ]
    #   ]
    # ]

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

実行例:

    logical_range_filter --logical_table Nonexistent --shard_key created_at
    # [
    #   [
    #     -22,
    #     1519132441.586192,
    #     0.0005924701690673828,
    #     "[logical_range_filter] no shard exists: logical_table: <Nonexistent>: shard_key: <created_at>",
    #     [
    #       [
    #         "Groonga::Sharding::LogicalRangeFilterCommand::Executor.execute",
    #         "/tmp/local/lib/groonga/plugins/sharding/logical_range_filter.rb",
    #         193
    #       ]
    #     ]
    #   ]
    # ]

#### 7.3.34.4.1.2. `shard_key`

個々のテーブルで共通のキーとして扱うカラム名を指定します。

TODO: Add examples

### 7.3.34.4.2. 省略可能引数

いくつか省略可能な引数があります。

#### 7.3.34.4.2.1. `min`

`shard_key` の最小値を指定します。

TODO: Add examples

#### 7.3.34.4.2.2. `min_border`

最小値を境界値として含めるのか否かを指定します。 `include` もしくは `exclude` を指定します。

TODO: Add examples

#### 7.3.34.4.2.3. `max`

`shard_key` の最大値を指定します。

TODO: Add examples

#### 7.3.34.4.2.4. `max_border`

最大値を境界値として含めるのか否かを指定します。 `include` もしくは `exclude` を指定します。

TODO: Add examples

#### 7.3.34.4.2.5. `order`

検索結果の順序を指定します。`ascending` もしくは `descending` を指定します。

`ascending` を設定した場合は、 `shard_key` を基準に検索結果は昇順に並べられます。`descending` を設定した場合は、 `shard_key` を基準に検索結果は降順に並べられます。

実行例:

    logical_range_filter --logical_table Entries --shard_key created_at --order "descending"
    # [
    #   [
    #     0,
    #     1557403984.311448,
    #     0.0003597736358642578
    #   ],
    #   [
    #     [
    #       [
    #         "_key",
    #         "ShortText"
    #       ],
    #       [
    #         "content",
    #         "Text"
    #       ],
    #       [
    #         "created_at",
    #         "Time"
    #       ],
    #       [
    #         "n_likes",
    #         "UInt32"
    #       ],
    #       [
    #         "tag",
    #         "ShortText"
    #       ]
    #     ],
    #     [
    #       "Good-bye Tritonn",
    #       "I also migrated all Tritonn system!",
    #       1436371200,
    #       3,
    #       "Senna"
    #     ],
    #     [
    #       "Good-bye Senna",
    #       "I migrated all Senna system!",
    #       1436367600,
    #       3,
    #       "Senna"
    #     ],
    #     [
    #       "Mroonga",
    #       "I also started to use Mroonga. It's also very fast! Really fast!",
    #       1436288400,
    #       15,
    #       "Groonga"
    #     ],
    #     [
    #       "Groonga",
    #       "I started to use Groonga. It's very fast!",
    #       1436284800,
    #       10,
    #       "Groonga"
    #     ],
    #     [
    #       "The first post!",
    #       "Welcome! This is my first post!",
    #       1436281200,
    #       5,
    #       "Hello"
    #     ]
    #   ]
    # ]

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

このコマンドは select 互換の検索関連パラメーターをサポートしています。

#### 7.3.34.4.3.1. `filter`

select の filter に対応しています。詳細は filter を見てください。

以下は例です。

TODO

#### 7.3.34.4.3.2. `post_filter`

バージョン 7.1.1 で追加.

`filtered` ステージの動的カラムが生成されてから実行するフィルターを指定します。 `post_filter` を使うと `filtered` ステージの動的カラムを使って絞り込むことができます。他は filter と同じです。

`post_filter` を使うと、「十分なレコードがマッチしたらそのテーブルの検索を切り上げる」機能が無効になります。（「十分なレコードがマッチしたら残りのテーブルの検索を切り上げる」機能は有効です。）なぜなら `post_filter` は動的カラムが生成されるのを待つ必要があるからです。 動的カラム関連の引数 も参照してください。

以下は人気のあるタグのエントリーだけを表示する例です。対象となるすべてのエントリーには `system` または `use` という単語が含まれています。

実行例:

    logical_range_filter \
      --logical_table Entries \
      --shard_key created_at \
      --columns[n_likes_sum_per_tag].stage filtered \
      --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' \
      --filter 'content @ "system" || content @ "use"' \
      --post_filter 'n_likes_sum_per_tag > 10' \
      --output_columns _key,n_likes,n_likes_sum_per_tag
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         "_key",
    #         "ShortText"
    #       ],
    #       [
    #         "n_likes",
    #         "UInt32"
    #       ],
    #       [
    #         "n_likes_sum_per_tag",
    #         "UInt32"
    #       ]
    #     ],
    #     [
    #       "Groonga",
    #       10,
    #       25
    #     ],
    #     [
    #       "Mroonga",
    #       15,
    #       25
    #     ]
    #   ]
    # ]

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

#### 7.3.34.4.4.1. `output_columns`

select の output_columns に対応しています。詳細は output_columns を見てください。

以下は例です。

実行例:

    logical_range_filter \
      --logical_table Entries \
      --shard_key created_at \
      --output_columns '_key, *'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         "_key",
    #         "ShortText"
    #       ],
    #       [
    #         "content",
    #         "Text"
    #       ],
    #       [
    #         "created_at",
    #         "Time"
    #       ],
    #       [
    #         "n_likes",
    #         "UInt32"
    #       ],
    #       [
    #         "tag",
    #         "ShortText"
    #       ]
    #     ],
    #     [
    #       "The first post!",
    #       "Welcome! This is my first post!",
    #       1436281200.0,
    #       5,
    #       "Hello"
    #     ],
    #     [
    #       "Groonga",
    #       "I started to use Groonga. It's very fast!",
    #       1436284800.0,
    #       10,
    #       "Groonga"
    #     ],
    #     [
    #       "Mroonga",
    #       "I also started to use Mroonga. It's also very fast! Really fast!",
    #       1436288400.0,
    #       15,
    #       "Groonga"
    #     ],
    #     [
    #       "Good-bye Senna",
    #       "I migrated all Senna system!",
    #       1436367600.0,
    #       3,
    #       "Senna"
    #     ],
    #     [
    #       "Good-bye Tritonn",
    #       "I also migrated all Tritonn system!",
    #       1436371200.0,
    #       3,
    #       "Senna"
    #     ]
    #   ]
    # ]

#### 7.3.34.4.4.2. `sort_keys`

バージョン 8.0.2 で追加.

select の sort_keys に対応しています。詳細は sort_keys を見てください。

`sort_keys` には制限があります。検索対象のシャードが1つの場合のみ動作します。もし、検索対象のシャードが複数ある場合、 `sort_keys` は正常な動作をしません。

注釈

複数のシャードに関して例外があります。`shard_key` と `sort_keys` に同じ値が指定された場合です。その場合はサポートしています。このコマンドはシャードを昇順で順番に処理します。そのため、`shard_key` の大小関係は保たれるので、正しくソートできます。

以下は1つのシャードのみを使っている例です。

実行例:

    logical_select \
      --logical_table Entries \
      --shard_key created_at \
      --sort_keys _key \
      --output_columns _key,created_at
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "created_at",
    #           "Time"
    #         ]
    #       ],
    #       [
    #         "Groonga",
    #         1436284800.0
    #       ],
    #       [
    #         "Mroonga",
    #         1436288400.0
    #       ],
    #       [
    #         "The first post!",
    #         1436281200.0
    #       ],
    #       [
    #         "Good-bye Senna",
    #         1436367600.0
    #       ],
    #       [
    #         "Good-bye Tritonn",
    #         1436371200.0
    #       ]
    #     ]
    #   ]
    # ]

以下は `shard_key` ベースの値を第一ソートキーに指定している例です。

実行例:

    plugin_register functions/time
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    logical_select \
      --logical_table Entries \
      --shard_key created_at \
      --columns[hour2].stage filtered \
      --columns[hour2].type Time \
      --columns[hour2].flags COLUMN_SCALAR \
      --columns[hour2].value 'time_classify_hour(created_at, 2)' \
      --sort_keys hour2,-n_likes \
      --output_columns hour2,n_likes,_key
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "hour2",
    #           "Time"
    #         ],
    #         [
    #           "n_likes",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1436367600.0,
    #         3,
    #         "Good-bye Senna"
    #       ],
    #       [
    #         1436367600.0,
    #         3,
    #         "Good-bye Tritonn"
    #       ],
    #       [
    #         1436281200.0,
    #         10,
    #         "Groonga"
    #       ],
    #       [
    #         1436281200.0,
    #         5,
    #         "The first post!"
    #       ],
    #       [
    #         1436288400.0,
    #         15,
    #         "Mroonga"
    #       ]
    #     ]
    #   ]
    # ]

#### 7.3.34.4.4.3. `offset`

select の offset に対応しています。詳細は offset を見てください。

以下は例です。

実行例:

    logical_range_filter \
      --logical_table Entries \
      --shard_key created_at \
      --offset 2
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         "_key",
    #         "ShortText"
    #       ],
    #       [
    #         "content",
    #         "Text"
    #       ],
    #       [
    #         "created_at",
    #         "Time"
    #       ],
    #       [
    #         "n_likes",
    #         "UInt32"
    #       ],
    #       [
    #         "tag",
    #         "ShortText"
    #       ]
    #     ],
    #     [
    #       "Mroonga",
    #       "I also started to use Mroonga. It's also very fast! Really fast!",
    #       1436288400.0,
    #       15,
    #       "Groonga"
    #     ],
    #     [
    #       "Good-bye Senna",
    #       "I migrated all Senna system!",
    #       1436367600.0,
    #       3,
    #       "Senna"
    #     ],
    #     [
    #       "Good-bye Tritonn",
    #       "I also migrated all Tritonn system!",
    #       1436371200.0,
    #       3,
    #       "Senna"
    #     ]
    #   ]
    # ]

#### 7.3.34.4.4.4. `limit`

select の limit に対応しています。詳細は limit を見てください。

select との違いは、このコマンドは offset と limit で指定したレコードを見つけたら検索を終了することです。

以下は例です。

実行例:

    logical_range_filter \
      --logical_table Entries \
      --shard_key created_at \
      --limit 2
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         "_key",
    #         "ShortText"
    #       ],
    #       [
    #         "content",
    #         "Text"
    #       ],
    #       [
    #         "created_at",
    #         "Time"
    #       ],
    #       [
    #         "n_likes",
    #         "UInt32"
    #       ],
    #       [
    #         "tag",
    #         "ShortText"
    #       ]
    #     ],
    #     [
    #       "The first post!",
    #       "Welcome! This is my first post!",
    #       1436281200.0,
    #       5,
    #       "Hello"
    #     ],
    #     [
    #       "Groonga",
    #       "I started to use Groonga. It's very fast!",
    #       1436284800.0,
    #       10,
    #       "Groonga"
    #     ]
    #   ]
    # ]

### 7.3.34.4.5. テスト関連の引数

#### 7.3.34.4.5.1. `use_range_index`

range_indexを使うかどうかを指定します。ただし、この引数はテスト用なので、本番で使うべきではありません。

TODO: Add examples

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

バージョン 7.0.9 で追加.

select のすべての動的カラム関連パラメーターをサポートしています。詳細は 動的カラム関連の引数 を見てください。

動的カラムを1つ以上使うと、「十分なレコードがマッチしたらそのテーブルの検索を切り上げる」機能が無効になります。（「十分なレコードがマッチしたら残りのテーブルの検索を切り上げる」機能は有効です。） `logical_range_filter` は要求されているマッチレコード数が小さくても各テーブルですべてのマッチするレコードを検索します。これはウィンドウ関数をサポートするためです。ウィンドウ関数を実行するには同一テーブル内のすべての対象レコードが必要です。

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

バージョン 7.0.9 で追加.

select の columns[${NAME}].stage に対応しています。詳細は columns[${NAME}].stage を見てください。

必須の引数です。

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

実行例:

    logical_range_filter \
      --logical_table Entries \
      --shard_key created_at \
      --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
    #   ],
    #   [
    #     [
    #       [
    #         "_id",
    #         "UInt32"
    #       ],
    #       [
    #         "is_popular",
    #         "Bool"
    #       ],
    #       [
    #         "n_likes",
    #         "UInt32"
    #       ]
    #     ],
    #     [
    #       2,
    #       true,
    #       10
    #     ],
    #     [
    #       3,
    #       true,
    #       15
    #     ]
    #   ]
    # ]

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

バージョン 7.0.9 で追加.

select の columns[${NAME}].flags に対応しています。詳細は columns[${NAME}].flags を見てください。

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

以下は `COLUMN_VECTOR` フラグを指定してベクターカラムを作る例です。 `plugin_register functions/vector` は vector_new 関数を使うために実行しています。:

実行例:

    plugin_register functions/vector
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    logical_range_filter \
      --logical_table Entries \
      --shard_key created_at \
      --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
    #   ],
    #   [
    #     [
    #       [
    #         "_id",
    #         "UInt32"
    #       ],
    #       [
    #         "vector",
    #         "UInt32"
    #       ]
    #     ],
    #     [
    #       1,
    #       [
    #         1,
    #         2,
    #         3
    #       ]
    #     ],
    #     [
    #       2,
    #       [
    #         1,
    #         2,
    #         3
    #       ]
    #     ],
    #     [
    #       3,
    #       [
    #         1,
    #         2,
    #         3
    #       ]
    #     ],
    #     [
    #       1,
    #       [
    #         1,
    #         2,
    #         3
    #       ]
    #     ],
    #     [
    #       2,
    #       [
    #         1,
    #         2,
    #         3
    #       ]
    #     ]
    #   ]
    # ]

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

バージョン 7.0.9 で追加.

select の columns[${NAME}].type に対応しています。詳細は columns[${NAME}].type を見てください。

必須の引数です。

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

実行例:

    logical_range_filter \
      --logical_table Entries \
      --shard_key created_at \
      --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
    #   ],
    #   [
    #     [
    #       [
    #         "_id",
    #         "UInt32"
    #       ],
    #       [
    #         "n_likes",
    #         "UInt32"
    #       ],
    #       [
    #         "n_likes_string",
    #         "ShortText"
    #       ]
    #     ],
    #     [
    #       1,
    #       5,
    #       "5"
    #     ],
    #     [
    #       2,
    #       10,
    #       "10"
    #     ],
    #     [
    #       3,
    #       15,
    #       "15"
    #     ],
    #     [
    #       1,
    #       3,
    #       "3"
    #     ],
    #     [
    #       2,
    #       3,
    #       "3"
    #     ]
    #   ]
    # ]

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

バージョン 7.0.9 で追加.

select の columns[${NAME}].value に対応しています。詳細は columns[${NAME}].value を見てください。

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

必須の引数です。

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

実行例:

    plugin_register functions/string
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    logical_range_filter \
      --logical_table Entries \
      --shard_key created_at \
      --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
    #   ],
    #   [
    #     [
    #       [
    #         "_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
    #     ],
    #     [
    #       1,
    #       "I migrated all Senna system!",
    #       28
    #     ],
    #     [
    #       2,
    #       "I also migrated all Tritonn system!",
    #       35
    #     ]
    #   ]
    # ]

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

バージョン 7.0.9 で追加.

select のすべてのウィンドウ関数関連パラメーターをサポートしています。詳細は ウィンドウ関数関連の引数 を見てください。

注釈

バージョン9.0.1以前では、複数のテーブルをまたがったウィンドウ関数はサポートしていません。バージョン9.0.2以降ではサポートしていますが、先頭のグループキーまたは、ソートキーがシャードキーと同じ順序で並んでいる必要があります。

例えば、以下のようなケースでは、複数のテーブルをまたいでウインドウ関数を適用できます。以下の例では、先頭のグループキーがシャードキーと同じ順序で並んでいるからです。

以下の例では、先頭のグループキーは `price` でシャードキーは `timestamp` です。 `price` と `timestamp` は同じ順序で並んでいるため、複数のテーブルをまたいでウインドウ関数を適用できます。

実行例:

    plugin_register sharding

    table_create Logs_20170415 TABLE_NO_KEY
    column_create Logs_20170415 timestamp COLUMN_SCALAR Time
    column_create Logs_20170415 price COLUMN_SCALAR UInt32
    column_create Logs_20170415 n_likes COLUMN_SCALAR UInt32

    table_create Logs_20170416 TABLE_NO_KEY
    column_create Logs_20170416 timestamp COLUMN_SCALAR Time
    column_create Logs_20170416 price COLUMN_SCALAR UInt32
    column_create Logs_20170416 n_likes COLUMN_SCALAR UInt32

    load --table Logs_20170415
    [
    {"timestamp": "2017/04/15 00:00:00", "n_likes": 2, "price": 100},
    {"timestamp": "2017/04/15 01:00:00", "n_likes": 1, "price": 100},
    {"timestamp": "2017/04/15 01:00:00", "n_likes": 2, "price": 200}
    ]

    load --table Logs_20170416
    [
    {"timestamp": "2017/04/16 10:00:00", "n_likes": 1, "price": 200},
    {"timestamp": "2017/04/16 11:00:00", "n_likes": 2, "price": 300},
    {"timestamp": "2017/04/16 11:00:00", "n_likes": 1, "price": 300}
    ]

    logical_range_filter Logs \
      --shard_key timestamp \
      --columns[count].stage initial \
      --columns[count].type UInt32 \
      --columns[count].flags COLUMN_SCALAR \
      --columns[count].value 'window_count()' \
      --columns[count].window.group_keys price \
      --output_columns price,count
    # [
    #   [
    #     0,
    #     0.0,
    #     0.0
    #   ],
    #   [
    #     [
    #       [
    #         6
    #       ],
    #       [
    #         [
    #           "price",
    #           "UInt32"
    #         ],
    #         [
    #           "count",
    #           "UInt32"
    #         ]
    #       ],
    #       [
    #         100,
    #         2
    #       ],
    #       [
    #         100,
    #         2
    #       ],
    #       [
    #         200,
    #         2
    #       ],
    #       [
    #         200,
    #         2
    #       ],
    #       [
    #         300,
    #         2
    #       ],
    #       [
    #         300,
    #         2
    #       ]
    #     ]
    #   ]
    # ]

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

バージョン 7.0.9 で追加.

select の columns[${NAME}].window.sort_keys に対応しています。詳細は columns[${NAME}].window.sort_keys を見てください。

ウィンドウ関数を使うには columns[${NAME}].window.sort_keys または columns[${NAME}].window.group_keys を指定しなければいけません。

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

実行例:

    logical_range_filter \
      --logical_table Entries \
      --shard_key created_at \
      --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 \
      --output_columns tag,_key,n_likes,n_likes_cumulative_sum_per_tag
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         "tag",
    #         "ShortText"
    #       ],
    #       [
    #         "_key",
    #         "ShortText"
    #       ],
    #       [
    #         "n_likes",
    #         "UInt32"
    #       ],
    #       [
    #         "n_likes_cumulative_sum_per_tag",
    #         "UInt32"
    #       ]
    #     ],
    #     [
    #       "Hello",
    #       "The first post!",
    #       5,
    #       5
    #     ],
    #     [
    #       "Groonga",
    #       "Groonga",
    #       10,
    #       10
    #     ],
    #     [
    #       "Groonga",
    #       "Mroonga",
    #       15,
    #       25
    #     ],
    #     [
    #       "Senna",
    #       "Good-bye Senna",
    #       3,
    #       3
    #     ],
    #     [
    #       "Senna",
    #       "Good-bye Tritonn",
    #       3,
    #       6
    #     ]
    #   ]
    # ]

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

バージョン 7.0.9 で追加.

select の columns[${NAME}].window.group_keys に対応しています。詳細は columns[${NAME}].window.group_keys を見てください。

ウィンドウ関数を使うには columns[${NAME}].window.sort_keys または columns[${NAME}].window.group_keys を指定しなければいけません。

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

実行例:

    logical_range_filter \
      --logical_table Entries \
      --shard_key created_at \
      --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,_key,n_likes,n_likes_sum_per_tag
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         "tag",
    #         "ShortText"
    #       ],
    #       [
    #         "_key",
    #         "ShortText"
    #       ],
    #       [
    #         "n_likes",
    #         "UInt32"
    #       ],
    #       [
    #         "n_likes_sum_per_tag",
    #         "UInt32"
    #       ]
    #     ],
    #     [
    #       "Hello",
    #       "The first post!",
    #       5,
    #       5
    #     ],
    #     [
    #       "Groonga",
    #       "Groonga",
    #       10,
    #       25
    #     ],
    #     [
    #       "Groonga",
    #       "Mroonga",
    #       15,
    #       25
    #     ],
    #     [
    #       "Senna",
    #       "Good-bye Senna",
    #       3,
    #       6
    #     ],
    #     [
    #       "Senna",
    #       "Good-bye Tritonn",
    #       3,
    #       6
    #     ]
    #   ]
    # ]

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

#### 7.3.34.4.8.1. `cache`

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

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

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

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

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

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

実行例:

    logical_range_filter \
      --logical_table Entries \
      --shard_key created_at \
      --cache no
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         "_key",
    #         "ShortText"
    #       ],
    #       [
    #         "content",
    #         "Text"
    #       ],
    #       [
    #         "created_at",
    #         "Time"
    #       ],
    #       [
    #         "n_likes",
    #         "UInt32"
    #       ],
    #       [
    #         "tag",
    #         "ShortText"
    #       ]
    #     ],
    #     [
    #       "The first post!",
    #       "Welcome! This is my first post!",
    #       1436281200.0,
    #       5,
    #       "Hello"
    #     ],
    #     [
    #       "Groonga",
    #       "I started to use Groonga. It's very fast!",
    #       1436284800.0,
    #       10,
    #       "Groonga"
    #     ],
    #     [
    #       "Mroonga",
    #       "I also started to use Mroonga. It's also very fast! Really fast!",
    #       1436288400.0,
    #       15,
    #       "Groonga"
    #     ],
    #     [
    #       "Good-bye Senna",
    #       "I migrated all Senna system!",
    #       1436367600.0,
    #       3,
    #       "Senna"
    #     ],
    #     [
    #       "Good-bye Tritonn",
    #       "I also migrated all Tritonn system!",
    #       1436371200.0,
    #       3,
    #       "Senna"
    #     ]
    #   ]
    # ]

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

## 7.3.34.5. 戻り値

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

    [
      HEADER,
      [
        COLUMNS,
        RECORDS
      ]
    ]

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

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

`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
      ]
    ]