Jimmer

https://jimmer.deno.dev/zh/docs
Admin
Jimmer is a modern object-relational mapping (ORM) framework that provides transparent caching,...
Tokens:384,008
Snippets:3,646
Trust Score:5.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Run MySQL Docker Container and Initialize Database

Source: https://jimmer.deno.dev/zh/docs/quick-view/get-started/create-database

Execute these shell commands to start a MySQL Docker container, copy the SQL schema file into it, and then run the SQL script to create the database structure. Ensure Docker is installed and the SQL file is in the current directory.

```shell
docker run \
	--restart=always \
	-d \
	--name jimmer-demo-mysql \
	--network jimmer-demo-network \
	--network-alias jimmer-demo-mysql \
	-p 3306:3306 \
	-e MYSQL_ROOT_PASSWORD=123456 \
	mysql \
	--lower_case_table_names=1
docker cp jimmer-demo.sql jimmer-demo-mysql:/var/jimmer-demo.sql
docker exec jimmer-demo-mysql /bin/sh -c \
        'mysql -uroot -p123456 </var/jimmer-demo.sql'
```

--------------------------------

### Any Equality Optimization Example (Java)

Source: https://jimmer.deno.dev/zh/docs/query/expression

This Java example shows a single-column 'in' list. With the optimization enabled and database support, it translates to `= any(?)`.

```java
where(
    book.name().in(
        Arrays.asList(
            "SQL in Action",
            "Java in Action"
        )
    )
);

```

--------------------------------

### Complete Java Dynamic Query Example

Source: https://jimmer.deno.dev/zh/docs/query/dynamic-where

A comprehensive Java example demonstrating multiple dynamic WHERE clauses for name, minimum price, and maximum price.

```java
public List<Book> findBooks(
    @Nullable String name,
    @Nullable BigDecimal minPrice,
    @Nullable BigDecimal maxPrice
) {
  
    BookTable table = Tables.BOOK_TABLE;
  
    return sqlClient
        .createQuery(table)
        .whereIf(
            name != null && !name.isEmpty(),
            table.name().eq(name)
        )
        .whereIf(
            minPrice != null,
            () -> table.price().ge(minPrice)
        )
        .whereIf(
            maxPrice != null,
            () -> table.price().le(maxPrice)
        )
        .orderBy(table.name().asc(), table.edition().desc())
        .select(table)
        .execute();
}

```

--------------------------------

### REST Controller Setup for Fetching Entities with Associated IDs

Source: https://jimmer.deno.dev/zh/docs/quick-view/fetch/export/entity

Provides examples of how to set up REST controllers in Java and Kotlin to fetch entities using associated IDs, leveraging the configured @IdView properties.

```APIDOC
## REST Controller Setup

Now, you can write your REST Controller like this:

### Java
```java
@RestController
public class BookController implements Fetchers {

    private final BookRepository bookRepository;

    public BookController(BookRepository bookRepository) {
        this.bookRepository = bookRepository;
    }

    @Nullable
    @GetMapping("/book")
    public @FetchBy("SHALLOW_BOOK") Book findBookById(
        @PathVariable("id") long id
    ) {
        return bookRepository.findBookById(id, SHALLOW_BOOK);
    }

    /**
     * Shallow Book DTO which can access
     * 1. All scalar properties of `Book` itself
     * 2. All associated ids, not associated objects.
     */
    private static final Fetcher<Book> SIMPLE_BOOK = 
            SHALLOW_BOOK
                    .allScalarFields()
                    .storeId()
                    .authorIds();

    ...省略其他成员...
}
```

### Kotlin
```kotlin
@RestController
class BookController(
    private val bookRepository: BookRepository
) {
    @GetMapping("/book/{id}")
    fun findBookById(
        @PathVariable id: Long
    ): @FetchBy("SHALLOW_BOOK") Book = 
        bookRepository.findBookById(id, SHALLOW_BOOK)

    ...省略其他成员...

    companion object {

        /**
         * Shallow Book DTO which can access
         * 1. All scalar properties of `Book` itself
         * 2. All associated ids, not associated objects.
         */
        val SHALLOW_BOOK = 
            newFetcher(Book::class).by {
                allScalarFields()
                storeId()
                authorIds()
            }

        ...省略其他形状定义...
    }
}
```
```

--------------------------------

### Complete Kotlin Dynamic Query Example

Source: https://jimmer.deno.dev/zh/docs/query/dynamic-where

A complete Kotlin example showing how to apply dynamic filters for name, minimum price, and maximum price using its lambda DSL.

```kotlin
fun findBooks(
    name: String? = null,
    minPrice: BigDecimal? = null,
    maxPrice: BigDecimal? = null
): List<Book> = 
    sqlClient
        .createQuery(Book::class) {
            name?.takeIf { it.isNotEmpty() }?.let {
                where(table.name eq it)
            }
            minPrice?.let {
                where(table.price ge it)
            }
            maxPrice?.let {
                where(table.price le it)
            }
            orderBy(table.name.asc(), table.edition.desc())
            select(table)
        }
        .execute()

```

--------------------------------

### Kotlin Query Example with Post-Select Syntax

Source: https://jimmer.deno.dev/zh/docs/query/usage

Illustrates the Kotlin syntax for query construction, mirroring the Java example with 'select' placed after other clauses. This highlights Jimmer's consistent DSL across languages.

```kotlin
val books = sqlClient  
    .createQuery(Book::class) { ❶  
        where(table.name eq "SQL in Action")  
        orderBy(table.name.asc(), table.edition.desc())  
        select(table) ❷  
    }  
    .limit(10, 100)  
    .execute() ❸  
```

--------------------------------

### Padding Optimization Example (Java)

Source: https://jimmer.deno.dev/zh/docs/query/expression

This Java example demonstrates a list with 3 elements. Padding optimization will expand this to the nearest power of two (4) by repeating the last element.

