<function>regexp_match</function>(<replaceable>string</replaceable>,
     <replaceable>pattern</replaceable> <optional>, <replaceable>flags</replaceable> </optional>).
     If there is no match, the result is <literal>NULL</literal>.
     If a match is found, and the <replaceable>pattern</replaceable> contains no
     parenthesized subexpressions, then the result is a single-element text
     array containing the substring matching the whole pattern.
     If a match is found, and the <replaceable>pattern</replaceable> contains
     parenthesized subexpressions, then the result is a text array
     whose <replaceable>n</replaceable>'th element is the substring matching
     the <replaceable>n</replaceable>'th parenthesized subexpression of
     the <replaceable>pattern</replaceable> (not counting <quote>non-capturing</quote>
     parentheses; see below for details).
     The <replaceable>flags</replaceable> parameter is an optional text string
     containing zero or more single-letter flags that change the function's
     behavior.  Supported flags are described
     in <xref linkend="posix-embedded-options-table"/>.
    </para>

   <para>
    Some examples:
<programlisting>
SELECT regexp_match('foobarbequebaz', 'bar.*que');
 regexp_match
--------------
 {barbeque}
(1 row)

SELECT regexp_match('foobarbequebaz', '(bar)(beque)');
 regexp_match
--------------
 {bar,beque}
(1 row)
</programlisting>
   </para>

    <tip>
     <para>
      In the common case where you just want the whole matching substring
      or <literal>NULL</literal> for no match, the best solution is to
      use <function>regexp_substr()</function>.
      However, <function>regexp_substr()</function> only exists
      in <productname>PostgreSQL</productname> version 15 and up.  When
      working in older versions, you can extract the first element
      of <function>regexp_match()</function>'s result, for example:
<programlisting>
SELECT (regexp_match('foobarbequebaz', 'bar.*que'))[1];
 regexp_match
--------------
 barbeque
(1 row)
</programlisting>
     </para>
    </tip>

    <para>
     The <function>regexp_matches</function> function returns a set of text arrays
     of matching substring(s) within matches of a POSIX regular
     expression pattern to a string.  It has the same syntax as
     <function>regexp_match</function>.
     This function returns no rows if there is no match, one row if there is
     a match and the <literal>g</literal> flag is not given, or <replaceable>N</replaceable>
     rows if there are <replaceable>N</replaceable> matches and the <literal>g</literal> flag
     is given.  Each returned row is a text array containing the whole
     matched substring or the substrings matching parenthesized
     subexpressions of the <replaceable>pattern</replaceable>, just as described above
     for <function>regexp_match</function>.
     <function>regexp_matches</function> accepts all the flags shown
     in <xref linkend="posix-embedded-options-table"/>, plus
     the <literal>g</literal> flag which commands it to return all matches, not
     just the first one.
    </para>

   <para>
    Some examples:
<programlisting>
SELECT regexp_matches('foo', 'not there');
 regexp_matches
----------------
(0 rows)

SELECT regexp_matches('foobarbequebazilbarfbonk', '(b[^b]+)(b[^b]+)', 'g');
 regexp_matches
----------------
 {bar,beque}
 {bazil,barf}
(2 rows)
</programlisting>
   </para>

   <tip>
    <para>
     In most cases <function>regexp_matches()</function> should be used with
     the <literal>g</literal> flag, since if you only want the first match, it's
     easier and more efficient to use <function>regexp_match()</function>.
     However, <function>regexp_match()</function> only exists
     in <productname>PostgreSQL</productname> version 10 and up.  When working in older
     versions, a common trick is to place a <function>regexp_matches()</function>
     call in a sub-select, for example:
<programlisting>
SELECT col1, (SELECT regexp_matches(col2,