rroonga 4.0.8-x86-mingw32 → 5.0.0-x86-mingw32

data/vendor/local/share/doc/groonga/en/html/_sources/reference.txt

@@ -19,7 +19,6 @@ Reference manual
    reference/tokenizers
    reference/token_filters
    reference/query_expanders
-   reference/pseudo_column
    reference/grn_expr
    reference/function
    reference/operations

data/vendor/local/share/doc/groonga/en/html/_sources/reference/api/grn_ctx.txt

@@ -52,7 +52,9 @@ Reference
 
    ctxの管理するメモリを解放し、使用を終了します。
 
-   If ``ctx`` is initialized by :c:func:`grn_ctx_open()` not :c:func:`grn_ctx_init()`. You need also to call :c:func:`grn_ctx_close()`.
+   If ``ctx`` is initialized by :c:func:`grn_ctx_open()` not
+   :c:func:`grn_ctx_init()`, you need to use
+   :c:func:`grn_ctx_close()` instead of :c:func:`grn_ctx_fin()`.
 
    :param ctx: 解放するctx構造体へのポインタを指定します。
    :return: ``GRN_SUCCESS`` on success, not ``GRN_SUCCESS`` on error.

data/vendor/local/share/doc/groonga/en/html/_sources/reference/column.txt

@@ -17,10 +17,18 @@ must be a table.
 
 Here are data store columns:
 
-  * :doc:`columns/scalar`
-  * :doc:`columns/vector`
-  * :doc:`columns/pseudo`
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   columns/scalar
+   columns/vector
+   columns/pseudo
 
 Here is an index column:
 
-  * :doc:`columns/index`
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   columns/index

data/vendor/local/share/doc/groonga/en/html/_sources/reference/columns/index.txt

@@ -0,0 +1,19 @@
+.. -*- rst -*-
+
+.. highlightlang:: none
+
+.. groonga-command
+.. database: columns_index
+
+Index column
+============
+
+Summary
+-------
+
+TODO
+
+Usage
+-----
+
+TODO

data/vendor/local/share/doc/groonga/en/html/_sources/reference/columns/pseudo.txt

@@ -2,8 +2,8 @@
 
 .. highlightlang:: none
 
-疑似カラム (pseudo_column)
-==========================
+Pseudo column
+=============
 
 名前
 ----

data/vendor/local/share/doc/groonga/en/html/_sources/reference/columns/scalar.txt

@@ -0,0 +1,19 @@
+.. -*- rst -*-
+
+.. highlightlang:: none
+
+.. groonga-command
+.. database: columns_scalar
+
+Scalar column
+=============
+
+Summary
+-------
+
+TODO
+
+Usage
+-----
+
+TODO

data/vendor/local/share/doc/groonga/en/html/_sources/reference/commands/select.txt

@@ -43,6 +43,35 @@ Syntax
          [query_flags=ALLOW_PRAGMA|ALLOW_COLUMN|ALLOW_UPDATE|ALLOW_LEADING_NOT|NONE]
          [query_expander=null]
          [adjuster=null]
+         [drilldown_calc_types=NONE]
+         [drilldown_calc_target=null]
+
+``select`` has the following named parameters for advanced drilldown:
+
+  * ``drilldown[${LABEL}].keys=null``
+  * ``drilldown[${LABEL}].sortby=null``
+  * ``drilldown[${LABEL}].output_columns="_key, _nsubrecs"``
+  * ``drilldown[${LABEL}].offset=0``
+  * ``drilldown[${LABEL}].limit=10``
+  * ``drilldown[${LABEL}].calc_types=NONE``
+  * ``drilldown[${LABEL}].calc_target=null``
+
+You can use one or more alphabets, digits, ``_`` and ``.`` for
+``${LABEL}``. For example, ``parent.sub1`` is a valid ``${LABEL}``.
+
+Parameters that have the same ``${LABEL}`` are grouped.
+
+For example, the following parameters specify one drilldown:
+
+  * ``--drilldown[label].keys column``
+  * ``--drilldown[label].sortby -_nsubrecs``
+
+The following parameters specify two drilldowns:
+
+  * ``--drilldown[label1].keys column1``
+  * ``--drilldown[label1].sortby -_nsubrecs``
+  * ``--drilldown[label2].keys column2``
+  * ``--drilldown[label2].sortby _key``
 
 Usage
 -----
