@PalmyraType#

com.palmyralabs.palmyra.base.annotations.PalmyraType

Maps a POJO to its primary database table. Target: TYPE. Retention: RUNTIME.

Attributes#

Attribute Signature
type String type() default "" — alias for value; logical type name
value String value() default "" — alias for type
table String table() default "" — DB table name
schema String schema() default "" — DB schema name
aclMask Acl aclMask() default Acl.ALL — access-control mask
active boolean active() default true — whether the entity is active
searchAll boolean searchAll() default false — all fields searchable
sortAll boolean sortAll() default false — all fields sortable
preferredKey String preferredKey() default "" — unique key to consult first during identity lookups (see preferredKey)
drop DropMode drop() default DropMode.NONE — drop behavior

When the database uses snake_case, supply type in CamelCase.

Example#

@PalmyraType(type = "User", table = "users", schema = "public", preferredKey = "loginName")
public class User {
    // ...
}

preferredKey#

When the framework needs to locate an existing row — either as a “does this already exist?” pre-check before an insert, or as the “which row are we updating?” lookup inside SaveHandler upsert flow — it runs a SELECT against the primary key OR every declared unique key, combined with OR. Any match wins.

preferredKey is a performance / correctness hint on top of that behaviour: it names one unique key that should be consulted first — or exclusively — when multiple keys could match.

Use it when:

  • Performance. A narrow index on one unique key is far cheaper than the OR-combined lookup across every unique key. Point Palmyra at the indexed one.
  • Precedence. Two unique keys could return different rows (e.g. loginName vs. externalId). Telling Palmyra which one to trust keeps the identity semantics predictable — no “first-matching-row-wins” surprises.

Example#

@PalmyraType(type = "User", preferredKey = "loginName")
@PalmyraMappingConfig(
    type = "User",
    uniqueKeys = {
        @PalmyraUniqueKey(fields = {"loginName"}),
        @PalmyraUniqueKey(fields = {"externalId"})
    }
)
public class User {
    @PalmyraField(primaryKey = true)
    private Long id;

    @PalmyraField(attribute = "loginName")
    private String loginName;

    @PalmyraField(attribute = "externalId")
    private String externalId;
}

Here a SaveHandler call that arrives with {loginName: "ada@example.com"} resolves via the loginName key rather than scanning both unique keys. Omitting preferredKey would still work — the row would be found via the OR’d lookup — but the indexed path is explicit.

Backward Annotations @PalmyraField Forward