IDs and Paths

Every document in Sanity must have an ID that identifies it, an arbitrary string made up of the characters a-zA-Z0-9._-. This ID is specified in the document's _id attribute, and must be unique within a dataset. An ID cannot be modified once a document is created, since it is used to track the document's history and relations.

The content 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 via the 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 - kind of like folders on your computer. Note that since the content studio does not allow you to specify IDs yourself, you cannot use paths with documents created in the studio.

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.


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.

Previous: TransactionsNext: Importing Data