jimmer-orm

Source of Truth

If the local path to the Jimmer project's source code is specified in the current context, the source implementation should be used as the baseline. If in other cases you need to consult Jimmer's specific implementation, its code repository is https://github.com/babyfish-ct/jimmer

Core Concepts

Entity Definition Characteristics

• Use interface to define entities, rather than class
• Entities aredynamic objectsandimmutable objects
• Only getters, no setters
• Generated at compile time by KSP (Kotlin) or AnnotationProcessor (Java)
• Property not set ≠ property is null

DSL Query Characteristics

• Strongly typed SQL DSL, providing compile-time safety guarantees
• Dynamic predicates: decide whether to add SQL conditions based on parameters
• Dynamic table joins: unused joins are automatically ignored, conflicting joins are automatically merged
• Implicit subqueries: create subqueries based on collection associations, automatically generating parent-child association conditions

Language Selection

Jimmer provides a specialized API style for Kotlin

• Entity mapping: refer to references/entity-mapping.md
• DSL query: refer to references/dsl-queries.md
• Entity template: refer to assets/EntityTemplate.kt

Key Annotations Quick Reference

• @Entity - marks entity type
• @MappedSuperclass - marks a mapped superinterface, reusing common fields
• @Embeddable - marks an embedded value object
• @Id - marks the primary key
• @GeneratedValue - primary key generation strategy
• @Key - business key
• @ManyToOne / @OneToMany / @ManyToMany / @OneToOne - association mapping
• @ManyToManyView - exposes a many-to-many view through an intermediate entity
• @IdView - association id view
• @JoinColumn - custom foreign key column name
• @JoinTable - custom intermediate table
• @Column - custom column name (only for non-association fields)
• @Table - custom table name
• @Version - optimistic lock version field
• @LogicalDeleted - logical delete field
• @Formula / @Transient - computed property
• ? (Kotlin) - marks a nullable property

Naming Conventions

• Entity name → table name:BookStore → BOOK_STORE
• Property name → column name:firstName → FIRST_NAME
• Many-to-one foreign key:store → STORE_ID

Workflow

1. When defining entities:

   • Use interface instead of class
   • Refer to the corresponding entity template and mapping documentation according to the project language
   • When the intermediate table has business fields such as ordering, time, source, etc., define an intermediate entity and use @ManyToManyView to expose a read-only many-to-many view
   • When you need to query directly by foreign key or write to input, preferentially add @IdView
   • Refer to assets/EntityTemplate.kt and references/entity-mapping.md
   • Refer to references/dto.md to complete the DTO definition

2. When writing queries:

   • Prefer dynamic predicates (Kotlin: `ilike?`/`between?`/`valueIn?`）
   • Use dynamic table joins to handle single-value association queries
   • Use implicit subqueries to handle collection associations, avoiding duplicate results and pagination failure caused by collection JOINs
   • When an API returns entities, use fetcher/DTO to control the projection; do not rely on the default serialization shape
   • Refer to the corresponding DSL query documentation based on the project language
   • Refer to references/dsl-queries.md

3. When encountering problems:

   • Check whether the entity is defined using an interface
   • Check the association mapping's mappedBy configuration
   • Check whether the parameters of the dynamic predicate are correct
   • Confirm whether the table join path is correct