rroonga 5.0.4-x86-mingw32 → 5.0.5-x86-mingw32

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

@@ -0,0 +1,107 @@
+.. -*- rst -*-
+
+.. highlightlang:: none
+
+.. groonga-command
+.. database: commands_logical_shard_list
+
+``logical_shard_list``
+======================
+
+Summary
+-------
+
+.. note::
+
+   This command is an experimental feature.
+
+.. versionadded:: 5.0.7
+
+``logical_shard_list`` returns all existing shard names against the
+specified logical table name.
+
+Syntax
+------
+
+This command takes only one required parameter::
+
+  logical_shard_list logical_table
+
+Usage
+-----
+
+You need to register ``sharding`` plugin to use this command:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/logical_shard_list/usage_register.log
+.. plugin_register sharding
+
+Here are sample shards:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/logical_shard_list/usage_shards.log
+.. table_create  Logs_20150801           TABLE_HASH_KEY ShortText
+.. column_create Logs_20150801 timestamp COLUMN_SCALAR  Time
+.. table_create  Logs_20150802           TABLE_HASH_KEY ShortText
+.. column_create Logs_20150802 timestamp COLUMN_SCALAR  Time
+.. table_create  Logs_20150930           TABLE_HASH_KEY ShortText
+.. column_create Logs_20150930 timestamp COLUMN_SCALAR  Time
+
+You can get the all shard names in ascending order by specifying
+``Logs`` as the logical table name:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/logical_shard_list/usage_list.log
+.. logical_shard_list --logical_table Logs
+
+
+Parameters
+----------
+
+This section describes parameters.
+
+Required parameters
+^^^^^^^^^^^^^^^^^^^
+
+There is one required parameter.
+
+.. _logical-shard-logical-table:
+
+``logical_table``
+"""""""""""""""""
+
+Specifies the logical table name. ``logical_shard_list`` returns a
+list of shard name of the logical table:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/logical_shard_list/logical_table.log
+.. logical_shard_list --logical_table Logs
+
+The list is sorted by shard name in ascending order.
+
+Optional parameters
+^^^^^^^^^^^^^^^^^^^
+
+There is no optional parameters.
+
+Return value
+------------
+
+The command returns a list of shard names in ascending order::
+
+  [
+    HEADER,
+    [
+      {"name": "SHARD_NAME_1"},
+      {"name": "SHARD_NAME_2"},
+      ...
+      {"name": "SHARD_NAME_N"}
+    ]
+  ]
+
+See :doc:`/reference/command/output_format` for ``HEADER``.
+
+See also
+--------
+
+  * :doc:`/reference/sharding`

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

@@ -22,7 +22,7 @@ TODO
 Syntax
 ------
 
-``logical_table_remove`` command has six parameters.
+This command takes many parameters.
 
 The required parameters are ``logical_table`` and ``shard_key``::
 
@@ -89,6 +89,8 @@ Specify ``include`` or ``exclude`` as the value of this parameter.
 Return value
 ------------
 
+TODO
+
 ::
 
   [HEADER, true]

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

@@ -25,10 +25,9 @@ It is useful for you to check the results of normalizer.
 Syntax
 --------
 
-``normalize`` commands has two required parameters. They are
-``normalizer`` and ``string``.
+This command takes three parameters.
 
-::
+``normalizer`` and ``string`` are required. Others are optional::
 
   normalize normalizer
             string

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

@@ -17,8 +17,7 @@ Summary
 Syntax
 ------
 
-``normalizer_list`` command takes no parameter.
-::
+This command takes no parameters::
 
   normalizer_list
 

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

@@ -0,0 +1,90 @@
+.. -*- rst -*-
+
+.. highlightlang:: none
+
+.. groonga-command
+.. database: commands_object_exist
+
+``object_exist``
+================
+
+Summary
+-------
+
+.. versionadded:: 5.0.6
+
+``object_exist`` returns whether object with the specified name exists
+or not in database.
+
+It's a light operation. It just checks existence of the name in the
+database. It doesn't load the specified object from disk.
+
+``object_exist`` doesn't check object type. The existing object may be
+table, column, function and so on.
+
+Syntax
+------
+
+This command takes only one required parameter::
+
+  object_exist name
+
+Usage
+-----
+
+You can check whether the name is already used in database:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/object_exist/usage.log
+.. object_exist Users
+.. table_create Users TABLE_HASH_KEY ShortText
+.. object_exist Users
+
+The ``object_exist Users`` returns ``false`` before we create
+``Users`` table.
+
+The ``object_exist Users`` returns ``true`` after we create ``Users``
+table.
+
+Parameters
+----------
+
+This section describes all parameters.
+
+Required parameters
+^^^^^^^^^^^^^^^^^^^
+
+There is only one required parameters.
+
+.. _object-exist-name:
+
+``name``
+""""""""
+
+Specifies the object name to be checked.
+
+If you want to check existence of a column, use
+``TABLE_NAME.COLUMN_NAME`` format like the following:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/object_exist/name_column.log
+.. table_create Logs TABLE_NO_KEY
+.. column_create Logs timestamp COLUMN_SCALAR Time
+.. object_exist Logs.timestamp
+
+``Logs`` is table name and ``timestamp`` is column name in
+``Logs.timestamp``.
+
+Return value
+------------
+
+The command returns ``true`` as body if object with the specified name
+exists in database such as::
+
+  [HEADER, true]
+
+The command returns ``false`` otherwise such as::
+
+  [HEADER, false]
+
+See :doc:`/reference/command/output_format` for ``HEADER``.

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

@@ -26,7 +26,7 @@ You can unregister a registered plugin by :doc:`plugin_unregister`.
 Syntax
 ------
 
-``plugin_register`` has a parameter ``name``. It is required parameter::
+This command takes only one required parameter::
 
   plugin_register name
 

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

@@ -22,7 +22,7 @@ Summary
 Syntax
 ------
 
-``plugin_unregister`` has a parameter ``name``. It is required parameter::
+This command takes only one required parameter::
 
   plugin_unregister name
 

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

@@ -30,7 +30,7 @@ process loads all registered plugins without ``register`` command.
 Syntax
 ------
 
-``register`` has a parameter ``path``. It is required parameter::
+This command takes only one required parameter::
 
   register path
 

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

@@ -35,9 +35,7 @@ If request is canceled, the canceled request has ``-5``
 Syntax
 ------
 
-``request_cancel`` command takes only one parameter.
-
-The required parameter is only ``id``::
+This command takes only one required parameter::
 
   request_cancel id
 

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

@@ -16,7 +16,7 @@ Summary
 Syntax
 ------
 
-``ruby_eval`` has one required parameter::
+This command takes only one required parameter::
 
   ruby_eval script
 

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

@@ -16,7 +16,7 @@ Summary
 Syntax
 ------
 
-``ruby_load`` has one required parameter::
+This command takes only one required parameter::
 
   ruby_load path
 

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

@@ -15,13 +15,15 @@ Summary
 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.
+understand ``select`` to use the full power of Groonga.
 
 Syntax
 ------
 
-``select`` has many parameters. The required parameter is only
-``table`` and others are optional::
+This command takes many parameters.
+
+The required parameter is only ``table``. Other parameters are
+optional::
 
   select table
          [match_columns=null]
@@ -87,7 +89,7 @@ Here are a schema definition and sample data to show usage.
 .. 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
+.. table_create Terms TABLE_PAT_KEY ShortText --default_tokenizer TokenBigram --normalizer NormalizerAuto
 .. 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
@@ -126,6 +128,8 @@ using ``TokenBigram`` tokenizer. So both ``Entries._key`` and
 
 OK. The schema and data for examples are ready.
 
+.. _select-simple-usage:
+
 Simple usage
 ^^^^^^^^^^^^
 
@@ -305,6 +309,8 @@ If nonexistent table is specified, an error is returned.
 .. include:: ../../example/reference/commands/select/table_nonexistent.log
 .. select Nonexistent
 
+.. _select-search-related-parameters:
+
 Search related parameters
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -485,10 +491,12 @@ is less than ``11`` from ``Entries`` table.
 
 See :doc:`/reference/grn_expr/script_syntax` for other operators.
 
+.. _select-advanced-search-parameters:
+
 Advanced search parameters
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. _match-escalation-threshold:
+.. _select-match-escalation-threshold:
 
 ``match_escalation_threshold``
 """"""""""""""""""""""""""""""
@@ -538,14 +546,14 @@ 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:
+.. _select-query-expansion:
 
 ``query_expansion``
 """""""""""""""""""
 
-Deprecated. Use :ref:`query-expander` instead.
+Deprecated. Use :ref:`select-query-expander` instead.
 
-.. _query-flags:
+.. _select-query-flags:
 
 ``query_flags``
 """""""""""""""
