Add documentation for user-defined operators

Author: nakamura-to

docs/locale/ja/LC_MESSAGES/query-dsl.po

@@ -2,7 +2,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: doma-docs\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2025-05-05 10:22+0900\n"
+"POT-Creation-Date: 2025-06-06 20:58+0900\n"
 "Last-Translator: \n"
 "Language-Team: Japanese\n"
 "MIME-Version: 1.0\n"
@@ -1213,42 +1213,58 @@ msgid "This feature is useful for working with two tables that share the same st
 msgstr "この機能は、同じ構造を共有する2つのテーブルを扱う場合に便利です。"
 
 #: ../../query-dsl.rst:1983
+msgid "User-Defined Operators"
+msgstr "ユーザー定義演算子"
+
+#: ../../query-dsl.rst:1985
+msgid "User-defined operators can be implemented as methods in a class that accepts a ``UserDefinedCriteriaContext`` instance via its constructor."
+msgstr "ユーザー定義の演算子は、 ``UserDefinedCriteriaContext`` インスタンスをコンストラクタを介して受け入れるクラスのメソッドとして実装することができます。"
+
+#: ../../query-dsl.rst:2000
+msgid "The class above can be used in the WHERE, JOIN, or HAVING clause of a query as follows:"
+msgstr "上記のクラスは、クエリの WHERE、JOIN、または HAVING 句で次のように使用できます。"
+
+#: ../../query-dsl.rst:2014
+msgid "The query above is translated into the following SQL:"
+msgstr "上記のクエリは次の SQL に変換されます。"
+
+#: ../../query-dsl.rst:2023
 msgid "Debugging"
 msgstr "デバッグ"
 
-#: ../../query-dsl.rst:1985
+#: ../../query-dsl.rst:2025
 msgid "To inspect the SQL statement generated by DSLs, use the ``asSql`` method:"
 msgstr "DSL によって生成される SQL ステートメントを調べるには、``asSql`` メソッドを使用します。"
 
-#: ../../query-dsl.rst:1997
+#: ../../query-dsl.rst:2037
 msgid "The code above outputs the following:"
 msgstr "上記のコードは以下を出力します。"
 
-#: ../../query-dsl.rst:2004
+#: ../../query-dsl.rst:2044
 msgid "The ``asSql`` method does not execute the SQL statement against the database; instead, it only constructs the SQL statement and returns it as an ``Sql`` object."
 msgstr "``asSql`` メソッドはSQLステートメントをデータベースに対して実行しません。代わりに、SQLステートメントを構築し、``Sql`` オブジェクトとして返します。"
 
-#: ../../query-dsl.rst:2006
+#: ../../query-dsl.rst:2046
 msgid "You can also obtain the ``Sql`` object by using the ``peek`` method:"
 msgstr "``peek`` メソッドを使用して ``Sql`` オブジェクトを取得することもできます。"
 
-#: ../../query-dsl.rst:2021
+#: ../../query-dsl.rst:2061
 msgid "The code above outputs SQL statements at various stages of the query:"
 msgstr "上記のコードは、クエリの様々な段階で SQL ステートメントを出力します。"
 
-#: ../../query-dsl.rst:2031
+#: ../../query-dsl.rst:2071
 msgid "Sample Projects"
 msgstr "サンプルプロジェクト"
 
-#: ../../query-dsl.rst:2033
+#: ../../query-dsl.rst:2073
 msgid "You can refer to the following sample projects for additional guidance:"
 msgstr "追加のガイダンスについては、以下のサンプルプロジェクトを参照してください。"
 
-#: ../../query-dsl.rst:2035
+#: ../../query-dsl.rst:2075
 msgid "`simple-examples <https://github.com/domaframework/simple-examples>`_"
 msgstr ""
 
-#: ../../query-dsl.rst:2036
+#: ../../query-dsl.rst:2076
 msgid "`kotlin-sample <https://github.com/domaframework/kotlin-sample>`_"
 msgstr ""
 

docs/query-dsl.rst

@@ -1979,6 +1979,46 @@ This generates:
     LOCATION, VERSION) select t0_.DEPARTMENT_ID, t0_.DEPARTMENT_NO, t0_.DEPARTMENT_NAME,
     t0_.LOCATION, t0_.VERSION from DEPARTMENT t0_
 
+User-Defined Operators
+----------------------
+
+User-defined operators can be implemented as methods in a class that accepts a ``UserDefinedCriteriaContext`` instance via its constructor.
+
+.. code-block:: java
+
+    record MyExtension(UserDefinedCriteriaContext context) {
+      public void regexp(PropertyMetamodel<String> propertyMetamodel, String regexp) {
+        context.add(
+            (b) -> {
+              b.appendExpression(propertyMetamodel);
+              b.appendSql(" ~ ");
+              b.appendParameter(propertyMetamodel, regexp);
+            });
+      }
+    }
+
+The class above can be used in the WHERE, JOIN, or HAVING clause of a query as follows:
+
+.. code-block:: java
+
+    var d = new Department_();
+    var list =
+        queryDsl.from(d)
+            .where(c -> c.extension(MyExtension::new, (ext) -> {
+                ext.regexp(d.departmentName, "A");
+            }))
+            .orderBy(c -> c.asc(d.departmentId))
+            .select()
+            .fetch();
+
+The query above is translated into the following SQL:
+
+.. code-block:: sql
+
+    select t0_.DEPARTMENT_ID, t0_.DEPARTMENT_NO, t0_.DEPARTMENT_NAME, t0_.LOCATION, t0_.VERSION from DEPARTMENT t0_
+    where t0_.DEPARTMENT_NAME ~ ?
+    order by t0_.DEPARTMENT_ID asc
+
 Debugging
 =========