rroonga 6.0.0-x64-mingw32 → 6.0.2-x64-mingw32

data/vendor/local/share/doc/groonga/ja/html/_sources/reference/commands/thread_limit.txt

@@ -74,7 +74,7 @@ This section describes all parameters.
 Required parameters
 ^^^^^^^^^^^^^^^^^^^
 
-There is no required parameters.
+There is no required parameter.
 
 Optional parameters
 ^^^^^^^^^^^^^^^^^^^

data/vendor/local/share/doc/groonga/ja/html/_sources/reference/commands/truncate.txt

@@ -68,8 +68,8 @@ Parameters
 
 This section describes parameters of ``truncate``.
 
-Required parameter
-^^^^^^^^^^^^^^^^^^
+Required parameters
+^^^^^^^^^^^^^^^^^^^
 
 There is required parameter, ``target_name``.
 

data/vendor/local/share/doc/groonga/ja/html/_sources/reference/executables/groonga-httpd.txt

@@ -106,7 +106,7 @@ Finally, to terminate the running groonga-httpd daemon, run this::
 Configuration directives
 ------------------------
 
-This section decribes only important directives. They are
+This section describes only important directives. They are
 groonga-httpd specific directives and performance related directives.
 
 The following directives can be used in the groonga-httpd configuration file.

data/vendor/local/share/doc/groonga/ja/html/_sources/reference/executables/groonga-suggest-httpd.txt

@@ -4,173 +4,374 @@
 
 .. groonga-command
 .. database: groonga-suggest-httpd
+.. % killall lt-groonga-suggest-learner || :
+.. % killall lt-groonga-suggest-httpd || :
 
-groonga-suggest-httpd
-=====================
+``groonga-suggest-httpd``
+=========================
 
 Summary
 -------
 
-groonga-suggest-httpd is a program to provide interface which accepts HTTP request and returns suggestion dataset, then saves logs for learning.
-groonga-suggest-httpd behaves similar in point of view of suggestion functionality, but the name of parameter is different.
+``groonga-suggest-httpd`` is a program that provides HTTP interface
+for the following features:
 
-Synopsis
---------
+  * Returning :doc:`/reference/suggest` execution result
+  * Saving logs for learning
+
+``groonga-suggest-httpd`` provides suggest feature like
+:doc:`/reference/commands/suggest` command. Note that some parameter
+names are different of them.
 
-::
+Syntax
+------
 
-  groonga-suggest-httpd [options] database_path
+``groonga-suggest-httpd`` requires database path::
+
+  groonga-suggest-httpd [options] DATABASE_PATH
 
 Usage
 -----
 
+You need to create one or more datasets to use
+``groonga-suggest-httpd``. A dataset consists of tables and
+columns. You can define them by :doc:`groonga-suggest-create-dataset`.
 
-Set up
-^^^^^^
+You need to use :doc:`groonga-suggest-learner` to learn suggestion
+data from user inputs. You doesn't need to use
+:doc:`groonga-suggest-learner` when you create suggestion data by
+hand. See :doc:`/reference/suggest` and sub documents about creating
+suggestion data by hand.
 
-First you need to set up database for suggestion.
+You can use ``groonga-suggest-httpd`` via HTTP after you create one or
+more datasets.
 
-.. groonga-command
-.. include:: ../example/reference/executables/groonga-suggest-httpd-setup.log
-.. .. % groonga-suggest-create-dataset /tmp/groonga-databases/groonga-suggest-httpd query
+The following sections describes the followings:
 
-Launch groonga-suggest-httpd
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  * How to set up a dataset
+  * How to use ``groonga-suggest-httpd`` with :doc:`groonga-suggest-learner`
+  * How to use ``groonga-suggest-httpd`` for retrieving suggestions.
 
-Execute groonga-suggest-httpd command:
+Setup
+^^^^^
+
+You need to create a dataset by :doc:`groonga-suggest-create-dataset`.
+
+Here is an example that creates ``query`` dataset:
 
 .. groonga-command
