rroonga 2.0.4-x86-mingw32 → 2.0.7-x86-mingw32

data/vendor/local/share/doc/groonga/source/reference/commands/select.txt

@@ -0,0 +1,892 @@
+.. -*- 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:<value`` means the
+value of ``column`` column is less than ``value``.
+
+Here is a simple equality operator search example.
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/query_equal.log
+.. select Entries --query _key:Groonga
+
+The ``select`` command searches records that ``_key`` column value is
+``Groonga`` from ``Entries`` table.
+
+Here is a simple less than operator search example.
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/query_less_than.log
+.. select Entries --query n_likes:<11
+
+The ``select`` command searches records that ``n_likes`` column value
+is less than ``11`` from ``Entries`` table.
+
+See :doc:`/reference/grn_expr/query_syntax` for other operations.
+
+``filter``
+""""""""""
+
+It specifies the filter text. Normally, it is used for complex search
+conditions. ``filter`` can be used with ``query`` parameter. If both
+``filter`` and ``query`` are specified, there are conbined with
+logical and. It means that matched records should be matched against
+both ``filter`` and ``query``.
+
+``filter`` parameter is designed for complex conditions. A filter text
+should be formated in :doc:`/reference/grn_expr/script_syntax`. The syntax is
+similar to ECMAScript. For example, ``column == "value"`` means that
+the value of ``column`` column is equal to ``"value"``. ``column <
+value`` means that the value of ``column`` column is less than
+``value``.
+
+Here is a simple equality operator search example.
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/filter_equal.log
+.. select Entries --filter '_key == "Groonga"'
+
+The ``select`` command searches records that ``_key`` column value is
+``Groonga`` from ``Entries`` table.
+
+Here is a simple less than operator search example.
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/filter_less_than.log
+.. select Entries --filter 'n_likes < 11'
+
+The ``select`` command searches records that ``n_likes`` column value
+is less than ``11`` from ``Entries`` table.
+
+See :doc:`/reference/grn_expr/script_syntax` for other operators.
+
+Advanced search parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. _match-escalation-threshold:
+
+``match_escalation_threshold``
+""""""""""""""""""""""""""""""
+
+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, the search storategy escalation is
+used. See :doc:`/spec/search` about the 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
+
+Here is a simple ``match_escalation_threshold`` usage example. The
+first ``select`` doesn't have ``match_escalation_threshold``
+parameter. The second ``select`` has ``match_escalation_threshold``
+parameter.
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/match_escalation_threshold.log
+.. select Entries --match_columns content --query groo
+.. select Entries --match_columns content --query groo --match_escalation_threshold -1
+
+The first ``select`` command searches records that contain a word
+``groo`` in ``content`` column value from ``Entries`` table. But no
+records are matched because the ``TokenBigram`` tokenizer tokenizes
+``groonga`` to ``groonga`` not ``gr|ro|oo|on|ng|ga``. (The
+``TokenBigramSplitSymbolAlpha`` tokenizer tokenizes ``groonga`` to
+``gr|ro|oo|on|ng|ga``. See :doc:`/reference/tokenizers` for details.)
+It means that ``groonga`` is indexed but ``groo`` isn't indexed. So no
+records are matched against ``groo`` by exact match. In the case, the
+search storategy escalation is used because the number of matched
+records (0) is equal to ``match_escalation_threshold`` (0). One record
+is matched against ``groo`` by unsplit search.
+
+The second ``select`` command also searches records that contain a
+word ``groo`` in ``content`` column value from ``Entries`` table. And
+it also doesn't found matched records. In this case, the search
+storategy escalation is not used because the number of matched
+records (0) is larger than ``match_escalation_threshold`` (-1). So no
+more searches aren't executed. And no records are matched.
+
+``query_expansion``
+"""""""""""""""""""
+
+It's for query expansion. Query expansion substitutes specific words
+to another words in query. Nomally, it's used for synonym search.
+
+It specifies a column that is used to substitute ``query`` parameter
+value. The format of this parameter value is
+"``${TABLE}.${COLUMN}``". For example, "``Terms.synonym``" specifies
+``synonym`` column in ``Terms`` table.
+
+Table for query expansion is called "substitution table". Substitution
+table's key must be ``ShortText``. So array table (``TABLE_NO_KEY``)
+can't be used for query expansion. Because array table doesn't have
+key.
+
+Column for query expansion is called "substitution
+column". Substitution column's value type must be
+``ShortText``. Column type must be vector (``COLUMN_VECTOR``).
+
+Query expansion substitutes key of substitution table in query with
+values in substitution column. If a word in ``query`` is a key of
+substitution table, the word is substituted with substitution column
+value that is associated with the key. Substition isn't performed
+recursively. It means that substitution target words in substituted
+query aren't substituted.
+
+Here is a sample substitution table to show a simple
+``query_expansion`` usage example.
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/query_expansion_substitution_table.log
+.. table_create Thesaurus TABLE_PAT_KEY|KEY_NORMALIZE ShortText
+.. column_create Thesaurus synonym COLUMN_VECTOR ShortText
+.. load --table Thesaurus
+.. [
+.. {"_key": "mroonga", "synonym": ["mroonga", "tritonn", "groonga mysql"]},
+.. {"_key": "groonga", "synonym": ["groonga", "senna"]}
+.. ]
+
+``Thesaurus`` substitution table has two synonyms, ``"mroonga"`` and
+``"groonga"``. If an user searches with ``"mroonga"``, groonga
+searches with ``"((mroonga) OR (tritonn) OR (groonga mysql))"``. If an
+user searches with ``"groonga"``, groonga searchs with ``"((groonga)
+OR (senna))"``. Nomrally, it's good idea that substitution table has
+``KEY_NORMALIZE`` flag. If the flag is used, substitute target word is
+matched in case insensitive manner.
+
+Note that those synonym values include the key value such as
+``"mroonga"`` and ``"groonga"``. It's recommended that you include the
+key value. If you don't include key value, substituted value doesn't
+include the original substitute target value. Normally, including the
+original value is better search result. If you have a word that you
+don't want to be searched, you should not include the original
+word. For example, you can implement "stop words" by an empty vector
+value.
+
+Here is a simple ``query_expansion`` usage example.
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/query_expansion_substitute.log
+.. select Entries --match_columns content --query "mroonga"
+.. select Entries --match_columns content --query "mroonga" --query_expansion Thesaurus.synonym
+.. select Entries --match_columns content --query "((mroonga) OR (tritonn) OR (groonga mysql))"
+
+The first ``select`` command doesn't use query expansion. So a record
+that has ``"tritonn"`` isn't found. The second ``select`` command uses
+query expansion. So a record that has ``"tritonn"`` is found. The
+third ``select`` command doesn't use query expansion but it is same as
+the second ``select`` command. The third one uses expanded query.
+
+Each substitute value can contain any :doc:`/reference/grn_expr/query_syntax` syntax
+such as ``(...)`` and ``OR``. You can use complex substitution by
+using those syntax.
+
+Here is a complex substitution usage example that uses query syntax.
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/query_expansion_complex.log
+.. load --table Thesaurus
+.. [
+.. {"_key": "popular", "synonym": ["popular", "n_likes:>=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`