Relationships

Ormed supports common relationship types between models using the @OrmRelation annotation.

Relationship Types

Has One

A one-to-one relationship where the related model has the foreign key.

@OrmModel(table: 'users')
class UserWithProfile extends Model<UserWithProfile> {
  const UserWithProfile({required this.id, this.profile});

  @OrmField(isPrimaryKey: true)
  final int id;

  @OrmRelation.hasOne(Profile, foreignKey: 'user_id')
  final Profile? profile;
}

@OrmModel(table: 'profiles')
class Profile extends Model<Profile> {
  const Profile({required this.id, required this.userId, required this.bio});

  @OrmField(isPrimaryKey: true)
  final int id;

  final int userId;
  final String bio;
}

Has Many

A one-to-many relationship.

@OrmModel(table: 'users')
class UserWithPosts extends Model<UserWithPosts> {
  const UserWithPosts({required this.id, this.posts});

  @OrmField(isPrimaryKey: true)
  final int id;

  @OrmRelation.hasMany(UserPost, foreignKey: 'author_id')
  final List<UserPost>? posts;
}

@OrmModel(table: 'posts')
class UserPost extends Model<UserPost> {
  const UserPost({
    required this.id,
    required this.authorId,
    required this.title,
  });

  @OrmField(isPrimaryKey: true)
  final int id;

  final int authorId;
  final String title;
}

Belongs To

The inverse of hasOne/hasMany: this model owns the foreign key.

class PostWithAuthor extends Model<PostWithAuthor> {
  const PostWithAuthor({
    required this.id,
    required this.authorId,
    required this.title,
    this.author,
  });

  @OrmField(isPrimaryKey: true)
  final int id;

  final int authorId;
  final String title;

  @OrmRelation.belongsTo(PostAuthor, foreignKey: 'author_id')
  final PostAuthor? author;
}

class PostAuthor extends Model<PostAuthor> {
  const PostAuthor({required this.id, required this.name});

  @OrmField(isPrimaryKey: true)
  final int id;

  final String name;
}

Belongs To Many

A many-to-many relationship using a pivot table.

class PostWithTags extends Model<PostWithTags> {
  const PostWithTags({required this.id, this.tags});

  @OrmField(isPrimaryKey: true)
  final int id;

  @OrmRelation.belongsToMany(
    Tag,
    pivotTable: 'post_tags',
    foreignKey: 'post_id',
    relatedKey: 'tag_id',
  )
  final List<Tag>? tags;
}

class Tag extends Model<Tag> {
  const Tag({required this.id, required this.name});

  @OrmField(isPrimaryKey: true)
  final int id;

  final String name;
}

Loading Relations

Eager Loading

Load relations upfront with the query:

Basic

Future<void> basicEagerLoading(DataSource dataSource) async {
  // Load a single relation
  final posts = await dataSource.query<$Post>().with_(['author']).get();

  for (final post in posts) {
    print(post.author?.name); // Already loaded, no additional query
  }
}

Multiple

Future<void> multipleRelationsLoading(DataSource dataSource) async {
  final posts = await dataSource.query<$Post>().with_([
    'author',
    'tags',
    'comments',
  ]).get();
}

Nested

Future<void> nestedRelationsLoading(DataSource dataSource) async {
  // Load author's profile along with author
  final posts = await dataSource.query<$Post>().with_(['author.profile']).get();

  // Multiple levels
  final deepPosts = await dataSource.query<$Post>().with_([
    'author.profile',
    'comments.user.profile',
  ]).get();
}

Lazy Loading

Load relations on-demand:

Load

Future<void> lazyLoading(DataSource dataSource) async {
  final post = await dataSource.query<$Post>().find(1);

  if (post != null) {
    // Load after fetching
    await post.load(['author', 'tags']);

    print(post.author?.name);
  }
}

Missing

Future<void> loadMissingExample(DataSource dataSource) async {
  final post = await dataSource.query<$Post>().find(1);

  if (post != null) {
    // Only loads relations that haven't been loaded yet
    await post.loadMissing(['author', 'comments']);
  }
}

Checking Relation Status

Future<void> checkLoadedExample(DataSource dataSource) async {
  final post = await dataSource.query<$Post>().find(1);

  if (post != null) {
    if (post.relationLoaded('author')) {
      print(post.author?.name);
    } else {
      await post.load(['author']);
    }
  }
}

Relation Manipulation

Setting Relations

Future<void> associateExample(DataSource dataSource) async {
  final postRepo = dataSource.repo<$Post>();
  final post = await dataSource.query<$Post>().first();
  final user = await dataSource.query<$User>().first();

  if (post != null && user != null) {
    // Set a belongs-to relationship
    post.associate('author', user);
    await postRepo.update(post);

    // Remove a belongs-to relationship
    post.dissociate('author');
    await postRepo.update(post);
  }
}

Many-to-Many Operations

Attach

Future<void> attachDetachExample(DataSource dataSource) async {
  final post = await dataSource.query<$Post>().first();

  if (post != null) {
    // Attach related models to a many-to-many relationship
    await post.attach('tags', [1, 2]);

    // With pivot data
    await post.attach('tags', [3], pivot: {'added_by': 1});

    // Detach related models
    await post.detach('tags', [1]);

    // Detach all
    await post.detach('tags');
  }
}

Sync

Future<void> syncToggleExample(DataSource dataSource) async {
  final post = await dataSource.query<$Post>().first();

  if (post != null) {
    // Sync: replaces all related models with these
    await post.sync('tags', [1, 2, 3]);

    // Toggle: add if not present, remove if present
    await post.toggle('tags', [1, 2]);
  }
}

Aggregate Loading

Load aggregate values without fetching all related models:

Count

Future<void> countAggregateExample(DataSource dataSource) async {
  final user = await dataSource.query<$User>().first();

  if (user != null) {
    await user.loadCount(['posts', 'comments']);
    // Access via getAttribute
    print('Posts: ${user.getAttribute<int>('posts_count')}');
    print('Comments: ${user.getAttribute<int>('comments_count')}');
  }
}

Sum

Future<void> sumAggregateExample(DataSource dataSource) async {
  final user = await dataSource.query<$User>().first();

  if (user != null) {
    await user.loadSum(['posts'], 'views');
    print('Total views: ${user.getAttribute<num>('posts_views_sum')}');
  }
}

Exists

Future<void> existsAggregateExample(DataSource dataSource) async {
  final user = await dataSource.query<$User>().first();

  if (user != null) {
    await user.loadExists(['posts']);
    if (user.getAttribute<bool>('posts_exists') ?? false) {
      print('User has posts');
    }
  }
}

Preventing N+1 Queries

Use Model.preventLazyLoading() in development to catch N+1 issues:

void preventNPlusOneExample() {
  // Enable lazy loading prevention in development
  // void main() {
  //   if (kDebugMode) {
  //     Model.preventLazyLoading();
  //   }
  //   runApp(MyApp());
  // }
  //
  // This throws an exception when you try to access a relation
  // that hasn't been eager-loaded, helping catch N+1 issues.
}

This throws an exception when accessing relations that haven't been eager-loaded, helping you identify performance issues early.