Convex manages its own document IDs, but UUID v7 works as an application-level identifier for cross-service correlation. See UUID v7 in Convex for the full guide.
Convex 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 — time-ordered, cross-service
customerId: v.string(),
total: v.number(),
status: v.string(),
}).index('by_external_id', ['externalId']),
});
Mutation 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 create = mutation({
args: { customerId: v.string(), total: v.number() },
handler: async (ctx, args) => {
const externalId = uuidv7(); // UUID v7 — encode creation time
return ctx.db.insert('orders', {
externalId,
customerId: args.customerId,
total: args.total,
status: 'pending',
});
},
});
// Query by UUID v7 external ID
export const getByExternalId = query({
args: { id: v.string() },
handler: async (ctx, args) =>
ctx.db
.query('orders')
.withIndex('by_external_id', q => q.eq('externalId', args.id))
.unique(),
});
Cursor pagination on UUID v7 externalId
export const list = query({
args: { cursor: v.optional(v.string()), limit: v.number() },
handler: async (ctx, { cursor, limit }) => {
let q = ctx.db.query('orders').withIndex('by_external_id');
if (cursor) q = q.filter(r => r.gt(r.field('externalId'), cursor));
const items = await q.order('asc').take(limit);
return {
items,
nextCursor: items.length === limit ? items.at(-1)?.externalId : null,
};
},
});
Further reading
- UUID v7 in Convex — 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 Convex document ID?
Convex generates its own document IDs automatically — you cannot override the _id field. However, you can store a UUID v7 as a separate externalId field with a unique index. This gives you a time-ordered, globally unique identifier for cross-service correlation while Convex manages its own internal ID. See What is a UUID.
How does UUID v7 help with Convex real-time queries?
Convex queries are reactive — they re-run when underlying data changes. Store UUID v7 as an externalId field and index it: index('by_external_id', ['externalId']). Clients can subscribe to useQuery(api.orders.getByExternalId, { id }). UUID v7's embedded timestamp lets you extract when the record was created without a separate _creationTime field. See UUID v7 in Distributed Systems.
How do I use UUID v7 for Convex cursor pagination?
Convex's paginate() uses Convex-native cursors. For UUID v7 pagination, store the UUID as externalId and query .filter(q => q.gt(q.field('externalId'), cursor)) after ordering. UUID v7 lexicographic order equals chronological order, so this gives you time-ordered pages. See UUID v7 for Cursor Pagination.