7.3.33. logical_count#

7.3.33.1. 概要#

Added in version 5.0.0.

logical_count は logical_select の件数カウント機能だけを提供するコマンドです。 logical_select は複数のテーブルからレコードを検索し、マッチしたレコード数を出力し、マッチしたレコードのカラムを出力し、他にもいろいろします。 logical_count は複数のテーブルからレコードを検索し、マッチしたレコード数を出力するだけです。

logical_count はマッチしたレコードの数だけを知りたいときに便利です。 logical_count と logical_range_filter を一緒に使えます。一緒に使うと、マッチしたレコード数を取得する前に、マッチしたレコードのうち先頭のNレコードだけを先に表示できます。 logical_select だけを使っている場合は、すべての検索処理が終わるまで待たなければいけません。

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

7.3.33.2. 構文#

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

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

logical_count
  logical_table
  shard_key
  [min=null]
  [min_border="include"]
  [max=null]
  [max_border="include"]
  [filter=null]
  [post_filter=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 initial

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

logical_count コマンドは実験的なプラグインです。このコマンドは将来的に変更されるかもしれません。

この機能を使う簡単な例を示します。複数のテーブルに保存されている特定のログをカウントしてみましょう。

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

実行例:

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 は両方とも全文検索できます。

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

以下は content カラムに Groonga または Senna を含むレコード数を数える例です。 logical_count はすべての Entries_YYYYMMDD テーブルを検索します。

実行例:

logical_count \
  --logical_table Entries \
  --shard_key created_at \
  --filter 'query("content", "Groonga OR Senna")'
# [[0,1337566253.89858,0.000355720520019531],2]

マッチしたレコードは次の通りです。

  • Entries_20150708 の中の _key:"Groonga"

  • Entries_20150709 の中の _key:"Good-bye Senna"

7.3.33.4. 引数#

このセクションではこのコマンドのパラメーターを説明します。

7.3.33.4.1. 必須引数#

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

7.3.33.4.1.1. logical_table#

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

logical_table と shard_key だけを指定すると全レコード数をカウントできます。これらの引数は必須の引数です。

実行例:

logical_count \
  --logical_table Entries \
  --shard_key created_at
# [[0,1337566253.89858,0.000355720520019531],5]

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

実行例:

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

7.3.33.4.1.2. shard_key#

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

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

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

7.3.33.4.2. 省略可能引数#

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

7.3.33.4.2.1. min#

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

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

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

実行例:

logical_count \
  --logical_table Entries \
  --shard_key created_at \
  --min "2015/07/09 00:00:00"
# [[0,1337566253.89858,0.000355720520019531],2]

7.3.33.4.2.2. min_border#

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

値

説明

include

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

exclude

min の値を含みません。

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

実行例:

logical_count \
  --logical_table Entries \
  --shard_key created_at \
  --min "2015/07/09 00:00:00" \
  --min_border "exclude"
# [[0,1337566253.89858,0.000355720520019531],1]

7.3.33.4.2.3. max#

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

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

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

実行例:

logical_count \
  --logical_table Entries \
  --shard_key created_at \
  --max "2015/07/08 23:59:59"
# [[0,1337566253.89858,0.000355720520019531],3]

7.3.33.4.2.4. max_border#

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

値

説明

include

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

exclude

max の値を含みません。

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

実行例:

logical_count \
  --logical_table Entries \
  --shard_key created_at \
  --max "2015/07/09 00:00:00" \
  --max_border "exclude"
# [[0,1337566253.89858,0.000355720520019531],3]

7.3.33.5. 戻り値#

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

[HEADER, N_HITS]

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

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

N_HITS はマッチしたレコード数です。