From 98b9447eb3081f3c1545b435900392739bb18732 Mon Sep 17 00:00:00 2001 From: Andrew Alsup Date: Mon, 24 Feb 2025 20:56:22 -0500 Subject: [PATCH v3 1/2] docs for UUID funcs formatted in table --- doc/src/sgml/func.sgml | 189 +++++++++++++++++++++++++++++++++-------- 1 file changed, 153 insertions(+), 36 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 0e6c5349652..ca06d9b3270 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -14328,54 +14328,171 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - PostgreSQL includes several functions to generate a UUID. - -gen_random_uuid () uuid -uuidv4 () uuid - - These functions return a version 4 (random) UUID. - -uuidv7 ( shift interval ) uuid - - This function returns a version 7 UUID (UNIX timestamp with millisecond - precision + sub-millisecond timestamp + random). This function can accept - optional shift parameter of type interval - which shift internal timestamp by the given interval. + shows the PostgreSQL + functions that can be used to generate UUIDs. - - The module provides additional functions that - implement other standard algorithms for generating UUIDs. - + + <acronym>UUID</acronym> Generation Functions + + + + + + Function + + + Description + + + Example(s) + + + + - - There are also functions to extract data from UUIDs: - -uuid_extract_timestamp (uuid) timestamp with time zone - - This function extracts a timestamp with time zone 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. - + + + + + gen_random_uuid + uuid + + + Generate a version 4 (random) UUID. + + + gen_random_uuid() + 5b30857f-0bfa-48b5-ac0b-5c64e28078d1 + + + + + + + uuidv4 + uuid + + + Generate a version 4 (random) UUID. + + + uuidv4() + b42410ee-132f-42ee-9e4f-09a6485c95b8 + + + + + + + uuidv7 + ( shift interval ) + uuid + + + Generate a version 7 (time-ordered) UUID. The timestamp is computed using UNIX timestamp + with millisecond precision + sub-millisecond timestamp + random. The optional parameter + shift will shift the computed timestamp by the given interval. + + + uuidv7() + 019535d9-3df7-79fb-b466-fa907fa17f9e + + + + + +
+ + + + The module provides additional functions that + implement other standard algorithms for generating UUIDs. + + - -uuid_extract_version (uuid) smallint - - This function extracts the version from a UUID of the variant described by - RFC 9562. For - other variants, this function returns null. For example, for a UUID - generated by gen_random_uuid, this function will - return 4. + shows the PostgreSQL + functions that can be used to extract information from UUIDs. + + <acronym>UUID</acronym> Extraction Functions + + + + + + Function + + + Description + + + Example(s) + + + + + + + + + + uuid_extract_timestamp + ( uuid ) + timestamp with time zone + + + Extracts a timestamp with time zone 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. + + + uuid_extract_timestamp('019535d9-3df7-79fb-b466-fa907fa17f9e'::UUID) + 2025-02-23 21:46:24.503-05 + + + + + + + uuid_extract_version + ( uuid ) + smallint + + + Extracts the version from a UUID of the variant described by + RFC 9562. For + other variants, this function returns null. For example, for a UUID + generated by gen_random_uuid, this function will + return 4. + + + uuid_extract_version('41db1265-8bc1-4ab3-992f-885799a4af1d'::UUID) + 4 + + + uuid_extract_version('019535d9-3df7-79fb-b466-fa907fa17f9e'::UUID) + 7 + + + + + +
+ PostgreSQL also provides the usual comparison operators shown in for UUIDs. + + See for how details on the UUID datatype in + PostgreSQL. + -- 2.39.5 (Apple Git-154)