Skip to content

Commit ba57dcf

Browse files
MasahikoSawadaMasahikoSawada
committed
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
1 parent 246dedc commit ba57dcf

File tree

2 files changed

+155
-36
lines changed

2 files changed

+155
-36
lines changed

‎doc/src/sgml/datatype.sgml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4407,6 +4407,15 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' );
44074407
are only unique within a single database.
44084408
</para>
44094409

4410+
<para>
4411+
RFC 9562 defines 8 different UUID versions. Each version has specific requirements
4412+
for generating new UUID values, and each version provides distinct benefits and drawbacks.
4413+
<productname>PostgreSQL</productname> provides native support for generating UUIDs
4414+
using the UUIDv4 and UUIDv7 algorithms. Alternatively, UUID values can be generated
4415+
outside of the database using any algorithm. The data type <type>uuid</type> can be used
4416+
to store any UUID, regardless of the origin and the UUID version.
4417+
</para>
4418+
44104419
<para>
44114420
A UUID is written as a sequence of lower-case hexadecimal digits,
44124421
in several groups separated by hyphens, specifically a group of 8

‎doc/src/sgml/func.sgml‎

Lines changed: 146 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -14328,54 +14328,164 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
1432814328
</indexterm>
1432914329

1433014330
<para>
14331-
<productname>PostgreSQL</productname> includes several functions to generate a UUID.
14332-
<synopsis>
14333-
<function>gen_random_uuid</function> () <returnvalue>uuid</returnvalue>
14334-
<function>uuidv4</function> () <returnvalue>uuid</returnvalue>
14335-
</synopsis>
14336-
These functions return a version 4 (random) UUID.
14337-
<synopsis>
14338-
<function>uuidv7</function> (<optional> <parameter>shift</parameter> <type>interval</type> </optional>) <returnvalue>uuid</returnvalue>
14339-
</synopsis>
14340-
This function returns a version 7 UUID (UNIX timestamp with millisecond
14341-
precision + sub-millisecond timestamp + random). This function can accept
14342-
optional <parameter>shift</parameter> parameter of type <type>interval</type>
14343-
which shift internal timestamp by the given interval.
14331+
<xref linkend="func_uuid_gen_table"/> shows the <productname>PostgreSQL</productname>
14332+
functions that can be used to generate UUIDs.
1434414333
</para>
1434514334

14346-
<para>
14347-
The <xref linkend="uuid-ossp"/> module provides additional functions that
14348-
implement other standard algorithms for generating UUIDs.
14349-
</para>
14335+
<table id="func_uuid_gen_table">
14336+
<title><acronym>UUID</acronym> Generation Functions</title>
14337+
<tgroup cols="1">
14338+
<thead>
14339+
<row>
14340+
<entry role="func_table_entry">
14341+
<para role="func_signature">
14342+
Function
14343+
</para>
14344+
<para>
14345+
Description
14346+
</para>
14347+
<para>
14348+
Example(s)
14349+
</para>
14350+
</entry>
14351+
</row>
14352+
</thead>
1435014353

14351-
<para>
14352-
There are also functions to extract data from UUIDs:
14353-
<synopsis>
14354-
<function>uuid_extract_timestamp</function> (uuid) <returnvalue>timestamp with time zone</returnvalue>
14355-
</synopsis>
14356-
This function extracts a <type>timestamp with time zone</type> from UUID
14357-
version 1 and 7. For other versions, this function returns null. Note that
14358-
the extracted timestamp is not necessarily exactly equal to the time the
14359-
UUID was generated; this depends on the implementation that generated the
14360-
UUID.
14361-
</para>
14354+
<tbody>
14355+
<row>
14356+
<entry role="func_table_entry">
14357+
<para role="func_signature">
14358+
<type>gen_random_uuid</type>
14359+
<returnvalue>uuid</returnvalue>
14360+
</para>
14361+
<para role="func_signature">
14362+
<type>uuidv4</type>
14363+
<returnvalue>uuid</returnvalue>
14364+
</para>
14365+
<para>
14366+
Generate a version 4 (random) UUID.
14367+
</para>
14368+
<para>
14369+
<literal>gen_random_uuid()</literal>
14370+
<returnvalue>5b30857f-0bfa-48b5-ac0b-5c64e28078d1</returnvalue>
14371+
</para>
14372+
<para>
14373+
<literal>uuidv4()</literal>
14374+
<returnvalue>b42410ee-132f-42ee-9e4f-09a6485c95b8</returnvalue>
14375+
</para>
14376+
</entry>
14377+
</row>
14378+
<row>
14379+
<entry role="func_table_entry">
14380+
<para role="func_signature">
14381+
<type>uuidv7</type>
14382+
( <optional> <parameter>shift</parameter> <type>interval</type> </optional> )
14383+
<returnvalue>uuid</returnvalue>
14384+
</para>
14385+
<para>
14386+
Generate a version 7 (time-ordered) UUID. The timestamp is computed using UNIX timestamp
14387+
with millisecond precision + sub-millisecond timestamp + random. The optional parameter
14388+
<parameter>shift</parameter> will shift the computed timestamp by the given <type>interval</type>.
14389+
</para>
14390+
<para>
14391+
<literal>uuidv7()</literal>
14392+
<returnvalue>019535d9-3df7-79fb-b466-fa907fa17f9e</returnvalue>
14393+
</para>
14394+
</entry>
14395+
</row>
14396+
</tbody>
14397+
</tgroup>
14398+
</table>
14399+
14400+
<note>
14401+
<para>
14402+
The <xref linkend="uuid-ossp"/> module provides additional functions that
14403+
implement other standard algorithms for generating UUIDs.
14404+
</para>
14405+
</note>
1436214406

