Perspectives

A perspective decides which rows a query can see and what _id they report.

drafts is an overlay, not a filter

This is the one that catches people, and it is worth stating flatly: drafts does not mean "only drafts". It is the draft-over-published overlay — the view an editor has. previewDrafts is a deprecated alias for the same thing.

Reading it as "only draft documents" is the intuitive interpretation and it is wrong in a way nothing catches: perspective=drafts is what the Studio and every preview deployment send, so implementing it that way silently drops every published document that has no draft.

The four overlay cases

• Both rows exist — the draft wins, and the published row is not reported separately.
• Draft only — reported as if published, so _id is the published id even though no row carries it.
• Published only — content unchanged, but _originalId is still set, to its own id. Sanity sets it on every document under this perspective, not only on overlaid ones.
• Neither — nothing.

A drafts.-prefixed id resolves to nothing under published or either overlay. raw is the only way to address a draft row by its own id, and that falls out of matching on the published id rather than from a separate filter.

Who may ask for what

published is available to anyone, including anonymous readers. The overlays require a session with a role that grants draft reads, or a valid preview secret. This is enforced in the API and by the database policies, so a bug in one does not expose the other.