```java
where(
    Expression.tuple(
        book.name(),
        book.edition()
    ).in(
        Arrays.asList(
            new Tuple2<>("SQL in Action", 1),
            new Tuple2<>("SQL in Action", 2),
            new Tuple2<>("Java in Action", 1)
        )
    )
);

```

--------------------------------

### Install External Environment for Caching (Bash)

Source: https://jimmer.deno.dev/zh/docs/quick-view/standard-demo

Execute this bash script to install the necessary external environment for demonstrating Jimmer's caching consistency features using Maxwell + MySQL. Ensure Docker is installed and running.

```bash
./install.sh
```

--------------------------------

### SQL Data Insertion Example

Source: https://jimmer.deno.dev/zh/docs/quick-view/get-started/create-database

This SQL snippet demonstrates inserting data into tables, showcasing tuples with IDs and associated values. It's a basic example that will be expanded upon in later tutorials.

```sql
(
                    17, 'Shirt', 15),
            (18, 'Man', 9),
                (19, 'Casual wear', 18),
                    (20, 'Jacket', 19),
                    (21, 'Jeans', 19),
                (22, 'Formal wear', 18),
                    (23, 'Suit', 22),
                    (24, 'Shirt', 22)
;
```

--------------------------------

### JSON Output Example

Source: https://jimmer.deno.dev/zh/docs/quick-view/fetch/feature

Example of the JSON output when fetching books with their associated store and author information.

```json
[
    {
        "id": 1,
        "name": "Learning GraphQL",
        "edition": 1,
        "price": 50,
        "store": {
            "id": 1,
            "name": "O'REILLY",
            "website": null
        },
        "authors": [
            {
                "id": 2,
                "firstName": "Alex",
                "lastName": "Banks",
                "gender": "MALE"
            },
            {
                "id": 1,
                "firstName": "Eve",
                "lastName": "Procello",
                "gender": "FEMALE"
            }
        ]
    },
    {
        "id": 2,
        "name": "Learning GraphQL",
        "edition": 2,
        "price": 55,
        "store": {
            "id": 1,
            "name": "O'REILLY",
            "website": null
        },
        "authors": [
            {
                "id": 2,
                "firstName": "Alex",
                "lastName": "Banks",
                "gender": "MALE"
            },
            {
                "id": 1,
                "firstName": "Eve",
                "lastName": "Procello",
                "gender": "FEMALE"
            }
        ]
    },
    {
        "id": 3,
        "name": "Learning GraphQL",
        "edition": 3,
        "price": 51,
        "store": {
            "id": 1,
            "name": "O'REILLY",
            "website": null
        },
        "authors": [
            {
                "id": 2,
                "firstName": "Alex",
                "lastName": "Banks",
                "gender": "MALE"
            },
            {
                "id": 1,
                "firstName": "Eve",
                "lastName": "Procello",
                "gender": "FEMALE"
            }
        ]
    }
]

```

--------------------------------

### SQL Query Example

Source: https://jimmer.deno.dev/zh/docs/query/object-fetcher/usage

This SQL query demonstrates selecting specific columns from the 'book' table.

```sql
select 
    b.id, 
    b.name, 
    b.edition 
    /* 不需要`b.price`和`b.store_id` */ 
from book b 
where b.edition = 3;  


```

--------------------------------

### Any Equality Optimization Example (Kotlin)

Source: https://jimmer.deno.dev/zh/docs/query/expression

This Kotlin example demonstrates a single-column 'in' list. When the 'any equality' optimization is active, it's converted to `= any(?)` for the database.

```kotlin
where(
    table.name valueIn listOf(
        "SQL in Action",
        "Java in Action"
    )
)

```

--------------------------------

### Install Maxwell Environment

Source: https://jimmer.deno.dev/zh/docs/mutation/trigger

Execute this script to set up the Maxwell environment. Ensure you are in the correct local directory after cloning the jimmer-examples repository.

```bash
bash ./install.sh  
```

--------------------------------

### BookController.kt

Source: https://jimmer.deno.dev/zh/docs/quick-view/fetch/export/entity

Example implementation of a BookController in Kotlin, demonstrating how to use Fetchers and @FetchBy for defining entity shapes.

```APIDOC
## GET /book/{id}

### Description
Retrieves a single book by its ID with a complex fetch configuration.

### Method
GET

### Endpoint
/book/{id}

### Parameters
#### Path Parameters
- **id** (Long) - Required - The ID of the book to retrieve.

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **Book** (Book) - The book object with complex details.

#### Response Example
```json
{
  "id": 1,
  "name": "The Lord of the Rings",
  "store": {
    "name": "Awesome Books"
  },
  "authors": [
    {
      "firstName": "J.R.R.",
      "lastName": "Tolkien"
    }
  ]
}
```

## GET /books

### Description
Retrieves a list of books, optionally filtered by name, with a simple fetch configuration for each book.

### Method
GET

### Endpoint
/books

### Parameters
#### Path Parameters
None

#### Query Parameters
- **name** (String) - Optional - The name of the book to filter by.

### Request Example
None

### Response
#### Success Response (200)
- **List<Book>** - A list of book objects, each with simple details.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "The Lord of the Rings"
  },
  {
    "id": 2,
    "name": "The Hobbit"
  }
]
```
```

--------------------------------

### DTO Flat Function Example

Source: https://jimmer.deno.dev/zh/docs/object/view/dto-language

Demonstrates the basic usage of the `flat` function to promote associated DTO properties. Note that this initial example can lead to naming conflicts if not used carefully.

```dto
FlatTreeNodeView {
  
    #allScalars(TreeNode)
  
    flat(parent) {
        #allScalars(TreeNode)
    }
}
```

--------------------------------

### BookController.java

Source: https://jimmer.deno.dev/zh/docs/quick-view/fetch/export/entity

Example implementation of a BookController in Java, demonstrating how to use Fetchers and @FetchBy for defining entity shapes.

```APIDOC
## GET /book/{id}

