Convex is a serverless backend platform with real-time reactive queries, ACID mutations, and built-in scheduling. Convex generates its own document IDs (Id<TableName>) — opaque strings you cannot customise. UUID v7 serves a different role in Convex applications: stable external IDs for API responses, pagination cursors, and trace correlation across actions that call external services. See UUID Generation Strategies for the server-side generation principle.
Schema with UUID v7 external ID
// convex/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";
export default defineSchema({
orders: defineTable({
externalId: v.string(), // UUID v7 — stable external ID
customerId: v.string(),
total: v.number(),
status: v.string(),
}).index("by_external_id", ["externalId"]),
});
The .index("by_external_id", ...) allows efficient lookup by UUID v7 from external API requests.
Mutation: create order with UUID v7
// convex/orders.ts
import { mutation, query } from "./_generated/server";
import { v } from "convex/values";
import { v7 as uuidv7 } from "uuid";
export const createOrder = mutation({
args: {
customerId: v.string(),
total: v.number(),
},
handler: async (ctx, args) => {
const externalId = uuidv7(); // server-side — safe in Convex runtime
const docId = await ctx.db.insert("orders", {
externalId,
customerId: args.customerId,
total: args.total,
status: "pending",
});
return { convexId: docId, externalId };
},
});
Query: lookup by UUID v7 external ID
export const getByExternalId = query({
args: { externalId: v.string() },
handler: async (ctx, args) => {
return ctx.db
.query("orders")
.withIndex("by_external_id", q => q.eq("externalId", args.externalId))
.unique();
},
});
Cursor pagination using UUID v7
export const listOrders = query({
args: {
cursor: v.optional(v.string()), // UUID v7 cursor
limit: v.optional(v.number()),
},
handler: async (ctx, args) => {
const limit = args.limit ?? 20;
let results = await ctx.db
.query("orders")
.withIndex("by_external_id")
.collect();
if (args.cursor) {
const idx = results.findIndex(o => o.externalId > args.cursor!);
results = idx >= 0 ? results.slice(idx, idx + limit) : [];
} else {
results = results.slice(0, limit);
}
const nextCursor = results.length === limit
? results[results.length - 1].externalId
: null;
return { results, nextCursor };
},
});
UUID v7 values sort chronologically as strings — externalId > cursor gives correct keyset pagination. See UUID v7 for Cursor Pagination.
Action: UUID v7 as correlation ID for external calls
// convex/actions.ts
import { action } from "./_generated/server";
import { v } from "convex/values";
import { v7 as uuidv7 } from "uuid";
export const processPayment = action({
args: { orderId: v.string(), amount: v.number() },
handler: async (ctx, args) => {
const correlationId = uuidv7(); // UUID v7 trace ID for this action
// All external calls share the same correlation ID
const paymentResult = await fetch("https://payments.api/charge", {
method: "POST",
headers: {
"x-correlation-id": correlationId,
"x-idempotency-key": args.orderId, // UUID v7 order ID as idempotency key
},
body: JSON.stringify({ amount: args.amount }),
});
console.log({ correlationId, orderId: args.orderId, status: paymentResult.status });
return { correlationId, success: paymentResult.ok };
},
});
Further reading
- UUID Generation Strategies — server vs client
- UUID v7 in Microservices — correlation IDs
- UUID as Idempotency Keys
- UUID v7 for Cursor Pagination
External references
Frequently asked questions
Does Convex support UUID v7 as a document ID?
Convex auto-generates its own opaque document IDs (type Id<TableName>). You cannot replace these with custom UUIDs. However, you can store a UUID v7 as a regular field (externalId: v.string()) and define an index on it for external lookups. This is the standard pattern for Convex applications that expose stable IDs to external systems.
How do I use UUID v7 in a Convex mutation?
Import the uuid package and call v7() inside a mutation function. Convex mutations run on the server — crypto.getRandomValues() is available in the Convex runtime. Store the UUID v7 as a string field alongside the auto-generated Convex document ID.
Can I use UUID v7 for Convex action correlation IDs?
Yes. Convex actions can call external APIs and run arbitrary async code. Generate a UUID v7 at the start of an action and pass it to all external calls as a trace/correlation header. Because UUID v7 embeds a timestamp, logs from multiple external services can be correlated and sorted by the UUID v7 prefix. See UUID v7 in Microservices.