rroonga 6.1.3-x86-mingw32 → 7.0.2-x86-mingw32

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

@@ -47,21 +47,61 @@ optional::
          [adjuster=null]
          [drilldown_calc_types=NONE]
          [drilldown_calc_target=null]
+         [drilldown_filter=null]
          [sort_keys=null]
          [drilldown_sort_keys=null]
 
-``select`` has the following named parameters for advanced drilldown:
+This command has the following named parameters for dynamic columns:
+
+   * ``columns[${NAME}].stage=null``
+   * ``columns[${NAME}].flags=COLUMN_SCALAR``
+   * ``columns[${NAME}].type=null``
+   * ``columns[${NAME}].value=null``
+   * ``columns[${NAME}].window.sort_keys=null``
+   * ``columns[${NAME}].window.group_keys=null``
+
+You can use one or more alphabets, digits, ``_`` for ``${NAME}``. For
+example, ``column1`` is a valid ``${NAME}``. This is the same rule as
+normal column. See also :ref:`column-create-name`.
+
+Parameters that have the same ``${NAME}`` are grouped.
+
+For example, the following parameters specify one dynamic column:
+
+  * ``--columns[name].stage initial``
+  * ``--columns[name].type UInt32``
+  * ``--columns[name].value 29``
+
+The following parameters specify two dynamic columns:
+
+  * ``--columns[name1].stage initial``
+  * ``--columns[name1].type UInt32``
+  * ``--columns[name1].value 29``
+  * ``--columns[name2].stage filtered``
+  * ``--columns[name2].type Float``
+  * ``--columns[name2].value '_score * 0.1'``
+
+This command has the following named parameters for advanced drilldown:
 
   * ``drilldowns[${LABEL}].keys=null``
-  * ``drilldowns[${LABEL}].sortby=null``
+  * ``drilldowns[${LABEL}].sort_keys=null``
   * ``drilldowns[${LABEL}].output_columns="_key, _nsubrecs"``
   * ``drilldowns[${LABEL}].offset=0``
   * ``drilldowns[${LABEL}].limit=10``
   * ``drilldowns[${LABEL}].calc_types=NONE``
   * ``drilldowns[${LABEL}].calc_target=null``
+  * ``drilldowns[${LABEL}].filter=null``
+  * ``drilldowns[${LABEL}].columns[${NAME}].stage=null``
+  * ``drilldowns[${LABEL}].columns[${NAME}].flags=COLUMN_SCALAR``
+  * ``drilldowns[${LABEL}].columns[${NAME}].type=null``
+  * ``drilldowns[${LABEL}].columns[${NAME}].value=null``
+  * ``drilldowns[${LABEL}].columns[${NAME}].window.sort_keys=null``
+  * ``drilldowns[${LABEL}].columns[${NAME}].window.group_keys=null``
 
 .. deprecated:: 6.0.3
-  ``drilldown[...]`` syntax is deprecated, Use ``drilldowns[...]`` instead.
+
+   ``drilldown[...]`` syntax is deprecated, Use ``drilldowns[...]``
+   instead.
 
 You can use one or more alphabets, digits, ``_`` and ``.`` for
 ``${LABEL}``. For example, ``parent.sub1`` is a valid ``${LABEL}``.
@@ -71,14 +111,14 @@ Parameters that have the same ``${LABEL}`` are grouped.
 For example, the following parameters specify one drilldown:
 
   * ``--drilldowns[label].keys column``
-  * ``--drilldowns[label].sortby -_nsubrecs``
+  * ``--drilldowns[label].sort_keys -_nsubrecs``
 
 The following parameters specify two drilldowns:
 
   * ``--drilldowns[label1].keys column1``
-  * ``--drilldowns[label1].sortby -_nsubrecs``
+  * ``--drilldowns[label1].sort_keys -_nsubrecs``
   * ``--drilldowns[label2].keys column2``
-  * ``--drilldowns[label2].sortby _key``
+  * ``--drilldowns[label2].sort_keys _key``
 
 Usage
 -----
@@ -245,7 +285,7 @@ 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
+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
@@ -291,6 +331,114 @@ 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.
 
