h1. チュートリアル
このページでは簡単なアプリケーションの作成を通して
rroongaの操作方法を紹介します。
h2. インストール
rroongaはRubyGemsでインストールできます。
!!!command_line
% sudo gem install rroonga
h2. データベースの作成
簡単なブックマークアプリケーション用のデータベースを作ってみ
ます。以下のようにgroongaライブラリを読み込んでirbを起動しま
す。
!!!irb
% irb --simple-prompt -rubygems -rgroonga
>>
まず、エンコーディングを設定します。ここではUTF-8を利用します。
!!!irb
>> $KCODE = "UTF-8"
=> "UTF-8"
>> Groonga::Context.default_options = {:encoding => :utf8}
=> {:encoding=>:utf8}
それでは、ファイルを指定してデータベースを作成します。
!!!irb
>> Groonga::Database.create(:path => "/tmp/bookmark.db")
=> #
ここで作成したデータベースは、これ以降、暗黙のうちに利用され
ます。最初にデータベースを作成したら特に意識する必要はありま
せん。
h2. テーブルの定義
groongaには以下の3種類のテーブルがあります。
- Groonga::Hash :=
ハッシュテーブル。主キーでレコードを管理します。キーと完全
一致するレコードを非常に高速に検索することができます。
=:
- Groonga::PatriciaTrie :=
パトリシアトライ。ハッシュテーブルに比べて完全一致検索の速
度がやや遅いですが、前方一致検索・共通接頭辞探索などの検索
が行えます。またカーソルを用いてキーの昇降順にレコードを取
り出すことができます。
=:
- Groonga::Array :=
配列。主キーの存在しないテーブルです。レコードはIDによって
識別します。
=:
ここではハッシュテーブルを利用して、 @Items@ という名前のテー
ブルを作成します。キーは文字列とします。
!!!irb
>> Groonga::Schema.create_table("Items", :type => :hash)
=> [...]
これで @Items@ という名前のテーブルが作成できました。
定義したテーブルはGroonga.[]で参照できます。
!!!irb
>> items = Groonga["Items"]
=> #
テーブルはRubyのHashのように扱えます。
例えば、以下のように @size@ でテーブルに登録されているレコード
の件数を取得できます。
!!!irb
>> items.size
=> 0
h2. レコードを追加する
@Items@ テーブルにレコードを追加します。
!!!irb
>> items.add("http://ja.wikipedia.org/wiki/Ruby")
=> #
>> items.add("http://www.ruby-lang.org/ja/")
=> #
件数を確認すると確かに2件増えています。
!!!irb
>> items.size
=> 2
主キーを指定してレコードを取り出す時には以下のようにします。
!!!irb
>> items["http://ja.wikipedia.org/wiki/Ruby"]
=> #
h2. 全文検索を行う
各itemのタイトル文字列を登録して、全文検索できるようにしてみ
ましょう。
まず @Items@ テーブルに @title@ という名前のカラムを追加し
ます。ここでは、 @Text@ 型のデータを持つカラムとして定義
します。
!!!irb
>> Groonga::Schema.change_table("Items") do |table|
?> table.text("title")
>> end
=> [...]
定義したカラムは @#{テーブル名}.#{カラム名}@ という名前になります。
テーブルと同じように {Groonga.[]} で参照できます。
!!!irb
>> title_column = Groonga["Items.title"]
=> #
全文検索するために、文字列を分解して得られる各単語を格納する
ためのテーブルを別途用意します。ここではTermsという名前でテー
ブルを定義します。
!!!irb
>> Groonga::Schema.create_table("Terms",
?> :type => :patricia_trie,
?> :key_normalize => true,
?> :default_tokenizer => "TokenBigram")
ここでは、トークナイザとして:default_tokenzier =>
"TokenBigram" を指定しています。トークナイザとは文字列を
単語に分解するオブジェクトのことです。デフォルトではトークナ
イザは指定されていません。全文検索を利用するためにはトークナ
イザを指定する必要があるので、ここではN-gramの一種であるバイ
グラムを指定しています。
N-gramを利用した全文検索では、分解したN文字とその出現位置を利
用して全文検索を行います。N-gramのNは文字列を何文字毎に分解す
るかの文字数になります。groongaは1文字で分解するユニグラム、
2文字のバイグラム、3文字のトリグラムをサポートしています。
また、大文字小文字の区別なく検索するために
@:key_normalize => true@ も指定しています。
単語格納用テーブルの準備ができたので、 @Items@ テーブ
ルの @title@ カラムに対するインデックスを定義します。
!!!irb
>> Groonga::Schema.change_table("Terms") do |table|
?> table.index("Items.title")
>> end
=> [...]
少し違和感を感じるかも知れませんが、 @Items@ テーブル
のカラムに対するインデックスは、 @Terms@ テーブルのカ
ラムとして定義します。
@Items@ にレコードが登録されると、その中に含まれる単
語に該当するレコードが @Terms@ に自動的に追加されるよ
うになります。
@Terms@ は、文書に含まれる語彙に相当する、やや特殊な
テーブルだと言えます。しかし、他のテーブルと同様に語彙テーブ
ルには自由にカラムを追加し、単語毎の様々な属性を管理すること
ができます。これはある種の検索処理を行う際には非常に便利に機
能します。
これでテーブルの定義は完了です。
先ほど登録した各レコードの @title@ カラムに値をセットします。
!!!irb
>> items["http://ja.wikipedia.org/wiki/Ruby"].title = "Ruby"
=> "Ruby"
>> items["http://www.ruby-lang.org/ja/"].title = "オブジェクトスクリプト言語Ruby"
"オブジェクトスクリプト言語Ruby"
以下のようにして検索することができます。
!!!irb
>> ruby_items = items.select {|record| record.title =~ "Ruby"}
=> #>
検索結果はGroonga::Hashで返されます。ハッシュのキーに見つかっ
た @Items@ のレコードが入っています。
!!!irb
>> ruby_items.collect {|record| record.key.key}
=> ["http://ja.wikipedia.org/wiki/Ruby", "http://www.ruby-lang.org/ja/"]
上の例では @record.key@ で @Items@ のレコードを取得して、
さらにそのキーを指定して（ @record.key.key@ ）で @Items@
のキーを返しています。
@record["_key"]@ でアクセスすると自動的に参照しているレコード
を辿っていき、参照先のキーにアクセスできます。
!!!irb
>> ruby_items.collect {|record| record["_key"]}
=> ["http://ja.wikipedia.org/wiki/Ruby", "http://www.ruby-lang.org/ja/"]
h2. マルチユーザ向けのブックマークアプリケーション
ここまでで作った単機能のアプリケーションをもう少し拡張して、
複数のユーザが、それぞれにコメントを記入できるブックマークア
プリケーションにしてみましょう。
まず、ユーザ情報とコメント情報を格納するテーブルを追加して、
下図のようなテーブル構成にします。
!http://qwik.jp/senna/senna2.files/rect4605.png!
まず、 @Users@ テーブルを追加します。
!!!irb
>> Groonga::Schema.create_table("Users", :type => :hash) do |table|
?> table.text("name")
>> end
=> [...]
次に、 @Comments@ テーブルを追加します。
!!!irb
>> Groonga::Schema.create_table("Comments") do |table|
?> table.reference("item")
>> table.reference("author", "Users")
>> table.text("content")
>> table.time("issued")
>> end
=> [...]
@Comments@ テーブルの @content@ カラムを全文検索できる
ようにインデックスを定義します。
!!!irb
>> Groonga::Schema.change_table("Terms") do |table|
?> table.index("Comments.content")
>> end
=> [...]
これでテーブルが定義できました。
続いてユーザを何人か追加します。
!!!irb
>> users = Groonga["Users"]
=> #
>> users.add("moritan", :name => "モリタン")
=> #
>> users.add("taporobo", :name => "タポロボ")
=> #
次に、実際にユーザがブックマークを貼る時の処理を実行してみま
しょう。
ユーザ @moritan@ が、Ruby関連のとあるページをブックマークしたと
想定します。
まず対象のページが @Items@ テーブルに登録済かどうか調
べます。
!!!irb
>> items.has_key?("http://www.rubyist.net/~matz/")
=> false
未登録なのでまず当該ページを @Items@ に登録します。
!!!irb
>> items.add("http://www.rubyist.net/~matz/",
?> :title => "Matzにっき")
=> #
次に、登録したitemを @item@ カラムの値に指定して
@Comments@ にレコードを登録します。
!!!irb
>> require "time"
=> true
>> comments = Groonga["Comments"]
=> #
>> comments.add(:item => "http://www.rubyist.net/~matz/",
?> :author => "moritan",
?> :content => "Ruby Matz",
?> :issued => Time.parse("2010-11-20T18:01:22+09:00"))
=> #
h2. メソッド化
上記の一連の手続きをメソッドにまとめてみます。
!!!irb
>> @items = items
=> #
>> @comments = comments
=> #
>> def add_bookmark(url, title, author, content, issued)
>> item = @items[url] || @items.add(url, :title => title)
>> @comments.add(:item => item,
?> :author => author,
?> :content => content,
?> :issued => issued)
>> end
=> nil
@items@ と @comments@ をインスタンス変数に代入しているのはメ
ソッド内からでも見えるようにするためです。
@add_bookmark@ は以下のような手順を実行しています。
* @Items@ テーブルに該当ページのレコードがあるかどうか調べる。
* レコードがなければ追加する。
* @Comments@ テーブルにレコードを登録する。
作成したメソッドを呼び出していくつかブックマークを登録してみ
ましょう。
!!!irb
>> add_bookmark("http://jp.rubyist.net/magazine/",
?> "Rubyist Magazine - るびま", "moritan", "Ruby 記事",
?> Time.parse("2010-10-07T14:18:28+09:00"))
=> #
>> add_bookmark("http://groonga.rubyforge.org/",
?> "Rubyでgroonga使って全文検索 - ラングバ", "taporobo",
?> "Ruby groonga 全文検索",
?> Time.parse("2010-11-11T12:39:59+09:00"))
=> #
>> add_bookmark("http://www.rubyist.net/~matz/",
?> "Matz日記", "taporobo", "Ruby 日記",
?> Time.parse("2010-07-28T20:46:23+09:00"))
=> #
h2. 全文検索その2
登録したレコードに対して全文検索を実行してみます。
!!!irb
>> records = comments.select do |record|
?> record["content"] =~ "Ruby"
>> end
=> #
>> records.each do |record|
?> comment = record.value
>> p [comment.id,
?> comment.issued,
?> comment.item.title,
?> comment.author.name,
?> comment.content]
>> end
[1, Sat Nov 20 18:01:22 +0900 2010, "Matzにっき", "モリタン", "Ruby Matz"]
[2, Thu Oct 07 14:18:28 +0900 2010, "Rubyist Magazine - るびま", "モリタン", "Ruby 記事"]
[3, Thu Nov 11 12:39:59 +0900 2010, "Rubyでgroonga使って全文検索 - ラングバ", "タポロボ", "Ruby groonga 全文検索検"]
[4, Wed Jul 28 20:46:23 +0900 2010, "Matzにっき", "タポロボ", "Ruby 日記"]
カラム名と同じメソッドでカラムへのアクセスできます。複合デー
タ型の要素も再帰的に辿ることができます。（同様の出力を普通の
RDBで実現するためには、 @Items@ テーブル、
@Comments@ テーブル、 @Users@ テーブルのJOIN操作が
必要になります。）
上の式の中で、肝心の検索処理は、第一引数の式を評価する時点で
完了していて、レコードセットオブジェクトとしてメモリに蓄積さ
れています。
!!!irb
>> records
#>
レコードセットは、出力する前に様々に加工することができます。
以下は、日付で降順にソートしてから出力した例です。
!!!irb
>> records.sort([{:key => "issued", :order => "descending"}]).each do |record|
?> comment = record.key
>> p [comment.id,
?> comment.issued,
?> comment.item.title,
?> comment.author.name,
?> comment.content]
>> end
[1, Sat Nov 20 18:01:22 +0900 2010, "Matzにっき", "モリタン", "Ruby Matz"]
[3, Thu Nov 11 12:39:59 +0900 2010, "Rubyでgroonga使って全文検索 - ラングバ", "タポロボ", "Ruby groonga 全文検索"]
[2, Thu Oct 07 14:18:28 +0900 2010, "Rubyist Magazine - るびま", "モリタン", "Ruby 記事"]
[4, Wed Jul 28 20:46:23 +0900 2010, "Matzにっき, "タポロボ", "Ruby 日記"]
=> [...]
同じitemが何度も出てくると検索結果が見にくいので、item毎にグ
ループ化してみます。
!!!irb
>> records.group("item").each do |record|
?> item = record.key
>> p [record.n_sub_records,
?> item.key,
?> item.title]
>> end
[2, "http://www.rubyist.net/~matz/", "Matzにっき"]
[1, "http://jp.rubyist.net/magazine/", "Rubyist Magazine - るびま"]
[1, "http://groonga.rubyforge.org/", "Rubyでgroonga使って全文検索 - ラングバ"]
=> nil
@n_sub_records@ というのはグループ化した単位に含まれるレコード
の件数を示します。SQLで言えば、GROUP BY句を含むクエリのcount
関数のような働きです。
h2. 少し複雑な検索
さらに実用的な検索について考えてみましょう。
ブックマークが大量に蓄積されるに従って、より的確に適合度を算
出する必要性に迫られます。
今のところ検索対象として利用できるのは @Items.title@
と @Comments.content@ ですが、 @Items.title@ は
元ページから得られるやや信頼できる情報なのに対して、
@Comments.content@ はブックマークユーザが任意に設定で
きる情報で、やや信憑性に乏しいと言えます。しかし、再現率を確
保するためにはユーザのコメントも是非対象に含めたいところです。
そこで、以下のようなポリシーで検索を行うことにします。
* @Items.title@ か @Comments.content@ のいずれ
かにマッチするitemを検索する。
* ただし、 @Items.title@ にマッチしたレコードはスコア
を10倍重み付けする。
* 同一のitemに対して、キーワードにマッチする @comment@
が複数存在した場合は、それぞれの @comment@ のスコアの
和を、該当するitemのスコアとする。
以下のようにして、commentとitemとそれぞれに対する検索結果を求
めます。
!!!irb
>> ruby_comments = @comments.select {|record| record.content =~ "Ruby"}
=> #
>> ruby_items = @items.select do |record|
?> target = record.match_target do |match_record|
?> match_record.title * 10
>> end
>> target =~ "Ruby"
>> end
#>
_ruby_comments_の結果をitem毎にグループ化し、_ruby_items_と
unionして出力します。
!!!irb
>> ruby_items = ruby_comments.group("item").union!(ruby_items)
#>
>> ruby_items.sort([{:key => "_score", :order => "descending"}]).each do |record|
>> p [record.score, record.title]
>> end
[10, "Rubyist Magazine - るびま"]
[10, "Ruby"]
[10, "Rubyでgroonga使って全文検索 - ラングバ"]
[10, "オブジェクトスクリプト言語Ruby"]
[2, "Matzにっき"]
これで目的の結果が得られました。