Entities & Fields

Data Modeling & Type System

Entities represent the core data structures of your microservice. Each entity is mapped to a GORM model, a Protobuf message, and a PostgreSQL table.

The Declaration Syntax

GDL supports two declaration styles for flexibility, though the Type-First approach is the modern standard for elite developers.

Modern Style (Type-First)

string(100) fullName required
datetime lastLogin
jsonb metadata

Classic Style (Field-First)

fullName String required
lastLogin DateTime
metadata JSONB

Comprehensive Financial Entity Example

This real-world example demonstrates the use of high-precision numeric types like Double and BigDecimal alongside standard types, modifiers, and entity annotations.

@Audited
@Searchable
entity Transaction {
    uuid id required unique             // Maps to UUID
    string(50) transactionId required unique // Maps to VARCHAR(50)
    string currency required            // Maps to VARCHAR(255)
    text notes                          // Maps to TEXT
    int attemptCount                    // Maps to INTEGER
    long userId required                // Maps to BIGINT
    float fee                           // Maps to REAL and float32
    double exchangeRate                 // Maps to DOUBLE PRECISION and float64
    bigdecimal amount required          // Maps to NUMERIC(19,4) and decimal.Decimal
    bool isInternational                // Maps to BOOLEAN
    time cutoffTime                     // Maps to TIME and time.Time
    datetime processedAt                // Maps to TIMESTAMP and time.Time
    instant createdAt                   // Maps to TIMESTAMP and time.Time
    jsonb metadata                      // Maps to JSONB
    json rawPayload                     // Maps to JSON
}

Global Type System Reference

GDL Type	Go Native	SQL (Postgres)
string(N)	string	VARCHAR(N)
text	string	TEXT
int / integer	int	INTEGER
long	int64	BIGINT
float	float32	REAL
double	float64	DOUBLE PRECISION
bigdecimal	decimal.Decimal	NUMERIC(19, 4)
bool / boolean	bool	BOOLEAN
json / jsonb	datatypes.JSON	JSON / JSONB
datetime / instant	time.Time	TIMESTAMP
time	time.Time	TIME
uuid	uuid.UUID	UUID

Field Modifiers

required

Strict Integrity

Adds `NOT NULL` to the SQL schema and marks the field as required in Protobuf and Gin validation hooks.

unique

Natural Key Protection

Automatically creates a unique index in PostgreSQL to prevent duplicate records across all silos.

Next Category

🧬 Relationships