@@ -57,6 +86,7 @@ Here are a schema definition and sample data to show usage.
 .. table_create Entries TABLE_HASH_KEY ShortText
 .. column_create Entries content COLUMN_SCALAR Text
 .. column_create Entries n_likes COLUMN_SCALAR UInt32
+.. column_create Entries tag COLUMN_SCALAR ShortText
 .. 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
@@ -64,25 +94,31 @@ Here are a schema definition and sample data to show usage.
 .. [
 .. {"_key":    "The first post!",
 ..  "content": "Welcome! This is my first post!",
-..  "n_likes": 5},
+..  "n_likes": 5,
+..  "tag": "Hello"},
 .. {"_key":    "Groonga",
-..  "content": "I started to use groonga. It's very fast!",
-..  "n_likes": 10},
+..  "content": "I started to use Groonga. It's very fast!",
+..  "n_likes": 10,
+..  "tag": "Groonga"},
 .. {"_key":    "Mroonga",
-..  "content": "I also started to use mroonga. It's also very fast! Really fast!",
-..  "n_likes": 15},
+..  "content": "I also started to use Mroonga. It's also very fast! Really fast!",
+..  "n_likes": 15,
+..  "tag": "Groonga"},
 .. {"_key":    "Good-bye Senna",
 ..  "content": "I migrated all Senna system!",
-..  "n_likes": 3},
+..  "n_likes": 3,
+..  "tag": "Senna"},
 .. {"_key":    "Good-bye Tritonn",
 ..  "content": "I also migrated all Tritonn system!",
-..  "n_likes": 3}
+..  "n_likes": 3,
+..  "tag": "Senna"}
 .. ]
 
 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
+content, the number of likes for the entry and tag. Title is key of
 ``Entries``. Content is value of ``Entries.content`` column. The
-number of likes is value of ``Entries.n_likes`` column.
+number of likes is value of ``Entries.n_likes`` column. Tag is value
+of ``Entries.tag`` column.
 
 ``Entries._key`` column and ``Entries.content`` column are indexed
 using ``TokenBigram`` tokenizer. So both ``Entries._key`` and
@@ -163,8 +199,8 @@ in ``content`` column value and has ``Groonga`` as ``_key`` from
 ``==`` 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.
+its details aren't described here. See
+:doc:`/reference/grn_expr/script_syntax` for datails.
 
 Paging
 ^^^^^^
@@ -176,7 +212,7 @@ Here is an example to output only the 2nd record.
 .. include:: ../../example/reference/commands/select/paging.log
 .. select Entries --offset 1 --limit 1
 
-``offset`` is zero-origin. ``--offset 1`` means output range is
+``offset`` is zero-based. ``--offset 1`` means output range is
 started from the 2nd record.
 
 ``limit`` specifies the max number of output records. ``--limit 1``
@@ -196,6 +232,56 @@ without any contents of records.
 ``--limit 0`` is also useful for retrieving only the number of matched
 records.
 
+Drilldown
+^^^^^^^^^
+
+You can get additional grouped results against the search result in
+one ``select``. You need to use two or more ``SELECT``s in SQL but
+``select`` in Groonga can do it in one ``select``.
+
+This feature is called as `drilldown
+<http://en.wikipedia.org/wiki/Drill_down>`_ in Groonga. It's also
+called as `faceted search
+<http://en.wikipedia.org/wiki/Faceted_search>`_ in other search
+engine.
+
+For example, think about the following situation.
+
+You search entries that has ``fast`` word:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/usage_drilldown_only_query.log
+.. select Entries --filter 'content @ "fast"'
+
+You want to use ``tag`` for additional search condition like
+``--filter 'content @ "fast" && tag == "???"``. But you don't know
+suitable tag until you see the result of ``content @ "fast"``.
+
+If you know the number of matched records of each available tag, you
+can choose suitable tag. You can use drilldown for the case:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/usage_drilldown.log
+.. select Entries --filter 'content @ "fast"' --drilldown tag
+
+``--drilldown tag`` returns a list of pair of available tag and the
+number of matched records. You can avoid "no hit search" case by
+choosing a tag from the list. You can also avoid "too many search
+results" case by choosing a tag that the number of matched records is
+few from the list.
+
+You can create the following UI with the drilldown results:
+
+  * Links to narrow search results. (Users don't need to input a
+    search query by their keyboard. They just click a link.)
+
+Most EC sites use the UI. See side menu at Amazon.
+
+Groonga supports not only counting grouped records but also finding
+the maximum and/or minimum value from grouped records, summing values
+in grouped records and so on. See
+:ref:`select-drilldown-related-parameters` for details.
+
 Parameters
 ----------
 
