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 Java

import an5.adapters.An5Query;
import an5.client.An5OrmTypes.StringFilter;
import an5.client.An5OrmTypes.UserWhere;
import an5.client.Post;
import an5.client.User;

import java.util.Arrays;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

UserWhere byId = new UserWhere();
byId.Id = StringFilter.is(userId);

Map<String, Object> include = new LinkedHashMap<String, Object>();
include.put("posts", true);

User user = db.getUser().findUnique(
    new An5Query().where(byId.toMap()).include(include));

The value under the relation name is true or an options map. The options are the ones a query takes — where, orderBy, skip, take, select and a nested include:

Map<String, Object> options = new LinkedHashMap<String, Object>();
options.put("where", Collections.singletonMap("title",
    Collections.singletonMap("contains", "AN5")));
options.put("orderBy", Collections.singletonMap("id", "desc"));
options.put("take", 5);
options.put("select", Arrays.asList("id", "title"));

Map<String, Object> include = new LinkedHashMap<String, Object>();
include.put("posts", options);

User user = db.getUser().findUnique(
    new An5Query().where(byId.toMap()).include(include));

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:

import an5.client.An5OrmTypes.Filters;

Map<String, Object> where = new LinkedHashMap<String, Object>();
where.put("authorId", Filters.eq(userId));

List<Post> posts = db.getPost().findMany(new An5Query().where(where));

Nested Create & Connect

One row per call, so a nested create is two calls in one transaction:

Post post = db.transaction(tx -> {
  User author = db.getUser().create(new User().withEmail("john@example.com"));
  return db.getPost().create(
      new Post().withTitle("Post 1").withAuthorId(author.getId()));
});

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