これはPGroonga 1.X用のドキュメントです。新しいPGroongaを使っているならPGroonga 2.xのドキュメントを見てください。

pgroonga.escape関数

1.1.9で追加。

概要

pgroonga.escape関数は渡された値をスクリプト構文のリテラルに変換します。このリテラルはスクリプト構文内で安全に使えます。スクリプト構文はJSONBの@@演算子などで使っています。

pgroonga.escape関数はpgroonga.command関数経由でのGroongaコマンドインジェクションが発生することを防ぐために使えます。Groongaコマンドインジェクションを防ぐことについてはpgroonga.command_escape_value関数とpgroonga.query_escape関数も見てください。

構文

この関数の構文は次の通りです。

text pgroonga.escape(value)

valueの型は次のどれかです。

valueはスクリプト構文で使うリテラルです。

pgroonga.query_escapeはtext型の値を返します。この値はスクリプト構文中でリテラルとして安全に使えます。

もしvalueがtext型の値の場合は、次のようにエスケープ対象の文字を0個以上指定できます。

text pgroonga.escape(value, special_characters)

special_charactersはtext型の値です。この値にエスケープ対象の文字をすべて含めます。「(」と「)」をエスケープしたい場合は'()'と指定します。

使い方

サンプルスキーマとデータは次の通りです。

CREATE TABLE logs (
  message jsonb
);

CREATE INDEX pgroonga_logs_index
          ON logs
       USING pgroonga (message);

INSERT INTO logs VALUES ('{"body": "\"index.html\" not found"}');

"index.html" not foundを検索したい場合は、次のように"を\"とエスケープします。

SELECT * FROM logs
 WHERE message @@ 'string @ "\"index.html\" not found"';
--                message                
-- --------------------------------------
--  {"body": "\"index.html\" not found"}
-- (1 row)

この用途にpgroonga.escape関数を使えます。

SELECT * FROM logs
 WHERE message @@ ('string @ ' || pgroonga.escape('"index.html" not found'));
--                message                
-- --------------------------------------
--  {"body": "\"index.html\" not found"}
-- (1 row)

pgroonga.escape関数はpgroonga.command関数と組み合わせたときも便利です。

SELECT jsonb_pretty(
  pgroonga.command('select',
                   ARRAY[
                     'table', pgroonga.table_name('pgroonga_logs_index'),
                     'output_columns', 'message.string',
                     'filter', 'message.string @ ' || pgroonga.escape('"index.html" not found')
                   ])::jsonb
);
--                   jsonb_pretty                  
-- ------------------------------------------------
--  [                                             +
--      [                                         +
--          0,                                    +
--          1480435379.074671,                    +
--          0.0004425048828125                    +
--      ],                                        +
--      [                                         +
--          [                                     +
--              [                                 +
--                  1                             +
--              ],                                +
--              [                                 +
--                  [                             +
--                      "message.string",         +
--                      "LongText"                +
--                  ]                             +
--              ],                                +
--              [                                 +
--                  [                             +
--                      "",                       +
--                      "\"index.html\" not found"+
--                  ]                             +
--              ]                                 +
--          ]                                     +
--      ]                                         +
--  ]
-- (1 row)

数値のようにtext型以外の値にもpgroonga.escape関数を使えます。

SELECT jsonb_pretty(
  pgroonga.command('select',
                   ARRAY[
                     'table', pgroonga.table_name('pgroonga_logs_index'),
                     'output_columns', '_id',
                     'filter', '_id == ' || pgroonga.escape(1)
                   ])::jsonb
);
--           jsonb_pretty          
-- --------------------------------
--  [                             +
--      [                         +
--          0,                    +
--          1480435504.153011,    +
--          0.00009799003601074219+
--      ],                        +
--      [                         +
--          [                     +
--              [                 +
--                  1             +
--              ],                +
--              [                 +
--                  [             +
--                      "_id",    +
--                      "UInt32"  +
--                  ]             +
--              ],                +
--              [                 +
--                  1             +
--              ]                 +
--          ]                     +
--      ]                         +
--  ]
-- (1 row)

参考