Skip to content
This repository was archived by the owner on Jul 9, 2025. It is now read-only.

Commit a39b5d3

Browse files
nakamura-tonakamura-to
authored
Add descriptions for duplicateKeyType and duplicateKeys (#20)
1 parent 233703d commit a39b5d3

File tree

3 files changed

+120
-33
lines changed

3 files changed

+120
-33
lines changed

‎docs/query/batch-insert.rst‎

Lines changed: 41 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,8 @@ Version number
6161
If value that explicitly set is over ``0`` then use the value if :doc:`../entity` has property that is annotated with ``@Version``.
6262
If the value is not set or is less than ``0`` the value is set ``1`` automatically.
6363

64-
Insert target property
65-
-----------------------
64+
Properties of @BatchInsert
65+
---------------------------
6666

6767
insertable
6868
~~~~~~~~~~
@@ -92,6 +92,40 @@ Even if property is specified with this element the property is excluded from in
9292
@BatchInsert(include = {"name", "salary"})
9393
int[] insert(List<Employee> employees);
9494
95+
duplicateKeyType
96+
~~~~~~~~~~~~~~~~
97+
98+
This property defines the strategy for handling duplicate keys during an insert operation.
99+
100+
It can take one of three values:
101+
102+
* ``DuplicateKeyType.UPDATE``: If a duplicate key is encountered, the existing row in the table will be updated.
103+
* ``DuplicateKeyType.IGNORE``: If a duplicate key is encountered, the insert operation will be ignored, and no changes will be made to the table.
104+
* ``DuplicateKeyType.EXCEPTION``: If a duplicate key is encountered, an exception will be thrown.
105+
106+
.. code-block:: java
107+
108+
@BatchInsert(duplicateKeyType = DuplicateKeyType.UPDATE)
109+
int[] insert(List<Employee> employees);
110+
111+
duplicateKeys
112+
~~~~~~~~~~~~~
113+
114+
This property represents the keys that should be used to determine if a duplicate key exists. If the duplicate key exists, the operation will use the ``duplicateKeyType`` strategy to handle the duplicate key.
115+
116+
.. code-block:: java
117+
118+
@BatchInsert(duplicateKeyType = DuplicateKeyType.UPDATE, duplicateKeys = {"employeeNo"})
119+
int[] insert(List<Employee> employees);
120+
121+
.. note::
122+
123+
This property is only utilized when the ``duplicateKeyType`` strategy is either ``DuplicateKeyType.UPDATE`` or ``DuplicateKeyType.IGNORE``.
124+
125+
.. note::
126+
127+
The MySQL dialect does not utilize this property.
128+
95129
Batch insert by SQL file
96130
===========================
97131

@@ -124,22 +158,13 @@ For example, you describe SQL like below to correspond above method.
124158
Parameter name indicate ``java.lang.Iterable`` subtype element in SQL file.
125159

126160
Identifier auto setting and version number auto setting are not executed in batch insert by SQL file.
127-
Also, ``exclude`` property and ``include`` property within ``@BatchInsert`` are not referenced.
128161

129-
Batch upsert
130-
===========================
131-
132-
you can specify whether to update or ignore using a ``duplicateKeyType`` property In case of duplication.
133-
By default, it is ``DuplicateKeyType.EXCEPTION`` , and an error will occur in case of duplicated.
134-
There are 3 types to choose from: ``DuplicateKeyType.UPDATE`` , ``DuplicateKeyType.IGNORE`` , ``DuplicateKeyType.EXCEPTION`` .
135-
136-
.. code-block:: java
137-
138-
@BatchInsert(duplicateKeyType = DuplicateKeyType.UPDATE)
139-
int[] insertOnDuplicateKeyUpdate(List<Employee> employees);
162+
Additionally, the following properties of ``@BatchInsert`` are not used:
140163

141-
@BatchInsert(duplicateKeyType = DuplicateKeyType.IGNORE)
142-
int[] insertOnDuplicateKeyIgnore(List<Employee> employees);
164+
* exclude
165+
* include
166+
* duplicateKeyType
167+
* duplicateKeys
143168

144169
Unique constraint violation
145170
============================

‎docs/query/insert.rst‎

Lines changed: 43 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,8 @@ If value that explicitly set is over 0 then use the value if :doc:`../entity` ha
6161

6262
If the value is not set or is less than 0 the value is set 1 automatically.
6363

64-
Control insertion target property
65-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64+
Properties of @Insert
65+
---------------------
6666

6767
insertable
6868
~~~~~~~~~~
@@ -105,6 +105,41 @@ the property is excluded from insertion if value is ``null``.
105105
@Insert(excludeNull = true)
106106
int insert(Employee employee);
107107
108+
duplicateKeyType
109+
~~~~~~~~~~~~~~~~
110+
111+
This property defines the strategy for handling duplicate keys during an insert operation.
112+
113+
It can take one of three values:
114+
115+
* ``DuplicateKeyType.UPDATE``: If a duplicate key is encountered, the existing row in the table will be updated.
116+
* ``DuplicateKeyType.IGNORE``: If a duplicate key is encountered, the insert operation will be ignored, and no changes will be made to the table.
117+
* ``DuplicateKeyType.EXCEPTION``: If a duplicate key is encountered, an exception will be thrown.
118+
119+
.. code-block:: java
120+
121+
@Insert(duplicateKeyType = DuplicateKeyType.UPDATE)
122+
int insert(Employee employee);
123+
124+
duplicateKeys
125+
~~~~~~~~~~~~~
126+
127+
This property represents the keys that should be used to determine if a duplicate key exists. If the duplicate key exists, the operation will use the ``duplicateKeyType`` strategy to handle the duplicate key.
128+
129+
.. code-block:: java
130+
131+
@Insert(duplicateKeyType = DuplicateKeyType.UPDATE, duplicateKeys = {"employeeNo"})
132+
int insert(Employee employee);
133+
134+
.. note::
135+
136+
This property is only utilized when the ``duplicateKeyType`` strategy is either ``DuplicateKeyType.UPDATE`` or ``DuplicateKeyType.IGNORE``.
137+
138+
.. note::
139+
140+
The MySQL dialect does not utilize this property.
141+
142+
108143
Insert by SQL file
109144
=====================
110145

@@ -135,22 +170,14 @@ For example, you describe SQL file like below to correspond above method.
135170
/* employee.version */0)
136171
137172
Identifier auto setting and version value auto setting is not done in insertion by SQL file.
138-
Also, ``exclude`` element and ``include`` element and ``excludeNull`` element of ``@Insert`` are not referenced.
139173

