rroonga 4.0.0-x86-mingw32 → 4.0.1-x86-mingw32

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

@@ -0,0 +1,25 @@
+.. -*- rst -*-
+
+.. highlightlang:: none
+
+Column
+======
+
+Column is a data store object or an index object for fast search.
+
+A column belongs to a table. Table has zero or more columns.
+
+Both data store column and index column have type. Type of data store
+column specifies data range. In other words, it is "value type". Type
+of index column specifies set of documents to be indexed. A set of
+documents is a table in Groonga. In other words, type of index column
+must be a table.
+
+Here are data store columns:
+
+  * :doc:`columns/scalar`
+  * :doc:`columns/vector`
+
+Here is an index column:
+
+  * :doc:`columns/index`

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

@@ -0,0 +1,333 @@
+.. -*- rst -*-
+
+.. highlightlang:: none
+
+.. groonga-command
+.. database: columns_vector
+
+Vector column
+=============
+
+Summary
+-------
+
+Vector column is a data store object. It can stores zero or more
+scalar values. In short, scalar value is a single value such as number
+and string. See :doc:`scalar` about scalar value details.
+
+One of vector column use cases is tags store. You can use a vector
+column to store tag values.
+
+You can use vector column as index search target in the same way as
+scalar column. You can set weight for each element. The element that
+has one or more weight is matched, the record has more score rather
+than no weight case. It is a vector column specific feature. Vector
+column that can store weight is called weight vector column.
+
+You can also do full text search against each text element. But search
+score is too high when weight is used. You should use full text search
+with weight carefully.
+
+Usage
+-----
+
+There are three vector column types:
+
+  * Normal vector column
+  * Reference vector column
+  * Weight vector column
+
+This section describes how to use these types.
+
+.. _normal-vector-column:
+
+Normal vector column
+^^^^^^^^^^^^^^^^^^^^
+
+Normal vector column stores zero or more scalar data. For example,
+scalar data are number, string and so on.
+
+A normal vector column can store the same type elements. You can't mix
+types. For example, you can't store a number and a string in the same
+normal vector column.
+
+Normal vector column is useful when a record has multiple values with
+a key. Tags are the most popular use case.
+
+How to create
+"""""""""""""
+
+Use :doc:`/reference/commands/column_create` command to create a
+normal vector column. The point is ``COLUMN_VECTOR`` flag:
+
+.. groonga-command
+.. include:: ../../example/reference/columns/vector/usage_create_normal.log
+.. table_create Bookmarks TABLE_HASH_KEY ShortText
+.. column_create Bookmarks tags COLUMN_VECTOR ShortText
+
+You can set zero or more tags to a bookmark.
+
+How to load
+"""""""""""
+
+You can load vector data by JSON array syntax::
+
+  [ELEMENT1, ELEMENT2, ELEMENT3, ...]
+
+Let's load the following data:
+
+.. list-table::
+   :header-rows: 1
+
+   * - ``_key``
+     - ``tags``
+   * - ``http://groonga.org/``
+     - ``["groonga"]``
+   * - ``http://mroonga.org/``
+     - ``["mroonga", "mysql", "groonga"]``
+   * - ``http://ranguba.org/``
+     - ``["ruby", "groonga"]``
+
+Here is a command that loads the data:
+
+.. groonga-command
+.. include:: ../../example/reference/columns/vector/usage_load_normal.log
+.. load --table Bookmarks
+.. [
+.. {"_key": "http://groonga.org/", "tags": ["groonga"]},
+.. {"_key": "http://mroonga.org/", "tags": ["mroonga", "mysql", "groonga"]},
+.. {"_key": "http://ranguba.org/", "tags": ["ruby", "groonga"]}
+.. ]
+
+The loaded data can be outputted as JSON array syntax:
+
+.. groonga-command
+.. include:: ../../example/reference/columns/vector/usage_output_normal.log
+.. select Bookmarks
+
+How to search
+"""""""""""""
+
+You need to create an index to search normal vector column:
+
+.. groonga-command
+.. include:: ../../example/reference/columns/vector/usage_index_normal.log
+.. table_create Tags TABLE_PAT_KEY ShortText
+.. column_create Tags bookmark_index COLUMN_INDEX Bookmarks tags
+
+There are no vector column specific way. You can create an index like
+a scalar column.
+
+You can search an element in ``tags`` like full text search syntax.
+
+With :ref:`select-match-columns` and :ref:`select-query`:
+
+.. groonga-command
+.. include:: ../../example/reference/columns/vector/usage_query_normal.log
+.. select Bookmarks --match_columns tags --query mysql --output_columns _key,tags,_score
+
+You can also use weight in :ref:`select-match-columns`:
+
+.. groonga-command
+.. include:: ../../example/reference/columns/vector/usage_query_weight_normal.log
+.. select Bookmarks --match_columns 'tags * 3' --query mysql --output_columns _key,tags,_score
+
+With :ref:`select-filter`:
+
+.. groonga-command
+.. include:: ../../example/reference/columns/vector/usage_filter_normal.log
+.. select Bookmarks --filter 'tags @ "msyql"' --output_columns _key,tags,_score
+
+.. groonga-command
+.. table_remove Tags
+.. table_remove Bookmarks
+
+.. _reference-vector-column:
+
+Reference vector column
+^^^^^^^^^^^^^^^^^^^^^^^
+
+TODO
+
+Reference vector column is space-efficient if there are many same
+value elements. Reference vector column keeps reference record IDs not
+value itself. Record ID is smaller than value itself.
+
+How to create
+"""""""""""""
+
+TODO
+
+How to load
+"""""""""""
+
+TODO
+
+How to search
+"""""""""""""
+
+TODO
+
+.. _weight-vector-column:
+
+Weight vector column
+^^^^^^^^^^^^^^^^^^^^
+
+Weight vector column is similar to normal vector column. It can store
+elements. It can also stores weights for them. Weight is degree of
+importance of the element.
+
+Weight is positive integer. ``0`` is the default weight. It means that
+no weight.
+
+If weight is one or larger, search score is increased by the
+weight. If the weight is ``0``, score is ``1``. If the weight is
+``10``, score is ``11`` (``= 1 + 10``).
+
+Weight vector column is useful for tuning search score. See also
+:ref:`select-adjuster`. You can increase search score of specific
+records.
+
+Limitations
+"""""""""""
+
+There are some limitations for now. They will be resolved in the
+future.
+
+Here are limitations:
+
+  * You need to use string representation for element value on load.
+    For example, you can't use ``29`` for number 29. You need to use
+    ``"29"`` for number 29.
+  * You can't use reference type.
+
+How to create
+"""""""""""""
+
+Use :doc:`/reference/commands/column_create` command to create a
+weight vector column. The point is ``COLUMN_VECTOR|WITH_WEIGHT``
+flags:
+
+.. groonga-command
+.. include:: ../../example/reference/columns/vector/usage_create_weight.log
+.. table_create Bookmarks TABLE_HASH_KEY ShortText
+.. column_create Bookmarks tags COLUMN_VECTOR|WITH_WEIGHT ShortText
+
+If you don't specify ``WITH_WEIGHT`` flag, it is just a normal vector
+column.
+
+You can set zero or more tags with weight to a bookmark.
+
+How to load
+"""""""""""
+
+You can load vector data by JSON object syntax::
+
+  {"ELEMENT1": WEIGHT1, "ELEMENT2": WEIGHT2, "ELEMENT3": WEIGHT3, ...}
+
+Let's load the following data:
+
+.. list-table::
+   :header-rows: 1
+
+   * - ``_key``
+     - ``tags``
+   * - ``http://groonga.org/``
+     - ``{"groonga": 100}``
+   * - ``http://mroonga.org/``
+     - ``{"mroonga": 100, "mysql": 50, "groonga": 10}``
+   * - ``http://ranguba.org/``
+     - ``{"ruby": 100, "groonga": 50}``
+
+Here is a command that loads the data:
+
+.. groonga-command
+.. include:: ../../example/reference/columns/vector/usage_load_weight.log
+.. load --table Bookmarks
+.. [
+.. {"_key": "http://groonga.org/",
+..  "tags": {"groonga": 100}},
+.. {"_key": "http://mroonga.org/",
+..  "tags": {"mroonga": 100,
+..           "mysql":   50,
+..           "groonga": 10}},
+.. {"_key": "http://ranguba.org/",
+..  "tags": {"ruby": 100,
+..           "groonga": 50}}
+.. ]
+
+The loaded data can be outputted as JSON object syntax:
+
+.. groonga-command
+.. include:: ../../example/reference/columns/vector/usage_output_weight.log
+.. select Bookmarks
+
+How to search
+"""""""""""""
+
+You need to create an index to search weight vector column. You don't
+forget to specify ``WITH_WEIGHT`` flag to ``column_create``:
+
+.. groonga-command
+.. include:: ../../example/reference/columns/vector/usage_index_weight.log
+.. table_create Tags TABLE_PAT_KEY ShortText
+.. column_create Tags bookmark_index COLUMN_INDEX|WITH_WEIGHT Bookmarks tags
+
+There are no weight vector column specific way except ``WITH_WEIGHT``
+flag. You can create an index like a scalar column.
+
+You can search an element in ``tags`` like full text search syntax.
+
+With :ref:`select-match-columns` and :ref:`select-query`:
+
+.. groonga-command
+.. include:: ../../example/reference/columns/vector/usage_query_weight.log
+.. select Bookmarks --match_columns tags --query groonga --output_columns _key,tags,_score
+
+You can also use weight in :ref:`select-match-columns`. The score is
+``(1 + weight_in_weight_vector) * weight_in_match_columns``:
+
+.. groonga-command
+.. include:: ../../example/reference/columns/vector/usage_query_weight_weight.log
+.. select Bookmarks --match_columns 'tags * 3' --query groonga --output_columns _key,tags,_score
+
+With :ref:`select-filter`:
+
+.. groonga-command
+.. include:: ../../example/reference/columns/vector/usage_filter_weight.log
+.. select Bookmarks --filter 'tags @ "groonga"' --output_columns _key,tags,_score
+
+How to apply just weight
+""""""""""""""""""""""""
+
+You can use weight in weight vector column to just increase search
+score without changing a set of matched records.
+
+Use :ref:`select-adjuster` for the purpose:
+
+.. groonga-command
+.. include:: ../../example/reference/columns/vector/usage_adjuster_weight.log
+.. select Bookmarks \
+..   --filter true \
+..   --adjuster 'tags @ "mysql" * 10 + tags @ "groonga" * 5' \
+..   --output_columns _key,tags,_score
+
+The ``select`` command uses ``--filter true``. So all records are
+matched with score 1. Then it applies ``--adjuster``. The adjuster
+does the following:
+
+  * ``tags @ "mysql" * 10`` increases score by ``(1 + weight) * 10``
+    of records that has ``"mysql"`` tag.
+  * ``tags @ "groonga" * 5`` increases score by ``(1 + weight) * 5``
+    of records that has ``"groonga"`` tag.
+
+For example, record ``"http://mroonga.org/"`` has both ``"mysql"`` tag
+and ``"groonga"`` tag. So its score is increased by ``565`` (``=
+((1 + 50) * 10) + ((1 + 10) * 5) = (51 * 10) + (11 * 5) = 510 + 55``).
+The search score is 1 by ``--filter true`` before applying
+``--adjuster``. So the final search score is ``566`` (``= 1 + 565``)
+of record ``"http://mroonga.org/"``.
+
+.. groonga-command
+.. table_remove Tags
+.. table_remove Bookmarks

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

