.. -*- rst -*- .. highlightlang:: none .. groonga-command .. database: commands_select select ====== Summary ------- ``select`` searches records that are matched to specified conditions from a table and then outputs them. ``select`` is the most important command in groonga. You need to understand ``select`` to use the full power of groonga. Syntax ------ ``select`` has many parameters. The required parameter is only ``table`` and others are optional:: 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] Usage ----- Let's learn about ``select`` usage with examples. This section shows many popular usages. Here are a schema definition and sample data to show usage. .. groonga-command .. include:: ../example/commands/select/usage_setup.log .. table_create Entries TABLE_HASH_KEY ShortText .. column_create Entries content COLUMN_SCALAR Text .. table_create Terms TABLE_PAT_KEY|KEY_NORMALIZE ShortText --default_tokenizer TokenBigram .. column_create Terms entries_key_index COLUMN_INDEX|WITH_POSITION Entries _key .. column_create Terms entries_content_index COLUMN_INDEX|WITH_POSITION Entries content .. 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!"} .. ] There is a table, ``Entries``, for blog entries. An entry has title and content. Title is key of ``Entries``. Content is value of ``Entries.content`` column. ``Entries._key`` column and ``Entries.content`` column are indexed using ``TokenBigram`` tokenizer. So both ``Entries._key`` and ``Entries.content`` are fulltext search ready. OK. The schema and data for examples are ready. Simple usage ^^^^^^^^^^^^ Here is the most simple usage with the above shema and data. It outputs all records in ``Entries`` table. .. groonga-command .. include:: ../example/commands/select/simple_usage.log .. select Entries Why does the command output all records? There are two reasons. The first reason is that the command doesn't specify any search conditions. No search condition means all records are matched. The second reason is that the number of all records is 3. ``select`` command outputs 10 records at a maximum by default. There are only 3 records. It is less than 10. So the command outputs all records. Search conditions ^^^^^^^^^^^^^^^^^ Search conditions are specified by ``query`` or ``filter``. You can also specify both ``query`` and ``filter``. It means that selected records must be matched against both ``query`` and ``filter``. Search condition: ``query`` """"""""""""""""""""""""""" ``query`` is designed for search box in Web page. Imagine a search box in google.com. You specify search conditions for ``query`` as space separated keywords. For example, ``search engine`` means a matched record should contain two words, ``search`` and ``engine``. Normally, ``query`` parameter is used for specifying fulltext search conditions. It can be used for non fulltext search conditions but ``filter`` is used for the propose. ``query`` parameter is used with ``match_columns`` parameter when ``query`` parameter is used for specifying fulltext search conditions. ``match_columns`` specifies which columnes and indexes are matched against ``query``. Here is a simple ``query`` usage example. .. groonga-command .. include:: ../example/commands/select/simple_query.log .. select Entries --match_columns content --query fast The ``select`` command searches records that contain a word ``fast`` in ``content`` column value from ``Entries`` table. ``query`` has query syntax but its deatils aren't described here. See :doc:`/spec/query_syntax` for datails. Search condition: ``filter`` """""""""""""""""""""""""""" ``filter`` is designed for complex search conditions. You specify search conditions for ``filter`` as ECMAScript like syntax. Here is a simple ``filter`` usage example. .. groonga-command .. include:: ../example/commands/select/simple_filter.log .. select Entries --filter 'content @ "fast" && _key == "Groonga"' The ``select`` command searches records that contain a word ``fast`` in ``content`` column value and has ``Groonga`` as ``_key`` from ``Entries`` table. There are three operators in the command, ``@``, ``&&`` and ``==``. ``@`` is fulltext search operator. ``&&`` and ``==`` are the same as ECMAScript. ``&&`` is logical AND operator and ``==`` is equality operator. ``filter`` has more operators and syntax like grouping by ``(...)`` its deatils aren't described here. See :doc:`/spec/script_syntax` for datails. Paging ^^^^^^ You can specify range of outputted records by ``offset`` and ``limit``. Here is an example to output only the 2nd record. .. groonga-command .. include:: ../example/commands/select/paging.log .. select Entries --offset 1 --limit 1 ``offset`` is zero-origin. ``--offset 1`` means output range is started from the 2nd record. ``limit`` specifies the max number of output records. ``--limit 1`` means the number of output records is 1 at a maximium. If no records are matched, ``select`` command outputs no records. The total number of records ^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can use ``--limit 0`` to retrieve the total number of recrods without any contents of records. .. groonga-command .. include:: ../example/commands/select/no_limit.log .. select Entries --limit 0 ``--limit 0`` is also useful for retrieving only the number of matched records. Parameters ---------- This section describes all parameters. Parameters are categorized. Required parameter ^^^^^^^^^^^^^^^^^^ There is a required parameter, ``table``. ``table`` """"""""" It specifies a table to be searched. ``table`` must be specified. If nonexistent table is specified, an error is returned. .. groonga-command .. include:: ../example/commands/select/table_nonexistent.log .. select Nonexistent Search related parameters ^^^^^^^^^^^^^^^^^^^^^^^^^ There are search related parameters. Typically, ``match_columns`` and ``query`` parameters are used for implementing a search box. ``filter`` parameters is used for implementing complex search feature. If both ``query`` and ``filter`` are specified, selected records must be matched against both ``query`` and ``filter``. If both ``query`` and ``filter`` aren't specified, all records are selected. ``match_columns`` """"""""""""""""" It specifies the default target column for fulltext search by ``query`` parameter value. A target column for fulltext search can be specified in ``query`` parameter. The difference between ``match_columns`` and ``query`` is whether weight is supported or not. ``match_columns`` supports weight but ``query`` doesn't. Weight is relative importance of target column. A higher weight target column gets more hit score rather than a lower weight target column when a record is matched by fulltext search. The default weight is 1. Here is a simple ``match_columns`` usage example. .. groonga-command .. include:: ../example/commands/select/match_columns_simple.log .. select Entries --match_columns content --query fast --output_columns '_key, _score' ``--match_columns content`` means the default target column for fulltext search is ``content`` column and its weight is 1. ``--output_columns '_key, _score'`` means that the ``select`` command outputs ``_key`` value and ``_score`` value for matched records. Pay attention to ``_score`` value. ``_score`` value is the number of matched counts against ``query`` parameter value. In the example, ``query`` parameter value is ``fast``. The fact that ``_score`` value is 1 means that ``fast`` appers in ``content`` column only once. The fact that ``_score`` value is 2 means that ``fast`` appears in ``content`` column twice. To specify weight, ``column * weight`` syntax is used. Here is a weight usage example. .. groonga-command .. include:: ../example/commands/select/match_columns_weight.log .. select Entries --match_columns 'content * 2' --query fast --output_columns '_key, _score' ``--match_columns 'content * 2'`` means the default target column for fulltext search is ``content`` column and its weight is 2. Pay attention to ``_score`` value. ``_score`` value is doubled because weight is 2. You can specify one or more columns as the default target columns for fulltext search. If one or more columns are specified, fulltext search is done for all columns and scores are accumulated. If one of the columns is matched against ``query`` parameter value, the record is treated as matched. To specify one or more columns, ``column1 * weight1 || column2 * weight2 || ...`` syntax is used. ``* weight`` can be omitted. If it is omitted, 1 is used for weight. Here is a one or more columns usage example. .. groonga-command .. include:: ../example/commands/select/match_columns_some_columns.log .. select Entries --match_columns '_key * 10 || content' --query groonga --output_columns '_key, _score' ``--match_columns '_key * 10 || content'`` means the default target columns for fulltext search are ``_key`` and ``content`` columns and ``_key`` column's weight is 10 and ``content`` column's weight is 1. This weight allocation means ``_key`` column value is more important rather than ``content`` column value. In this example, title of blog entry is more important rather thatn content of blog entry. ``query`` """"""""" TODO: write short description and add example. See :doc:`/spec/query_syntax`. ``filter`` """""""""" TODO: write short description and add example. See :doc:`/spec/script_syntax`. Advanced search parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^ ``match_escalation_threshold`` """""""""""""""""""""""""""""" TODO: add example. It specifies threshold to determine whether search storategy escalation is used or not. The threshold is compared against the number of matched records. If the number of matched records is equal to or less than the threshold, search storategy escalation is used. See :doc:`/spec/search` about search storategy escalation. The default threshold is 0. It means that search storategy escalation is used only when no records are matched. The default threshold can be customized by one of the followings. * ``--with-match-escalation-threshold`` option of configure * ``--match-escalation-threshold`` option of groogna command * ``match-escalation-threshold`` configuration item in configuration file ``query_expansion`` """"""""""""""""""" TODO: write in English and add example. It specifies a column that is used to expand (substitute) ``query`` parameter value. query_expansionパラメータには、queryパラメータに指定された文字列を置換(拡張)する条件となるテーブル・カラムを指定します。フォーマットは「${テーブル名}.${カラム名}」となります。指定するテーブルは文字列を主キーとするハッシュ型あるいはパトリシア木型のテーブルで、一つ以上の文字列型のカラムが定義されている必要があります。(ここでは置換テーブルと呼びます。) queryパラメータに指定された文字列が、指定されたテーブルの主キーと完全一致する場合、その文字列を指定されたカラム値の文字列に置換します。queryパラメータが、空白、括弧、演算子などを含む場合は、その演算子によって区切られた文字列の単位で置換が実行されます。ダブルクォート("")で括られた範囲は、その内部に空白を含んでいても一つの置換される単位と見なされます。検索文字列と置換テーブルの主キー値との比較に際して大文字小文字等を区別したくない場合には、置換テーブルを定義する際にKEY_NORMALIZEを指定します。置換後の文字列となるカラムの値には、括弧や*, ORなど、queryパラメータで利用可能な全ての演算子を指定することができます。 Output related parameters ^^^^^^^^^^^^^^^^^^^^^^^^^ ``output_columns`` """""""""""""""""" TODO: write in English and add example. 出力するカラム名のリストをカンマ(',')区切りで指定します。 アスタリスク('*')を指定すると、全てのカラムが指定されたものとみなされます。または、script形式のgrn_expr文字列を指定します。 (デフォルトは、'_id, _key, \*') ``sortby`` """""""""" TODO: write in English and add example. ソートキーとなるカラム名のリストをカンマ(',')区切りで指定します。:: [-]カラム名1, [-]カラム名2, [-]カラム名3, ... カラム名1の値でソートし、値が同一である場合はカラム名2でソート、と順次比較を行いソートします。カラム名の前に - を付加した場合は降順にソートします。付加しない場合には昇順にソートします。 query引数またはfilter引数を指定した場合はカラム名に'_score'を使えます。'_score'を指定することでスコアでソートすることができます。query引数もfilter引数も指定していない状態で'_score'を指定するとエラーになります。 ``offset`` """""""""" TODO: write in English and add example. 検索条件にマッチしたレコードのうち、出力対象となる最初のレコードの番号を0ベースで指定します。デフォルト値は0です。offsetに負の値を指定した場合は、ヒットした件数 + offset によって算出される値が指定されたものとみなされます。 ``limit`` """"""""" TODO: write in English and add example. 検索条件にマッチしたレコードのうち、出力を行うレコードの件数を指定します。デフォルト値は10です。実際には、offset + limit がヒットした件数を超えない範囲でレコードが出力されます。limitに負の値を指定した場合は、ヒットした件数 + limit + 1 によって算出される値が指定されたものとみなされます。 ``scorer`` """""""""" TODO: write in English and add example. 検索条件にマッチする全てのレコードに対して適用するgrn_exprをscript形式で指定します。 scorerは、検索処理が完了し、ソート処理が実行される前に呼び出されます。従って、各レコードのスコアを操作する式を指定しておけば、検索結果のソート順序をカスタマイズできるようになります。 Facet related parameters ^^^^^^^^^^^^^^^^^^^^^^^^ ``drilldown`` """"""""""""" TODO: write in English and add example. グループ化のキーとなるカラム名のリストをカンマ(',')区切りで指定します。検索条件にマッチした各レコードを出力したのちに、drilldownに指定されたカラムの値が同一であるレコードをとりまとめて、それぞれについて結果レコードを出力します。 ``drilldown_sortby`` """""""""""""""""""" TODO: write in English and add example. drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、ソートキーとなるカラム名のリストをカンマ(',')区切りで指定します。sortbyパラメータと同様に昇降順を指定できます。 ``drilldown_output_columns`` """""""""""""""""""""""""""" TODO: write in English and add example. drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、出力するカラム名のリストをカンマ(',')区切りで指定します。 ``drilldown_offset`` """""""""""""""""""" TODO: write in English and add example. drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、出力対象となる最初のレコードの番号を0ベースで指定します。デフォルト値は0です。drilldown_offsetに負の値を指定した場合は、ヒットした件数 + drilldown_offsetによって算出される値が指定されたものとみなされます。 ``drilldown_limit`` """"""""""""""""""" TODO: write in English and add example. drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、出力を行うレコードの件数を指定します。デフォルト値は10です。実際には、drilldown_offset + drilldown_limit がヒットした件数を超えない範囲でレコードが出力されます。drilldown_limitに負の値を指定した場合は、ヒットした件数 + drilldown_limit + 1 によって算出される値が指定されたものとみなされます。 Cache related parameter ^^^^^^^^^^^^^^^^^^^^^^^ ``cache`` """"""""" TODO: write in English and add example. クエリキャッシュに関する動作を設定します。 ``no`` 検索結果をクエリキャッシュに残しません。キャッシュして再利用される可能性が低いクエリに対して用います。キャッシュ容量は有限です。有効なキャッシュが多くヒットするために、このパラメータは有効です。 返値 ---- 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によって指定された条件に従って各レコードの値が出力されます。 See also -------- * :doc:`/spec/query_syntax` * :doc:`/spec/script_syntax`