groonga 0.0.7 → 0.9.0

data/lib/groonga/schema.rb

@@ -27,17 +27,17 @@ module Groonga
   # のようなスキーマを定義する場合は以下のようになる。
   #
   #   Groonga::Schema.define do |schema|
-  #     schema.create_table("items") do |table|
+  #     schema.create_table("Items") do |table|
   #       table.short_text("title")
   #     end
   #
-  #     schema.create_table("users") do |table|
+  #     schema.create_table("Users") do |table|
   #       table.short_text("name")
   #     end
   #
   #     schema.create_table("comments") do |table|
-  #       table.reference("item", "items")
-  #       table.reference("author", "users")
+  #       table.reference("item", "Items")
+  #       table.reference("author", "Users")
   #       table.text("content")
   #       table.time("issued")
   #     end
@@ -50,7 +50,11 @@ module Groonga
       #
       # スキーマを定義する。ブロックにはGroonga::Schemaオブ
       # ジェクトがわたるので、そのオブジェクトを利用してスキー
-      # マを定義する。
+      # マを定義する。以下の省略形。
+      #
+      #  schema = Groonga::Scheme.new(options)
+      #  ...
+      #  schema.define
       #
       # _options_に指定可能な値は以下の通り。
       #
@@ -80,6 +84,15 @@ module Groonga
       #
       # _options_に指定可能な値は以下の通り。
       #
+      # [+:force+]
+      #   +true+を指定すると既存の同名のテーブルが存在してい
+      #   ても、強制的にテーブルを作成する。
+      #
+      # [+:type+]
+      #   テーブルの型を指定する。+:array+, +:hash+,
+      #   +:patricia_trie+のいずれかを指定する。デフォルトで
+      #   は+:array+になる。
+      #
       # [+:context+]
       #   スキーマ定義時に使用するGroonga::Contextを指定する。
       #   省略した場合はGroonga::Context.defaultを使用する。
@@ -96,6 +109,49 @@ module Groonga
       # [+:value_type+]
       #   値の型を指定する。省略すると値のための領域を確保しない。
       #   値を保存したい場合は必ず指定すること。
+      #
+      # [+:sub_records+]
+      #   +true+を指定するとGroonga::Table#groupでグループ化
+      #   したときに、Groonga::Record#n_sub_recordsでグルー
+      #   プに含まれるレコードの件数を取得できる。
+      #
+      # 以下は+:type+に+:hash+あるいは+:patricia_trie+を指定
+      # した時に指定可能。
+      #
+      # [+:key_type+]
+      #   キーの種類を示すオブジェクトを指定する。キーの種類
+      #   には型名（"Int32"や"ShortText"など）または
+      #   Groonga::Typeまたはテーブル（Groonga::Array、
+      #   Groonga::Hash、Groonga::PatriciaTrieのどれか）を指
+      #   定する。
+      #
+      #   Groonga::Typeを指定した場合は、その型が示す範囲の
+      #   値をキーとして使用する。ただし、キーの最大サイズは
+      #   4096バイトであるため、Groonga::Type::TEXTや
+      #   Groonga::Type::LONG_TEXTは使用できない。
+      #
+      #   テーブルを指定した場合はレコードIDをキーとして使用
+      #   する。指定したテーブルのGroonga::Recordをキーとし
+      #   て使用することもでき、その場合は自動的に
+      #   Groonga::RecordからレコードIDを取得する。
+      #
+      #   省略した場合は文字列をキーとして使用する。この場合、
+      #   4096バイトまで使用可能である。
+      #
+      # [+:default_tokenizer+]
+      #   Groonga::IndexColumnで使用するトークナイザを指定す
+      #   る。デフォルトでは何も設定されていないので、テーブ
+      #   ルにGroonga::IndexColumnを定義する場合は
+      #   <tt>"TokenBigram"</tt>などを指定する必要がある。
+      #
+      # 以下は+:type+に+:patricia_trie+を指定した時に指定可能。
+      #
+      # [+:key_normalize+]
+      #   +true+を指定するとキーを正規化する。
+      #
+      # [+:key_with_sis+]
+      #   +true+を指定するとキーの文字列の全suffixが自動的に
+      #   登録される。
       def create_table(name, options={}, &block)
         define do |schema|
           schema.create_table(name, options, &block)
@@ -103,6 +159,7 @@ module Groonga
       end
 
       # 名前が_name_のテーブルを削除する。
