7.3.33. logical_range_filter¶
7.3.33.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.33.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.33.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.33.3.1. 簡単な使い方¶
TODO
7.3.33.4. 引数¶
このセクションでは logical_range_filter の引数について説明します。
7.3.33.4.1. 必須引数¶
必須引数は二つあります。 logical_table と shard_key です。
7.3.33.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.33.4.2. 省略可能引数¶
いくつか省略可能な引数があります。
7.3.33.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.33.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
  ]
]