.. -*- rst -*-

.. highlightlang:: none

.. groonga-command
.. database: tutorial
.. table_remove Site
.. table_remove Terms

基本的な操作
============

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/tutorial/introduction-1.log
.. .. % groonga -n /tmp/groonga-databases/introduction.db
.. status

以上のように、コマンドの実行結果は基本的にjson形式で返却されます。jsonの配列の0番目の要素に、エラーコードや実行時間などの情報が入ります。jsonの配列の1番目の様子に、コマンドの実行結果が入ります。

コマンド
--------

groonga実行ファイルやgroongaサーバを介して様々なコマンドを実行して、DBを操作することができます。
コマンドは以下の書式のうちいずれかで与えることができます。 ::

 書式1: コマンド名 引数1 引数2 ..

 書式2: コマンド名 --引数名1 値1 --引数名2 値2 ..

書式1と2は混ぜて使うことができます。

書式2において、空白や、記号「"'()\」のうちいずれかを含む値を指定したい場合は、シングルクォート(')かダブルクォート(")で値を囲みます。

詳しくは、 :doc:`/executables/groonga` のコマンドの項を参考にしてください。

主なコマンド
------------

 :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/tutorial/introduction-2.log
.. table_create --name Site --flags TABLE_HASH_KEY --key_type ShortText

検索
----

:doc:`/commands/select` コマンドを用いて、テーブルの中身を表示することができます。

.. groonga-command
.. include:: ../example/tutorial/introduction-3.log
.. select --table Site

selectにテーブル名を指定すると、指定したテーブルの中身を10件表示します。[0]は検索されたレコードの件数、["_id","Uint32"]は値がUInt32型である"_id'という名前のカラム、["_key","ShortText"]は値がShortText型である'_key'という名前のカラムを示しています。

table_createコマンドで作成したテーブルには、最初から'_id'/'_key'という２つのカラムがあります。'_id'はgroongaが自動的に付与するID番号が格納されるカラムです。'_key'は主キーが格納されるカラムです。これらのカラム名を変更することはできません。

カラムの作成
------------

:doc:`/commands/column_create` コマンドを用いて、カラムを作成することができます。

ShortText型の値を持つ、'comment'という名前のカラムを'Site'テーブルに追加しましょう。

.. groonga-command
.. include:: ../example/tutorial/introduction-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/tutorial/introduction-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/tutorial/introduction-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/tutorial/introduction-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/tutorial/introduction-8.log
.. select --table Site

データの検索
------------

groongaでは、'_id'カラムと'_key'カラムの値はテーブル中で一意です。よって、それを用いて検索してみましょう。

selectコマンドにおいて、queryパラメータを用いるとデータの検索を行うことができます。

.. groonga-command
.. include:: ../example/tutorial/introduction-9.log
.. select --table Site --query _id:1

queryパラメータに与えた「_id:1」というのは、'_id'という名前のカラムに'1'という値が入っているレコードを検索する、という意味です。

_keyでも検索してみましょう。

.. groonga-command
.. include:: ../example/tutorial/introduction-10.log
.. select --table Site --query "_key:\"http://example.org/\""

queryパラメータに与えた「_key:\"http://example.org/\"」というのは、'_key'という名前のカラムに'"http://example.org/"'という値が入っているレコードを検索する、という意味です。

全文検索
--------

queryパラメータでは、インデックスを用いた全文検索を行うこともできます。

.. groonga-command
.. include:: ../example/tutorial/introduction-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/tutorial/introduction-12.log
.. select --table Site --match_columns title --query this

出力カラムの指定
----------------

selectコマンドにおいて、output_columnsパラメータを用いることで、検索結果で表示するカラムを指定することが出来ます。

複数のカラムを指定する場合は、カンマ(,)区切りで指定します。

.. groonga-command
.. include:: ../example/tutorial/introduction-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/tutorial/introduction-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/tutorial/introduction-15.log
.. select --table Site --sortby -_id

出力カラムの指定で紹介した「_score」カラムは、ソートの条件としても使うことができます。

.. groonga-command
.. include:: ../example/tutorial/introduction-16.log
.. select --table Site --query title:@test --output_columns _id,_score,title --sortby _score

ソートするカラム名を複数指定したい場合は、カンマ(,)区切りで指定します。複数のカラムを指定した場合、最初のカラムで同一の値のレコードがあった場合に、次のカラムの値でソートさせることができます。

.. groonga-command
.. include:: ../example/tutorial/introduction-17.log
.. select --table Site --query title:@test --output_columns _id,_score,title --sortby _score,_id

.. rubric:: 脚注

.. [1] 現在のバージョンでは、全文検索インデックスが存在する場合にのみ、match_columnsパラメータを利用することができます。通常のカラムでの絞り込みには利用できません。