### Description
Retrieves a single book by its ID with a complex fetch configuration.

### Method
GET

### Endpoint
/book/{id}

### Parameters
#### Path Parameters
- **id** (long) - Required - The ID of the book to retrieve.

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **Book** (Book) - The book object with complex details.

#### Response Example
```json
{
  "id": 1,
  "name": "The Lord of the Rings",
  "store": {
    "name": "Awesome Books"
  },
  "authors": [
    {
      "firstName": "J.R.R.",
      "lastName": "Tolkien"
    }
  ]
}
```

## GET /books

### Description
Retrieves a list of books, optionally filtered by name, with a simple fetch configuration for each book.

### Method
GET

### Endpoint
/books

### Parameters
#### Path Parameters
None

#### Query Parameters
- **name** (String) - Optional - The name of the book to filter by.

### Request Example
None

### Response
#### Success Response (200)
- **List<Book>** - A list of book objects, each with simple details.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "The Lord of the Rings"
  },
  {
    "id": 2,
    "name": "The Hobbit"
  }
]
```
```

--------------------------------

### Padding Optimization Example (Kotlin)

Source: https://jimmer.deno.dev/zh/docs/query/expression

This Kotlin example shows a list of 3 elements. Padding optimization ensures the list length becomes a power of two (4) by duplicating the last item.

```kotlin
where(
    tuple(
        table.name,
        table.edition
    ) valueIn listOf(
        Tuple2("SQL in Action", 1),
        Tuple2("SQL in Action", 2),
        Tuple2("Java in Action", 1)
    )
)

```

--------------------------------

### Book Entity Interface (Kotlin)

Source: https://jimmer.deno.dev/zh/docs/cache/multiview-cache/user-filter

Example of a `Book` entity interface in Kotlin that extends `TenantAware`.

```kotlin
@Entity
interface Book : TenantAware {
      
    ...省略代码...
}

```

--------------------------------

### Query Execution with Specified Connection (Java)

Source: https://jimmer.deno.dev/zh/docs/configuration/connection-manager

Example of executing a query using a user-provided `Connection` object in Java.

```java
BookTable book = Tables.BOOK_TABLE;

List<Book> books = sqlClient
    .createQuery(book)
    .select(book)
    .execute(con);
```

--------------------------------

### Query with JOIN (Java)

Source: https://jimmer.deno.dev/zh/docs/spring/repository/abstract

Example of calling the repository method with only the 'storeName' parameter specified. This will generate an INNER JOIN to the BookStore table.

```java
List<Book> books = bookRepository
    .findByNameStartsWithAndStoreName(null, "MANNING");
```

--------------------------------

### Comprehensive Query Result Example

Source: https://jimmer.deno.dev/zh/docs/showcase/comprehensive-query

Example of the JSON output from a comprehensive book query, showing paginated results with nested store and author information. Illustrates the structure of returned data.

```json
Page{
    rows=[
        {
            "id":1,
            "name":"Learning GraphQL",
            "edition":1,
            "price":50.00,
            "store":{"id":1,"name":"O'REILLY"},
            "authors":[
                {"id":2,"firstName":"Alex","lastName":"Banks"},
                {"id":1,"firstName":"Eve","lastName":"Procello"}
            ]
        }
    ],
    totalRowCount=3,
    totalPageCount=2
}
```

--------------------------------

### Book Entity Interface (Java)

Source: https://jimmer.deno.dev/zh/docs/cache/multiview-cache/user-filter

Example of a `Book` entity interface in Java that extends `TenantAware`.

```java
@Entity
public interface Book extends TenantAware {

    ...省略代码...
}

```

--------------------------------

### Query Execution with Specified Connection (Kotlin)

Source: https://jimmer.deno.dev/zh/docs/configuration/connection-manager

Example of executing a query using a user-provided `Connection` object in Kotlin.

```kotlin
val books = sqlClient
    .createQuery(Book::class) {
        select(table)
    }
    .execute(con)
```

--------------------------------

### Formatted JSON output for fetching ID and Name

Source: https://jimmer.deno.dev/zh/docs/query/object-fetcher/props

Example JSON output showing the 'id' and 'name' fields for a book.

```json
[
    {
        "id":3,
        "name":"Learning GraphQL"
    },
    ...省略其他对象...
]

```

--------------------------------

### Delete Command Example (Java)

Source: https://jimmer.deno.dev/zh/docs/mutation/delete-command

Demonstrates how to create a delete command, configure it with actions like setting a foreign key to null, and then execute it.

```APIDOC
## Delete Command Example (Java)

### Description
This example shows how to use the `deleteCommand` API to create a delete instruction, configure dissociation actions, and then execute the command.

### Method
`deleteCommand` followed by `execute`

### Endpoint
N/A (This is an SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
DeleteResult result = sqlClient
    .getEntities()
    .deleteCommand(BookStore.class, 1L) 
    .setDissociateAction(BookProps.STORE, DissociateAction.SET_NULL) 
    .execute(); 
```

### Response
#### Success Response (200)
- **result** (DeleteResult) - Contains information about the execution of the delete command.

#### Response Example
```json
{
  "example": "DeleteResult object"
}
```
```

--------------------------------

### Query with JOIN (Kotlin)

Source: https://jimmer.deno.dev/zh/docs/spring/repository/abstract

Example of calling the repository method with only the 'storeName' parameter specified. This will generate an INNER JOIN to the BookStore table.

```kotlin
val books = bookRepository
    .findByNameStartsWithAndStoreName(null, "MANNING")
```

--------------------------------

### Multi-column Sorting with makeOrders in Java

Source: https://jimmer.deno.dev/zh/docs/query/dynamic-order

Example of using Order.makeOrders with multiple string arguments to specify multi-column sorting in Java.

```java
Order.makeOrders(table, "name", "edition desc")  