+Dynamic column
+^^^^^^^^^^^^^^
+
+You can create zero or more columns dynamically while a ``select``
+execution. You can use them for drilldown by computed value, window
+function and so on.
+
+Here is an example that uses dynamic column for drilldown by computed
+value. This example creates a new column named
+``n_likes_class``. ``n_likes_class`` column has classified value of
+``Entry.n_likes`` value. This example classifies ``Entry.n_likes``
+column value ``10`` step and the lowest number in the class is the
+classified value. If a ``Entry.n_likes`` value is between ``0`` and
+``9`` such as ``3`` and ``5``, ``n_likes_class`` value (classified
+value) is ``0``. If ``Entry.n_likes`` value is between ``10`` and
+``19`` such as ``10`` and ``15``, ``n_likes_class`` value (classified
+value) is ``10``.
+
+You can use :doc:`/reference/functions/number_classify` function for
+the classification. You need to register ``functions/number`` plugin
+by :doc:`plugin_register` command to use
+:doc:`/reference/functions/number_classify` function.
+
+This example does drilldown by ``n_likes_class`` value. The drilldown
+result will help you to know data trend.
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/usage_dynamic_column.log
+.. plugin_register functions/number
+.. select \
+..   --table Entries \
+..   --columns[n_likes_class].stage initial \
+..   --columns[n_likes_class].type UInt32 \
+..   --columns[n_likes_class].value 'number_classify(n_likes, 10)' \
+..   --drilldown n_likes_class \
+..   --drilldown_sort_keys _nsubrecs \
+..   --output_columns n_likes,n_likes_class
+
+See :ref:`select-dynamic-column-related-parameters` for details.
+
+Window function
+^^^^^^^^^^^^^^^
+
+You can compute each record value from values of grouped records. For
+example, you can compute sums of each group and puts sums to each
+record. The difference against drilldown is drilldown can compute sums
+of each group but it puts sums to each group not record.
+
+Here is the result with window function. Each record has sum:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Group No.
+     - Target value
+     - Sum result
+   * - 1
+     - 5
+     - 5
+   * - 2
+     - 10
+     - 25
+   * - 2
+     - 15
+     - 25
+   * - 3
+     - 3
+     - 8
+   * - 3
+     - 5
+     - 8
+
+Here is the result with drilldown. Each group has sum:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Group No.
+     - Target values
+     - Sum result
+   * - 1
+     - 5
+     - 5
+   * - 2
+     - 10, 15
+     - 25
+   * - 3
+     - 3, 5
+     - 8
+
+Window function is useful for data analysis.
+
+Here is an example that sums ``Entries.n_likes`` per
+``Entries.tag``:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/usage_window_function.log
+.. plugin_register functions/number
+.. select \
+..   --table Entries \
+..   --columns[n_likes_sum_per_tag].stage initial \
+..   --columns[n_likes_sum_per_tag].type UInt32 \
+..   --columns[n_likes_sum_per_tag].value 'window_sum(n_likes)' \
+..   --columns[n_likes_sum_per_tag].window.group_keys tag \
+..   --output_columns tag,n_likes,n_likes_sum_per_tag
+
+See :ref:`select-window-function-related-parameters` for details.
+
 Parameters
 ----------
 
@@ -852,7 +1000,7 @@ record.
 
 .. groonga-command
 .. include:: ../../example/reference/commands/select/offset_simple.log
-.. select Entries --sortby _id --offset 3 --output_columns _key
+.. select Entries --sort_keys _id --offset 3 --output_columns _key
 
 The ``select`` command outputs from the 4th record.
 
@@ -864,7 +1012,7 @@ record.
 
 .. groonga-command
 .. include:: ../../example/reference/commands/select/offset_negative.log
-.. select Entries --sortby _id --offset -2 --output_columns _key
+.. select Entries --sort_keys _id --offset -2 --output_columns _key
 
 The ``select`` command outputs from the 4th record because the total
 number of records is ``5``.
@@ -883,7 +1031,7 @@ 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
+.. select Entries --sort_keys _id --offset 2 --limit 3 --output_columns _key
 
 The ``select`` command outputs the 3rd, the 4th and the 5th records.
 
@@ -912,6 +1060,476 @@ TODO: write in English and add example.
 
 scorerは、検索処理が完了し、ソート処理が実行される前に呼び出されます。従って、各レコードのスコアを操作する式を指定しておけば、検索結果のソート順序をカスタマイズできるようになります。
 
