Refactor documentation to replace 'includes' with 'preload' for eager loading examples

Author: eliasjpr

README.md

@@ -346,11 +346,11 @@ user.posts.create(title: "New Post", content: "Content")
 user.posts.size                         # Efficient count without loading all records
 user.posts.any?                         # Check existence without memory overhead
 
-# Smart eager loading
-users_with_posts = User.includes(:posts, :profile)
+# Eager loading with preload (avoids N+1 queries)
+users_with_posts = User.preload(:posts)
                       .where(active: true)
                       .all
-# Single query instead of N+1 queries!
+# Only 2 queries instead of N+1 queries!
 ```
 
 ### Transaction Management
@@ -486,10 +486,10 @@ fragment_cache = CQL::Cache::FragmentCache.new(memory_cache)
 # Intelligent caching with automatic invalidation
 result = fragment_cache.cache_fragment("expensive_query", {"user_id" => user.id}) do
   # Expensive database operation cached automatically
-  User.joins(:posts, :comments)
+  User.join(:posts)
       .where(active: true)
-      .includes(:profile)
-      .complex_aggregation
+      .preload(:profile)
+      .all
 end
 
 # Tag-based cache invalidation
@@ -516,7 +516,7 @@ detector.analyze_queries(queries) do |pattern|
   puts "⚠️  N+1 Query Pattern Detected:"
   puts "   Model: #{pattern.model}"
   puts "   Association: #{pattern.association}"
-  puts "   Suggestion: Use .includes(:#{pattern.association})"
+  puts "   Suggestion: Use .preload(:#{pattern.association})"
 end
 
 # Generate beautiful performance reports

docs/advanced-topics/performance-optimization.md

@@ -50,7 +50,7 @@ users.each do |user|
 end
 
 # Good: Eager loading
-users = User.includes(:posts).all
+users = User.preload(:posts).all
 users.each do |user|
   puts user.posts.size  # No additional queries
 end

docs/advanced-topics/performance-tools.md

@@ -104,7 +104,7 @@ posts.each do |post|
 end
 
 # Better approach:
-posts = Post.includes(:user).all  # Single query with JOIN
+posts = Post.preload(:user).all  # Single query with JOIN
 posts.each do |post|
   puts "#{post.title} by #{post.user.name}"  # No additional queries
 end
@@ -434,7 +434,7 @@ end
 
 # Usage
 users = benchmark_query("User.all with includes") do
-  User.includes(:posts, :comments).all
+  User.preload(:posts, :comments).all
 end
 ```
 

docs/caching-and-performance/caching-guide.md

@@ -314,7 +314,7 @@ def render_category_tree
     tags: ["categories"],
     ttl: 30.minutes
   ) do