```

--------------------------------

### Physical Deletion Example (Java)

Source: https://jimmer.deno.dev/zh/docs/mutation/delete-command

Illustrates how to perform a physical delete operation, which permanently removes data from the database.

```APIDOC
## Physical Deletion Example (Java)

### Description
This example demonstrates how to execute a physical delete operation, which permanently removes data. It shows the usage of `deleteAll` with a list of IDs and how to retrieve affected row counts.

### Method
`deleteAll`

### Endpoint
N/A (This is an SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
DeleteResult result = sqlClient
    .getEntities()
    .deleteAll(Book.class, Arrays.asList(1L, 2L, 3L, 4L));

System.out.println(
    "Affected row count: " +
    result.getTotalAffectedRowCount() +
    "\nAffected row count of table 'BOOK': " +
    result.getAffectedRowCount(AffectedTable.of(Book.class)) +
    "\nAffected row count of middle table 'BOOK_AUTHOR_MAPPING': " +
    result.getAffectedRowCount(AffectedTable.of(BookProps.AUTHORS))
);
```

### Response
#### Success Response (200)
- **result** (DeleteResult) - Contains the total number of affected rows and counts per table.

#### Response Example
```json
{
  "example": "DeleteResult object with affected row counts"
}
```
```

--------------------------------

### Install adm-zip Dependency

Source: https://jimmer.deno.dev/zh/docs/client/api

Install the 'adm-zip' package as a development dependency using yarn.

```bash
yarn add adm-zip --dev  
```

--------------------------------

### Flat DTO Output Example

Source: https://jimmer.deno.dev/zh/docs/object/view/dto-language

Shows the expected output of a flattened DTO object after transformation, illustrating the promoted properties.

```text
com.yourcompany.yourproject.FlatTreeNodeView(
    id = 4,
    name = Coco cola,
    parentId = 3,
    parentName = Drinks,
    grandParentId = 2,
    grandParentName = "Food"
)
```

--------------------------------

### Java Example: Querying with Fetcher

Source: https://jimmer.deno.dev/zh/docs/spring/repository/default

Demonstrates how to call the custom find method with specific pagination and sorting, and crucially, with a configured Fetcher to retrieve nested data like the store's name and author details.

```java
Page<Book> page = bookRepository
    .find(
        null,
        null,
        null,
        PageRequest.of(
            1, // 从0开始，1表示第二页,
            5,
            SortUtils.toSort("name, edition desc")
        ),
        Fetchers.BOOK_FETCHER
            .allScalarFields()
            .store(
                Fetchers.BOOK_FETCHER
                    .name() // 关联对象仅查询id(隐含+强制)和name
            )
            .authors(
                Fetchers.AUTHOR_FETCHER
```

--------------------------------

### SQL Derived Table Example

Source: https://jimmer.deno.dev/zh/docs/query/base-query

Illustrates a standard SQL query using a derived table as a base for further querying.

```sql
select a, b, c   
from (  
    select a, b, c, d from t where ....
) derived_table  
where d between 1 and 10  


```

--------------------------------

### Modifying Child Nodes with TreeNode Draft

Source: https://jimmer.deno.dev/zh/docs/object/draft

Examples demonstrating how to modify child nodes using the `childNodes` getter. The Java example uses `childNodes(false)` and accesses elements by index, while the Kotlin example uses the `childNodes()` function for a more concise syntax.

```Java
TreeNode newTreeNode = Immutables.createTreeNode(treeNode, draft -> {
        draft  
            .childNodes(false)  
            .get(0)  
            .setName("Son");  
        draft  
            .childNodes(false)  
            .get(0)  
            .childNodes(false)  
            .get(0)  
            .setName("Grandson");  
    });
```

```Kotlin
val newTreeNode = TreeNode(treeNode) {
    childNodes()[0].name = "Son"
    childNodes()[0].childNodes()[0].name = "Grandson"
}
```

--------------------------------

### Kotlin DTO Output Example

Source: https://jimmer.deno.dev/zh/docs/quick-view/fetch/feature

Example of the Kotlin DTO output when fetching books with their associated store and author information.

```kotlin
[
    BookView(
        id=1, 
        name=Learning GraphQL, 
        edition=1, 
        price=50.00,
        store=BookView.TargetOf_store(
            id=1, 
            name=O'REILLY, 
            website=null
        ),
        authors=[
            BookView.TargetOf_authors(
                id=2, 
                firstName=Alex, 
                lastName=Banks, 
                gender=MALE
            ),
            BookView.TargetOf_authors(
                id=1, 
                firstName=Eve, 
                lastName=Procello, 
                gender=FEMALE
            )
        ]
    ),
    BookView(
        id=2, 
        name=Learning GraphQL, 
        edition=2, 
        price=55.00,
        store=BookView.TargetOf_store(
            id=1, 
            name=O'REILLY, 
            website=null
        ),
        authors=[
            BookView.TargetOf_authors(
                id=2, 
                firstName=Alex, 
                lastName=Banks, 
                gender=MALE
            ),
            BookView.TargetOf_authors(
                id=1, 
                firstName=Eve, 
                lastName=Procello, 
                gender=FEMALE
            )
        ]
    ),
    BookView(
        id=3, 
        name=Learning GraphQL, 
        edition=3, 
        price=51.00,
        store=BookView.TargetOf_store(
            id=1, 
            name=O'REILLY, 
            website=null
        ),
        authors=[
            BookView.TargetOf_authors(
                id=2, 
                firstName=Alex, 
                lastName=Banks, 
                gender=MALE
            ),
            BookView.TargetOf_authors(
                id=1, 
                firstName=Eve, 
                lastName=Procello, 
                gender=FEMALE
            )
        ]
    )
]

```

--------------------------------

### Foreign Key Constraint Example

Source: https://jimmer.deno.dev/zh/docs/mapping/base/association/many-to-one

Example of a foreign key constraint in SQL for a many-to-one relationship where the foreign key is real.

```sql
// 如果指向关联对象的外键是真的，建立外键约束  
alter table BOOK  
    add constraint FK_BOOK__BOOK_STORE  
        foreign key(STORE_ID)  
            references BOOK_STORE(ID);
```

--------------------------------

### Java: Calling findBooks with all parameters

Source: https://jimmer.deno.dev/zh/docs/quick-view/dsl/feature

Example of calling the `findBooks` method in Java with non-null values for name, minPrice, and maxPrice, triggering all WHERE conditions.

```Java
List<Book> books = bookRepository.findBooks(
    "GraphQL", // name
    new BigDecimal(20), // minPrice
    new BigDecimal(50), // maxPrice
    null
);

```

--------------------------------

### Example Result for INSERT_IF_ABSENT

Source: https://jimmer.deno.dev/zh/docs/mutation/save-command/save-mode

This example shows the expected output when inserting one data record and ignoring another using `INSERT_IF_ABSENT`.

```text
1

```

--------------------------------

### Example JSON Output of Recursive Fetch

Source: https://jimmer.deno.dev/zh/docs/query/object-fetcher/recursive

This is an example of the JSON output when fetching objects recursively. It shows a nested structure with 'childNodes' arrays.

```json
{
    "id": 1,
    "name": "Home",
    "childNodes": [
        {
            "id": 9,
            "name": "Clothing",
            "childNodes": [
                {
                    "id": 18,
                    "name": "Man",
                    "childNodes": [
                        {
                            "id": 19,
                            "name": "Casual wear",
                            "childNodes": [
                                {
                                    "id": 20,
                                    "name": "Jacket",
                                    "childNodes": []
                                },
                                {
                                    "id": 21,
                                    "name": "Jeans",
                                    "childNodes": []
                                }
                            ]
                        },
                        {
                            "id": 22,
                            "name": "Formal wear",
                            "childNodes": [
                                {
                                    "id": 24,
                                    "name": "Shirt",
                                    "childNodes": []
                                },
                                {
                                    "id": 23,
                                    "name": "Suit",
                                    "childNodes": []
                                }
                            ]
                        }
                    ]
                },
                {
                    "id": 10,
                    "name": "Woman",
                    "childNodes": [
                        {
                            "id": 11,
                            "name": "Casual wear",
                            "childNodes": [
                                {
                                    "id": 12,
                                    "name": "Dress",
                                    "childNodes": []
                                },
                                {
                                    "id": 14,
                                    "name": "Jeans",
                                    "childNodes": []
                                },
                                {
                                    "id": 13,
                                    "name": "Miniskirt",
                                    "childNodes": []
                                }
                            ]
                        },
                        {
                            "id": 15,
                            "name": "Formal wear",
                            "childNodes": [
                                {
                                    "id": 17,
                                    "name": "Shirt",
                                    "childNodes": []
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

```

--------------------------------

### SaveException IllegalTargetId Example

Source: https://jimmer.deno.dev/zh/docs/mutation/save-command/investigation

Example of a SaveException indicating an invalid associated ID, specifying the entity path and the problematic reference property and ID.

```java
org.babyfish.jimmer.sql.exception.SaveException$IllegalTargetId: 
    Save error caused by the path: "<root>.store": 
    Cannot save the entity, the associated id of the reference 
    property "com.yourcompany.yourproject.Book.store" is 
    "999" but there is no corresponding associated object in the database
```

--------------------------------

### SaveException NotUnique Example

Source: https://jimmer.deno.dev/zh/docs/mutation/save-command/investigation

Example of a SaveException indicating a unique constraint violation, specifying the entity path and the conflicting key property values.

```java
#lighlight-next-line
org.babyfish.jimmer.sql.exception.SaveException$NotUnique: 
    Save error caused by the path: "<root>": 
    Cannot save the entity, the value of the key properties "[
        com.yourcompany.yourproject.model.Book.name, 
        com.yourcompany.yourproject.Book.edition
    ]" are "Tuple2(
        _1=GraphQL in Action,
        _2=1
    )" which already exists
```

--------------------------------

### Multi-column IN expression example

Source: https://jimmer.deno.dev/zh/docs/configuration/dialect

Example of a multi-column IN expression, which is a feature highly dependent on Jimmer. Microsoft SQL Server currently does not support this feature.

```sql
where (a, b) in ((3, 4), (8, 13))
```

```sql
where (a, b) in (select x, y from ...)
```

--------------------------------

### Kotlin KSqlClient Configuration for Microservices

Source: https://jimmer.deno.dev/zh/docs/spring/spring-cloud

Demonstrates configuring KSqlClient directly with a microservice name when not using Spring Boot Starters.

```kotlin
val sqlClient = newKSqlClient {
    setMicroServiceName("...")
    ...省略其他配置...
}


```

--------------------------------

### Fetch Book Name and Price using Object Fetcher (Java)

Source: https://jimmer.deno.dev/zh/docs/query/object-fetcher/usage

Demonstrates fetching book name and price by modifying the Object Fetcher. This example shows how to select different properties than the default.

```java
BookTable table = Tables.BOOK_TABLE;
List<Book> books = sqlClient.createQuery(table) 
        .where(table.edition().eq(3))
        .select(
            table.fetch(
                Fetchers.BOOK_FETCHER 
                    .name()
                    .price()
            )
        )
        .execute();
System.out.println(books);

```

--------------------------------

### Fetch Book Name and Price using Object Fetcher (Kotlin)

Source: https://jimmer.deno.dev/zh/docs/query/object-fetcher/usage

Demonstrates fetching book name and price by modifying the Object Fetcher in Kotlin. This example shows how to select different properties than the default.

```kotlin
val books = sqlClient
    .createQuery(Book::class) {
        where(table.edition.eq(3))
        select(
            table.fetchBy {
                name
                price
            }
        )
    }
    .execute()
println(books)

```

--------------------------------

### Java Base Query with Object Fetcher

Source: https://jimmer.deno.dev/zh/docs/query/base-query

Java example demonstrating how to create a base query using an object fetcher. It dynamically selects columns based on the fetcher's requirements, simplifying the query definition.

```java
private List<Book> findBooks(  
    Fetcher<Book> fetcher  
) {  
    BookTable table = BookTable.$;  
    AuthorTableEx author = AuthorTableEx.$;  
    BaseTable2<BookTable, NumericExpression<Integer>> baseTable =  
        sqlClient  
            .createBaseQuery(table)  
            .addSelect(table)  
            .addSelect(  
                Expression.numeric().sql(  
                    Integer.class,  
                    "dense_rank() over(" +  
                        "order by %e desc" +  
                        ")",  
                    sqlClient.createSubQuery(author)  
                        .where(author.books().id().eq(table.id()))  
                        .selectCount()  
                )  
            )  
            .asBaseTable();  
    return sqlClient  
        .createQuery(baseTable)  
        .where(baseTable.get_2().eq(1))  
        .select(  
            baseTable.get_1().fetch(  
                fetcher  
            )  
        )  
        .execute();  
}  

```

--------------------------------

### GraphQL Query Result Example

Source: https://jimmer.deno.dev/zh/docs/graphql/query

This is an example of the JSON response you can expect after executing the GraphQL query. It shows nested data for bookstores, their books, and authors.

```json
{
    "data":{
        "bookStores":[
            {
                "id":2,
                "name":"MANNING",
                "avgPrice":80.333333,
                "books":[
                    {
                        "id":10,
                        "name":"GraphQL in Action",
                        "edition":1,
                        "price":80,
                        "authors":[
                            {
                                "id":5,
                                "firstName":"Samer",
                                "fullName":"Samer Buna",
                                "gender":"MALE"
                            }
                        ]
                    },
                    {
                        "id":11,
                        "...略..."
                    },
                    {
                        "id":12,
                        "...略..."
                    }
                ]
            },
            {
                "id":1,
                "name":"O'REILLY",
                "avgPrice":58.5,
                "books":[
                    {
                        "id":4,
                        "name":"Effective TypeScript",
                        "edition":1,
                        "price":73,
                        "authors":[
                            {
                                "id":3,
                                "firstName":"Dan",
                                "fullName":"Dan Vanderkam",
                                "gender":"MALE"
                            }
                        ]
                    },
                    {
                        "id":5,
                        "...略..."
                    },
                    {
                        "id":6,
                        "...略..."
                    },
                    {
                        "id":1,
                        "name":"Learning GraphQL",
                        "edition":1,
                        "price":50,
                        "authors":[
                            {
                                "id":2,
                                "firstName":"Alex",
                                "fullName":"Alex Banks",
                                "gender":"MALE"
                            },
                            {
                                "id":1,
                                "firstName":"Eve",
                                "fullName":"Eve Procello",
                                "gender":"FEMALE"
                            }
                        ]
                    },
                    {
                        "id":2,
                        "name":"Learning GraphQL",
                        "edition":2,
                        "price":55,
                        "authors":[
                            {
                                "id":2,
                                "firstName":"Alex",
                                "fullName":"Alex Banks",
                                "gender":"MALE"
                            },
                            {
                                "id":1,
                                "firstName":"Eve",
                                "fullName":"Eve Procello",
                                "gender":"FEMALE"
                            }
                        ]
                    },
                    {
                        "id":3,
                        "name":"Learning GraphQL",
                        "edition":3,
                        "price":51,
                        "authors":[
                            {
                                "id":2,
                                "firstName":"Alex",
                                "fullName":"Alex Banks",
                                "gender":"MALE"
                            },
                            {
                                "id":1,
                                "firstName":"Eve",
                                "fullName":"Eve Procello",
                                "gender":"FEMALE"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

```

--------------------------------

### Kotlin Example for INSERT_IF_ABSENT

Source: https://jimmer.deno.dev/zh/docs/mutation/save-command/save-mode

This Kotlin example demonstrates the use of INSERT_IF_ABSENT for conditional inserts, similar to the Java version. It retrieves the IDs of entities after the save operation.

```kotlin
val books = listOf(
    Book {
        name = "SQL in Action"
        edition = 3
        price = BigDecimal("49.9")
        storeId = 2L
    },
    Book {
        name = "SQL in Action"
        edition = 2
        price = BigDecimal("39.9")
        storeId = 2L
    }
)
val ids = sqlClient
    .saveEntities(
        books,
        SaveMode.INSERT_IF_ABSENT
    )
    .items
    .map {
        if (isLoaded(it, Book::id)) {
            it.originalEntity.id
        } else {
            null
        }
     }
println(ids)
```

--------------------------------

### Create and Update Product API (Kotlin)

Source: https://jimmer.deno.dev/zh/docs/mutation/save-command/input-dto/dto-lang

Example of Spring Boot controllers for creating and updating a product using generated DTOs in Kotlin. The `CreateProductInput` is used for creation, and `UpdateProductInput` for updates.

```kotlin
@PostMapping("/product")  
fun createProduct(  
    // `CreateProductInput`属性相对多  
    @RequestBody input: CreateProductInput  
) {  
    productRepository.insert(input)  
}  

@PutMapping("/product")  
fun updateProduct(  
    // `UpdateProductInput`属性相对少  
    @RequestBody input: UpdateProductInput  
) {  
    productRepository.update(input)  
}  

```

--------------------------------

### Get Property Value (Kotlin)

Source: https://jimmer.deno.dev/zh/docs/object/tool

Use `get` to retrieve the value of a dynamic object's property. This method will throw an exception if the property is in an unloaded state.

```kotlin
val authors = get(book, Book::authors)
```

--------------------------------

### Add Book to Store Incrementally (Kotlin)

Source: https://jimmer.deno.dev/zh/docs/mutation/save-command/usage

Demonstrates a simple incremental update to add a book to a store. This contrasts with the full data replacement shown in previous examples, illustrating the save command's adaptability to different complexity levels.

```kotlin
@PutMapping("/store/{storeId}/books/{bookId}")
fun addBook(
    @PathVariable storeId: Long,
    @PathVariable bookId: Long
) {
    sqlClient.update(
        Book {
            id = bookId
            storeId = storeId
        }
    )
}

```

--------------------------------

### Java Example for INSERT_IF_ABSENT

Source: https://jimmer.deno.dev/zh/docs/mutation/save-command/save-mode

Use INSERT_IF_ABSENT to insert entities only if they do not already exist based on key properties. This example shows how to retrieve the IDs of the saved or existing entities.

```java
List<Book> books = Arrays.asList(
    Immutables.createBook(draft -> {
        draft.setName("SQL in Action");
        draft.setEdition(3);
        draft.setPrice(new BigDecimal("49.9"));
        draft.setStoreId(2L);
    }),
    Immutables.createBook(draft -> {
        draft.setName("LINQ in Action");
        draft.setEdition(2);
        draft.setPrice(new BigDecimal("39.9"));
        draft.setStoreId(2L);
    })
);
List<Long> ids = sqlClient
    .saveEntities(
        books,
        SaveMode.INSERT_IF_ABSENT
    )
    .getItems()
    .stream()
    .map(it ->
        ImmutableObjects.isLoaded(it, BookProps.ID) ?
            it.getModifiedEntity().id() :
            null
    )
    .collect(Collectors.toList());
System.out.println(ids);
```

--------------------------------

### Delete Command Example (Kotlin)

Source: https://jimmer.deno.dev/zh/docs/mutation/delete-command

Illustrates the Kotlin approach to deleting objects, where delete methods accept an optional lambda for configuration and execute directly.

```APIDOC
## Delete Command Example (Kotlin)

### Description
This example demonstrates the Kotlin syntax for deleting objects, utilizing a lambda parameter for configurations directly within the delete method.

### Method
`delete` with a configuration lambda

### Endpoint
N/A (This is an SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```kotlin
val result = sqlClient
    .entities
    .delete(BookStore.class, 1L) {
        setDissociateAction(Book::store, DissociateAction.SET_NULL)
    }
```

### Response
#### Success Response (200)
- **result** (DeleteResult) - Contains information about the execution of the delete operation.

#### Response Example
```json
{
  "example": "DeleteResult object"
}
```
```

--------------------------------

### Fetch avgPrice using Fetcher (Java)

Source: https://jimmer.deno.dev/zh/docs/mapping/advanced/calculated/transient

Demonstrates fetching `BookStore` entities along with their calculated `avgPrice` property using `Fetchers.BOOK_STORE_FETCHER` in Java.

```java
List<BookStore> stores = bookStoreRepository.findAll(
    Fetchers.BOOK_STORE_FETCHER
        .name()
        .avgPrice()
);
System.out.println(stores);

```

--------------------------------

### Create Book with Few Properties (Kotlin)

Source: https://jimmer.deno.dev/zh/docs/object/dynamic

Use the Book constructor with a lambda to set basic properties like the name.

```kotlin
val book = Book {
    name = "Learning GraphQL"
}
```

--------------------------------

### Jimmer Page Object Result Example

Source: https://jimmer.deno.dev/zh/docs/showcase/page

This is an example of the JSON output when using Jimmer's `Page<T>` object, showing the rows, total row count, and total page count.

```json
Page{
    rows=[
        {
            "id":10,
            "name":"GraphQL in Action",
            "edition":1,
            "price":82.00,
            "store":{"id":2}
        },
        {
            "id":3,
            "name":"Learning GraphQL",
            "edition":3,
            "price":51.00,
            "store":{"id":1}
        },
        {
            "id":2,
            "name":"Learning GraphQL",
            "edition":2,
            "price":55.00,
            "store":{"id":1}
        },
        {
            "id":1,
            "name":"Learning GraphQL",
            "edition":1,
            "price":50.00,
            "store":{"id":1}
        },
        {
            "id":9,
            "name":"Programming TypeScript",
            "edition":3,
            "price":48.00,
            "store":{"id":1}
        }
    ],
    totalRowCount=12,
    totalPageCount=3
}

```

--------------------------------

### Create and Update Product API (Java)

Source: https://jimmer.deno.dev/zh/docs/mutation/save-command/input-dto/dto-lang

Example of Spring Boot controllers for creating and updating a product using generated DTOs. The `CreateProductInput` is used for creation, and `UpdateProductInput` for updates.

```java
@PostMapping("/product")  
public void createProduct(  
    // `CreateProductInput`属性相对多  
    @RequestBody CreateProductInput input  
) {  
    productRepository.insert(input);  
}  

@PutMapping("/product")  
public void updateProduct(  
    // `UpdateProductInput`属性相对少  
    @RequestBody UpdateProductInput input  
) {  
    productRepository.update(input);  
}  

```

--------------------------------

### Recursive Query JSON Output Example

Source: https://jimmer.deno.dev/zh/docs/quick-view/fetch/feature

Example JSON output demonstrating a recursive query result. It shows nested `parent` and `childNodes` structures, illustrating the hierarchical data fetched.

```json
{
    "id": 10,
    "name": "Woman",
    "parent": {
        "id": 9,
        "name": "Clothing",
        "parent": {
            "id": 1,
            "name": "Home",
            "parent": null
        }
    },
    "childNodes": [
        {
            "id": 11,
            "name": "Casual wear",
            "childNodes": [
                {
                    "id": 12,
                    "name": "Dress",
                    "childNodes": []
                },
                {
                    "id": 13,
                    "name": "Miniskirt",
                    "childNodes": []
                },
                {
                    "id": 14,
                    "name": "Jeans",
                    "childNodes": []
                }
            ]
        },
        {
            "id": 15,
            "name": "Formal wear",
            "childNodes": [
                {
                    "id": 16,
                    "name": "Suit",
                    "childNodes": []
                },
                {
                    "id": 17,
                    "name": "Shirt",
                    "childNodes": []
                }
            ]
        }
    ]
}

```

--------------------------------

### DTO Language Example

Source: https://jimmer.deno.dev/zh/docs/overview/introduction

This example demonstrates the DTO language syntax for defining a DTO type. DTOs are automatically generated, providing a cheap and type-safe way to handle data transfer objects.

```dto
dto UserInfo {
    id: long
    name: string
}
```

--------------------------------

### Kotlin: Calling findBooks with all parameters

Source: https://jimmer.deno.dev/zh/docs/quick-view/dsl/feature

Example of calling the `findBooks` function in Kotlin with non-null name, minPrice, and maxPrice, resulting in all WHERE conditions being applied.

```Kotlin
val books = bookRepository.findBooks(
    name = "GraphQL",
    minPrice = BigDecimal(20),
    maxPrice = BigDecimal(50)
)

```

--------------------------------

### Spring Data Page Object Result Example

Source: https://jimmer.deno.dev/zh/docs/showcase/page

This is an example of the JSON output when using Spring Data's `Page<T>` object, including content, pageable details, total pages, and total elements.

```json
{
    "content":[
        {
            "id":10,
            "name":"GraphQL in Action",
            "edition":1,
            "price":82,
            "store":{"id":2}
        },
        {
            "id":3,
            "name":"Learning GraphQL",
            "edition":3,
            "price":51,
            "store":{"id":1}
        },
        {
            "id":2,
            "name":"Learning GraphQL",
            "edition":2,
            "price":55,
            "store":{"id":1}
        },
        {
            "id":1,
            "name":"Learning GraphQL",
            "edition":1,
            "price":50,
            "store":{"id":1}
        },
        {
            "id":9,
            "name":"Programming TypeScript",
            "edition":3,
            "price":48,
            "store":{"id":1}
        }
    ],
    "pageable":{
        "sort":{
            "unsorted":false,
            "sorted":true,
            "empty":false
        },
        "pageNumber":1,
        "pageSize":5,
        "offset":5,
        "paged":true,
        "unpaged":false
    },
    "totalPages":3,
    "totalElements":12,
    "last":false,
    "numberOfElements":5,
    "first":false,
    "size":5,
    "number":1,
    "sort":{
        "unsorted":false,
        "sorted":true,
        "empty":false
    },
    "empty":false
}

```

--------------------------------

### Fetch List of Books using TanStack/Query

Source: https://jimmer.deno.dev/zh/docs/client/api

This example demonstrates how to fetch a list of books using TanStack/Query and the generated api.bookService.findBooks method. It uses useImmer for managing request options and displays loading, data, and error states.

```typescript
const [options, setOptions] = useImmer<
    // RequestOf是Jimmer生成的TypeScript辅助类，
    // 用于提取任何REST API的参数类型
    RequestOf<
        typeof api.bookService.findBooks
    >
>(() => {
    return {
        pageIndex: 0,
        pageSize: 10,
        sortCode: "name asc"
    };
});

const { 
    isLoading, 
    // 如果`data`非`undefined`, 则其类型必为
    // `Page<BookDto['BookService/SIMPLE_BOOK']>`
    data,
    error,
    refetch
} = useQuery({
    queryKey: ["Books", options],
    // `data`的类型由此决定
    queryFn: () => api.bookService.findBooks(options)
});

```

--------------------------------

### Executing a Query Without Parameters (Java)

Source: https://jimmer.deno.dev/zh/docs/spring/repository/default

Demonstrates how to call the `find` method in a Java repository without providing any arguments, resulting in a query that selects all books ordered by name and edition.

```java
List<Book> books = bookRepository
    .find(null);

```

--------------------------------

### Recursive Query Kotlin Output Example

Source: https://jimmer.deno.dev/zh/docs/quick-view/fetch/feature

Example Kotlin data class output demonstrating a recursive query result. It mirrors the JSON structure with nested objects and lists for parent and child nodes.

```kotlin
RecursiveTreeNodeView(
    id=10, 
    name=Woman, 
    parent=RecursiveTreeNodeView.TargetOf_parent( 
        id=9, 
        name=Clothing, 
        parent=RecursiveTreeNodeView.TargetOf_parent( 
            id=1, 
            name=Home, 
            parent=null 
        )
    ), 
    childNodes=[
        RecursiveTreeNodeView.TargetOf_childNodes(
            id=11, 
            name=Casual wear,
            childNodes=[
                RecursiveTreeNodeView.TargetOf_childNodes(
                    id=12, 
                    name=Dress,
                    childNodes=[]
                ),
                RecursiveTreeNodeView.TargetOf_childNodes(
                    id=13, 
                    name=Miniskirt,
                    childNodes=[]
                ),
                RecursiveTreeNodeView.TargetOf_childNodes(
                    id=14, 
                    name=Jeans,
                    childNodes=[]
                )
            ]
        ),
        RecursiveTreeNodeView.TargetOf_childNodes(
            id=15, 
            name=Formal wear,
            childNodes=[
                RecursiveTreeNodeView.TargetOf_childNodes(
                    id=16, 
                    name=Suit,
                    childNodes=[]
                ),
                RecursiveTreeNodeView.TargetOf_childNodes(
                    id=17, 
                    name=Shirt,
                    childNodes=[]
                )
            ]
        )
    ]
)

```
Tokens:
Raw