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

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.