diff --git a/_po/ja/reference/functions/pgroonga-condition.po b/_po/ja/reference/functions/pgroonga-condition.po new file mode 100644 index 000000000..97c4e21e8 --- /dev/null +++ b/_po/ja/reference/functions/pgroonga-condition.po @@ -0,0 +1,707 @@ +msgid "" +msgstr "" +"Project-Id-Version: PACKAGE VERSION\n" +"Report-Msgid-Bugs-To: \n" +"PO-Revision-Date: 2024-09-09 01:38+0000\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Japanese\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=; plural=;\n" + +msgid "" +"---\n" +"title: pgroonga_condition function\n" +"upper_level: ../\n" +"---" +msgstr "" +"---\n" +"title: pgroonga_condition 関数\n" +"upper_level: ../\n" +"---" + +msgid "# `pgroonga_condition()` function" +msgstr "# `pgroonga_condition()` 関数" + +msgid "Since 3.1.6." +msgstr "3.1.6で追加。" + +msgid "## Summary" +msgstr "## 概要" + +msgid "" +"`pgroonga_condition()` function returns `pgroonga_condition` type value.\n" +"The function and the type have same name, but they are two different " +"things.\n" +"`pgroonga_condition` type represents complicated conditional expressions, " +"such as `pgroonga_full_text_search_condition` type and " +"`pgroonga_full_text_search_condition_with_scorers` type." +msgstr "" +"`pgroonga_condition()`関数は`pgroonga_condition`型の値を返します。\n" +"関数名と型名が同じですが別物です。\n" +"`pgroonga_condition`型は`pgroonga_full_text_search_condition`型や" +"`pgroonga_full_text_search_condition_with_scorers`型のように複雑な条件式を表" +"現します。" + +msgid "" +"`pgroonga_condition()` function is a useful function to make the " +"`pgroonga_condition` type value.\n" +"It allows to make the `pgroonga_condition` type value by designating the " +"specific attribute values." +msgstr "" +"`pgroonga_condition()`関数は`pgroonga_condition`型の値を作るための便利関数で" +"す。\n" +"特定の属性値のみを指定して`pgroonga_condition`型の値を作れます。" + +msgid "" +"There were not this kind of useful functions for " +"`pgroonga_full_text_search_condition` type and " +"`pgroonga_full_text_search_condition_with_scorers` type, so designating all " +"attribute values was necessary to make the value." +msgstr "" +"`pgroonga_full_text_search_condition`型や" +"`pgroonga_full_text_search_condition_with_scorers`型では、このような便利関数" +"がなかったため必ず全ての属性値を指定して値を作る必要がありました。" + +msgid "" +"Therefore, you need to designate `NULL` for disused attribute value as " +"follows when `pgroonga_full_text_search_condition` type and " +"`pgroonga_full_text_search_condition_with_scorers` type are used to avoid " +"making all the values." +msgstr "" +"したがって、不要な属性値があっても、`pgroonga_full_text_search_condition`型や" +"`pgroonga_full_text_search_condition_with_scorers`型では、次のように不要な属" +"性値には`NULL`を指定する必要がありました。" + +msgid "" +"```sql\n" +"title &@~ ('keyword', NULL, 'index_name')::" +"pgroonga_full_text_search_condition\n" +"title &@~ ('keyword', ARRAY[1,1,1,5,0], NULL, 'index_name')::" +"pgroonga_full_text_search_condition_with_scorers\n" +"```" +msgstr "" + +msgid "" +"It was not possible for existing value creation methods to make new " +"attribute value while keeping backward compatibility.\n" +"Thus, it was necessary to add a new type every time when a new attribute " +"value is added, such as `pgroonga_full_text_search_condition_with_XXX` " +"type.\n" +"For example, `pgroogna_full_text_search_condition_with_scorers` type was " +"added because of the added new attribute." +msgstr "" +"型を指定して直接値を作る従来の方法では後方互換性を維持したまま新しい属性を作" +"ることができませんでした。\n" +"そのため、新しい属性を追加するたびに" +"`pgroonga_full_text_search_condition_with_XXX`というような新しい型を追加する" +"必要がありました。\n" +"たとえば、`pgroogna_full_text_search_condition_with_scorers`型はそのために追" +"加された型です。" + +msgid "" +"The difference between `pgroonga_full_text_search_condition` type and " +"`pgroonga_full_text_search_condition_with_scorers` type is whether `scorers` " +"exist or not. If `scorers` is added to `pgroonga_full_text_search_condition` " +"type, every users are required to insert new `NULL` to make " +"`pgroonga_full_text_search_condition` type regardless of `scorers` usage." +msgstr "" +"`pgroonga_full_text_search_condition`型と" +"`pgroonga_full_text_search_condition_with_scorers`型の違いは`scorers`が存在す" +"るかどうかですが、`pgroonga_full_text_search_condition`型に`scorers`を追加し" +"てしまうと、`scorers`を使わないユーザーも新たに`NULL`を挿入して" +"`pgroonga_full_text_search_condition`型の値を作らなければなりません。" + +msgid "" +"However, installing `pgroonga_condition()` function to make new " +"`pgroonga_condition` type value let a new attribute to be added while " +"keeping backward compatibility.\n" +"It is because `pgroonga_condition()` function absorbs incompatibility." +msgstr "" +"しかし、`pgroonga_condition`型の値を作るための便利関数`pgroonga_condition()`" +"関数を導入することにより後方互換性を維持したまま`pgroonga_condition`型に新し" +"い属性を追加できます。\n" +"`pgroonga_condition()`関数が非互換を吸収してくれるからです。" + +msgid "" +"`pgroonga_condition()` function lets current writing style when a new " +"attribute value is added because the function can leave out unnecessary " +"attribute value as following sample.\n" +"(In the following sample, `weights`, `scorers`, `schema_name` and " +"`column_name` are left out. The details of attribute values would be noted " +"in next [\"Syntax\"](#syntax). Here, point is that possibility of leaving " +"out unnecessary attribute values.)" +msgstr "" +"次のように、`pgroonga_condition()`関数は不要な属性値を省略できるため、新たに" +"属性値が追加されても既存の書き方を維持できます。\n" +"(次の例では、`weights`、`scorers`、`schema_name`、`column_name`を省略していま" +"す。属性値の詳細については、後述の「構文」で記載します。ここでは、不要な属性" +"値が省略できることに注目してください。)" + +msgid "" +"```sql\n" +"title &@~ pgroonga_condition('keyword', index_name => 'index_name')\n" +"```" +msgstr "" + +msgid "" +"Please note that while using `pgroonga_condition()` function you can leave " +"out attribute values instead you need to describe comment like keyword " +"argument such as `index_name => 'index name'`." +msgstr "" +"`pgroonga_condition()`関数では、上のように属性値を省略できますが、代わりに、" +"「`index_name => 'index name'`」のようにキーワード引数のような記載が必要にな" +"ることに注意してください。" + +msgid "" +"In the above sample, there are mix of attribute values which is like keyword " +"argument or not.\n" +"How to separate writing is going to be explained in next [\"Syntax\"]" +"(#syntax).\n" +"The point here is there is need of different writing from the current." +msgstr "" +"上の例では、キーワード引数のような書き方をしている属性値とそうでない属性値が" +"あります。\n" +"どのように書き分けるかについては、後述の「構文」で記載します。\n" +"ここでは、従来とは異なる書き方が必要になることがあるという点に注目してくださ" +"い。" + +msgid "## Syntax" +msgstr "## 構文" + +msgid "Here is the syntax of this function:" +msgstr "この関数の構文は次の通りです。" + +msgid "" +"```\n" +"pgroonga_condition pgroonga_condition(keyword,\n" +" weights,\n" +" scorers,\n" +" schema_name,\n" +" index_name,\n" +" column_name)\n" +"```" +msgstr "" + +msgid "`keyword` is a keyword for full text search. It's `text` type." +msgstr "`keyword`は検索したいキーワードです。`text`型です。" + +msgid "`weights` is importance factors of each value. It's `int[]` type." +msgstr "`weights`は、検索対象のカラムの重要度です。`int[]`型です。" + +msgid "" +"`scorers` is [score compute procedures][scorer] of each value. It's `text[]` " +"type." +msgstr "" +"`scorers`は、検索対象のカラムのスコアーを計算する[スコアラー][scorer]です。" +"`text[]`型です。" + +msgid "" +"`schema_name` is the schema name to which the index that PGroonga refers to " +"when executing a sequential search belongs. It's `text` type." +msgstr "" +"`schema_name`は、シーケンシャルサーチ実行時に参照するインデックスが属するス" +"キーマの名前です。`text`型です。" + +msgid "" +"`index_name` is index name which PGroonga refer to when executing sequential " +"search. It's `text` type." +msgstr "" +"`index_name`は、シーケンシャルサーチ実行時に参照するインデックスの名前です。" +"`text`型です。" + +msgid "" +"`column_name` is the column name within the index which PGroonga refers to " +"when executing a sequential search. It's `text` type." +msgstr "" +"`column_name`は、シーケンシャルサーチ実行時に参照するインデックス内のカラムの" +"名前です。`text`型です" + +msgid "" +"All arguments of `pgroonga_condition()` are optional. If you want to specify " +"a particular argument, you can use [Named Notation][sql-syntax-calling-funcs-" +"named] such as `name => value` without relying on its position. For example, " +"if you specify only `index_name` argument, you can write " +"`pgroonga_condition(index_name => 'index1')`." +msgstr "" +"`pgroonga_condition()`の引数はすべて省略可能です。引数の位置に依らずに、特定" +"の引数を指定したい場合は[`引数名 => 値`][sql-syntax-calling-funcs-named]とい" +"う名前付き表記が使えます。たとえば、引数に`index_name`だけ指定する場合は" +"`pgroonga_condition(index_name => 'index1')`となります。" + +msgid "In general, it is enough to remember the following three cases." +msgstr "一般的なユースケースでは次の3種類の書き方を覚えておけば十分です。" + +msgid "" +"```sql\n" +"pgroonga_condition('keyword', index_name => 'pgroonga_index')\n" +"pgroonga_condition('keyword', ARRAY[weight1, weight2, ...])\n" +"pgroonga_condition('keyword', ARRAY[weight1, weight2, ...], index_name => " +"'pgroonga_index')\n" +"```" +msgstr "" + +msgid "" +"Please refer to [Calling Functions][sql-syntax-calling-funcs] for " +"information about the difference between when you need to write `name => " +"value` and when you don't." +msgstr "" +"上の例以外の使い方をする場合のために、`引数名 => 値`で記述する必要がある引数" +"とそうでない引数の違いについては、[関数呼び出し][sql-syntax-calling-funcs]を" +"参照してください。" + +msgid "## Usage" +msgstr "## 使い方" + +msgid "### Specify `index_name`" +msgstr "### `index_name`を指定する" + +msgid "" +"Introducing how to search with normalizer and tokeniser options specified in " +"the index while sequential search is executed." +msgstr "" +"シーケンシャルサーチ実行時でも、インデックスに指定したノーマライザーやトーク" +"ナイザーのオプションを使って検索する方法を紹介します。" + +msgid "" +"Use `pgroonga_condition('keyword', index_name => 'pgroonga_index')`.\n" +"Assign the name of index specified tokenizer or normalizer to `index_name`." +msgstr "" +"`pgroonga_condition('keyword', index_name => 'pgroonga_index')`を使います。\n" +"`index_name`にノーマライザーやトークナイザーを指定したインデックスの名前を指" +"定します。" + +msgid "Here are sample schema and data:" +msgstr "サンプルスキーマとデータは次の通りです。" + +msgid "" +"```sql\n" +"CREATE TABLE tags (\n" +" name text PRIMARY KEY\n" +");" +msgstr "" + +msgid "" +"CREATE INDEX pgroonga_tag_name_index ON tags\n" +" USING pgroonga (name pgroonga_text_term_search_ops_v2)\n" +" WITH (normalizers='NormalizerNFKC150(\"remove_symbol\", true)');" +msgstr "" + +msgid "" +"INSERT INTO tags VALUES ('PostgreSQL');\n" +"INSERT INTO tags VALUES ('Groonga');\n" +"INSERT INTO tags VALUES ('PGroonga');\n" +"INSERT INTO tags VALUES ('pglogical');\n" +"```" +msgstr "" + +msgid "" +"At the time of an index search, you can customize the behavior of the index " +"search by using the options specified to the index.\n" +"In the above example, the options are specified in the `normalizers='...'` " +"section." +msgstr "" +"インデックスサーチ時はインデックスに指定したオプションを使ってインデックス" +"サーチ時の挙動をカスタマイズできます。\n" +"上のサンプルでは、`normalizers='...'`の部分でオプションを指定しています。" + +msgid "" +"On the other hand, at the sequential search, the options specified to the " +"index cannot be referenced.\n" +"It is because there is no information which index to be referenced at the " +"sequential search." +msgstr "" +"一方、インデックスサーチではなくシーケンシャルサーチが実行されると、インデッ" +"クスに指定されているオプションは参照できません。\n" +"シーケンシャルサーチ時はどのインデックスを参照すればよいかという情報がないか" +"らです。" + +msgid "" +"Because of that, there is a possibility that the search results may differ " +"between a sequential search and an index search.\n" +"In order to avoid this issue, explicitly specify which index to be " +"referenced at the sequential search.\n" +"The `index_name => '...'` argument in `pgroonga_condition()` is used for " +"that." +msgstr "" +"そのためシーケンシャルサーチ実行時は、インデックスサーチ実行時と検索結果が異" +"なる可能性があります。\n" +"この問題を回避するためにシーケンシャルサーチ時に参照するインデックスを明示的" +"に指定します。\n" +"`pgroonga_condition()`の`index_name => '...'`がそのための引数です。" + +msgid "" +"The next example executes a prefix search with the keyword \"`_p_G`\" while " +"`NormalizerNFKC150(\"remove_symbol\", true)` is specified in the index.\n" +"Since [`remove_symbol`][remove-symbol] is the option to ignore the symbols, " +"\"`_p_G`\" is normalized to \"`pg`\".\n" +"(The reason why the capital letter \"`G`\" becomes a lowercase \"`g`\" is " +"not due to the `remove_symbol` option, but rather the default behavior of " +"`NormalizerNFKC150`.)\n" +"Therefore, both \"`PGroonga`\" and \"`pglogical`\" should be hit while this " +"option is active." +msgstr "" +"次の例は、「`_p_G`」というキーワードで前方一致検索をしており、インデックスに" +"は`NormalizerNFKC150(\"remove_symbol\", true)`が設定されています。\n" +"[`remove_symbol`][remove-symbol]は記号を無視するオプションなので、「`_p_G`」" +"は「`pg`」にノーマライズされます。\n" +"（大文字が小文字になっているのは、`remove_symbol`オプションの挙動ではなく、" +"`NormalizerNFKC150`のデフォルトの挙動によるものです。）\n" +"そのため、このオプションが有効であれば、「`PGroonga`」と「`pglogical`」がヒッ" +"トします。" + +msgid "" +"You can see that \"`PGroonga`\" and \"`pglogical`\" are hit as a result of " +"the sequential search.\n" +"This result shows that `NormalizerNFKC150(\"remove_symbol\", true)` " +"specified in the index is referenced even during sequential search execution." +msgstr "" +"次の例は、シーケンシャルサーチですが、「`PGroonga`」と「`pglogical`」がヒット" +"していることが確認できます。\n" +"このことから、シーケンシャルサーチ実行時でもインデックスに設定されている" +"`NormalizerNFKC150(\"remove_symbol\", true)`が参照できていることが確認できま" +"す。" + +msgid "" +"```sql\n" +"EXPLAIN ANALYZE\n" +"SELECT *\n" +" FROM tags\n" +" WHERE name &^ pgroonga_condition('_p_G',\n" +" index_name => 'pgroonga_tag_name_index');\n" +" QUERY PLAN\n" +"--------------------------------------------------------------------------------------------------\n" +" Seq Scan on tags (cost=0.00..1043.60 rows=1 width=32) (actual " +"time=2.267..2.336 rows=2 loops=1)\n" +" Filter: (name &^ '(_p_G,,,,pgroonga_tag_name_index,)'::" +"pgroonga_condition)\n" +" Rows Removed by Filter: 2\n" +" Planning Time: 0.871 ms\n" +" Execution Time: 2.352 ms\n" +"(5 rows)" +msgstr "" + +msgid "" +"SELECT *\n" +" FROM tags\n" +" WHERE name &^ pgroonga_condition('_p_G',\n" +" index_name => 'pgroonga_tag_name_index');\n" +" name\n" +"-----------\n" +" PGroonga\n" +" pglogical\n" +"(2 rows)\n" +"```" +msgstr "" + +msgid "" +"As you can see in next, \"`PGroonga`\" and \"`pglogical`\" would not be hit " +"when `index_name` is not specified. (This means that " +"`NormalizerNFKC150(\"remove_symbol\", true)` cannot be referenced.)" +msgstr "" +"`index_name`を指定しない場合（つまり、`NormalizerNFKC150(\"remove_symbol\", " +"true)`が参照できない場合）は、次のように「`PGroonga`」と「`pglogical`」はヒッ" +"トしません。" + +msgid "" +"```sql\n" +"EXPLAIN ANALYZE\n" +"SELECT *\n" +" FROM tags\n" +" WHERE name &^ pgroonga_condition('_p_G');\n" +" QUERY PLAN\n" +"--------------------------------------------------------------------------------------------------\n" +" Seq Scan on tags (cost=0.00..1043.60 rows=1 width=32) (actual " +"time=0.032..0.032 rows=0 loops=1)\n" +" Filter: (name &^ '(_p_G,,,,,)'::pgroonga_condition)\n" +" Rows Removed by Filter: 4\n" +" Planning Time: 0.910 ms\n" +" Execution Time: 0.053 ms\n" +"(5 rows)" +msgstr "" + +msgid "" +"SELECT *\n" +" FROM tags\n" +" WHERE name &^ pgroonga_condition('_p_G');" +msgstr "" + +msgid "" +" name\n" +"------\n" +"(0 rows)\n" +"```" +msgstr "" + +msgid "" +"In this way, by specifying `index_name`, you can ensure that the search " +"result remain the same whether executing a sequential search or an index " +"search." +msgstr "" +"このように、`index_name`を指定することで、シーケンシャルサーチ実行時でもイン" +"デックスサーチ実行時でも検索結果が変わらないようにできます。" + +msgid "### Specify `weights`" +msgstr "### `weights`を指定する" + +msgid "" +"Introducing how to specify different weights for each column.\n" +"This allows the title to be weighted more than the main text." +msgstr "" +"カラム毎に異なるweight（重要度）を設定する方法を紹介します。\n" +"これにより、「タイトルを本文よりも重要視する」を実現できます。" + +msgid "" +"Use `pgroonga_condition('keyword', ARRAY[weight1, weight2, ...])`.\n" +"`weight1`, `weight2`, and so on specify the weights for each column." +msgstr "" +"`pgroonga_condition('keyword', ARRAY[weight1, weight2, ...])` を使います。\n" +"`weight1`、 `weight2`でカラム毎の重要度を指定します。" + +msgid "" +"```sql\n" +"DROP TABLE IF EXISTS memos;\n" +"CREATE TABLE memos (\n" +" title text,\n" +" content text\n" +");" +msgstr "" + +msgid "" +"CREATE INDEX pgroonga_memos_index\n" +" ON memos\n" +" USING pgroonga ((ARRAY[title, content]));" +msgstr "" + +msgid "" +"INSERT INTO memos VALUES ('PostgreSQL', 'PostgreSQL is a relational database " +"management system.');\n" +"INSERT INTO memos VALUES ('Groonga', 'Groonga is the fast full text search " +"engine optimized for Japanese.');\n" +"INSERT INTO memos VALUES ('PGroonga', 'PGroonga is an extension for " +"PostgreSQL to use Groonga as the index.');\n" +"INSERT INTO memos VALUES ('command line', 'There is a groonga command.');\n" +"```" +msgstr "" +"INSERT INTO memos VALUES ('PostgreSQL', 'PostgreSQLはリレーショナル・データ" +"ベース管理システムです。');\n" +"INSERT INTO memos VALUES ('Groonga', 'Groongaは日本語対応の高速な全文検索エン" +"ジンです。');\n" +"INSERT INTO memos VALUES ('PGroonga', 'PGroongaはインデックスとしてGroongaを" +"使うためのPostgreSQLの拡張機能です。');\n" +"INSERT INTO memos VALUES ('コマンドライン', 'groongaコマンドがあります。');\n" +"```" + +msgid "" +"[`pgroonga_score function`][pgroonga-score-function] can be used to search " +"for records that match by the specified query." +msgstr "" +"指定したクエリーによりマッチしたレコードを探すためには[`pgroonga_score " +"function`][pgroonga-score-function]を使えます。" + +msgid "" +"```sql\n" +"SELECT *, pgroonga_score(tableoid, ctid) AS score\n" +" FROM memos\n" +" WHERE ARRAY[title, content] &@~\n" +" pgroonga_condition('Groonga OR PostgreSQL', ARRAY[5, 1])\n" +" ORDER BY score DESC;\n" +" title | " +"content | score \n" +"--------------" +"+----------------------------------------------------------------------" +"+-------\n" +" Groonga | Groonga is the fast full text search engine optimized for " +"Japanese. | 6\n" +" PostgreSQL | PostgreSQL is a relational database management " +"system. | 6\n" +" PGroonga | PGroonga is an extension for PostgreSQL to use Groonga as " +"the index. | 2\n" +" command line | There is a groonga " +"command. | 1\n" +"(4 rows)\n" +"```" +msgstr "" +"```sql\n" +"SELECT *, pgroonga_score(tableoid, ctid) AS score\n" +" FROM memos\n" +" WHERE ARRAY[title, content] &@~\n" +" pgroonga_condition('Groonga OR PostgreSQL', ARRAY[5, 1])\n" +" ORDER BY score DESC;\n" +" title | " +"content | score \n" +"----------------" +"+---------------------------------------------------------------------------" +"+-------\n" +" Groonga | Groongaは日本語対応の高速な全文検索エンジンで" +"す。 | 6\n" +" PostgreSQL | PostgreSQLはリレーショナル・データベース管理システムで" +"す。 | 6\n" +" PGroonga | PGroongaはインデックスとしてGroongaを使うためのPostgreSQLの" +"拡張機能です。 | 2\n" +" コマンドライン | groongaコマンドがありま" +"す。 | 1\n" +"(4 rows)\n" +"```" + +msgid "" +"In above example, the title is 5 times weighted that the main text because " +"`ARRAY[title, content] &@~ pgroonga_condition('Groonga OR PostgreSQL', " +"ARRAY[5, 1])` is specified.\n" +"You can see the score is higher for the records with `Groonga` or " +"`PostgreSQL` in the `title` column compared to records with `Groonga` or " +"`PostgreSQL` in the `content` column." +msgstr "" +"上の例では、`ARRAY[title, content] &@~ pgroonga_condition('Groonga OR " +"PostgreSQL', ARRAY[5, 1])`と指定しているので、タイトルが本文より5倍重要として" +"います。\n" +"`title`カラムに「`Groonga`」または「`PostgreSQL`」があるレコードの方が" +"`content`カラムに「`Groonga`」または「`PostgreSQL`」がある方よりスコアーが高" +"いことを確認できます。" + +msgid "### Exclude from search target" +msgstr "### 特定のカラムを検索対象から除外する" + +msgid "" +"Introducing how to search without specific columns as the search target." +msgstr "特定のカラムを検索対象から除外して検索する方法を紹介します。" + +msgid "" +"Use `pgroonga_condition('keyword', ARRAY[weight1, weight2, ...])`.\n" +"You need to specify `0` to `weight` of the column that would be excluded " +"from the search target." +msgstr "" +"`pgroonga_condition('keyword', ARRAY[weight1, weight2, ...])`を使います。\n" +"検索対象から除外したいカラムに対応する`weight`に`0`を指定します。" + +msgid "" +"In the next example, the `content` column is excluded from the search " +"target.\n" +"The record, `'PGroonga is an extension for PostgreSQL to use Groonga as the " +"index.'`, should be hit if the `content` column is included in the search " +"target with the search keyword is \"`extension`\", but the record is not " +"hit.\n" +"You can see that the `content` column is excluded from the search target." +msgstr "" +"次の例では、`content`カラムを検索対象から除外しています。\n" +"「`拡張`」というキーワードで全文検索しているので、`content`カラムを検索対象と" +"していれば、`'PGroongaはインデックスとしてGroongaを使うためのPostgreSQLの拡張" +"機能です。'`がヒットするはずですが、このレコードはヒットしていません。\n" +"このことから、`content`カラムが検索対象から除外されていることを確認できます。" + +msgid "" +"```sql\n" +"SELECT *\n" +" FROM memos\n" +" WHERE ARRAY[title, content] &@~\n" +" pgroonga_condition('extension', ARRAY[1, 0]);\n" +" title | content \n" +"-------+---------\n" +"(0 rows)\n" +"```" +msgstr "" +"```sql\n" +"SELECT *\n" +" FROM memos\n" +" WHERE ARRAY[title, content] &@~\n" +" pgroonga_condition('拡張', ARRAY[1, 0]);\n" +" title | content\n" +"-------+---------\n" +"(0 rows)\n" +"```" + +msgid "" +"As the `content` column is set as the search target in the next example, the " +"record `'PGroonga is an extension for PostgreSQL to use Groonga as an " +"index.'` is hit." +msgstr "" +"次のように、`content`カラムを検索対象にすると`'PGroongaはインデックスとして" +"Groongaを使うためのPostgreSQLの拡張機能です。'`がヒットします。" + +msgid "" +"```sql\n" +"SELECT *\n" +" FROM memos\n" +" WHERE ARRAY[title, content] &@~\n" +" pgroonga_condition('extension', ARRAY[1, 1]);\n" +" title | " +"content \n" +"----------" +"+----------------------------------------------------------------------\n" +" PGroonga | PGroonga is an extension for PostgreSQL to use Groonga as the " +"index.\n" +"(1 row)\n" +"```" +msgstr "" +"```sql\n" +"SELECT *\n" +" FROM memos\n" +" WHERE ARRAY[title, content] &@~\n" +" pgroonga_condition('拡張', ARRAY[1, 1]);\n" +" title | content\n" +"----------" +"+---------------------------------------------------------------------------\n" +" PGroonga | PGroongaはインデックスとしてGroongaを使うためのPostgreSQLの拡張機" +"能です。\n" +"(1 row)\n" +"```" + +msgid "## See also" +msgstr "## 参考" + +msgid "* [Calling Functions][sql-syntax-calling-funcs]" +msgstr "* [関数呼び出し][sql-syntax-calling-funcs]" + +msgid "* [Named Notation][sql-syntax-calling-funcs-named]" +msgstr "* [名前付け表記の使用][sql-syntax-calling-funcs-named]" + +msgid "* [normalizers_mapping][normalizers-mapping]" +msgstr "" + +msgid "* [pgroonga_score function][pgroonga-score-function]" +msgstr "* [pgroonga_score関数][pgroonga-score-function]" + +msgid "* [postgres_fdw][postgres-fdw]" +msgstr "" + +msgid "* [remove_symbol][remove-symbol]" +msgstr "" + +msgid "* [score compute procedures][scorer]" +msgstr "* [スコア計算について][scorer]" + +msgid "" +"[sql-syntax-calling-funcs]:{{ site.postgresql_doc_base_url.en }}/sql-syntax-" +"calling-funcs.html" +msgstr "" +"[sql-syntax-calling-funcs]:{{ site.postgresql_doc_base_url.ja }}/sql-syntax-" +"calling-funcs.html" + +msgid "" +"[sql-syntax-calling-funcs-named]:{{ site.postgresql_doc_base_url.en }}/sql-" +"syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-NAMED" +msgstr "" +"[sql-syntax-calling-funcs-named]:{{ site.postgresql_doc_base_url.ja }}/sql-" +"syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-NAMED" + +msgid "" +"[normalizers-mapping]:../create-index-using-pgroonga.html#custom-normalizer" +msgstr "" + +msgid "[pgroonga-score-function]:pgroonga-score.html" +msgstr "" + +msgid "[postgres-fdw]:{{ site.postgresql_doc_base_url.en }}/postgres-fdw.html" +msgstr "[postgres-fdw]:{{ site.postgresql_doc_base_url.ja }}/postgres-fdw.html" + +msgid "" +"[remove-symbol]:https://groonga.org/docs/reference/normalizers/" +"normalizer_nfkc150.html#remove-symbol" +msgstr "" +"[remove-symbol]:https://groonga.org/ja/docs/reference/normalizers/" +"normalizer_nfkc150.html#normalizer-nfkc150-remove-symbol" + +msgid "[scorer]:https://groonga.org/docs/reference/scorer.html" +msgstr "[scorer]:https://groonga.org/ja/docs/reference/scorer.html" diff --git a/_po/ja/reference/index.po b/_po/ja/reference/index.po index d59286bec..ae9a52923 100644 --- a/_po/ja/reference/index.po +++ b/_po/ja/reference/index.po @@ -627,6 +627,9 @@ msgstr " * [`pgroonga_command`関数][command]" msgid " * [`pgroonga_command_escape_value` function][command-escape-value]" msgstr " * [`pgroonga_command_escape_value`関数][command-escape-value]" +msgid " * [`pgroonga_condition` function][condition]" +msgstr " * [`pgroonga_condition`関数][escape]" + msgid " * [`pgroonga_escape` function][escape]" msgstr " * [`pgroonga_escape`関数][escape]" @@ -1002,6 +1005,7 @@ msgstr "" msgid "" "[command]:functions/pgroonga-command.html\n" +"[condition]:functions/pgroonga-condition.html\n" "[command-escape-value]:functions/pgroonga-command-escape-value.html\n" "[escape]:functions/pgroonga-escape.html\n" "[flush]:functions/pgroonga-flush.html\n" diff --git a/ja/reference/functions/pgroonga-condition.md b/ja/reference/functions/pgroonga-condition.md new file mode 100644 index 000000000..1489bdb82 --- /dev/null +++ b/ja/reference/functions/pgroonga-condition.md @@ -0,0 +1,314 @@ +--- +title: pgroonga_condition 関数 +upper_level: ../ +--- + +# `pgroonga_condition()` 関数 + +3.1.6で追加。 + +## 概要 + +`pgroonga_condition()`関数は`pgroonga_condition`型の値を返します。 +関数名と型名が同じですが別物です。 +`pgroonga_condition`型は`pgroonga_full_text_search_condition`型や`pgroonga_full_text_search_condition_with_scorers`型のように複雑な条件式を表現します。 + +`pgroonga_condition()`関数は`pgroonga_condition`型の値を作るための便利関数です。 +特定の属性値のみを指定して`pgroonga_condition`型の値を作れます。 + +`pgroonga_full_text_search_condition`型や`pgroonga_full_text_search_condition_with_scorers`型では、このような便利関数がなかったため必ず全ての属性値を指定して値を作る必要がありました。 + +したがって、不要な属性値があっても、`pgroonga_full_text_search_condition`型や`pgroonga_full_text_search_condition_with_scorers`型では、次のように不要な属性値には`NULL`を指定する必要がありました。 + +```sql +title &@~ ('keyword', NULL, 'index_name')::pgroonga_full_text_search_condition +title &@~ ('keyword', ARRAY[1,1,1,5,0], NULL, 'index_name')::pgroonga_full_text_search_condition_with_scorers +``` + +型を指定して直接値を作る従来の方法では後方互換性を維持したまま新しい属性を作ることができませんでした。 +そのため、新しい属性を追加するたびに`pgroonga_full_text_search_condition_with_XXX`というような新しい型を追加する必要がありました。 +たとえば、`pgroogna_full_text_search_condition_with_scorers`型はそのために追加された型です。 + +`pgroonga_full_text_search_condition`型と`pgroonga_full_text_search_condition_with_scorers`型の違いは`scorers`が存在するかどうかですが、`pgroonga_full_text_search_condition`型に`scorers`を追加してしまうと、`scorers`を使わないユーザーも新たに`NULL`を挿入して`pgroonga_full_text_search_condition`型の値を作らなければなりません。 + +しかし、`pgroonga_condition`型の値を作るための便利関数`pgroonga_condition()`関数を導入することにより後方互換性を維持したまま`pgroonga_condition`型に新しい属性を追加できます。 +`pgroonga_condition()`関数が非互換を吸収してくれるからです。 + +次のように、`pgroonga_condition()`関数は不要な属性値を省略できるため、新たに属性値が追加されても既存の書き方を維持できます。 +(次の例では、`weights`、`scorers`、`schema_name`、`column_name`を省略しています。属性値の詳細については、後述の「構文」で記載します。ここでは、不要な属性値が省略できることに注目してください。) + +```sql +title &@~ pgroonga_condition('keyword', index_name => 'index_name') +``` + +`pgroonga_condition()`関数では、上のように属性値を省略できますが、代わりに、「`index_name => 'index name'`」のようにキーワード引数のような記載が必要になることに注意してください。 + +上の例では、キーワード引数のような書き方をしている属性値とそうでない属性値があります。 +どのように書き分けるかについては、後述の「構文」で記載します。 +ここでは、従来とは異なる書き方が必要になることがあるという点に注目してください。 + +## 構文 + +この関数の構文は次の通りです。 + +``` +pgroonga_condition pgroonga_condition(keyword, + weights, + scorers, + schema_name, + index_name, + column_name) +``` + +`keyword`は検索したいキーワードです。`text`型です。 + +`weights`は、検索対象のカラムの重要度です。`int[]`型です。 + +`scorers`は、検索対象のカラムのスコアーを計算する[スコアラー][scorer]です。`text[]`型です。 + +`schema_name`は、シーケンシャルサーチ実行時に参照するインデックスが属するスキーマの名前です。`text`型です。 + +`index_name`は、シーケンシャルサーチ実行時に参照するインデックスの名前です。`text`型です。 + +`column_name`は、シーケンシャルサーチ実行時に参照するインデックス内のカラムの名前です。`text`型です + +`pgroonga_condition()`の引数はすべて省略可能です。引数の位置に依らずに、特定の引数を指定したい場合は[`引数名 => 値`][sql-syntax-calling-funcs-named]という名前付き表記が使えます。たとえば、引数に`index_name`だけ指定する場合は`pgroonga_condition(index_name => 'index1')`となります。 + +一般的なユースケースでは次の3種類の書き方を覚えておけば十分です。 + +```sql +pgroonga_condition('keyword', index_name => 'pgroonga_index') +pgroonga_condition('keyword', ARRAY[weight1, weight2, ...]) +pgroonga_condition('keyword', ARRAY[weight1, weight2, ...], index_name => 'pgroonga_index') +``` + +上の例以外の使い方をする場合のために、`引数名 => 値`で記述する必要がある引数とそうでない引数の違いについては、[関数呼び出し][sql-syntax-calling-funcs]を参照してください。 + +## 使い方 + +### `index_name`を指定する + +シーケンシャルサーチ実行時でも、インデックスに指定したノーマライザーやトークナイザーのオプションを使って検索する方法を紹介します。 + +`pgroonga_condition('keyword', index_name => 'pgroonga_index')`を使います。 +`index_name`にノーマライザーやトークナイザーを指定したインデックスの名前を指定します。 + +サンプルスキーマとデータは次の通りです。 + +```sql +CREATE TABLE tags ( + name text PRIMARY KEY +); + +CREATE INDEX pgroonga_tag_name_index ON tags + USING pgroonga (name pgroonga_text_term_search_ops_v2) + WITH (normalizers='NormalizerNFKC150("remove_symbol", true)'); + +INSERT INTO tags VALUES ('PostgreSQL'); +INSERT INTO tags VALUES ('Groonga'); +INSERT INTO tags VALUES ('PGroonga'); +INSERT INTO tags VALUES ('pglogical'); +``` + +インデックスサーチ時はインデックスに指定したオプションを使ってインデックスサーチ時の挙動をカスタマイズできます。 +上のサンプルでは、`normalizers='...'`の部分でオプションを指定しています。 + +一方、インデックスサーチではなくシーケンシャルサーチが実行されると、インデックスに指定されているオプションは参照できません。 +シーケンシャルサーチ時はどのインデックスを参照すればよいかという情報がないからです。 + +そのためシーケンシャルサーチ実行時は、インデックスサーチ実行時と検索結果が異なる可能性があります。 +この問題を回避するためにシーケンシャルサーチ時に参照するインデックスを明示的に指定します。 +`pgroonga_condition()`の`index_name => '...'`がそのための引数です。 + + +次の例は、「`_p_G`」というキーワードで前方一致検索をしており、インデックスには`NormalizerNFKC150("remove_symbol", true)`が設定されています。 +[`remove_symbol`][remove-symbol]は記号を無視するオプションなので、「`_p_G`」は「`pg`」にノーマライズされます。 +（大文字が小文字になっているのは、`remove_symbol`オプションの挙動ではなく、`NormalizerNFKC150`のデフォルトの挙動によるものです。） +そのため、このオプションが有効であれば、「`PGroonga`」と「`pglogical`」がヒットします。 + +次の例は、シーケンシャルサーチですが、「`PGroonga`」と「`pglogical`」がヒットしていることが確認できます。 +このことから、シーケンシャルサーチ実行時でもインデックスに設定されている`NormalizerNFKC150("remove_symbol", true)`が参照できていることが確認できます。 + +```sql +EXPLAIN ANALYZE +SELECT * + FROM tags + WHERE name &^ pgroonga_condition('_p_G', + index_name => 'pgroonga_tag_name_index'); + QUERY PLAN +-------------------------------------------------------------------------------------------------- + Seq Scan on tags (cost=0.00..1043.60 rows=1 width=32) (actual time=2.267..2.336 rows=2 loops=1) + Filter: (name &^ '(_p_G,,,,pgroonga_tag_name_index,)'::pgroonga_condition) + Rows Removed by Filter: 2 + Planning Time: 0.871 ms + Execution Time: 2.352 ms +(5 rows) + +SELECT * + FROM tags + WHERE name &^ pgroonga_condition('_p_G', + index_name => 'pgroonga_tag_name_index'); + name +----------- + PGroonga + pglogical +(2 rows) +``` + +`index_name`を指定しない場合（つまり、`NormalizerNFKC150("remove_symbol", true)`が参照できない場合）は、次のように「`PGroonga`」と「`pglogical`」はヒットしません。 + +```sql +EXPLAIN ANALYZE +SELECT * + FROM tags + WHERE name &^ pgroonga_condition('_p_G'); + QUERY PLAN +-------------------------------------------------------------------------------------------------- + Seq Scan on tags (cost=0.00..1043.60 rows=1 width=32) (actual time=0.032..0.032 rows=0 loops=1) + Filter: (name &^ '(_p_G,,,,,)'::pgroonga_condition) + Rows Removed by Filter: 4 + Planning Time: 0.910 ms + Execution Time: 0.053 ms +(5 rows) + +SELECT * + FROM tags + WHERE name &^ pgroonga_condition('_p_G'); + + name +------ +(0 rows) +``` + +このように、`index_name`を指定することで、シーケンシャルサーチ実行時でもインデックスサーチ実行時でも検索結果が変わらないようにできます。 + +### `weights`を指定する + +カラム毎に異なるweight（重要度）を設定する方法を紹介します。 +これにより、「タイトルを本文よりも重要視する」を実現できます。 + +`pgroonga_condition('keyword', ARRAY[weight1, weight2, ...])` を使います。 +`weight1`、 `weight2`でカラム毎の重要度を指定します。 + +サンプルスキーマとデータは次の通りです。 + +```sql +DROP TABLE IF EXISTS memos; +CREATE TABLE memos ( + title text, + content text +); + +CREATE INDEX pgroonga_memos_index + ON memos + USING pgroonga ((ARRAY[title, content])); + +INSERT INTO memos VALUES ('PostgreSQL', 'PostgreSQLはリレーショナル・データベース管理システムです。'); +INSERT INTO memos VALUES ('Groonga', 'Groongaは日本語対応の高速な全文検索エンジンです。'); +INSERT INTO memos VALUES ('PGroonga', 'PGroongaはインデックスとしてGroongaを使うためのPostgreSQLの拡張機能です。'); +INSERT INTO memos VALUES ('コマンドライン', 'groongaコマンドがあります。'); +``` + +指定したクエリーによりマッチしたレコードを探すためには[`pgroonga_score function`][pgroonga-score-function]を使えます。 + +```sql +SELECT *, pgroonga_score(tableoid, ctid) AS score + FROM memos + WHERE ARRAY[title, content] &@~ + pgroonga_condition('Groonga OR PostgreSQL', ARRAY[5, 1]) + ORDER BY score DESC; + title | content | score +----------------+---------------------------------------------------------------------------+------- + Groonga | Groongaは日本語対応の高速な全文検索エンジンです。 | 6 + PostgreSQL | PostgreSQLはリレーショナル・データベース管理システムです。 | 6 + PGroonga | PGroongaはインデックスとしてGroongaを使うためのPostgreSQLの拡張機能です。 | 2 + コマンドライン | groongaコマンドがあります。 | 1 +(4 rows) +``` + +上の例では、`ARRAY[title, content] &@~ pgroonga_condition('Groonga OR PostgreSQL', ARRAY[5, 1])`と指定しているので、タイトルが本文より5倍重要としています。 +`title`カラムに「`Groonga`」または「`PostgreSQL`」があるレコードの方が`content`カラムに「`Groonga`」または「`PostgreSQL`」がある方よりスコアーが高いことを確認できます。 + +### 特定のカラムを検索対象から除外する + +特定のカラムを検索対象から除外して検索する方法を紹介します。 + +`pgroonga_condition('keyword', ARRAY[weight1, weight2, ...])`を使います。 +検索対象から除外したいカラムに対応する`weight`に`0`を指定します。 + +サンプルスキーマとデータは次の通りです。 + +```sql +DROP TABLE IF EXISTS memos; +CREATE TABLE memos ( + title text, + content text +); + +CREATE INDEX pgroonga_memos_index + ON memos + USING pgroonga ((ARRAY[title, content])); + +INSERT INTO memos VALUES ('PostgreSQL', 'PostgreSQLはリレーショナル・データベース管理システムです。'); +INSERT INTO memos VALUES ('Groonga', 'Groongaは日本語対応の高速な全文検索エンジンです。'); +INSERT INTO memos VALUES ('PGroonga', 'PGroongaはインデックスとしてGroongaを使うためのPostgreSQLの拡張機能です。'); +INSERT INTO memos VALUES ('コマンドライン', 'groongaコマンドがあります。'); +``` + +次の例では、`content`カラムを検索対象から除外しています。 +「`拡張`」というキーワードで全文検索しているので、`content`カラムを検索対象としていれば、`'PGroongaはインデックスとしてGroongaを使うためのPostgreSQLの拡張機能です。'`がヒットするはずですが、このレコードはヒットしていません。 +このことから、`content`カラムが検索対象から除外されていることを確認できます。 + +```sql +SELECT * + FROM memos + WHERE ARRAY[title, content] &@~ + pgroonga_condition('拡張', ARRAY[1, 0]); + title | content +-------+--------- +(0 rows) +``` + +次のように、`content`カラムを検索対象にすると`'PGroongaはインデックスとしてGroongaを使うためのPostgreSQLの拡張機能です。'`がヒットします。 + +```sql +SELECT * + FROM memos + WHERE ARRAY[title, content] &@~ + pgroonga_condition('拡張', ARRAY[1, 1]); + title | content +----------+--------------------------------------------------------------------------- + PGroonga | PGroongaはインデックスとしてGroongaを使うためのPostgreSQLの拡張機能です。 +(1 row) +``` + +## 参考 + +* [関数呼び出し][sql-syntax-calling-funcs] + +* [名前付け表記の使用][sql-syntax-calling-funcs-named] + +* [normalizers_mapping][normalizers-mapping] + +* [pgroonga_score関数][pgroonga-score-function] + +* [postgres_fdw][postgres-fdw] + +* [remove_symbol][remove-symbol] + +* [スコア計算について][scorer] + + +[sql-syntax-calling-funcs]:{{ site.postgresql_doc_base_url.ja }}/sql-syntax-calling-funcs.html + +[sql-syntax-calling-funcs-named]:{{ site.postgresql_doc_base_url.ja }}/sql-syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-NAMED + +[normalizers-mapping]:../create-index-using-pgroonga.html#custom-normalizer + +[pgroonga-score-function]:pgroonga-score.html + +[postgres-fdw]:{{ site.postgresql_doc_base_url.ja }}/postgres-fdw.html + +[remove-symbol]:https://groonga.org/ja/docs/reference/normalizers/normalizer_nfkc150.html#normalizer-nfkc150-remove-symbol + +[scorer]:https://groonga.org/ja/docs/reference/scorer.html diff --git a/ja/reference/index.md b/ja/reference/index.md index fd0f04901..fa3de2ef1 100644 --- a/ja/reference/index.md +++ b/ja/reference/index.md @@ -525,6 +525,8 @@ PGroongaは`pgroonga`スキーマに関数・演算子・演算子クラスな * [`pgroonga_command_escape_value`関数][command-escape-value] + * [`pgroonga_condition`関数][escape] + * [`pgroonga_escape`関数][escape] * [`pgroonga_flush`関数][flush] @@ -749,6 +751,7 @@ PGroongaは`pgroonga`スキーマに関数・演算子・演算子クラスな [upgrade-incompatible]:../upgrade/#incompatible-case [command]:functions/pgroonga-command.html +[condition]:functions/pgroonga-condition.html [command-escape-value]:functions/pgroonga-command-escape-value.html [escape]:functions/pgroonga-escape.html [flush]:functions/pgroonga-flush.html diff --git a/reference/functions/pgroonga-condition.md b/reference/functions/pgroonga-condition.md new file mode 100644 index 000000000..8a8115de9 --- /dev/null +++ b/reference/functions/pgroonga-condition.md @@ -0,0 +1,314 @@ +--- +title: pgroonga_condition function +upper_level: ../ +--- + +# `pgroonga_condition()` function + +Since 3.1.6. + +## Summary + +`pgroonga_condition()` function returns `pgroonga_condition` type value. +The function and the type have same name, but they are two different things. +`pgroonga_condition` type represents complicated conditional expressions, such as `pgroonga_full_text_search_condition` type and `pgroonga_full_text_search_condition_with_scorers` type. + +`pgroonga_condition()` function is a useful function to make the `pgroonga_condition` type value. +It allows to make the `pgroonga_condition` type value by designating the specific attribute values. + +There were not this kind of useful functions for `pgroonga_full_text_search_condition` type and `pgroonga_full_text_search_condition_with_scorers` type, so designating all attribute values was necessary to make the value. + +Therefore, you need to designate `NULL` for disused attribute value as follows when `pgroonga_full_text_search_condition` type and `pgroonga_full_text_search_condition_with_scorers` type are used to avoid making all the values. + +```sql +title &@~ ('keyword', NULL, 'index_name')::pgroonga_full_text_search_condition +title &@~ ('keyword', ARRAY[1,1,1,5,0], NULL, 'index_name')::pgroonga_full_text_search_condition_with_scorers +``` + +It was not possible for existing value creation methods to make new attribute value while keeping backward compatibility. +Thus, it was necessary to add a new type every time when a new attribute value is added, such as `pgroonga_full_text_search_condition_with_XXX` type. +For example, `pgroogna_full_text_search_condition_with_scorers` type was added because of the added new attribute. + +The difference between `pgroonga_full_text_search_condition` type and `pgroonga_full_text_search_condition_with_scorers` type is whether `scorers` exist or not. If `scorers` is added to `pgroonga_full_text_search_condition` type, every users are required to insert new `NULL` to make `pgroonga_full_text_search_condition` type regardless of `scorers` usage. + +However, installing `pgroonga_condition()` function to make new `pgroonga_condition` type value let a new attribute to be added while keeping backward compatibility. +It is because `pgroonga_condition()` function absorbs incompatibility. + +`pgroonga_condition()` function lets current writing style when a new attribute value is added because the function can leave out unnecessary attribute value as following sample. +(In the following sample, `weights`, `scorers`, `schema_name` and `column_name` are left out. The details of attribute values would be noted in next ["Syntax"](#syntax). Here, point is that possibility of leaving out unnecessary attribute values.) + +```sql +title &@~ pgroonga_condition('keyword', index_name => 'index_name') +``` + +Please note that while using `pgroonga_condition()` function you can leave out attribute values instead you need to describe comment like keyword argument such as `index_name => 'index name'`. + +In the above sample, there are mix of attribute values which is like keyword argument or not. +How to separate writing is going to be explained in next ["Syntax"](#syntax). +The point here is there is need of different writing from the current. + +## Syntax + +Here is the syntax of this function: + +``` +pgroonga_condition pgroonga_condition(keyword, + weights, + scorers, + schema_name, + index_name, + column_name) +``` + +`keyword` is a keyword for full text search. It's `text` type. + +`weights` is importance factors of each value. It's `int[]` type. + +`scorers` is [score compute procedures][scorer] of each value. It's `text[]` type. + +`schema_name` is the schema name to which the index that PGroonga refers to when executing a sequential search belongs. It's `text` type. + +`index_name` is index name which PGroonga refer to when executing sequential search. It's `text` type. + +`column_name` is the column name within the index which PGroonga refers to when executing a sequential search. It's `text` type. + +All arguments of `pgroonga_condition()` are optional. If you want to specify a particular argument, you can use [Named Notation][sql-syntax-calling-funcs-named] such as `name => value` without relying on its position. For example, if you specify only `index_name` argument, you can write `pgroonga_condition(index_name => 'index1')`. + +In general, it is enough to remember the following three cases. + +```sql +pgroonga_condition('keyword', index_name => 'pgroonga_index') +pgroonga_condition('keyword', ARRAY[weight1, weight2, ...]) +pgroonga_condition('keyword', ARRAY[weight1, weight2, ...], index_name => 'pgroonga_index') +``` + +Please refer to [Calling Functions][sql-syntax-calling-funcs] for information about the difference between when you need to write `name => value` and when you don't. + +## Usage + +### Specify `index_name` + +Introducing how to search with normalizer and tokeniser options specified in the index while sequential search is executed. + +Use `pgroonga_condition('keyword', index_name => 'pgroonga_index')`. +Assign the name of index specified tokenizer or normalizer to `index_name`. + +Here are sample schema and data: + +```sql +CREATE TABLE tags ( + name text PRIMARY KEY +); + +CREATE INDEX pgroonga_tag_name_index ON tags + USING pgroonga (name pgroonga_text_term_search_ops_v2) + WITH (normalizers='NormalizerNFKC150("remove_symbol", true)'); + +INSERT INTO tags VALUES ('PostgreSQL'); +INSERT INTO tags VALUES ('Groonga'); +INSERT INTO tags VALUES ('PGroonga'); +INSERT INTO tags VALUES ('pglogical'); +``` + +At the time of an index search, you can customize the behavior of the index search by using the options specified to the index. +In the above example, the options are specified in the `normalizers='...'` section. + +On the other hand, at the sequential search, the options specified to the index cannot be referenced. +It is because there is no information which index to be referenced at the sequential search. + +Because of that, there is a possibility that the search results may differ between a sequential search and an index search. +In order to avoid this issue, explicitly specify which index to be referenced at the sequential search. +The `index_name => '...'` argument in `pgroonga_condition()` is used for that. + + +The next example executes a prefix search with the keyword "`_p_G`" while `NormalizerNFKC150("remove_symbol", true)` is specified in the index. +Since [`remove_symbol`][remove-symbol] is the option to ignore the symbols, "`_p_G`" is normalized to "`pg`". +(The reason why the capital letter "`G`" becomes a lowercase "`g`" is not due to the `remove_symbol` option, but rather the default behavior of `NormalizerNFKC150`.) +Therefore, both "`PGroonga`" and "`pglogical`" should be hit while this option is active. + +You can see that "`PGroonga`" and "`pglogical`" are hit as a result of the sequential search. +This result shows that `NormalizerNFKC150("remove_symbol", true)` specified in the index is referenced even during sequential search execution. + +```sql +EXPLAIN ANALYZE +SELECT * + FROM tags + WHERE name &^ pgroonga_condition('_p_G', + index_name => 'pgroonga_tag_name_index'); + QUERY PLAN +-------------------------------------------------------------------------------------------------- + Seq Scan on tags (cost=0.00..1043.60 rows=1 width=32) (actual time=2.267..2.336 rows=2 loops=1) + Filter: (name &^ '(_p_G,,,,pgroonga_tag_name_index,)'::pgroonga_condition) + Rows Removed by Filter: 2 + Planning Time: 0.871 ms + Execution Time: 2.352 ms +(5 rows) + +SELECT * + FROM tags + WHERE name &^ pgroonga_condition('_p_G', + index_name => 'pgroonga_tag_name_index'); + name +----------- + PGroonga + pglogical +(2 rows) +``` + +As you can see in next, "`PGroonga`" and "`pglogical`" would not be hit when `index_name` is not specified. (This means that `NormalizerNFKC150("remove_symbol", true)` cannot be referenced.) + +```sql +EXPLAIN ANALYZE +SELECT * + FROM tags + WHERE name &^ pgroonga_condition('_p_G'); + QUERY PLAN +-------------------------------------------------------------------------------------------------- + Seq Scan on tags (cost=0.00..1043.60 rows=1 width=32) (actual time=0.032..0.032 rows=0 loops=1) + Filter: (name &^ '(_p_G,,,,,)'::pgroonga_condition) + Rows Removed by Filter: 4 + Planning Time: 0.910 ms + Execution Time: 0.053 ms +(5 rows) + +SELECT * + FROM tags + WHERE name &^ pgroonga_condition('_p_G'); + + name +------ +(0 rows) +``` + +In this way, by specifying `index_name`, you can ensure that the search result remain the same whether executing a sequential search or an index search. + +### Specify `weights` + +Introducing how to specify different weights for each column. +This allows the title to be weighted more than the main text. + +Use `pgroonga_condition('keyword', ARRAY[weight1, weight2, ...])`. +`weight1`, `weight2`, and so on specify the weights for each column. + +Here are sample schema and data: + +```sql +DROP TABLE IF EXISTS memos; +CREATE TABLE memos ( + title text, + content text +); + +CREATE INDEX pgroonga_memos_index + ON memos + USING pgroonga ((ARRAY[title, content])); + +INSERT INTO memos VALUES ('PostgreSQL', 'PostgreSQL is a relational database management system.'); +INSERT INTO memos VALUES ('Groonga', 'Groonga is the fast full text search engine optimized for Japanese.'); +INSERT INTO memos VALUES ('PGroonga', 'PGroonga is an extension for PostgreSQL to use Groonga as the index.'); +INSERT INTO memos VALUES ('command line', 'There is a groonga command.'); +``` + +[`pgroonga_score function`][pgroonga-score-function] can be used to search for records that match by the specified query. + +```sql +SELECT *, pgroonga_score(tableoid, ctid) AS score + FROM memos + WHERE ARRAY[title, content] &@~ + pgroonga_condition('Groonga OR PostgreSQL', ARRAY[5, 1]) + ORDER BY score DESC; + title | content | score +--------------+----------------------------------------------------------------------+------- + Groonga | Groonga is the fast full text search engine optimized for Japanese. | 6 + PostgreSQL | PostgreSQL is a relational database management system. | 6 + PGroonga | PGroonga is an extension for PostgreSQL to use Groonga as the index. | 2 + command line | There is a groonga command. | 1 +(4 rows) +``` + +In above example, the title is 5 times weighted that the main text because `ARRAY[title, content] &@~ pgroonga_condition('Groonga OR PostgreSQL', ARRAY[5, 1])` is specified. +You can see the score is higher for the records with `Groonga` or `PostgreSQL` in the `title` column compared to records with `Groonga` or `PostgreSQL` in the `content` column. + +### Exclude from search target + +Introducing how to search without specific columns as the search target. + +Use `pgroonga_condition('keyword', ARRAY[weight1, weight2, ...])`. +You need to specify `0` to `weight` of the column that would be excluded from the search target. + +Here are sample schema and data: + +```sql +DROP TABLE IF EXISTS memos; +CREATE TABLE memos ( + title text, + content text +); + +CREATE INDEX pgroonga_memos_index + ON memos + USING pgroonga ((ARRAY[title, content])); + +INSERT INTO memos VALUES ('PostgreSQL', 'PostgreSQL is a relational database management system.'); +INSERT INTO memos VALUES ('Groonga', 'Groonga is the fast full text search engine optimized for Japanese.'); +INSERT INTO memos VALUES ('PGroonga', 'PGroonga is an extension for PostgreSQL to use Groonga as the index.'); +INSERT INTO memos VALUES ('command line', 'There is a groonga command.'); +``` + +In the next example, the `content` column is excluded from the search target. +The record, `'PGroonga is an extension for PostgreSQL to use Groonga as the index.'`, should be hit if the `content` column is included in the search target with the search keyword is "`extension`", but the record is not hit. +You can see that the `content` column is excluded from the search target. + +```sql +SELECT * + FROM memos + WHERE ARRAY[title, content] &@~ + pgroonga_condition('extension', ARRAY[1, 0]); + title | content +-------+--------- +(0 rows) +``` + +As the `content` column is set as the search target in the next example, the record `'PGroonga is an extension for PostgreSQL to use Groonga as an index.'` is hit. + +```sql +SELECT * + FROM memos + WHERE ARRAY[title, content] &@~ + pgroonga_condition('extension', ARRAY[1, 1]); + title | content +----------+---------------------------------------------------------------------- + PGroonga | PGroonga is an extension for PostgreSQL to use Groonga as the index. +(1 row) +``` + +## See also + +* [Calling Functions][sql-syntax-calling-funcs] + +* [Named Notation][sql-syntax-calling-funcs-named] + +* [normalizers_mapping][normalizers-mapping] + +* [pgroonga_score function][pgroonga-score-function] + +* [postgres_fdw][postgres-fdw] + +* [remove_symbol][remove-symbol] + +* [score compute procedures][scorer] + + +[sql-syntax-calling-funcs]:{{ site.postgresql_doc_base_url.en }}/sql-syntax-calling-funcs.html + +[sql-syntax-calling-funcs-named]:{{ site.postgresql_doc_base_url.en }}/sql-syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-NAMED + +[normalizers-mapping]:../create-index-using-pgroonga.html#custom-normalizer + +[pgroonga-score-function]:pgroonga-score.html + +[postgres-fdw]:{{ site.postgresql_doc_base_url.en }}/postgres-fdw.html + +[remove-symbol]:https://groonga.org/docs/reference/normalizers/normalizer_nfkc150.html#remove-symbol + +[scorer]:https://groonga.org/docs/reference/scorer.html diff --git a/reference/index.md b/reference/index.md index 77196f18a..ab654c06c 100644 --- a/reference/index.md +++ b/reference/index.md @@ -523,6 +523,8 @@ Use [`pgroonga_jsonb_ops_v2` operator class](#text-jsonb-ops-v2) instead. * [`pgroonga_command_escape_value` function][command-escape-value] + * [`pgroonga_condition` function][condition] + * [`pgroonga_escape` function][escape] * [`pgroonga_flush` function][flush] @@ -746,6 +748,7 @@ But you need to tune PGroonga in some cases such as a case that you need to hand [upgrade-incompatible]:../upgrade/#incompatible-case [command]:functions/pgroonga-command.html +[condition]:functions/pgroonga-condition.html [command-escape-value]:functions/pgroonga-command-escape-value.html [escape]:functions/pgroonga-escape.html [flush]:functions/pgroonga-flush.html