7.3.38. logical_select#

7.3.38.1. 概要#

Added in version 5.0.5.

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

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

7.3.38.2. 構文#

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

shard_key は必須の引数です。 shard[${LABEL}].table を使わない場合は logical_table も必須です。 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]
               [query_flags=ALLOW_PRAGMA|ALLOW_COLUMN]
               [drilldown_filter=null]
               [post_filter=null]
               [load_table=null]
               [load_columns=null]
               [load_values=null]
               [n_workers=0]

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

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

  • cache=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}].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

このコマンドには実際のテーブルを明示的に指定するために以下の名前付き引数があります。

  • shard[${LABEL}].table=null

7.3.38.3. select との違い#

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

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

  • table 引数ではなく、 shard_key と、 logical_table か1つ以上の shard[${LABEL}].table が必須です。

  • 複数のシャードを使った場合の sort_keys はサポートしていません。（1つのシャードのみを使った場合はサポートしています。複数のシャードについては1つ例外があります。shard_key と sort_keys が同じ場合です。その場合はサポートしています。詳細は sort_keys を参照してください。）

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

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

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

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

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

7.3.38.4. 使い方#

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

このコマンドは 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.38.4.1. 簡単な使い方#

以下は必須のパラメータのみを指定した例です。

実行例:

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"
#       ]
#     ]
#   ]
# ]

上記の例では、 Entries_20150708 と Entries_20150709 から検索されていることがわかります。

7.3.38.5. 引数#

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

7.3.38.5.1. 必須引数#

shard_key は常に必須です。加えて、 logical_table または1つ以上の shard[${LABEL}].table のどちらかを指定する必要があります。

7.3.38.5.1.1. logical_table#

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

logical_table と shard_key 引数を指定すると5レコード表示できます。

実行例:

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>",
#     [
#       [
#         "execute_search",
#         "lib/groonga/plugins/sharding/logical_select.rb",
#         2929
#       ]
#     ]
#   ]
# ]

7.3.38.5.1.2. shard_key#

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

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

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

7.3.38.5.1.3. shard[${LABEL}].table#

Added in version 16.1.1.

実際のテーブルを明示的に指定します。

通常、logical_select は ${LOGICAL_TABLE}_${YYYYMMDD} という命名規則に基づいて実際のテーブルを自動的に特定します。実際のテーブルがこの命名規則に従っていない場合は、このパラメータを使用して明示的に指定することができます:

logical_select \
  --shard_key timestamp \
  --shard[1].table Logs_host1 \
  --shard[2].table Logs_host2

${LABEL} は単なるラベルです。これは、指定された実際のテーブルを並べ替えるためにのみ使用されます。すべてのラベルが 1、2、10 のように数字のみで構成されている場合は数値順に、それ以外の場合は文字列として並べ替えます。

注意： min や max と一緒に使うとき、ラベルが YYYYMM や YYYYMMDD であっても、シャードの取捨選択には使いません。指定された実際のテーブルをすべて検索します。

1つ以上の shard[${LABEL}].table を指定した場合、logical_table を指定する必要はありません。両方が指定された場合、 shard[${LABEL}].table が使用され、logical_table は無視されます。

shard_key は必須です。指定されたすべての実際のテーブルは、指定されたカラムを含んでいる必要があります。

7.3.38.5.2. 省略可能引数#

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

7.3.38.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.38.5.2.2. min_border#

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

値

説明

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.38.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.38.5.2.4. max_border#

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

値

説明

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.38.5.4. 高度な検索のための引数#

高度な検索パラメーターはほとんど実装されていません。

7.3.38.5.4.1. match_escalation_threshold#

未実装です。

7.3.38.5.4.2. query_flags#

Added in version 16.1.1.

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

デフォルト値は ALLOW_PRAGMA|ALLOW_COLUMN です。 select と同じです。

7.3.38.5.4.3. query_expander#

未実装です。

7.3.38.6. 戻り値#

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

このページでは