Add UUID API functions #4395
Add UUID API functions #4395
Conversation
Add API documentation for the new UUID functions that were introduced in 2.22.
|
Allow 10 minutes from last push for the staging site to build. If the link doesn't work, try using incognito mode instead. For internal reviewers, check web-documentation repo actions for staging build status. Link to build for this PR: http://docs-dev.timescale.com/docs-uuid-functions |
|
I am not sure I did things right and I probably missed a bunch of things. But at least it is a starting point. |
billy-the-fish
requested review from
brandonpurcell-dev
and removed request for
billy-the-fish
api/hypertable/create_table.md
Outdated
| ```sql | ||
| CREATE TABLE events ( | ||
| vvid uuid PRIMARY KEY DEFAULT uuidv7(), | ||
| vvpayload jsonb | ||
| ); | ||
| WITH (tsdb.hypertable, tsdb.partition_column = by_uuidv7('id')); |
There was a problem hiding this comment.
| ```sql | |
| CREATE TABLE events ( | |
| vvid uuid PRIMARY KEY DEFAULT uuidv7(), | |
| vvpayload jsonb | |
| ); | |
| WITH (tsdb.hypertable, tsdb.partition_column = by_uuidv7('id')); | |
| ```sql | |
| CREATE TABLE events ( | |
| id uuid PRIMARY KEY DEFAULT generate_uuidv7(), | |
| payload jsonb | |
| ) WITH (tsdb.hypertable, tsdb.partition_column = 'id'); |
There was a problem hiding this comment.
AFAIK, this format of create table automatically enables compression as well. I believe (optimized) UUID compression is not enabled by default, which means that the id column will use sub-optimal compression. I am wondering if we should preface this with saying that we recommend setting enable_uuid_compression=true first?
There was a problem hiding this comment.
@dbeck Do you have any insights here?
There was a problem hiding this comment.
Updated with guc setting and tabs for the postgres versions
| UUIDv7 is a time-ordered UUID that includes a Unix timestamp (with millisecond precision) in its first 48 bits. Like | ||
| other UUIDs, it uses 6 bits for version and variant info, and the remaining 74 bits are random. |
There was a problem hiding this comment.
The precision thing can be a bit confusing, so I think we need to be very clear on it. Here we write millisecond precision in the text but show a picture with microseconds, which can raise questions.
The UUIDv7 specifies a millisecond timestamp. However, one can add an optional sub-millisecond fraction, which we do in this function.
Therefore the generated UUID will have microsecond precision. The caveat, though, is that there is no way to specify in the UUID that this extra precision is encoded in the extra bits so if someone gets this UUID and doesn't know that the extra bits encode microseconds, there is no way to know for sure that the precision is microseconds.
Not sure how we can make this clear without going into too much detail.
Maybe the picture should say that the microsecond bits are optional?
There was a problem hiding this comment.
I've updated the image. Will take a while for the AWS cache to clear to make it visible. Added the updated image here for speed.
| ```sql | ||
| SELECT run_id, status | ||
| FROM runs | ||
| WHERE to_timestamp(run_id) >= now() - interval '5 minutes'; |
There was a problem hiding this comment.
In our examples it would be good to differentiate between this approach that has to scan and apply the to_timestamp() function to every row vs using to_uuidv7_boundary() that should be more efficient since it's limiting by a range with the random portion zeroed out.
There was a problem hiding this comment.
Sounds good. Could you supply a code example please.
Description
Add API documentation for the new UUID functions that were introduced in 2.22.
Links
timescale/timescaledb#8546
Review checklists
Reviewers: use this section to ensure you have checked everything before approving this PR:
Subject matter expert (SME) review checklist
Documentation team review checklist
and have they been implemented?