doc: Convert UUID functions list to table format.

Convert the list of UUID functions into a table for better
readability. This commit also adds references to the UUID type section
and includes descriptions of different UUID generation algorithm
versions.

Author: Andy Alsup <bluesbreaker@gmail.com>
Reviewed-by: Laurenz Albe <laurenz.albe@cybertec.at>
Discussion: https://postgr.es/m/CADOZ7s7OHag+r6w+BzKw2xgb3fVtAD-pU=_N9-9pSe5W1TB+xQ@mail.gmail.com

2 files changed, 155 insertions, 36 deletions

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 87679dc4a11..09309ba0390 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -4408,6 +4408,15 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' );
    </para>
 
    <para>
+    RFC 9562 defines 8 different UUID versions.  Each version has specific requirements
+    for generating new UUID values, and each version provides distinct benefits and drawbacks.
+    <productname>PostgreSQL</productname> provides native support for generating UUIDs
+    using the UUIDv4 and UUIDv7 algorithms.  Alternatively, UUID values can be generated
+    outside of the database using any algorithm.  The data type <type>uuid</type> can be used
+    to store any UUID, regardless of the origin and the UUID version.
+   </para>
+
+   <para>
     A UUID is written as a sequence of lower-case hexadecimal digits,
     in several groups separated by hyphens, specifically a group of 8
     digits followed by three groups of 4 digits followed by a group of
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 0e6c5349652..bf31b1f3eee 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -14328,54 +14328,164 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
   </indexterm>
 
   <para>
-   <productname>PostgreSQL</productname> includes several functions to generate a UUID.
-<synopsis>
-<function>gen_random_uuid</function> () <returnvalue>uuid</returnvalue>
-<function>uuidv4</function> () <returnvalue>uuid</returnvalue>
-</synopsis>
-   These functions return a version 4 (random) UUID.
-<synopsis>
-<function>uuidv7</function> (<optional> <parameter>shift</parameter> <type>interval</type> </optional>) <returnvalue>uuid</returnvalue>
-</synopsis>
-    This function returns a version 7 UUID (UNIX timestamp with millisecond
-    precision + sub-millisecond timestamp + random). This function can accept
-    optional <parameter>shift</parameter> parameter of type <type>interval</type>
-    which shift internal timestamp by the given interval.
+   <xref linkend="func_uuid_gen_table"/> shows the <productname>PostgreSQL</productname>
+   functions that can be used to generate UUIDs.
   </para>
 
-  <para>
-   The <xref linkend="uuid-ossp"/> module provides additional functions that
-   implement other standard algorithms for generating UUIDs.
-  </para>
+  <table id="func_uuid_gen_table">
+   <title><acronym>UUID</acronym> Generation Functions</title>
+   <tgroup cols="1">
+    <thead>
+     <row>
+      <entry role="func_table_entry">
+       <para role="func_signature">
+        Function
+       </para>
+       <para>
+        Description
+        </para>
+       <para>
+        Example(s)
+       </para>
+       </entry>
+     </row>
+    </thead>
 
-  <para>
-   There are also functions to extract data from UUIDs:
-<synopsis>
-<function>uuid_extract_timestamp</function> (uuid) <returnvalue>timestamp with time zone</returnvalue>
-</synopsis>
-   This function extracts a <type>timestamp with time zone</type> from UUID
-   version 1 and 7.  For other versions, this function returns null.  Note that
-   the extracted timestamp is not necessarily exactly equal to the time the
-   UUID was generated; this depends on the implementation that generated the
-   UUID.
-  </para>
+    <tbody>
+     <row>
+      <entry role="func_table_entry">
+       <para role="func_signature">
+        <type>gen_random_uuid</type>
+        <returnvalue>uuid</returnvalue>
+       </para>
+       <para role="func_signature">
+        <type>uuidv4</type>
+        <returnvalue>uuid</returnvalue>
+       </para>
+       <para>
+         Generate a version 4 (random) UUID.
+       </para>
+       <para>
+        <literal>gen_random_uuid()</literal>
+        <returnvalue>5b30857f-0bfa-48b5-ac0b-5c64e28078d1</returnvalue>
+       </para>
+       <para>
+        <literal>uuidv4()</literal>
+        <returnvalue>b42410ee-132f-42ee-9e4f-09a6485c95b8</returnvalue>
+       </para>
+      </entry>
+     </row>
+     <row>
+      <entry role="func_table_entry">
+       <para role="func_signature">
+        <type>uuidv7</type>
+        ( <optional> <parameter>shift</parameter> <type>interval</type> </optional> )
+        <returnvalue>uuid</returnvalue>
+       </para>
+       <para>
+        Generate a version 7 (time-ordered) UUID. The timestamp is computed using UNIX timestamp
+        with millisecond precision + sub-millisecond timestamp + random. The optional parameter
+        <parameter>shift</parameter> will shift the computed timestamp by the given <type>interval</type>.
+       </para>
+       <para>
+        <literal>uuidv7()</literal>
+        <returnvalue>019535d9-3df7-79fb-b466-fa907fa17f9e</returnvalue>
+       </para>
+      </entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </table>
+
+  <note>
+   <para>
+    The <xref linkend="uuid-ossp"/> module provides additional functions that
+    implement other standard algorithms for generating UUIDs.
+   </para>
+  </note>
 
   <para>
