anima-core 0.2.1 → 1.0.0

data/skills/activerecord/examples/querying/optimization.rb

@@ -0,0 +1,275 @@
+# Query Optimization Examples
+# Demonstrates pluck, calculations, select, and memory-efficient patterns
+
+# ============================================
+# pluck vs map - Value Extraction
+# ============================================
+
+# BAD - loads full User objects into memory
+emails = User.all.map(&:email)
+# 1. Instantiates every User object
+# 2. Allocates memory for all attributes
+# 3. Then extracts just email
+
+# GOOD - only fetches email column from database
+emails = User.pluck(:email)
+# SELECT email FROM users
+# Returns Array of strings directly
+
+# Multiple columns - returns array of arrays
+User.pluck(:id, :email)
+# => [[1, "a@example.com"], [2, "b@example.com"]]
+
+# With conditions
+User.where(active: true).pluck(:email)
+
+# ============================================
+# pluck Caveats
+# ============================================
+
+# pluck returns Array, not Relation - cannot chain after
+User.pluck(:email).where(active: true)  # NoMethodError!
+
+# pluck ignores select
+User.select(:id).pluck(:email)  # Still plucks email
+
+# pluck with association requires join
+Post.joins(:author).pluck("authors.name")
+# SELECT authors.name FROM posts INNER JOIN authors...
+
+# ============================================
+# ids - Shortcut for Primary Keys
+# ============================================
+
+# These are equivalent
+User.pluck(:id)
+User.ids
+
+# With conditions
+User.active.ids
+# SELECT id FROM users WHERE active = true
+
+# ============================================
+# pick - Single Value
+# ============================================
+
+# Get first matching value (Rails 6+)
+User.where(admin: true).pick(:email)
+# Equivalent to: User.where(admin: true).limit(1).pluck(:email).first
+
+# Multiple columns
+User.pick(:id, :email)
+# => [1, "admin@example.com"]
+
+# ============================================
+# Calculations - Database-Level Math
+# ============================================
+
+# count
+User.count                        # COUNT(*)
+User.count(:email)                # COUNT(email) - excludes NULL
+User.distinct.count(:role)        # COUNT(DISTINCT role)
+
+# sum, average, minimum, maximum
+Order.sum(:total)
+Order.average(:total)
+User.minimum(:created_at)
+User.maximum(:login_count)
+
+# With conditions
+Order.where(status: "completed").sum(:total)
+User.active.average(:age)
+
+# ============================================
+# Grouped Calculations
+# ============================================
+
+# Group by single column
+Order.group(:status).count
+# => {"pending" => 10, "shipped" => 25, "delivered" => 50}
+
+Order.group(:status).sum(:total)
+# => {"pending" => 1000, "shipped" => 5000, "delivered" => 10000}
+
+# Group by multiple columns
+User.group(:role, :status).count
+# => {["admin", "active"] => 5, ["user", "active"] => 100, ...}
+
+# Group by date
+Order.group("DATE(created_at)").count
+# Daily order counts
+
+Order.group("DATE_TRUNC('month', created_at)").sum(:total)
+# Monthly revenue (PostgreSQL)
+
+# ============================================
+# select - Limit Loaded Columns
+# ============================================
+
+# Only load needed columns - reduces memory
+users = User.select(:id, :name, :email)
+
+# WARNING: Accessing non-selected columns raises error
+users.first.password_digest
+# => ActiveModel::MissingAttributeError
+
+# Select with alias
+User.select("name, email, created_at AS signup_date")
+
+# Select with calculation
+User.select("*, (SELECT COUNT(*) FROM posts WHERE user_id = users.id) AS posts_count")
+
+# ============================================
+# exists? vs any? vs count
+# ============================================
+
+# exists? - most efficient for checking presence
+User.where(email: "test@example.com").exists?
+# SELECT 1 FROM users WHERE email = '...' LIMIT 1
+
+# any? - also efficient, slightly different semantics
+User.active.any?
+# SELECT 1 FROM users WHERE active = true LIMIT 1
+
+# count - returns number, less efficient for just checking
+User.active.count > 0  # Less efficient than any?
+
+# BAD - loads all records
+User.active.to_a.any?  # Loads everything!
+User.active.length > 0  # Also loads everything!
+
+# ============================================
+# size vs count vs length
+# ============================================
+
+users = User.where(active: true)
+
+# count - always hits database
+users.count  # SELECT COUNT(*) FROM users WHERE active = true
+
+# size - smart: uses count if not loaded, length if loaded
+users.size   # COUNT(*) if not loaded
+users.to_a
+users.size   # Uses array length (no query)
+
+# length - always loads all records first
+users.length  # SELECT * FROM users..., then .length on array
+
+# Rule: Use size unless you specifically need count or length behavior
+
+# ============================================
+# Anti-Patterns and Fixes
+# ============================================
+
+# Anti-pattern 1: Ruby filtering instead of SQL
+# BAD
+User.all.select { |u| u.active? }
+# GOOD
+User.where(active: true)
+
+# Anti-pattern 2: map instead of pluck
+# BAD
+User.all.map(&:email)
+# GOOD
+User.pluck(:email)
+
+# Anti-pattern 3: each with update
+# BAD - N queries
+User.where(old: true).each { |u| u.update(archived: true) }
+# GOOD - 1 query
+User.where(old: true).update_all(archived: true)
+
+# Anti-pattern 4: Loading for count
+# BAD
+User.all.length
+User.all.size  # If records not yet loaded, ok; if force loading, bad
+# GOOD
+User.count
+
+# Anti-pattern 5: exists check with count
+# BAD
+User.where(email: "test@example.com").count > 0
+# GOOD
+User.where(email: "test@example.com").exists?
+
+# ============================================
+# Practical Optimization Examples
+# ============================================
+
+# Example 1: Dashboard statistics (efficient)
+def dashboard_stats
+  {
+    total_users: User.count,
+    active_users: User.active.count,
+    new_today: User.where("created_at >= ?", Date.current).count,
+    orders_by_status: Order.group(:status).count,
+    monthly_revenue: Order.completed.this_month.sum(:total)
+  }
+end
+
+# Example 2: Dropdown options (efficient)
+def category_options
+  # Instead of Category.all.map { |c| [c.name, c.id] }
+  Category.order(:name).pluck(:name, :id)
+end
+
+# Example 3: Bulk presence check
+def users_exist?(emails)
+  existing = User.where(email: emails).pluck(:email)
+  emails.map { |e| existing.include?(e) }
+end
+
+# Example 4: Memory-efficient iteration with select
+User.select(:id, :email).find_each do |user|
+  # Only id and email loaded, saves memory
+  SomeService.process(user.id, user.email)
+end
+
+# Example 5: Conditional eager loading
+def load_posts(include_comments:)
+  posts = Post.includes(:author)
+  posts = posts.includes(:comments) if include_comments
+  posts
+end
+
+# ============================================
+# EXPLAIN for Query Analysis
+# ============================================
+
+# See query execution plan
+User.where(email: "test@example.com").explain
+# EXPLAIN SELECT * FROM users WHERE email = '...'
+
+# PostgreSQL specific
+User.where(email: "test@example.com").explain(:analyze)
+# EXPLAIN ANALYZE SELECT * FROM users WHERE email = '...'
+
+# Check if index is used
+# Look for "Index Scan" vs "Seq Scan" in output
+
+# ============================================
+# Raw SQL When Needed
+# ============================================
+
+# Complex queries with find_by_sql
+User.find_by_sql([
+  "SELECT users.*, COUNT(posts.id) as post_count
+   FROM users
+   LEFT JOIN posts ON posts.user_id = users.id
+   WHERE users.active = ?
+   GROUP BY users.id
+   HAVING COUNT(posts.id) > ?",
+  true, 5
+])
+
+# Pure SQL execution
+result = ActiveRecord::Base.connection.execute(
+  "SELECT DATE(created_at), COUNT(*) FROM users GROUP BY 1"
+)
+result.to_a  # Array of hashes
+
+# Using Arel for complex conditions
+users = User.arel_table
+User.where(
+  users[:age].gt(18).and(users[:age].lt(65))
+)