@@ -70,7 +70,7 @@ Return value
 
 ``cache_limit`` returns the current max number of query cache entries::
 
-  [[HEADER, N_ENTRIES]]
+  [HEADER, N_ENTRIES]
 
 ``HEADER``
 

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

@@ -94,8 +94,7 @@ Return value
 
 ``HEADER``
 
-  The format of HEADER is [0, UNIX_TIME_WHEN_COMMAND_IS_STARTED, ELAPSED_TIME].
-  See :doc:`/reference/command/output_format` about HEADER.
+  See :doc:`/reference/command/output_format` about ``HEADER``.
 
 ``SUCCEEDED``
 

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

@@ -11,16 +11,31 @@
 Summary
 -------
 
-``column_rename`` command renames specified column name of table.
+``column_rename`` command renames a column.
+
+It is a light operation. It just changes a relationship between name
+and the column object. It doesn't copy column values.
+
+It is a dangerous operation. You must stop all operations including
+read operations while you run ``column_rename``. If the following case
+is occurred, Groonga process may be crashed:
+
+  * Starts an operation (like ``select``) that accesses the column to
+    be renamed by the current column name. The current column name is
+    called as ``the old column name`` in the below because the column
+    name is renamed.
+  * Runs ``column_rename``. The ``select`` is still running.
+  * The ``select`` accesses the column to be renamed by the old column
+    name. But the ``select`` can't find the column by the old name
+    because the column has been renamed to the new column name. It may
+    crash the Groonga process.
 
 Syntax
 ------
 