140-
Upsert
141-
===========================
142-
143-
you can specify whether to update or ignore using a ``duplicateKeyType`` property In case of duplication.
144-
By default, it is ``DuplicateKeyType.EXCEPTION`` , and an error will occur in case of duplicated.
145-
There are 3 types to choose from: ``DuplicateKeyType.UPDATE`` , ``DuplicateKeyType.IGNORE`` , ``DuplicateKeyType.EXCEPTION`` .
146-
147-
.. code-block:: java
148-
149-
@Insert(duplicateKeyType = DuplicateKeyType.UPDATE)
150-
int insertOnDuplicateKeyUpdate(Employee employee);
174+
Additionally, the following properties of ``@Insert`` are not used:
151175

152-
@Insert(duplicateKeyType = DuplicateKeyType.IGNORE)
153-
int insertOnDuplicateKeyIgnore(Employee employee);
176+
* exclude
177+
* include
178+
* excludeNull
179+
* duplicateKeyType
180+
* duplicateKeys
154181

155182
Unique constraint violation
156183
===========================

‎docs/query/multi-row-insert.rst‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,9 @@ Also the ``postInsert`` method of entity listener method is called each entity w
3636
* MySQL
3737
* PostgreSQL
3838
* SQL Server
39+
* Oracle Database
3940

40-
However, in the case of SQL Server, this feature cannot be executed on tables with an auto-increment primary key.
41+
However, in the case of SQL Server and Oracle, this feature cannot be executed on tables with an auto-increment primary key.
4142

4243
Return type
4344
===========
@@ -100,6 +101,40 @@ Entity properties with ``insertable`` set to ``false`` in the ``@Column`` annota
100101
@MultiInsert(include = {"name", "salary"})
101102
int insert(List<Employee> employees);
102103
104+
duplicateKeyType
105+
----------------
106+
107+
This property defines the strategy for handling duplicate keys during an insert operation.
108+
109+
It can take one of three values:
110+
111+
* ``DuplicateKeyType.UPDATE``: If a duplicate key is encountered, the existing row in the table will be updated.
112+
* ``DuplicateKeyType.IGNORE``: If a duplicate key is encountered, the insert operation will be ignored, and no changes will be made to the table.
113+
* ``DuplicateKeyType.EXCEPTION``: If a duplicate key is encountered, an exception will be thrown.
114+
115+
.. code-block:: java
116+
117+
@MultiInsert(duplicateKeyType = DuplicateKeyType.UPDATE)
118+
int insert(List<Employee> employees);
119+
120+
duplicateKeys
121+
----------------
122+
123+
This property represents the keys that should be used to determine if a duplicate key exists. If the duplicate key exists, the operation will use the ``duplicateKeyType`` strategy to handle the duplicate key.
124+
125+
.. code-block:: java
126+
127+
@MultiInsert(duplicateKeyType = DuplicateKeyType.UPDATE, duplicateKeys = {"employeeNo"})
128+
int insert(List<Employee> employees);
129+
130+
.. note::
131+
132+
This property is only utilized when the ``duplicateKeyType`` strategy is either ``DuplicateKeyType.UPDATE`` or ``DuplicateKeyType.IGNORE``.
133+
134+
.. note::
135+
136+
The MySQL dialect does not utilize this property.
137+
103138
Unique constraint violation
104139
============================
105140

0 commit comments

Comments
 (0)