1436314407
<para>
14364-
<synopsis>
14365-
<function>uuid_extract_version</function> (uuid) <returnvalue>smallint</returnvalue>
14366-
</synopsis>
14367-
This function extracts the version from a UUID of the variant described by
14368-
<ulink url="https://datatracker.ietf.org/doc/html/rfc9562">RFC 9562</ulink>. For
14369-
other variants, this function returns null. For example, for a UUID
14370-
generated by <function>gen_random_uuid</function>, this function will
14371-
return 4.
14408+
<xref linkend="func_uuid_extract_table"/> shows the <productname>PostgreSQL</productname>
14409+
functions that can be used to extract information from UUIDs.
1437214410
</para>
1437314411

14412+
<table id="func_uuid_extract_table">
14413+
<title><acronym>UUID</acronym> Extraction Functions</title>
14414+
<tgroup cols="1">
14415+
<thead>
14416+
<row>
14417+
<entry role="func_table_entry">
14418+
<para role="func_signature">
14419+
Function
14420+
</para>
14421+
<para>
14422+
Description
14423+
</para>
14424+
<para>
14425+
Example(s)
14426+
</para>
14427+
</entry>
14428+
</row>
14429+
</thead>
14430+
14431+
<tbody>
14432+
<row>
14433+
<entry role="func_table_entry">
14434+
<para role="func_signature">
14435+
<type>uuid_extract_timestamp</type>
14436+
( <type>uuid</type> )
14437+
<returnvalue>timestamp with time zone</returnvalue>
14438+
</para>
14439+
<para>
14440+
Extracts a <type>timestamp with time zone</type> from UUID
14441+
version 1 and 7. For other versions, this function returns null. Note that
14442+
the extracted timestamp is not necessarily exactly equal to the time the
14443+
UUID was generated; this depends on the implementation that generated the
14444+
UUID.
14445+
</para>
14446+
<para>
14447+
<literal>uuid_extract_timestamp('019535d9-3df7-79fb-b466-fa907fa17f9e'::uuid)</literal>
14448+
<returnvalue>2025-02-23 21:46:24.503-05</returnvalue>
14449+
</para>
14450+
</entry>
14451+
</row>
14452+
<row>
14453+
<entry role="func_table_entry">
14454+
<para role="func_signature">
14455+
<type>uuid_extract_version</type>
14456+
( <type>uuid</type> )
14457+
<returnvalue>smallint</returnvalue>
14458+
</para>
14459+
<para>
14460+
Extracts the version from a UUID of the variant described by
14461+
<ulink url="https://datatracker.ietf.org/doc/html/rfc9562">RFC 9562</ulink>. For
14462+
other variants, this function returns null. For example, for a UUID
14463+
generated by <function>gen_random_uuid</function>, this function will
14464+
return 4.
14465+
</para>
14466+
<para>
14467+
<literal>uuid_extract_version('41db1265-8bc1-4ab3-992f-885799a4af1d'::uuid)</literal>
14468+
<returnvalue>4</returnvalue>
14469+
</para>
14470+
<para>
14471+
<literal>uuid_extract_version('019535d9-3df7-79fb-b466-fa907fa17f9e'::uuid)</literal>
14472+
<returnvalue>7</returnvalue>
14473+
</para>
14474+
</entry>
14475+
</row>
14476+
</tbody>
14477+
</tgroup>
14478+
</table>
14479+
1437414480
<para>
1437514481
<productname>PostgreSQL</productname> also provides the usual comparison
1437614482
operators shown in <xref linkend="functions-comparison-op-table"/> for
1437714483
UUIDs.
1437814484
</para>
14485+
<para>
14486+
See <xref linkend="datatype-uuid"/> for details on the data type
14487+
<type>uuid</type> in <productname>PostgreSQL</productname>.
14488+
</para>
1437914489
</sect1>
1438014490

1438114491
<sect1 id="functions-xml">

0 commit comments

Comments
 (0)