Define Entity Mappings

Use the annotations and rules for the chosen persistence model. The supported NoSQL forms below do not extend to arbitrary combinations of Java types.

Map a Record and an Embedded Value

This example defines a NoSQL entity record with an embedded address. Both types must be available to metadata discovery.

import jakarta.nosql.Column;
import jakarta.nosql.Embeddable;
import jakarta.nosql.Entity;
import jakarta.nosql.Id;

@Entity
public record OrderDocument(@Id String id, @Column Address address) {
    @Embeddable
    public record Address(@Column String city) {
    }
}

An embeddable supplies nested mapping information. It is not registered as an independent entity name.

Supported NoSQL Entity Shapes

The following table pairs supported mapping forms with their rejection conditions.

Shape	Supported Use	Rejected or Restricted Form
Mutable class	Concrete entity with supported fields and usable construction	Abstract entity, interface, or non-static member entity
Record	Canonical-constructor mapping, including supported embedded values	Invalid component mappings
Constructor-based entity	Resolvable constructor covering persistent and inherited fields	Incomplete, ambiguous, or duplicate mapped parameters
Constructor parameter name	Explicit mapped name or available source parameter name	Blank mapped name without an available source name
Final field	Supported immutable and no-argument/final-field reconstruction	Forms outside the materialization contract
Embeddable	Discovered grouping or nested class/record	Missing admitted metadata for a nested mapped type
Converter	Supported jakarta.nosql.Convert mapping and applicable constructor/container conversion	Converter on a non-persistent record component
Array	Reifiable supported scalar or embeddable component	Non-reifiable generic array
Collection	Supported iterable, list, set, queue, deque, sorted/navigable, priority, and concrete forms	Raw, wildcard, unresolved type-variable, unsupported interface, or unconstructible form
Ordered collection	Usable comparator or compatible resolved natural ordering	Missing required ordering contract
Map	Reifiable supported key/value types and supported materialization	Raw map; embedded-value map with a key type other than String

Unsupported shapes fail deployment metadata construction with MappingException. Supported collection families include Iterable, Collection, List, Set, Queue, Deque, SortedSet, NavigableSet, supported priority queues, and instantiable concrete forms.

The NoSQL model does not imply Jakarta Persistence relationship, persistence-context, or polymorphic inheritance semantics.