Mutations

EdgeDB provides GraphQL mutations to perform DELETE, INSERT and UPDATE operations.

The “delete” mutation is very similar in structure to a query. Basically, it works the same way as a query, using the filter, order, and various pagination parameters to define a set of objects to be deleted. These objects are also returned as the result of the delete mutation. Each object type has a corresponding delete_ mutation:

GraphQL

EdgeQL equivalent

Copy
mutation delete_all_books {
    delete_Book {
        title
        synopsis
        author {
            name
        }
    }
}
Copy
SELECT (
    DELETE Book
) {
    title,
    synopsis,
    author: {
        name
    }
};
Copy
mutation delete_book_spam {
    delete_Book(
        filter: {
            title: {
                eq: "Spam"
            }
        }
    ) {
        title
        synopsis
    }
}
Copy
SELECT (
    DELETE Book
    FILTER
        Book.title = 'Spam'
) {
    title,
    synopsis
};
Copy
mutation delete_one_book {
    delete_Book(
        filter: {
            author: {
                name: {
                    eq:
            "Lewis Carroll"
                }
            }
        },
        order: {
            title: {
                dir: ASC
            }
        },
        first: 1
    ) {
        title
        synopsis
    }
}
Copy
SELECT (
    DELETE Book
    FILTER
        Book.author.name =
            'Lewis Carroll'
    ORDER BY
        Book.title ASC
    LIMIT 1
) {
    title,
    synopsis
};

The “insert” mutation exists for every object type. It allows creating new objects and supports nested insertions, too. The objects to be inserted are specified via the data parameter, which takes a list of specifications. Each such specification has the same structure as the object being inserted with required and optional fields (although if a field is required in the object, but has a default it’s optional in the insert specification):

GraphQL

EdgeQL equivalent

Copy
mutation insert_books {
    insert_Book(
        data: [{
            title: "One"
        }, {
            title: "Two"
        }]
    ) {
        id
        title
    }
}
Copy
SELECT {
    (INSERT Book {
        title := "One"
    }),
    (INSERT Book {
        title := "Two"
    })
} {
    id,
    title
};

It’s possible to insert a nested structure all at once (e.g. a new book and a new author):

GraphQL

EdgeQL equivalent

Copy
mutation insert_books {
    insert_Book(
        data: [{
            title: "Three",
            author: {
                data: {
                    name:
                "Unknown"
                }
            }
        }]
    ) {
        id
        title
    }
}
Copy
SELECT (
    INSERT Book {
        title := "Three",
        author := (
            INSERT Author {
                name :=
                "Unknown"
            }
        )
   }
) {
    id,
    title
};

It’s also possible to insert a new object that’s connected to an existing object (e.g. a new book by an existing author). In this case the nested object is specified using filter, order, and various pagination parameters to define a set of objects to be connected:

GraphQL

EdgeQL equivalent

Copy
mutation insert_book {
    insert_Book(
        data: [{
            title: "Four",
            author: {
                filter: {
    name: {eq: "Unknown"}
                }
            }
        }]
    ) {
        id
        title
    }
}
Copy
SELECT (
    INSERT Book {
        title := "Four",
        author := (
            SELECT Author
            FILTER
            Author.name =
                "Unknown"
        )
    }
) {
    id,
    title
};

The “update” mutation has features that are similar to both an “insert” mutation and a query. On one hand, the mutation takes filter, order, and various pagination parameters to define a set of objects to be updated. On the other hand, the data parameter is used to specify what and how should be updated.

The data parameter contains the fields that should be altered as well as what type of update operation must be performed (set, increment, append, etc.). The particular operations available depend on the type of field being updated.

GraphQL

EdgeQL equivalent

Copy
mutation update_book {
    update_Book(
        filter: {
            title: {
                eq: "One"
            }
        }
        data: {
            synopsis: {
                set: "TBD"
            }
            author: {
                set: {
        filter: {
            name: {
                eq:
                "Unknown"
            }
        }
                }
            }
        }
    ) {
        id
        title
    }
}
Copy
WITH
    Upd := (
        UPDATE Book
        FILTER
            Book.title =
                "One"
        SET {
            synopsis :=
                "TBD",
            author := (
            SELECT Author
            FILTER
            Author.name =
                "Unknown"
            )
        }
    )
SELECT Upd {
    id,
    title
};
Light
Dark
System