rroonga 2.1.0-x86-mingw32 → 2.1.1-x86-mingw32

data/vendor/local/share/doc/groonga/source/reference.txt

@@ -11,7 +11,9 @@
    reference/executables
    reference/output
    reference/command
-   reference/type
+   reference/types
+   reference/tables
+   reference/normalizers
    reference/tokenizers
    reference/query_expanders
    reference/pseudo_column

data/vendor/local/share/doc/groonga/source/reference/commands/select.txt

@@ -5,8 +5,8 @@
 .. groonga-command
 .. database: commands_select
 
-select
-======
+``select``
+==========
 
 Summary
 -------

data/vendor/local/share/doc/groonga/source/reference/commands/table_create.txt

@@ -2,115 +2,285 @@
 
 .. highlightlang:: none
 
-table_create
-============
+.. groonga-command
+.. database: commands_table_create
 
-名前
-----
+``table_create``
+================
 
-table_create - テーブルの追加
+Summary
+-------
 
-書式
-----
-::
+``table_create`` creates a new table in the current database. You need
+to create one or more tables to store and search data.
 
- table_create name [flags [key_type [value_type [default_tokenizer]]]]
+Syntax
+------
 
-説明
-----
+``table_create`` has many parameters. The required parameter is only
+``name`` and otehrs are optional::
 
-groonga組込コマンドの一つであるtable_createについて説明します。組込コマンドは、groonga実行ファイルの引数、標準入力、またはソケット経由でgroongaサーバにリクエストを送信することによって実行します。
+  table_create name
+               [flags=TABLE_HASH_KEY]
+               [key_type=null]
+               [value_type=null]
+               [default_tokenizer=null]
+               [normalizer=null]
 
-table_createコマンドは、使用しているデータベースに対してテーブルを追加します。groongaには名前付きテーブルと名前なしテーブル、永続テーブルと一時テーブルがありますが、table_createコマンドでは、名前付きの永続テーブルのみが作成できます。テーブルはレコードの集合であり、全てのレコードは一意なIDを持ちます。IDはレコードを追加した順序に従って自動的に付与されます。
+Usage
+-----
 
-テーブルにカラムを追加する時にはcolumn_createコマンドを使用します。また、テーブルを作成した時点でいくつかの疑似カラムが使用可能になっています。
+``table_create`` command creates a new persistent table. See
+:doc:`/reference/tables` for table details.
 
