Relations

an5 ORM supports relations between models using foreign keys and declarative schemas.

Googlesheets note: The Google Sheets adapter resolves relations by cross-referencing matching ID columns across individual sheet tabs in memory.

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