Xata provides a serverless database API over PostgreSQL with TypeScript-first ergonomics. UUID v7 as a custom ID replaces Xata’s prefixed random IDs with RFC-standard, time-ordered identifiers. See UUID in PostgreSQL for the underlying storage pattern.
Xata schema (xata.json)
{
"tables": [
{
"name": "orders",
"columns": [
{ "name": "id", "type": "string" },
{ "name": "customer_id", "type": "string" },
{ "name": "total", "type": "float" },
{ "name": "status", "type": "string" }
]
}
]
}
Insert with UUID v7
import { getXataClient } from './xata';
import { v7 as uuidv7 } from 'uuid';
const xata = getXataClient();
async function createOrder(customerId: string, total: number) {
return xata.db.orders.create({
id: uuidv7(), // UUID v7 — time-ordered, RFC 9562
customer_id: customerId,
total,
status: 'pending',
});
}
Cursor pagination
// UUID v7 lex order = chronological — no xata_createdat sort needed
async function listOrders(cursor?: string, limit = 20) {
const filter = cursor ? { id: { $gt: cursor } } : {};
const { records } = await xata.db.orders
.filter(filter)
.sort('id', 'asc')
.getPaginated({ pagination: { size: limit } });
const nextCursor = records.length === limit
? records.at(-1)?.id
: undefined;
return { records, nextCursor };
}
Time-range query using UUID v7 prefix
// Query records created in the last hour using UUID v7 timestamp range
function uuidV7MinAt(date: Date): string {
const ms = BigInt(date.getTime());
const hex = ms.toString(16).padStart(12, '0');
// Minimum UUID v7 at this timestamp
return `${hex.slice(0,8)}-${hex.slice(8,12)}-7000-8000-000000000000`;
}
async function recentOrders(sinceMs = 3_600_000) {
const since = uuidV7MinAt(new Date(Date.now() - sinceMs));
const { records } = await xata.db.orders
.filter({ id: { $gt: since } })
.sort('id', 'asc')
.getAll();
return records;
}
Extract creation time from UUID v7 ID
function createdAt(id: string): Date {
const hex = id.replace(/-/g, '').slice(0, 12);
return new Date(parseInt(hex, 16));
}
Further reading
External references
Frequently asked questions
Can I use UUID v7 as a record ID in Xata?
Yes. Xata accepts a custom id field when creating records. Pass your UUID v7 string to xata.db.orders.create({ id: uuidv7(), ...fields }). Xata validates uniqueness and stores the string as-is. UUID v7's lexicographic order enables filter: { id: { $gt: cursor } } cursor pagination. See UUID v7 for Cursor Pagination.
What is Xata's default record ID format?
Xata generates IDs in the format rec_<random> by default — a rec_ prefix followed by a random base62 string. These are not time-ordered. UUID v7 replaces this with a standard, time-ordered identifier compatible with any UUID-aware tooling. See Prefix ID for the pattern.
Does UUID v7 work with Xata branch databases?
Yes. Xata branches are isolated database environments for development and preview. UUID v7 IDs generated in a branch are unique across branches because the 74 random bits prevent collisions. When promoting a branch, IDs do not conflict with the main database.