+      #
       # _options_に指定可能な値は以下の通り。
       #
       # [+:context+]
@@ -114,6 +171,26 @@ module Groonga
         end
       end
 
+      # call-seq:
+      #   Groonga::Schema.change_table(name, options={}) {|table| ...}
+      #
+      # 名前が_name_のテーブルを変更する。以下の省略形。
+      #
+      #   Groonga::Schema.define do |schema|
+      #     schema.change_table(name, options) do |table|
+      #       ...
+      #     end
+      #   end
+      #
+      # ブロックにはGroonga::Schema::TableDefinitionオブジェ
+      # クトがわたるので、そのオブジェクトを利用してテーブル
+      # の詳細を定義する。
+      #
+      # _options_に指定可能な値は以下の通り。
+      #
+      # [+:context+]
+      #   スキーマ定義時に使用するGroonga::Contextを指定する。
+      #   省略した場合はGroonga::Context.defaultを使用する。
       def change_table(name, options={}, &block)
         define do |schema|
           schema.change_table(name, options, &block)
@@ -203,13 +280,25 @@ module Groonga
       instance_eval(dumped_text)
     end
 
+    # call-seq:
+    #   schema.create_table(name, options={}) {|table| ...}
+    #
     # 名前が_name_のテーブルを作成する。
     #
-    # 作成したテーブルは#defineを呼び出すまでは実行されない
-    # ことに注意すること。
+    # テーブルの作成は#defineを呼び出すまでは実行されないこ
+    # とに注意すること。
     #
     # _options_に指定可能な値は以下の通り。
     #
+    # [+:force+]
+    #   +true+を指定すると既存の同名のテーブルが存在してい
+    #   ても、強制的にテーブルを作成する。
+    #
+    # [+:type+]
+    #   テーブルの型を指定する。+:array+, +:hash+,
+    #   +:patricia_trie+のいずれかを指定する。デフォルトで
+    #   は+:array+になる。
+    #
     # [+:context+]
     #   スキーマ定義時に使用するGroonga::Contextを指定する。
     #   省略した場合はGroonga::Schema.newで指定した
@@ -230,17 +319,83 @@ module Groonga
     #   い。値を保存したい場合は必ず指定すること。
     #
     #   参考: Groonga::Type.new
+    #
+    # [+:sub_records+]
+    #   +true+を指定するとGroonga::Table#groupでグループ化
+    #   したときに、Groonga::Record#n_sub_recordsでグルー
+    #   プに含まれるレコードの件数を取得できる。
+    #
+    # 以下は+:type+に+:hash+あるいは+:patricia_trie+を指定
+    # した時に指定可能。
+    #
+    # [+:key_type+]
+    #   キーの種類を示すオブジェクトを指定する。キーの種類
+    #   には型名（"Int32"や"ShortText"など）または
+    #   Groonga::Typeまたはテーブル（Groonga::Array、
+    #   Groonga::Hash、Groonga::PatriciaTrieのどれか）を指
+    #   定する。
+    #
+    #   Groonga::Typeを指定した場合は、その型が示す範囲の
+    #   値をキーとして使用する。ただし、キーの最大サイズは
+    #   4096バイトであるため、Groonga::Type::TEXTや
+    #   Groonga::Type::LONG_TEXTは使用できない。
+    #
+    #   テーブルを指定した場合はレコードIDをキーとして使用
+    #   する。指定したテーブルのGroonga::Recordをキーとし
+    #   て使用することもでき、その場合は自動的に
+    #   Groonga::RecordからレコードIDを取得する。
+    #
+    #   省略した場合は文字列をキーとして使用する。この場合、
+    #   4096バイトまで使用可能である。
+    #
+    # [+:default_tokenizer+]
+    #   Groonga::IndexColumnで使用するトークナイザを指定す
+    #   る。デフォルトでは何も設定されていないので、テーブ
+    #   ルにGroonga::IndexColumnを定義する場合は
+    #   <tt>"TokenBigram"</tt>などを指定する必要がある。
+    #
+    # 以下は+:type+に+:patricia_trie+を指定した時に指定可能。
+    #
+    # [+:key_normalize+]
+    #   +true+を指定するとキーを正規化する。
+    #
+    # [+:key_with_sis+]
+    #   +true+を指定するとキーの文字列の全suffixが自動的に
+    #   登録される。
     def create_table(name, options={})
       definition = TableDefinition.new(name, @options.merge(options || {}))
       yield(definition)
       @definitions << definition
     end
 
