rroonga 1.0.1-x86-mingw32 → 1.1.0-x86-mingw32

data/test/test-table-select-weight.rb

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# Copyright (C) 2010  Kouhei Sutou <kou@clear-code.com>
+# Copyright (C) 2010-2011  Kouhei Sutou <kou@clear-code.com>
 #
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
@@ -42,6 +42,11 @@ class TableSelectWeightTest < Test::Unit::TestCase
         table.index("Comments.content", :with_section => true)
       end
 
+      schema.create_table("Titles",
+                          :type => :hash) do |table|
+        table.index("Comments.title")
+      end
+
       schema.change_table("Users") do |table|
         table.index("Comments.user")
       end
@@ -101,4 +106,18 @@ class TableSelectWeightTest < Test::Unit::TestCase
       [record.title, record.score]
     end
   end
+
+  def test_index
+    result = @comments.select do |record|
+      record.match("Hello") do |match_record|
+        (match_record.index("Titles.Comments_title") * 1000) |
+          (match_record.index("Terms.Comments_title") * 100) |
+          match_record.content
+      end
+    end
+    assert_equal_select_result([["Hello", 1101], ["(no title)", 3]],
+                               result) do |record|
+      [record.title, record.score]
+    end
+  end
 end

data/test/test-table-select.rb

@@ -33,7 +33,12 @@ class TableSelectTest < Test::Unit::TestCase
                                          :default_tokenizer => "TokenBigram")
     terms.define_index_column("comment_content", @comments,
                               :with_section => true,
+                              :with_position => true,
                               :source => "content")
+    terms.define_index_column("users_key", @users,
+                              :with_section => true,
+                              :with_position => true,
+                              :source => "_key")
     @comment1 = @comments.add(:content => "Hello Good-bye!",
                               :created_at => Time.parse("2009-08-09"),
                               :user => "morita")
@@ -147,4 +152,11 @@ class TableSelectTest < Test::Unit::TestCase
     end
     assert_equal_select_result([], result)
   end
+
+  def test_select_query_key
+    result = @users.select do |record|
+      record["_key"] =~ "mori"
+    end
+    assert_equal_select_result([@users["morita"]], result)
+  end
 end

data/test/test-table.rb

@@ -594,6 +594,71 @@ class TableTest < Test::Unit::TestCase
     assert_false(users.have_column?("description"), "description")
   end
 
+  def test_have_column_id
+    users = Groonga::Array.create(:name => "Users")
+    assert_true(users.have_column?(:_id))
+  end
+
+  def test_have_column_key_hash
+    users = Groonga::Hash.create(:name => "Users",
+                                 :key_type => "ShortText")
+    assert_true(users.have_column?(:_key))
+  end
+
+  def test_have_column_key_array
+    users = Groonga::Array.create(:name => "Users")
+    assert_false(users.have_column?(:_key))
+  end
+
+  def test_have_column_value_hash_with_value_type
+    users = Groonga::Hash.create(:name => "Users",
+                                 :key_type => "ShortText",
+                                 :value_type => "Int32")
+    assert_true(users.have_column?(:_value))
+  end
+
+  def test_have_column_value_hash_without_value_type
+    users = Groonga::Hash.create(:name => "Users",
+                                 :key_type => "ShortText")
+    assert_false(users.have_column?(:_value))
+  end
+
+  def test_have_column_value_array
+    users = Groonga::Array.create(:name => "Users")
+    assert_false(users.have_column?(:_value))
+  end
+
+  def test_have_column_nsubrecs_existent
+    users = Groonga::Hash.create(:name => "Users",
+                                 :key_type => "ShortText")
+    assert_true(users.select.have_column?(:_nsubrecs))
+  end
+
+  def test_have_column_nsubrecs_nonexistent
+    users = Groonga::Hash.create(:name => "Users",
+                                 :key_type => "ShortText")
+    assert_false(users.have_column?(:_nsubrecs))
+  end
+
+  def test_have_column_score_existent
+    users = Groonga::Hash.create(:name => "Users",
+                                 :key_type => "ShortText")
+    assert_true(users.select.have_column?(:_score))
+  end
+
+  def test_have_column_score_nonexistent
+    users = Groonga::Hash.create(:name => "Users",
+                                 :key_type => "ShortText")
+    assert_false(users.have_column?(:_score))
+  end
+
+  def test_exist?
+    users = Groonga::Hash.create(:name => "Users")
+    morita = users.add("morita")
+    assert_true(users.exist?(morita.id))
+    assert_false(users.exist?(morita.id + 1))
+  end
+
   private
   def create_bookmarks
     bookmarks = Groonga::Array.create(:name => "Bookmarks")

data/test/test-variable-size-column.rb

@@ -50,6 +50,18 @@ class VariableSizeColumnTest < Test::Unit::TestCase
     @yu = @users.add(:name => "Yutaro Shimamura")
   end
 
+  def test_index?
+    assert_not_predicate(@nick_names, :index?)
+  end
+
+  def test_vector?
+    assert_predicate(@nick_names, :vector?)
+  end
+
+  def test_scalar?
+    assert_not_predicate(@nick_names, :scalar?)
+  end
+
   def test_inspect
     assert_equal("#<Groonga::VariableSizeColumn " +
                  "id: <#{@name.id}>, " +

data/text/tutorial.ja.rdoc

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