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

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.