-``column_rename`` command takes two parameters.
-
-The required parameter is ``table`` and ``column_name``::
+``column_rename`` command takes three parameters. All parameters are required::
 
-  column_rename table column
+  column_rename table name new_name
 
 Usage
 -----
@@ -46,20 +61,26 @@ Parameters
 
 This section describes parameters of ``column_rename``.
 
-Required parameter
-^^^^^^^^^^^^^^^^^^
+Required parameters
+^^^^^^^^^^^^^^^^^^^
+
+All parameters are required.
+
+``table``
+"""""""""
+
+It specifies the name of table that has the column to be renamed.
 
-There are required parameters, ``table_name`` and ``column_name``.
+``name``
+""""""""
 
-``table_name``
-""""""""""""""
+It specifies the column name to be renamed.
 
-It specifies the name of table.
+``new_name``
+""""""""""""
 
-``column_name``
-"""""""""""""""
+It specifies the new column name.
 
-It specifies the name of column.
 
 Return value
 ------------
@@ -70,10 +91,9 @@ Return value
 
 ``HEADER``
 
-  The format of HEADER is [0, UNIX_TIME_WHEN_COMMAND_IS_STARTED, ELAPSED_TIME].
-  See :doc:`/reference/command/output_format` about HEADER.
+  See :doc:`/reference/command/output_format` about ``HEADER``.
 
 ``SUCCEEDED_OR_NOT``
 