+.. _select-dynamic-column-related-parameters:
+
+Dynamic column related parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 6.0.6
+
+This section describes dynamic column related parameters. You can use
+dynamic column for window function but this section doesn't describe
+window function. See :ref:`select-window-function-related-parameters`
+for window function.
+
+You can create zero or more columns and fill values into these columns
+while a ``select`` execution. These columns are called as "dynamic
+columns". You can use dynamic columns as same as normal columns after
+dynamic columns are created.
+
+Dynamic column has performance merit because its values are computed
+at once and reused computed values.
+
+Dynamic column increases memory usage because its values are kept
+while the ``select`` execution.
+
+You need to use dynamic column in the following cases:
+
+  * You want to name values like ``AS`` in SQL.
+
+  * You want to use computed values for drilldown. Groonga doesn't
+    support drilldown target value computation in drilldown.
+
+  * You want to use window function.
+
+There are some points to create dynamic columns. You must specify
+``stage`` to each dynamic column to control dynamic columns creation
+points. It's important that you choose proper point to get better
+performance.
+
+For example, it's not a good idea that you create a dynamic column
+that is only used for output for all records. The number of output
+records will be a little even if there are many records in a
+table. Because you will filter, sort and limit all records and output
+only the limited records in many cases.
+
+See :ref:`select-columns-name-stage` for ``stage`` detail.
+
+Here are parameters for dynamic column. They don't include window
+function related parameters. See
+:ref:`select-window-function-related-parameters` for window function
+related parameters:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Default value
+     - Required or optional
+   * - ``columns[${NAME}].stage``
+     - ``null``
+     - Required
+   * - ``columns[${NAME}].flags``
+     - ``COLUMN_SCALAR``
+     - Optional
+   * - ``columns[${NAME}].type``
+     - ``null``
+     - Required
+   * - ``columns[${NAME}].value``
+     - ``null``
+     - Required
+
+You need to specify multiple parameters for a dynamic
+column. ``${NAME}`` is the name for each dynamic column. Parameters
+that use the same ``${NAME}`` are treated as parameters for the same
+dynamic column. Here is an example to specify parameters for 2 dynamic
+columns (``name1`` and ``name2``)::
+
+    --columns[name1].stage initial
+    --columns[name1].type UInt32
+    --columns[name1].value 29
+
+    --columns[name2].stage filtered
+    --columns[name2].type ShortText
+    --columns[name2].value "29"
+
+.. _select-columns-name-stage:
+
+``columns[${NAME}].stage``
+""""""""""""""""""""""""""
+
+.. versionadded:: 6.0.6
+
+Specifies when the dynamic column is created. This is a required
+parameter to create a dynamic column.
+
+Here are available stages:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Description
+   * - ``initial``
+     - Dynamic column is created at first.
+   * - ``filtered``
+     - Dynamic column is created after :ref:`select-query` and
+       :ref:`select-filter` are evaluated.
+   * - ``output``
+     - Dynamic column is created before :ref:`select-output-columns`
+       is evaluated.
+
+Here is the ``select`` process flow with dynamic column creation
+points. You should choose stage as late as possible:
+
+  #. Creates dynamic columns for ``initial`` stage. All records have
+     these dynamic columns.
+
+  #. Evaluates :ref:`select-query` and :ref:`select-filter`. You can
+     use dynamic columns created in ``initial`` stage.
+
+  #. Creates dynamic columns for ``filtered`` stage. Only filtered
+     records have these dynamic columns.
+
+  #. Evaluates :ref:`select-adjuster`. You can use dynamic columns
+     created in ``initial`` stage and ``filtered`` stage.
+
+  #. Evaluates :ref:`select-scorer`. You can use dynamic columns
+     created in ``initial`` stage and ``filtered`` stage.
+
+  #. Evaluates :ref:`select-sort-keys`, :ref:`select-offset` and
+     :ref:`select-limit`. You can use dynamic columns created in
+     ``initial`` stage and ``filtered`` stage.
+
+  #. Evaluates :ref:`select-slice-related-parameters`. You can use
+     dynamic columns created in ``initial`` stage and ``filtered`` stage.
+
+  #. Evaluates :ref:`select-drilldown-related-parameters` and
+     :ref:`select-advanced-drilldown-related-parameters`. You can use
+     dynamic columns created in ``initial`` stage and ``filtered`` stage.
+     Note that you can create dynamic columns in each drilldown.
+
+  #. Creates dynamic columns for ``output`` stage. Only
+     :ref:`select-limit` records have these dynamic columns.
+
+  #. Evaluates :ref:`select-output-columns`. You can use dynamic
+     columns created in ``initial`` stage, ``filtered`` stage and
+     ``output`` stage.
+
+Here is an example that creates ``is_popular`` column at ``initial``
+stage. You can use ``is_popular`` in all parameters such as ``filter``
+and ``output_columns``:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/columns_name_stage.log
+.. select Entries \
+..   --columns[is_popular].stage initial \
+..   --columns[is_popular].type Bool \
+..   --columns[is_popular].value 'n_likes >= 10' \
+..   --filter is_popular \
+..   --output_columns _id,is_popular,n_likes
+
+.. _select-columns-name-flags:
+
+``columns[${NAME}].flags``
+""""""""""""""""""""""""""
+
+.. versionadded:: 6.0.6
+
+Specifies flags for the dynamic column. It's the same as ``flags``
+parameter for :doc:`column_create`. See :ref:`column-create-flags` for
+available flags.
+
+The default value is ``COLUMN_SCALAR``.
+
+Here is a ``columns[${NAME}].flags`` example. It creates a vector
+column by ``COLUMN_VECTOR`` flags. ``plugin_register
+functions/vector`` is for using :doc:`/reference/functions/vector_new`
+function:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/columns_name_flags.log
+.. plugin_register functions/vector
+.. select Entries \
+..   --columns[vector].stage initial \
+..   --columns[vector].flags COLUMN_VECTOR \
+..   --columns[vector].type UInt32 \
+..   --columns[vector].value 'vector_new(1, 2, 3)' \
+..   --output_columns _id,vector
+
+.. _select-columns-name-type:
+
+``columns[${NAME}].type``
+"""""""""""""""""""""""""
+
+.. versionadded:: 6.0.6
+
+Specifies value type for the dynamic column. It's the same as ``type``
+parameter for :doc:`column_create`. See :ref:`column-create-type` for
+available types.
+
+This is a required parameter.
+
+Here is an example that creates a ``ShortText`` type column. Stored
+value is casted to ``ShortText`` automatically. In this example,
+number is casted to ``ShortText``:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/columns_name_type.log
+.. select Entries \
+..   --columns[n_likes_string].stage initial \
+..   --columns[n_likes_string].type ShortText \
+..   --columns[n_likes_string].value n_likes \
+..   --output_columns _id,n_likes,n_likes_string
+
+.. _select-columns-name-value:
+
+``columns[${NAME}].value``
+""""""""""""""""""""""""""
+
+.. versionadded:: 6.0.6
+
+Specifies expression that generates values for the dynamic column. The
+expression uses :doc:`/reference/grn_expr/script_syntax`. It's the
+same syntax in :ref:`select-filter`. For example, ``1 + 1``,
+``string_length("Hello")``, ``column * 1.08`` and so on are valid
+expressions.
+
+You need to specify :doc:`/reference/window_function` as ``value``
+value and other window function related parameters when you use window
+function. See :ref:`select-window-function-related-parameters` for
+details.
+
+This is a required parameter.
+
+Here is an example that creates a new dynamic column that stores the
+number of characters of content. This example uses
+:doc:`/reference/functions/string_length` function in
+``functions/string`` plugin to compute the number of characters in a
+string. :doc:`plugin_register` is used to register
+``functions/string`` plugin:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/columns_name_value.log
+.. plugin_register functions/string
+.. select Entries \
+..   --columns[content_length].stage initial \
+..   --columns[content_length].type UInt32 \
+..   --columns[content_length].value 'string_length(content)' \
+..   --output_columns _id,content,content_length
+
+.. _select-window-function-related-parameters:
+
+Window function related parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 6.0.6
+
+This section describes window function related parameters. You need to
+use dynamic column for using window function. See
+:ref:`select-dynamic-column-related-parameters` for dynamic column.
+
+Window function in Groonga is similar to window function in
+SQL. Normal function computes its result with only the current
+record. On the other hand, window function computes its result with
+multiple records. Window function is useful to data analysis because
+it can process multiple records.
+
+You can find supported window functions at
+:doc:`/reference/window_function`. For example,
+:doc:`/reference/window_functions/window_sum` is a window function. It
+sums numbers in the target records.
+
+Window function processes records that are grouped by the specified
+group keys. For example, window function processes three groups
+(``Hello`` group, ``Groonga`` group and ``Senna`` group) in the
+following case. :doc:`/reference/window_functions/window_sum` sums
+``n_likes`` values in each group:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Group No.
+     - Group key value
+     - ``n_likes`` value
+     - :doc:`/reference/window_functions/window_sum` result
+   * - 1
+     - ``Hello``
+     - 5
+     - 5
+   * - 2
+     - ``Groonga``
+     - 10
+     - 25
+   * - 2
+     - ``Groonga``
+     - 15
+     - 25
+   * - 3
+     - ``Senna``
+     - 3
+     - 6
+   * - 3
+     - ``Senna``
+     - 3
+     - 6
+
+You can specify no group keys. In the case, window function processes
+only one group that includes all
+records. :doc:`/reference/window_functions/window_sum` sums all
+``n_likes`` values in the following case:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Group No.
+     - ``n_likes`` value
+     - :doc:`/reference/window_functions/window_sum` result
+   * - 1
+     - 5
+     - 36
+   * - 1
+     - 10
+     - 36
+   * - 1
+     - 15
+     - 36
+   * - 1
+     - 3
+     - 36
+   * - 1
+     - 3
+     - 36
+
+Window function processes records in each group in the specified
+order. You can specify no sort keys like the above group keys
+example.
+
+The behavior when you specify no sort keys depends on each window
+function specification. For example,
+:doc:`/reference/window_functions/window_sum` uses different behavior
+whether sort keys are specified or not. If you specify not sort keys,
+:doc:`/reference/window_functions/window_sum` sums values of all
+records in the group and puts it to all target records like the above
+group keys example. If you specify sort keys,
+:doc:`/reference/window_functions/window_sum` behaves as cumulative
+sum. :doc:`/reference/window_functions/window_sum` sums values of all
+records in the group in sequence and puts the current sum to the
+current record like the following:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Group No.
+     - Group key value
+     - Sort key value
+     - ``n_likes`` value
+     - :doc:`/reference/window_functions/window_sum` result
+     - Note
+   * - 1
+     - ``Hello``
+     - 1
+     - 5
+     - 5
+     - The first record in group No. 1. (``5 = 5``)
+   * - 2
+     - ``Groonga``
+     - 90
+     - 10
+     - 10
+     - The first record in group No. 2. (``10 = 10``)
+   * - 2
+     - ``Groonga``
+     - 91
+     - 15
+     - 25
+     - The second record in group No. 2. (``10 + 15 = 25``)
+   * - 3
+     - ``Senna``
+     - 200
+     - 3
+     - 8
+     - The second record in group No. 3. (``5 + 3 = 8``)
+   * - 3
+     - ``Senna``
+     - 100
+     - 5
+     - 5
+     - The first record in group No. 3. (``5 = 5``)
+
+Here are parameters for window function. You need to specify both
+window function related parameters and required dynamic columns
+parameters. Because window function is implemented based on dynamic
+column. See :ref:`select-dynamic-column-related-parameters` for
+dynamic column related parameters:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Required or optional
+     - Note
+   * - ``columns[${NAME}].value``
+     - Required
+     - Use :doc:`/reference/window_function`.
+   * - ``columns[${NAME}].window.sort_keys``
+     - Required if ``columns[${NAME}].window.group_keys`` isn't specified.
+     -
+   * - ``columns[${NAME}].window.group_keys``
+     - Required if ``columns[${NAME}].window.sort_keys`` isn't specified.
+     -
+
+.. _select-columns-name-window-sort-keys:
+
+``columns[${NAME}].window.sort_keys``
+"""""""""""""""""""""""""""""""""""""
+
+.. versionadded:: 6.0.6
+
+Specifies sort keys in each group. Window function processes records
+in each group in the specified order.
+
+Sort keys are separated by ``,``. Each sort key is column name. It's
+the same as :ref:`select-sort-keys`.
+
+You must specify :ref:`select-columns-name-window-sort-keys` or
+:ref:`select-columns-name-window-group-keys` to use window function.
+
+Here is an example that computes cumulative sum per
+``Entries.tag``. Each group is sorted by ``Entries._key``:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/columns_name_window_sort_keys.log
+.. select \
+..   --table Entries \
+..   --columns[n_likes_cumulative_sum_per_tag].stage initial \
+..   --columns[n_likes_cumulative_sum_per_tag].type UInt32 \
+..   --columns[n_likes_cumulative_sum_per_tag].value 'window_sum(n_likes)' \
+..   --columns[n_likes_cumulative_sum_per_tag].window.sort_keys _key \
+..   --columns[n_likes_cumulative_sum_per_tag].window.group_keys tag \
+..   --sort_keys _key \
+..   --output_columns tag,_key,n_likes,n_likes_cumulative_sum_per_tag
+
+.. _select-columns-name-window-group-keys:
+
+``columns[${NAME}].window.group_keys``
+""""""""""""""""""""""""""""""""""""""
+
+.. versionadded:: 7.0.0
+
+Specifies group keys. Window function processes records in each
+group. If you specify no group keys, window function processes one
+group that includes all records.
+
+Group keys are separated by ``,``. Each group key is column name. It's
+the same as :ref:`select-drilldown`.
+
+You must specify :ref:`select-columns-name-window-sort-keys` or
+:ref:`select-columns-name-window-group-keys` to use window function.
+
+Here is an example that computes sum per ``Entries.tag``:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/columns_name_window_group_keys.log
+.. select \
+..   --table Entries \
+..   --columns[n_likes_sum_per_tag].stage initial \
+..   --columns[n_likes_sum_per_tag].type UInt32 \
+..   --columns[n_likes_sum_per_tag].value 'window_sum(n_likes)' \
+..   --columns[n_likes_sum_per_tag].window.group_keys tag \
+..   --sort_keys _key \
+..   --output_columns tag,_key,n_likes,n_likes_sum_per_tag
+
 .. _select-drilldown-related-parameters:
 
 Drilldown related parameters