-引数
-----
+Create data store table
+^^^^^^^^^^^^^^^^^^^^^^^
+
+You can use all table types for data store table. See
+:doc:`/reference/tables` for all table types.
+
+Table type is specified as ``TABLE_${TYPE}`` to ``flags`` parameter.
+
+Here is an example to create ``TABLE_NO_KEY`` table:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_create/data_store_table_no_key.log
+.. table_create Logs TABLE_NO_KEY
+
+The ``table_create`` command creates a table that is named ``Logs``
+and is ``TABLE_NO_KEY`` type.
+
+If your records aren't searched by key, ``TABLE_NO_KEY`` type table is
+suitable. Because ``TABLE_NO_KEY`` doesn't support key but it is fast
+and small table. Storing logs into groonga database is the case.
+
+If your records are searched by key or referenced by one or more
+columns, ``TABLE_NO_KEY`` type isn't suitable. Lexicon for fulltext
+search is the case.
+
+Create lexicon table
+^^^^^^^^^^^^^^^^^^^^
+
+You can use all table types except ``TABLE_NO_KEY`` for lexicon table.
+Lexicon table needs key support but ``TABLE_NO_KEY`` doesn't support
+key.
+
+Here is an example to create ``TABLE_PAT_KEY`` table:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_create/lexicon_table_pat_key.log
+.. table_create Lexicon TABLE_PAT_KEY ShortText --default_tokenizer TokenBigram --normalizer NormalizerAuto
+
+The ``table_create`` command creates the following table:
+
+* The table is named ``Lexicon``.
+* The table is ``TABLE_PAT_KEY`` type table.
+* The table's key is ``ShortText`` type.
+* The table uses ``TokenBigram`` tokenizer to extract tokens from a
+  normalized text.
+* The table uses ``NormalizerAuto`` normalizer to normalize a text.
+
+``TABLE_PAT_KEY`` is suitable table type for lexicon table. Lexicon
+table is used for fulltext search.
+
+In fulltext search, predictive search may be used for fuzzy
+search. Predictive search is supported by ``TABLE_PAT_KEY`` and
+``TABLE_DAT_KEY``.
+
+Lexicon table has many keys because a fulltext target text has many
+tokens. Table that has many keys should consider table size because
+large table requires large memory. Requiring large memory causes disk
+I/O. It blocks fast search. So table size is important for a table
+that has many keys. ``TABLE_PAT_KEY`` is less table size than
+``TABLE_DAT_KEY``.
+
+Because of the above reasons, ``TABLE_PAT_KEY`` is suitable table type
+for lexicon table.
+
+Create tag index table
+^^^^^^^^^^^^^^^^^^^^^^
+
+You can use all table types except ``TABLE_NO_KEY`` for tag index
+table. Tag index table needs key support but ``TABLE_NO_KEY`` doesn't
+support key.
+
+Here is an example to create ``TABLE_HASH_KEY`` table:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_create/tag_index_table_hash_key.log
+.. table_create Tags TABLE_HASH_KEY ShortText
+
+The ``table_create`` command creates a table that is named ``Tags``,
+is ``TABLE_HASH_KEY`` type and has ``ShortText`` type key.
+
+``TABLE_HASH_KEY`` or ``TABLE_DAT_KEY`` are suitable table types for
+tag index table.
+
+If you need only exact match tag search feature, ``TABLE_HASH_KEY`` is
+suitable. It is the common case.
+
+If you also need predictive tag search feature (for example, searching
+``"groonga"`` by ``"gr"`` keyword.), ``TABLE_DAT_KEY`` is suitable.
+``TABLE_DAT_KEY`` is large table size but it is not important because
+the number of tags will not be large.
+
+Create range index table
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can use ``TABLE_PAT_KEY`` and ``TABLE_DAT_KEY`` table types for
+range index table. Range index table needs range search support but
+``TABLE_NO_KEY`` and ``TABLE_HASH_KEY`` don't support it.
+
+Here is an example to create ``TABLE_DAT_KEY`` table:
+
+.. groonga-command
+.. include:: ../../example/reference/commands/table_create/tag_index_table_hash_key.log
+.. table_create Ages TABLE_DAT_KEY UInt32
+
+The ``table_create`` command creates a table that is named ``Ages``,
+is ``TABLE_DAT_KEY`` type and has ``UInt32`` type key.
+
+``TABLE_PAT_KEY`` and ``TABLE_DAT_KEY`` are suitable table types for
+range index table.
+
+If you don't have many indexed items, ``TABLE_DAT_KEY`` is
+suitable. Index for age is the case in the above example. Index for
+age will have only 0-100 items because human doesn't live so long.
+
+If you have many indexed items, ``TABLE_PAT_KEY`` is suitable. Because
+``TABLE_PAT_KEY`` is smaller than ``TABLE_DAT_KEY``.
+
+Parameters
+----------
+
+This section describes all parameters.
 
 ``name``
+^^^^^^^^
+
+It specifies a table name to be created. ``name`` must be specified.
 
-  作成するテーブルの名前を指定します。nameはデータベース内で一意な、未定義の名前でなければなりません。組込型名・組込コマンド名・組込関数名は予約済みであり、テーブル名には 使用できません。また、ピリオド('.'), コロン(':')を含む名前のテーブルは作成できません。
+Here are available characters:
+
+* ``0`` .. ``9`` (digit)
+* ``a`` .. ``z`` (alphabet, lower case)
+* ``A`` .. ``Z`` (alphabet, upper case)
+* ``#`` (hash)
+* ``@`` (at mark)
+* ``-`` (hyphen)
+* ``_`` (underscore) (NOTE: Underscore can't be used as the first
+  character.)
+
+You need to create a name with one or more the above chracters. Note
+that you cannot use ``_`` as the first charcter such as
+``_name``.
 
 ``flags``
