2.1. インストールと基本的な操作

本チュートリアルでは、Webブックマークサービスのデータベースを作成し、groongaの利用方法を紹介します。

2.1.1. インストール方法

groongaは、ほとんど他のライブラリに依存せずに動作します。

  • MeCabのインストール

本チュートリアルでは使用しませんが、 将来的に形態素単位でトークナイズした全文検索索引を使用したい場合は、 事前にMeCab (http://mecab.sourceforge.net/)をインストールしてください。

  • groongaのインストール

http://groonga.org/download/よりtar.gzファイルを取得し、 インストール先の環境にファイルを展開して、

./configure --prefix=/usr && make && sudo make install

のように実行することでインストールできます。

prefixは、インストール先を指定するパラメータです。prefixを指定しない場合には、/usr/localが指定されたものとみなします。LD_LIBRARY_PATHなどに詳しくない人は、上記のように/usrを指定することをお勧めします。

2.1.2. 使用方法

groongaは、Cのライブラリとして使用する方法と、groonga実行ファイルを通して使用する方法があります。

本チュートリアルでは、groonga実行ファイルを使用する方法について説明します。

2.1.2.1. groonga実行ファイル

groonga実行ファイルを使って、DBの作成・操作・サーバの起動・サーバへの接続などの操作が行えます。

2.1.2.1.1. DBの作成

以下のようなコマンドを実行すると、データベースを新規に作成することができます。

書式

groonga -n データベースパス名

-nオプションは、データベースを作ることを示します。

データベースパス名には、新しく作成するデータベースのフルパス名を指定します。

上記コマンドでデータベースを作成すると、そのまま対話モードと呼ばれるコマンドを受け付けるモードになります。Ctrlキーを押しながらdキーを押すと、対話モードから抜けることができます。

実行例:

% groonga -n /tmp/tutorial.db
> ctrl-d
%

2.1.2.1.2. DBの操作

書式

groonga DBパス名 [コマンド]

既存のデータベースのフルパス名をDBパス名に指定します。 コマンドを指定すると、実行結果を返します。

コマンドを指定しない場合には、対話モードに入ります。 対話モードでは、標準入力からコマンドを読み込み、順次実行します。 本チュートリアルでは、対話モードを主に使用します。

たとえば、statusというコマンドを実行してみましょう。statusコマンドは、groongaの実行状態を返すコマンドです。

実行例:

% groonga /tmp/tutorial.db
> status
[[0,1269935682.29616,0.000122],{"alloc_count":124,"starttime":1269935680,"uptime":2,"version":"0.1.7-10-g6bf93ba"}]

以上のように、コマンドの実行結果は基本的にjson形式で返却されます。jsonの配列の0番目の要素に、エラーコードや実行時間などの情報が入ります。jsonの配列の1番目の様子に、コマンドの実行結果が入ります。

2.1.2.2. コマンド

groonga実行ファイルやgroongaサーバを介して様々なコマンドを実行して、DBを操作することができます。 コマンドは以下の書式のうちいずれかで与えることができます。

書式1: コマンド名 引数1 引数2 ..

書式2: コマンド名 --引数名1 値1 --引数名2 値2 ..

書式1と2は混ぜて使うことができます。

書式2において、空白や、記号「”’()」のうちいずれかを含む値を指定したい場合は、シングルクォート(‘)かダブルクォート(“)で値を囲みます。

詳しくは、:doc:../execfile のコマンドの項を参考にしてください。

2.1.2.2.1. 主なコマンド

status
groongaプロセスの状態を表示します。
table_list
DBに定義されているテーブルのリストを表示します。
column_list
テーブルに定義されているカラムのリストを表示します。
table_create
DBにテーブルを追加します。
column_create
テーブルにカラムを追加します。
select
テーブルに含まれるレコードを検索して表示します。
load
テーブルにレコードを挿入します。

2.1.2.2.2. テーブルの作成

table_create コマンドを使用してテーブルを作成します。

groongaでは、多くの場合テーブルを作成する際に主キーが必要となります。また、主キーには型と、その格納方法を指定する必要があります。

型については、本チュートリアルでは触れません。:doc:type の項を参照してください。主キーの格納方法によって、主キーでの検索速度や、前方一致検索の可否が決まります。しかし、本チュートリアルでは触れません。

ここでは、ShortText型の主キー値を持ち、主キーの格納方法はHASHである、’Site’という名前のテーブルを作成します。

実行例:

> table_create --name Site --flags TABLE_HASH_KEY --key_type ShortText
[[0,1268294088.70744,0.098794]]

2.1.2.2.3. 検索

select コマンドを用いて、テーブルの中身を表示することができます。

実行例:

> select --table Site
[[0,1269854691.80132,0.000106],[[[0],[["_id","UInt32"],["_key","ShortText"]]]]]

selectにテーブル名を指定すると、指定したテーブルの中身を10件表示します。[0]は検索されたレコードの件数、[“_id”,”Uint32”]は値がUInt32型である”_id’という名前のカラム、[“_key”,”ShortText”]は値がShortText型である’_key’という名前のカラムを示しています。

table_createコマンドで作成したテーブルには、最初から’_id’/’_key’という2つのカラムがあります。’_id’はgroongaが自動的に付与するID番号が格納されるカラムです。’_key’は主キーが格納されるカラムです。これらのカラム名を変更することはできません。

2.1.2.2.4. カラムの作成

column_create コマンドを用いて、カラムを作成することができます。

ShortText型の値を持つ、’comment’という名前のカラムを’Site’テーブルに追加しましょう。

実行例:

> column_create --table Site --name title --flags COLUMN_SCALAR --type ShortText
[[0,1268294203.38404,0.056593]]
> select --table Site
[[0,1269854897.8173,0.000105],[[[0],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]]]]]

