Happening this week! Hear how Amplitude built a self-serve marketing engine to drive growth 🚀

IDs and Paths

How document IDs work, and what you can do with them

IDs

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.

Gotcha

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.

Paths

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 drafts. path.

Gotcha

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.

Was this article helpful?