+    # 名前が_name_のテーブルを削除する。
+    #
+    # テーブルの削除は#defineを呼び出すまでは実行されないこ
+    # とに注意すること。
+    #
+    # _options_に指定可能な値は以下の通り。
+    #
+    # [+:context+]
+    #   スキーマ定義時に使用するGroonga::Contextを指定する。
+    #   省略した場合はGroonga::Context.defaultを使用する。
     def remove_table(name, options={})
       definition = TableRemoveDefinition.new(name, @options.merge(options || {}))
       @definitions << definition
     end
 
+    # call-seq:
+    #   schema.change_table(name, options={}) {|table| ...}
+    #
+    # 名前が_name_のテーブルを変更する。
+    #
+    # テーブルの変更は#defineを呼び出すまでは実行されないこ
+    # とに注意すること。
+    #
+    # _options_に指定可能な値は以下の通り。
+    #
+    # [+:context+]
+    #   スキーマ定義時に使用するGroonga::Contextを指定する。
+    #   省略した場合はGroonga::Context.defaultを使用する。
     def change_table(name, options={})
       options = @options.merge(options || {}).merge(:change => true)
       definition = TableDefinition.new(name, options)
@@ -248,10 +403,14 @@ module Groonga
       @definitions << definition
     end
 
+    # スキーマ定義時にGroonga::Schema.create_tableや
+    # Groonga::Schema#create_tableからブロックに渡されてくる
+    # オブジェクト
     class TableDefinition
+      # テーブルの名前
       attr_reader :name
 
-      def initialize(name, options)
+      def initialize(name, options) # :nodoc:
         @name = name
         @name = @name.to_s if @name.is_a?(Symbol)
         @definitions = []
@@ -260,22 +419,56 @@ module Groonga
         @table_type = table_type
       end
 
-      def define
+      def define # :nodoc:
+        table = context[@name]
         if @options[:change]
-          table = context[@name]
+          raise ArgumentError, "table doesn't exist: #{@name}" if table.nil?
         else
-          table = context[@name]
           if table and @options[:force]
             table.remove
+            table = nil
           end
-          table = @table_type.create(create_options)
+          table ||= @table_type.create(create_options)
         end
         @definitions.each do |definition|
-          definition.define(table)
+          definition.define(self, table)
         end
         table
       end
 
+      # 名前が_name_で型が_type_のカラムを作成する。
+      #
+      # _options_に指定可能な値は以下の通り。
+      #
+      # [+:force+]
+      #   +true+を指定すると既存の同名のカラムが存在してい
+      #   ても、強制的に新しいカラムを作成する。
+      #
+      # [+:path+]
+      #   カラムを保存するパス。
+      #
+      # [+:persistent+]
+      #   +true+を指定すると永続カラムとなる。+:path+を省略
+      #   した場合は自動的にパスが付加される。
+      #
+      # [+:type+]
+      #   カラムの値の格納方法について指定する。省略した場合は、
+      #   +:scalar+になる。
+      #
+      #   [+:scalar+]
+      #     スカラ値(単独の値)を格納する。
+      #
+      #   [+:vector+]
+      #     値の配列を格納する。
+      #
+      # [+:compress+]
+      #   値の圧縮方法を指定する。省略した場合は、圧縮しない。
+      #
+      #   [+:zlib+]
+      #     値をzlib圧縮して格納する。
+      #
+      #   [+:lzo+]
+      #     値をlzo圧縮して格納する。
       def column(name, type, options={})
         definition = self[name, ColumnDefinition]
         if definition.nil?
@@ -287,6 +480,10 @@ module Groonga
         self
       end
 
+      # 名前が_name_のカラムを削除する。
+      #
+      # _options_に指定可能な値はない(TODO _options_は不要?)。
+      #
       def remove_column(name, options={})
         definition = self[name, ColumnRemoveDefinition]
         if definition.nil?
@@ -297,6 +494,33 @@ module Groonga
         self
       end
 
