# Primary updating expressions
Update expressions are the visible part of JSONiq Updates in the language. Each primary updating expression contributes an update primitive to the Pending Update List being built.
## Nested updates (memory or persistent)
These expressions may appear in a copy-modify-return (transform) expression (for in-memory updates on cloned values), or outside (for persistent updates to an underlying storage).
### **Inserting values into an object or array**
A JSON insert expression is used to insert new pairs into an object. It produces a *jupd:insert-into-object* update primitive. If the target is not an object, JNUP0008 is raised. If the content is not a sequence of objects, JNUP0019 is raised. These objects are merged prior to inserting the pairs into the target, and JNDY0003 is raised if the content to be inserted has colliding keys.
**Example**
```
copy $obj := { "foo" : "bar" }
modify insert json { "bar" : 123, "foobar" : [ true, false ] } into $obj
return $obj
```
**Result:** { "foo" : "bar", "bar" : 123, "foobar" : \[ true, false ] }
A JSON insert expression is also used to insert a new member into an array. It produces a *jupd:insert-into-array* update primitive. If the target is not an array, JNUP0008 is raised. If the position is not an integer, JNUP0007 is raised.
**Example**
```
copy $arr := { "foo" : [1,2,3,4] }
modify insert json 5 into $arr.foo at position 3
return $arr
```
**Result:** { "foo" : \[ 1, 2, 5, 3, 4 ] }
### **Deleting values in an object or array**
A JSON delete expression is used to remove a pair from an object. It produces a *jupd:delete-from-object* update primitive. If the key is not a string, JNUP0007 is raised. If the key does not exist, JNUP0016 is raised.
**Example**
```
copy $obj := { "foo" : "bar", "bar" : 123 }
modify delete json $obj.foo
return $obj
```
**Result:** { "bar" : 123 }
A JSON delete expression is also used to remove a member from an array. It produces a *jupd:insert-from-array* update primitive. If the position is not an integer, JNUP0007 is raised. If the position is out of range, JNUP0016 is raised.
**Example**
```
copy $arr := [1,2,3,4,5,6]
modify delete json $arr[[3]]
return $arr
```
**Result:** \[ 1, 2, 4, 5, 6 ]
### **Renaming a key**
A JSON rename expression is used to rename a key in an object. It produces a *jupd:rename-in-object* update primitive. If the sequence on the left of the dot is not a single object, JNUP0008 is raised. If the new name is not a single string, JNUP0007 is raised. If the old key does not exist, JNUP0016 is raised.
**Example 196. JSON rename expression**
```
copy $obj := { "foo" : "bar", "bar" : 123 }
modify rename json $obj.foo as "foobar"
return $obj
```
**Result:** { "foobar" : "bar", "bar" : 123 }
### **Appending values to an array**
A JSON append expression is used to add a new member at the end of an array. It produces a *jupd:insert-into-array* update primitive. JNUP0008 is raised if the target is not an array.
**Example 197. JSON append expression**
```
copy $obj := { "foo" : "bar", "bar" : [1,2,3] }
modify append json 4 into $obj.bar
return $obj
```
**Result:** { "foo" : "bar", "bar" : \[ 1, 2, 3, 4 ] }
### **Replacing a value in an object or array.**
A JSON replace expression is used to replace the value associated with a certain key in an object. It produces a *jupd:replace-in-object* update primitive. JNUP0007 is raised if the selector is not a single string. If the selector key does not exist, JNUP0016 is raised.
**Example**
```
copy $obj := { "foo" : "bar", "bar" : [1,2,3] }
modify replace value of json $obj.foo with { "nested" : true }
return $obj
```
**Result:** { "foo" : { "nested" : true }, "bar" : \[ 1, 2, 3 ] }
A JSON replace expression is also used to replace a member in an array. It produces a *jupd:insert-in-array* update primitive. JNUP0007 is raised if the selector is not a single position. If the selector position is out of range, JNUP0016 is raised.
**Example**
```
copy $obj := { "foo" : "bar", "bar" : [1,2,3] }
modify replace value of json $obj.bar[[2]] with "two"
return $obj
```
**Result:** { "foo" : "bar", "bar" : \[ 1, "two", 3 ] }
## Update expressions at the collection top-level (persistent only)
These expressions may not appear in a copy-modify-return (transform) expression because they can only be used for persistent updates to an underlying storage (document store, data lakehouse, etc).
### Creating a collection
This expression creates an update primitive that creates a collection.
**Example**
```
create collection table("mytable") with ({"foo":1},{"foo":2}),
create collection delta-file("/path/to/file.delta") with ({"foo":1},{"foo":2})
```
### Deleting a collection
This expression creates an update primitive that deletes a collection.
**Example**
```
delete collection table("mytable"),
delete collection delta-file("/path/to/file.delta")
```
### Inserting into a collection
This expression creates an update primitive that inserts values at the beginning or end of a collection, or before or after specific values in that collection.
**Example**
```
insert {"foo":3} first into collection table("mytable"),
insert {"foo":4} last into collection delta-file("/path/to/file.delta"),
insert {"foo":3} before table("mytable")[3] into collection,
insert {"foo":3} after delta-file("/path/to/file.delta")[3] into collection
```
### Editing a value in a collection
This expression creates an update primitive that modifies a value in a collection into the other supplied value.
**Example**
```
edit table("mytable")[1] into {"foo":3} in collection
```
### Deleting a value from a collection
This expression creates an update primitive that deletes a specified value from its collection.
**Example**
```
delete table("mytable")[1] from collection
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.rumbledb.org/the-jsoniq-language/jsoniq-update-facility/primary-updating-expressions.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
