Commands/data
< Commands
 |
This feature is exclusive to Java Edition. |
data
| Restrictions | |
|---|---|
| First introduced |
The /data command allows the user to get, merge, modify, and remove NBT data of a block entity, entity, or Command NBT storage[upcoming: 1.15].
- Syntax
There are four instructions for /data (get, merge, modify, remove), and the targets/sources referenced by each instruction command may be either block <targetPos>, entity <target>, or storage <target>[upcoming: 1.15].
data get block <targetPos> [<path>] [<scale>]data get entity <target> [<path>] [<scale>]data merge block <targetPos> <nbt>data merge entity <target> <nbt>data modify block <targetPos> <targetPath> (append|insert <index>|merge|prepend|set) from block <sourcePos> <sourcePath>data modify block <targetPos> <targetPath> (append|insert <index>|merge|prepend|set) from entity <source> <sourcePath>data modify block <targetPos> <targetPath> (append|insert <index>|merge|prepend|set) value <nbt>data modify entity <target> <targetPath> (append|insert <index>|merge|prepend|set) from block <sourcePos> <sourcePath>data modify entity <target> <targetPath> (append|insert <index>|merge|prepend|set) from entity <source> <sourcePath>data modify entity <target> <targetPath> (append|insert <index>|merge|prepend|set) value <value>data remove block <targetPos> <targetPath>data remove entity <target> <path>
- Syntax displayed in various ways
Simplified tree: /data- where substituted arguments are:
<TARGET>=(block <targetPos> | entity <target> | storage <target>)<MODIFICATION>=(append|insert <index>|merge|prepend|set)<SOURCE>=(block <sourcePos> | entity <source>)
Comprehensive tree: /data… get… block <targetPos> [<path>] [<scale>]… entity <target> [<path>] [<scale>]
… merge… block <targetPos> <nbt>… entity <target> <nbt>
… modify… block <targetPos> <targetPath> (append|insert <index>|merge|prepend|set)… from… block <sourcePos> [<sourcePath>]… entity <source> [<sourcePath>]
… value <value>
… entity <target> <targetPath> (append|insert <index>|merge|prepend|set)… from… block <sourcePos> [<sourcePath>]… entity <source> [<sourcePath>]
… value <value>
… remove… block <targetPos> [<targetPath>]… entity <target> [<targetPath>]
Squished tree: /data… get (block <targetPos>|entity <target>) [<path>] [<scale>]… merge (block <targetPos>|entity <target>) <nbt>… modify (block <targetPos>|entity <target>)<targetPath> (append|insert <index>|merge|prepend|set)… from (block <sourcePos>|entity <source>) [<sourcePath>]… value <value>
… remove (block <targetPos>|entity <target>) <path>
Diagram: 
Minimised: /data (get (block <targetPos>|entity <target>) [<path>] [<scale>]|merge (block <targetPos>|entity <target>) <nbt>|modify (block <targetPos>|entity <target>) (append|insert <index>|merge|prepend|set) (from (block <sourcePos>|entity <source>) <sourcePath>|value <value>)|remove (block <targetPos>|entity <target>) <path>)
Maximised: data get block <targetPos> [<path>] [<scale>]data get entity <target> [<path>] [<scale>]data merge block <targetPos> <nbt>data merge entity <target> <nbt>data modify block <targetPos> <targetPath> append from block <sourcePos> <sourcePath>data modify block <targetPos> <targetPath> append from entity <source> <sourcePath>data modify block <targetPos> <targetPath> append value <nbt>data modify block <targetPos> <targetPath> insert <index> from block <sourcePos> <sourcePath>data modify block <targetPos> <targetPath> insert <index> from entity <source> <sourcePath>data modify block <targetPos> <targetPath> insert <index> value <nbt>data modify block <targetPos> <targetPath> merge from block <sourcePos> <sourcePath>data modify block <targetPos> <targetPath> merge from entity <source> <sourcePath>data modify block <targetPos> <targetPath> merge value <nbt>data modify block <targetPos> <targetPath> prepend from block <sourcePos> <sourcePath>data modify block <targetPos> <targetPath> prepend from entity <source> <sourcePath>data modify block <targetPos> <targetPath> prepend value <nbt>data modify block <targetPos> <targetPath> set from block <sourcePos> <sourcePath>data modify block <targetPos> <targetPath> set from entity <source> <sourcePath>data modify block <targetPos> <targetPath> set value <nbt>data modify entity <target> <targetPath> append from block <sourcePos> <sourcePath>data modify entity <target> <targetPath> append from entity <source> <sourcePath>data modify entity <target> <targetPath> append value <value>data modify entity <target> <targetPath> insert <index> from block <sourcePos> <sourcePath>data modify entity <target> <targetPath> insert <index> from entity <source> <sourcePath>data modify entity <target> <targetPath> insert <index> value <value>data modify entity <target> <targetPath> merge from block <sourcePos> <sourcePath>data modify entity <target> <targetPath> merge from entity <source> <sourcePath>data modify entity <target> <targetPath> merge value <value>data modify entity <target> <targetPath> prepend from block <sourcePos> <sourcePath>data modify entity <target> <targetPath> prepend from entity <source> <sourcePath>data modify entity <target> <targetPath> prepend value <value>data modify entity <target> <targetPath> set from block <sourcePos> <sourcePath>data modify entity <target> <targetPath> set from entity <source> <sourcePath>data modify entity <target> <targetPath> set value <value>data remove block <targetPos> <targetPath>data remove entity <target> <path>
- Arguments
(block <targetPos>|entity <target>|storage <target>):
<targetPos>—The<x> <y> <z>position of the target tile entity whose NBT is to be operated on<target>—Valid UUID, or target selector variable for an entity whose NBT is to be operated on<target>—Valid namespaced ID for a storage to be operated on
get . . . [<path>] [<scale>]:
<path>—Valid path name defining the specific NBT to retrieve<scale>—Scalar for the command's return value
merge . . . <nbt>:
<nbt>—Compound tag. The simplest valid imput is{}.
modify . . . <targetPath> (append|insert <index>|merge|prepend|set):
<targetPath>—Valid path name defining the specific target NBT to modify<index>—Valid integer specifying an item's index within a list
… from (block <sourcePos>|entity <source>) <sourcePath>:
<sourcePos>—The<x> <y> <z>position of the source block whose NBT is to be used<source>—Valid player name, UUID, or target selector variable of a source entity whose NBT is to be used<sourcePath>—Valid path name defining the specific source NBT to be used bymodify
… value <value>:
<value>—Numeric value to use in modifying the target NBT. Must match in data type
remove . . . <path>:
<path>—Valid path name to the NBT to remove
- See § NBT path
- Results
- Command fails if the arguments are not specified correctly.
- On success:
/data get-
/data get . . .- Read off the entire NBT data from the targeted block position or entity to the executor with syntax highlighting.
- If applicable, returns 1 on success.
/data get . . . <path>- Send the subsection of the NBT data from the targeted block position or entity to the executor without syntax highlighting.
- Return value depends on the type of the NBT element:
- Retrieving a number returns that number.
- Retrieving a string returns the length of the string.
- Retrieving a list returns the number of elements in that list.
- Retrieving a compound returns the number of tags that are direct children of that compound.
/data get . . . <path> <scale>- Return the value of the tag, scaled by <scale>.
- <path> needs to specify a numeric tag—TAG_byte, TAG_short, TAG_int, TAG_long, TAG_float, or TAG_double.
/data merge- Merge the NBT data from the sourced block position or entity with the specified <nbt> data.
- If applicable, returns 1 on success.
/data modify-
append- Append the source data onto the end of the pointed-to list.
<targetPath>must specify a tag of the TAG_list type, and the source data should be of an item type appropriate for the list.insert <index>- Insert the source data into the pointed-to list as element
<index>, then shift higher elements one position upwards. <targetPath>must specify a tag of the TAG_list type, and the source data should be of an item type appropriate for the list.merge- Merge the source data with the pointed-to object.
<targetPath>must specify a tag of the TAG_list type, and source data must be of the TAG_compound type.prepend- Prepend the source data onto the beginning of the pointed-to list.
<targetPath>must specify a tag of the TAG_list type, and the source data should be of an item type appropriate for the list.set- Set the tag specified by
<targetPath>to the source data.
/data remove- Removes NBT data at <path> from the targeted block position or entity. Player NBT data cannot be removed.
- If applicable, returns 1 on success.
Contents
NBT path[edit]
An NBT data 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 sub-elements can be chosen from a previous tag.
Node[edit]
These are all six types of nodes available.
The tags collection start with only one element (i.e. the root tag) and changes along the nodes on the path. NBT path consumers will operate on the final collection of the tags.
| Name | Format | Description | Selection Result | Example | Example Description |
|---|---|---|---|---|---|
| Root Node with Object | {tag}, where tag is the compound NBT content
|
Selects the starting tag only if it matches the compound tag given. Only applicable as the first element in the path. |
The starting tag, or nothing if matching fails. | {Invisible:1b}
|
Selects the root tag if it has a subtag Invisible with value 1.
|
| Named Node | name, where name can be a plain or an escaped string
|
Selects the subtags named name in the previous tags. | A collection of tags; no more elements than the previous tag collection. May be nothing. | VillagerData
|
Selects the VillagerData subtag. |
"A cool name[]"
|
Selects the A cool name[] subtag. | ||||
| Named Node with Object | name{tag}, where name can be a plain or an escaped string and tag is the compound NBT content
|
Selects the subtags matching the compound tag given and named name in the previous tags. | A collection of tags; no more elements than the previous tag collection. May be nothing. | VillagerData{profession:"minecraft:nitwit"}
|
Select the VillagerData tag only if it has a subtag profession with value minecraft:nitwit.
|
| Indexed List Node | name[index], where name can be a plain or an escaped string and index is an integer
|
Selects elements at index (or listLength + index if index is negative) of the sub-lists named name in the previous tags.
|
A collection of tags; no more elements than the previous tag collection. May be nothing. | Pos[0]
|
Selects the first child tag in the Pos sublist. |
Inventory[-1]
|
Selects the last child tag in the Inventory sublist. | ||||
| All of List Node | name[]
|
Selects all elements of the sub-lists named name in the previous tags. | A collection of tags; may have more elements than the previous tag collection. May be nothing. | ActiveEffects[]
|
Select all the elements in the ActiveEffects subtag of the last tag. |
| List Node with Object | name[{tag}], where name can be a plain or an escaped string and tag is the compound NBT content
|
Selects the elements matching the compound tag given and in the sub-lists named name in the previous tags. | A collection of tags; may have more elements than the previous tag collection. May be nothing. | Inventory[{Count:25b}]
|
Select the elements of Inventory tag that has a subtag Count with value 25.
|
In the path, . (dot/period) characters separate the nodes. The nodes can be mixed and matched, except the root node with object must be the first in the path when it is present.
Name escaping[edit]
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 term (that is, followed by nothing but a period or the end of the path—. or ). That being said, the reasonable character set for defining a data tag would be: a-z A-Z 0-9 _ . [ ] { } (To put this as a Regular expression, [a-zA-Z0-9.[\]{}]*)
Quoted strings, such as "Quoted strings", may be used if a name of a key needs to be escaped.
Examples[edit]
Foo bar example:[edit]
/data get entity @p foo.bar[0]."A [crazy name]!".baz
These names have been arbitrarily picked, for demonstrative purposes.
foo—Specifies the top-level element named "foo"foo.bar—Specifies foo's child named "bar". Let's pretend this is a list.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 elementfoo.bar[0]."A [crazy name]!".baz—Specifies the child named "baz" under that crazily named elementfoo.bar[]—Specifies all elements of the list "bar"foo.bar[].baz—Specifies the children of all elements of the list "bar"foo.bar[{baz:5b}]—Specifies all elements of the list "bar" of which the "baz" tag is set to5b{}—Specifies the root tag of the targeted entity or block{foo:4.0f}—Specifies the root tag of the targeted entity or block if the "foo" tag is set to4.0ffoo{bar:"baz"}—Specifies the "foo" tag if its child "bar" has the value"baz"foo{bar:"baz"}.bar—Specifies the "bar" tag if it matches the value"baz"
The tree structure
- The root entity data
- foo: The "foo" element
- bar: The "bar" element
- The first element of list "bar"
- A [crazy name]!: The "A [crazy name]!" element
- baz: The "baz" element; the target element of this example.
- A [crazy name]!: The "A [crazy name]!" element
- Another unrelated element in list "bar"
- The first element of list "bar"
- bar: The "bar" element
- foo: The "foo" element
Book-in-a-chest example:[edit]
/data get block ~ ~ ~ Items[1].tag.pages[3]
The player has written a book and placed it inside a chest at her feet. She's going to work up to the above command in stages. Observe the following imaginary chat log.
Chat log * Alex jumps on top of a chest. * Alex runs the command: /data get block ~ ~ ~ 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex only wants to look at the chest's inventory. She could search the Official Minecraft Wiki for what the name of that tag is, but because she understands how to read NBT format, she decides to figure it out from that last command's output. * Alex runs the command: /data get block ~ ~ ~ Items 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex wants to narrow this down to the second item in the chest. She starts counting from 0, so the second item would be element 1. * Alex runs the command: /data get block ~ ~ ~ Items[1] 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex wants just the "tag" tag. * Alex runs the command: /data get block ~ ~ ~ Items[1].tag 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex wants just the "pages" tag. * Alex runs the command: /data get block ~ ~ ~ Items[1].tag.pages 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex wants just the fourth element from this list. * Alex runs the command: /data get block ~ ~ ~ Items[1].tag.pages[3] 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex has what she needs now... She uses the paths she's gathered to edit the book from outside the chest. * Alex runs the command: /data modify block ~ ~ ~ Items[1].tag.pages[3] set value '{"text":"And this pig here\'s named Babe."}' Modified block data of 0 55 0 * Alex runs the command: /data modify block ~ ~ ~ Items[1].tag.pages prepend value '{"text":"Call me Ishmael."}' Modified block data of 0 55 0 * Alex runs the command: /data modify block ~ ~ ~ Items[1].tag.author set value "Cthulhu the Sleeper"
Storage[edit]
 |
This page contains content on features that may be included in the next update to Java Edition. These features have appeared in Java Edition development versions, but the full update containing these features has not been released for Java Edition yet.
|
See also: command storage format
The command storage of NBT data is an efficient way for commands to access or save NBT data without an overhead for block entities or entities reading from or writing to the NBT data.
Each command storage is a general purpose, key-value storage, identified by a namespaced ID to prevent unintentional conflicts.
/data get and /data modify can read from the storage, while /data merge, /data modify, /data remove, and /execute store can write to the storage.
The command storage is accessible with JSON text as well.
History[edit]
| Java Edition | |||||
|---|---|---|---|---|---|
| 1.13 | 17w45b | Added /data. | |||
| 18w03a | /data get with a path now works on non-numeric values. | ||||
| 1.14 | 18w43a | Added /data modify. | |||
| Upcoming Java Edition | |||||
| 1.15 | 19w38a | Added command storage. | |||
Added storage <namespaced ID> as a source or target. | |||||
| 19w39a | Added NBT storage chat component. | ||||
