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 };
  },
});

See UUID as Idempotency Keys.

Further reading

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.