data/skills/activerecord/examples/querying/scopes.rb

@@ -0,0 +1,260 @@
+# Scopes Examples
+# Demonstrates named scopes, scope vs class method, default_scope issues
+
+# ============================================
+# Named Scopes - Basic Usage
+# ============================================
+
+class Article < ApplicationRecord
+  belongs_to :author
+  has_many :comments
+
+  # Simple scope
+  scope :published, -> { where(published: true) }
+  scope :draft, -> { where(published: false) }
+
+  # Ordering scope
+  scope :recent, -> { order(created_at: :desc) }
+  scope :oldest, -> { order(created_at: :asc) }
+
+  # Scope with argument
+  scope :by_author, ->(author) { where(author:) }
+  scope :created_after, ->(date) { where("created_at > ?", date) }
+  scope :created_between, ->(start_date, end_date) { where(created_at: start_date..end_date) }
+
+  # Scope with optional argument
+  scope :tagged, ->(tag = nil) {
+    tag ? joins(:tags).where(tags: { name: tag }) : all
+  }
+
+  # Complex scope
+  scope :featured, -> {
+    published
+      .where(featured: true)
+      .where("published_at > ?", 1.week.ago)
+  }
+end
+
+# Usage - scopes are chainable
+Article.published.recent
+Article.published.by_author(current_user).recent
+Article.draft.created_after(1.month.ago)
+
+# ============================================
+# Scope Chaining
+# ============================================
+
+# All scopes return Relations - fully chainable
+articles = Article.published
+                  .recent
+                  .by_author(current_user)
+                  .limit(10)
+
+# Scopes work with associations
+author.articles.published.recent
+
+# Scopes work with finder methods
+Article.published.find_by(slug: "hello-world")
+Article.recent.first
+Article.published.count
+
+# ============================================
+# Scope vs Class Method
+# ============================================
+
+class Post < ApplicationRecord
+  # SCOPE - always returns Relation
+  scope :active, -> {
+    if Feature.enabled?(:soft_delete)
+      where(deleted_at: nil)
+    end
+    # Returns nil if condition false, but Rails converts to .all
+  }
+
+  # CLASS METHOD - can return nil (breaks chaining!)
+  def self.active_method
+    if Feature.enabled?(:soft_delete)
+      where(deleted_at: nil)
+    end
+    # Returns nil if condition false - breaks chaining!
+  end
+end
+
+# Scope handles nil gracefully
+Post.active.recent  # Works even if condition returns nil
+
+# Class method breaks
+Post.active_method.recent  # NoMethodError if active_method returns nil!
+
+# CLASS METHOD is better when:
+# - Complex logic with early returns
+# - Need to accept block
+# - Want explicit control over return value
+
+# Good class method example
+class Post < ApplicationRecord
+  def self.search(query)
+    return none if query.blank?  # Explicit empty result
+
+    sanitized = sanitize_sql_like(query)
+    where("title ILIKE :q OR body ILIKE :q", q: "%#{sanitized}%")
+  end
+end
+
+# ============================================
+# default_scope - USE WITH EXTREME CAUTION
+# ============================================
+
+# Anti-pattern example - DO NOT DO THIS
+class Article < ApplicationRecord
+  default_scope { where(published: true) }  # Dangerous!
+end
+
+# Problem 1: Affects NEW records
+Article.new.published  # => true (unexpected default!)
+Article.create(title: "Draft")  # published: true automatically!
+
+# Problem 2: Hidden filtering everywhere
+Article.all           # Only published articles
+Article.count         # Only counts published
+Article.find(id)      # Fails silently if unpublished!
+
+# Problem 3: Affects joins
+Author.joins(:articles)  # Only joins published articles
+
+# Problem 4: Must remember to unscope
+Article.unscoped.all            # All articles
+Article.unscoped { Article.all }  # Block form
+
+# ============================================
+# Better Alternatives to default_scope
+# ============================================
+
+class Article < ApplicationRecord
+  # Alternative 1: Explicit scopes
+  scope :published, -> { where(published: true) }
+  scope :visible, -> { published }  # Semantic alias
+
+  # Alternative 2: Query object
+  class PublishedArticles
+    def self.call
+      Article.where(published: true)
+    end
+  end
+
+  # Alternative 3: Explicit default in controller
+  def index
+    @articles = Article.published
+  end
+end
+
+# When default_scope IS acceptable (rare):
+# - Ordering only (not filtering)
+# - Truly universal constraint (multi-tenant tenant_id)
+
+class Tenant < ApplicationRecord
+  # Ordering default_scope is less dangerous
+  default_scope { order(:name) }
+end
+
+class Document < ApplicationRecord
+  # Multi-tenant - MUST always filter
+  default_scope { where(tenant_id: Current.tenant_id) }
+end
+
+# ============================================
+# Merging Scopes
+# ============================================
+
+class Author < ApplicationRecord
+  has_many :articles
+  scope :active, -> { where(active: true) }
+  scope :verified, -> { where(verified: true) }
+end
+
+class Article < ApplicationRecord
+  belongs_to :author
+  scope :published, -> { where(published: true) }
+  scope :recent, -> { where("created_at > ?", 1.week.ago) }
+end
+
+# Merge scopes from different models
+Article.published
+       .joins(:author)
+       .merge(Author.active)
+# SELECT articles.* FROM articles
+#   INNER JOIN authors ON authors.id = articles.author_id
+#   WHERE articles.published = true
+#   AND authors.active = true
+
+# Merge multiple scopes
+Article.published
+       .joins(:author)
+       .merge(Author.active.verified)
+
+# Merge with association scope
+class Author < ApplicationRecord
+  has_many :articles
+  has_many :published_articles, -> { published }, class_name: "Article"
+end
+
+# ============================================
+# unscoped - Removing Scopes
+# ============================================
+
+# Remove all scopes (including default_scope)
+Article.unscoped.all
+
+# Block form - only affects block
+Article.unscoped do
+  Article.where(id: 1)  # No default_scope
+end
+
+# unscope - remove specific clauses
+Article.published.recent.unscope(:order)
+# Removes order, keeps where
+
+Article.published.where(featured: true).unscope(where: :published)
+# Removes published condition, keeps featured
+
+# reorder - replace order
+Article.order(:title).reorder(:created_at)
+# Only ordered by created_at
+
+# rewhere - replace where (Rails 7+)
+Article.where(status: "draft").rewhere(status: "published")
+# status = 'published' only
+
+# ============================================
+# Practical Scope Patterns
+# ============================================
+
+class Order < ApplicationRecord
+  # Status scopes
+  scope :pending, -> { where(status: "pending") }
+  scope :processing, -> { where(status: "processing") }
+  scope :completed, -> { where(status: "completed") }
+  scope :cancelled, -> { where(status: "cancelled") }
+
+  # Time-based scopes
+  scope :today, -> { where(created_at: Time.current.all_day) }
+  scope :this_week, -> { where(created_at: Time.current.all_week) }
+  scope :this_month, -> { where(created_at: Time.current.all_month) }
+
+  # Aggregate scopes
+  scope :high_value, -> { where("total > ?", 1000) }
+  scope :with_items, -> { joins(:order_items).distinct }
+
+  # Boolean shortcuts
+  scope :paid, -> { where(paid: true) }
+  scope :unpaid, -> { where(paid: false) }
+
+  # Negation pattern
+  scope :not_cancelled, -> { where.not(status: "cancelled") }
+  scope :active, -> { not_cancelled.where.not(status: "completed") }
+end
+
+# Combining scopes for reports
+Order.this_month.completed.sum(:total)
+Order.today.pending.count
+Order.this_week.high_value.paid.includes(:customer)