4.1. 基本的な操作#
Groongaには、Cのライブラリとして使用する方法と、groonga実行ファイルを通して使用する方法があります。本チュートリアルでは、groonga実行ファイルを使用する方法について説明します。groonga実行ファイルを使って、データベースの作成・操作・サーバの起動・サーバへの接続などの操作が行えます。
4.1.1. データベースの作成#
Groongaユーザへの第一歩はデータベースの作成です。まずは以下の書式をご覧ください。
書式:
groonga -n DB_PATH
-n オプションは、データベースの作成を指示します。DB_PATHは、新しく作成するデータベースのパスを指定します。データベースは複数のファイルによって構成されるため、正確には、データベースの入り口となるファイルのパスとして使用されます。また、データベースを構成する他のファイルについては、DB_PATHがパスのプレフィックスとして使用されます。指定されたパスにファイルが存在しているときは失敗するので注意してください（失敗例: db open failed (DB_PATH): syscall error 'DB_PATH' (ファイルが存在します)。 次の章で、既存のデータベースを開く方法を説明します）。
上記のコマンドは、データベースを作成してから、コマンドの入力を受け付ける対話モードに入ります。Ctrlキーを押しながらdキーを押すと、対話モードから抜けることができます。
実行例:
% groonga -n /tmp/groonga-databases/introduction.db
データベースの作成に成功すれば、/tmp/groonga-databases以下にデータベースを構成するファイルが配置されます。
4.1.2. データベースの操作#
以下の書式は、既存のデータベースを操作する方法を示しています。
書式:
groonga DB_PATH [COMMAND]
DB_PATHには操作対象のデータベースを指定します。指定したデータベースが存在しないときは失敗します。
COMMAND が指定された場合、COMMAND を実行した後、実行結果を返します。指定されなかった場合には、対話モードに入ります。対話モードでは、標準入力からコマンドを読み込み、順次実行します。本チュートリアルでは、対話モードを主に使用します。
それでは、 status コマンドを実行して、Groongaの実行状態を確認してみましょう。
実行例:
% groonga /tmp/groonga-databases/introduction.db
status
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# {
# "alloc_count": 29,
# "starttime": 1696558618,
# "start_time": 1696558618,
# "uptime": 0,
# "version": "2.9.1",
# "n_queries": 0,
# "cache_hit_rate": 0.0,
# "command_version": 1,
# "default_command_version": 1,
# "max_command_version": 3,
# "n_jobs": 0,
# "features": {
# "nfkc": true,
# "mecab": true,
# "message_pack": true,
# "mruby": true,
# "onigmo": true,
# "zlib": true,
# "lz4": true,
# "zstandard": true,
# "kqueue": false,
# "epoll": true,
# "poll": false,
# "rapidjson": false,
# "apache_arrow": true,
# "xxhash": true,
# "blosc": true,
# "bfloat16": true,
# "h3": true,
# "simdjson": true,
# "llama.cpp": true,
# "back_trace": true,
# "reference_count": false
# },
# "apache_arrow": {
# "version_major": 2,
# "version_minor": 9,
# "version_patch": 1,
# "version": "2.9.1"
# },
# "memory_map_size": 2929,
# "n_workers": 0,
# "default_n_workers": 0,
# "os": "Linux",
# "cpu": "x86_64"
# }
# ]
以上のように、コマンドの実行結果は基本的にjson形式の配列として返却されます。配列の先頭には、エラーコードや実行時間などの情報が入ります。2番目の要素には、指示された操作の実行結果が入ります。
4.1.3. コマンドの書式#
データベースを操作するコマンドには、以下の書式で引数を与えます。:
Form_1: COMMAND VALUE_1 VALUE_2 ..
Form_2: COMMAND --NAME_1 VALUE_1 --NAME_2 VALUE_2 ..
書式1では値を適切な順番で渡す必要があります。このような引数は、位置によって値の意味が決まるため、位置固定引数などと呼ばれることもあります。
書式2では値を名前と一緒に渡します。そのため、任意の順序で引数を指定することができます。このような引数は、名前付き引数やキーワード引数と呼ばれることもあります。
空白や特殊な記号（ダブルクォート、シングルクォート、および丸括弧）を含む値を指定したいときは、シングルクォート(')かダブルクォート(")で値を囲むようにしてください。
詳しくは、 groonga 実行ファイル のコマンドの項を参考にしてください。
4.1.4. 主なコマンド#
- status
Groongaプロセスの状態を表示します。
- table_list
データベースに定義されているテーブルのリストを表示します。
- column_list
テーブルに定義されているカラムのリストを表示します。
- table_create
データベースにテーブルを追加します。
- column_create
テーブルにカラムを追加します。
- select
テーブルに含まれるレコードを検索して表示します。
- load
テーブルにレコードを挿入します。
4.1.5. テーブルの作成#
table_create コマンドを使用してテーブルを作成します。
Groongaのテーブルには基本的に主キーが必要であり、テーブルを作成する際には型と格納方法も併せて指定する必要があります。
型には数値や文字列などがあります。ここではデータの種類を表しているものという程度に考えてください。詳細は データ型 に記述されています。主キーの格納方法は、主キーを条件とする検索にかかる時間や、前方一致検索の可否などを左右します。こちらも後で説明します。
それでは、テーブルを作成してみましょう。以下の例では、主キーのあるテーブルを作成します。 name 引数はテーブルの名前を指定します。 flags 引数は主キーの格納方法を指定するために使っています。 key_type 引数は主キーの型を指定します。
実行例:
table_create --name Site --flags TABLE_HASH_KEY --key_type ShortText
# [[0,1337566253.89858,0.000355720520019531],true]
実行結果の第2要素は、操作が成功したことを示しています。
4.1.6. テーブルの表示#
select コマンドを用いて、テーブルの中身を表示することができます。
実行例:
select --table Site
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 0
# ],
# [
# [
# "_id",
# "UInt32"
# ],
# [
# "_key",
# "ShortText"
# ]
# ]
# ]
# ]
# ]
select に table 引数のみを指定すると、指定したテーブルの中身を10件まで表示します。実行結果の[0]はテーブルに含まれるレコードの数を示しています。今回は何も登録されていないため0件です。レコード数の次に表示されている配列はテーブルの構成を示しています。["_id","Uint32"]はUInt32型の値を持つ_idという名前のカラム、["_key","ShortText"]はShortText型の値を持つ_keyという名前のカラムをそれぞれ表しています。
上記の_idカラムと_keyカラムの2つのカラムは必須のカラムです。_idカラムはGroongaが自動的に割り当てるIDを格納します。_keyカラムは主キーを格納します。これらのカラム名を変更することはできません。
4.1.7. カラムの作成#
column_create コマンドを用いて、カラムを作成することができます。
それでは、カラムを作成してみましょう。以下の例では、新しいカラムをSiteテーブルに追加します。 table 引数はテーブルの名前を指定します。 name 引数は新しいカラムの名前を指定します。 type 引数はカラムに格納する値の型を指定します。
実行例:
column_create --table Site --name title --type ShortText
# [[0,1337566253.89858,0.000355720520019531],true]
select --table Site
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 0
# ],
# [
# [
# "_id",
# "UInt32"
# ],
# [
# "_key",
# "ShortText"
# ],
# [
# "title",
# "ShortText"
# ]
# ]
# ]
# ]
# ]
4.1.8. データのロード#
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,1337566253.89858,0.000355720520019531],9]
実行結果の第2要素はロードされたレコードの数を示しています。上記の操作では、すべてのレコードを問題なくロードできています。
念のため、データが入っていることを確認してみましょう。
実行例:
select --table Site
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 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."
# ]
# ]
# ]
# ]
4.1.9. レコードの取得#
select コマンドを用いて、テーブルの中身を表示することができます。
query 引数を使って検索条件が指定された場合、 select コマンドは検索条件に適合するレコードを検索し、検索結果を出力します。
それでは、IDを指定してレコードを取り出してみましょう。以下の例では、Siteテーブルの先頭レコードを取り出します。正確には、 query 引数を使って _id カラムに1が格納されているレコードを要求しています。
実行例:
select --table Site --query _id:1
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 1
# ],
# [
# [
# "_id",
# "UInt32"
# ],
# [
# "_key",
# "ShortText"
# ],
# [
# "title",
# "ShortText"
# ]
# ],
# [
# 1,
# "http://example.org/",
# "This is test record 1!"
# ]
# ]
# ]
# ]
次に、主キーを指定してレコードを取り出してみましょう。以下の例では、主キーが "http://example.org/" のキーを取り出します。正確には、 query 引数を使って _key カラムに "http://example.org/" が格納されているレコードを要求しています。
実行例:
select --table Site --query '_key:"http://example.org/"'
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 1
# ],
# [
# [
# "_id",
# "UInt32"
# ],
# [
# "_key",
# "ShortText"
# ],
# [
# "title",
# "ShortText"
# ]
# ],
# [
# 1,
# "http://example.org/",
# "This is test record 1!"
# ]
# ]
# ]
# ]
4.1.10. 全文検索用の語彙表の作成#
そろそろ全文検索の使い方について見ていきましょう。
Groongaでは転置インデックスを使って高速な全文検索を実現しています。そのため、まずは転置インデックスとして用いるテーブルを作成する必要があります。テーブルの内容は、文書に含まれる単語やN-gramなどの索引語を主キーとして、各カラムに索引語の位置情報を格納するという構成になります。結果として、主キーのカラムは全文検索における語彙表の役割を果たします。
以下の例では、Termsという名前のテーブルを転置インデックスの語彙表として作成しています。索引語を格納するため、主キーの型はShortTextです。
実行例:
table_create --name Terms --flags TABLE_PAT_KEY --key_type ShortText --default_tokenizer TokenBigram --normalizer NormalizerAuto
# [[0,1337566253.89858,0.000355720520019531],true]
table_create には多くの引数が指定されているものの、本チュートリアルではすべてを理解する必要はありません。以下に簡単な説明を述べますが、読み飛ばしてもらってかまいません。
TABLE_PAT_KEYフラグは、主キーをパトリシア木に格納することを指示しています。 default_tokenizer 引数には、検索対象の文書をトークナイズする方式を指定するようになっています。上記の例では、一般的にN-gramと呼ばれるインデックス方式に対応するTokenBigramを指定しています。
normalizer 引数はインデックスの単語をノーマライズするかどうかを指定しています。
4.1.11. 全文検索用のインデックスカラムの作成#
次に必要なのは、インデックス型のカラムを作成することです。このカラムは、関連付けられたカラムに対する全文検索に利用されます。つまり、全文検索を行いたいカラムに対してインデックスを作成することに相当します。
それでは、インデックスカラムを作成してみましょう。以下の例では、Siteテーブルのカラムに対するインデックスカラムを作成します。それでは、Siteテーブルのtitleカラムを全文検索の対象とするべく、インデックス型のカラムを作成してみましょう。
実行例:
column_create --table Terms --name blog_title --flags COLUMN_INDEX|WITH_POSITION --type Site --source title
# [[0,1337566253.89858,0.000355720520019531],true]
table 引数は語彙表を指定し、 name 引数はインデックスカラムを指定します。また、 type 引数はインデックスの対象となるテーブルを指定し、 source 引数はインデックスの対象となるカラムを指定します。COLUMN_INDEXフラグはインデックスカラムの作成を指示し、WITH_POSITIONフラグは各索引語の位置情報をインデックスに含めることを指示します。一般的な全文検索インデックスを作成したいときは、COLUMN_INDEX|WITH_POSITIONを指定してください。索引語の位置情報については、本チュートリアルでは触れません。
注釈
語彙表とインデックスカラムを作成するタイミングは、データをロードする前後のどちらでも問題ありません。データをロードした後でインデックスを作成し、さらに新しいデータをロードすることもできます。インデックスの作成を指示したタイミングでレコードが既に存在するときは、静的にインデックスを作成します。一方、インデックスを作成した後で追加されたレコードについては、動的にインデックスを更新します。
4.1.12. 全文検索#
インデックスを作成したことにより、 select コマンドによる全文検索が可能になります。
全文検索のクエリは query 引数により指定することができます。以下の例では、titleカラムに "this" という文字列が含まれているレコードを検索します。 query 引数に含まれる '@' は、全文検索を指示しています。語彙表の作成において NormalizerAuto を指定したときは、全角・半角や大文字・小文字などの違いが吸収されることに注意してください。
実行例:
select --table Site --query title:@this
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 1
# ],
# [
# [
# "_id",
# "UInt32"
# ],
# [
# "_key",
# "ShortText"
# ],
# [
# "title",
# "ShortText"
# ]
# ],
# [
# 1,
# "http://example.org/",
# "This is test record 1!"
# ]
# ]
# ]
# ]
上記の例では、"This" という単語を含む先頭レコードのみが検索条件に適合します。
select コマンドには、 match_columns という引数が存在します。このパラメータはデフォルトで検索対象にするカラムを指定するもので、カラム名を指定しない検索条件にのみ適用されます。 [1]
"--match_columns title" と "--query this" の組み合わせを指定すると、 "--query title:@this" を指定したときと同じ検索条件になります。
実行例:
select --table Site --match_columns title --query this
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 1
# ],
# [
# [
# "_id",
# "UInt32"
# ],
# [
# "_key",
# "ShortText"
# ],
# [
# "title",
# "ShortText"
# ]
# ],
# [
# 1,
# "http://example.org/",
# "This is test record 1!"
# ]
# ]
# ]
# ]
4.1.13. 出力カラムの指定#
select コマンドにおいて output_columns 引数を用いることで、検索結果に含めるカラムを指定することができます。複数のカラムを指定するときは、カンマ（,）区切りでカラムを列挙します。
実行例:
select --table Site --output_columns _key,title,_score --query title:@test
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 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の検索結果に含まれるカラムであり、全文検索の条件に合致するレコードほど高い数値が入ります。
4.1.14. 表示範囲指定#
select コマンドにおいて offset 引数と limit 引数を用いることで、検索結果の一部のみを表示することができます。大量の検索結果を分割してページ単位で表示したい場合などに有用です。
offset 引数には、検索結果における始点を指定します。検索結果の1件目が必要な場合、 offset 引数を省略するか、0を指定するようにしてください。 limit 引数には、検索結果の表示件数を指定します。
実行例:
select --table Site --offset 0 --limit 3
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 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,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 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,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 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."
# ]
# ]
# ]
# ]
4.1.15. 検索結果の並べ替え#
select コマンドに sort_keys 引数を渡すことにより、検索結果を並べ替えることができます。
sort_keys 引数には、整列の基準として用いるカラムを指定します。検索結果は指定したカラムの値が昇順になるように並べ替えられます。 sort_keys 引数の中でカラム名の前にハイフン（-）を付けることにより、降順に並べ替えることもできます。
以下の例では、Siteテーブルのレコードを逆順に表示しています。
実行例:
select --table Site --sort_keys -_id
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 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 --sort_keys -_score
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 9
# ],
# [
# [
# "_id",
# "UInt32"
# ],
# [
# "_score",
# "Int32"
# ],
# [
# "title",
# "ShortText"
# ]
# ],
# [
# 6,
# 4,
# "test test test test record six."
# ],
# [
# 5,
# 3,
# "test test test record five."
# ],
# [
# 7,
# 3,
# "test test test record seven."
# ],
# [
# 8,
# 2,
# "test test record eight."
# ],
# [
# 3,
# 2,
# "test test record three."
# ],
# [
# 9,
# 2,
# "test test record nine."
# ],
# [
# 1,
# 1,
# "This is test record 1!"
# ],
# [
# 4,
# 1,
# "test record four."
# ],
# [
# 2,
# 1,
# "test record 2."
# ]
# ]
# ]
# ]
整列の基準となるカラムを複数指定したいときは、カンマ（,）区切りでカラムを列挙します。複数のカラムを指定したときは、最初のカラムを基準として整列した後、最初のカラムに同じ値が格納されているレコードを次のカラムを基準として整列します。
実行例:
select --table Site --query title:@test --output_columns _id,_score,title --sort_keys -_score,_id
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 9
# ],
# [
# [
# "_id",
# "UInt32"
# ],
# [
# "_score",
# "Int32"
# ],
# [
# "title",
# "ShortText"
# ]
# ],
# [
# 6,
# 4,
# "test test test test record six."
# ],
# [
# 5,
# 3,
# "test test test record five."
# ],
# [
# 7,
# 3,
# "test test test record seven."
# ],
# [
# 3,
# 2,
# "test test record three."
# ],
# [
# 8,
# 2,
# "test test record eight."
# ],
# [
# 9,
# 2,
# "test test record nine."
# ],
# [
# 1,
# 1,
# "This is test record 1!"
# ],
# [
# 2,
# 1,
# "test record 2."
# ],
# [
# 4,
# 1,
# "test record four."
# ]
# ]
# ]
# ]
脚注