@@ -646,11 +732,10 @@ more liked entries.
 The ``select`` command outputs records that ``n_likes`` column value
 is equal to or more than ``10`` from ``Entries`` table.
 
-
 Output related parameters
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. _output_columns:
+.. _select-output-columns:
 
 ``output_columns``
 """"""""""""""""""
@@ -682,6 +767,8 @@ column value.
 The default value is ``_id, _key, *``. It means that all column
 values except ``_score`` are outputted.
 
+.. _select-sortby:
+
 ``sortby``
 """"""""""
 
@@ -723,11 +810,13 @@ 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.
 
+.. _select-offset:
+
 ``offset``
 """"""""""
 
 It specifies offset to determine output records range. Offset is
-zero-origin. ``--offset 1`` means output range is started from the 2nd
+zero-based. ``--offset 1`` means output range is started from the 2nd
 record.
 
 .. groonga-command
@@ -738,8 +827,9 @@ 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.
+``--offset -2``, you get records from the 2nd (``3 + -2 = 1``. ``1``
+means 2nd. Remember that offset is zero-based.) record to the 3rd
+record.
 
 .. groonga-command
 .. include:: ../../example/reference/commands/select/offset_negative.log
@@ -787,43 +877,658 @@ TODO: write in English and add example.
 
 scorerは、検索処理が完了し、ソート処理が実行される前に呼び出されます。従って、各レコードのスコアを操作する式を指定しておけば、検索結果のソート順序をカスタマイズできるようになります。
 
-Facet related parameters
-^^^^^^^^^^^^^^^^^^^^^^^^
+.. _select-drilldown-related-parameters:
+
+Drilldown related parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section describes basic drilldown related parameters. Advanced
+drilldown related parameters are described in another section.
+
+.. _select-drilldown:
 
 ``drilldown``
 """""""""""""
 
-TODO: write in English and add example.
+It specifies keys for grouping separated by ``,``.
+
+Matched records by specified search conditions are grouped by each
+key. If you specify no search condition, all records are grouped by
+each key.
+
+Here is a simple ``drilldown`` example:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_simple.log
+.. select Entries \
+..   --output_columns _key,tag \
+..   --drilldown tag
+
+The ``select`` command outputs the following information:
+
+  * There is one record that has "Hello" tag.
+  * There is two records that has "Groonga" tag.
+  * There is two records that has "Senna" tag.
+
+Here is a ``drilldown`` with search condition example:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_filter.log
+.. select Entries \
+..   --output_columns _key,tag \
+..   --filter 'n_likes >= 5' \
+..   --drilldown tag
+
+The ``select`` command outputs the following information:
+
+  * In records that have 5 or larger as ``n_likes`` value:
 
-グループ化のキーとなるカラム名のリストをカンマ(',')区切りで指定します。検索条件にマッチした各レコードを出力したのちに、drilldownに指定されたカラムの値が同一であるレコードをとりまとめて、それぞれについて結果レコードを出力します。
+    * There is one record that has "Hello" tag.
+    * There is two records that has "Groonga" tag.
+
+Here is a ``drilldown`` with multiple group keys example:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_multiple.log
+.. select Entries \
+..   --limit 0 \
+..   --output_column _id \
+..   --drilldown tag,n_likes
+
+The ``select`` command outputs the following information:
+
+  * About ``tag``:
+
+    * There is one record that has "Hello" tag.
+    * There is two records that has "Groonga" tag.
+    * There is two records that has "Senna" tag.
+
+  * About ``n_likes``:
+
+    * There is one record that has "Hello" tag.
+    * There is two records that has "Groonga" tag.
+    * There is two records that has "Senna" tag.
+
+.. _select-drilldown-sortby:
 
 ``drilldown_sortby``
 """"""""""""""""""""
 
