7.3.35. logical_range_filter#

7.3.35.1. 概要#

Added in version 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.35.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

Added in version 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.35.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.35.3.1. 簡単な使い方#

TODO

7.3.35.4. 引数#

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

7.3.35.4.1. 必須引数#

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

7.3.35.4.1.1. logical_table#

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

実行例:

logical_range_filter --logical_table Entries --shard_key created_at
# [
#   [
#     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"
#     ]
#   ]
# ]

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

実行例:

logical_range_filter --logical_table Nonexistent --shard_key created_at
# [
#   [
#     -22,
#     1337566253.89858,
#     0.000355720520019531,
#     "[logical_range_filter] no shard exists: logical_table: <Nonexistent>: shard_key: <created_at>",
#     [
#       [
#         "execute",
#         "lib/groonga/plugins/sharding/logical_range_filter.rb",
#         2929
#       ]
#     ]
#   ]
# ]

7.3.35.4.1.2. shard_key#

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

TODO: Add examples

7.3.35.4.2. 省略可能引数#

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

7.3.35.4.2.1. min#

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

TODO: Add examples

7.3.35.4.2.2. min_border#

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

TODO: Add examples

7.3.35.4.2.3. max#

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

TODO: Add examples

7.3.35.4.2.4. max_border#

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

TODO: Add examples

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

7.3.35.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
  ]
]