-  If command succeeded, it returns true, otherwise it returns false on error.
+  It is ``true`` on success, ``false`` otherwise.
 

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

@@ -40,7 +40,7 @@ Here are a schema definition and sample data to show usage.
 .. [
 .. {"_key": 1, "status": "OK"}
 .. {"_key": 2, "status": "NG"}
-.. ] 
+.. ]
 
 Delete the record from Entry table which has "2" as the key.
 
@@ -67,12 +67,12 @@ The country column of Users table associates with Country table.
 .. {"_key": 2, "name": "Mike", country: "United States"}
 .. {"_key": 3, "name": "Takashi", country: "Japan"}
 .. {"_key": 4, "name": "Hanako", country: "Japan"}
-.. ] 
+.. ]
 .. load --table Country
 .. [
 .. {"_key": "United States"}
 .. {"_key": "Japan"}
-.. ] 
+.. ]
 .. delete Country "United States"
 .. select Country
 .. select Users
@@ -108,8 +108,7 @@ Return value
 
 ``HEADER``
 
-  The format of HEADER is [0, UNIX_TIME_WHEN_COMMAND_IS_STARTED, ELAPSED_TIME].
-  See :doc:`/reference/command/output_format` about HEADER.
+  See :doc:`/reference/command/output_format` about ``HEADER``.
 
 ``SUCCEEDED_OR_NOT``
 

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

@@ -132,8 +132,7 @@ Return value
 
 ``HEADER``
 
-  The format of HEADER is [0, UNIX_TIME_WHEN_COMMAND_IS_STARTED, ELAPSED_TIME].
-  See :doc:`/reference/command/output_format` about HEADER.
+  See :doc:`/reference/command/output_format` about ``HEADER``.
 
 ``normalized_text``
 

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

@@ -42,6 +42,7 @@ Syntax
          [query_expansion=null]
          [query_flags=ALLOW_PRAGMA|ALLOW_COLUMN|ALLOW_UPDATE|ALLOW_LEADING_NOT|NONE]
          [query_expander=null]
+         [adjuster=null]
 
 Usage
 -----
@@ -838,6 +839,104 @@ TODO: write in English and add example.
 
   検索結果をクエリキャッシュに残しません。キャッシュして再利用される可能性が低いクエリに対して用います。キャッシュ容量は有限です。有効なキャッシュが多くヒットするために、このパラメータは有効です。
 
