groongaには、Cのライブラリとして使用する方法と、groonga実行ファイルを通して使用する方法があります。本チュートリアルでは、groonga実行ファイルを使用する方法について説明します。groonga実行ファイルを使って、データベースの作成・操作・サーバの起動・サーバへの接続などの操作が行えます。
以下のようなコマンドを実行すると、データベースを新規に作成することができます。
書式:
groonga -n DB_PATH_NAME
-nオプションは、データベースを作ることを指示します。DB_PATH_NAMEには、新しく作成するデータベースのパスを指定します。指定されたパスが既に存在するときはコマンドが失敗するので注意してください。
上記コマンドは、データベースを作成してから、コマンドの入力を受け付ける対話モードに入ります。Ctrlキーを押しながらdキーを押すと、対話モードから抜けることができます。
実行例:
% groonga -n /tmp/tutorial.db
> Ctrl-d
%
書式:
groonga DB_PATH_NAME [COMMAND]
操作対象のデータベースのパスをDB_PATH_NAMEに指定します。
COMMAND が指定された場合、COMMAND を実行した後、実行結果を返します。指定されなかった場合には、対話モードに入ります。対話モードでは、標準入力からコマンドを読み込み、順次実行します。本チュートリアルでは、対話モードを主に使用します。
Let's try to see the status of a groonga process by using a status command.
実行例:
% groonga -n /tmp/groonga-databases/introduction.db
> status
[[0,1322616280.40348,0.000158121],{"alloc_count":127,"starttime":1322616279,"uptime":1,"version":"1.2.8-9-gbf05b82","n_queries":0,"cache_hit_rate":0.0,"command_version":1,"default_command_version":1,"max_command_version":2}]
以上のように、コマンドの実行結果は基本的にjson形式の配列として返却されます。配列の先頭には、エラーコードや実行時間などの情報が入ります。2番目の要素には、コマンドによって指定された操作の実行結果が入ります。
データベースを操作するコマンドには、以下の書式で引数を与えます。:
Form_1: COMMAND VALUE_1 VALUE_2 ..
Form_2: COMMAND --NAME_1 VALUE_1 --NAME_2 VALUE_2 ..
書式1では値を適切な順番で渡す必要があります。このような引数は、位置によって値の意味が決まるため、位置固定引数などと呼ばれることもあります。
書式2では値を名前と一緒に渡します。そのため、任意の順序で引数を指定することができます。このような引数は、名前付き引数やキーワード引数と呼ばれることもあります。
空白や特殊な記号「"'()」を含む値を指定したいときは、シングルクォート(')かダブルクォート(")で値を囲むようにしてください。
詳しくは、 groonga実行ファイル のコマンドの項を参考にしてください。
- status
- shows status of a groonga process.
- table_list
- shows a list of tables in a database.
- column_list
- shows a list of columns in a table.
- table_create
- adds a table to a database.
- column_create
- adds a column to a table.
- select
- searches records from a table and shows the result.
- load
- inserts records to a table.
table_create コマンドを使用してテーブルを作成します。
groongaのテーブルには基本的に主キーが必要であり、テーブルを作成する際には型と格納方法も併せて指定する必要があります。
型については後で説明するので、ここではデータの種類を表しているものという程度に考えてください。主キーの格納方法は、主キーを条件とする検索にかかる時間や、前方一致検索の可否などを左右します。こちらも後で説明します。
それでは、'Site'という名前のテーブルを作成してみましょう。主キーについては、型がShortTextで格納方法はHASHとしています。
実行例:
> table_create --name Site --flags TABLE_HASH_KEY --key_type ShortText
[[0,1322616280.60791,0.01234375],true]
select コマンドを用いて、テーブルの中身を表示することができます。
実行例:
> select --table Site
[[0,1322616280.82196,0.000451873],[[[0],[["_id","UInt32"],["_key","ShortText"]]]]]
selectにテーブル名のみを指定すると、指定したテーブルの中身を10件まで表示します。実行結果の[0]はテーブルに含まれるレコードの数を示しています。今回は何も登録されていないため0件です。レコード数の次に表示されている配列はテーブルの構成を示しています。["_id","Uint32"]はUInt32型の値を持つ'_id'という名前のカラム、["_key","ShortText"]はShortText型の値を持つ'_key'という名前のカラムをそれぞれ表しています。
table_createコマンドで作成したテーブルには、最初から'_id', '_key'という2つのカラムがあります。'_id'はgroongaが自動的に付与するID番号が格納されるカラムです。'_key'は主キーが格納されるカラムです。これらのカラム名を変更することはできません。
column_create コマンドを用いて、カラムを作成することができます。
Let's add a column of ShortText to store titles. You may give a descriptive name 'title' to the column.
実行例:
> column_create --table Site --name title --flags COLUMN_SCALAR --type ShortText
[[0,1317212712.91734,0.077833747],true]
> select --table Site
[[0,1317212713.19572,0.000121119],[[[0],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]]]]]
COLUMN_SCALAR は'comment'を通常のカラムとして作成することを指示しています。
そろそろ全文検索の使い方について見ていきましょう。
Groonga uses an inverted index to provide fast full text search. So, the first step is to create a lexicon table which stores an inverted index, also known as postings lists. The primary key of this table is associated with a vocabulary made up of index terms and each record stores postings lists for one index term.
以下の例では、'Terms'という名前のテーブルを転置インデックスとして作成しています。索引語を格納するため、主キーの型はShortTextです。
実行例:
> table_create --name Terms --flags TABLE_PAT_KEY|KEY_NORMALIZE --key_type ShortText --default_tokenizer TokenBigram
[[0,1317212713.39679,0.092312046],true]
この実行例には、多くのパラメータが指定されています。本チュートリアルでは、これらをすべて理解する必要はありません。以下に簡単な説明を記しますが、読み飛ばしてもらってかまいません。
The 'TABLE_PAT_KEY' flag specifies to store index terms in a patricia trie. The 'KEY_NORMALIZE' flag specifies to normalize index terms. In this example, both flags are validated by using a '|'. The 'default_tokenizer' parameter specifies a method for tokenizing text. This example specifies 'TokenBigram' that is generally called 'N-gram'.
The second step is to create an index column, which allows you to search records from its associated column. That is to say this step specifies which column needs an index.
それでは、Siteテーブルのtitleカラムを全文検索の対象とするべく、インデックス型のカラムを作成してみましょう。
実行例:
> column_create --table Terms --name blog_title --flags COLUMN_INDEX|WITH_POSITION --type Site --source title
[[0,1317212713.68994,0.19739078],true]
Siteテーブルのtitleカラムを検索対象とする、'blog_title'という名前のインデックス型カラムをTermsテーブルに作成しました。インデックス対象となるテーブルをtypeに、インデックス対象となるカラムをsourceに指定します。実行例のflagsのCOLUMN_INDEX|WITH_POSITIONという値は、索引語の位置情報を格納するインデックス型のカラムであることを示しています。通常の全文検索インデックスでは、COLUMN_INDEX|WITH_POSITIONを指定してください。索引語の位置情報を格納する意味については、本チュートリアルでは触れません。
load コマンドを使用します。loadコマンドでは、json形式で受け取ったデータをテーブルに格納します。
以下の例では9つのレコードをSiteテーブルに格納します。
実行例:
> load --table Site
> [
> {"_key":"http://example.org/","title":"This is test record 1!"},
> {"_key":"http://example.net/","title":"test record 2."},
> {"_key":"http://example.com/","title":"test test record three."},
> {"_key":"http://example.net/afr","title":"test record four."},
> {"_key":"http://example.org/aba","title":"test test test record five."},
> {"_key":"http://example.com/rab","title":"test test test test record six."},
> {"_key":"http://example.net/atv","title":"test test test record seven."},
> {"_key":"http://example.org/gat","title":"test test record eight."},
> {"_key":"http://example.com/vdw","title":"test test record nine."},
> ]
[[0,1317212714.08816,2.203527402],9]
selectコマンドで、データが入っていることを確認しましょう。
実行例:
> select --table Site
[[0,1317212716.49285,0.000270908],[[[9],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"],[2,"http://example.net/","test record 2."],[3,"http://example.com/","test test record three."],[4,"http://example.net/afr","test record four."],[5,"http://example.org/aba","test test test record five."],[6,"http://example.com/rab","test test test test record six."],[7,"http://example.net/atv","test test test record seven."],[8,"http://example.org/gat","test test record eight."],[9,"http://example.com/vdw","test test record nine."]]]]
データの準備もできたので全文検索を試してみたいところですが、その前に、'_id'カラムと'_key'カラムを用いた検索を行ってみましょう。これらのカラムは値を指定すればレコードが一意に決まります。
selectコマンドにおいて、queryパラメータを用いるとデータの検索を行うことができます。
実行例:
> select --table Site --query _id:1
[[0,1317212716.69871,0.000308514],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"]]]]
queryパラメータに与えた「_id:1」というのは、'_id'という名前のカラムに'1'という値が入っているレコードを検索する、という意味です。
_keyでも検索してみましょう。
実行例:
> select --table Site --query "_key:\"http://example.org/\""
[[0,1317212716.9005,0.000478343],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"]]]]
queryパラメータに与えた「_key:"http://example.org/"」というのは、'_key'という名前のカラムに'"http://example.org/"'という値が入っているレコードを検索する、という意味です。
queryパラメータでは、インデックスを用いた全文検索を行うこともできます。
実行例:
> select --table Site --query title:@this
[[0,1317212717.10303,0.000581287],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"]]]]
queryパラメータに与えた「title:@this」は、'title'という名前のカラムに'this'という文字列が含まれているレコードを検索する、という意味を持ちます。この例では1つのレコードが検索条件に該当しています。転置インデックスを作成するときにKEY_NORMALIZEという値を指定したため、大文字と小文字の違いが吸収されていることに注意してください。
selectコマンドには、match_columnsというパラメータが存在します。このパラメータはデフォルトで検索対象にするカラムを指定するもので、カラム名を指定しない検索条件にのみ適用されます。[1]_
match_columnsパラメータに'title'、queryパラメータに'this'という文字列を指定すると、上記のクエリと同じ結果を得ることができます。
実行例:
> select --table Site --match_columns title --query this
[[0,1317212717.30596,0.000716439],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"]]]]
selectコマンドにおいて、output_columnsパラメータを用いることで、検索結果に含めるカラムを指定することができます。複数のカラムを指定する場合は、カンマ(,)区切りで指定します。
実行例:
> select --table Site --output_columns _key,title,_score --query title:@test
[[0,1317212717.50916,0.00060758],[[[9],[["_key","ShortText"],["title","ShortText"],["_score","Int32"]],["http://example.org/","This is test record 1!",1],["http://example.net/","test record 2.",1],["http://example.com/","test test record three.",2],["http://example.net/afr","test record four.",1],["http://example.org/aba","test test test record five.",3],["http://example.com/rab","test test test test record six.",4],["http://example.net/atv","test test test record seven.",3],["http://example.org/gat","test test record eight.",2],["http://example.com/vdw","test test record nine.",2]]]]
この例では、「_score」という名前のカラムを含む3つのカラムを指定しています。「_score」という名前のカラムはgroongaの検索結果に含まれるカラムです。このカラムには、全文検索の条件に合致する文書ほど高い数値が入ります。
selectコマンドにおいて、offset,limitパラメータを用いることで、検索結果から指定された範囲のみを表示することができます。大量の検索結果をページで分けて、1ページ分のみを表示したい場合に有用です。
offsetパラメータには、検索結果を返す始点を指定します。1件目から結果を返す場合には、0を指定します。limitパラメータには、検索結果の表示件数を指定します。
実行例:
> select --table Site --offset 0 --limit 3
[[0,1317212717.71574,0.000238544],[[[9],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"],[2,"http://example.net/","test record 2."],[3,"http://example.com/","test test record three."]]]]
> select --table Site --offset 3 --limit 3
[[0,1317212717.91925,0.00023617],[[[9],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[4,"http://example.net/afr","test record four."],[5,"http://example.org/aba","test test test record five."],[6,"http://example.com/rab","test test test test record six."]]]]
> select --table Site --offset 7 --limit 3
[[0,1317212718.12219,0.00019999],[[[9],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[8,"http://example.org/gat","test test record eight."],[9,"http://example.com/vdw","test test record nine."]]]]
selectコマンドにおいて、sortbyパラメータを用いることで、検索結果を並び替えることができます。
sortbyパラメータにカラム名を指定することで、そのカラムの値で昇順にソートします。また、カラム名の前にハイフン(-)を付けることで、降順にソートすることもできます。
実行例:
> select --table Site --sortby -_id
[[0,1317212718.32565,0.000385755],[[[9],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[9,"http://example.com/vdw","test test record nine."],[8,"http://example.org/gat","test test record eight."],[7,"http://example.net/atv","test test test record seven."],[6,"http://example.com/rab","test test test test record six."],[5,"http://example.org/aba","test test test record five."],[4,"http://example.net/afr","test record four."],[3,"http://example.com/","test test record three."],[2,"http://example.net/","test record 2."],[1,"http://example.org/","This is test record 1!"]]]]
出力カラムの指定で紹介した「_score」カラムは、ソートの条件としても使うことができます。
実行例:
> select --table Site --query title:@test --output_columns _id,_score,title --sortby _score
[[0,1317212718.5331,0.000667311],[[[9],[["_id","UInt32"],["_score","Int32"],["title","ShortText"]],[1,1,"This is test record 1!"],[2,1,"test record 2."],[4,1,"test record four."],[3,2,"test test record three."],[9,2,"test test record nine."],[8,2,"test test record eight."],[7,3,"test test test record seven."],[5,3,"test test test record five."],[6,4,"test test test test record six."]]]]
ソートするカラム名を複数指定したい場合は、カンマ(,)区切りで指定します。複数のカラムを指定した場合、最初のカラムで同一の値のレコードがあった場合に、次のカラムの値でソートさせることができます。
実行例:
> select --table Site --query title:@test --output_columns _id,_score,title --sortby _score,_id
[[0,1317212718.73819,0.00069225],[[[9],[["_id","UInt32"],["_score","Int32"],["title","ShortText"]],[1,1,"This is test record 1!"],[2,1,"test record 2."],[4,1,"test record four."],[3,2,"test test record three."],[8,2,"test test record eight."],[9,2,"test test record nine."],[5,3,"test test test record five."],[7,3,"test test test record seven."],[6,4,"test test test test record six."]]]]
脚注
[1] | 現在のバージョンでは、全文検索インデックスが存在する場合にのみ、match_columnsパラメータを利用することができます。通常のカラムでの絞り込みには利用できません。 |