+      # _taget_column_を対象とするインデックスカラムを作成す
+      # る。
+      #
+      # _options_に指定可能な値は以下の通り。
+      #
+      # [+:name+]
+      #   インデックスカラムのカラム名を任意に指定する。
+      #
+      # [+:force+]
+      #   +true+を指定すると既存の同名のカラムが存在してい
+      #   ても、強制的に新しいカラムを作成する。
+      #
+      # [+:path+]
+      #   カラムを保存するパス。
+      #
+      # [+:persistent+]
+      #   +true+を指定すると永続カラムとなる。+:path+を省略
+      #   した場合は自動的にパスが付加される。
+      #
+      # [+:with_section+]
+      #   転置索引にsection(段落情報)を合わせて格納する。
+      #
+      # [+:with_weight+]
+      #   転置索引にweight情報を合わせて格納する。
+      #
+      # [+:with_position+]
+      #   転置索引に出現位置情報を合わせて格納する。
       def index(target_column, options={})
         name = options.delete(:name)
         if name.nil?
@@ -319,66 +543,112 @@ module Groonga
         self
       end
 
+      # 名前が_name_の32bit符号付き整数のカラムを作成する。
+      #
+      # _options_に指定可能な値は
+      # Groonga::Schema::TableDefinition#columnを参照。
       def integer32(name, options={})
         column(name, "Int32", options)
       end
       alias_method :integer, :integer32
       alias_method :int32, :integer32
 
+      # 名前が_name_の64bit符号付き整数のカラムを作成する。
+      #
+      # _options_に指定可能な値は
+      # Groonga::Schema::TableDefinition#columnを参照。
       def integer64(name, options={})
         column(name, "Int64", options)
       end
       alias_method :int64, :integer64
 
+      # 名前が_name_の32bit符号なし整数のカラムを作成する。
+      #
+      # _options_に指定可能な値は
+      # Groonga::Schema::TableDefinition#columnを参照。
       def unsigned_integer32(name, options={})
         column(name, "UInt32", options)
       end
       alias_method :unsigned_integer, :unsigned_integer32
       alias_method :uint32, :unsigned_integer32
 
+      # 名前が_name_の64bit符号なし整数のカラムを作成する。
+      #
+      # _options_に指定可能な値は
+      # Groonga::Schema::TableDefinition#columnを参照。
       def unsigned_integer64(name, options={})
         column(name, "UInt64", options)
       end
       alias_method :uint64, :unsigned_integer64
 
+      # 名前が_name_のieee754形式の64bit浮動小数点数のカラム
+      # を作成する。
+      #
+      # _options_に指定可能な値は
+      # Groonga::Schema::TableDefinition#columnを参照。
       def float(name, options={})
         column(name, "Float", options)
       end
 
+      # 名前が_name_の64bit符号付き整数で1970年1月1日0時0分
+      # 0秒からの経過マイクロ秒数を格納するカラムを作成する。
+      #
+      # _options_に指定可能な値は
+      # Groonga::Schema::TableDefinition#columnを参照。
       def time(name, options={})
         column(name, "Time", options)
       end
 
+      # 名前が_name_の4Kbyte以下の文字列を格納できるカラムを
+      # 作成する。
+      #
+      # _options_に指定可能な値は
+      # Groonga::Schema::TableDefinition#columnを参照。
       def short_text(name, options={})
         column(name, "ShortText", options)
       end
       alias_method :string, :short_text
 
+      # 名前が_name_の64Kbyte以下の文字列を格納できるカラムを
+      # 作成する。
+      #
+      # _options_に指定可能な値は
+      # Groonga::Schema::TableDefinition#columnを参照。
       def text(name, options={})
         column(name, "Text", options)
       end
 
+      # 名前が_name_の2Gbyte以下の文字列を格納できるカラムを
+      # 作成する。
+      #
+      # _options_に指定可能な値は
+      # Groonga::Schema::TableDefinition#columnを参照。
       def long_text(name, options={})
         column(name, "LongText", options)
       end
 
+      # 名前が_name_で_table_のレコードIDを格納する参照カラ
+      # ムを作成する。
+      #
+      # _options_に指定可能な値は
+      # Groonga::Schema::TableDefinition#columnを参照。
       def reference(name, table, options={})
         column(name, table, options)
       end
 
-      def [](name, definition_class=nil)
+      def [](name, definition_class=nil) # :nodoc:
         @definitions.find do |definition|
           definition.name.to_s == name.to_s and
             (definition_class.nil? or definition.is_a?(definition_class))
         end
       end
 
-      def context
+      def context # :nodoc:
         @options[:context] || Groonga::Context.default
       end
 
       private
