Relations
an5 ORM supports relations between models using foreign keys and declarative schemas.
Postgresql note:
PostgreSQL enforces relational constraints via foreign key indexes. Relations compile to SQL LEFT JOIN or correlated EXISTS / NOT EXISTS subqueries.
Defining Relations
One-to-Many
model User {
id NVARCHAR(1000) @id @default(uuid())
email NVARCHAR(255) @unique
posts Post[] // One user has many posts
}
model Post {
id NVARCHAR(1000) @id @default(uuid())
title NVARCHAR(255)
content TEXT
published BOOLEAN @default(false)
authorId NVARCHAR(1000)
createdAt DATETIME @default(now())
author User @relation(fields: [authorId], references: [id])
}
One-to-One
model User {
id NVARCHAR(1000) @id @default(uuid())
email NVARCHAR(255) @unique
profile Profile?
}
model Profile {
id NVARCHAR(1000) @id @default(uuid())
bio TEXT
userId NVARCHAR(1000) @unique
user User @relation(fields: [userId], references: [id])
}
Many-to-Many
Implicit many-to-many join tables are not generated automatically. Model many-to-many as an explicit join model with two foreign keys:
model PostTag {
id NVARCHAR(1000) @id @default(uuid())
postId NVARCHAR(1000)
tagId NVARCHAR(1000)
post Post @relation(fields: [postId], references: [id])
tag Tag @relation(fields: [tagId], references: [id])
@@map("post_tags")
}
Querying Relations
Include Relations in Kotlin
import an5.client.An5Orm
import an5.client.Post
import an5.client.User
val user = db.user.findFirst {
where(An5Orm.UserWhere(id = An5Orm.StringFilter.`is`(userId)).build())
include(mapOf("posts" to true))
}
findFirst { ... } takes the query block, so include sits next to where. The value
under the relation name is true or a map of the same options a query takes:
val user = db.user.findFirst {
where(An5Orm.UserWhere(id = An5Orm.StringFilter.`is`(userId)).build())
include(mapOf(
"posts" to mapOf(
"where" to mapOf("title" to mapOf("contains" to "AN5")),
"orderBy" to mapOf("id" to "desc"),
"take" to 5,
"select" to listOf("id", "title"),
)
))
}
Relation Filters
The some / every / none shorthand is the TypeScript adapter’s. The JVM SQL builder
never reads it, and a key it cannot parse lands in an empty WHERE, which matches every
row instead of failing — so filter from the child side:
val posts = db.post.findMany {
where(mapOf("authorId" to mapOf("equals" to userId)))
}
Nested Create & Connect
One row per call, so a nested create is two calls in one transaction:
val post = db.transaction {
val author = db.user.create(User(email = "john@example.com"))
db.post.create(Post(title = "Post 1", authorId = author.id))
}
Cascade Operations
Configure cascade delete behavior in your .an5 schema using @cascade:
model User {
id NVARCHAR(1000) @id @default(uuid())
posts Post[] @cascade
@@map("users")
}
model Post {
id NVARCHAR(1000) @id @default(uuid())
authorId NVARCHAR(1000)
author User @relation(fields: [authorId], references: [id])
@@map("posts")
}
Next Steps
- Advanced Queries - Complex filtering, aggregation and raw SQL
- Transactions - Atomic multi-table updates