~ubuntu-branches/ubuntu/trusty/hyperestraier/trusty

<meta name="description" content="Programming Guide of Hyper Estraier" />

<div class="note">Copyright (C) 2004-2006 Mikio Hirabayashi</div>

<div class="note">Last Update: Mon, 11 Sep 2006 21:41:45 +0900</div>

<div class="navi">[<a href="pguide-en.html" hreflang="en">English</a>/<span class="void">Japanese</span>] [<a href="index.ja.html">HOME</a>]</div>

<p>このガイドでは、Hyper EstraierのAPIの詳細な使い方を説明します。<a href="uguide-ja.html">ユーザガイド</a>をまだお読みでない場合は先にそちらに目を通しておいてください。</p>

<p>このガイドではC言語版のコアAPIについて説明しますが、コアAPIを<a href="javanativeapi/">Java</a>や<a href="rubynativeapi/">Ruby</a>や<a href="perlnativeapi/">Perl</a>から呼び出すためのバインディングもあります。また、Hyper EstraierはP2Pアーキテクチャに基づく「<strong>ノードAPI</strong>」も提供しています。ノードAPIについては<a href="nguide-ja.html">P2Pガイド</a>をご覧ください。</p>

<div class="illust"><img src="coreframe.png" width="720" height="450" alt="[framework]" /></div>

<p>文書オブジェクトにキーワードを添付するには、関数 `est_doc_set_keywords' を用います。</p>

 

<dl>

<dt><kbd>void est_doc_set_keywords(ESTDOC *<var>doc</var>, CBMAP *<var>kwords</var>);</kbd></dt>

<dd>`doc' は文書オブジェクトを指定します。`kwords' はキーワードのマップオブジェクトを指定します。マップのキーはキーワードの文字列で、値はそのスコアの10進数表現です。マップオブジェクトは内部的にコピーされます。</dd>

</dl>

 

<p>文書オブジェクトに代替スコアを設定するには、関数 `est_doc_set_score' を用います。</p>

 

<dl>

<dt><kbd>void est_doc_set_score(ESTDOC *<var>doc</var>, int <var>score</var>);</kbd></dt>

<dd>`doc' は文書オブジェクトを指定します。`score' は代替スコアを指定します。負数の場合は代替スコアの既存の設定が無効化されます。</dd>

</dl>

 

<p>文書オブジェクトに添付されたキーワードを取得するには、関数 `est_doc_keywords' を用います。</p>

 

<dl>

<dt><kbd>CBMAP *est_doc_keywords(ESTDOC *<var>doc</var>);</kbd></dt>

<dd>`doc' は文書オブジェクトを指定します。戻り値はキーワードのマップオブジェクトです。マップのキーはキーワードの文字列で、値はそのスコアの10進数表現です。戻り値のオブジェクトの寿命は文書オブジェクトのそれと同期します。</dd>

</dl>

 

<p>検索条件オブジェクトに検索結果からスキップする文書数を設定するには、関数 `est_cond_set_skip' を用います。</p>

 

<dl>

<dt><kbd>void est_cond_set_skip(ESTCOND *<var>cond</var>, int <var>skip</var>);</kbd></dt>

<dd>`cond' は検索条件オブジェクトを指定します。`skip' は検索結果からスキップする文書数を指定します。</dd>

</dl>

 

<dd>`cond' は検索条件オブジェクトを指定します。`options' はオプションを指定します。`ESTCONDSURE' だと全てのN-gramキーを検索します。`ESTCONDUSUAL' はデフォルトですが、N-gramのキーを1個置きで検査します。`ESTCONDFAST' だとN-gramのキーを2個置き、`ESTCONDAGITO' だと3個置きで検査します。`ESTCONDNOIDF' だとTF-IDF法による重みづけを省略します。`ESTCONDSIMPLE' だと検索フレーズを簡便書式のものとして扱います。`ESTCONDROUGH' だと検索フレーズを粗略書式のものとして扱います。`ESTCONDUNION' だと検索フレーズを論理和書式（OR結合）のものとして扱います。`ESTCONDISECT' だと検索フレーズを論理積書式（AND結合）のものとして扱います。`ESTCONDSCFB' だとスコアをフィードバックします（デバッグ専用）。それぞれのオプションはビット和で同時に指定できます。N-gramのキーの検査が省略されればされるほど、検索速度は向上しますが、検索精度は低下します。</dd>

