7.3.34. logical_select

7.3.34.1. 概要

バージョン 5.0.5 で追加.

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

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

7.3.34.2. 構文

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

必須の引数は logical_table と shard_key です。それ以外の引数は省略可能です:

logical_select logical_table
               shard_key
               [min=null]
               [min_border="include"]
               [max=null]
               [max_border="include"]
               [filter=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]
               [drilldown_calc_types=NONE]
               [drilldown_calc_target=null]
               [sort_keys=null]
               [drilldown_sort_keys=null]
               [match_columns=null]
               [query=null]
               [drilldown_filter=null]

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

  • 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}].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.1.4 で撤廃: drilldown[...] 構文は非推奨になりました。代わりに drilldowns[...] を使用してください。

バージョン 6.1.5 で撤廃: drilldowns[${LABEL}].sortby は非推奨になりました。代わりに drilldowns[${LABEL}].sort_keys を使ってください。

${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.34.3. select との違い

logical_select の多くの機能は select の機能と対応しています。たとえば、引数名は同じですし、出力フォーマットも同じです。

しかし、いくつか select と違うところもあります。

  • table 引数ではなく、 logical_table と shard_key 引数が必須です。

  • 複数のシャードを使った場合の sort_keys はサポートしていません。（1つのシャードのみを使った場合はサポートしています。）

  • 複数のシャードを使った場合、 drilldowns[${LABEL}].sort_keys の中で _value.${KEY_NAME} を使えません。1つのシャードのみを使った場合は使えます。

  • cache はまだサポートしていません。

  • match_escalation_threshold はまだサポートしていません。

  • query_flags はまだサポートしていません。

  • query_expander はまだサポートしていません。

  • adjuster はまだサポートしていません。

7.3.34.4. 使い方

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

logical_select は 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.4.1. 簡単な使い方

TODO

7.3.34.5. 引数

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

7.3.34.5.1. 必須引数

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

7.3.34.5.1.1. logical_table

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

logical_table と shard_key 引数を指定すると10レコード表示できます。これらの引数は必須の引数です。

実行例:

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

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

実行例:

logical_select --logical_table Nonexistent --shard_key created_at
# [
#   [
#     -22,
#     1337566253.89858,
#     0.000355720520019531,
#     "[logical_select] no shard exists: logical_table: <Nonexistent>: shard_key: <created_at>",
#     [
#       [
#         "Groonga::Sharding::LogicalSelectCommand::Executor.execute_search",
#         "/home/kou/work/c/groonga.clean/plugins/sharding/logical_select.rb",
#         728
#       ]
#     ]
#   ]
# ]

7.3.34.5.1.2. shard_key

シャードキーとして使うカラム名を指定します。シャードキーは適切なシャードへレコードを分配するために使う値を保存しているカラムです。

今のところ、シャードキーは Time 型でなければいけません。

shard_key の指定方法は logical_table を見てください。

7.3.34.5.2. 省略可能引数

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

7.3.34.5.2.1. min

shard_key カラムの最小値を指定します。シャードにマッチするレコードがない場合は、そのシャードは検索対象外になります。

たとえば、 min が "2015/07/09 00:00:00" なら、 Entry_20150708 は検索対象外です。なぜなら、 Entry_20150708 は "2015/07/08" のレコードしかないからです。

以下の例は Entry_20150709 テーブルだけを使う例です。 Entry_20150708 は使われません。

実行例:

logical_select \
  --logical_table Entries \
  --shard_key created_at \
  --min "2015/07/09 00:00:00"
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         2
#       ],
#       [
#         [
#           "_id",
#           "UInt32"
#         ],
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "content",
#           "Text"
#         ],
#         [
#           "created_at",
#           "Time"
#         ],
#         [
#           "n_likes",
#           "UInt32"
#         ],
#         [
#           "tag",
#           "ShortText"
#         ]
#       ],
#       [
#         1,
#         "Good-bye Senna",
#         "I migrated all Senna system!",
#         1436367600.0,
#         3,
#         "Senna"
#       ],
#       [
#         2,
#         "Good-bye Tritonn",
#         "I also migrated all Tritonn system!",
#         1436371200.0,
#         3,
#         "Senna"
#       ]
#     ]
#   ]
# ]

7.3.34.5.2.2. min_border

最小値を含めるかどうかを指定します。指定可能な値は次の通りです。

Value

説明
include

min の値を含みます。これがデフォルト値です。
exclude

min の値を含みません。

次の例は exclude の使用例です。結果には "Good-bye Senna" レコードは含まれません。このレコードの created_at の値が "2015/07/09 00:00:00" だからです。

実行例:

logical_select \
  --logical_table Entries \
  --shard_key created_at \
  --min "2015/07/09 00:00:00" \
  --min_border "exclude"
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         1
#       ],
#       [
#         [
#           "_id",
#           "UInt32"
#         ],
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "content",
#           "Text"
#         ],
#         [
#           "created_at",
#           "Time"
#         ],
#         [
#           "n_likes",
#           "UInt32"
#         ],
#         [
#           "tag",
#           "ShortText"
#         ]
#       ],
#       [
#         2,
#         "Good-bye Tritonn",
#         "I also migrated all Tritonn system!",
#         1436371200.0,
#         3,
#         "Senna"
#       ]
#     ]
#   ]
# ]

7.3.34.5.2.3. max

shard_key カラムの最大値を指定します。シャードにマッチするレコードがない場合、そのシャードは検索対象外になります。

たとえば、 max が "2015/07/08 23:59:59" なら Entry_20150709 は検索対象外です。なぜなら Entry_20150709 には ""2015/07/09" のレコードしかないからです。

以下の例は Entry_20150708 テーブルだけを使います。 Entry_20150709 は使いません。

実行例:

logical_select \
  --logical_table Entries \
  --shard_key created_at \
  --max "2015/07/08 23:59:59"
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         3
#       ],
#       [
#         [
#           "_id",
#           "UInt32"
#         ],
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "content",
#           "Text"
#         ],
#         [
#           "created_at",
#           "Time"
#         ],
#         [
#           "n_likes",
#           "UInt32"
#         ],
#         [
#           "tag",
#           "ShortText"
#         ]
#       ],
#       [
#         1,
#         "The first post!",
#         "Welcome! This is my first post!",
#         1436281200.0,
#         5,
#         "Hello"
#       ],
#       [
#         2,
#         "Groonga",
#         "I started to use Groonga. It's very fast!",
#         1436284800.0,
#         10,
#         "Groonga"
#       ],
#       [
#         3,
#         "Mroonga",
#         "I also started to use Mroonga. It's also very fast! Really fast!",
#         1436288400.0,
#         15,
#         "Groonga"
#       ]
#     ]
#   ]
# ]

7.3.34.5.2.4. max_border

最大値を含めるかどうかを指定します。指定可能な値は次の通りです。

Value

説明
include

max の値を含みます。これがデフォルト値です。
exclude

max の値を含みません。

次の例は exclude の使用例です。結果には "Good-bye Senna" レコードは含まれません。このレコードの created_at の値が "2015/07/09 00:00:00" だからです。

実行例:

logical_select \
  --logical_table Entries \
  --shard_key created_at \
  --max "2015/07/09 00:00:00" \
  --max_border "exclude"
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         3
#       ],
#       [
#         [
#           "_id",
#           "UInt32"
#         ],
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "content",
#           "Text"
#         ],
#         [
#           "created_at",
#           "Time"
#         ],
#         [
#           "n_likes",
#           "UInt32"
#         ],
#         [
#           "tag",
#           "ShortText"
#         ]
#       ],
#       [
#         1,
#         "The first post!",
#         "Welcome! This is my first post!",
#         1436281200.0,
#         5,
#         "Hello"
#       ],
#       [
#         2,
#         "Groonga",
#         "I started to use Groonga. It's very fast!",
#         1436284800.0,
#         10,
#         "Groonga"
#       ],
#       [
#         3,
#         "Mroonga",
#         "I also started to use Mroonga. It's also very fast! Really fast!",
#         1436288400.0,
#         15,
#         "Groonga"
#       ]
#     ]
#   ]
# ]

7.3.34.5.4. 高度な検索のための引数

logical_select は高度な検索パラメーターをまだ実装していません。

7.3.34.5.4.1. match_escalation_threshold

未実装です。

7.3.34.5.4.2. query_flags

未実装です。

7.3.34.5.4.3. query_expander

未実装です。

7.3.34.6. 戻り値

logical_select の戻り値のフォーマットは select と同じです。詳細は 戻り値 を見てください。