Skip to content

Commit 9af3bb0

Browse files
authored
Update gen-random-uuid.md
1 parent 315a2ad commit 9af3bb0

File tree

1 file changed

+32
-9
lines changed

1 file changed

+32
-9
lines changed

docs/en/sql-reference/20-sql-functions/13-uuid-functions/gen-random-uuid.md

Lines changed: 32 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: GEN_RANDOM_UUID
33
---
44

5-
Generates a random UUID based on v4.
5+
Generates a random UUID based on version 7, starting from version 1.2.658. Previously, this function generated UUIDs based on version 4.
66

77
## Syntax
88

@@ -14,14 +14,37 @@ GEN_RANDOM_UUID()
1414

1515
- [UUID](uuid.md)
1616

17+
## Why Use UUID v7?
18+
19+
- **Time-Based Ordering**: UUID v7 includes a timestamp, allowing events or records to be ordered chronologically by the time they were created. This is especially useful when you need to track the sequence of actions.
20+
21+
- **Chronological Sorting**: UUID v7 ensures that UUIDs are sorted by creation time, which is ideal for scenarios where sorting events by time is necessary, such as event logging or maintaining audit trails.
22+
23+
## Version Information
24+
25+
- Version 1.2.658 and later: UUID version upgraded from v4 to v7.
26+
- Version prior to 1.2.658: UUID generation was based on v4.
27+
1728
## Examples
1829

30+
In an application where events are logged, maintaining the correct sequence of actions is essential. UUID v7 ensures that each event is time-ordered, making it easy to track actions chronologically.
31+
1932
```sql
20-
SELECT GEN_RANDOM_UUID(), UUID();
21-
22-
┌─────────────────────────────────────────────────────────────────────────────┐
23-
│ gen_random_uuid() │ uuid() │
24-
├──────────────────────────────────────┼──────────────────────────────────────┤
25-
│ f88e7efe-1bc2-494b-806b-3ffe90db8f47 │ f88e7efe-1bc2-494b-806b-3ffe90db8f47 │
26-
└─────────────────────────────────────────────────────────────────────────────┘
27-
```
33+
-- Log a user logging in
34+
SELECT GEN_RANDOM_UUID(), 'User logged in' AS event, CURRENT_TIMESTAMP AS event_time;
35+
36+
-- Log a user making a purchase
37+
SELECT GEN_RANDOM_UUID(), 'User made a purchase' AS event, CURRENT_TIMESTAMP AS event_time;
38+
```
39+
40+
The results from these queries might look like this:
41+
```sql
42+
┌──────────────────────────────────────────────────────────────────────────────────────────┐
43+
│ gen_random_uuid() │ event │ event_time │
44+
├──────────────────────────────────────┼──────────────────────┼────────────────────────────┤
45+
│ 019329e6-26a2-7b01-b9f5-1c3c02600578 │ User logged in2024-11-14 08:59:29.313906
46+
│ 019329e6-329e-73c3-b0a8-a413ce298607 │ User made a purchase │ 2024-11-14 08:59:32.381497
47+
└──────────────────────────────────────────────────────────────────────────────────────────┘
48+
```
49+
50+
Notice that the `gen_random_uuid()` values are generated in the order that the events occurred, making it easy to maintain chronological order.

0 commit comments

Comments
 (0)