-.. include:: ../example/reference/executables/groonga-suggest-httpd-launch.log
-.. .. % groonga-suggest-httpd /tmp/groonga-databases/groonga-suggest-httpd
+.. include:: ../../example/reference/executables/groonga-suggest-httpd/setup.log
+.. % groonga-suggest-create-dataset ${DB_PATH} query
 
-After executing above command, groonga-suggest-httpd accepts HTTP request on 8080 port.
+:doc:`groonga-suggest-create-dataset` outputs executed commands. You
+can confirm that what tables and columns are created for the new
+dataset.
 
-If you just want to save requests into log file, use ``-l`` option.
+Launch ``groonga-suggest-learner``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Here is the example to save log files under ``logs`` directory with ``log`` prefix for each file.::
+You can choose whether you use learned suggestion data immediately or
+not.
 
-  % groonga-suggest-httpd -l logs/log /tmp/groonga-databases/groonga-suggest-httpd
+There are two ways to use learned suggestion data immediately:
 
-Under ``logs`` directory, log files such as ``logYYYYmmddHHMMSS-00`` are created.
+  * Both of ``groonga-suggest-httpd`` and
+    :doc:`groonga-suggest-learner` use the same database
+  * ``groonga-suggest-httpd`` receives learned suggestion data from
+    :doc:`groonga-suggest-learner`
 
-Request to groonga-suggest-httpd
+In the former case, you must run both ``groonga-suggest-httpd`` and
+:doc:`groonga-suggest-learner` on the same host.
+
+In the latter case, you can run ``groonga-suggest-httpd`` and
+:doc:`groonga-suggest-learner` on different hosts.
+
+If you don't need to use learned suggestion data immediately, you need
+to apply learned suggestion data from database that is used by
+:doc:`groonga-suggest-learner` to database that is used by
+``groonga-suggest-httpd`` by hand. Normally, this usage is
+recommended. Because learned suggestion data may have garbage data by
+inputs from evil users.
+
+In this document, learned suggestion data are used immediately by
+receiving learned suggestion data from
+:doc:`groonga-suggest-learner`. Both ``groonga-suggest-httpd`` and
+:doc:`groonga-suggest-learner` are running on the same host. Because
+it's easy to explain.
+
+Here is an example that launches :doc:`groonga-suggest-learner`. You
+need to specify database that has ``query`` dataset. This document
+omits the instruction for creating ``query`` dataset:
+
+.. groonga-command
+.. database: groonga-suggest-httpd-learner
+.. % groonga-suggest-create-dataset ${DB_PATH} query
+
+.. groonga-command
+.. include:: ../../example/reference/executables/groonga-suggest-httpd/launch-lerner.log
+.. % groonga-suggest-learner --daemon ${DB_PATH}
+
+The ``groonga-suggest-learner`` process opens two endpoints at
+``1234`` port and ``1235`` port:
+
+  * ``1234`` port: Endpoint that accepts user input data from
+    ``groogna-suggest-httpd``
+  * ``1235`` port: Endpoint that sends learned suggestion data to
+    ``groogna-suggest-httpd``
+
+Launch ``groonga-suggest-httpd``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Here is the sample requests to learn ``groonga`` for ``query`` dataset::
+You need to launch ``groonga-suggest-httpd`` for the following proposes:
 
-  % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=92619&t=complete&q=g'
-  % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=93850&t=complete&q=gr'
-  % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=94293&t=complete&q=gro'
-  % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=94734&t=complete&q=groo'
-  % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=95147&t=complete&q=grooon'
-  % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=95553&t=complete&q=groonga'
-  % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=95959&t=submit&q=groonga
+  * Learning suggestion data from user inputs
+  * Providing suggestion result to clients
 
-Options
--------
+Here is an example that launches ``groonga-suggest-httpd`` that
+communicates :doc:`groonga-suggest-learner`:
 
-.. cmdoption:: -p, --port
+.. groonga-command
+.. database: groonga-suggest-httpd
 
-   Specify http server port number. The default value is 8080.
+.. groonga-command
+.. include:: ../../example/reference/executables/groonga-suggest-httpd/launch.log
+.. % groonga-suggest-httpd --send-endpoint 'tcp://127.0.0.1:1234' --receive-endpoint 'tcp://127.0.0.1:1235' --daemon ${DB_PATH}
 