@@ -948,7 +1566,7 @@ The ``select`` command outputs the following information:
 Here is a ``drilldown`` with search condition example:
 
 .. groonga-command
-.. include:: ../../example/reference/commands/select/drilldown_filter.log
+.. include:: ../../example/reference/commands/select/drilldown_with_filter.log
 .. select Entries \
 ..   --output_columns _key,tag \
 ..   --filter 'n_likes >= 5' \
@@ -967,7 +1585,7 @@ Here is a ``drilldown`` with multiple group keys example:
 .. include:: ../../example/reference/commands/select/drilldown_multiple.log
 .. select Entries \
 ..   --limit 0 \
-..   --output_column _id \
+..   --output_columns _id \
 ..   --drilldown tag,n_likes
 
 The ``select`` command outputs the following information:
@@ -1003,15 +1621,15 @@ 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:
+Here is a simple ``drilldown_sort_keys`` example:
 
 .. groonga-command
-.. include:: ../../example/reference/commands/select/drilldown_sortby_simple.log
+.. include:: ../../example/reference/commands/select/drilldown_sort_keys_simple.log
 .. select Entries \
 ..   --limit 0 \
-..   --output_column _id \
+..   --output_columns _id \
 ..   --drilldown tag \
-..   --drilldown_sortby '-_nsubrecs, _key'
+..   --drilldown_sort_keys '-_nsubrecs, _key'
 
 Drilldown result is sorted by the number of grouped records (=
 ``_nsubrecs`` ) in descending order. If there are grouped results that
