IDs and Paths
How document IDs work, and what you can do with them
Every document in a Sanity dataset must have an ID that identifies it, an arbitrary string made up of the characters
a-zA-Z0-9._-. Note that an ID cannot start with a
- (dash) character. E.g.
-abcde-12345 would be an invalid ID.
The ID is specified in the document’s
_id property, and must be unique within the dataset. The ID cannot be modified once a document is created, since it is used to track the document’s history and relations.
The Sanity Studio automatically generates a random UUID for new documents (e.g.
189bc292-e41b-42a0-91b5-bfaa33a34af2), and does not allow you to specify an ID yourself, but you are free to use your own ID scheme for documents that you create using the HTTP API.
For technical reasons, every document ID ever written to a dataset will be retained in our systems until the dataset is deleted, even if the document itself is deleted. For this reason, we strongly recommend you never put personal data or other sensitive data in document IDs.
IDs are also considered paths, separated by periods. You can use this to organize documents into namespaces by using IDs like
animal.mammal.dog – kind of like folders on your computer. Note that path segments cannot start with the
- (dash) character. E.g. a
dog.-abcde-12345 would be an invalid ID.
GROQ provides a
path() function that allows you to filter documents by path, such as fetching all mammals with
_id in path("animal.mammal.*") or fetching all animals with
_id in path("animal.**"). In path expressions,
* is taken to mean “anything up to the next period”, while
** means “anything including periods”. The
path() function currently only works with the
_id attribute, since it requires special indexing.
Sanity also uses paths for storing various internal data in your datasets. For example, internal objects like groups are stored under the
_. path, and the content studio stores draft documents under the
The default, fixed access control rules give unauthenticated users read access to documents under the root path only, which means that it is not possible to make documents under a sub-path (i.e. containing a
. in the ID) publicly available. This currently cannot be changed unless you have custom access controls enabled on your plan.