</dl>

 

<p>検索条件オブジェクトに補助インデックスの結果を採用する許可を設定するには、関数 `est_cond_set_auxiliary' を用います。</p>

 

<dl>

<dt><kbd>void est_cond_set_auxiliary(ESTCOND *<var>cond</var>, int <var>min</var>);</kbd></dt>

<dd>`cond' は検索条件オブジェクトを指定します。`min' は補助インデックスが返す結果を採用するための下限該当件数を指定します。0を越えない値を指定すると、補助インデックスは使われません。デフォルトは32件です。</dd>

</dl>

 

<p>検索条件オブジェクトに類似隠蔽における下限類似度を設定するには、関数 `est_cond_set_eclipse' を用います。</p>

<dd>`cond' は検索条件オブジェクトを指定します。`limit' は隠蔽される文書の下限の類似度を0.0から1.0までの値で指定しますが、`ESTECLSIMURL' を加算するとURLを重み付けに使うようになります。`ESTECLSERV' を指定すると類似度を無視して同じサーバの文書を隠蔽します。`ESTECLDIR' を指定すると類似度を無視して同じディレクトリの文書を隠蔽します。`ESTECLSERV' を指定すると類似度を無視して同じファイルの文書を隠蔽します。</dd>

</dl>

 

<p>検索条件オブジェクトに属性重複除去フィルタを設定するには、関数 `est_cond_set_distinct' を用います。</p>

 

<dl>

<dt><kbd>void est_cond_set_distinct(ESTCOND *<var>cond</var>, const char *<var>name</var>);</kbd></dt>

<dd>`cond' は検索条件オブジェクトを指定します。`name' は値が重複してはならない属性の名前を指定します。このフィルタが設定された場合、検索結果の候補の中で重複する属性値を持つものは除外されます。</dd>

</dl>

 

<p>検索条件オブジェクトにメタ検索の対象のマスクを設定するには、関数 `est_cond_set_mask' を用います。</p>

 

<dl>

<dt><kbd>void est_cond_set_mask(ESTCOND *<var>cond</var>, int <var>mask</var>);</kbd></dt>

<dd>`cond' は検索条件オブジェクトを指定します。`mask' は検索対象のマスクを指定します。1は1番目の対象、2は2番目の対象、4は3番目の対象といった2の累乗の値の合計で検索を抑止する対象を指定します。</dd>

<dd>`name' はデータベースのディレクトリ名を指定します。`omode' はオープンモードを指定します。`ESTDBWRITER' ならライタ（書き込みモード）で、`ESTDBREADER' ならリーダ（読み込みモード）です。ライタの場合、ビット和で次のものを指定できます。`ESTDBCREAT' ならデータベースが存在しない場合に新規に作成することを指示し、`ESTDBTRUNC' ならデータベースが既存だった場合にも新規に作りなおすことを指示します。リーダでもライタでも `ESTDBNOLCK' または `ESTDBLCKNB' をビット和で指定することができますが、前者はファイルロックをかけないでデータベースを開くことを指示し、後者はブロックせずにロックをかけることを指示します。その場合は排他制御の責任はアプリケーションが負います。`ESTDBCREAT' に `ESTDBPERFNG' をビット和で加えてデータベースを作成すると、文書の欧文も完全なN-gram法で処理されるようになります。`ESTDBCREAT' に `ESTDBSMALL' をビット和で加えてデータベースを作成すると50000件未満の文書を登録することを想定してインデックスがチューニングされ、`ESTDBLARGE' をビット和で加えてデータベースを作成すると300000件以上の文書を登録することを想定してインデックスがチューニングされ、`ESTDBHUGE' をビット和で加えてデータベースを作成すると1000000件以上の文書を登録することを想定してインデックスがチューニングされ、`ESTDBHUGE2' をビット和で加えてデータベースを作成すると5000000件以上の文書を登録することを想定してインデックスがチューニングされ、`ESTDBHUGE3' をビット和で加えてデータベースを作成すると10000000件以上の文書を登録することを想定してインデックスがチューニングされ、`ESTDBSCVOID' をビット和で加えてデータベースを作成するとスコア情報を破棄するようになり、`ESTDBSCINT' をビット和で加えてデータベースを作成するとスコア情報を32ビットの数値として記録するようになり、`ESTDBSCASIS' をビット和で加えてデータベースを作成するとスコア情報をそのまま保存した上で検索時に調整されないようにマークします。`ecp' はエラーコードを格納する変数へのポインタを指定します。戻り値はデータベースオブジェクトか、エラーの場合は `NULL' です。</dd>

