mirror of
https://github.com/postgres/postgres.git
synced 2025-05-29 16:21:20 +03:00
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
This commit is contained in:
Masahiko Sawada
parent
246dedc5d0
commit
ba57dcfdcd
@ -4407,6 +4407,15 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' );
|
||||
are only unique within a single database.
|
||||
</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
|
||||
|
||||
@ -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>
|
||||
|
||||
<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>
|
||||
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.
|
||||
<xref linkend="func_uuid_extract_table"/> shows the <productname>PostgreSQL</productname>
|
||||
functions that can be used to extract information from UUIDs.
|
||||
</para>
|
||||
|
||||
<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.
|
||||
</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">
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user