@@ -1021,12 +1639,12 @@ 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
+.. include:: ../../example/reference/commands/select/drilldown_sort_keys_simple.log
 .. select Entries \
 ..   --limit 0 \
-..   --output_column _id \
+..   --output_columns _id \
 ..   --drilldown 'tag, n_likes' \
-..   --drilldown_sortby '-_nsubrecs, _key'
+..   --drilldown_sort_keys '-_nsubrecs, _key'
 
 The same sort keys are used in ``tag`` drilldown and ``n_likes``
 drilldown.
@@ -1047,7 +1665,7 @@ Here is a ``drilldown_output_columns`` example:
 .. include:: ../../example/reference/commands/select/drilldown_output_columns_simple.log
 .. select Entries \
 ..   --limit 0 \
-..   --output_column _id \
+..   --output_columns _id \
 ..   --drilldown tag \
 ..   --drilldown_output_columns _key
 
@@ -1092,7 +1710,7 @@ You can refer ``Tags.label`` by ``label`` in
 .. include:: ../../example/reference/commands/select/drilldown_output_columns_referenced_type_column_label.log
 .. select Items \
 ..   --limit 0 \
-..   --output_column _id \
+..   --output_columns _id \
 ..   --drilldown tag \
 ..   --drilldown_output_columns '_key, label'
 
@@ -1102,7 +1720,7 @@ You can use ``*`` to refer all columns in referenced table (= ``Tags``):
 .. include:: ../../example/reference/commands/select/drilldown_output_columns_referenced_type_column_asterisk.log
 .. select Items \
 ..   --limit 0 \
-..   --output_column _id \
+..   --output_columns _id \
 ..   --drilldown tag \
 ..   --drilldown_output_columns '_key, *'
 
@@ -1132,9 +1750,9 @@ Here is a ``drilldown_offset`` example:
 .. include:: ../../example/reference/commands/select/drilldown_offset_simple.log
 .. select Entries \
 ..   --limit 0 \
-..   --output_column _id \
+..   --output_columns _id \
 ..   --drilldown tag \
-..   --drilldown_sortby _key \
+..   --drilldown_sort_keys _key \
 ..   --drilldown_offset 1
 
 The ``select`` command outputs from the 2nd record.
@@ -1149,9 +1767,9 @@ grouped result to the 3rd grouped result.
 .. include:: ../../example/reference/commands/select/drilldown_offset_negative.log
 .. select Entries \
 ..   --limit 0 \
-..   --output_column _id \
+..   --output_columns _id \
 ..   --drilldown tag \
-..   --drilldown_sortby _key \
+..   --drilldown_sort_keys _key \
 ..   --drilldown_offset -2
 
 The ``select`` command outputs from the 2nd grouped result because the
@@ -1173,9 +1791,9 @@ Here is a ``drilldown_limit`` example:
 .. include:: ../../example/reference/commands/select/drilldown_limit_simple.log
 .. select Entries \
 ..   --limit 0 \
-..   --output_column _id \
+..   --output_columns _id \
 ..   --drilldown tag \