<p>データベースに属性の絞り込み用またはソート用のインデックスを加えるには、関数 `est_db_add_attr_index' を用いる。</p>

 

<dl>

<dt><kbd>int est_db_add_attr_index(ESTDB *<var>db</var>, const char *<var>name</var>, int <var>type</var>);</kbd></dt>

<dd>`db' はライタとして接続したデータベースオブジェクトを指定します。`name' は対象となる属性の名前を指定します。`type' はインデックスのデータ型を指定します。`ESTIDXATTRSEQ' なら多目的のシーケンシャルアクセス用になり、`ESTIDXATTRSTR' なら文字列の絞り込み用になり、`ESTIDXATTRNUM' なら数値型の絞り込み用になります。戻り値は成功なら真、エラーなら偽です。この関数はどの文書を登録するよりも前に呼ぶ必要があります。</dd>

</dl>

 

<dd>`db' はライタとして接続したデータベースオブジェクトを指定します。`max' はフラッシュする語の最大数を指定しますが、0以下ならば全ての索引語がフラッシュされます。戻り値は成功なら真、エラーなら偽です。</dd>

<p>別のデータベースをマージするには、関数 `est_db_merge' を用います。</p>

 

<dl>

<dt><kbd>int est_db_merge(ESTDB *<var>db</var>, const char *<var>name</var>, int <var>options</var>);</kbd></dt>

<dd>`db' はライタとして接続したデータベースオブジェクトを指定します。`name' は別のデータベースのディレクトリ名を指定します。`options' はオプションを指定します。`ESTODCLEAN' は削除された文書の領域を整理することを指示します。戻り値は成功なら真、エラーなら偽です。双方のデータベースを作成した際のオプションは完全に同一である必要があります。取り込んだ文書のURLが既存の文書のURLと同じ場合は、既存の文書は削除されます。</dd>

</dl>

 

<dd>`db' はライタとして接続したデータベースオブジェクトを指定します。`doc' は文書オブジェクトを指定します。文書オブジェクトはURI属性を持っていなければなりません。`options' はオプションを指定します。`ESTPDCLEAN' は上書きされた文書の領域を整理することを指示し、`ESTPDWEIGHT' はインデクシングの際に重み付け属性を静的に適用することを指示します。戻り値は成功なら真、エラーなら偽です。指定された文書オブジェクトのURI属性がデータベース内の既存の文書と一致する場合、既存の方は削除されます。</dd>

<dd>`db' はデータベースオブジェクトを指定します。`id' は登録文書のID番号を指定します。`options' はオプションを指定します。`ESTGDNOATTR' は属性を取得しないことを指示し、`ESTGDNOTEXT' は本文を取得しないことを指示し、`ESTGDNOKWD' はキーワードを取得しないことを指示します。オプションはビット和で同時に指定できます。戻り値は文書オブジェクトか、エラーなら `NULL' です。戻り値のオブジェクトは `est_doc_new' で生成されているので、不要になったら `est_doc_delete' で破棄してください。</dd>

