/
tutorial01.txt
319 lines (205 loc) · 15.4 KB
/
tutorial01.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
.. highlightlang:: none
.. groonga-command
.. table_remove Site
.. table_remove Terms
インストールと基本的な操作
==========================
本チュートリアルでは、groongaの利用方法を紹介します。
インストール方法
----------------
groongaは、ほとんど他のライブラリに依存せずに動作します。
* MeCabのインストール
形態素単位でトークナイズした全文検索索引を使用したい場合は、
groongaのインストール前にMeCab (http://mecab.sourceforge.net/)をインストールしてください。
* groongaのインストール
http://groonga.org/download/よりtar.gzファイルを取得し、
インストール先の環境にファイルを展開して、 ::
./configure --prefix=/usr --localstatedir=/var && make && sudo make install
のように実行することでインストールできます。
prefixは、インストール先を指定するパラメータです。prefixを指定しない場合には、/usr/localが指定されたものとみなします。LD_LIBRARY_PATHなどに詳しくない人は、上記のように/usrを指定することをお勧めします。
基本的な操作
------------
groongaは、Cのライブラリとして使用する方法と、groonga実行ファイルを通して使用する方法があります。
本チュートリアルでは、groonga実行ファイルを使用する方法について説明します。
groonga実行ファイルを使って、DBの作成・操作・サーバの起動・サーバへの接続などの操作が行えます。
DBの作成
^^^^^^^^
以下のようなコマンドを実行すると、データベースを新規に作成することができます。
書式 ::
groonga -n データベースパス名
-nオプションは、データベースを作ることを示します。
データベースパス名には、新しく作成するデータベースのフルパス名を指定します。
上記コマンドでデータベースを作成すると、そのまま対話モードと呼ばれるコマンドを受け付けるモードになります。Ctrlキーを押しながらdキーを押すと、対話モードから抜けることができます。
実行例::
% groonga -n /tmp/tutorial.db
> ctrl-d
%
DBの操作
^^^^^^^^
書式 ::
groonga DBパス名 [コマンド]
既存のデータベースのフルパス名をDBパス名に指定します。
コマンドを指定すると、実行結果を返します。
コマンドを指定しない場合には、対話モードに入ります。
対話モードでは、標準入力からコマンドを読み込み、順次実行します。
本チュートリアルでは、対話モードを主に使用します。
たとえば、statusというコマンドを実行してみましょう。statusコマンドは、groongaの実行状態を返すコマンドです。
.. groonga-command
.. include:: ../example/tutorial01-1.log
.. .. % groonga /tmp/tutorial.db
.. status
以上のように、コマンドの実行結果は基本的にjson形式で返却されます。jsonの配列の0番目の要素に、エラーコードや実行時間などの情報が入ります。jsonの配列の1番目の様子に、コマンドの実行結果が入ります。
コマンド
^^^^^^^^
groonga実行ファイルやgroongaサーバを介して様々なコマンドを実行して、DBを操作することができます。
コマンドは以下の書式のうちいずれかで与えることができます。 ::
書式1: コマンド名 引数1 引数2 ..
書式2: コマンド名 --引数名1 値1 --引数名2 値2 ..
書式1と2は混ぜて使うことができます。
書式2において、空白や、記号「"'()\」のうちいずれかを含む値を指定したい場合は、シングルクォート(')かダブルクォート(")で値を囲みます。
詳しくは、 :doc:`../execfile` のコマンドの項を参考にしてください。
主なコマンド
^^^^^^^^^^^^
:doc:`../commands/status`
groongaプロセスの状態を表示します。
:doc:`../commands/table_list`
DBに定義されているテーブルのリストを表示します。
:doc:`../commands/column_list`
テーブルに定義されているカラムのリストを表示します。
:doc:`../commands/table_create`
DBにテーブルを追加します。
:doc:`../commands/column_create`
テーブルにカラムを追加します。
:doc:`../commands/select`
テーブルに含まれるレコードを検索して表示します。
:doc:`../commands/load`
テーブルにレコードを挿入します。
テーブルの作成
^^^^^^^^^^^^^^
:doc:`../commands/table_create` コマンドを使用してテーブルを作成します。
groongaでは、多くの場合テーブルを作成する際に主キーが必要となります。また、主キーには型と、その格納方法を指定する必要があります。
型については、のちのチュートリアルで触れます。データの種類をあらわしているもの、とイメージしてください。
主キーの格納方法によって、主キーでの検索速度や、前方一致検索の可否が決まります。これも、のちのチュートリアルで触れます。
ここでは、ShortText型の主キー値を持ち、主キーの格納方法はHASHである、'Site'という名前のテーブルを作成します。
.. groonga-command
.. include:: ../example/tutorial01-2.log
.. table_create --name Site --flags TABLE_HASH_KEY --key_type ShortText
検索
^^^^
:doc:`../commands/select` コマンドを用いて、テーブルの中身を表示することができます。
.. groonga-command
.. include:: ../example/tutorial01-3.log
.. select --table Site
selectにテーブル名を指定すると、指定したテーブルの中身を10件表示します。[0]は検索されたレコードの件数、["_id","Uint32"]は値がUInt32型である"_id'という名前のカラム、["_key","ShortText"]は値がShortText型である'_key'という名前のカラムを示しています。
table_createコマンドで作成したテーブルには、最初から'_id'/'_key'という2つのカラムがあります。'_id'はgroongaが自動的に付与するID番号が格納されるカラムです。'_key'は主キーが格納されるカラムです。これらのカラム名を変更することはできません。
カラムの作成
^^^^^^^^^^^^
:doc:`../commands/column_create` コマンドを用いて、カラムを作成することができます。
ShortText型の値を持つ、'comment'という名前のカラムを'Site'テーブルに追加しましょう。
.. groonga-command
.. include:: ../example/tutorial01-4.log
.. column_create --table Site --name title --flags COLUMN_SCALAR --type ShortText
.. select --table Site
COLUMN_SCALARについては、通常のカラムであることを示しています。
全文検索用の語彙テーブルの作成
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
このチュートリアルでは、groongaに登録したデータを用いた全文検索を行います。
全文検索を行う場合は、まず語彙テーブルを作成する必要があります。
語彙表テーブルとは、文書の中にある単語が主キーとなるテーブルです。
ここでは、ShortText型の主キー値を持つ、'Terms'という名前のテーブルを作成しました。
.. groonga-command
.. include:: ../example/tutorial01-5.log
.. table_create --name Terms --flags TABLE_PAT_KEY|KEY_NORMALIZE --key_type ShortText --default_tokenizer TokenBigram
この実行例には、多くのパラメータが指定されています。本チュートリアルでは、これらをすべて理解する必要はありません。以下に簡単な説明を記しますが、読み飛ばしてもらってかまいません。
実行例にある、TABLE_PAT_KEY|KEY_NORMALIZEという値は、主キー値をパトリシア木に格納し、各語彙を正規化して登録することを示しています。
実行例にある、TokenBigramという値は、 語彙表として使用するテーブルは、対象の文書をトークナイズする方式を、default_tokenizerパラメータで与えます。この例ではTokenBigramを指定しています。よって、一般的にN-gramと呼ばれるようなインデックス方式を選択しています。
全文検索用のインデックスカラムの作成
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Siteテーブルのtitleカラムを全文検索の対象としたいとしましょう。その場合には、語彙テーブルにインデックス型のカラムを作成します。
.. groonga-command
.. include:: ../example/tutorial01-6.log
.. column_create --table Terms --name blog_title --flags COLUMN_INDEX|WITH_POSITION --type Site --source title
Siteテーブルのtitleカラムを検索対象とする、'blog_title'という名前のインデックス型カラムをTermsテーブルに作成しました。インデックス対象となるテーブルをtypeに、インデックス対象となるカラムをsourceに指定します。
実行例のflagsのCOLUMN_INDEX|WITH_POSITIONという値は、語彙の位置情報を格納するインデックス型のカラムであることを示しています。通常の全文検索インデックスでは、COLUMN_INDEX|WITH_POSITIONを指定してください。語彙の位置情報を格納する意味については、本チュートリアルでは触れません。
データのロード
^^^^^^^^^^^^^^
:doc:`../commands/load` コマンドを使用します。loadコマンドでは、jsonで受け取ったデータをテーブルに格納します。
.. groonga-command
.. include:: ../example/tutorial01-7.log
.. 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."},
.. ]
selectコマンドで、データが入っていることを確認しましょう。
.. groonga-command
.. include:: ../example/tutorial01-8.log
.. select --table Site
データの検索
^^^^^^^^^^^^
groongaでは、'_id'カラムと'_key'カラムの値はテーブル中で一意です。よって、それを用いて検索してみましょう。
selectコマンドにおいて、queryパラメータを用いるとデータの検索を行うことができます。
.. groonga-command
.. include:: ../example/tutorial01-9.log
.. select --table Site --query _id:1
queryパラメータに与えた「_id:1」というのは、'_id'という名前のカラムに'1'という値が入っているレコードを検索する、という意味です。
_keyでも検索してみましょう。
.. groonga-command
.. include:: ../example/tutorial01-10.log
.. select --table Site --query "_key:\"http://example.org/\""
queryパラメータに与えた「_key:\"http://example.org/\"」というのは、'_key'という名前のカラムに'"http://example.org/"'という値が入っているレコードを検索する、という意味です。
全文検索
^^^^^^^^
queryパラメータでは、インデックスを用いた全文検索を行うこともできます。
.. groonga-command
.. include:: ../example/tutorial01-11.log
.. select --table Site --query title:@this
titleカラムに対して、'this'という文字列で全文検索を行った結果を返します。
queryパラメータに与えた「title:@this」というのが、'title'という名前のカラムに'this'という文字列が含まれているレコードを検索する、という意味です。
selectコマンドには、match_columnsというパラメータが存在します。これを指定すると、query内にカラム名を指定しない条件があった場合、match_columnsで指定されたカラムに対しての検索であることを示します。[1]_
match_columnsパラメータに'title'、queryパラメータに'this'という文字列を指定すると、上記のクエリと同じ結果を得ることができます。
.. groonga-command
.. include:: ../example/tutorial01-12.log
.. select --table Site --match_columns title --query this
出力カラムの指定
^^^^^^^^^^^^^^^^
selectコマンドにおいて、output_columnsパラメータを用いることで、検索結果で表示するカラムを指定することが出来ます。
複数のカラムを指定する場合は、カンマ(,)区切りで指定します。
.. groonga-command
.. include:: ../example/tutorial01-13.log
.. select --table Site --output_columns _key,title,_score --query title:@test
groongaの検索結果には、「_score」という名前のカラムが追加されています。このカラムは、全文検索の条件が合致する文書ほど高い数値が入ります。
表示範囲指定
^^^^^^^^^^^^
selectコマンドにおいて、offset,limitパラメータを用いることで、検索結果から指定された範囲のみを表示することが出来ます。大量の検索結果をページで分けて、1ページ分のみを表示したい場合に有効です。
offsetパラメータには、検索結果を返す始点を指定します。1件目から結果を返す場合には、0を指定します。
limitパラメータには、検索結果を何件表示するのかを指定します。
.. groonga-command
.. include:: ../example/tutorial01-14.log
.. select --table Site --offset 0 --limit 3
.. select --table Site --offset 3 --limit 3
.. select --table Site --offset 7 --limit 3
並び替え
^^^^^^^^
selectコマンドにおいて、sortbyパラメータを用いることで、検索結果を並び替えることが出来ます。
sortbyパラメータにカラム名を指定することで、そのカラムの値で昇順にソートします。また、カラム名の前にハイフン(-)を付けることで、降順にソートすることも出来ます。
.. groonga-command
.. include:: ../example/tutorial01-15.log
.. select --table Site --sortby -_id
出力カラムの指定で紹介した「_score」カラムは、ソートの条件としても使うことができます。
.. groonga-command
.. include:: ../example/tutorial01-16.log
.. select --table Site --query title:@test --output_columns _id,_score,title --sortby _score
ソートするカラム名を複数指定したい場合は、カンマ(,)区切りで指定します。複数のカラムを指定した場合、最初のカラムで同一の値のレコードがあった場合に、次のカラムの値でソートさせることができます。
.. groonga-command
.. include:: ../example/tutorial01-17.log
.. select --table Site --query title:@test --output_columns _id,_score,title --sortby _score,_id
.. rubric:: 脚注
.. [1] 現在のバージョンでは、全文検索インデックスが存在する場合にのみ、match_columnsパラメータを利用することをができます。通常のカラムでの絞り込みには利用できません。