.. -*- 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] [query_flags=ALLOW_PRAGMA|ALLOW_COLUMN|ALLOW_UPDATE|ALLOW_LEADING_NOT|NONE] 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/reference/commands/select/usage_setup.log .. table_create Entries TABLE_HASH_KEY ShortText .. column_create Entries content COLUMN_SCALAR Text .. column_create Entries n_likes COLUMN_SCALAR UInt32 .. 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!", .. "n_likes": 5}, .. {"_key": "Groonga", .. "content": "I started to use groonga. It's very fast!", .. "n_likes": 10}, .. {"_key": "Mroonga", .. "content": "I also started to use mroonga. It's also very fast! Really fast!", .. "n_likes": 15}, .. {"_key": "Good-bye Senna", .. "content": "I migrated all Senna system!", .. "n_likes": 3}, .. {"_key": "Good-bye Tritonn", .. "content": "I also migrated all Tritonn system!", .. "n_likes": 3} .. ] There is a table, ``Entries``, for blog entries. An entry has title, content and the number of likes for the entry. Title is key of ``Entries``. Content is value of ``Entries.content`` column. The number of likes is value of ``Entries.n_likes`` 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 schema and data. It outputs all records in ``Entries`` table. .. groonga-command .. include:: ../../example/reference/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 5. ``select`` command outputs 10 records at a maximum by default. There are only 5 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/reference/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:`/reference/grn_expr/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/reference/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:`/reference/grn_expr/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/reference/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/reference/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/reference/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/reference/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/reference/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/reference/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`` """"""""" It specifies the query text. Normally, it is used for fulltext search with ``match_columns`` parameter. ``query`` parameter is designed for a fulltext search form in a Web page. A query text should be formatted in :doc:`/reference/grn_expr/query_syntax`. The syntax is similar to common search form like Google's search form. For example, ``word1 word2`` means that groonga searches records that contain both ``word1`` and ``word2``. ``word1 OR word2`` means that groogna searches records that contain either ``word1`` or ``word2``. Here is a simple logical and search example. .. groonga-command .. include:: ../../example/reference/commands/select/query_and.log .. select Entries --match_columns content --query "fast groonga" The ``select`` command searches records that contain two words ``fast`` and ``groonga`` in ``content`` column value from ``Entries`` table. Here is a simple logical or search example. .. groonga-command .. include:: ../../example/reference/commands/select/query_or.log .. select Entries --match_columns content --query "groonga OR mroonga" The ``select`` command searches records that contain one of two words ``groonga`` or ``mroonga`` in ``content`` column value from ``Entries`` table. See :doc:`/reference/grn_expr/query_syntax` for other syntax. It can be used for not only fulltext search but also other conditions. For example, ``column:value`` means the value of ``column`` column is equal to ``value``. ``column:=10"]} .. ] .. select Entries --match_columns content --query "popular" --query_expansion Thesaurus.synonym The ``load`` command registers a new synonym ``"popular"``. It is substituted with ``((popular) OR (n_likes:>=10))``. The substituted query means that "popular" is containing the word "popular" or 10 or more liked entries. The ``select`` command outputs records that ``n_likes`` column value is equal to or more than ``10`` from ``Entries`` table. .. _query-flags: ``query_flags`` """"""""""""""" It customs ``query`` parameter syntax. You cannot update column value by ``query`` parameter by default. But if you specify ``ALLOW_COLUMN|ALLOW_UPDATE`` as ``query_flags``, you can update column value by ``query``. Here are available values: * ``ALLOW_PRAGMA`` * ``ALLOW_COLUMN`` * ``ALLOW_UPDATE`` * ``ALLOW_LEADING_NOT`` * ``NONE`` ``ALLOW_PRAGMA`` enables pragma at the head of ``query``. This is not implemented yet. ``ALLOW_COLUMN`` enables search againt columns that are not included in ``match_columns``. To specify column, there are ``COLUMN:...`` syntaxes. ``ALLOW_UPDATE`` enables column update by ``query`` with ``COLUMN:=NEW_VALUE`` syntax. ``ALLOW_COLUMN`` is also required to update column because the column update syntax specifies column. ``ALLOW_LEADING_NOT`` enables leading NOT condition with ``-WORD`` syntax. The query searches records that doesn't match ``WORD``. Leading NOT condition query is heavy query in many cases because it matches many records. So this flag is disabled by default. Be careful about it when you use the flag. ``NONE`` is just ignores. You can use ``NONE`` for specifying no flags. They can be combined by separated ``|`` such as ``ALLOW_COLUMN|ALLOW_UPDATE``. The default value is ``ALLOW_PRAGMA|ALLOW_COLUMN``. Here is a usage example of ``ALLOW_COLUMN``. .. groonga-command .. include:: ../../example/reference/commands/select/query_flags_allow_column.log .. select Entries --query content:@mroonga --query_flags ALLOW_COLUMN The ``select`` command searches records that contain ``mroonga`` in ``content`` column value from ``Entries`` table. Here is a usage example of ``ALLOW_UPDATE``. .. groonga-command .. include:: ../../example/reference/commands/select/query_flags_allow_update.log .. table_create Users TABLE_HASH_KEY ShortText .. column_create Users age COLUMN_SCALAR UInt32 .. load --table Users .. [ .. {"_key": "alice", "age": 18}, .. {"_key": "bob", "age": 20} .. ] .. select Users --query age:=19 --query_flags ALLOW_COLUMN|ALLOW_UPDATE .. select Users The first ``select`` command sets ``age`` column value of all records to ``19``. The second ``select`` command outputs updated ``age`` column values. Here is a usage example of ``ALLOW_LEADING_NOT``. .. groonga-command .. include:: ../../example/reference/commands/select/query_flags_allow_leading_not.log .. select Entries --match_columns content --query -mroonga --query_flags ALLOW_LEADING_NOT The ``select`` command searches records that don't contain ``mroonga`` in ``content`` column value from ``Entries`` table. Here is a usage example of ``NONE``. .. groonga-command .. include:: ../../example/reference/commands/select/query_flags_none.log .. select Entries --match_columns content --query 'mroonga OR _key:Groonga' --query_flags NONE The ``select`` command searches records that contain one of two words ``mroonga`` or ``_key:Groonga`` in ``content`` from ``Entries`` table. Note that ``_key:Groonga`` doesn't mean that the value of ``_key`` column is equal to ``Groonga``. Because ``ALLOW_COLUMN`` flag is not specified. See also :doc:`/reference/grn_expr/query_syntax`. Output related parameters ^^^^^^^^^^^^^^^^^^^^^^^^^ ``output_columns`` """""""""""""""""" It specifies output columns separated by ``,``. Here is a simple ``output_columns`` usage example. .. groonga-command .. include:: ../../example/reference/commands/select/output_columns_simple.log .. select Entries --output_columns '_id, _key' --limit 1 The ``select`` command just outputs ``_id`` and ``_key`` column values. ``*`` is a special value. It means that all columns that are not :doc:`/reference/pseudo_column`. Here is a ``*`` usage example. .. groonga-command .. include:: ../../example/reference/commands/select/output_columns_asterisk.log .. select Entries --output_columns '_key, *' --limit 1 The ``select`` command outputs ``_key`` pseudo column, ``content`` column and ``n_likes`` column values but doesn't output ``_id`` pseudo column value. The default value is ``_id, _key, *``. It means that all column values except ``_score`` are outputted. ``sortby`` """""""""" It specifies sort keys separated by ``,``. Each sort key is column name. Here is a simple ``sortby`` usage example. .. groonga-command .. include:: ../../example/reference/commands/select/sortby_simple.log .. select Entries --sortby 'n_likes, _id' The ``select`` command sorts by ``n_likes`` column value in ascending order. For records that has the same ``n_likes`` are sorted by ``_id`` in ascending order. ``"Good-bye Senna"`` and ``"Good-bye Tritonn"`` are the case. If you want to sort in descending order, add ``-`` before column name. Here is a descending order ``sortby`` usage example. .. groonga-command .. include:: ../../example/reference/commands/select/sortby_descending.log .. select Entries --sortby '-n_likes, _id' The ``select`` command sorts by ``n_likes`` column value in descending order. But ascending order is used for sorting by ``_id``. You can use ``_score`` pseudo column in ``sortby`` if you use ``query`` or ``filter`` parameter. .. groonga-command .. include:: ../../example/reference/commands/select/sortby_score_with_query.log .. select Entries --match_columns content --query fast --sortby -_score --output_columns '_key, _score' The ``select`` command sorts matched records by hit score in descending order and outputs record key and hit score. If you use ``_score`` without ``query`` nor ``filter`` parameters, it's just ignored but get a warning in log file. ``offset`` """""""""" It specifies offset to determine output records range. Offset is zero-origin. ``--offset 1`` means output range is started from the 2nd record. .. groonga-command .. include:: ../../example/reference/commands/select/offset_simple.log .. select Entries --sortby _id --offset 3 --output_columns _key The ``select`` command outputs from the 4th record. You can specify negative value. It means that ``the number of matched records + offset``. If you have 3 matched records and specify ``--offset -2``, you get records from the 1st (``3 + -2 = 1``) record to the 3rd record. .. groonga-command .. include:: ../../example/reference/commands/select/offset_negative.log .. select Entries --sortby _id --offset -2 --output_columns _key The ``select`` command outputs from the 4th record because the total number of records is ``5``. The default value is ``0``. ``limit`` """"""""" It specifies the max number of output records. If the number of matched records is less than ``limit``, all records are outputted. Here is a simple ``limit`` usage example. .. groonga-command .. include:: ../../example/reference/commands/select/limit_simple.log .. select Entries --sortby _id --offset 2 --limit 3 --output_columns _key The ``select`` command outputs the 3rd, the 4th and the 5th records. You can specify negative value. It means that ``the number of matched records + limit + 1``. For example, ``--limit -1`` outputs all records. It's very useful value to show all records. Here is a simple negative ``limit`` value usage example. .. groonga-command .. include:: ../../example/reference/commands/select/limit_negative.log .. select Entries --limit -1 The ``select`` command outputs all records. The default value is ``10``. ``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:`/reference/grn_expr/query_syntax` * :doc:`/reference/grn_expr/script_syntax`