This is a document for PGroonga 2.X. See PGroonga 1.x document when you're using old PGroonga.

pgroonga_query_expand function

Since 1.2.2.

Summary

pgroonga_query_expand function expands registered synonyms in query in query syntax. Query syntax is used by &@~ operator, &@~| operator and so on.

pgroonga_query_expand function is useful to implement query expansion. See also document for Groonga's query expansion feature.

Syntax

Here is the syntax of this function:

text pgroonga_query_expand(table_name,
                           term_column_name,
                           synonyms_column_name,
                           query)

table_name is a text type value. It's an existing table name that stores synonyms.

term_column_name is a text type value. It's an column name that stores term to be expanded in the table_name table. The column is text type or text[] type value.

synonyms_column_name is a text type value. It's an column name that stores synonyms of the term column. The column is text[] type value.

query is a text type value. It's a query that uses query syntax.

pgroonga_query_expand returns a text type value. All registered synonyms are expanded in the query.

It's recommended that ${table_name}.${term_column_name} is indexed by PGroonga with pgroonga_text_term_search_ops_v2 operator class for fast query expansion like the following:

CREATE TABLE synonyms (
  term text,
  synonyms text[]
);

CREATE INDEX synonyms_term
          ON synonyms
       USING pgroonga (term pgroonga_text_term_search_ops_v2);

pgroonga_query_escape function can work without index but can work faster with index.

You can use all index access methods that support = for text type such as btree. But it's recommended that you use PGroonga. Because PGroonga supports value normalized = (including case insensitive comparison) for text. Value normalized = is useful for query expansion.

Usage

You can use the following styles:

A term to multiple synonyms mapping

Here are sample schema and data:

CREATE TABLE synonyms (
  term text,
  synonyms text[]
);

CREATE INDEX synonyms_term
          ON synonyms
       USING pgroonga (term pgroonga_text_term_search_ops_v2);

INSERT INTO synonyms VALUES ('PGroonga', ARRAY['PGroonga', 'Groonga PostgreSQL']);

In this sample, all of "PGroonga" and "pgroonga" in query are expanded because PGroonga index is used:

SELECT pgroonga_query_expand('synonyms', 'term', 'synonyms',
                             'PGroonga OR Mroonga') AS query_expand;
--                  query_expand                   
-- -------------------------------------------------
--  ((PGroonga) OR (Groonga PostgreSQL)) OR Mroonga
-- (1 row)
SELECT pgroonga_query_expand('synonyms', 'term', 'synonyms',
                             'pgroonga OR mroonga') AS query_expand;
--                   query_expand                   
-- -------------------------------------------------
--  ((PGroonga) OR (Groonga PostgreSQL)) OR mroonga
-- (1 row)

Synonym groups

Since 2.2.1.

Here are sample schema and data:

CREATE TABLE synonym_groups (
  synonyms text[]
);

CREATE INDEX synonym_groups_synonyms
          ON synonym_groups
       USING pgroonga (synonyms pgroonga_text_array_term_search_ops_v2);

INSERT INTO synonym_groups
  VALUES (ARRAY['PGroonga', 'Groonga']);

In this sample, all of "PGroonga" and "pgroonga" in query are expanded because PGroonga index is used:

SELECT pgroonga_query_expand('synonym_groups', 'synonyms', 'synonyms',
                             'PGroonga OR Mroonga') AS query_expand;
--              query_expand             
-- --------------------------------------
--  ((PGroonga) OR (Groonga)) OR Mroonga
-- (1 row)
SELECT pgroonga_query_expand('synonym_groups', 'synonyms', 'synonyms',
                             'pgroonga OR mroonga') AS query_expand;
--              query_expand             
-- --------------------------------------
--  ((PGroonga) OR (Groonga)) OR mroonga
-- (1 row)

See also