groonga - オープンソースのカラムストア機能付き全文検索エンジン

7.3.17. select

7.3.17.1. 概要

select はテーブルから指定された条件にマッチするレコードを検索し、見つかったレコードを出力します。

select は最も重要なgroongaのコマンドです。groongaの力を最大限に活かすためには select を理解する必要があります。

7.3.17.2. 構文

select には多くの引数があります。必須の引数は table だけで、残りは省略できます。:

select table
       [match_columns=null]
       [query=null]
       [filter=null]
       [scorer=null]
       [sortby=null]
       [output_columns="_id, _key, *"]
       [offset=0]
       [limit=10]
       [drilldown=null]
       [drilldown_sortby=null]
       [drilldown_output_columns=null]
       [drilldown_offset=0]
       [drilldown_limit=10]
       [cache=yes]
       [match_escalation_threshold=0]
       [query_expansion=null]

7.3.17.3. 使い方

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

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

Execution example:

> table_create Entries TABLE_HASH_KEY ShortText
[[0,1335594537.43378,0.000381708145141602],true]
> column_create Entries content COLUMN_SCALAR Text
[[0,1335594537.63582,0.000931501388549805],true]
> table_create Terms TABLE_PAT_KEY|KEY_NORMALIZE ShortText --default_tokenizer TokenBigram
[[0,1335594537.83776,0.000288009643554688],true]
> column_create Terms entries_key_index COLUMN_INDEX|WITH_POSITION Entries _key
[[0,1335594538.03901,0.0059964656829834],true]
> column_create Terms entries_content_index COLUMN_INDEX|WITH_POSITION Entries content
[[0,1335594538.24584,0.00617790222167969],true]
> load --table Entries
> [
> {"_key": "The first post!", "content": "Welcome! This is my first post!"},
> {"_key": "Groonga", "content": "I started to use groonga. It's very fast!"}
> {"_key": "Mroonga", "content": "I also started to use mroonga. It's also very fast! Really fast!"}
> ]

ブログエントリ用の Entries テーブルがあります。各エントリはタイトルと内容を持っています。タイトルは Entries のキーとします。内容は Entries.content カラムの値とします。

Entries._key カラムと Entries.content カラムには TokenBigram トークナイザーを使ってのインデックスを作成します。そのため、 Entries._keyEntries.content は両方とも全文検索できます。

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

7.3.17.3.1. 簡単な使い方

上記のスキーマとデータを使った一番簡単な使い方を示します。この例では Entries テーブルのすべてのレコードを出力します。

Execution example:

> select Entries
[
  [
    0,
    1335519592.67133,
    0.000493049621582031
  ],
  [
    [
      [
        3
      ],
      [
        [
          "_id",
          "UInt32"
        ],
        [
          "_key",
          "ShortText"
        ],
        [
          "content",
          "Text"
        ]
      ],
      [
        1,
        "The first post!",
        "Welcome! This is my first post!"
      ],
      [
        2,
        "Groonga",
        "I started to use groonga. It's very fast!"
      ],
      [
        3,
        "Mroonga",
        "I also started to use mroonga. It's also very fast! Really fast!"
      ]
    ]
  ]
]

どうしてこのコマンドがすべてのレコードを出力するのでしょうか?理由は2つです。1つ目の理由はこのコマンドが検索条件を何も指定していないからです。検索条件を指定しないとすべてのレコードがマッチします。2つ目の理由は全レコード数が2だからです。 select コマンドはデフォルトでは最大10レコードを出力します。この例では3レコードしかありません。これは10よりも少ないのですべてのレコードを出力します。

7.3.17.3.2. 検索条件

検索条件は query または filter で指定します。 queryfilter を両方指定することもできます。この場合は queryfilter の両方の条件にマッチしたレコードが出力されます。

7.3.17.3.2.1. 検索条件: query

query はWebページの検索ボックス用に用意されています。例えば、google.co.jpにあるような検索ボックスです。 query の検索条件はスペース区切りでキーワードを指定します。例えば、 検索 エンジン検索エンジン という2つのキーワードを含むレコードを検索します。