-..   --drilldown_sortby _key \
+..   --drilldown_sort_keys _key \
 ..   --drilldown_offset 1 \
 ..   --drilldown_limit 2
 
@@ -1191,9 +1809,9 @@ Here is a negative ``drilldown_limit`` value example.
 .. include:: ../../example/reference/commands/select/drilldown_limit_negative.log
 .. select Entries \
 ..   --limit 0 \
-..   --output_column _id \
+..   --output_columns _id \
 ..   --drilldown tag \
-..   --drilldown_sortby _key \
+..   --drilldown_sort_keys _key \
 ..   --drilldown_limit -1
 
 The ``select`` command outputs all groups.
@@ -1259,7 +1877,7 @@ Here is a ``MAX`` example:
 .. include:: ../../example/reference/commands/select/drilldown_calc_types_max.log
 .. select Entries \
 ..   --limit -1 \
-..   --output_column _id,n_likes \
+..   --output_columns _id,n_likes \
 ..   --drilldown tag \
 ..   --drilldown_calc_types MAX \
 ..   --drilldown_calc_target n_likes \
@@ -1277,7 +1895,7 @@ Here is a ``MIN`` example:
 .. include:: ../../example/reference/commands/select/drilldown_calc_types_min.log
 .. select Entries \
 ..   --limit -1 \
-..   --output_column _id,n_likes \
+..   --output_columns _id,n_likes \
 ..   --drilldown tag \
 ..   --drilldown_calc_types MIN \
 ..   --drilldown_calc_target n_likes \
@@ -1295,7 +1913,7 @@ Here is a ``SUM`` example:
 .. include:: ../../example/reference/commands/select/drilldown_calc_types_sum.log
 .. select Entries \
 ..   --limit -1 \
-..   --output_column _id,n_likes \
+..   --output_columns _id,n_likes \
 ..   --drilldown tag \
 ..   --drilldown_calc_types SUM \
 ..   --drilldown_calc_target n_likes \
@@ -1313,7 +1931,7 @@ Here is a ``AVG`` example:
 .. include:: ../../example/reference/commands/select/drilldown_calc_types_avg.log
 .. select Entries \
 ..   --limit -1 \
-..   --output_column _id,n_likes \
+..   --output_columns _id,n_likes \
 ..   --drilldown tag \
 ..   --drilldown_calc_types AVG \
 ..   --drilldown_calc_target n_likes \
@@ -1331,7 +1949,7 @@ Here is an example that uses all calculation types:
 .. include:: ../../example/reference/commands/select/drilldown_calc_types_all.log
 .. select Entries \
 ..   --limit -1 \
-..   --output_column _id,n_likes \
+..   --output_columns _id,n_likes \
 ..   --drilldown tag \
 ..   --drilldown_calc_types MAX,MIN,SUM,AVG \
 ..   --drilldown_calc_target n_likes \
@@ -1352,6 +1970,8 @@ that only ``COUNT`` is enabled. Because ``NONE`` is just ignored and
 ``drilldown_calc_target``
 """""""""""""""""""""""""
 
+.. versionadded:: 6.0.3
+
 Specifies the target column for :ref:`select-drilldown-calc-types`.
 
 If you specify a calculation type that needs a target column such as
@@ -1372,11 +1992,36 @@ See :ref:`select-drilldown-calc-types` to know how to use
 The default value of ``drilldown_calc_target`` is ``null``. It means
 that no calculation target column is specified.
 
+.. _select-drilldown-filter:
+
+``drilldown_filter``
+""""""""""""""""""""
+
+.. versionadded:: 6.0.3
+
+Specifies the filter condition against the drilled down result.
+
+The syntax is :doc:`/reference/grn_expr/script_syntax`. It's the same
+as :ref:`select-filter`.
+
+Here is an example to suppress tags that are occurred only once:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldown_filter.log
+.. select Entries \
+..   --limit -1 \
+..   --output_columns _id,tag \
+..   --drilldown tag \
+..   --drilldown_filter '_nsubrecs > 1' \
+..   --drilldown_output_columns _key,_nsubrecs
+
 .. _select-advanced-drilldown-related-parameters:
 
 Advanced drilldown related parameters
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. versionadded:: 4.0.8
+
 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,
@@ -1386,12 +2031,19 @@ You can use a configuration for each drilldown by the following
 parameters:
 
   * ``drilldowns[${LABEL}].keys``
-  * ``drilldowns[${LABEL}].sortby``
+  * ``drilldowns[${LABEL}].sort_keys``
   * ``drilldowns[${LABEL}].output_columns``
   * ``drilldowns[${LABEL}].offset``
   * ``drilldowns[${LABEL}].limit``
   * ``drilldowns[${LABEL}].calc_types``
   * ``drilldowns[${LABEL}].calc_target``
+  * ``drilldowns[${LABEL}].filter``
+  * ``drilldowns[${LABEL}].columns[${NAME}].stage=null``
+  * ``drilldowns[${LABEL}].columns[${NAME}].flags=COLUMN_SCALAR``
+  * ``drilldowns[${LABEL}].columns[${NAME}].type=null``
+  * ``drilldowns[${LABEL}].columns[${NAME}].value=null``
+  * ``drilldowns[${LABEL}].columns[${NAME}].window.sort_keys=null``
+  * ``drilldowns[${LABEL}].columns[${NAME}].window.group_keys=null``
 
 ``${LABEL}`` is a variable. You can use the following characters for
 ``${LABEL}``:
@@ -1401,6 +2053,13 @@ parameters:
   * ``.``
   * ``_``
 
