Skip to main content

Documentation Code Examples

This page demonstrates how code examples are embedded from the examples/ package.

Prerequisites​

What You’ll Learn​

  • How docs snippets are sourced from runnable example code
  • How region-based snippet extraction stays synchronized with source
  • Where to look for canonical examples by feature area

Basic Model Definition​

// #region intro-model
import 'package:ormed/ormed.dart';

part 'user.orm.dart';

@OrmModel(table: 'users')
class User extends Model<User> {
  const User({
    required this.id,
    required this.email,
    this.name,
    this.createdAt,
  });

  @OrmField(isPrimaryKey: true, autoIncrement: true)
  final int id;

  final String email;
  final String? name;
  final DateTime? createdAt;
}

// #endregion intro-model

Model with Options​

import 'package:ormed/ormed.dart';

part 'admin.orm.dart';

@OrmModel(
  table: 'admins',
  hidden: ['password'], // Fields hidden from serialization
  fillable: ['email'], // Fields that can be mass-assigned
  guarded: ['id'], // Fields protected from mass-assignment
  casts: {'createdAt': 'datetime'},
)
class Admin extends Model<Admin> {
  const Admin({
    required this.id,
    required this.email,
    this.password,
    this.createdAt,
  });

  @OrmField(isPrimaryKey: true, autoIncrement: true)
  final int id;

  final String email;
  final String? password;
  final DateTime? createdAt;
}

Basic Queries​

import 'package:ormed/ormed.dart';

import 'models/user.dart';
import 'models/user.orm.dart';
import 'models/post.dart';
import 'models/post.orm.dart';
import 'models/relations/has_many.dart';

Future<void> basicQueryExample(QueryContext context) async {
  // Find all users
  final users = await context.query<$User>().get();

  // Find by ID
  final user = await context.query<$User>().find(1);

  // Find with conditions
  final activeUsers = await context
      .query<$User>()
      .whereEquals('active', true)
      .get();
}

Where Clauses​

Future<void> whereClauseExamples(QueryContext context) async {
  // Equals
  await context.query<$User>().whereEquals('name', 'John').get();

  // Not equals
  await context.query<$User>().whereNotEquals('status', 'banned').get();

  // Comparison operators
  await context.query<$User>().whereGreaterThan('age', 18).get();
  await context.query<$User>().whereGreaterThanOrEqual('age', 21).get();
  await context.query<$User>().whereLessThan('age', 65).get();

  // In clause
  await context.query<$User>().whereIn('role', ['admin', 'moderator']).get();

  // Like clause
  await context.query<$User>().whereLike('name', '%john%').get();

  // Null checks
  await context.query<$User>().whereNull('deletedAt').get();
  await context.query<$User>().whereNotNull('emailVerifiedAt').get();

  // Between
  await context.query<$User>().whereBetween('age', 18, 65).get();
}

Ordering and Limiting​

Future<void> orderingLimitingExamples(QueryContext context) async {
  // Order by single column (ascending by default)
  await context.query<$User>().orderBy('name').get();

  // Order descending
  await context.query<$User>().orderBy('createdAt', descending: true).get();

  // Multiple order by
  await context.query<$User>().orderBy('lastName').orderBy('firstName').get();

  // Limit and offset
  await context.query<$User>().limit(10).get();
  await context.query<$User>().limit(10).offset(20).get();

  // First record
  final firstUser = await context.query<$User>().orderBy('id').first();
}

Aggregates​

Future<void> aggregateExamples(QueryContext context) async {
  // Count
  final userCount = await context.query<$User>().count();

  // Exists check
  final hasAdmins = await context
      .query<$User>()
      .whereEquals('role', 'admin')
      .exists();

  // Max/Min
  final maxAge = await context.query<$User>().max('age');
  final minAge = await context.query<$User>().min('age');

  // Sum/Avg
  final totalBalance = await context.query<$User>().sum('balance');
  final avgAge = await context.query<$User>().avg('age');
}

Working with Relations​

Future<void> relationExamples(QueryContext context) async {
  // Eager load a relation
  final posts = await context.query<$Post>().with_(['author']).get();

  // Load multiple relations
  final postsWithComments = await context.query<$Post>().with_([
    'author',
    'comments',
  ]).get();

  // Nested relation loading
  final postsDeep = await context.query<$Post>().with_([
    'author.profile',
    'comments.user',
  ]).get();

  // Join relation for filtering without loading
  final userPosts = await context
      .query<$User>()
      .joinRelation('posts')
      .whereEquals('posts.published', true)
      .get();
}