-<synopsis>
-<function>uuid_extract_version</function> (uuid) <returnvalue>smallint</returnvalue>
-</synopsis>
-   This function extracts the version from a UUID of the variant described by
-   <ulink url="https://datatracker.ietf.org/doc/html/rfc9562">RFC 9562</ulink>.  For
-   other variants, this function returns null.  For example, for a UUID
-   generated by <function>gen_random_uuid</function>, this function will
-   return 4.
+   <xref linkend="func_uuid_extract_table"/> shows the <productname>PostgreSQL</productname>
+   functions that can be used to extract information from UUIDs.
   </para>
 
+  <table id="func_uuid_extract_table">
+   <title><acronym>UUID</acronym> Extraction Functions</title>
+   <tgroup cols="1">
+    <thead>
+     <row>
+      <entry role="func_table_entry">
+       <para role="func_signature">
+        Function
+       </para>
+       <para>
+        Description
+       </para>
+       <para>
+        Example(s)
+       </para>
+      </entry>
+     </row>
+    </thead>
+
+    <tbody>
+     <row>
+      <entry role="func_table_entry">
+       <para role="func_signature">
+        <type>uuid_extract_timestamp</type>
+        ( <type>uuid</type> )
+        <returnvalue>timestamp with time zone</returnvalue>
+       </para>
+       <para>
+        Extracts a <type>timestamp with time zone</type> from UUID
+        version 1 and 7.  For other versions, this function returns null.  Note that
+        the extracted timestamp is not necessarily exactly equal to the time the
+        UUID was generated; this depends on the implementation that generated the
+        UUID.
+       </para>
+       <para>
+        <literal>uuid_extract_timestamp('019535d9-3df7-79fb-b466-fa907fa17f9e'::uuid)</literal>
+         <returnvalue>2025-02-23 21:46:24.503-05</returnvalue>
+       </para>
+      </entry>
+     </row>
+     <row>
+      <entry role="func_table_entry">
+       <para role="func_signature">
+        <type>uuid_extract_version</type>
+        ( <type>uuid</type> )
+        <returnvalue>smallint</returnvalue>
+       </para>
+       <para>
+        Extracts the version from a UUID of the variant described by
+        <ulink url="https://datatracker.ietf.org/doc/html/rfc9562">RFC 9562</ulink>.  For
+        other variants, this function returns null.  For example, for a UUID
+        generated by <function>gen_random_uuid</function>, this function will
+        return 4.
+       </para>
+       <para>
+        <literal>uuid_extract_version('41db1265-8bc1-4ab3-992f-885799a4af1d'::uuid)</literal>
+        <returnvalue>4</returnvalue>
+       </para>
+       <para>
+        <literal>uuid_extract_version('019535d9-3df7-79fb-b466-fa907fa17f9e'::uuid)</literal>
+        <returnvalue>7</returnvalue>
+       </para>
+      </entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </table>
+
   <para>
    <productname>PostgreSQL</productname> also provides the usual comparison
    operators shown in <xref linkend="functions-comparison-op-table"/> for
    UUIDs.
   </para>
+  <para>
+   See <xref linkend="datatype-uuid"/> for details on the data type
+   <type>uuid</type> in <productname>PostgreSQL</productname>.
+  </para>
  </sect1>
 
  <sect1 id="functions-xml">