 <sect1 id="functions-uuid">
  <title>UUID Functions</title>

  <indexterm zone="functions-uuid">
   <primary>UUID</primary>
   <secondary>generating</secondary>
  </indexterm>

  <indexterm>
   <primary>gen_random_uuid</primary>
  </indexterm>

  <indexterm>
   <primary>uuidv4</primary>
  </indexterm>

  <indexterm>
   <primary>uuidv7</primary>
  </indexterm>

  <indexterm>
   <primary>uuid_extract_timestamp</primary>
  </indexterm>

  <indexterm>
   <primary>uuid_extract_version</primary>
  </indexterm>

  <para>
   <xref linkend="func_uuid_gen_table"/> shows the <productname>PostgreSQL</productname>
   functions that can be used to generate 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>

    <tbody>
     <row>
      <entry role="func_table_entry"><para role="func_signature">
        <function>gen_random_uuid</function> ( )
        <returnvalue>uuid</returnvalue>
       </para>
       <para role="func_signature">
        <function>uuidv4</function> ( )
        <returnvalue>uuid</returnvalue>
       </para>
       <para>
        Generates 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">
        <function>uuidv7</function>
        ( <optional> <parameter>shift</parameter> <type>interval</type> </optional> )
        <returnvalue>uuid</returnvalue>
       </para>
       <para>
        Generates 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>.
        Infinite interval values are not accepted.
        The shifted timestamp must fall within the range supported by
        UUID version 7's 48-bit millisecond timestamp field: from
        1970-01-01 00:00:00 UTC to approximately year 10889.
        An error is raised if the resulting timestamp is outside this
        range.
       </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>
   <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">
        <function>uuid_extract_timestamp</function>
        ( <type>uuid</type> )
        <returnvalue>timestamp with time zone</returnvalue>
       </para>
       <para>
        Extracts a <type>timestamp with time zone</type> from a UUID of
        version 1 or 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-&zwsp;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">
        <function>uuid_extract_version</function>
        ( <type>uuid</type> )
        <returnvalue>smallint</returnvalue>
       </para>
       <para>
        Extracts the version from a UUID of one of the variants 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-&zwsp;885799a4af1d'::uuid)</literal>
        <returnvalue>4</returnvalue>
       </para>
       <para>
        <literal>uuid_extract_version('019535d9-3df7-79fb-b466-&zwsp;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>
