groongaデータベースAPIについて概説

groongaにおいて、データベースを扱うためのAPI群について概説します。
groongaは、RDBMSでいうところのテーブル・カラムを扱うAPIを提供します。
テーブルは、内部的にハッシュテーブルもしくはパトリシアトライが基となっています。

それぞれの要素について、どのような操作が行えるかを説明します。

grn_hash

grn_hashとは、以下の操作を行えるAPI群です。

• 任意のkeyを指定したデータ保存
• 任意のkeyを指定したデータ取得
• 任意のkeyを指定したデータ削除
• カーソルを用いた、全てのkey/valueの取得・設定・削除

内部の実装は、ハッシュテーブルです。
メモリ上に作成することも、ファイルとして作成することもできます。

いわゆる*DBMと同等のことができます。
Tokyo CabinetでいうところのTCHDBですね。

grn_pat

grn_patとは、以下の操作を行えるAPI群です。

• 任意のkeyを指定したデータ保存
• 任意のkeyを指定したデータ取得
• 任意のkeyを指定したデータ削除
• 与えられた文字列内で、最左最長一致するkeyの検索
• 与えられた文字列と前方一致するkey群の検索
• 与えられた文字列と後方一致するkey群の検索
• 与えられた文字列と前方最長一致検索するkeyの検索
• カーソルを用いた、全てのkey/valueの取得・設定・削除

内部の実装は、パトリシアトライです。
メモリ上に作成することも、ファイルとして作成することもできます。

groongaは、全文検索を目的に開発されています。
Sennaの時代から、全文検索の語彙表を表現するためにパトリシアトライを用いてきました。
ハッシュテーブルとは異なり、keyの前方一致検索や前方最長一致検索を行うことができます。

内部的に半無限文字列をパトリシアトライに追加するオプションがあります。
このオプションを付与すると、
keyの前方一致検索だけでなく、後方一致検索を行うことができます。

「与えられた文字列内で、最左最長一致するkeyの検索」を用いることによって、
はてなキーワードの自動リンク付与のような処理を行うことができます。

grn_table/grn_column

grn_tableとは、以下の操作を行えるAPI群です。

• 任意のkeyを指定したレコード検索・作成・削除
• 任意のkeyと前方最長一致するレコード検索・作成・削除(オプションによる)
• カーソルを用いた、全てのレコードの取得・削除
• 任意の名前と型を持ったgrn_columnの作成・取得
• 任意のカラム値を用いたソート・上位n件取得
• 任意の外部参照テーブルのカラム値（多重参照も可）を用いたソート・上位n件取得
• 任意の関数を用いたソート・上位n件取得
• 任意のカラム値を用いたグループ化
• 任意の外部参照テーブルのカラム値（多重参照も可）を用いたグループ化
• 任意の関数を用いたグループ化
• テーブル間での和・差テーブルの取得
• 全データの削除
• レコード数の取得

grn_tableの実装は、grn_hashもしくはgrn_patを拡張する形で行われています。
メモリ上に作成することも、ファイルとして作成することもできます。

grn_columnとは、以下の操作を行えるAPI群です。

• 値の取得・設定
• grn_columnが転置インデックス型の場合、インデックスの更新
• 属するgrn_tableの取得

grn_columnの内部の実装は、固定長配列・可変長配列・grn_table・転置インデックスのいずれかです。
メモリ上に作成することも、ファイルとして作成することもできます。
たとえば、ファイルとして作成されたgrn_tableに、メモリ上の一時的なgrn_columnを付与することができます。

grn_tableとgrn_columnについては、
RDBMSでのテーブルを想定していただければイメージがわきやすいと思います。

テーブルにおいて、１つのレコードはただ１つの値を保持することができます(key-value store的な感じ)。
また、１つのレコードは、複数のカラム(grn_col)を持つことができます(RDBMS的な感じ）。
key-value storeの１つのkey-valueペアに対して、カラムが複数個くっついているイメージを持ってください。

grn_hashやgrn_patとは異なり、
ソートやグループ化、集合演算などを行うことができます。
その場合、任意のカラムや関数でソートやグループ化を行えます。

grn_columnは、他のgrn_tableのレコードへの参照保持することができます。
いわゆる外部参照キーを保持するイメージを持ってください。
外部参照先のgrn_tableのカラムを用いたソートやグループ化を高速に行うことができます。

grn_columnは、転置インデックスを保持することができます。
転置インデックスを用いて、高速な全文検索を行うことができます。
詳細については、別稿で述べます。

groongaのmemcachedバイナリプロトコル互換実装では、
flagsやexptime、casなどの値を保存するためにgrn_columnを用いています。

サンプルコード

groongaパッケージのexampleディレクトリに、kv.cというソースコードがあります。
これは、上記のそれぞれのAPIを用いて、
key-valueの保存・参照を100万回行うサンプルプログラムです。

kvを起動すると、以下のようにusageが表示されます。

usage: kv dbpath [put|get] [col|table|hash|pat|ql] [value_size]

第１引数に、データベース名を指定します。
第２引数に、データの保存ならput、データの取得ならgetを指定します。getの場合には、１度putを行う必要があります。
第３引数に、groongaが持つAPIセットのうちどのAPIセットを用いるかを指定します。
第４引数に、保存する値のサイズを指定します。

このサンプルコードを読めば、
上記の構成部品についてごく基本的な使い方をマスターすることができます。

まとめ

groongaでは、さまざまなデータ構造に対応したAPIセットがあります。

• keyをハッシュテーブルで保持するgrn_hash
• keyをパトリシアトライで保持するgrn_pat
• keyã‚’grn_hash/grn_patで保持し、任意個のgrn_columnを持つことができるgrn_table

これらのデータ構造は、メモリ上に作成することもファイルに保存することも可能です。

grn_hashは気軽なkey-value storeとして用いることができます。
grn_patはkeyの前方一致・後方一致が行えるkey-value storeとして用いることができます。
grn_tableは、grn_hash/grn_patを拡張したものです。ただ１つしか持てないvalueに加えて、複数個のcolumnを保持することができます。
またgrn_tableは、grn_hashやgrn_patにないソートやグループ化機能を備えます。