これはPGroonga 2.X and 3.X用のドキュメントです。古いPGroongaを使っているならPGroonga 1.xのドキュメントを見てください。
pgroonga_command関数pgroonga_command関数はGroongaのコマンドを実行してtext型の値として結果を返します。
この関数の構文は次の通りです。
text pgroonga_command(command)
commandはtext型の値です。pgroonga_commandはcommandをGroongaのコマンドとして実行します。
この関数にはもうひとつ構文があります。これは1.1.9以降で使えます。
text pgroonga_command(name,
ARRAY[argument_name1, argument_value1,
argument_name2, argument_value2,
...])
2つめの構文を推奨します。理由は引数の値を自動でエスケープするからです。これによりシンタックスエラーとGroongaコマンドインジェクションを防げます。
nameはtext型の値です。実行するコマンド名です。
argument_nameはtext型の値です。引数名です。この後に対応する引数の値が続きます。
argument_valueはtext型の値です。直前にした引数名に対応する値です。
pgroonga_commandはnameとargument_nameとargument_valueからGroongaコマンドを作り、そのGroongaコマンドを実行します。
Groongaのコマンドは結果をJSONとして返します。pgroonga_commandはJSONをtext型の値として返します。結果をjson型かjsonb型にキャストするとPostgreSQLが提供するJSON関数・演算を使うことができます。
サンプルスキーマとデータは次の通りです。
CREATE TABLE memos (
content text
);
CREATE INDEX pgroonga_memos_index
ON memos
USING pgroonga (content);
INSERT INTO memos VALUES ('PGroonga (PostgreSQL+Groonga) is great!');
以下はstatus Groongaコマンドの実行例です。このコマンドには引数はありません。
SELECT jsonb_pretty(pgroonga_command('status')::jsonb);
-- jsonb_pretty
-- -----------------------------------------
-- [ +
-- [ +
-- 0, +
-- 1480484730.607103, +
-- 0.0001363754272460938 +
-- ], +
-- { +
-- "uptime": 859, +
-- "version": "6.1.0-53-g460b5c9",+
-- "n_queries": 6, +
-- "starttime": 1480483871, +
-- "start_time": 1480483871, +
-- "alloc_count": 14034, +
-- "cache_hit_rate": 0.0, +
-- "command_version": 1, +
-- "max_command_version": 3, +
-- "default_command_version": 1 +
-- } +
-- ]
-- (1 row)
以下は挿入したデータを検索する例です。検索にはselect Groongaコマンドを使います。pgroonga_table_name関数を使ってPGroongaのインデックス名をGroongaのテーブル名に変換する必要があります。
SELECT jsonb_pretty(
pgroonga_command(
'select ' ||
'--table ' || pgroonga_table_name('pgroonga_memos_index')
)::jsonb
);
-- jsonb_pretty
-- ------------------------------------------------------------
-- [ +
-- [ +
-- 0, +
-- 1480484984.533947, +
-- 0.0005786418914794922 +
-- ], +
-- [ +
-- [ +
-- [ +
-- 1 +
-- ], +
-- [ +
-- [ +
-- "_id", +
-- "UInt32" +
-- ], +
-- [ +
-- "content", +
-- "LongText" +
-- ], +
-- [ +
-- "ctid", +
-- "UInt64" +
-- ] +
-- ], +
-- [ +
-- 1, +
-- "PGroonga (PostgreSQL+Groonga) is great!",+
-- 1 +
-- ] +
-- ] +
-- ] +
-- ]
-- (1 row)
以下は「PostgreSQL」と「Groonga」を含むレコードを検索する例です。「PostgreSQL Groonga」を1つの引数値として扱うためにダブルクォート（またはシングルクォート）で囲む必要がある点に注意してください。
SELECT jsonb_pretty(
pgroonga_command(
'select ' ||
'--table ' || pgroonga_table_name('pgroonga_memos_index') || ' ' ||
'--match_columns content ' ||
'--query "PostgreSQL Groonga"'
)::jsonb
);
-- jsonb_pretty
-- ------------------------------------------------------------
-- [ +
-- [ +
-- 0, +
-- 1480485153.923481, +
-- 0.002448797225952148 +
-- ], +
-- [ +
-- [ +
-- [ +
-- 1 +
-- ], +
-- [ +
-- [ +
-- "_id", +
-- "UInt32" +
-- ], +
-- [ +
-- "content", +
-- "LongText" +
-- ], +
-- [ +
-- "ctid", +
-- "UInt64" +
-- ] +
-- ], +
-- [ +
-- 1, +
-- "PGroonga (PostgreSQL+Groonga) is great!",+
-- 1 +
-- ] +
-- ] +
-- ] +
-- ]
-- (1 row)
引数を配列で指定するスタイルと使うと、ダブルクォートで囲むことについて気にする必要がなくなります。
SELECT jsonb_pretty(
pgroonga_command(
'select',
ARRAY[
'table', pgroonga_table_name('pgroonga_memos_index'),
'match_columns', 'content',
'query', 'PostgreSQL Groonga'
]
)::jsonb
);
-- jsonb_pretty
-- ------------------------------------------------------------
-- [ +
-- [ +
-- 0, +
-- 1480485246.841189, +
-- 0.00008869171142578125 +
-- ], +
-- [ +
-- [ +
-- [ +
-- 1 +
-- ], +
-- [ +
-- [ +
-- "_id", +
-- "UInt32" +
-- ], +
-- [ +
-- "content", +
-- "LongText" +
-- ], +
-- [ +
-- "ctid", +
-- "UInt64" +
-- ] +
-- ], +
-- [ +
-- 1, +
-- "PGroonga (PostgreSQL+Groonga) is great!",+
-- 1 +
-- ] +
-- ] +
-- ] +
-- ]
-- (1 row)
selectコマンドに関する注意事項Groongaのselectコマンドを使うとき、不正なタプルについて注意する必要があります。
詳細はpgroonga_tuple_is_alive Groonga関数を参照してください。