COLUMN_SCALARについては、通常のカラムであることを示しています。

2.1.2.2.5. 全文検索用の語彙テーブルの作成

このチュートリアルでは、groongaに登録したデータを用いた全文検索を行います。

全文検索を行う場合は、まず語彙テーブルを作成する必要があります。 語彙表テーブルとは、文書の中にある単語が主キーとなるテーブルです。 ここでは、ShortText型の主キー値を持つ、’Terms’という名前のテーブルを作成しました。

実行例:

> table_create --name Terms --flags TABLE_PAT_KEY|KEY_NORMALIZE --key_type ShortText --default_tokenizer TokenBigram
[[0,1268294159.76784,0.049841]]

この実行例には、多くのパラメータが指定されています。本チュートリアルでは、これらをすべて理解する必要はありません。以下に簡単な説明を記しますが、読み飛ばしてもらってかまいません。

実行例にある、TABLE_PAT_KEY|KEY_NORMALIZEという値は、主キー値をパトリシア木に格納し、各語彙を正規化して登録することを示しています。

実行例にある、TokenBigramという値は、 語彙表として使用するテーブルは、対象の文書をトークナイズする方式を、default_tokenizerパラメータで与えます。この例ではTokenBigramを指定しています。よって、一般的にN-gramと呼ばれるようなインデックス方式を選択しています。

2.1.2.2.6. 全文検索用のインデックスカラムの作成

Siteテーブルのtitleカラムを全文検索の対象としたいとしましょう。その場合には、語彙テーブルにインデックス型のカラムを作成します。

実行例:

> column_create --table Terms --name blog_title --flags COLUMN_INDEX|WITH_POSITION --type Site --source title
[[0,1268294247.01333,0.129917]]

Siteテーブルのtitleカラムを検索対象とする、’blog_title’という名前のインデックス型カラムをTermsテーブルに作成しました。インデックス対象となるテーブルをtypeに、インデックス対象となるカラムをsourceに指定します。

実行例のflagsのCOLUMN_INDEX|WITH_POSITIONという値は、語彙の位置情報を格納するインデックス型のカラムであることを示しています。通常の全文検索インデックスでは、COLUMN_INDEX|WITH_POSITIONを指定してください。語彙の位置情報を格納する意味については、本チュートリアルでは触れません。

2.1.2.2.7. データのロード

load コマンドを使用します。loadコマンドでは、jsonで受け取ったデータをテーブルに格納します。

実行例:

> load --table Site
> [
> {"_key":"http://example.org/","title":"This is test record 1!"},
> {"_key":"http://example.net/","title":"test record 2."},
> ]
[[0,1268380982.80157,0.002685],2]

selectコマンドで、データが入っていることを確認しましょう。:

> select --table Site
[[0,1269855382.8395,0.000121],[[[2],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"],[2,"http://example.net/","test record 2."]]]]

2.1.2.2.8. データの検索

groongaでは、’_id’カラムと’_key’カラムの値はテーブル中で一意です。よって、それを用いて検索してみましょう。

selectコマンドにおいて、queryパラメータを用いるとデータの検索を行うことができます。

実行例:

> select --table Site --query _id:1
[[0,1269961834.61914,0.001204],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"]]]]

queryパラメータに与えた「_id:1」というのは、’_id’という名前のカラムに‘1’という値が入っているレコードを検索する、という意味です。

_keyでも検索してみましょう。

実行例:

> select --table Site --query "_key:\"http://example.org/\""
[[0,1269964004.37746,0.0006],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"]]]]

queryパラメータに与えた「”_key:”http://example.org/“”」というのは、’_key’という名前のカラムに’”http://example.org/“’という値が入っているレコードを検索する、という意味です。

2.1.2.2.9. 全文検索

queryパラメータでは、インデックスを用いた全文検索を行うこともできます。

実行例

> select --table Site --query title:this
[[0,1268381101.20846,0.000401],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"]]]]

titleカラムに対して、’this’という文字列で全文検索を行った結果を返します。

selectコマンドには、match_columnsというパラメータが存在します。これを指定すると、query内にカラム名を指定しない条件があった場合、match_columnsで指定されたカラムに対しての検索であることを示します。[1]_

match_columnsパラメータに’title’、queryパラメータに’this’という文字列を指定すると、上記のクエリと同じ結果を得ることができます。

実行例

> select --table Site --match_columns title --query this
[[0,1268381101.20846,0.000401],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"]]]]

2.1.3. 出力カラムの指定

執筆中です。

2.1.4. offset/limit/sort

執筆中です。

脚注

[1]現在のバージョンでは、全文検索インデックスが存在する場合にのみ、match_columnsパラメータを利用することをができます。通常のカラムでの絞り込みには利用できません。