diff options
Diffstat (limited to 'doc/src/sgml/func/func-uuid.sgml')
| -rw-r--r-- | doc/src/sgml/func/func-uuid.sgml | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/doc/src/sgml/func/func-uuid.sgml b/doc/src/sgml/func/func-uuid.sgml new file mode 100644 index 00000000000..65c5ddec6b7 --- /dev/null +++ b/doc/src/sgml/func/func-uuid.sgml @@ -0,0 +1,188 @@ + <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"> + <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> + <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"> + <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-&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"> + <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-&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> |