rroonga 0.9.5-x86-mingw32 → 1.0.1-x86-mingw32

data/vendor/local/share/groonga/doc/ja/html/_sources/tutorial.txt

@@ -0,0 +1,10 @@
+.. highlightlang:: none
+
+チュートリアル
+==============
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   tutorial/*

data/vendor/local/share/groonga/doc/ja/html/_sources/tutorial/tutorial01.txt

@@ -0,0 +1,293 @@
+.. highlightlang:: none
+
+.. groonga-command
+.. table_remove Site
+.. table_remove Terms
+
+基本的な操作
+============
+
+groongaは、Cのライブラリとして使用する方法と、groonga実行ファイルを通して使用する方法があります。
+
+本チュートリアルでは、groonga実行ファイルを使用する方法について説明します。
+
+groonga実行ファイルを使って、DBの作成・操作・サーバの起動・サーバへの接続などの操作が行えます。
+
+DBの作成
+--------
+
+以下のようなコマンドを実行すると、データベースを新規に作成することができます。
+
+書式 ::
+
+  groonga -n データベースパス名
+
+-nオプションは、データベースを作ることを示します。
+
+データベースパス名には、新しく作成するデータベースのフルパス名を指定します。
+
+上記コマンドでデータベースを作成すると、そのまま対話モードと呼ばれるコマンドを受け付けるモードになります。Ctrlキーを押しながらdキーを押すと、対話モードから抜けることができます。
+
+実行例::
+
+  % groonga -n /tmp/tutorial.db
+  > ctrl-d
+  %
+
+DBの操作
+--------
+
+書式 ::
+
+  groonga DBパス名 [コマンド]
+
+既存のデータベースのフルパス名をDBパス名に指定します。
+コマンドを指定すると、実行結果を返します。
+
+コマンドを指定しない場合には、対話モードに入ります。
+対話モードでは、標準入力からコマンドを読み込み、順次実行します。
+本チュートリアルでは、対話モードを主に使用します。
+
+たとえば、statusというコマンドを実行してみましょう。statusコマンドは、groongaの実行状態を返すコマンドです。
+
+.. groonga-command
+.. include:: ../example/tutorial01-1.log
+.. .. % groonga /tmp/tutorial.db
+.. status
+
+以上のように、コマンドの実行結果は基本的にjson形式で返却されます。jsonの配列の0番目の要素に、エラーコードや実行時間などの情報が入ります。jsonの配列の1番目の様子に、コマンドの実行結果が入ります。
+
+コマンド
+--------
+
+groonga実行ファイルやgroongaサーバを介して様々なコマンドを実行して、DBを操作することができます。
+コマンドは以下の書式のうちいずれかで与えることができます。 ::
+
+ 書式1: コマンド名 引数1 引数2 ..
+
+ 書式2: コマンド名 --引数名1 値1 --引数名2 値2 ..
+
+書式1と2は混ぜて使うことができます。
+
+書式2において、空白や、記号「"'()\」のうちいずれかを含む値を指定したい場合は、シングルクォート(')かダブルクォート(")で値を囲みます。
+
+詳しくは、 :doc:`../execfile` のコマンドの項を参考にしてください。
+
+主なコマンド
+------------
+
+ :doc:`../commands/status`
+  groongaプロセスの状態を表示します。
+ :doc:`../commands/table_list`
+  DBに定義されているテーブルのリストを表示します。
+ :doc:`../commands/column_list`
+  テーブルに定義されているカラムのリストを表示します。
+ :doc:`../commands/table_create`
+  DBにテーブルを追加します。
+ :doc:`../commands/column_create`
+  テーブルにカラムを追加します。
+ :doc:`../commands/select`
+  テーブルに含まれるレコードを検索して表示します。
+ :doc:`../commands/load`
+  テーブルにレコードを挿入します。
+
+テーブルの作成
+--------------
+
+:doc:`../commands/table_create` コマンドを使用してテーブルを作成します。
+
+groongaでは、多くの場合テーブルを作成する際に主キーが必要となります。また、主キーには型と、その格納方法を指定する必要があります。
+
+型については、のちのチュートリアルで触れます。データの種類をあらわしているもの、とイメージしてください。
+
+主キーの格納方法によって、主キーでの検索速度や、前方一致検索の可否が決まります。これも、のちのチュートリアルで触れます。
+
+ここでは、ShortText型の主キー値を持ち、主キーの格納方法はHASHである、'Site'という名前のテーブルを作成します。
+
+.. groonga-command
+.. include:: ../example/tutorial01-2.log
+.. table_create --name Site --flags TABLE_HASH_KEY --key_type ShortText
+
+検索
+----
+
+:doc:`../commands/select` コマンドを用いて、テーブルの中身を表示することができます。
+
+.. groonga-command
+.. include:: ../example/tutorial01-3.log
+.. select --table Site
+
+selectにテーブル名を指定すると、指定したテーブルの中身を10件表示します。[0]は検索されたレコードの件数、["_id","Uint32"]は値がUInt32型である"_id'という名前のカラム、["_key","ShortText"]は値がShortText型である'_key'という名前のカラムを示しています。
+
+table_createコマンドで作成したテーブルには、最初から'_id'/'_key'という２つのカラムがあります。'_id'はgroongaが自動的に付与するID番号が格納されるカラムです。'_key'は主キーが格納されるカラムです。これらのカラム名を変更することはできません。
+
+カラムの作成
+------------
+
+:doc:`../commands/column_create` コマンドを用いて、カラムを作成することができます。
+
+ShortText型の値を持つ、'comment'という名前のカラムを'Site'テーブルに追加しましょう。
+
+.. groonga-command
+.. include:: ../example/tutorial01-4.log
+.. column_create --table Site --name title --flags COLUMN_SCALAR --type ShortText
+.. select --table Site
+
+COLUMN_SCALARについては、通常のカラムであることを示しています。
+
+全文検索用の語彙テーブルの作成
+------------------------------
+
+このチュートリアルでは、groongaに登録したデータを用いた全文検索を行います。
+
+全文検索を行う場合は、まず語彙テーブルを作成する必要があります。
+語彙表テーブルとは、文書の中にある単語が主キーとなるテーブルです。
+ここでは、ShortText型の主キー値を持つ、'Terms'という名前のテーブルを作成しました。
+
+.. groonga-command
+.. include:: ../example/tutorial01-5.log
+.. table_create --name Terms --flags TABLE_PAT_KEY|KEY_NORMALIZE --key_type ShortText --default_tokenizer TokenBigram
+
+この実行例には、多くのパラメータが指定されています。本チュートリアルでは、これらをすべて理解する必要はありません。以下に簡単な説明を記しますが、読み飛ばしてもらってかまいません。
+
+実行例にある、TABLE_PAT_KEY|KEY_NORMALIZEという値は、主キー値をパトリシア木に格納し、各語彙を正規化して登録することを示しています。
+
+実行例にある、TokenBigramという値は、 語彙表として使用するテーブルは、対象の文書をトークナイズする方式を、default_tokenizerパラメータで与えます。この例ではTokenBigramを指定しています。よって、一般的にN-gramと呼ばれるようなインデックス方式を選択しています。
+
+全文検索用のインデックスカラムの作成
+------------------------------------
+
+Siteテーブルのtitleカラムを全文検索の対象としたいとしましょう。その場合には、語彙テーブルにインデックス型のカラムを作成します。
+
+.. groonga-command
+.. include:: ../example/tutorial01-6.log
+.. column_create --table Terms --name blog_title --flags COLUMN_INDEX|WITH_POSITION --type Site --source title
+
+Siteテーブルのtitleカラムを検索対象とする、'blog_title'という名前のインデックス型カラムをTermsテーブルに作成しました。インデックス対象となるテーブルをtypeに、インデックス対象となるカラムをsourceに指定します。
+
+実行例のflagsのCOLUMN_INDEX|WITH_POSITIONという値は、語彙の位置情報を格納するインデックス型のカラムであることを示しています。通常の全文検索インデックスでは、COLUMN_INDEX|WITH_POSITIONを指定してください。語彙の位置情報を格納する意味については、本チュートリアルでは触れません。
+
+データのロード
+--------------
+
+:doc:`../commands/load` コマンドを使用します。loadコマンドでは、jsonで受け取ったデータをテーブルに格納します。
+
+.. groonga-command
+.. include:: ../example/tutorial01-7.log
+.. load --table Site
+.. [
+.. {"_key":"http://example.org/","title":"This is test record 1!"},
+.. {"_key":"http://example.net/","title":"test record 2."},
+.. {"_key":"http://example.com/","title":"test test record three."},
+.. {"_key":"http://example.net/afr","title":"test record four."},
+.. {"_key":"http://example.org/aba","title":"test test test record five."},
+.. {"_key":"http://example.com/rab","title":"test test test test record six."},
+.. {"_key":"http://example.net/atv","title":"test test test record seven."},
+.. {"_key":"http://example.org/gat","title":"test test record eight."},
+.. {"_key":"http://example.com/vdw","title":"test test record nine."},
+.. ]
+
+selectコマンドで、データが入っていることを確認しましょう。
+
+.. groonga-command
+.. include:: ../example/tutorial01-8.log
+.. select --table Site
+
+データの検索
+------------
+
+groongaでは、'_id'カラムと'_key'カラムの値はテーブル中で一意です。よって、それを用いて検索してみましょう。
+
+selectコマンドにおいて、queryパラメータを用いるとデータの検索を行うことができます。
+
+.. groonga-command
+.. include:: ../example/tutorial01-9.log
+.. select --table Site --query _id:1
+
+queryパラメータに与えた「_id:1」というのは、'_id'という名前のカラムに'1'という値が入っているレコードを検索する、という意味です。
+
+_keyでも検索してみましょう。
+
+.. groonga-command
+.. include:: ../example/tutorial01-10.log
+.. select --table Site --query "_key:\"http://example.org/\""
+
+queryパラメータに与えた「_key:\"http://example.org/\"」というのは、'_key'という名前のカラムに'"http://example.org/"'という値が入っているレコードを検索する、という意味です。
+
+全文検索
+--------
+
+queryパラメータでは、インデックスを用いた全文検索を行うこともできます。
+
+.. groonga-command
+.. include:: ../example/tutorial01-11.log
+.. select --table Site --query title:@this
+
+titleカラムに対して、'this'という文字列で全文検索を行った結果を返します。
+
+queryパラメータに与えた「title:@this」というのが、'title'という名前のカラムに'this'という文字列が含まれているレコードを検索する、という意味です。
+
+selectコマンドには、match_columnsというパラメータが存在します。これを指定すると、query内にカラム名を指定しない条件があった場合、match_columnsで指定されたカラムに対しての検索であることを示します。[1]_
+
+match_columnsパラメータに'title'、queryパラメータに'this'という文字列を指定すると、上記のクエリと同じ結果を得ることができます。
+
+.. groonga-command
+.. include:: ../example/tutorial01-12.log
+.. select --table Site --match_columns title --query this
+
+出力カラムの指定
+----------------
+
+selectコマンドにおいて、output_columnsパラメータを用いることで、検索結果で表示するカラムを指定することが出来ます。
+
+複数のカラムを指定する場合は、カンマ(,)区切りで指定します。
+
+.. groonga-command
+.. include:: ../example/tutorial01-13.log
+.. select --table Site --output_columns _key,title,_score --query title:@test
+
+groongaの検索結果には、「_score」という名前のカラムが追加されています。このカラムは、全文検索の条件が合致する文書ほど高い数値が入ります。
+
+
+表示範囲指定
+------------
+
+selectコマンドにおいて、offset,limitパラメータを用いることで、検索結果から指定された範囲のみを表示することが出来ます。大量の検索結果をページで分けて、1ページ分のみを表示したい場合に有効です。
+
+offsetパラメータには、検索結果を返す始点を指定します。1件目から結果を返す場合には、0を指定します。
+
+limitパラメータには、検索結果を何件表示するのかを指定します。
+
+.. groonga-command
+.. include:: ../example/tutorial01-14.log
+.. select --table Site --offset 0 --limit 3
+.. select --table Site --offset 3 --limit 3
+.. select --table Site --offset 7 --limit 3
+
+並び替え
+--------
+
+selectコマンドにおいて、sortbyパラメータを用いることで、検索結果を並び替えることが出来ます。
+
+sortbyパラメータにカラム名を指定することで、そのカラムの値で昇順にソートします。また、カラム名の前にハイフン（-）を付けることで、降順にソートすることも出来ます。
+
+.. groonga-command
+.. include:: ../example/tutorial01-15.log
+.. select --table Site --sortby -_id
+
+出力カラムの指定で紹介した「_score」カラムは、ソートの条件としても使うことができます。
+
+.. groonga-command
+.. include:: ../example/tutorial01-16.log
+.. select --table Site --query title:@test --output_columns _id,_score,title --sortby _score
+
+ソートするカラム名を複数指定したい場合は、カンマ(,)区切りで指定します。複数のカラムを指定した場合、最初のカラムで同一の値のレコードがあった場合に、次のカラムの値でソートさせることができます。
+
+.. groonga-command
+.. include:: ../example/tutorial01-17.log
+.. select --table Site --query title:@test --output_columns _id,_score,title --sortby _score,_id
+
+.. rubric:: 脚注
+
+.. [1] 現在のバージョンでは、全文検索インデックスが存在する場合にのみ、match_columnsパラメータを利用することをができます。通常のカラムでの絞り込みには利用できません。
+

data/vendor/local/share/groonga/doc/ja/html/_sources/tutorial/tutorial02.txt

@@ -0,0 +1,100 @@
+.. highlightlang:: none
+
+.. groonga-include : tutorial01.txt
+
+ネットワークを通じた利用
+========================
+
+groongaはネットワークを通じて利用することができます。groonga独自プロトコルもしくはHTTPのどちらかを選択してgroongaを起動することにより、groongaはネットワーク接続を待ち受けます。
+
+groonga専用プロトコルによる通信
+-------------------------------
+
+groongaデーモンの起動
+^^^^^^^^^^^^^^^^^^^^^
+
+書式 ::
+
+  groonga [-p ポート番号] -d DBパス名
+
+既存のデータベースのフルパス名をDBパス名に指定します。
+groongaがデーモンモードで起動し、指定したポート番号でgroongaの専用プロトコルを用いた通信をすることができます。
+(ポート番号を省略した場合は10041が使用されます)
+
+実行例::
+
+  % groonga -d /var/tmp/hoge.db
+  12345
+  %
+
+デーモンモードで起動後、プロセス番号が表示されます。
+
+groongaサーバへの接続
+^^^^^^^^^^^^^^^^^^^^^
+
+書式 ::
+
+  groonga [-p ポート番号] -c [対象ホスト名またはIPアドレス]
+
+対象ホストで動作しているgroongaサーバに接続します。
+
+対象ホスト名を省略した場合はlocalhostに対して接続し、対象ポート番号を省略した場合は10041ポートに対して接続します。
+
+接続に成功すると対話モードに入り、標準入力からコマンドを読み込んで順次実行します。
+
+.. groonga-command
+.. include:: ../example/tutorial02-1.log
+.. .. % groonga -c
+.. status
+.. .. > ctrl-d
+.. .. %
+
+groongaデーモンの終了
+^^^^^^^^^^^^^^^^^^^^^
+
+groongaデーモンにshutdownコマンドを発行することにより、終了させることができます。
+
+.. groonga-command
+.. include:: ../example/tutorial02-2.log
+.. .. % groonga -c
+.. .. > shutdown
+.. .. %
+
+HTTPによる通信
+--------------
+
+groongaをHTTP経由で利用したい場合には、HTTPプロトコルモードで起動します。
+
+書式 ::
+
+  groonga [-p ポート番号] -d --protocol http DBパス名
+
+protocolオプションで、groongaが受け付けるプロトコルを指定できます。httpを指定すると、groongaはHTTPプロトコルでの通信を受け付けます。
+
+HTML管理ツール
+^^^^^^^^^^^^^^
+
+コマンド実行後、http://[IPアドレスまたはホスト名]:[ポート番号]/ というURLにブラウザからアクセスすると、HTML管理ツールが表示されます。ブラウザは、JavaScriptの実行が有効になっている必要があります。
+
+HTTPでのコマンド実行
+^^^^^^^^^^^^^^^^^^^^
+
+groongaがHTTPプロトコルモードで起動されているとき、「/d/コマンド名」というURLにアクセスすると、コマンドを実行することが出来ます。
+
+コマンドのオプションは、HTTPのGETパラメータで渡します。つまり、「?オプション=値&オプション=値 …」という書式になります。
+
+.. groonga-command
+.. include:: ../example/tutorial02-3.log
+.. .. http://[IPまたはホスト名]:[ポート番号]/d/status
+.. .. 実行される処理：
+.. status
+.. .. 
+.. .. http://[IPまたはホスト名]:[ポート番号]/d/select?table=Site&query=title:@this
+.. .. 実行される処理：
+.. select --table Site --query title:@this
+
+
+セキュリティ
+------------
+
+groongaのネットワークサービスにはは認証機能がありません。誰でもデータベースの内容を閲覧・修正することができます。iptablesなどを用いて、アクセス元IPアドレスを制限することを薦めます。

data/vendor/local/share/groonga/doc/ja/html/_sources/tutorial/tutorial03.txt

@@ -0,0 +1,72 @@
+.. highlightlang:: none
+
+.. groonga-include : tutorial01.txt
+
+さまざまな種類をもったデータの保存
+==================================
+
+groongaでは、さまざまなデータを格納させることが出来ます。
+
+データ型
+--------
+
+groongaでは、数値（整数・小数）や文字列や時刻や経緯度などの情報を格納することができます。
+
+ここでは、Int32型のカラムに整数を格納、Float型のカラムに浮動小数点の小数を、ShortText型のカラムに文字列を、Time型のカラムに時間を格納する例を示します。経緯度の格納については、のちのチュートリアルで触れます。
+
+その他のデータ型の一覧は、 :doc:`../type` を参照してください。
+
+.. groonga-command
+.. table_remove Type
+.. include:: ../example/tutorial03-1.log
+.. table_create --name Type --flags TABLE_HASH_KEY --key_type ShortText
+.. column_create --table Type --name number --type Int32
+.. column_create --table Type --name float --type Float
+.. column_create --table Type --name string --type ShortText
+.. column_create --table Type --name time --type Time
+.. load --table Type
+.. [{"_key":"sample","number":12345,"float":42.195,"string":"GROONGA","time":1234567890.12}]
+.. select --table Type
+
+
+テーブル型
+----------
+
+table_createで作成したテーブルを、カラムの型として使うことが出来ます。
+
+また、output_columnsにおいて「.」を区切りとして、参照先のテーブルに存在するカラムを指定すると、指定したカラムの値を表示することができます。
+
+ここでは、先のチュートリアルで作成したSiteテーブルに手を加え、どのサイトをリンクしているのかを保存してみましょう。
+
+他のテーブルを参照するカラムにデータを入力する場合には、参照先のテーブルの_keyカラムの値を代入する必要があります。
+
+.. groonga-command
+.. include:: ../example/tutorial03-2.log
+.. column_create --table Site --name link --type Site
+.. load --table Site
+.. [{"_key":"http://example.org/","link":"http://example.net/"}]
+.. select --table Site --output_columns _key,title,link._key,link.title --query title:@this
+
+このように、linkカラムに他のサイトへの参照を保存することができました。また、参照先の_keyとtitleカラムの内容を表示することができました。
+
+ベクターカラム
+--------------
+
+column_createコマンドでカラムを作成するとき、--flagsオプションでCOLUMN_VECTORフラグを指定すると、複数の値を配列で格納できるカラムが作成されます。
+
+テーブル型で配列を格納するカラムは、1対多の参照関係を表すのに有効です。
+
+テーブル型のチュートリアルでは、Siteテーブルに手を加え、どのサイトをリンクしているのかを保存しました。しかし、通常は1つのサイトから多くのサイトにリンクが張られています。複数のリンク情報を格納するために、複数の参照関係を保存するカラムを作成してみましょう。
+
+他のテーブルを参照するベクターカラムにデータを入力する場合には、参照先のテーブルの_keyカラムの値の「配列」を代入する必要があります。
+
+.. FIXME: _idの配列ではダメなのかどうか。検証する。
+
+.. groonga-command
+.. include:: ../example/tutorial03-3.log
+.. column_create --table Site --name links --flags COLUMN_VECTOR --type Site
+.. load --table Site
+.. [{"_key":"http://example.org/","links":["http://example.net/","http://example.org/","http://example.com/"]}]
+.. select --table Site --output_columns _key,title,links._key,links.title --query title:@this
+
+このように、複数の参照関係が保存できました。また、output_columnsによって、複数の参照先のカラム値も表示させることができました。