doc/src/sgml/func/func-uuid.sgml - master - githubmirror/postgres

doc/src/sgml/func/func-uuid.sgml
185 строк6 KB
Masahiko Sawada
Support UUIDv6 in uuid_extract_timestamp().
04 авг 2026, 20:57
04 авг 2026, 20:57451871b
 <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, 6, 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>