.. -*- rst -*-

.. highlightlang:: none

select
======

名前
----

select - テーブルの中から条件にマッチするレコードを検索して出力する

書式
----
::

 select table [match_columns [query [filter [scorer [sortby [output_columns
              [offset [limit [drilldown [drilldown_sortby [drilldown_output_columns
              [drilldown_offset [drilldown_limit [cache
              [match_escalation_threshold [query_expansion]]]]]]]]]]]]]]]]

説明
----

groonga組込コマンドの一つであるselectについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。

selectは、使用しているデータベースのテーブルの中から条件にマッチするレコードを検索して出力します。

引数
----

``table``

  検索対象のテーブルを指定します。存在しないテーブルを指定した場合はエラーになります。

``match_columns``

  query引数に指定する検索条件文字列でデフォルトの検索対象となるカラムを指定します。

    カラム名

  カラム名の後ろに'* 数値'を指定することによって、そのカラムにヒットした際のスコアに積算される重みを指定することができます。

    カラム名 * 重み

  複数のカラムを'||'で結合して指定することもできます。

    カラム名1 * 重み1 || カラム名2 * 重み2

  また、カラム名ではなく、検索に使用するインデックス名を指定することもできます。

``query``

  以下の形式の文字列によって検索条件を指定します。

条件式
^^^^^^

以下の条件式が使用できます。

文字列
  全文検索条件(デフォルト検索対象カラムの値が指定された文字列を含んでいる)

\"文字列\"
  フレーズ検索条件(デフォルト検索対象カラムの値が指定されたフレーズを含んでいる)

カラム名:値
  一致条件(カラム値 == 値)

カラム名:!値
  不一致条件(カラム値 != 値)

カラム名:<値
  比較条件(カラム値 < 値)

カラム名:>値
  比較条件(カラム値 > 値)

カラム名:<=値
  比較条件(カラム値 <= 値)

カラム名:>=値
  比較条件(カラム値 >= 値)

カラム名:@文字列
  全文検索条件(カラム値が指定された文字列を含んでいる)

結合演算子
^^^^^^^^^^

複数の条件式を結合するために以下の演算子が使用できます。

a OR b
  論理和(aとbといずれかの条件がマッチする)

a + b
  論理積(aとbの両方がマッチする)

a - b
  aにマッチし、bにはマッチしない

( )
  複数の条件をまとめる


``filter``

  絞り込み条件をscript形式のgrn_expr文字列によって指定します。

  query引数とfilter引数をどちらも指定した場合は、両方の条件を満足するレコードのみがヒットします。どちらも指定しない場合は全件がヒットします。

``scorer``

  検索条件にマッチする全てのレコードに対して適用するgrn_exprをscript形式で指定します。

  scorerは、検索処理が完了し、ソート処理が実行される前に呼び出されます。従って、各レコードのスコアを操作する式を指定しておけば、検索結果のソート順序をカスタマイズできるようになります。

``sortby``

  ソートキーとなるカラム名のリストをカンマ(',')区切りで指定します。::

    [-]カラム名1, [-]カラム名2, [-]カラム名3, ...

  カラム名1の値でソートし、値が同一である場合はカラム名2でソート、と順次比較を行いソートします。カラム名の前に - を付加した場合は降順にソートします。付加しない場合には昇順にソートします。

  query引数またはfilter引数を指定した場合はカラム名に'_score'を使えます。'_score'を指定することでスコアでソートすることができます。query引数もfilter引数も指定していない状態で'_score'を指定するとエラーになります。

``output_columns``

  出力するカラム名のリストをカンマ(',')区切りで指定します。

  アスタリスク('*')を指定すると、全てのカラムが指定されたものとみなされます。または、script形式のgrn_expr文字列を指定します。 (デフォルトは、'_id, _key, \*')

``offset``

  検索条件にマッチしたレコードのうち、出力対象となる最初のレコードの番号を0ベースで指定します。デフォルト値は0です。offsetに負の値を指定した場合は、ヒットした件数 + offset によって算出される値が指定されたものとみなされます。

``limit``

  検索条件にマッチしたレコードのうち、出力を行うレコードの件数を指定します。デフォルト値は10です。実際には、offset + limit がヒットした件数を超えない範囲でレコードが出力されます。limitに負の値を指定した場合は、ヒットした件数 + limit + 1 によって算出される値が指定されたものとみなされます。

``drilldown``

  グループ化のキーとなるカラム名のリストをカンマ(',')区切りで指定します。検索条件にマッチした各レコードを出力したのちに、drilldownに指定されたカラムの値が同一であるレコードをとりまとめて、それぞれについて結果レコードを出力します。

``drilldown_sortby``

  drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、ソートキーとなるカラム名のリストをカンマ(',')区切りで指定します。sortbyパラメータと同様に昇降順を指定できます。

``drilldown_output_columns``

  drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、出力するカラム名のリストをカンマ(',')区切りで指定します。

``drilldown_offset``

  drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、出力対象となる最初のレコードの番号を0ベースで指定します。デフォルト値は0です。drilldown_offsetに負の値を指定した場合は、ヒットした件数 + drilldown_offsetによって算出される値が指定されたものとみなされます。

``drilldown_limit``

  drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、出力を行うレコードの件数を指定します。デフォルト値は10です。実際には、drilldown_offset + drilldown_limit がヒットした件数を超えない範囲でレコードが出力されます。drilldown_limitに負の値を指定した場合は、ヒットした件数 + drilldown_limit + 1 によって算出される値が指定されたものとみなされます。

``cache``

  クエリキャッシュに関する動作を設定します。

    ``no``

      検索結果をクエリキャッシュに残しません。キャッシュして再利用される可能性が低いクエリに対して用います。キャッシュ容量は有限です。有効なキャッシュが多くヒットするために、このパラメータは有効です。

``match_escalation_threshold``

  検索の挙動をエスカレーションするかどうかの閾値を設定します。デフォルト値は0です。デフォルト値は以下のいずれかの方法で設定できます。

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

  クエリのヒット件数が閾値を越えない場合は :doc:`/spec/search` で説明している方法で検索方法をエスカレーションしてきます。

``query_expansion``

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

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

返値
----

以下のような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によって指定された条件に従って各レコードの値が出力されます。

例
--

テーブルEntryの全レコード・全カラムの値を出力します。::

 select Entry

 [[[2],[["_id", "UInt32"],["_key","ShortText"],["body","ShortText"]],[1,"abandon","放棄する"],[2,"abbreviate","短縮する"]]]

関連項目
--------

:doc:`../expr`