+Score related parameters
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+There is a score related parameter, ``adjuster``.
+
+.. _select-adjuster:
+
+
+``adjuster``
+""""""""""""
+
+It specifies one or more score adjust expressions. You need to use
+``adjuster`` with ``query`` or ``filter``. ``adjuster`` doesn't work
+with not searched request.
+
+You can increase score of specific records by ``adjuster``. You can
+use ``adjuster`` to set high score for important records.
+
+For example, you can use ``adjuster`` to increase score of records
+that have ``groonga`` tag.
+
+Here is the syntax::
+
+  --adjuster "SCORE_ADJUST_EXPRESSION1 + SCORE_ADJUST_EXPRESSION2 + ..."
+
+Here is the ``SCORE_ADJUST_EXPRESSION`` syntax::
+
+  COLUMN @ "KEYWORD" * FACTOR
+
+Note the following:
+
+  * ``COLUMN`` must be indexed.
+  * ``"KEYWORD"`` must be a string.
+  * ``FACTOR`` must be a positive integer.
+
+Here is a sample ``adjuster`` usage example that uses just one
+``SCORE_ADJUST_EXPRESSION``:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/adjuster_one.log
+.. select Entries \
+..   --filter true \
+..   --adjuster 'content @ "groonga" * 5' \
+..   --output_columns _key,content,_score
+
+The ``select`` command matches all records. Then it applies
+``adjuster``. The adjuster increases score of records that have
+``"groonga"`` in ``Entries.content`` column by 5. There is only one
+record that has ``"groonga"`` in ``Entries.content`` column.  So the
+record that its key is ``"Groonga"`` has score 6 (``= 1 + 5``).
+
+You can omit ``FACTOR``. If you omit ``FACTOR``, it is treated as 1.
+
+Here is a sample ``adjuster`` usage example that omits ``FACTOR``:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/adjuster_no_factor.log
+.. select Entries \
+..   --filter true \
+..   --adjuster 'content @ "groonga"' \
+..   --output_columns _key,content,_score
+
+The ``adjuster`` in the ``select`` command doesn't have ``FACTOR``. So
+the factor is treated as 1. There is only one record that has
+``"groonga"`` in ``Entries.content`` column. So the record that its
+key is ``"Groonga"`` has score 2 (``= 1 + 1``).
+
+Here is a sample ``adjuster`` usage example that uses multiple
+``SCORE_ADJUST_EXPRESSION``:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/select/adjuster_multiple.log
+.. select Entries \
+..   --filter true \
+..   --adjuster 'content @ "groonga" * 5 + content @ "started" * 3' \
+..   --output_columns _key,content,_score
+
+The ``adjuster`` in the ``select`` command has two
+``SCORE_ADJUST_EXPRESSION`` s. The final increased score is sum of
+scores of these ``SCORE_ADJUST_EXPRESSION`` s. All
+``SCORE_ADJUST_EXPRESSION`` s in the ``select`` command are applied to
+a record that its key is ``"Groonga"``. So the final increased score
+of the record is sum of scores of all ``SCORE_ADJUST_EXPRESSION`` s.
+
+The first ``SCORE_ADJUST_EXPRESSION`` is ``content @ "groonga" * 5``.
+It increases score by 5.
+
+The second ``SCORE_ADJUST_EXPRESSION`` is ``content @ "started" * 3``.
+It increases score by 3.
+
+The final increased score is 9 (``= 1 + 5 + 3``).
+
+A ``SCORE_ADJUST_EXPRESSION`` has a factor for ``"KEYWORD"``. This
+means that increased scores of all records that has ``"KEYWORD"`` are
+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.
+
 返値
 ----
 

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

@@ -187,7 +187,7 @@ Here are available flags:
 +--------------------+------------------------------+
 | ``TABLE_NO_KEY``   | Array table.                 |
 +--------------------+------------------------------+
-| ``TABLE_HASH_HEY`` | Hash table.                  |
+| ``TABLE_HASH_KEY`` | Hash table.                  |
 +--------------------+------------------------------+
 | ``TABLE_PAT_KEY``  | Patricia trie.               |
 +--------------------+------------------------------+

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

@@ -64,8 +64,7 @@ Return value
 
 ``HEADER``
 
-  The format of HEADER is [0, UNIX_TIME_WHEN_COMMAND_IS_STARTED, ELAPSED_TIME].
-  See :doc:`/reference/command/output_format` about HEADER.
+  See :doc:`/reference/command/output_format` about ``HEADER``.
 
 ``SUCCEEDED_OR_NOT``