+^^^^^^^^^
 
-  作成するテーブルの属性を示す数値か、パイプ('|')で組み合わせたシンボル名を指定します。(デフォルト値は0(="TABLE_HASH_KEY"))
+It specifies a table type and table customize options.
 
-   0, ``TABLE_HASH_KEY``
-     主キー値をハッシュ表で管理するテーブルを作成します。ハッシュ表を使用したテーブルでは、主キー値に完全一致するレコードを非常に高速に検索することができます。
+Here are available flags:
 
-   1, ``TABLE_PAT_KEY``
-     主キー値をパトリシア木で管理するテーブルを作成します。パトリシア木を使用したテーブルでは、主キー値に完全一致するレコードを検索することができるとともに、前方一致するレコード、および最長共通接頭辞となるレコードを高速に検索することができます。また、キー値の昇降順でレコードを取り出したり、キー値の範囲での検索を行うことができます。また、flagsの値に64を加えることによって、後方一致検索も可能となります。
++--------------------+------------------------------+
+|      flags         | description                  |
++--------------------+------------------------------+
+| ``TABLE_NO_KEY``   | Array table.                 |
++--------------------+------------------------------+
+| ``TABLE_HASH_HEY`` | Hash table.                  |
++--------------------+------------------------------+
+| ``TABLE_PAT_KEY``  | Patricia trie.               |
++--------------------+------------------------------+
+| ``TABLE_DAT_KEY``  | Double Array trie.           |
++--------------------+------------------------------+
+| ``KEY_WITH_SIS``   | Enable Semi Infinite String. |
+|                    | Require ``TABLE_PAT_KEY``.   |
++--------------------+------------------------------+
 
-   2, ``TABLE_DAT_KEY``
-     主キー値をダブル配列で管理するテーブルを作成します。ダブル配列を使用したテーブルでは、主キー値に完全一致するレコードを高速に検索することができるとともに、前方一致するレコード、および最長共通接頭辞となるレコードを検索することができます。また、キー値の昇降順でレコードを取り出したり、キー値の範囲での検索を行うことができます。
+.. note::
+   Since groonga 2.1.0 ``KEY_NORMALIZE`` flag is deprecated. Use
+   ``normalizer`` option with ``NormalizerAuto`` instead.
 
-   3, ``TABLE_NO_KEY``
-     主キーを持たないテーブルを作成します。各レコードはIDのみによって特定することができます。
+You must specify one of ``TABLE_${TYPE}`` flags. You cannot specify two
+or more ``TABLE_${TYPE}`` flags. For example,
+``TABLE_NO_KEY|TABLE_HASH_KEY`` is invalid.
 
-   4, ``TABLE_VIEW``
-     複数のテーブルをまとめて操作するための仮想的なテーブル(view)を作成します。
+You can combine flags with ``|`` (vertical bar) such as
+``TABLE_PAT_KEY|KEY_WITH_SIS``.
 
-   64, ``KEY_WITH_SIS``
-     語彙表となるパトリシア木型のテーブルにおいて、後方一致検索を可能とします。
+See :doc:`/reference/tables` for difference between table types.
 
-   128, ``KEY_NORMALIZE``
-     ハッシュ表型か、パトリシア木型のテーブルにおいて、主キー値を正規化した上で登録します。この値が指定されたテーブルではたとえば、主キー値'abc'と'ABC' は同一のレコードに対応するものとみなされます。
+The default flags are ``TABLE_HASH_KEY``.
 
 ``key_type``
+^^^^^^^^^^^^
+
+It specifies key type.
 
-  主キー値の型を指定します。主キー値を持つテーブルに限り有効です。型にはgroongaの組込型か、同一データベースに定義済みのユーザ定義型、定義済みのテーブルを指定することができます。
+If you specify ``TABLE_HASH_KEY``, ``TABLE_PAT_KEY`` or
+``TABLE_DAT_KEY`` as ``flags`` parameter, you need to specify
+``key_type`` option.
+
+See :doc:`/reference/types` for all types.
+
+The default value is none.
 
 ``value_type``
+^^^^^^^^^^^^^^
 
