@Documented @Retention(RUNTIME) @Target(METHOD) public @interface Insert

The Insert annotation indicates that the annotated repository method requests that one or more entities be inserted into the database. This method must have a single parameter whose type must be one of the following:

The entity to be inserted.
An Iterable of entities to be inserted.
An array of entities to be inserted.

The return type of an annotated method that requires a single entity as the parameter must have a return type that is void, Void, or the same type as the parameter. The return type of an annotated method that accepts an Iterable or array of entities as the parameter must have a return type that is void, Void, or an Iterable or array of the entity. For example, if the method is annotated with @Insert and takes a parameter of type Car car, the return type can be Car. Similarly, if the parameter is an Iterable<Car> or an array of Car, the return type can be Iterable<Car>. Entities that are returned by the annotated method must include all values that were written to the database, including all automatically generated values and incremented values that changed due to the insert. The position of entities within an Iterable or array return value must correspond to the position of entities in the parameter based on the unique identifier of the entity.

After invoking this method, it is recommended not to use the entity value supplied as a parameter, as this method makes no guarantees about the state of the entity value after insertion.

If an entity of this type with the same unique identifier already exists in the database and the databases performs ACID (atomic, consistent, isolated, durable) transactions, then annotated method raises EntityExistsException. In databases that follow the BASE model or use an append model to write data, this exception is not thrown.

For example, consider an interface representing a garage:

 @Repository
 interface Garage {
     @Insert
     Car park(Car car);
 }

The @Insert annotation can be used to indicate that the park(Car) method is responsible for inserting a Car entity into a database.

If this annotation is combined with other operation annotations (e.g., @Update, @Delete, @Save), it will throw an UnsupportedOperationException because only one operation type can be specified. A Jakarta Data provider implementation must detect (and report) this error at compile time or at runtime.

Annotation Interface Insert