Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitba57dcf

Browse files
doc: Convert UUID functions list to table format.
Convert the list of UUID functions into a table for betterreadability. This commit also adds references to the UUID type sectionand includes descriptions of different UUID generation algorithmversions.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 parent246dedc commitba57dcf

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)
[8]ページ先頭
©2009-2025 Movatter.jp