-  値の型を指定します。tableの値には固定長の型のみが指定できます。(可変長の値が必要な場合は別途カラムを作成します) 型にはgroongaの組込型か、同一データベースに定義済みのユーザ定義型、またはテーブルを指定することができます。(デフォルトはvalueなし)
+It specifies value type.
 
-``default_tokenizer``
+You can use value when you specify ``TABLE_NO_KEY``,
+``TABLE_HASH_KEY`` or ``TABLE_PAT_KEY`` as ``flags`` parameter. Value
+type must be a fixed size type. For example, ``UInt32`` can be used
+but ``ShortText`` cannot be used. Use columns instead of value.
 
-  作成するテーブルを語彙表として使用する場合、文字列を分割するトークナイザを指定します。
+The default value is none.
 
-  組込のトークナイザとして、以下が準備されています。
+``default_tokenizer``
+^^^^^^^^^^^^^^^^^^^^^
 
-  ``TokenDelimit``
-    空白で区切られた文字列をトークンとする
+It specifies the default tokenizer that is used on searching and data
+loading.
 
-  ``TokenUnigram``
-    unigram(1文字を1トークンとする)
+You cannot use ``default_tokenizer`` with ``TABLE_NO_KEY`` because
+``TABLE_NO_KEY`` cannot be used for index.
 
-  ``TokenBigram``
-    bigram(2文字の文字列要素をトークンとする)
+You must specify ``default_tokenizer`` for a table that is used for
+fulltext search index.
 
-  ``TokenTrigram``
-    trigram(3文字の文字列要素をトークンとする)
+See :doc:`/reference/tokenizers` for all tokenizers
 
-  ``TokenMecab``
-    形態素解析器mecabで解析した形態素をトークンとする。(mecabを組み込んだ場合のみ有効)
+The default value is none.
 
-  トークナイザが指定されなかった場合は、対象の文字列を分割せずに語彙表に登録します。
+``normalizer``
+^^^^^^^^^^^^^^
 
-返値
-----
+It specifies a normalizer that is used to normalize key.
 
-json形式
-^^^^^^^^
+You cannot use ``normalizer`` with ``TABLE_NO_KEY`` because
+``TABLE_NO_KEY`` doesn't support key.
 
-::
+See :doc:`/reference/normalizers` for all normalizsers.
 
- [成功かどうかのフラグ]
+The default value is none.
 
- ``成功かどうかのフラグ``
+Return value
+------------
 
-   エラーが生じなかった場合にはtrue、エラーが生じた場合にはfalseを返す。
+``table_create`` returns ``true`` as body on success such as::
 
-例
---
+  [HEADER, true]
 
-ShortText型の主キーを持つハッシュ表型のテーブル、Entryを作成します。::
+If ``table_create`` fails, error details are in ``HEADER``.
 
-  table_create Entry --key_type ShortText
-  [true]
+See :doc:`/reference/command/output_format` for ``HEADER``.
 
-ShortText型の主キーを持つパトリシア木型のテーブル、Termを作成します。主キー値は正規化して管理します。また、このテーブルを語彙表とする転置索引を作成する場合には、バイグラムの索引を作成します。::
+See also
+--------
 
-  table_create Term --flags TABLE_PAT_KEY|KEY_NORMALIZE --key_type ShortText --default_tokenizer TokenBigram
-  [true]
+* :doc:`/reference/tables`
+* :doc:`/reference/commands/column_create`
+* :doc:`/reference/tokenizers`
+* :doc:`/reference/normalizers`
+* :doc:`/reference/command/output_format`

data/vendor/local/share/doc/groonga/source/reference/executables/grntest.txt

@@ -134,7 +134,7 @@ grntest命令
 コマンドファイル
 ^^^^^^^^^^^^^^^^
 
-コマンドファイルは、groonga組み込みコマンドを1行に1つずつ記述したテキストファイルです。拡張子に制限はありません。groonga組み込みコマンドに関しては :doc:`/reference/commands` を参照してください。
+コマンドファイルは、groonga組み込みコマンドを1行に1つずつ記述したテキストファイルです。拡張子に制限はありません。groonga組み込みコマンドに関しては :doc:`/reference/command` を参照してください。
 
 サンプル
 ^^^^^^^^