-.. cmdoption:: -t, --n-threads
+The ``groonga-suggest-httpd`` process accepts HTTP requests on
+``8080`` port.
 
-   Specify number of threads. The default value is 8.
-   This option accepts 128 as the max value, but use the number of CPU cores for
-   performance.
+If you want to save requests into log file, use
+:option:`--log-base-path` option.
 
-.. cmdoption:: -s, --send-endpoint
+Here is an example to save log files under ``logs`` directory with
+``log`` prefix for each file::
 
-   Specify endpoint for sender.
+  % groonga-suggest-httpd --log-base-path logs/log ${DB_PATH}
 
-.. cmdoption:: -r, --receive-endpoint
+``groonga-suggest-httpd`` creates log files such as
+``logYYYYmmddHHMMSS-00`` under ``logs`` directory.
 
-   Specify endpoint for receiver.
+Learn from user inputs
+^^^^^^^^^^^^^^^^^^^^^^
 
-.. cmdoption:: -l, --log-base-path
+You can learn suggestion data from user inputs.
 
-   Specify path prefix of log.
+You need to specify the following parameters to learn suggestion data:
 
-.. cmdoption:: --n-lines-per-log-file
+  * ``i``: The ID of the user (You may use IP address of client)
+  * ``l``: The dataset name
+  * ``s``: The timestamp of the input in seconds
+  * ``t``: The query type (It's optional. You must specify ``submit`` only when the user input is submitted.)
+  * ``q``: The user input
 
-   Specify the number of lines in a log file. The default value is 1,000,000.
+Here are example requests to learn user input "Groonga" in ``query``
+dataset::
 
-.. cmdoption:: -d, --daemon
+.. groonga-command
+.. include:: ../../example/reference/executables/groonga-suggest-httpd/learn.log
+.. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=92619&q=G'
+.. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=93850&q=Gr'
+.. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=94293&q=Gro'
+.. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=94734&q=Groo'
+.. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=95147&q=Grooon'
+.. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=95553&q=Groonga'
+.. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=95959&t=submit&q=Groonga'
 
-   Specify this option to daemonize.
+Inputting data must not use ``t=submit`` parameter. In the above example, you just learn user inputs but you can learn and get complete candidates at once. It's described at the next section.
 
-.. cmdoption:: --disable-max-fd-check
+Submitted data must use ``t=submit`` parameter.
 
-   Specify this option to disable checking max fd on start.
+Use suggested response
+^^^^^^^^^^^^^^^^^^^^^^
+
+You can get suggested result from ``groonga-suggest-httpd``.
+
+You need to specify the following parameters to get suggested result:
+
+  * ``n``: The dataset name
+  * ``t``: The query type (``complete``, ``correct`` and/or ``suggest``)
+  * ``q``: The user input
+
+You can also specify parameters for :doc:`/reference/commands/suggest` as option.
+
+Here is an example that gets :doc:`/reference/suggest/completion` result. The result is computed by using learned data at the previous section. ``frequency_threshold=1`` parameter is used because this is an example. The parameter enables input data that are occurred one or more times. Normally, you should not use the parameter for production. The parameter will increase noises:
+
+.. groonga-command
+.. include:: ../../example/reference/executables/groonga-suggest-httpd/complete.log
+.. % curl 'http://localhost:8080/?n=query&t=complete&q=G&frequency_threshold=1'
+
+You can combine completion and learning by specifying parameters for both:
+
+.. groonga-command
+.. include:: ../../example/reference/executables/groonga-suggest-httpd/learn-and-complete.log
+.. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=96000&q=G&n=query&t=complete&frequency_threshold=1'
 
 Command line parameters
 -----------------------
 
-There is one required parameter - ``database_path``.
+Required parameters
+^^^^^^^^^^^^^^^^^^^
+
+There is one required parameter.
+
+``DATABASE_PATH``
+"""""""""""""""""
+
+Specifies the path to a Groonga database. This database must have one
+or more datasets. Each dataset must be created by
+:doc:`groonga-suggest-create-dataset`.
 
-``database_path``
+Optional parameters
 ^^^^^^^^^^^^^^^^^^^
 
-Specifies the path to a Groonga database. This database must be created by :doc:`groonga-suggest-create-dataset` command because it executes required initialization for suggestion.
+.. option:: -p, --port
+
+   Specify HTTP server port number.
+
+   The default port number is ``8080``.
+
+.. option:: -t, --n-threads
+
+   Specify number of threads.
+
+   This option accepts ``128`` as the max value, but use the number of
+   CPU cores for performance.
+
+   The default value is the number of CPU cores.
+
+.. option:: -s, --send-endpoint
+
+   Specify endpoint URI of :doc:`groonga-suggest-learner` for sending
+   user inputs.
+
+   The format is ``tcp://${HOST}:${PORT}`` such as
+   ``tcp://192.168.0.1:2929``.
 
+   The default value is none.
+
+.. option:: -r, --receive-endpoint
+
+   Specify endpoint URI of :doc:`groonga-suggest-learner` for
+   receiving learned suggestion data.
+
+   The format is ``tcp://${HOST}:${PORT}`` such as
+   ``tcp://192.168.0.1:2929``.
+
+   The default value is none.
+
+.. option:: -l, --log-base-path
+
+   Specify path prefix of log.
+
+   The default value is none.
+
+.. option:: --n-lines-per-log-file
+
+   Specify the max number of lines in a log file.
+
+   The default value is ``1000000``.
+
+.. option:: -d, --daemon
+
+   Specify this option to daemonize.
+
+   Don't daemonize by default.
+
+.. option:: --disable-max-fd-check
+
+   Specify this option to disable checking the max number of file
+   descriptors on start.
+
+   Check by default.
 
 GET parameters
 --------------
 
-groonga-suggest-httpd accepts following GET parameters.
+``groonga-suggest-httpd`` accepts some GET parameters.
 
-There are required parameters which depends on type of query.
+There are required parameters which depend on query type.
+
+In ``complete``, ``correct`` or ``suggest`` query type, unhandled
+parameters are passed through :doc:`/reference/commands/suggest`. It
+means that you can use parameters of
+:doc:`/reference/commands/suggest`.
+
+.. _groonga-suggest-httpd-required-parameters:
 
 Required parameters
 ^^^^^^^^^^^^^^^^^^^
 
+You must specify the following parameters.
+
 .. list-table::
    :header-rows: 1
 
    * - Key
      - Description
      - Note
-   * - q
-     - UTF-8 encoded string which user fills in form
-     - 
-   * - t
-     - The type of query. The value of type must be complete, correct, suggest or submit. It also accepts multiple type of query which is concatinated by ``|``. Note that ``submit`` is invalid value when you specify multiple type of query.
-     - 
+   * - ``q``
+     - Input by user. It must be UTF-8 encoded string.
+     -
+
+.. _groonga-suggest-httpd-required-parameters-learning:
 
 Required parameters for learning
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+You must specify the following parameters when you specify
+:option:`--send-endpoint`.
+
 .. list-table::
    :header-rows: 1
 
    * - Key
      - Description
      - Note
-   * - s
-     - Elapsed time from 0:00 January 1, 1970
-     - Note that you need specify the value of ``s`` in milliseconds
-   * - i
-     - Unique ID to distinct user
-     - Use session ID or IP address for example
-   * - l
-     - Specify the name of dataset for learning. It also accepts multiple dataset name which is concatinated by ``|``
-     - Note that dataset name must be matched to following regular expression ``[A-Za-z ][A-Za-z0-9 ]{0,15}``
+   * - ``s``
+     - Elapsed time since ``1970-01-01T00:00:00Z``.
+     - The unit is millisecond.
+   * - ``i``
+     - Unique ID to distinct each user
+     - Session ID, IP address and so on will be usable
+       for this value.
+   * - ``l``
+     - One or more learn target dataset names. You need to use ``|``
+       as separator such as ``dataset1|dataset2|dataset3``.
+     - Dataset name is the name that you specify to
+       :doc:`groonga-suggest-create-dataset`.
+
+.. _groonga-suggest-httpd-required-parameters-suggestion:
 
 Required parameters for suggestion
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+You must specify the following parameters when you specify one of
+``complete``, ``correct`` and ``suggest`` to ``t`` parameter.
+
 .. list-table::
    :header-rows: 1
 
    * - Key
      - Description
      - Note
-   * - n
-     - Specify the name of dataset for suggestion
-     - This dataset name is used to calculate suggestion results
+   * - ``n``
+     - The dataset name to use computing suggestion result.
+     - Dataset name is the name that you specify to
+       :doc:`groonga-suggest-create-dataset`.
+   * - ``t``
+     - The query type.
 
-Optional parameter
-^^^^^^^^^^^^^^^^^^
+       Available values are ``complete``, ``correct``, ``suggest``.
+
+     - You can specify multiple types. You need to use ``|`` as
+       separator such as ``complete|correct``.
+
+.. _groonga-suggest-httpd-optional-parameters:
+
+Optional parameters
+^^^^^^^^^^^^^^^^^^^
+
+Here are optional parameters.
 
 .. list-table::
    :header-rows: 1
@@ -178,33 +379,90 @@ Optional parameter
    * - Key
      - Description
      - Note
-   * - callback
-     - Specify the name of function if you prefer JSONP as response format
-     - The name of function must be matched to reqular expression ``[A-Za-z ][A-Za-z0-9 ]{0,15}``
+   * - ``callback``
+     - Function name for JSONP
+     -
 
-Return value
-------------
+.. _groonga-suggest-httpd-optional-parameters-learning:
+
+Optional parameters for learning
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Here are optional parameters when you specify
+:option:`--send-endpoint`.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Description
+     - Note
+   * - ``t``
+     - The query type.
 
-``groonga-suggest-httpd`` command returns following response in JSON or JSONP format.
+       Available value is only ``submit``.
 
-In JSON format::
+     - You must specify ``submit`` when user submits the input
+       specified as ``q``.
 
-  {TYPE: [[CANDIDATE_1, SCORE_1], [CANDIDATE_2, SCORE_2], ... [CANDIDATE_N, SCORE_N]]}
+       You must not specify ``submit`` for user inputs that aren't
+       submitted yet. You can use suggestion by specifying
+       ``complete``, ``correct`` and/or ``suggest`` to ``t`` when you
+       doesn't specify ``submit``. See
+       :ref:`groonga-suggest-httpd-required-parameters-suggestion` for
+       details about these values.
 
-In JSONP format::
 
-  FUNCTION({TYPE: [[CANDIDATE_1, SCORE_1], [CANDIDATE_2, SCORE_2], ... [CANDIDATE_N, SCORE_N]]})
+Return value
+------------
 
+``groonga-suggest-httpd`` returns the following format response. It's
+the same format as body of :doc:`/reference/commands/suggest`::
+
+  {
+    TYPE1: [
+      [CANDIDATE_1, SCORE_1],
+      [CANDIDATE_2, SCORE_2],
+      ...,
+      [CANDIDATE_N, SCORE_N]
+    ],
+    TYPE2: [
+      [CANDIDATE_1, SCORE_1],
+      [CANDIDATE_2, SCORE_2],
+      ...,
+      [CANDIDATE_N, SCORE_N]
+    ],
+    ...
+  }
+
+Here is the response when ``t`` is ``submit``::
+
+  {}
 
 ``TYPE``
+^^^^^^^^
 
-  One of ``complete``, ``correct`` and ``suggest``.
+One of ``complete``, ``correct`` and ``suggest``.
 
 ``CANDIDATE_N``
+^^^^^^^^^^^^^^^
 
-  The string of candidate (UTF-8).
+The string of candidate in UTF-8.
 
 ``SCORE_N``
+^^^^^^^^^^^
+
+The score of the candidate.
+
+Candidates are sorted by score descendant.
 
-  The score.
+See also
+--------
+
+  * :doc:`/reference/commands/suggest`
 
+.. groonga-command
+.. % killall lt-groonga-suggest-learner || :
+.. % killall lt-groonga-suggest-httpd || :
+.. % killall -KILL lt-groonga-suggest-learner || :
+.. % killall -KILL lt-groonga-suggest-httpd || :