-TODO: write in English and add example.
+It specifies sort keys for drilldown outputs separated by ``,``. Each
+sort key is column name.
+
+You can refer the number of grouped records by ``_nsubrecs``
+:doc:`/reference/columns/pseudo`.
+
+Here is a simple ``drilldown_sortby`` example:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_sortby_simple.log
+.. select Entries \
+..   --limit 0 \
+..   --output_column _id \
+..   --drilldown tag \
+..   --drilldown_sortby '-_nsubrecs, _key'
+
+Drilldown result is sorted by the number of grouped records (=
+``_nsubrecs`` ) in descending order. If there are grouped results that
+the number of records in the group are the same, these grouped results
+are sorted by grouped key (= ``_key`` ) in ascending order.
+
+The sort keys are used in all group keys specified in ``drilldown``:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_sortby_simple.log
+.. select Entries \
+..   --limit 0 \
+..   --output_column _id \
+..   --drilldown 'tag, n_likes' \
+..   --drilldown_sortby '-_nsubrecs, _key'
+
+The same sort keys are used in ``tag`` drilldown and ``n_likes``
+drilldown.
+
+If you want to use different sort keys for each drilldown, use
+:ref:`select-advanced-drilldown-related-parameters`.
 
-drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、ソートキーとなるカラム名のリストをカンマ(',')区切りで指定します。sortbyパラメータと同様に昇降順を指定できます。
+.. _select-drilldown-output-columns:
 
 ``drilldown_output_columns``
 """"""""""""""""""""""""""""
 
-TODO: write in English and add example.
+It specifies output columns for drilldown separated by ``,``.
+
+Here is a ``drilldown_output_columns`` example:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_output_columns_simple.log
+.. select Entries \
+..   --limit 0 \
+..   --output_column _id \
+..   --drilldown tag \
+..   --drilldown_output_columns _key
+
+The ``select`` command just outputs grouped key.
+
+If grouped key is a referenced type column (= column that its type is
+a table), you can access column of the table referenced by the
+referenced type column.
+
+Here are a schema definition and sample data to show drilldown against
+referenced type column:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_output_columns_referenced_type_column_definition.log
+.. table_create Tags TABLE_HASH_KEY ShortText --normalizer NormalizerAuto
+.. column_create Tags label COLUMN_SCALAR ShortText
+.. column_create Tags priority COLUMN_SCALAR Int32
+..
+.. table_create Items TABLE_HASH_KEY ShortText
+.. column_create Items tag COLUMN_SCALAR Tags
+..
+.. load --table Tags
+.. [
+.. {"_key": "groonga", label: "Groonga", priority: 10},
+.. {"_key": "mroonga", label: "Mroonga", priority: 5}
+.. ]
+..
+.. load --table Items
+.. [
+.. {"_key": "A", "tag": "groonga"},
+.. {"_key": "B", "tag": "groonga"},
+.. {"_key": "C", "tag": "mroonga"}
+.. ]
+
+``Tags`` table is a referenced table. ``Items.tag`` is a referenced
+type column.
 
-drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、出力するカラム名のリストをカンマ(',')区切りで指定します。
+You can refer ``Tags.label`` by ``label`` in
+``drilldown_output_columns``:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_output_columns_referenced_type_column_label.log
+.. select Items \
+..   --limit 0 \
+..   --output_column _id \
+..   --drilldown tag \
+..   --drilldown_output_columns '_key, label'
+
+You can use ``*`` to refer all columns in referenced table (= ``Tags``):
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_output_columns_referenced_type_column_asterisk.log
+.. select Items \
+..   --limit 0 \
+..   --output_column _id \
+..   --drilldown tag \
+..   --drilldown_output_columns '_key, *'
+
+``*`` is expanded to ``label, priority``.
+
+The default value of ``drilldown_output_columns`` is ``_key,
+_nsubrecs``. It means that grouped key and the number of records in
+the group are output.
+
+You can use more :doc:`/reference/columns/pseudo` in
+``drilldown_output_columns`` such as ``_max``, ``_min``, ``_sum`` and
+``_avg`` when you use :ref:`select-drilldown-calc-types`. See
+``drilldown_calc_types`` document for details.
+
+.. _select-drilldown-offset:
 
 ``drilldown_offset``
 """"""""""""""""""""
 
-TODO: write in English and add example.
+It specifies offset to determine range of drilldown output
+records. Offset is zero-based. ``--drilldown_offset 1`` means output
+range is started from the 2nd record.
 
-drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、出力対象となる最初のレコードの番号を0ベースで指定します。デフォルト値は0です。drilldown_offsetに負の値を指定した場合は、ヒットした件数 + drilldown_offsetによって算出される値が指定されたものとみなされます。
+Here is a ``drilldown_offset`` example:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_offset_simple.log
+.. select Entries \
+..   --limit 0 \
+..   --output_column _id \
+..   --drilldown tag \
+..   --drilldown_sortby _key \
+..   --drilldown_offset 1
+
+The ``select`` command outputs from the 2nd record.
+
+You can specify negative value. It means that ``the number of grouped
+results + offset``. If you have 3 grouped results and specify
+``--drilldown_offset -2``, you get grouped results from the 2st
+(``3 + -2 = 1``. ``1`` means 2nd. Remember that offset is zero-based.)
+grouped result to the 3rd grouped result.
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_offset_negative.log
+.. select Entries \
+..   --limit 0 \
+..   --output_column _id \
+..   --drilldown tag \
+..   --drilldown_sortby _key \
+..   --drilldown_offset -2
+
+The ``select`` command outputs from the 2nd grouped result because the
+total number of grouped results is ``3``.
+
+The default value of ``drilldown_offset`` is ``0``.
+
+.. _select-drilldown-limit:
 
 ``drilldown_limit``
 """""""""""""""""""
 
-TODO: write in English and add example.
+It specifies the max number of groups in a drilldown. If the number of
+groups is less than ``drilldown_limit``, all groups are outputted.
+
+Here is a ``drilldown_limit`` example:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_limit_simple.log
+.. select Entries \
+..   --limit 0 \
+..   --output_column _id \
+..   --drilldown tag \
+..   --drilldown_sortby _key \
+..   --drilldown_offset 1 \
+..   --drilldown_limit 2
+
+The ``select`` command outputs the 2rd and the 3rd groups.
+
+You can specify negative value. It means that ``the number of groups +
+drilldown_limit + 1``. For example, ``--drilldown_limit -1`` outputs
+all groups. It's very useful value to show all groups.
+
+Here is a negative ``drilldown_limit`` value example.
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_limit_negative.log
+.. select Entries \
+..   --limit 0 \
+..   --output_column _id \
+..   --drilldown tag \
+..   --drilldown_sortby _key \
+..   --drilldown_limit -1
+
+The ``select`` command outputs all groups.
+
+The default value of ``drilldown_limit`` is ``10``.
+
+.. _select-drilldown-calc-types:
+
+``drilldown_calc_types``
+""""""""""""""""""""""""
+
+It specifies how to calculate (aggregate) values in grouped records by
+a drilldown. You can specify multiple calculation types separated by
+"``,``". For example, ``MAX,MIN``.
+
+Calculation target values are read from a column of grouped
+records. The column is specified by
+:ref:`select-drilldown-calc-target`.
+
+You can read calculated value by :doc:`/reference/columns/pseudo` such
+as ``_max`` and ``_min`` in :ref:`select-drilldown-output-columns`.
+
+You can use the following calculation types:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Type name
+     - :doc:`/reference/columns/pseudo` name
+     - Need :ref:`select-drilldown-calc-target`
+     - Description
+   * - ``NONE``
+     - Nothing.
+     - Not needs.
+     - Just ignored.
+   * - ``COUNT``
+     - ``_nsubrecs``
+     - Not needs.
+     - Counting grouped records. It's always enabled. So you don't
+       specify it.
+   * - ``MAX``
+     - ``_max``
+     - Needs.
+     - Finding the maximum integer value from integer values in
+       grouped records.
+   * - ``MIN``
+     - ``_min``
+     - Needs.
+     - Finding the minimum integer value from integer values in
+       grouped records.
+   * - ``SUM``
+     - ``_sum``
+     - Needs.
+     - Summing integer values in grouped records.
+   * - ``AVG``
+     - ``_avg``
+     - Needs.
+     - Averaging integer/float values in grouped records.
+
+Here is a ``MAX`` example:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_calc_types_max.log
+.. select Entries \
+..   --limit -1 \
+..   --output_column _id,n_likes \
+..   --drilldown tag \
+..   --drilldown_calc_types MAX \
+..   --drilldown_calc_target n_likes \
+..   --drilldown_output_columns _key,_max
+
+The ``select`` command groups all records by ``tag`` column value,
+finding the maximum ``n_likes`` column value for each group and
+outputs pairs of grouped key and the maximum ``n_likes`` column value
+for the group. It uses ``_max`` :doc:`/reference/columns/pseudo` to
+read the maximum ``n_likes`` column value.
+
+Here is a ``MIN`` example:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_calc_types_min.log
+.. select Entries \
+..   --limit -1 \
+..   --output_column _id,n_likes \
+..   --drilldown tag \
+..   --drilldown_calc_types MIN \
+..   --drilldown_calc_target n_likes \
+..   --drilldown_output_columns _key,_min
+
+The ``select`` command groups all records by ``tag`` column value,
+finding the minimum ``n_likes`` column value for each group and
+outputs pairs of grouped key and the minimum ``n_likes`` column value
+for the group. It uses ``_min`` :doc:`/reference/columns/pseudo` to
+read the minimum ``n_likes`` column value.
+
+Here is a ``SUM`` example:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_calc_types_sum.log
+.. select Entries \
+..   --limit -1 \
+..   --output_column _id,n_likes \
+..   --drilldown tag \
+..   --drilldown_calc_types SUM \
+..   --drilldown_calc_target n_likes \
+..   --drilldown_output_columns _key,_sum
+
+The ``select`` command groups all records by ``tag`` column value,
+sums all ``n_likes`` column values for each group and outputs pairs
+of grouped key and the summed ``n_likes`` column values for the
+group. It uses ``_sum`` :doc:`/reference/columns/pseudo` to read the
+summed ``n_likes`` column values.
+
+Here is a ``AVG`` example:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_calc_types_avg.log
+.. select Entries \
+..   --limit -1 \
+..   --output_column _id,n_likes \
+..   --drilldown tag \
+..   --drilldown_calc_types AVG \
+..   --drilldown_calc_target n_likes \
+..   --drilldown_output_columns _key,_avg
+
+The ``select`` command groups all records by ``tag`` column value,
+averages all ``n_likes`` column values for each group and outputs
+pairs of grouped key and the averaged ``n_likes`` column values for
+the group. It uses ``_avg`` :doc:`/reference/columns/pseudo` to read
+the averaged ``n_likes`` column values.
+
+Here is an example that uses all calculation types:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_calc_types_all.log
+.. select Entries \
+..   --limit -1 \
+..   --output_column _id,n_likes \
+..   --drilldown tag \
+..   --drilldown_calc_types MAX,MIN,SUM,AVG \
+..   --drilldown_calc_target n_likes \
+..   --drilldown_output_columns _key,_nsubrecs,_max,_min,_sum,_avg
+
+The ``select`` command specifies multiple calculation types separated
+by "``,``" like ``MAX,MIN,SUM,AVG``. You can use ``_nsubrecs``
+:doc:`/reference/columns/pseudo` in
+:ref:`select-drilldown-output-columns` without specifying ``COUNT`` in
+``drilldown_calc_types``. Because ``COUNT`` is always enabled.
+
+The default value of ``drilldown_calc_types`` is ``NONE``. It means
+that only ``COUNT`` is enabled. Because ``NONE`` is just ignored and
+``COUNT`` is always enabled.
+
+.. _select-drilldown-calc-target:
+
+``drilldown_calc_target``
+"""""""""""""""""""""""""
+
+It specifies the target column for :ref:`select-drilldown-calc-types`.
 
-drilldown条件に指定されたカラムの値毎にとりまとめられたレコードについて、出力を行うレコードの件数を指定します。デフォルト値は10です。実際には、drilldown_offset + drilldown_limit がヒットした件数を超えない範囲でレコードが出力されます。drilldown_limitに負の値を指定した場合は、ヒットした件数 + drilldown_limit + 1 によって算出される値が指定されたものとみなされます。
+If you specify a calculation type that needs a target column such as
+``MAX`` in :ref:`select-drilldown-calc-types` but you omit
+``drilldown_calc_target``, the calculation result is always ``0``.
+
+You can specify only one column name like ``--drilldown_calc_target
+n_likes``. You can't specify multiple column name like
+``--drilldown_calc_target _key,n_likes``.
+
+You can use referenced value from the target record by combining
+"``.``" like ``--drilldown_calc_target
+reference_column.nested_reference_column.value``.
+
+See :ref:`select-drilldown-calc-types` to know how to use
+``drilldown_calc_target``.
+
+The default value of ``drilldown_calc_target`` is ``null``. It means
+that no calculation target column is specified.
+
+.. _select-advanced-drilldown-related-parameters:
+
+Advanced drilldown related parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can get multiple drilldown results by specifying multiple group
+keys by :ref:`select-drilldown`. But you need to use the same
+configuration for all drilldowns. For example,
+:ref:`select-drilldown-output-columns` is used by all drilldowns.
+
+You can use a configuration for each drilldown by the following
+parameters:
+
+  * ``drilldown[${LABEL}].keys``
+  * ``drilldown[${LABEL}].sortby``
+  * ``drilldown[${LABEL}].output_columns``
+  * ``drilldown[${LABEL}].offset``
+  * ``drilldown[${LABEL}].limit``
+  * ``drilldown[${LABEL}].calc_types``
+  * ``drilldown[${LABEL}].calc_target``
+
+``${LABEL}`` is a variable. You can use the following characters for
+``${LABEL}``:
+
+  * Alphabets
+  * Digits
+  * ``.``
+  * ``_``
+
+.. You can use more characters but it's better that you use only these
+   characters.
+
+Parameters that has the same ``${LABEL}`` value are grouped. Grouped
+parameters are used for one drilldown.
+
+For example, there are 2 groups for the following parameters:
+
+  * ``--drilldown[label1].keys _key``
+  * ``--drilldown[label1].output_columns _nsubrecs``
+  * ``--drilldown[label2].keys tag``
+  * ``--drilldown[label2].output_columns _key,_nsubrecs``
+
+``drilldown[label1].keys`` and ``drilldown[label1].output_columns``
+are grouped. ``drilldown[label2].keys`` and
+``drilldown[label2].output_columns`` are also grouped.
+
+In ``label1`` group, ``_key`` is used for group key and ``_nsubrecs``
+is used for output columns.
+
+In ``label2`` group, ``tag`` is used for group key and
+``_key,_nsubrecs`` is used for output columns.
+
+See document for corresponding ``drilldown_XXX`` parameter to know how
+to use it for the following parameters:
+
+  * ``drilldown[${LABEL}].sortby``: :ref:`select-drilldown-sortby`
+  * ``drilldown[${LABEL}].offset``: :ref:`select-drilldown-offset`
+  * ``drilldown[${LABEL}].limit``: :ref:`select-drilldown-limit`
+  * ``drilldown[${LABEL}].calc_types``: :ref:`select-drilldown-calc-types`
+  * ``drilldown[${LABEL}].calc_target``: :ref:`select-drilldown-calc-target`
+
+The following parameters are needed more description:
+
+  * ``drilldown[${LABEL}].keys``
+  * ``drilldown[${LABEL}].output_columns``
+
+Output format is different a bit. It's also needed more description.
+
+.. _select-drilldown-label-keys:
+
+``drilldown[${LABEL}].keys``
+""""""""""""""""""""""""""""
+
+:ref:`select-drilldown` can specify multiple keys for multiple
+drilldowns. But it can't specify multiple keys for one drilldown.
+
+``drilldown[${LABEL}].keys`` can't specify multiple keys for multiple
+drilldowns. But it can specify multiple keys for one drilldown.
+
+You can specify multiple keys separated by "``,``".
+
+Here is an example to group by multiple keys, ``tag`` and ``n_likes``
+column values:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_label_keys_multiple.log
+.. select Entries \
+..   --limit -1 \
+..   --output_column tag,n_likes \
+..   --drilldown[tag.n_likes].keys tag,n_likes \
+..   --drilldown[tag.n_likes].output_columns _value.tag,_value.n_likes,_nsubrecs
+
+``tag.n_likes`` is used as the label for the drilldown parameters
+group. You can refer grouped keys by ``_value.${KEY_NAME}`` syntax in
+:ref:`select-drilldown-label-output-columns`. ``${KEY_NAME}`` is a
+column name to be used by group key. ``tag`` and ``n_likes`` are
+``${KEY_NAME}`` in this case.
+
+Note that you can't use ``_value.${KEY_NAME}`` syntax when you just
+specify one key as ``drilldown[${LABEL}].keys`` like ``--drilldown[tag].keys
+tag``. You should use ``_key`` for the case. It's the same rule in
+:ref:`select-drilldown-output-columns`.
+
+.. _select-drilldown-label-output-columns:
+
+``drilldown[${LABEL}].output_columns``
+""""""""""""""""""""""""""""""""""""""
+
+It's almost same as :ref:`select-drilldown-output-columns`. The
+difference between :ref:`select-drilldown-output-columns` and
+``drilldown[${LABEL}].output_columns`` is how to refer group keys.
+
+:ref:`select-drilldown-output-columns` uses ``_key``
+:doc:`/reference/columns/pseudo` to refer group
+key. ``drilldown[${LABEL}].output_columns`` also uses ``_key``
+:doc:`/reference/columns/pseudo` to refer group key when you specify
+only one group key by :ref:`select-drilldown-label-keys`.
+
+Here is an example to refer single group key by ``_key``
+:doc:`/reference/columns/pseudo`:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_label_output_columns_single_group_key.log
+.. select Entries \
+..   --limit 0 \
+..   --output_column _id \
+..   --drilldown[tag.n_likes].keys tag \
+..   --drilldown[tag.n_likes].output_columns _key
+
+But you can't refer each group key by ``_key``
+:doc:`/reference/columns/pseudo` in
+``drilldown[${LABEL}].output_columns``. You need to use
+``_value.${KEY_NAME}`` syntax. ``${KEY_NAME}`` is a column name that is
+used for group key in :ref:`select-drilldown-label-keys`.
+
+Here is an example to refer each group key in multiple group keys by
+``_value.${KEY_NAME}`` syntax:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_label_output_columns_single_group_key.log
+.. select Entries \
+..   --limit 0 \
+..   --output_column _id \
+..   --drilldown[tag.n_likes].keys tag,n_likes \
+..   --drilldown[tag.n_likes].output_columns _value.tag,_value.n_likes
+
+.. tip:: Why ``_value.${KEY_NAME}`` syntax?
+
+   It's implementation specific information.
+
+   ``_key`` is a vector value. The vector value is consists of all
+   group keys. You can see byte sequence of the vector value by
+   referring ``_key`` in ``drilldown[${LABEL}].output_columns``.
+
+   There is one grouped record in ``_value`` to refer each grouped
+   values when you specify multiple group keys to
+   :ref:`select-drilldown-label-keys`. So you can refer each group key
+   by ``_value.${KEY_NAME}`` syntax.
+
+   On the other hand, there is no grouped record in ``_value`` when
+   you specify only one group key to
+   :ref:`select-drilldown-label-keys`. So you can't refer group key by
+   ``_value.${KEY_NAME}`` syntax.
+
+.. _select-drilldown-label-output-format:
+
+Output format for ``drilldown[${LABEL}]`` style
+"""""""""""""""""""""""""""""""""""""""""""""""
+
+There is a difference in output format between :ref:`select-drilldown`
+and :ref:`select-drilldown-label-keys`. :ref:`select-drilldown` uses
+array to output multiple drilldown results.
+:ref:`select-drilldown-label-keys` uses pairs of label and drilldown
+result.
+
+:ref:`select-drilldown` uses the following output format::
+
+  [
+    HEADER,
+    [
+      SEARCH_RESULT,
+      DRILLDOWN_RESULT1,
+      DRILLDOWN_RESULT2,
+      ...
+    ]
+  ]
+
+:ref:`select-drilldown-label-keys` uses the following output format::
+
+  [
+    HEADER,
+    [
+      SEARCH_RESULT,
+      {
+        "LABEL1": DRILLDOWN_RESULT1,
+        "LABEL2": DRILLDOWN_RESULT2,
+        ...
+      }
+    ]
+  ]
 
 Cache related parameter
 ^^^^^^^^^^^^^^^^^^^^^^^