data/vendor/local/share/doc/groonga/source/reference/executables/groonga-server-http.txt

@@ -48,7 +48,7 @@ GETメソッドのみが使用可能です。
 
 output_typeにはjson, tsv, xmlが指定可能です。
 
-command_versionはコマンドの仕様の互換性を指定します。詳細は :doc:`/reference/command_version` を参照してください。
+command_versionはコマンドの仕様の互換性を指定します。詳細は :doc:`/reference/command/command_version` を参照してください。
 
 返値
 ----

data/vendor/local/share/doc/groonga/source/reference/executables/groonga.txt

@@ -138,6 +138,8 @@ groongaのデータベースは、groongaコマンドかCライブラリイン
 
    スタンドアロンおよびクライアントモードの場合は、実行するコマンドとその引数をコマンドライン引数に指定できます。コマンドライン引数にcommandを与えなかった場合は、標準入力から一行ずつEOFに達するまでコマンド文字列を読み取り、順次実行します。
 
+.. _command-list-with-continuous-line:
+
 コマンド
 --------
 
@@ -154,6 +156,13 @@ groongaコマンドを通してデータベースを操作する命令をコマ
 
 標準入力からコマンド文字列を与える場合は、コマンド名と引数名と値は、空白( )で区切ります。空白や、記号「"'()\」のうちいずれかを含む値を指定したい場合は、シングルクォート(')かダブルクォート(")で値を囲みます。値として指定する文字列の中では、改行文字は'\n'に置き換えて指定します。また、引用符に使用した文字を値の中で指定する場合には、その文字の前にバックスラッシュ('\') を指定します。バックスラッシュ文字自身を値として指定する場合には、その前にバックスラッシュを指定します。
 
+You can write command list with continuous line which is represented by '\\' character.::
+
+  table_create --name Terms \
+               --flags TABLE_PAT_KEY \
+               --key_type ShortText \
+               --default_tokenizer TokenBigram
+
 組み込みコマンド
 ----------------
 

data/vendor/local/share/doc/groonga/source/reference/functions/geo_distance.txt

@@ -158,7 +158,7 @@ you want to calculate the value of distance between two points.
 
 You can specify the value of GeoPoint type. [#]_
 
-See :doc:`/reference/type` about GeoPoint.
+See :doc:`/reference/types` about GeoPoint.
 
 ``point2``
 """"""""""
@@ -169,7 +169,7 @@ you want to calculate the value of distance between two points.
 You can specify the value of GeoPoint type or 
 the string indicating the coordinate.
 
-See :doc:`/reference/type` about GeoPoint and the coordinate.
+See :doc:`/reference/types` about GeoPoint and the coordinate.
 
 Optional parameter
 ^^^^^^^^^^^^^^^^^^

data/vendor/local/share/doc/groonga/source/reference/grn_expr/script_syntax.txt

@@ -221,7 +221,7 @@ Its syntax is ``name(arugment1, argument2, ...)``.
 ``name(argument1, argument2, ...)`` calls a function that is named
 ``name`` with arguments ``argument1``, ``argument2`` and ``...``.
 
-See :doc:`/reference/functions/` for available functin list.
+See :doc:`/reference/function` for available functin list.
 
 Here is a simple exmaple.
 

data/vendor/local/share/doc/groonga/source/reference/normalizers.txt

@@ -0,0 +1,122 @@
+.. -*- rst -*-
+
+.. highlightlang:: none
+
+.. groonga-command
+.. database: normalisers
+
+Normalizers
+===========
+
+Summary
+-------
+
+Groonga has normalizer module. It is used when tokenizing text and
+storing table key. For example, ``A`` and ``a`` are processed as the
+same character after normalization.
+
+Normalizer module can be added as a plugin. You can customize text
+normalization by registering your normalizer plugins to groonga.
+
+A normalizer module is attached to a table. A table can have zero or
+one normalizer module. You can attach a normalizer module to a table
+by :ref:`table-create-normalizer` option in
+:doc:`/reference/commands/table_create`.
+
+Here is an example ``table_create`` that uses ``NormalizerAuto``
+normalizer module:
+
+.. groonga-command
+.. include:: ../example/reference/normalizers/example-table-create.log
+.. table_create Dictionary TABLE_HASH_KEY ShortText --normalizer NormalizerAuto
+
+.. note::
+
+   Groonga 2.0.9 or earlier doesn't have ``--normalizer`` option in
+   ``table_create``. ``KEY_NORMALIZE`` flag was used instead.
+
+   You can open an old database by groonga 2.1.0 or later. An old
+   database means that the database is created by groonga 2.0.9 or
+   earlier. But you cannot open the opened old database by groonga
+   2.0.9 or earlier. Once you open the old database by groonga 2.1.0
+   or later, ``KEY_NORMALIZE`` flag information in the old database is
+   converted to normalizer information. So groogna 2.0.9 or earlier
+   cannot find ``KEY_NORMALIZE`` flag information in the opened old
+   database.
+
+Keys of a table that has a normalizer module are normalized:
+
+.. groonga-command
+.. include:: ../example/reference/normalizers/example-load.log
+.. load --table Dictionary
+.. [
+.. {"_key": "Apple"},
+.. {"_key": "black"},
+.. {"_key": "COLOR"}
+.. ]
+.. select Dictionary
+
+``NormalizerAuto`` normalizer normalizes a text as a downcased text.
+For example, ``"Apple"`` is normalized to ``"apple"``, ``"black"`` is
+normalized to ``"blank"`` and ``"COLOR"`` is normalized to
+``"color"``.
+
+If a table is a lexicon for fulltext search, tokenized tokens are
+normalized. Because tokens are stored as table keys. Table keys are
+normalized as described above.
+
+Built-in normalizers
+--------------------
+
+Here is a list of built-in-normalizers:
+
+  * ``NormalizerAuto``
+  * ``NormalizerNFKC51``
+
+``NormalizerAuto``
+^^^^^^^^^^^^^^^^^^
+
+Normally you should use ``NormalizerAuto``
+normalizer. ``NormalizerAuto`` was the normalizer for groonga 2.0.9 or
+earlier. ``KEY_NORMALIZE`` flag in ``table_create`` on groonga 2.0.9
+or earlier equals to ``--normalizer NormalizerAuto`` option in
+``table`` on groonga 2.1.0 or later.
+
+``NormalizerAuto`` supports all encoding. It uses Unicode NFKC
+(Normalization Form Compatibility Composition) for UTF-8 encoding
+text. It uses encoding specific original normalization for other
+encodings. The results of those original normalization are similar to
+NFKC.
+
+For example, half-width katakana (such as U+FF76 HALFWIDTH KATAKANA
+LETTER KA) + half-width katakana voiced sound mark (U+FF9E HALFWIDTH
+KATAKANA VOICED SOUND MARK) is normalized to full-width katakana with
+voiced sound mark (U+30AC KATAKANA LETTER GA). The former is two
+chracters but the latter is one character.
+
+Here is an example that uses ``NormalizerAuto`` normalizer:
+
+.. groonga-command
+.. include:: ../example/reference/normalizers/normalizer-auto.log
+.. table_create NormalLexicon TABLE_HASH_KEY ShortText --normalizer NormalizerAuto
+
+``NormalizerNFKC51``
+^^^^^^^^^^^^^^^^^^^^
+
+``NormalizerNFKC51`` normalizes texts by Unicode NFKC (Normalization
+Form Compatibility Composition) for Unicode version 5.1. It supports
+only UTF-8 encoding.
+
+Normally you don't need to use ``NormalizerNFKC51`` explicitly. You can
+use ``NormalizerAuto`` instead.
+
+Here is an example that uses ``NormalizerNFKC51`` normalizer:
+
+.. groonga-command
+.. include:: ../example/reference/normalizers/normalizer-nfkc51.log
+.. table_create NFKC51Lexicon TABLE_HASH_KEY ShortText --normalizer NormalizerNFKC51
+
+See also
+--------
+
+* :doc:`/reference/commands/table_create`