+``${NAME}`` is a variable. You can use the following characters for
+``${NAME}``:
+
+  * Alphabets
+  * Digits
+  * ``_``
+
 .. note::
 
    You can use more characters but it's better that you use only these
@@ -1429,24 +2088,42 @@ In ``label2`` group, ``tag`` is used for group key and
 See document for corresponding ``drilldown_XXX`` parameter to know how
 to use it for the following parameters:
 
-  * ``drilldowns[${LABEL}].sortby``: :ref:`select-drilldown-sortby`
+  * ``drilldowns[${LABEL}].sort_keys``: :ref:`select-drilldown-sort-keys`
   * ``drilldowns[${LABEL}].offset``: :ref:`select-drilldown-offset`
   * ``drilldowns[${LABEL}].limit``: :ref:`select-drilldown-limit`
   * ``drilldowns[${LABEL}].calc_types``: :ref:`select-drilldown-calc-types`
   * ``drilldowns[${LABEL}].calc_target``: :ref:`select-drilldown-calc-target`
+  * ``drilldowns[${LABEL}].filter``: :ref:`select-drilldown-filter`
+
+See document for corresponding ``columns[${NAME}].XXX`` parameter to
+know how to use it for the following parameters:
+
+  * ``drilldowns[${LABEL}].columns[${NAME}].flags=COLUMN_SCALAR``:
+    :ref:`select-columns-name-flags`
+  * ``drilldowns[${LABEL}].columns[${NAME}].type=null``:
+    :ref:`select-columns-name-type`
+  * ``drilldowns[${LABEL}].columns[${NAME}].value=null``:
+    :ref:`select-columns-name-value`
+  * ``drilldowns[${LABEL}].columns[${NAME}].window.sort_keys=null``:
+    :ref:`select-columns-name-window-sort-keys`
+  * ``drilldowns[${LABEL}].columns[${NAME}].window.group_keys=null``:
+    :ref:`select-columns-name-window-group-keys`
 
 The following parameters are needed more description:
 
   * ``drilldowns[${LABEL}].keys``
   * ``drilldowns[${LABEL}].output_columns``
+  * ``drilldowns[${LABEL}].columns[${NAME}].stage=null``
 
 Output format is different a bit. It's also needed more description.
 
-.. _select-drilldown-label-keys:
+.. _select-drilldowns-label-keys:
 
 ``drilldowns[${LABEL}].keys``
 """""""""""""""""""""""""""""
 
+.. versionadded:: 4.0.8
+
 :ref:`select-drilldown` can specify multiple keys for multiple
 drilldowns. But it can't specify multiple keys for one drilldown.
 
@@ -1459,16 +2136,16 @@ 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
+.. include:: ../../example/reference/commands/select/drilldowns_label_keys_multiple.log
 .. select Entries \
 ..   --limit -1 \
-..   --output_column tag,n_likes \
+..   --output_columns tag,n_likes \
 ..   --drilldowns[tag.n_likes].keys tag,n_likes \
 ..   --drilldowns[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
+:ref:`select-drilldowns-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.
 
@@ -1477,11 +2154,13 @@ specify one key as ``drilldowns[${LABEL}].keys`` like ``--drilldowns[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:
+.. _select-drilldowns-label-output-columns:
 
 ``drilldowns[${LABEL}].output_columns``
 """""""""""""""""""""""""""""""""""""""
 
+.. versionadded:: 4.0.8
+
 It's almost same as :ref:`select-drilldown-output-columns`. The
 difference between :ref:`select-drilldown-output-columns` and
 ``drilldowns[${LABEL}].output_columns`` is how to refer group keys.
