Relations

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

Nbase note: NBase is a neural vector store without native relational foreign keys. When using NBase alongside a relational database, store foreign keys and metadata in your relational tables while referencing vector IDs.

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

Querying Relations in C#

In the generated .NET entity client:

// Retrieve user with included posts
var users = db.Users.FindMany(
    where: u => u.Email.Contains("@example.com"),
    include: "Posts"
);

// Access child posts collection
foreach (var user in users)
{
    Console.WriteLine($"{user.Name} has {user.Posts.Count} posts");
}

Creating Child Records

var postTable = db.Table<Post>("Post");
postTable.Create(new Post {
    Id = Guid.NewGuid().ToString(),
    Title = "AN5 on .NET",
    AuthorId = authorId
});

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