Minecraft Wiki
Advertisement
Information icon
This feature is exclusive to Java Edition. 

An NBT path is a descriptive label used to specify a collection of particular elements from an NBT data tree. A path has the general form node.….node, where each node declares what types of child tags can be chosen from previous tags.

Nodes[]

These are all seven types of nodes available.

The tags collection start with only one element (i.e. the root tag) and changes along the nodes when resolving path. Tags in the final tag collection are just the targets selected by the NBT path.

Name Format Description Selection Result Example Example Description
Root compound tag {tag}, where tag is the compound NBT content and can be empty. Selects the starting tag, only if it matches the specified content tag (if given).
Only applicable as the first element in an NBT path.
The starting tag, or nothing if matching fails. {Invisible:1b} Selects the root tag if it has a child tag  Invisible with value 1.
{} Selects the root tag.
Named tag name, where name can be a plain string or a quoted string Selects child tags named name in the previous tags. A collection of tags; no more elements than the previous tag collection. May be empty. VillagerData Selects the child tag named VillagerData.
"A cool name[]" Selects the child tag named A cool name[].
Named compound tag name{tag}, where name can be a plain or a quoted string, and tag is the compound NBT content which can be empty. Selects child tags named name in the previous tags, only if they are compound tags, and matching the specified content tag (if given). A collection of compound tags; no more elements than the previous tag collection. May be empty. VillagerData{profession:"minecraft:nitwit"} Select the child tag  VillagerData only if it has a child tag  profession with value minecraft:nitwit.
VillagerData{} Selects the child tag  VillagerData if it is a compound tag.
Element of named list or array tag name[index], where name can be a plain or a quoted string and index is an integer. Selects elements at index (or listLength + index if index is negative) of the child list (or array) tags named name in the previous tags. A collection of tags; no more elements than the previous tag collection. May be empty. Pos[0] Selects the first element in the child tag "Pos" list (or array).
Inventory[-1] Selects the last element in the child tag "Inventory" list (or array).
All elements of named list or array tag name[] Selects all elements of the child list (or array) tags named name in the previous tags. A collection of tags; may have more elements than the previous tag collection. May be empty. ActiveEffects[] Select all the elements in the child tag "ActiveEffects".
Compound Elements of Named List Tag name[{tag}], where name can be a plain or a quoted string and tag is the compound NBT content which can be empty. Selects elements in the child list tags named name in the previous tags, only if the elements are compound tags, and matching the specified content tag (if given). A collection of compound tags; may have more elements than the previous tag collection. May be empty. Inventory[{Count:25b}] Select compound elements of the child  Inventory tag that have a child tag  Count with value 25.
Foo[{}] Selects compound elements of the child  Foo tag.
Elements of the child list (or array) in named list tag name[index or blank][index or blank][index or blank]......[index or tag], where name can be a plain string or a quoted string, index is an integer, and tag is the compound NBT content which can be empty. Selects child elements of the child elements in the lists named name in the previous tags. A collection of tags; may have more elements than the previous tag collection. May be empty. foo[][{}] Select compound elements of the child lists in  foo list.
foo.bar[0][0].baz Select the baz tag in the first compound element of the first list element of the bar list in the  foo tag.

In an NBT path, . (dot/period) characters separate the nodes. Required nodes can be used arbitrarily, except the root compound tag node must be the first in the path when it is present.

Name escaping[]

The valid character set (without quote) for a path seems to be all non-whitespace characters, as long as any opening brackets and braces ([ and {) are closed and at the end of each node (that is, followed by nothing but a period or the end of the path). That being said, the "reasonable character set" for defining a tag name includes all ASCII lowercase and uppercase letters, digits, underscore, period, and square and curly brackets (Regular expression: [a-zA-Z0-9_\.[\]{}]*).

Quoted strings, such as "Lorem ipsum" or 'Lorem ipsum', can be used if a tag name needs to be escaped.

Examples[]

Mixed path[]

  • {}—Specifies the root tag
  • {foo:4.0f}—Specifies the root tag if its children tag "foo" is 4.0f
  • foo—Specifies the tag named "foo" under the root tag
  • foo.bar or foo{}.bar—Specifies foo's children tag named "bar".
  • foo.bar[0]—Specifies the first element of the list (or array) "bar"
  • foo.bar[-1]—Specifies the last element of the list (or array) "bar"
  • foo.bar[0]."A [crazy name]!"—Specifies the children tag named "A [crazy name]!" under that first element
  • foo.bar[0]."A [crazy name]!".baz—Specifies the children tag named "baz" under that crazily named tag
  • foo.bar[]—Specifies all elements of the list (or array) "bar"
  • foo.bar[].baz—Specifies the children tags named "baz" under all elements of the list "bar"
  • foo.bar[{baz:5b}]—Specifies all elements of the list "bar", in which the "baz" tags are 5b
  • foo{bar:"baz"}—Specifies the "foo" tag if its child tag "bar" has the value "baz"
  • foo{bar:"baz"}.bar—Specifies the "bar" tag under "foo", only if it matches the value "baz"

Example 1[]

/data get entity @p foo.bar[0]."A [crazy name]!".baz

These names have been arbitrarily picked, for demonstrative purposes.

  • foo—Specifies the subtag named "foo" under the root tag.
  • foo.bar—Specifies foo's child named "bar".
  • foo.bar[0]—Specifies the first element of the list "bar"
  • foo.bar[0]."A [crazy name]!"—Specifies the child named "A [crazy name]!" under that first element
  • foo.bar[0]."A [crazy name]!".baz—Specifies the child named "baz" under that crazily named element

Example 2[]

/data get block ~ ~ ~ Items[1].tag.pages[3]

A player has written a book and placed it inside a chest at their feet, and are going to work up to the above command in stages. Observe the following imaginary chat log:

History[]

Dark Oak Sapling
This article is a stub. 
You can help by expanding it.
Java Edition
1.20Pre-release 2Single quotation marks are now supported in NBT paths.[1]

References[]

  1. MC-175504 — "Single quotation marks are not supported in NBT paths." — resolved as "Fixed".
Advertisement