通常は query パラメータは全文検索条件を指定するために使います。全文検索条件以外も指定できますが、その用途には filter パラメータの方が向いています。

query パラメータで全文検索条件を指定する場合は、 match_columns パラメータと一緒に使います。 match_columns はどのカラムまたはインデックスを使って query を検索するかを指定します。

以下は簡単な query の使用例です。

Execution example:

> select Entries --match_columns content --query fast
[
  [
    0,
    1335519592.87374,
    0.000868797302246094
  ],
  [
    [
      [
        2
      ],
      [
        [
          "_id",
          "UInt32"
        ],
        [
          "_key",
          "ShortText"
        ],
        [
          "content",
          "Text"
        ]
      ],
      [
        2,
        "Groonga",
        "I started to use groonga. It's very fast!"
      ],
      [
        3,
        "Mroonga",
        "I also started to use mroonga. It's also very fast! Really fast!"
      ]
    ]
  ]
]

この select コマンドは Entries テーブルの中から content カラムの値に fast を含んでいるレコードを検索します。

query はクエリ構文という構文を使いますが、詳細はここでは説明しません。詳細は クエリ構文 を参照してください。

7.3.17.3.2.2. 検索条件: filter

filter は複雑な検索条件を指定するために用意されています。ECMAScriptのような構文で filter に検索条件を指定します。

以下は簡単な filter の使用例です。

Execution example:

> select Entries --filter 'content @ "fast" && _key == "Groonga"'
[
  [
    0,
    1335520300.98383,
    0.000544071197509766
  ],
  [
    [
      [
        1
      ],
      [
        [
          "_id",
          "UInt32"
        ],
        [
          "_key",
          "ShortText"
        ],
        [
          "content",
          "Text"
        ]
      ],
      [
        2,
        "Groonga",
        "I started to use groonga. It's very fast!"
      ]
    ]
  ]
]

この select コマンドは Entries テーブルの中の content カラムの値に fast という単語を含んでいて、かつ、 _keyGroonga のレコードを検索します。このコマンドの中には @&&== という3つの演算子があります。 @ は全文検索用の演算子です。 &&== はECMAScriptと同じ意味です。 && が論理和用の演算子で == が等価演算子です。

filter にはもっと演算子や構文があります。例えば、 (...) を使った検索条件のグループ化などです。しかし、ここでは詳細は説明しません。詳細は スクリプト構文 を参照してください。

7.3.17.3.3. ページング

offsetlimit を指定することで出力されるレコードの範囲を指定できます。以下は2番目のレコードだけを出力する例です。

Execution example:

> select Entries --offset 1 --limit 1
[
  [
    0,
    1335519593.28077,
    0.000288248062133789
  ],
  [
    [
      [
        3
      ],
      [
        [
          "_id",
          "UInt32"
        ],
        [
          "_key",
          "ShortText"
        ],
        [
          "content",
          "Text"
        ]
      ],
      [
        2,
        "Groonga",
        "I started to use groonga. It's very fast!"
      ]
    ]
  ]
]

offset は0基点です。 --offset 1 は2番目以降のレコードを出力するという意味になります。

limit は出力レコード数の最大値を指定します。 --limit 1 は多くても1レコードを出力するという意味になります。もし、1つもレコードがマッチしていなければ select コマンドはどのレコードも出力しません。

7.3.17.3.4. 全レコード数

--limit 0 を使うとレコードの内容は取得せずに全レコード数だけを取得できます。

Execution example:

> select Entries --limit 0
[
  [
    0,
    1335519593.48351,
    0.000329017639160156
  ],
  [
    [
      [
        3
      ],
      [
        [
          "_id",
          "UInt32"
        ],
        [
          "_key",
          "ShortText"
        ],
        [
          "content",
          "Text"
        ]
      ]
    ]
  ]
]

--limit 0 はマッチしたレコード数だけを取得したいときにも便利です。

7.3.17.4. 引数

このセクションではすべての引数について説明します。引数はカテゴリわけしています。