@@ -1490,16 +2169,16 @@ difference between :ref:`select-drilldown-output-columns` and
 :doc:`/reference/columns/pseudo` to refer group
 key. ``drilldowns[${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`.
+only one group key by :ref:`select-drilldowns-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
+.. include:: ../../example/reference/commands/select/drilldowns_label_output_columns_single_group_key.log
 .. select Entries \
 ..   --limit 0 \
-..   --output_column _id \
+..   --output_columns _id \
 ..   --drilldowns[tag.n_likes].keys tag \
 ..   --drilldowns[tag.n_likes].output_columns _key
 
@@ -1507,16 +2186,16 @@ But you can't refer each group key by ``_key``
 :doc:`/reference/columns/pseudo` in
 ``drilldowns[${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`.
+used for group key in :ref:`select-drilldowns-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
+.. include:: ../../example/reference/commands/select/drilldowns_label_output_columns_single_group_key.log
 .. select Entries \
 ..   --limit 0 \
-..   --output_column _id \
+..   --output_columns _id \
 ..   --drilldowns[tag.n_likes].keys tag,n_likes \
 ..   --drilldowns[tag.n_likes].output_columns _value.tag,_value.n_likes
 
@@ -1530,23 +2209,82 @@ Here is an example to refer each group key in multiple group keys by
 
    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
+   :ref:`select-drilldowns-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
+   :ref:`select-drilldowns-label-keys`. So you can't refer group key by
    ``_value.${KEY_NAME}`` syntax.
 
-.. _select-drilldown-label-output-format:
+.. _select-drilldowns-label-columns-name-stage:
+
+``drilldowns[${LABEL}].columns[${NAME}].stage``
+"""""""""""""""""""""""""""""""""""""""""""""""
+
+.. versionadded:: 6.0.5
+
+Specifies when the dynamic column is created. This is a required
+parameter to create a dynamic column.
+
+Here are available stages:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Description
+   * - ``initial``
+     - Dynamic column is created at first.
+
+Here is one drilldown process flow with dynamic column creation
+points. You should choose stage as late as possible:
+
+  #. Evaluates :ref:`select-drilldowns-label-keys`,
+     ``drilldowns[${LABEL}].calc_types`` and
+     ``drilldowns[${LABEL}].calc_target``.
+
+  #. Creates dynamic columns for ``initial`` stage. All drilldown
+     result records have these dynamic columns.
+
+  #. Evaluates ``drilldowns[${LABEL}].filter``. You can use dynamic
+     columns created in ``initial`` stage.
+
+  #. Evaluates ``drilldowns[${LABEL}].sort_keys``,
+     ``drilldowns[${LABEL}].offset`` and
+     ``drilldowns[${LABEL}].limit``. You can use dynamic columns
+     created in ``initial`` stage.
+
+  #. Evaluates :ref:`select-drilldowns-label-output-columns`. You can
+     use dynamic columns created in ``initial`` stage.
+
+Here is a ``drilldowns[${LABEL}].columns[${NAME}].stage`` example. It
+creates ``is_popular`` column at ``initial`` stage. You can use
+``is_popular`` in all parameters such as
+``drilldowns[${LABEL}].filter`` and
+``drilldowns[${LABEL}].output_columns``:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/drilldowns_label_columns_name_stage.log
+.. select Entries \
+..   --drilldowns[tag].keys tag \
+..   --drilldowns[tag].columns[is_popular].stage initial \
+..   --drilldowns[tag].columns[is_popular].type Bool \
+..   --drilldowns[tag].columns[is_popular].value '_nsubrecs > 1' \
+..   --drilldowns[tag].filter is_popular \
+..   --drilldowns[tag].output_columns _key,is_popular,_nsubrecs
+
+.. versionadded:: 4.0.8
+
+.. _select-drilldowns-label-output-format:
 
 Output format for ``drilldowns[${LABEL}]`` style
 """"""""""""""""""""""""""""""""""""""""""""""""
 
 There is a difference in output format between :ref:`select-drilldown`
-and :ref:`select-drilldown-label-keys`. :ref:`select-drilldown` uses
+and :ref:`select-drilldowns-label-keys`. :ref:`select-drilldown` uses
 array to output multiple drilldown results.
-:ref:`select-drilldown-label-keys` uses pairs of label and drilldown
+:ref:`select-drilldowns-label-keys` uses pairs of label and drilldown
 result.
 
 :ref:`select-drilldown` uses the following output format::
@@ -1561,7 +2299,7 @@ result.
     ]
   ]
 
-:ref:`select-drilldown-label-keys` uses the following output format::
+:ref:`select-drilldowns-label-keys` uses the following output format::
 
   [
     HEADER,
@@ -1575,6 +2313,115 @@ result.
     ]
   ]
 
+.. _select-slice-related-parameters:
+
+Slice related parameters
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 6.0.3
+
+This section describes slice related parameters.
+
+TODO
+
+Here are parameters for slice:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Required
+   * - ``--slices[${LABEL}].match_columns``
+     - Optional
+   * - ``--slices[${LABEL}].query``
+     - Required if ``--slices[${LABEL}].filter`` isn't specified.
+   * - ``--slices[${LABEL}].filter``
+     - Required if ``--slices[${LABEL}].query`` isn't specified.
+   * - ``--slices[${LABEL}].query_expander``
+     - Optional
+   * - ``--slices[${LABEL}].query_flags``
+     - Optional
+   * - ``--slices[${LABEL}].sort_keys``
+     - Optional
+   * - ``--slices[${LABEL}].output_columns``
+     - Optional
+   * - ``--slices[${LABEL}].offset``
+     - Optional
+   * - ``--slices[${LABEL}].limit``
+     - Optional
+   * - ``--slices[${LABEL}].table``
+     - Optional
+
+.. _select-slices-label-match-columns:
+
+``slices[${LABEL}].match_columns``
+""""""""""""""""""""""""""""""""""
+
+TODO
+
+.. _select-slices-label-query:
+
+``slices[${LABEL}].query``
+""""""""""""""""""""""""""
+
+TODO
+
+.. _select-slices-label-filter:
+
+``slices[${LABEL}].filter``
+"""""""""""""""""""""""""""
+
+TODO
+
+.. _select-slices-label-query-expander:
+
+``slices[${LABEL}].query_expander``
+"""""""""""""""""""""""""""""""""""
+
+TODO
+
+.. _select-slices-label-query-flags:
+
+``slices[${LABEL}].query_flags``
+""""""""""""""""""""""""""""""""
+
+TODO
+
+.. _select-slices-label-sort-keys:
+
+``slices[${LABEL}].sort_keys``
+""""""""""""""""""""""""""""""
+
+TODO
+
+.. _select-slices-label-output-columns:
+
+``slices[${LABEL}].output_columns``
+"""""""""""""""""""""""""""""""""""
+
+TODO
+
+.. _select-slices-label-offset:
+
+``slices[${LABEL}].offset``
+"""""""""""""""""""""""""""
+
+TODO
+
+.. _select-slices-label-limit:
+
+``slices[${LABEL}].limit``
+""""""""""""""""""""""""""
+
+TODO
+
+.. _select-slices-label-table:
+
+``slices[${LABEL}].table``
+""""""""""""""""""""""""""
+
+TODO
+
 Cache related parameter
 ^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1918,7 +2765,7 @@ The following value part is the same format as ``SEARCH_RESULT``::
     RECORDS
   ]
 
-See also :ref:`select-drilldown-label-output-format` for
+See also :ref:`select-drilldowns-label-output-format` for
 ``drilldowns[${LABEL}]`` style drilldown output format.