This is a document for PGroonga 1.X. See PGroonga 2.x document when you're using recent 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 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

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');
--                  query_expand                   
-- -------------------------------------------------
--  ((PGroonga) OR (Groonga PostgreSQL)) OR Mroonga
-- (1 row)
SELECT pgroonga.query_expand('synonyms', 'term', 'synonyms',
                             'pgroonga OR mroonga');
--                   query_expand                   
-- -------------------------------------------------
--  ((PGroonga) OR (Groonga PostgreSQL)) OR mroonga
-- (1 row)

See also