7.3.17.4.1. 必須引数

table だけが必須の引数です。

7.3.17.4.1.1. table

検索対象のテーブルを指定します。 table は必ず指定しなければいけません。

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

Execution example:

> select Nonexistent
[
  [
    -22,
    1335519593.68574,
    0.000583171844482422,
    "invalid table name: <Nonexistent>",
    [
      [
        "grn_select",
        "proc.c",
        542
      ]
    ]
  ]
]

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

7.3.17.4.3.1. match_escalation_threshold

TODO: add example.

検索方法をエスカレーションするかどうかを決定するための閾値を指定します。この閾値はマッチしたレコード数との比較に使われます。マッチしたレコード数がこの閾値以下の場合は検索方法をエスカレーションします。検索方法のエスカレーションについては 検索 を参照してください。

デフォルトの閾値は0です。これは1つもレコードがマッチしなかったときだけ検索方法をエスカレーションするということです。

デフォルトの閾値は以下の方法でカスタマイズできます。

  • configureの --with-match-escalation-threshold オプション
  • groongaコマンドの --match-escalation-threshold オプション
  • 設定ファイルの match-escalation-threshold 設定項目

7.3.17.4.3.2. query_expansion

TODO: write in English and add example.

query 引数の値を拡張(置換)するために使うカラムを指定します。

query_expansionパラメータには、queryパラメータに指定された文字列を置換(拡張)する条件となるテーブル・カラムを指定します。フォーマットは「${テーブル名}.${カラム名}」となります。指定するテーブルは文字列を主キーとするハッシュ型あるいはパトリシア木型のテーブルで、一つ以上の文字列型のカラムが定義されている必要があります。(ここでは置換テーブルと呼びます。)

queryパラメータに指定された文字列が、指定されたテーブルの主キーと完全一致する場合、その文字列を指定されたカラム値の文字列に置換します。queryパラメータが、空白、括弧、演算子などを含む場合は、その演算子によって区切られた文字列の単位で置換が実行されます。ダブルクォート("")で括られた範囲は、その内部に空白を含んでいても一つの置換される単位と見なされます。検索文字列と置換テーブルの主キー値との比較に際して大文字小文字等を区別したくない場合には、置換テーブルを定義する際にKEY_NORMALIZEを指定します。置換後の文字列となるカラムの値には、括弧や*, ORなど、queryパラメータで利用可能な全ての演算子を指定することができます。

7.3.17.5. 返値

TODO: write in English and add example.

以下のようなjson形式で値が返却されます。

[[リターンコード, 処理開始時間, 処理時間], [検索結果, ドリルダウン結果]]

リターンコード

grn_rcに対応する数値が返されます。0(GRN_SUCCESS)以外の場合は、続いてエラー内容を示す 文字列が返されます。

処理開始時間

処理を開始した時間について、1970年1月1日0時0分0秒を起点とした秒数を小数で返します。

処理時間

処理にかかった秒数を返します。

検索結果

drilldown条件が実行される前の検索結果が以下のように出力されます。:

[[検索件数], [[カラム名1,カラム型1],..], 検索結果1,..]

検索件数

検索件数が出力されます。

カラム名n

output_columnsに指定された条件に従って、対象となるカラム名が出力されます。

カラム型n

output_columnsに指定された条件に従って、対象となるカラム型が出力されます。

検索結果n

output_columns, offset, limitによって指定された条件に従って各レコードの値が出力されます。

drilldown結果

drilldown処理の結果が以下のように出力されます。:

[[[件数], [[カラム名1,カラム型1],..], 検索結果1,..],..]

件数

drilldownに指定されたカラムの値の異なり数が出力されます。

カラム名n

drilldown_output_columnsに指定された条件に従って、対象となるカラム名が出力されます。

カラム型n

drilldown_output_columnsに指定された条件に従って、対象となるカラム型が出力されます。

ドリルダウン結果n

drilldown_output_columns, drilldown_offset, drilldown_limitによって指定された条件に従って各レコードの値が出力されます。