-    Category.root_categories.includes(:children).to_json
+    Category.root_categories.preload(:children).to_json
   end
 end
 ```
@@ -451,7 +451,7 @@ class ProductsController < ApplicationController
 
     product_json = cache_fragment("product_#{product_id}") do
       product = Product.find(product_id)
-      reviews = product.reviews.includes(:user).limit(10)
+      reviews = product.reviews.preload(:user).limit(10)
 
       {
         product: product.to_json,

docs/caching-and-performance/per-request-query-caching.md

@@ -308,11 +308,11 @@ class BlogApp < Azu::Application
 
   get "/articles" do |ctx|
     # First query - hits database
-    articles = Article.published.includes(:author)
+    articles = Article.published.preload(:author)
 
     # If this same query runs again in the same request
     # (e.g., in a partial or helper), it hits the cache
-    popular_articles = Article.published.includes(:author)
+    popular_articles = Article.published.preload(:author)
 
     render_template "articles/index.html", {
       articles: articles,
@@ -359,8 +359,8 @@ class UsersController < ApplicationController
 
   def dashboard
     # Complex queries that benefit from caching
-    @active_users = User.where(active: true).includes(:posts)
-    @recent_posts = Post.recent.includes(:author)
+    @active_users = User.where(active: true).preload(:posts)
+    @recent_posts = Post.recent.preload(:author)
 
     # If these queries are repeated (e.g., in partials), they hit cache
     render "dashboard"

docs/examples-and-tutorials/examples-1/generated-schema-example.md

@@ -310,12 +310,12 @@ comment.save!
 puts "Created comment: #{comment.content} (ID: #{comment.id})"
 
 # Query with relationships
-posts = Post.includes(:user).all
+posts = Post.preload(:user).all
 posts.each do |post|
   puts "Post: #{post.title} by #{post.user.try(&.name) || 'Unknown'}"
 end
 
-comments = Comment.includes(:user, :post).all
+comments = Comment.preload(:user, :post).all
 comments.each do |comment|
   puts "Comment: #{comment.content} by #{comment.user.try(&.name) || 'Unknown'} on #{comment.post.try(&.title) || 'Unknown Post'}"
 end

docs/examples/generated-schema-example.md

@@ -310,12 +310,12 @@ comment.save!
 puts "Created comment: #{comment.content} (ID: #{comment.id})"
 
 # Query with relationships
-posts = Post.includes(:user).all
+posts = Post.preload(:user).all
 posts.each do |post|
   puts "Post: #{post.title} by #{post.user.try(&.name) || 'Unknown'}"
 end
 
-comments = Comment.includes(:user, :post).all
+comments = Comment.preload(:user, :post).all
 comments.each do |comment|
   puts "Comment: #{comment.content} by #{comment.user.try(&.name) || 'Unknown'} on #{comment.post.try(&.title) || 'Unknown Post'}"
 end

docs/foundation/crud-operations/README.md

@@ -385,9 +385,9 @@ users = User.query
   .where(active: true)
   .limit(100)
 
-# Use includes for eager loading (prevents N+1)
+# Use preload for eager loading (prevents N+1)
 posts = Post.query
-  .includes(:user, :comments)
+  .preload(:user, :comments)
   .where(published: true)
 
 # Use batch operations for large datasets

docs/guides/active-record-with-cql/queryable.md

@@ -763,6 +763,96 @@ end
 
 ---
 
+## Eager Loading with Preload
+
+Eager loading allows you to load associated records in batch queries, avoiding the N+1 query problem. CQL provides the `preload` method for efficient association loading.
+
+### Basic Preloading
+
+```crystal
+# Preload a single association
+users = User.preload(:posts).all
+users.each do |user|
+  # posts are already loaded - no additional query
+  puts "#{user.name} has #{user.posts.size} posts"
+end
+
+# Preload multiple associations
+users = User.preload(:posts, :comments).all
+users.each do |user|
+  puts "#{user.name}: #{user.posts.size} posts, #{user.comments.size} comments"
+end
+```
+
+### Chaining with Where
+
+Preload works seamlessly with other query methods:
+
+```crystal
+# Filter users then preload their posts
+active_users = User.where(active: true)
+                   .preload(:posts)
+                   .order(:name)
+                   .all
+
+# Only 2 queries total:
+# 1. SELECT * FROM users WHERE active = true ORDER BY name
+# 2. SELECT * FROM posts WHERE user_id IN (...)
+```
+
+### How Preload Works
+
+Unlike JOIN-based eager loading, `preload` uses separate queries:
+
+1. First query fetches the primary records
+2. Subsequent queries fetch associated records using `IN` clauses
+3. Records are matched in memory and associations are populated
+
+This approach:
+
+- Avoids cartesian product issues with multiple has_many associations
+- Keeps queries simple and indexable
+- Works well with pagination
+
+### Preload vs Join
+
+| Aspect                   | `preload`                    | `join`                          |
+|--------------------------|------------------------------|---------------------------------|
+| Query count              | N+1 reduced to 2 queries     | 1 query                         |
+| Cartesian product        | No                           | Yes (with multiple has_many)    |
+| Filtering on association | No                           | Yes                             |
+| Pagination               | Works correctly              | May return duplicates           |
+| Best for                 | Loading data to display      | Filtering by association        |
+
+```crystal
+# Use preload when you need the associated data
+users = User.preload(:posts).all
+
+# Use join when filtering by association
+users_with_recent_posts = User.join(:posts)
+                              .where("posts.created_at > ?", 1.week.ago)
+                              .distinct
+                              .all
+```
+
+### Performance Considerations
+
+```crystal
+# Preload only what you need
+users = User.preload(:posts).all  # Good - loads posts in one query
+
+# Avoid preloading unused associations
+users = User.preload(:posts, :comments, :profile).all  # Wasteful if you only use posts
+
+# Combine with select for optimal performance
+users = User.select(:id, :name)
+            .preload(:posts)
+            .where(active: true)
+            .all
+```
+
+---
+
 ## Advanced Query Composition
 
 CQL's query interface allows you to build complex queries by combining multiple query methods. This section demonstrates common patterns and best practices for composing sophisticated queries.

docs/guides/active-record-with-cql/relations/README.md

@@ -164,12 +164,38 @@ Each guide includes:
 - **Advanced Features**: Using collection methods, dependent options, and performance optimizations
 - **Complete Examples**: Real-world scenarios with full code samples
 
+## Eager Loading with Preload
+
+CQL provides the `preload` method to efficiently load associations and avoid N+1 query problems:
+
+```crystal
+# Load users with their posts in 2 queries (instead of N+1)
+users = User.preload(:posts).all
+users.each do |user|
+  puts "#{user.name} has #{user.posts.size} posts"  # No additional query
+end
+
+# Preload multiple associations
+users = User.preload(:posts, :comments, :profile).all
+
+# Chain with other query methods
+active_users = User.where(active: true)
+                   .preload(:posts)
+                   .order(:name)
+                   .all
+```
+
+For more details, see:
+
+- [Eager Loading in Queryable](../queryable.md#eager-loading-with-preload)
+- [HasMany Eager Loading](./hasmany.md#eager-loading)
+
 ## Best Practices
 
 ### Performance
 
 - Use `cache: true` for frequently accessed `belongs_to` associations
-- Consider eager loading for scenarios where you'll access multiple associations
+- Use `preload` to avoid N+1 queries when accessing associations in loops
 - Use `dependent: :destroy` or `:delete` to maintain referential integrity
 
 ### Schema Design