@@ -637,7 +645,7 @@ specified.
 
 See also :doc:`/reference/grn_expr/query_syntax`.
 
-.. _query-expander:
+.. _select-query-expander:
 
 ``query_expander``
 """"""""""""""""""
@@ -671,7 +679,7 @@ Here is a sample substitution table to show a simple
 
 .. groonga-command
 .. include:: ../../example/reference/commands/select/query_expander_substitution_table.log
-.. table_create Thesaurus TABLE_PAT_KEY|KEY_NORMALIZE ShortText
+.. table_create Thesaurus TABLE_PAT_KEY ShortText --normalizer NormalizerAuto
 .. column_create Thesaurus synonym COLUMN_VECTOR ShortText
 .. load --table Thesaurus
 .. [
@@ -680,12 +688,15 @@ Here is a sample substitution table to show a simple
 .. ]
 
 ``Thesaurus`` substitution table has two synonyms, ``"mroonga"`` and
-``"groonga"``. If an user searches with ``"mroonga"``, groonga
+``"groonga"``. If an user searches with ``"mroonga"``, Groonga
 searches with ``"((mroonga) OR (tritonn) OR (groonga mysql))"``. If an
-user searches with ``"groonga"``, groonga searches 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.
+user searches with ``"groonga"``, Groonga searches with ``"((groonga)
+OR (senna))"``.
+
+Normally, it's good idea that substitution table uses a
+normalizer. For example, if normalizer is used, substitute target word
+is matched in case insensitive manner. See
+:doc:`/reference/normalizers` for available normalizers.
 
 Note that those synonym values include the key value such as
 ``"mroonga"`` and ``"groonga"``. It's recommended that you include the