<p>複数のデータベースを検索して検索条件に該当する文書の一覧を取得するには、関数 `est_db_search_meta' を用います。</p>

 

<dl>

<dt><kbd>int *est_db_search_meta(ESTDB **<var>dbs</var>, int <var>dbnum</var>, ESTCOND *<var>cond</var>, int *<var>nump</var>, CBMAP *<var>hints</var>);</kbd></dt>

<dd>`dbs' はデータベースオブジェクトを要素とした配列を指定します。`dbnum' はその配列の要素数を指定します。`cond' は検索条件オブジェクトを指定します。`nump' は戻り値の配列の要素数を格納する変数へのポインタです。`hints' は各検索語に該当する文書数を格納するマップオブジェクトを指定しますが、`NULL' なら無視されます。否定条件の中の語の該当数は負数になります。マップ内の空文字列のキーには全体の該当数が関連づけられます。戻り値は該当した文書を格納したデータベースのインデックスと文書IDを交互に要素とする配列です。この関数は決してエラーになりません。もし該当する文書がない場合にも、空の配列が返されます。戻り値の領域は `malloc' で生成されているので、不要になったら `free' で破棄してください。</dd>

</dl>

 

<dd>`db' はデータベースオブジェクトを指定します。`size' はインデックス用のキャッシュメモリの最大サイズを指定します。デフォルトは64MBです。負数を指定すると、現状の設定を変更しません。`anum' は文書の属性用のキャッシュのレコード数を指定します。デフォルトは8192個です。負数を指定すると、現状の設定を変更しません。`tnum' は文書のテキスト用のキャッシュのレコード数を指定します。デフォルトは1024個です。負数を指定すると、現状の設定を変更しません。`rnum' は出現結果用のキャッシュのレコード数を指定します。デフォルトは256個です。負数を指定すると、現状の設定を変更しません。</dd>

<p>検索結果が得られたら、あとはそれに含まれる個々の文書を取り出してから表示します。<code>est_db_get_doc</code>はIDに対応した文書オブジェクトを取り出す関数です。既に削除した文書がヒットすることもあるので、その場合には<code>NULL</code>が返されます。<code>NULL</code>の場合は単に無視して次の周回に進みます。<code>est_doc_get_attr</code>は属性を取得する関数です。<code>est_doc_get_texts</code>は本文のリストを取得する関数です。この関数の戻り値は、QDBMのcabin.hが提供するリストオブジェクトです。<code>cblistnum</code>関数で要素の数を得たり、<code>cblistval</code>関数で特定の番号の要素を取り出すことができます。この例では、取り出した属性や本文の値をそのまま画面に出力しています。</p>

<p>Hyper Estraierのデータベースは、ファイルロックによって保護されます。読み込みモードで接続された場合は共有ロックがかかり、書き込みモードで接続された場合は排他ロックがかかります。したがって、読み込みモード同士であれば複数のプロセスが同じデータベースを同時に開くことができますが、書き込みモードで接続できるのは一つのデータベースに対して一つのプロセスだけです。読み込みモードの場合、複数のプロセスが同一のデータベースを開くだけでなく、読み込みモードでデータベースを開いたプロセスを<code>fork</code>させることもできます。</p>

 

<p>書き込みモードであっても読み込みモードであっても、同一プロセス内で同一のデータベースに対する複数のコネクションを生成することはできません。マルチスレッドのプログラムにおいて複数のスレッドでデータベースを処理したい場合は、スレッド間でコネクションを共有するようにしてください。なお、コアAPIの各関数はリエントラントですが、コネクションはマルチスレッドセーフではありませんので、mutexで各コネクションを保護するようにしてください。</p>

<p>実は、このガイドで紹介した以外にも関数がたくさん提供されています。それらはちょっと使い方が難しい、いわばハッカー用のAPIです。興味を持たれた方は、<code>estraier.h</code>を覗いてみてください。</p>

<p>現状ではHyper EstraierのソースパッケージにはJavaとRubyとPerlの言語バインディングが収録されていますが、それらはC言語のスレッドAPIをベースとして実装されています。したがって、並列性の性質はスレッドAPIと同様になります。</p>