Fauna distributes writes globally with strict consistency. UUID v7 as an application-level field gives Fauna documents a time-ordered identifier usable by external services. See UUID v7 in Fauna for the implementation guide.
Fauna schema with UUID v7 field
// Define collection with UUID v7 external ID index
import { Client, fql } from 'fauna';
const client = new Client({ secret: process.env.FAUNA_SECRET! });
// Create collection and index (run once)
await client.query(fql`
Collection.create({
name: "Orders",
indexes: {
byExternalId: {
terms: [{ field: "externalId" }]
}
}
})
`);
Insert with UUID v7
import { v7 as uuidv7 } from 'uuid';
async function createOrder(customerId: string, total: number) {
const externalId = uuidv7(); // UUID v7 — time-ordered, cross-service
const result = await client.query(fql`
Orders.create({
externalId: ${externalId},
customerId: ${customerId},
total: ${total},
status: "pending"
})
`);
return { faunaId: result.data.id, externalId };
}
Cursor pagination via UUID v7 range
// FQL v10 range query on externalId index
async function listOrders(cursor?: string, limit = 20) {
const result = cursor
? await client.query(fql`
Orders.all()
.where(.externalId > ${cursor})
.order(.externalId)
.take(${limit})
`)
: await client.query(fql`
Orders.all()
.order(.externalId)
.take(${limit})
`);
const items = result.data.data;
const nextCursor = items.length === limit ? items.at(-1)?.externalId : null;
return { items, nextCursor };
}
Further reading
- UUID v7 in Fauna — Full Guide
- UUID v7 for Cursor Pagination
- UUID v7 in Distributed Systems
- What is a UUID?
External references
Frequently asked questions
Can I use UUID v7 as a Fauna document ID?
Fauna manages document IDs internally — you cannot override the id field. Store UUID v7 as a separate field: externalId: String with a unique index. This provides a time-ordered cross-service identifier while Fauna handles its internal ID. See UUID v7 in Fauna for the full guide.
How does UUID v7 improve Fauna index queries?
Index a externalId field of type String. UUID v7 lexicographic order equals chronological order — index.range({ gt: cursor }) in FQL v10 returns records created after the cursor without a separate timestamp comparison. See UUID v7 for Cursor Pagination.
What is FQL v10?
FQL v10 is the current Fauna Query Language — a functional expression language with first-class support for document reads, writes, index queries, and transactions. Fauna's JavaScript driver exposes FQL v10 via a template-literal API: fql\`Orders.byExternalId(${id})\`. See What is a UUID.