@@ -840,6 +851,8 @@ number of records is ``5``.
 
 The default value is ``0``.
 
+.. _select-limit:
+
 ``limit``
 """""""""
 
@@ -868,6 +881,8 @@ The ``select`` command outputs all records.
 
 The default value is ``10``.
 
+.. _select-scorer:
+
 ``scorer``
 """"""""""
 
@@ -1190,7 +1205,7 @@ You can use the following calculation types:
      - ``_nsubrecs``
      - Not needs.
      - Counting grouped records. It's always enabled. So you don't
-       specify it.
+       need to specify it.
    * - ``MAX``
      - ``_max``
      - Needs.
@@ -1358,7 +1373,9 @@ parameters:
   * ``.``
   * ``_``
 
-.. You can use more characters but it's better that you use only these
+.. note::
+
+   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
@@ -1533,16 +1550,38 @@ result.
 Cache related parameter
 ^^^^^^^^^^^^^^^^^^^^^^^
 
+.. _select-cache:
+
 ``cache``
 """""""""
 
-TODO: write in English and add example.
+Specifies whether caching the result of this query or not.
+
+If the result of this query is cached, the next same query returns
+response quickly by using the cache.
+
+It doesn't control whether existing cached result is used or not.
+
+Here are available values:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Value
+     - Description
+   * - ``no``
+     - Don't cache the output of this query.
+   * - ``yes``
+     - Cache the output of this query.
+       It's the default value.
 
-クエリキャッシュに関する動作を設定します。
+Here is an example to disable caching the result of this query:
 
-``no``
+.. groonga-command
+.. include:: ../../example/reference/commands/select/cache_no.log
+.. select Entries --cache no
 
-  検索結果をクエリキャッシュに残しません。キャッシュして再利用される可能性が低いクエリに対して用います。キャッシュ容量は有限です。有効なキャッシュが多くヒットするために、このパラメータは有効です。
+The default value is ``yes``.
 
 Score related parameters
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1642,73 +1681,218 @@ the same value. You can change increase score for each record that has
 the same ``"KEYWORD"``. It is useful to tune search score. See
 :ref:`weight-vector-column` for details.
 
-返値
-----
+.. _select-return-value:
 
-TODO: write in English and add example.
+Return value
+------------
+
+``select`` returns response with the following format::
+
+  [
+    HEADER,
+    [
+      SEARCH_RESULT,
+      DRILLDOWN_RESULT_1,
+      DRILLDOWN_RESULT_2,
+      ...,
+      DRILLDOWN_RESULT_N
+    ]
+  ]
+
+If ``select`` fails, error details are in ``HEADER``.
+
+See :doc:`/reference/command/output_format` for ``HEADER``.
+
+There are zero or more ``DRILLDOWN_RESULT``. If no ``drilldown`` and
+``drilldown[${LABEL}].keys`` are specified, they are omitted like the
+following::
+
+  [
+    HEADER,
+    [
+      SEARCH_RESULT
+    ]
+  ]
 
-以下のようなjson形式で値が返却されます。
+If ``drilldown`` has two or more keys like ``--drilldown "_key,
+column1, column2"``, multiple ``DRILLDOWN_RESULT`` exist::
 
-::
+  [
+    HEADER,
+    [
+      SEARCH_RESULT,
+      DRILLDOWN_RESULT_FOR_KEY,
+      DRILLDOWN_RESULT_FOR_COLUMN1,
+      DRILLDOWN_RESULT_FOR_COLUMN2
+    ]
+  ]
 
- [[リターンコード, 処理開始時間, 処理時間], [検索結果, ドリルダウン結果]]
+If ``drilldown[${LABEL}].keys`` is used, only one ``DRILLDOWN_RESULT``
+exist::
 
-``リターンコード``
+  [
+    HEADER,
+    [
+      SEARCH_RESULT,
+      DRILLDOWN_RESULT_FOR_LABELED_DRILLDOWN
+    ]
+  ]
 
-  grn_rcに対応する数値が返されます。0(GRN_SUCCESS)以外の場合は、続いてエラー内容を示す
-  文字列が返されます。
+``DRILLDOWN_RESULT`` format is different between ``drilldown`` and
+``drilldown[${LABEL}].keys``. It's described later.
 
-``処理開始時間``
+``SEARCH_RESULT`` is the following format::
 
-  処理を開始した時間について、1970年1月1日0時0分0秒を起点とした秒数を小数で返します。
+  [
+    [N_HITS],
+    COLUMNS,
+    RECORDS
+  ]
 
-``処理時間``
+See :ref:`select-simple-usage` for concrete example of the format.
 
-  処理にかかった秒数を返します。
+``N_HITS`` is the number of matched records before :ref:`select-limit`
+is applied.
 
-``検索結果``
+``COLUMNS`` describes about output columns specified by
+:ref:`select-output-columns`. It uses the following format::
 
-  drilldown条件が実行される前の検索結果が以下のように出力されます。::
+  [
+    [COLUMN_NAME_1, COLUMN_TYPE_1],
+    [COLUMN_NAME_2, COLUMN_TYPE_2],
+    ...,
+    [COLUMN_NAME_N, COLUMN_TYPE_N]
+  ]
+
+``COLUMNS`` includes one or more output column information. Each
+output column information includes the followings:
 
-    [[ヒット数], [[カラム名1,カラム型1],..], 検索結果1,..]
+  * Column name as string
+  * Column type as string or ``null``
 
-  ``ヒット数``
+Column name is extracted from value specified as
+:ref:`select-output-columns`.
 
-    検索条件にヒットしたレコードの数が出力されます。 ``--limit`` オプションで出力件数を制限した場合は出力するレコード数と一致しません。 ``ヒット数`` は ``--limit`` オプションに関係なく常にヒットしたレコードの数になります。
+Column type is Groonga's type name or ``null``. It doesn't describe
+whether the column value is vector or scalar. You need to determine it
+by whether real column value is array or not.
 
-  ``カラム名n``
+See :doc:`/reference/types` for type details.
 
-    output_columnsに指定された条件に従って、対象となるカラム名が出力されます。
+``null`` is used when column value type isn't determined. For example,
+function call in :ref:`select-output-columns` such as
+``--output_columns "snippet_html(content)"`` uses ``null``.
 
-  ``カラム型n``
+Here is an example of ``COLUMNS``::
+
+  [
+    ["_id",     "UInt32"],
+    ["_key",    "ShortText"],
+    ["n_likes", "UInt32"],
+  ]
 
-    output_columnsに指定された条件に従って、対象となるカラム型が出力されます。
+``RECORDS`` includes column values for each matched record. Included
+records are selected by :ref:`select-offset` and
+:ref:`select-limit`. It uses the following format::
 
-  ``検索結果n``
+  [
+    [
+      RECORD_1_COLUMN_1,
+      RECORD_1_COLUMN_2,
+      ...,
+      RECORD_1_COLUMN_N
+    ],
+    [
+      RECORD_2_COLUMN_1,
+      RECORD_2_COLUMN_2,
+      ...,
+      RECORD_2_COLUMN_N
+    ],
+    ...
+    [
+      RECORD_N_COLUMN_1,
+      RECORD_N_COLUMN_2,
+      ...,
+      RECORD_N_COLUMN_N
+    ]
+  ]
 
-    output_columns, offset, limitによって指定された条件に従って各レコードの値が出力されます。
+Here is an example ``RECORDS``::
 
-``drilldown結果``
+  [
+    [
+      1,
+      "The first post!",
+      5
+    ],
+    [
+      2,
+      "Groonga",
+      10
+    ],
+    [
+      3,
+      "Mroonga",
+      15
+    ]
+  ]
 
-  drilldown処理の結果が以下のように出力されます。::
+``DRILLDOWN_RESULT`` format is different between ``drilldown`` and
+``drilldown[${LABEL}].keys``.
 
-    [[[件数], [[カラム名1,カラム型1],..], 検索結果1,..],..]
+``drilldown`` uses the same format as ``SEARCH_RESULT``::
 
-  ``件数``
+  [
+    [N_HITS],
+    COLUMNS,
+    RECORDS
+  ]
 
-    drilldownに指定されたカラムの値の異なり数が出力されます。
+And ``drilldown`` generates one or more ``DRILLDOWN_RESULT`` when
+:ref:`select-drilldown` has one ore more keys.
+
+``drilldown[${LABEL}].keys`` uses the following format. Multiple
+``drilldown[${LABEL}].keys`` are mapped to one object (key-value
+pairs)::
+
+  {
+    "LABEL_1": [
+      [N_HITS],
+      COLUMNS,
+      RECORDS
+    ],
+    "LABEL_2": [
+      [N_HITS],
+      COLUMNS,
+      RECORDS
+    ],
+    ...,
+    "LABEL_N": [
+      [N_HITS],
+      COLUMNS,
+      RECORDS
+    ]
+  }
 
-  ``カラム名n``
+Each ``drilldown[${LABEL}].keys`` corresponds to the following::
 
-    drilldown_output_columnsに指定された条件に従って、対象となるカラム名が出力されます。
+  "LABEL": [
+    [N_HITS],
+    COLUMNS,
+    RECORDS
+  ]
 
-  ``カラム型n``
+The following value part is the same format as ``SEARCH_RESULT``::
 
-    drilldown_output_columnsに指定された条件に従って、対象となるカラム型が出力されます。
+  [
+    [N_HITS],
+    COLUMNS,
+    RECORDS
+  ]
 
-  ``ドリルダウン結果n``
+See also :ref:`select-drilldown-label-output-format` for
+``drilldown[${LABEL}]`` style drilldown output format.
 
-    drilldown_output_columns, drilldown_offset, drilldown_limitによって指定された条件に従って各レコードの値が出力されます。
 
 See also
 --------