Skip to content

docs(data-modeling): state the autonumber contract — unique and monotonic, not gapless #8525

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
qq9340100 merged 1 commit into from
Aug 13, 2026
+22 −0
Merged

docs(data-modeling): state the autonumber contract — unique and monotonic, not gapless #8525

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions content/docs/data-modeling/field-types.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -483,6 +483,21 @@ Auto-incrementing number with format template.
{ name: 'ticket_number', label: 'Ticket #', type: 'autonumber', autonumberFormat: 'TKT-{0000}' }
```

<Callout type="warn">
**An autonumber is unique and monotonic per scope — it is not gapless.** Any
write that gets rejected after the number was reserved — a unique violation on
another field, a failed validation rule, a `beforeInsert` hook that throws —
still consumes that number, and it is never reissued. `TKT-0001` succeeding and
`TKT-0002` failing means the next row is `TKT-0003`; `TKT-0002` will not exist.

This is a decided property of the counter, not a bug to work around. If you are
building an invoice, contract, or receipt sequence on an `autonumber` field,
design for gaps: an autonumber guarantees a unique, ever-increasing business
identifier, but it is **not** a legally gapless document number. Treat that
guarantee as a separate requirement to satisfy explicitly, not something
`autonumber` already gives you.
</Callout>

---

## Embedded Structured Types
Expand Down
7 changes: 7 additions & 0 deletions content/docs/data-modeling/schema-design.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,13 @@ Field.autonumber({
// no separate reset config. A fixed prefix like 'INV-{000}' keeps one global counter.
```

The counter is unique and monotonic per scope, **not gapless** — a rejected
write (a unique violation on another field, a failed validation rule, a
throwing `beforeInsert`) still consumes the number it reserved. Before wiring
an `autonumber` field to an invoice, contract, or receipt sequence, see the
[full contract](/docs/data-modeling/field-types#autonumber) in the Field Type
Gallery.

### User Fields

Pick a person — the equivalent of Airtable's *Collaborator* or Salesforce's
Expand Down
Loading