-      def update_definition(name, definition_class, definition)
+      def update_definition(name, definition_class, definition) # :nodoc:
         old_definition = self[name, definition_class]
         if old_definition
           index = @definitions.index(old_definition)
@@ -392,8 +662,8 @@ module Groonga
                                :type, :path, :persistent,
                                :key_type, :value_type, :sub_records,
                                :default_tokenizer,
-                               :key_normalize, :key_with_sis]
-      def validate_options(options)
+                               :key_normalize, :key_with_sis] # :nodoc:
+      def validate_options(options) # :nodoc:
         return if options.nil?
         unknown_keys = options.keys - AVAILABLE_OPTION_KEYS
         unless unknown_keys.empty?
@@ -403,7 +673,7 @@ module Groonga
         end
       end
 
-      def table_type
+      def table_type # :nodoc:
         type = @options[:type]
         case type
         when :array, nil
@@ -417,7 +687,7 @@ module Groonga
         end
       end
 
-      def create_options
+      def create_options # :nodoc:
         common = {
           :name => @name,
           :path => @options[:path],
@@ -446,16 +716,16 @@ module Groonga
         end
       end
 
-      def column_options
+      def column_options # :nodoc:
         {:persistent => persistent?}
       end
 
-      def persistent?
+      def persistent? # :nodoc:
         @options[:persistent].nil? ? true : @options[:persistent]
       end
     end
 
-    class TableRemoveDefinition
+    class TableRemoveDefinition # :nodoc:
       def initialize(name, options={})
         @name = name
         @options = options
@@ -467,7 +737,7 @@ module Groonga
       end
     end
 
-    class ColumnDefinition
+    class ColumnDefinition # :nodoc:
       attr_accessor :name, :type
       attr_reader :options
 
@@ -478,14 +748,33 @@ module Groonga
         @type = nil
       end
 
-      def define(table)
+      def define(table_definition, table)
+        column = table.column(@name)
+        if column
+          return column if same_column?(table_definition, column)
+          if @options.delete(:force)
+            column.remove
+          else
+            raise ArgumentError,
+                  "the same name column with different type is " +
+                  "already defined: #{@type.inspect}(#{@options.inspect}): " +
+                  "#{column.inspect}"
+          end
+        end
         table.define_column(@name,
                             Schema.normalize_type(@type),
                             @options)
       end
+
+      private
+      def same_column?(table_definition, column)
+        context = table_definition.context
+        # TODO: should check column type and other options.
+        column.range == context[Schema.normalize_type(@type)]
+      end
     end
 
-    class ColumnRemoveDefinition
+    class ColumnRemoveDefinition # :nodoc:
       attr_accessor :name
       attr_reader :options
 
@@ -495,12 +784,12 @@ module Groonga
         @options = (options || {}).dup
       end
 
-      def define(table)
+      def define(table_definition, table)
         table.column(@name).remove
       end
     end
 
-    class IndexColumnDefinition
+    class IndexColumnDefinition # :nodoc:
       attr_accessor :name, :target
       attr_reader :options
 
@@ -511,12 +800,27 @@ module Groonga
         @target = nil
       end
 
-      def define(table)
+      def define(table_definition, table)
         target = @target
-        target = context[target] unless target.is_a?(Groonga::Object)
+        unless target.is_a?(Groonga::Object)
+          target = table_definition.context[target]
+        end
         if target.nil?
           raise ArgumentError, "Unknown index target: #{@target.inspect}"
         end
+        index = table.column(@name)
+        if index
+          return index if same_index?(table_definition, index, target)
+          if @options.delete(:force)
+            index.remove
+          else
+            raise ArgumentError,
+                  "the same name index column with " +
+                  "different target or options is " +
+                  "already defined: #{target.inspect}(#{@options.inspect}): " +
+                  "#{index.inspect}"
+          end
+        end
         index = table.define_index_column(@name,
                                           target.table,
                                           @options)
@@ -525,12 +829,14 @@ module Groonga
       end
 
       private
-      def context
-        @options[:context] || Groonga::Context.default
+      def same_index?(table_definition, index, target)
+        context = table_definition.context
+        # TODO: should check column type and other options.
+        index.range == target.table and index.sources == [target]
       end
     end
 
-    class Dumper
+    class Dumper # :nodoc:
       def initialize(options={})
         @options = (options || {}).dup
       end