Commands/data

From Minecraft Wiki
Jump to: navigation, search
data
Restrictions

Operator

Information icon.svg
This feature is exclusive to Java Edition.

The /data command allows the user to get, merge, modify, and remove NBT data of a block entity, entity, or Command NBT storage.

Syntax[edit]

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

/data ...
... get
... (block <targetPos>|entity <target>|storage <target>) [<path>] [<scale>]
Read off the entire NBT data or the subsection of the NBT data from the targeted block position or entity to the executor with syntax highlighting, scaled by <scale> if specified.
... merge
... (block <targetPos>|entity <target>|storage <target>) <nbt>
Merge the NBT data from the sourced block position or entity with the specified <nbt> data.
... modify (block <targetPos>|entity <target>|storage <target>) <targetPath> ...
... append from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
... append value <value>
Append the source data onto the end of the pointed-to list.
... insert <index> from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
... insert <index> value <value>
Insert the source data into the pointed-to list as element <index>, then shift higher elements one position upwards.
... merge from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
... merge value <value>
Merge the source data into the pointed-to object.
... prepend from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
... prepend value <value>
Prepend the source data onto the beginning of the pointed-to list.
... set from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
... set value <value>
Set the tag specified by <targetPath> to the source data.
... remove
... (block <targetPos>|entity <target>|storage <target>) <path>
Removes NBT data at <path> from the targeted block position or entity. Player NBT data cannot be removed.


Syntax displayed in various ways

Arguments[edit]

<targetPos>: block_pos

It must be a block position composed of <x>, <y> and <z>, each of which must be an integer or tilde and caret notation.
The position of the target block entity whose NBT is to be operated on.

<target>: entity (in entity <target> mode)

Must be a player name, a target selector or a UUID.  And the target selector must be of single type.
Speciafies an entity whose NBT is to be operated on.

<target>: resource_location (in storage <target> mode)

Must be a namespaced ID.
Specifies a storage to be operated on.

<path>: nbt_path

Must be an NBT path.
Specifies the NBT to retrieve or remove.

<scale>: double

Must be a Double-precision floating-point format number.
Scalar for the command's return value.

<nbt>: nbt_compound_tag

Must be a Double-precision floating-point format number.
Specifies a compound tag to be merged into somewhere.

<targetPath>: nbt_path

Must be an NBT path.
Specifies target NBT to modify.

<index>: integer

Must be a 32-bit integer number. And it must be between -2147483648 and 2147483647 (inclusive).
Specifies an item's index within a list.

<sourcePos>: block_pos

It must be a block position composed of <x>, <y> and <z>, each of which must be an integer or tilde and caret notation.
The position of the target block entity whose NBT is to be used.

<sourceEntity>: entity

Must be a player name, a target selector or a UUID.  And the target selector must be of single type.
Speciafies an entity whose NBT is to be used by modify.

<sourceStorage>: resource_location

Must be a namespaced ID.
Specifies a storage to be used by modify.

<sourcePath>: nbt_path

Must be an NBT path.
Specifies the source NBT to be used by modify.

<value>: nbt_tag

Must be an NBT tag of any type in SNBT format.
Value used in modifying the target NBT. Should match in data type.

Result[edit]

CommandTriggerJava Edition
anythe arguments are not specified correctly Unparseable
if <targetPos> is unloaded or out of the world Failed
if the block at <targetPos> is not a block entity
if <target> (in entity <target> mode) fails to resolve to an entity (named player must be online)
/data get ...if more than one tag is got
/data get ... <path>if <path> does not exist
/data get ... <path> <scale>if the obtained tag is not a numeric tag
/data merge ...
/data remove ...
/data modify ...
if nothing is changed
try to edit player's data
/data remove ...if <path> is {}(the root tag)
/data modify ... from block ...if <sourcePos> is unloaded or out of the world
if the block at <sourcePos> is not a block entity
/data modify ... from entity ...if <sourceEntity> fails to resolve to an entity (named player must be online)
/data modify ... from ... <sourcePath>if <sourcePath> does not exist
/data modify ... append ...
/data modify ... insert <index> ...
/data modify ... prepend ...
if the target tag isn't a list or array
if source data isn't of an item type appropriate for the list
/data modify ... insert <index> ...if the index is invalid
/data modify ... merge ...if the target path does not specify a compound tag
if the source data is not a compound tag
anyOn successGet, merge, modify, and remove NBT data.

Output[edit]

CommandEditionSituationSuccess Count/execute store succeess .../execute store result ...
anyJava EditionOn fail000
/data get ...On success111
/data get ... <path>if a numeric tag is got11the obtained value after rounding down[1]
if a list or array tag is got11The number of elements in this list or array
if a string tag is got11The length of the string
if a compound tag is got11The number of tags that are direct children of that compound
/data get ... <path> <scale>On success11the obtained value multiplied by <scale>, then rounded down[2]
/data merge ...On success111
/data remove ...On success111
/data modify ... append ...
/data modify ... insert <index> ...
/data modify ... prepend ...
On success11the number of lists or arrays to which new elements are added
/data modify ... set ...On success11the number of target tags that was successfully modified
/data modify ... merge ...On success11the number of target compound tags that was successfully modified

Examples[edit]

  • To make all items within 10 blocks unable to be picked up by players:
    /data modify entity @e[type=item,distance=..10,limit=1,sort=nearest] PickupDelay set value -1
  • To get the Y-position of a random item:
    /data get entity @e[type=item,limit=1,sort=random] Pos[1]
  • To get the item ID of the item in the first hotbar slot of the nearest player:
    /data get entity @p Inventory[{Slot:0b}].id
  • To set the armor attribute of the dolphin closest to coordinates (0, 64, 0) to 20:
    /data modify entity @e[x=0,y=64,z=0,type=dolphin,limit=1] Attributes[{Name:"generic.armor"}].Base set value 20
  • To change the first item in a chest located at coordinates (1, 64, 1) into a diamond block, keeping all NBT data:
    /data modify block 1 64 1 Items[0].id set value "minecraft:diamond_block"

Storage[edit]

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.1317w45bAdded /data.
17w47aCommands /blockdata and /entitydata have been removed as their features are merged into /data.
18w03aUsing /data get with a path now works on non-numeric values.
1.1418w43aAdded /data modify.
1.1519w38aAdded command storage.
Added storage <namespaced ID> as a source or target.
19w39aAdded NBT storage chat component.

References[edit]

  1. double n = (double)value
    int output = n < (int)n ? (int)n - 1 :(int)n
  2. double n = (double)value * scale
    int output = n < (int)n ? (int)n - 1 :(int)n