"Fossies" - the Fresh Open Source Software Archive

Member "groonga-12.0.5/doc/README" (30 Jun 2022, 24386 Bytes) of package /linux/misc/groonga-12.0.5.tar.gz:

    1 全文検索ライブラリGroonga
    2 =========================
    3 
    4 Groonga は組み込み型の全文検索エンジンライブラリです。DBMSやスクリプト言語処理
    5 系等に組み込むことによって、その全文検索機能を強化することができます。また、リ
    6 レーショナルモデルに基づくデータストア機能を内包しており、Groonga単体でも高速
    7 なデータストアサーバとして使用することができます。
    8 
    9 特徴
   10 ----
   11 
   12 ■全文検索方式
   13 
   14 転置索引型の全文検索エンジンです。転置索引は圧縮されてファイルに格納され、検索
   15 時のディスク読み出し量を小さく、かつ局所的に抑えるように設計されています。用途
   16 に応じて以下の索引タイプを選択できます。
   17 
   18  ・ 転置文書索引
   19 
   20     語が出現する文書番号のリストを索引に格納します。索引サイズが
   21     小さく、索引の更新が非常に高速です。ただし、フレーズ検索時に
   22     フォルスドロップが発生する可能性があります。タグ検索など、フ
   23     レーズ検索が不要な用途に特に適しています。
   24 
   25  ・ 完全転置索引
   26 
   27     語が出現する文書番号、および文書内での出現位置の完全なリスト
   28     を格納します。高精度な検索が実現できます。
   29 
   30  ・ 段落情報つき転置索引
   31 
   32     語が出現する文書とその文書内での段落番号も索引に格納します。
   33     段落単位での高精度な検索が実現できます。
   34 
   35  ・ 重み情報つき転置索引
   36 
   37     語が出現する文書とその文書内での重要度(フォントサイズなど)の
   38     情報も索引に格納します。XML/HTMLなどのタグつき文書を対象とす
   39     る高精度な検索が実現できます。
   40 
   41 ■トークナイズ方式
   42 
   43 トークナイズ(検索対象の文書を語に分解する)処理の方式は、用途に応じて選択するこ
   44 とができます。ビルトインのトークナイザとしては、形態素解析
   45 (mecab),n-gram(unigram,bigram,trigram),空白区切りが用意されています。またユー
   46 ザが作成した共有ライブラリ形式のトークナイザモジュールを実行時に組み込んで使う
   47 ことができます。
   48 
   49 ■組み込み型
   50 
   51 DBMSやスクリプト言語処理系等への組み込みやすさを重視しています。
   52 
   53 Groongaはそれ自身もデータストア機能を備えていますが、必要な部品のみを選択して
   54 利用することができます。したがって、あらかじめデータストア機能を備えているDBMS
   55 に組み込む場合は転置索引機能のみを利用し、言語処理系に組み込む場合には必要に応
   56 じてデータストア機能も含めて利用する、といった柔軟な構成を選択することができま
   57 す。
   58 
   59 転置索引を含めたデータストアのオブジェクトは、複数のスレッドおよび複数のプロセ
   60 スで共有することができます。また、検索処理は他の処理との排他制御を挟むことなく
   61 実行できます。したがって様々なスレッドモデル・プロセスモデルのシステムに、その
   62 同時実行性能を妨げることなく組み込むことができます。
   63 
   64 ■即時更新
   65 
   66 転置索引を含めたデータストアオブジェクトは、検索処理と同時に更新(追加/削除)処
   67 理を実行することができます。更新した内容は、即座に検索結果に反映されます。頻繁
   68 に内容が更新される文書に対して、常に最新の検索結果を返したい用途に適していま
   69 す。
   70 
   71 ■高速大容量
   72 
   73 Groongaは検索処理と更新処理のどちらも高速に実行できるように、また、大量の検索
   74 要求が集中するサーバ用途で性能を発揮できるように設計されています。具体的には、
   75 一つのオブジェクトに対して、(それが更新処理と同時であっても)複数のスレッドまた
   76 はプロセスが同時に参照可能としています。ただし、一つのオブジェクトに対する更新
   77 処理は同時に一つまでしか実行できません。
   78 
   79 また、二次記憶への読み書きをバッファリングすることで、実メモリサイズを超える大
   80 容量の文書でも急激に性能を低下させずに処理可能となっています。
   81 
   82 ■データストア機能
   83 
   84 Groongaはリレーショナルモデルに基づくデータストア機能をもっています。データス
   85 トアは、レコードの集まりであるテーブル、テーブルの集まりであるデータベースから
   86 構成されます。テーブルには任意数のカラムを定義することができます。全文検索に用
   87 いる転置索引もテーブルとカラムの組み合わせによって実現されます。適宜必要なカラ
   88 ムを追加することによって、本文以外の書誌情報による絞り込みや分類・ソートなどの
   89 機能を自由に表現することができます。
   90 
   91 テーブルは、主キー管理方式によって以下の3種類から選択できます。
   92 
   93  ・ ハッシュテーブル
   94 
   95     ハッシュテーブルで主キーを管理します。キーと完全一致するレコー
   96     ドを非常に高速に検索することができます。
   97 
   98  ・ パトリシアトライ
   99 
  100     ハッシュテーブルに比べて完全一致検索の速度がやや遅いですが、
  101     前方一致検索・共通接頭辞探索などの検索が行えます。またカーソ
  102     ルを用いてキーの昇降順にレコードを取り出すことができます。
  103 
  104  ・ 主キーなし
  105 
  106     主キーの存在しないテーブルを管理します。レコードはID(識別子)
  107     によって識別します。
  108 
  109 いずれの種類のテーブルも、永続型と一時型の2種類を選択できます。永続型のテーブ
  110 ルは、ファイルに保存され、複数のプロセスで共有することができます。一時型のテー
  111 ブルはメモリ上のみに存在し、プロセスの終了と共に破棄されます。
  112 
  113 ■動作環境
  114 
  115 Linux(x86-64)を主要な対象として開発しています。
  116 
  117 Windows-XP以降, Mac OS 10.*, FreeBSD, Solarisも将来的にサポートする予定です。
  118 
  119 ■ライセンス
  120 
  121 Groongaはフリーソフトウェアです。あなたは、 Free Software Foundationが公表した
  122 GNU Lesser General Public License 2.1が定める条項に従って本プログラムを再頒布
  123 または変更することができます。
  124 
  125 Groongaは有用とは思いますが、頒布にあたっては、市場性及び特定目的適合性につい
  126 ての暗黙の保証を含めて、いかなる保証も行ないません。詳細については GNU Lesser
  127 General Public License 2.1をお読みください。
  128 
  129 ■Sennaとの関係
  130 
  131 GroongaはSennaの後継プロジェクトです。Sennaよりも柔軟性に優れたソフトウェアに
  132 するために、APIを一新し、プロジェクト名も改めました。
  133 
  134 Groongaはデータストア機能を備えるなど、Sennaとは機能的に大きく異なるソフトウェ
  135 アのように見えますが、全文検索エンジンとしてのアーキテクチャはSennaの設計をそ
  136 のまま踏襲しています。高い検索性能と更新性能などの特徴はそのまま受け継いでいま
  137 す。
  138 
  139 GroongaはSennaとの互換性はありませんが、GroongaのAPIを組み合わせることによっ
  140 て、Sennaと同等の機能は全て実現することができます。
  141 
  142 API説明
  143 =======
  144 
  145 概要
  146 ----
  147 
  148 Groongaはリレーショナルモデルに基づくデータストア機能を中心としたAPIを提供しま
  149 す。
  150 
  151 データストアを構成する主要なオブジェクトは、db, type, table, column, procの5つ
  152 です。
  153 
  154 dbはtableの集合を管理するオブジェクトです。永続dbと一時dbのいずれかを選択でき
  155 ます。
  156 
  157 tableはレコードの集合を管理するオブジェクトです。dbと同様、永続tableと一時
  158 tableのいずれかを選択できます。tableに含まれるレコードは、そのtableの中で一意
  159 なIDを持ちます。
  160 
  161 tableには複数のcolumnを定義することができます。 columnには名前と型を与えます。
  162 column名はtableの中で一意でなければなりません。型とは、columnの値が納まるべき
  163 範囲を意味します。数値や文字列などの基本的な型をtypeと呼びます。また、定義済み
  164 の他のtableもcolumnの型として指定することができます。この場合、型として指定さ
  165 れたtableのいずれかのレコードがcolumnの値となります。
  166 
  167 int, float, textなどのtypeはdbの初期化時に自動的に定義されます。それ以外にユー
  168 ザが自由にtypeを定義することも可能です。
  169 
  170 ユーザが作成した共有ライブラリの関数を、dbにproc(手続き)として組み込むことがで
  171 きます。 procは、データの更新・検索・トークナイズなどの幾つかの契機で呼び出す
  172 ことができます。
  173 
  174 mecab, unigram, bigram, delimitedなど、トークナイザとして指定可能ないくつかの
  175 procはdbの初期化時に自動的に定義されます。
  176 
  177 type, table, proc, columnはdbの中で一意なIDを持っています。
  178 
  179 3階層のapi
  180 ----------
  181 
  182 Groongaは、QL-API, DB-API, LOW-LEVEL-APIという3階層のAPIを提供しています。その
  183 ほかにsnippet抽出や文字列操作などのいくつかのユーティリティAPIを提供していま
  184 す。
  185 
  186 QL-APIはgql(groonga query language)というクエリ言語を通してdbを操作するための
  187 APIです。QL-APIはDB-APIの関数を使って実装されています。
  188 
  189 DB-APIはtableやcolumn等のデータストアを構成するオブジェクトの個々の操作に対応
  190 するAPIです。QL-APIを使用する場合に比べて同じ処理を記述するのにより多くのステ
  191 ップ数が必要となりますが、QL-APIを使用するよりも高速に処理を実行できます。
  192 DB-APIはLOW- LEVEL-APIの関数を使って実装されています。
  193 
  194 LOW-LEVEL-APIはtableやcolumnの構成要素であるhash tableやpatricia trieなどのデ
  195 ータ構造を直接操作するためのAPIです。LOW-LEVEL-APIを使用した場合、tableや
  196 columnの関係はユーザが管理する必要があります。また複数の更新処理が同時に実行さ
  197 れることを防ぐための排他制御もユーザ側で実行する必要があります。このため、
  198 DB-APIを使用する場合に比べて同じ処理を記述するのにより多くのステップが必要とな
  199 りますが、用途によってはDB-APIを使用するよりも高速に処理を実行できます。
  200 
  201 ■grn_ctx
  202 
  203 ほとんどのAPI関数の第一引数にはgrn_ctxという構造体を渡します。grn_ctx構造体は次の3
  204 つの用途に用いられます。
  205 
  206  ・ エラー情報の通知
  207 
  208     API実行中に発生したエラーのコード(enum型 grn_rcの値)、発生し
  209     た箇所(ソースファイル名,関数名,行番号)、エラーメッセージが
  210     grn_ctx構造体のメンバにセットされます。
  211 
  212  ・ API内部で使用するメモリの管理
  213 
  214     API関数は様々なオブジェクトを返します。オブジェクトには、複数
  215     のスレッド(またはプロセス)で共有可能なものと、grn_ctxに従属す
  216     るものとがあります。検索結果のレコードセットを格納する一時テー
  217     ブルなどは後者です。grn_ctxはこれらの一時的なオブジェクトの消
  218     費するメモリを管理する機能を持っています。検索処理や更新処理
  219     の過程で生成した一時オブジェクトは、個別に解放することも可能
  220     ですし、grn_ctx_fin()を呼び出すことによって一括して解放するこ
  221     ともできます。
  222 
  223  ・ QL処理系の管理
  224 
  225     gql(groonga query language)処理系オブジェクトは一つのgrn_ctx
  226     について一つだけ生成することができます。qlの実行状態は
  227     grn_ctxの内部で管理されます。qlを使用するかどうかはgrn_ctxの
  228     初期化時に選択することができます。
  229 
  230 GroongaのAPI関数は全てリエントラントであり、マルチスレッド環境で安全に動作しま
  231 す。しかし、APIの扱うオブジェクトの中には、複数スレッドで同時に使用可能なもの
  232 と、そうではないものがあります。grn_ctxは後者にあたります。また、複数スレッド
  233 での同時使用が不可能なその他のオブジェクトは、全てgrn_ctxに従属します。マルチ
  234 スレッド環境でGroonga APIを安全に使用するためには、一つのgrn_ctxおよびgrn_ctx
  235 に従属するオブジェクトを、複数のスレッドが同時に使用しない、という制約を守る必
  236 要があります。
  237 
  238 この制約を守るための簡単な手段として、スレッド固有データにgrn_ctxを保存し、ス
  239 レッドとgrn_ctxと1:1に保つという方法が考えられます。多くのアプリケーションでこ
  240 の方法が有効に機能するでしょう。しかし、例えば非常に多くのクライアントからの接
  241 続を同時に受け付けるサーバシステムの中でGroongaを使用する場合には、スレッドと
  242 grn_ctxとを動的に対応づけた方が有利かもしれません。
  243 
  244 grn_ctx構造体は、APIを呼び出すプログラム側であらかじめ領域を確保し初期化してお
  245 く必要があります。 grn_ctxはgrn_ctx_init()関数を使って初期化します。第1引数に
  246 初期化対象であるgrc_ctx構造体へのポインタを指定します。第 2引数には、
  247 GRN_CTX_USE_QL(gql処理系の要否)を指定します。grn_ctx構造体のサイズはおよそ300
  248 バイト前後です。 grn_ctxがエラー報告のみに使用される場合、これ以上のメモリは消
  249 費されません。grn_ctxに従属する一時オブジェクトが生成される都度、内部でメモリ
  250 が確保されます。GRN_CTX_USE_QLを指定した場合、さらに数KByte程度のメモリが確保
  251 されます。 grn_ctx_fin()を呼び出すとgrn_ctxとそれに従属するオブジェクトの消費
  252 するメモリは全て解放されます。
  253 
  254 QL-API
  255 ------
  256 
  257 QL-APIは、gql(groonga query language)を使ってデータストアを操作するためのごく
  258 シンプルなAPI関数です。主な操作は以下の4つだけです。
  259 
  260  ・ gql処理系の初期化
  261  ・ クエリの送信
  262  ・ クエリの実行結果の受信
  263  ・ gql処理系の終了
  264 
  265 ライブラリを組み込んだアプリケーションのプロセス内にgql処理系を生成する方法
  266 と、ネットワーク上に立てられたGroongaサーバに接続して Groongaサーバプロセス内
  267 にgql処理系を生成する方法があります。初期化の手順を除けば、gql処理系がクライア
  268 ントサイド/サーバサイドのどちら側にあっても全く同じインタフェースで操作するこ
  269 とができます。
  270 
  271 現時点でのgqlの実体は、Groongaバインディングを組み込んだR4RS Scheme処理系で
  272 す。Schemeを選択した理由は、
  273 
  274  ・ 処理系のfootprintの小ささ
  275  ・ 構文木へのアクセスの容易さ
  276 
  277 の2点にあります。両者を備えた、ユーザにとってより親しみやすい言語処理系があれ
  278 ばそちらに移行するかもしれません。
  279 
  280 DB-API
  281 ------
  282 
  283 DB-APIは、Groongaデータストアを構成するオブジェクトの個々の操作に対応する関数
  284 を提供します。以下、DB-APIを構成するオブジェクトに沿って説明します。
  285 
  286 ■grn_db
  287 
  288 grn_dbは、tableやcolumnの名前や関係を格納し、ひとまとまりのデータストアとして
  289 管理するオブジェクトです。grn_dbオブジェクトを作成する際に、永続(ファイルに内
  290 容を保存する)、一時(メモリ上のみで管理)のいずれかを選択することができます。一
  291 時dbは複数スレッドで共有して同時に使用できますが、複数プロセスで共有することは
  292 できません。永続dbは複数プロセスおよび複数スレッドで共有して同時に使用すること
  293 ができます。 grn_ctxは一度に一つのgrn_dbのみを使用することができます。grn_ctx
  294 が操作対象とするgrn_dbを切り替えるときには grn_ctx_use()を使用します。複数の
  295 grn_ctxが同一のgrn_dbを使用することができます。あるgrn_ctxを通してgrn_db に加
  296 えられた更新操作は、即座に他のgrn_ctxからも参照可能となります。
  297 
  298 ■grn_type
  299 
  300 データストアに格納する個々の値は、全ていずれかのデータ型に属します。データ型と
  301 は値の範囲を決めるオブジェクトです。grn_typeは、数値や文字列などのデータ型を表
  302 すオブジェクトです。grn_dbを作成すると、以下のgrn_typeが自動的に定義されます。
  303 
  304   Object
  305   Bool
  306   Int8
  307   UInt8
  308   Int16
  309   UInt16
  310   Int32
  311   UInt32
  312   Int64
  313   UInt64
  314   Float
  315   Time
  316   ShortText
  317   Text
  318   LongText
  319   TokyoGeoPoint
  320   WGS84GeoPoint
  321 
  322 上記のgrn_typeの名前は、適宜optionを指定することによって変更することもできま
  323 す。
  324 
  325 ユーザが新たなgrn_typeを定義することができます。grn_typeはgrn_dbの中で一意な名
  326 前をつける必要があります。また、その値をデータストア内で表現するのに必要なbyte
  327 数(可変長ならば最大のbyte数)を与えます。
  328 
  329 ■grn_table
  330 
  331 grn_tableはレコードの集合を表すオブジェクトです。grn_tableに含まれるレコードに
  332 は、そのtableの中で一意なIDを与えられます。そのレコードが削除されない限り、レ
  333 コードのIDが変更されることはありません。削除されたレコードのIDはその後に追加さ
  334 れた別のレコードの IDとして再利用されます。レコードのIDは自動的に払い出され、
  335 ユーザが指定することはできません。ただし、そのtableからレコードが削除されない
  336 限り、レコードIDは tableにレコードを追加した順番(自然数)と一致します。
  337 
  338 ユーザが指定するキーと対応づけてレコードを管理することもできます。キーはレコー
  339 ドと1:1に対応し、tableの中で一意な値でなければなりません。キーには文字列や数値
  340 などの任意のバイト列を使用することができます。キーに使用するデータの範囲はデー
  341 タ型によって与えます。キーに指定できるデータは4Kbyte以下でなければなりません。
  342 (<text>, <longtext>をキーとするtableを定義することはできません)
  343 
  344 tableを作成するときに、キーの管理方式を選択することができます。
  345 
  346  ・ GRN_OBJ_TABLE_HASH_KEY
  347 
  348     ハッシュ表によってキーを管理します。レコードの追加/検索/削除
  349     操作を非常に高速に実行できます。
  350 
  351  ・ GRN_OBJ_TABLE_PAT_KEY
  352 
  353     パトリシアトライによってキーを管理します。
  354     GRN_OBJ_TABLE_HASH_KEYと比較して、レコードの追加/検索/削除操
  355     作の実行はやや遅くなります。前方一致検索・共通接頭辞探索など
  356     の検索が行えます。またカーソルを用いてキーの範囲検索を実行し、
  357     キー値の昇降順にレコードを取り出すことができます。また、
  358     GRN_OBJ_KEY_WITH_SISを合わせて指定した場合、キーの後方一致検
  359     索が可能になります。
  360 
  361  ・ GRN_OBJ_TABLE_NO_KEY
  362 
  363     主キーの存在しないtableを管理します。レコードはIDのみによって
  364     識別可能になります。
  365 
  366 文字列を主キーとするtableの場合は、GRN_OBJ_KEY_NORMALIZEを指定すると、正規化し
  367 た文字列がキーとなります。(符号化方式がUTF8であった場合にはUAX #15 NFKCによっ
  368 て正規化を行います)
  369 
  370 GRN_OBJ_PERSISTENTを指定して作られたtableはその内容がファイルに永続的に保存さ
  371 れます。そうでなければ、tableの内容はメモリ上のみに蓄積されます。
  372 
  373 tableを格納するgrn_dbの永続性と、tableの永続性とは独立です。一時的なgrn_dbの中
  374 に永続的なgrn_tableを作成したり、永続的なgrn_dbの中に一時的なgrn_tableを作成す
  375 ることも可能です。前者の場合は、tableの実体はファイルに保存されますが、その
  376 tableの名前、キーのデータ型、他のtableとの関係などの情報は永続的には保存されま
  377 せん。
  378 
  379 grn_tableには、名前つきtableと無名tableの2種類があります。名前つきtableを作成
  380 するときには、grn_dbの中で一意な名前を与えなければなりません。名前付きtable
  381 は、複数のgrn_ctxで共有することができます。無名tableはgrn_ctxに従属し、他の
  382 grn_ctxから操作することはできません。永続的なtableは必ず名前つきでなければなり
  383 ません。
  384 
  385 ■grn_column
  386 
  387 grn_tableには複数のカラム(grn_column)を作成できます。columnにはtableの中で一意
  388 な名前と、そのcolumnに格納する値が属するデータ型を定義します。
  389 
  390 データ型にはgrn_typeかgrn_tableを指定します。grn_tableを指定した場合は、外部参
  391 照キーとして機能します。
  392 
  393 grn_columnには、単一の値を格納するものと値の集合を格納するものがあります。値の
  394 集合を格納するcolumnには以下の種類があります。
  395 
  396  ・ GRN_OBJ_COLUMN_ARRAY
  397 
  398     値の配列を格納します。
  399 
  400  ・ GRN_OBJ_COLUMN_SECTIONS
  401 
  402     重み情報つきの値の配列を格納します。配列の要素毎に32bit符号な
  403     し数値を付与することができます。
  404 
  405  ・ GRN_OBJ_COLUMN_POSTINGS
  406 
  407     keyとvalueのペアの集合を値として格納します。
  408 
  409  ・ GRN_OBJ_COLUMN_INDEX
  410 
  411     転置索引エントリを値として格納します。この種類のcolumnを使っ
  412     て高速な全文検索が実行できます。GRN_OBJ_WITH_SECTION を指定し
  413     た場合には、段落情報も合わせて格納します。
  414     GRN_OBJ_WITH_WEIGHTを指定した場合には、重み情報も合わせて格納
  415     します。GRN_OBJ_WITH_POSITIONを指定した場合は出現位置リストも
  416     合わせて格納します。
  417 
  418 GRN_OBJ_COLUMN_INDEX以外のcolumnには、GRN_OBJ_COMPRESS_ZLIBあるいは
  419 GRN_OBJ_COMPRESS_LZOを指定することによってデータを圧縮して保存することができま
  420 す。
  421 
  422 ■grn_proc
  423 
  424 grn_procは、tableやcolumnに対する参照/更新などの幾つかの契機で呼び出される手続
  425 きに対応するオブジェクトです。転置索引を更新/検索する時に、対象の文字列をトー
  426 クンに分解するトークナイザもgrn_procとして定義されます。grn_dbを作成すると、以
  427 下のトークナイザprocが自動的に定義されます。
  428 
  429  ・ TokenDelimit : 空白で区切られた文字列をトークンとする
  430  ・ TokenUnigram : unigram(1文字を1トークンとする)
  431  ・ TokenBigram : bigram(2文字の文字列要素をトークンとする)
  432  ・ TokenTrigram : trigram(3文字の文字列要素をトークンとする)
  433  ・ TokenMecab : 形態素解析器mecabで解析した形態素をトークンとする
  434 
  435 これ以外にも、ユーザが定義した関数をgrn_procとして組み込むことができます。ユー
  436 ザがgrn_procを定義する場合には、init, next, finという3つの契機で呼ばれる関数を
  437 用意します。initは手続きの実処理の最初に一度だけ呼び出されます。nextは必要に応
  438 じて複数回呼び出されます。finは最後に一度だけ呼び出されます。それぞれの関数が
  439 受け取る引数は、procの呼び出し契機毎に異なります。