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": true,
#       "apache_arrow": true,
#       "xxhash": true,
#       "blosc": 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
#   }
# ]

以上のように、コマンドの実行結果は基本的にjson形式の配列として返却されます。配列の先頭には、エラーコードや実行時間などの情報が入ります。2番目の要素には、指示された操作の実行結果が入ります。

注釈

他のツールを使うことで、JSONを整形できます。例えば、 grnwrapGrnlinejq などが使えます。

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"
#         ]
#       ]
#     ]
#   ]
# ]

selecttable 引数のみを指定すると、指定したテーブルの中身を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.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."
#       ]
#     ]
#   ]
# ]

脚注