From 1bba3505424891bd24e544d864f78c0cf9197438 Mon Sep 17 00:00:00 2001 From: Morgan Aubert Date: Sat, 22 Jun 2024 10:37:24 -0400 Subject: [PATCH] #23 - Add support for model scopes definition --- docs/docs/getting-started/tutorial.md | 4 +- docs/docs/models-and-databases/queries.md | 115 +++++++ spec/marten/db/model/querying_spec.cr | 301 ++++++++++++++++++ spec/marten/db/model/querying_spec/app.cr | 5 + .../querying_spec/models/abstract_post.cr | 13 + .../abstract_post_with_default_scope.cr | 11 + .../db/model/querying_spec/models/author.cr | 9 + .../model/querying_spec/models/child_post.cr | 6 + .../models/child_post_with_default_scope.cr | 6 + .../querying_spec/models/non_abstract_post.cr | 4 + .../non_abstract_post_with_default_scope.cr | 4 + .../model/querying_spec/models/parent_post.cr | 13 + .../models/parent_post_with_default_scope.cr | 11 + .../db/model/querying_spec/models/post.cr | 16 + .../models/post_with_default_scope.cr | 11 + .../db/model/querying_spec/models/tag.cr | 9 + src/marten/db/field/many_to_many.cr | 8 +- src/marten/db/field/many_to_one.cr | 4 +- src/marten/db/model/querying.cr | 216 ++++++++++++- 19 files changed, 751 insertions(+), 15 deletions(-) create mode 100644 spec/marten/db/model/querying_spec/app.cr create mode 100644 spec/marten/db/model/querying_spec/models/abstract_post.cr create mode 100644 spec/marten/db/model/querying_spec/models/abstract_post_with_default_scope.cr create mode 100644 spec/marten/db/model/querying_spec/models/author.cr create mode 100644 spec/marten/db/model/querying_spec/models/child_post.cr create mode 100644 spec/marten/db/model/querying_spec/models/child_post_with_default_scope.cr create mode 100644 spec/marten/db/model/querying_spec/models/non_abstract_post.cr create mode 100644 spec/marten/db/model/querying_spec/models/non_abstract_post_with_default_scope.cr create mode 100644 spec/marten/db/model/querying_spec/models/parent_post.cr create mode 100644 spec/marten/db/model/querying_spec/models/parent_post_with_default_scope.cr create mode 100644 spec/marten/db/model/querying_spec/models/post.cr create mode 100644 spec/marten/db/model/querying_spec/models/post_with_default_scope.cr create mode 100644 spec/marten/db/model/querying_spec/models/tag.cr diff --git a/docs/docs/getting-started/tutorial.md b/docs/docs/getting-started/tutorial.md index fc35bd471..d44478d99 100644 --- a/docs/docs/getting-started/tutorial.md +++ b/docs/docs/getting-started/tutorial.md @@ -292,10 +292,10 @@ Now we can try to retrieve all the `Article` records that we currently have in ```crystal Article.all -# => ]> +# => ]> ``` -This method returns a `Marten::DB::Query::Set` object, which is commonly referred to as a "query set". A query set is a representation of records collections from the database that can be filtered, and iterated over. +This method returns an `Article::QuerySet` object, which is commonly referred to as a "query set". A query set is a representation of records collections from the database that can be filtered, and iterated over. The `Article::QuerySet` class, automatically generated for the `Article` model, is a subclass of `Marten::DB::Query::Set`. :::info Please refer to [Queries](../models-and-databases/queries.md) to learn more about Marten's querying capabilities. diff --git a/docs/docs/models-and-databases/queries.md b/docs/docs/models-and-databases/queries.md index 696ea1bc5..7669d0dcb 100644 --- a/docs/docs/models-and-databases/queries.md +++ b/docs/docs/models-and-databases/queries.md @@ -427,3 +427,118 @@ Article.filter(title: "My article").delete ``` By default, related objects that are associated with the deleted records will also be deleted by following the deletion strategy defined in each relation field (`on_delete` option, see the [reference](./reference/fields.md#on_delete) for more details). The method always returns the number of deleted records. + +## Scopes + +Scopes allow for the pre-definition of specific filtered query sets, which can be easily applied to model classes and model query sets. When defining such scopes, all the query set capabilities that were covered previously (such as [filtering records](#filtering-specific-records), [excluding records](#excluding-specific-records), etc) can be leveraged. + +### Defining scopes + +Scopes can be defined through the use of the [`#scope`](pathname:///api/dev/Marten/DB/Model/Querying.html#scope(name%2C%26block)-macro) macro. This macro expects a scope name (string literal or symbol) as first argument and requires a block where the query set filtering logic is defined. + +For example: + +```crystal +class Post < Marten::Model + field :id, :big_int, primary_key: true, auto: true + field :title, :string, max_size: 255 + field :is_published, :bool, default: false + field :created_at, :date_time + + // highlight-next-line + scope :published { filter(is_published: true) } + // highlight-next-line + scope :unpublished { filter(is_published: false) } + // highlight-next-line + scope :recent { filter(created_at__gt: 1.year.ago) } +end +``` + +Considering the above model definition, it is possible to get published posts by using the following method call: + +```crystal +Post.published # => Post::QuerySet [...]> +``` + +Similarly, retrieving all published posts from a query set object can be accomplished by calling the `#published` method on the query set object: + +```crystal +query_set = Post.all +query_set.published # => Post::QuerySet [...]> +``` + +Because of this capability, it is important to note that scopes can technically be chained. For example, the following snippet will return all the published posts that were created less than one year ago: + +```crystal +Post.published.recent # => Post::QuerySet [...]> +``` + +### Defining scopes with arguments + +If needed, you can define scopes that require arguments. To accomplish this, simply include the required arguments within the scope block. + +For example: + +```crystal +class Post < Marten::Model + field :id, :big_int, primary_key: true, auto: true + field :title, :string, max_size: 255 + field :author, :many_to_one, to: Author + + // highlight-next-line + scope :by_author_id { |author_id| filter(author_id: author_id) } +end +``` + +Scopes that require arguments can be used in the same way as argument-free scopes; they can be called on model classes or model query sets: + +```crystal +Post.by_author_id(42) # => Post::QuerySet [...]> + +query_set = Post.all +query_set.by_author_id(42) # => Post::QuerySet [...]> +``` + +### Defining default scopes + +By default, querying all model records returns unfiltered query sets. However, you can define a default scope to automatically apply a specific filter to all queries for that model. This ensures that certain criteria are consistently enforced without the need to explicitly include a specific filter in every query. + +Default scopes can be defined through the use of the [`#default_scope`](pathname:///api/dev/Marten/DB/Model/Querying.html#default_scope-macro) macro. This macro requires a block where the query set filtering logic is defined. + +For example: + +```crystal +class Post < Marten::Model + field :id, :big_int, primary_key: true, auto: true + field :title, :string, max_size: 255 + field :is_published, :bool, default: false + field :created_at, :date_time + + // highlight-next-line + default_scope { filter(published: true) } +end +``` + +### Disabling scoping + +It is worth mentioning that unscoped model records are always accessible through the use of the [`#unscoped`](pathname:///api/dev/Marten/DB/Model/Querying/ClassMethods.html#unscoped-instance-method) class method. This is especially useful if your model defines a default scope and you need to override it for certain queries. + +For example: + +```crystal +class Post < Marten::Model + field :id, :big_int, primary_key: true, auto: true + field :title, :string, max_size: 255 + field :is_published, :bool, default: false + field :created_at, :date_time + + // highlight-next-line + default_scope { filter(published: true) } +end +``` + +Considering, the above model definition, you can retrieve all the `Post` records by bypassing the default scope with: + +```crystal +Post.unscoped # => Post::QuerySet [...]> +``` diff --git a/spec/marten/db/model/querying_spec.cr b/spec/marten/db/model/querying_spec.cr index e6b2b14b4..0f8425109 100644 --- a/spec/marten/db/model/querying_spec.cr +++ b/spec/marten/db/model/querying_spec.cr @@ -1,4 +1,5 @@ require "./spec_helper" +require "./querying_spec/app" describe Marten::DB::Model::Querying do describe "::all" do @@ -122,6 +123,70 @@ describe Marten::DB::Model::Querying do end end + describe "::default_scope" do + with_installed_apps Marten::DB::Model::QueryingSpec::App + + it "allows to define a default scope for a model" do + post_1 = Marten::DB::Model::QueryingSpec::PostWithDefaultScope.create!( + title: "Post 1", + content: "Content 1", + published: true + ) + Marten::DB::Model::QueryingSpec::PostWithDefaultScope.create!( + title: "Post 2", + content: "Content 2", + published: false + ) + post_3 = Marten::DB::Model::QueryingSpec::PostWithDefaultScope.create!( + title: "Post 3", + content: "Content 3", + published: true + ) + + Marten::DB::Model::QueryingSpec::PostWithDefaultScope.all.to_a.should eq [post_1, post_3] + end + + it "allows to define a default scope for a model through the use of an abstract parent model" do + post_1 = Marten::DB::Model::QueryingSpec::NonAbstractPostWithDefaultScope.create!( + title: "Post 1", + content: "Content 1", + published: true + ) + Marten::DB::Model::QueryingSpec::NonAbstractPostWithDefaultScope.create!( + title: "Post 2", + content: "Content 2", + published: false + ) + post_3 = Marten::DB::Model::QueryingSpec::NonAbstractPostWithDefaultScope.create!( + title: "Post 3", + content: "Content 3", + published: true + ) + + Marten::DB::Model::QueryingSpec::NonAbstractPostWithDefaultScope.all.to_a.should eq [post_1, post_3] + end + + it "allows to define a default scope for a model through the use of a non-abstract parent model" do + post_1 = Marten::DB::Model::QueryingSpec::ChildPostWithDefaultScope.create!( + title: "Post 1", + content: "Content 1", + published: true + ) + Marten::DB::Model::QueryingSpec::ChildPostWithDefaultScope.create!( + title: "Post 2", + content: "Content 2", + published: false + ) + post_3 = Marten::DB::Model::QueryingSpec::ChildPostWithDefaultScope.create!( + title: "Post 3", + content: "Content 3", + published: true + ) + + Marten::DB::Model::QueryingSpec::ChildPostWithDefaultScope.all.to_a.should eq [post_1, post_3] + end + end + describe "::exclude" do before_each do TestUser.create!(username: "jd1", email: "jd1@example.com", first_name: "John", last_name: "Doe") @@ -991,6 +1056,217 @@ describe Marten::DB::Model::Querying do end end + describe "::scope" do + with_installed_apps Marten::DB::Model::QueryingSpec::App + + it "allows to define a scope for a model" do + post_1 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 1", + content: "Content 1", + published: true + ) + post_2 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 2", + content: "Content 2", + published: false + ) + post_3 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 3", + content: "Content 3", + published: true + ) + + Marten::DB::Model::QueryingSpec::Post.all.to_a.should eq [post_1, post_2, post_3] + Marten::DB::Model::QueryingSpec::Post.published.to_a.should eq [post_1, post_3] + end + + it "allows to define a scope that requires arguments for a model" do + post_1 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Top Post 1", + content: "Content 1", + ) + post_2 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 2", + content: "Content 2", + ) + post_3 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Top Post 2", + content: "Content 3", + ) + + Marten::DB::Model::QueryingSpec::Post.all.to_a.should eq [post_1, post_2, post_3] + Marten::DB::Model::QueryingSpec::Post.prefixed("Top").to_a.should eq [post_1, post_3] + end + + it "defines scopes on a model query set" do + post_1 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 1", + content: "Content 1", + published: true + ) + post_2 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 2", + content: "Content 2", + published: false + ) + post_3 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 3", + content: "Content 3", + published: true + ) + + Marten::DB::Model::QueryingSpec::Post.all.to_a.should eq [post_1, post_2, post_3] + Marten::DB::Model::QueryingSpec::Post.all.published.to_a.should eq [post_1, post_3] + end + + it "defines scopes that require arguments on a model query set" do + post_1 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Top Post 1", + content: "Content 1", + ) + post_2 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 2", + content: "Content 2", + ) + post_3 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Top Post 2", + content: "Content 3", + ) + + Marten::DB::Model::QueryingSpec::Post.all.to_a.should eq [post_1, post_2, post_3] + Marten::DB::Model::QueryingSpec::Post.all.prefixed("Top").to_a.should eq [post_1, post_3] + end + + it "defines custom scopes on related sets" do + author_1 = Marten::DB::Model::QueryingSpec::Author.create!(name: "Author 1", is_admin: true) + author_2 = Marten::DB::Model::QueryingSpec::Author.create!(name: "Author 2", is_admin: false) + + post_1 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 1", + content: "Content 1", + author: author_1, + published: true + ) + Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 2", + content: "Content 2", + author: author_2, + published: false + ) + post_3 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 3", + content: "Content 3", + author: author_1, + published: false + ) + + author_1.posts.to_a.should eq [post_1, post_3] + author_1.posts.published.to_a.should eq [post_1] + end + + it "defines custom scopes on many-to-many sets" do + tag_1 = Marten::DB::Model::QueryingSpec::Tag.create!(name: "Tag 1", is_active: true) + tag_2 = Marten::DB::Model::QueryingSpec::Tag.create!(name: "Tag 2", is_active: false) + tag_3 = Marten::DB::Model::QueryingSpec::Tag.create!(name: "Tag 3", is_active: true) + tag_4 = Marten::DB::Model::QueryingSpec::Tag.create!(name: "Tag 4", is_active: true) + + post_1 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 1", + content: "Content 1", + published: true + ) + post_1.tags.add(tag_1, tag_2, tag_3) + + post_2 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 2", + content: "Content 2", + published: false + ) + post_2.tags.add(tag_2, tag_3, tag_4) + + post_3 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 3", + content: "Content 3", + published: true + ) + post_3.tags.add(tag_1, tag_3, tag_4) + + post_1.tags.to_a.should eq [tag_1, tag_2, tag_3] + post_1.tags.active.to_a.should eq [tag_1, tag_3] + end + + it "configures scopes that can be chained" do + post_1 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 1", + content: "Content 1", + published: true, + published_at: 2.years.ago, + ) + post_2 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 2", + content: "Content 2", + published: false + ) + post_3 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 3", + content: "Content 3", + published: true, + published_at: 1.day.ago, + ) + post_4 = Marten::DB::Model::QueryingSpec::Post.create!( + title: "Post 4", + content: "Content 4", + published: true, + published_at: 1.week.ago, + ) + + Marten::DB::Model::QueryingSpec::Post.all.to_a.should eq [post_1, post_2, post_3, post_4] + Marten::DB::Model::QueryingSpec::Post.published.recent.to_a.should eq [post_3, post_4] + end + + it "allows to define a scope for a model through the use of an abstract parent model" do + post_1 = Marten::DB::Model::QueryingSpec::NonAbstractPost.create!( + title: "Post 1", + content: "Content 1", + published: true + ) + post_2 = Marten::DB::Model::QueryingSpec::NonAbstractPost.create!( + title: "Post 2", + content: "Content 2", + published: false + ) + post_3 = Marten::DB::Model::QueryingSpec::NonAbstractPost.create!( + title: "Post 3", + content: "Content 3", + published: true + ) + + Marten::DB::Model::QueryingSpec::NonAbstractPost.all.to_a.should eq [post_1, post_2, post_3] + Marten::DB::Model::QueryingSpec::NonAbstractPost.published.to_a.should eq [post_1, post_3] + end + + it "allows to define a scope for a model through the use of a non-abstract parent model" do + post_1 = Marten::DB::Model::QueryingSpec::ChildPost.create!( + title: "Post 1", + content: "Content 1", + published: true + ) + post_2 = Marten::DB::Model::QueryingSpec::ChildPost.create!( + title: "Post 2", + content: "Content 2", + published: false + ) + post_3 = Marten::DB::Model::QueryingSpec::ChildPost.create!( + title: "Post 3", + content: "Content 3", + published: true + ) + + Marten::DB::Model::QueryingSpec::ChildPost.all.to_a.should eq [post_1, post_2, post_3] + Marten::DB::Model::QueryingSpec::ChildPost.published.to_a.should eq [post_1, post_3] + end + end + describe "::sum" do it "properly calculates the sum" do user = TestUser.create!(username: "jd1", email: "jd1@example.com", first_name: "John", last_name: "Doe") @@ -1001,6 +1277,31 @@ describe Marten::DB::Model::Querying do end end + describe "::unscoped" do + with_installed_apps Marten::DB::Model::QueryingSpec::App + + it "ignores the default scope" do + post_1 = Marten::DB::Model::QueryingSpec::PostWithDefaultScope.create!( + title: "Post 1", + content: "Content 1", + published: true + ) + post_2 = Marten::DB::Model::QueryingSpec::PostWithDefaultScope.create!( + title: "Post 2", + content: "Content 2", + published: false + ) + post_3 = Marten::DB::Model::QueryingSpec::PostWithDefaultScope.create!( + title: "Post 3", + content: "Content 3", + published: true + ) + + Marten::DB::Model::QueryingSpec::PostWithDefaultScope.all.to_a.should eq [post_1, post_3] + Marten::DB::Model::QueryingSpec::PostWithDefaultScope.unscoped.to_a.should eq [post_1, post_2, post_3] + end + end + describe "::using" do before_each do TestUser.using(:other).create!(username: "jd1", email: "jd1@example.com", first_name: "John", last_name: "Doe") diff --git a/spec/marten/db/model/querying_spec/app.cr b/spec/marten/db/model/querying_spec/app.cr new file mode 100644 index 000000000..dd4b5f438 --- /dev/null +++ b/spec/marten/db/model/querying_spec/app.cr @@ -0,0 +1,5 @@ +require "./models/**" + +class Marten::DB::Model::QueryingSpec::App < Marten::App + label :querying_spec +end diff --git a/spec/marten/db/model/querying_spec/models/abstract_post.cr b/spec/marten/db/model/querying_spec/models/abstract_post.cr new file mode 100644 index 000000000..408b6a1b2 --- /dev/null +++ b/spec/marten/db/model/querying_spec/models/abstract_post.cr @@ -0,0 +1,13 @@ +module Marten::DB::Model::QueryingSpec + abstract class AbstractPost < Marten::Model + field :id, :big_int, primary_key: true, auto: true + field :title, :string, max_size: 255 + field :content, :text + field :published, :bool, default: false + field :published_at, :date_time, blank: true, null: true + field :created_at, :date_time, auto_now_add: true + + scope :published { filter(published: true) } + scope :recent { filter(published_at__gt: 1.year.ago) } + end +end diff --git a/spec/marten/db/model/querying_spec/models/abstract_post_with_default_scope.cr b/spec/marten/db/model/querying_spec/models/abstract_post_with_default_scope.cr new file mode 100644 index 000000000..322ed543c --- /dev/null +++ b/spec/marten/db/model/querying_spec/models/abstract_post_with_default_scope.cr @@ -0,0 +1,11 @@ +module Marten::DB::Model::QueryingSpec + abstract class AbstractPostWithDefaultScope < Marten::Model + field :id, :big_int, primary_key: true, auto: true + field :title, :string, max_size: 255 + field :content, :text + field :published, :bool, default: false + field :created_at, :date_time, auto_now_add: true + + default_scope { filter(published: true) } + end +end diff --git a/spec/marten/db/model/querying_spec/models/author.cr b/spec/marten/db/model/querying_spec/models/author.cr new file mode 100644 index 000000000..0de121801 --- /dev/null +++ b/spec/marten/db/model/querying_spec/models/author.cr @@ -0,0 +1,9 @@ +module Marten::DB::Model::QueryingSpec + class Author < Marten::Model + field :id, :big_int, primary_key: true, auto: true + field :name, :string, max_size: 255 + field :is_admin, :bool, default: false + + scope :admins { filter(is_admin: true) } + end +end diff --git a/spec/marten/db/model/querying_spec/models/child_post.cr b/spec/marten/db/model/querying_spec/models/child_post.cr new file mode 100644 index 000000000..d2f9283a7 --- /dev/null +++ b/spec/marten/db/model/querying_spec/models/child_post.cr @@ -0,0 +1,6 @@ +require "./parent_post" + +module Marten::DB::Model::QueryingSpec + class ChildPost < ParentPost + end +end diff --git a/spec/marten/db/model/querying_spec/models/child_post_with_default_scope.cr b/spec/marten/db/model/querying_spec/models/child_post_with_default_scope.cr new file mode 100644 index 000000000..f2c49f206 --- /dev/null +++ b/spec/marten/db/model/querying_spec/models/child_post_with_default_scope.cr @@ -0,0 +1,6 @@ +require "./parent_post_with_default_scope" + +module Marten::DB::Model::QueryingSpec + class ChildPostWithDefaultScope < ParentPostWithDefaultScope + end +end diff --git a/spec/marten/db/model/querying_spec/models/non_abstract_post.cr b/spec/marten/db/model/querying_spec/models/non_abstract_post.cr new file mode 100644 index 000000000..d5bd94be3 --- /dev/null +++ b/spec/marten/db/model/querying_spec/models/non_abstract_post.cr @@ -0,0 +1,4 @@ +module Marten::DB::Model::QueryingSpec + class NonAbstractPost < AbstractPost + end +end diff --git a/spec/marten/db/model/querying_spec/models/non_abstract_post_with_default_scope.cr b/spec/marten/db/model/querying_spec/models/non_abstract_post_with_default_scope.cr new file mode 100644 index 000000000..2d4675bf0 --- /dev/null +++ b/spec/marten/db/model/querying_spec/models/non_abstract_post_with_default_scope.cr @@ -0,0 +1,4 @@ +module Marten::DB::Model::QueryingSpec + class NonAbstractPostWithDefaultScope < AbstractPostWithDefaultScope + end +end diff --git a/spec/marten/db/model/querying_spec/models/parent_post.cr b/spec/marten/db/model/querying_spec/models/parent_post.cr new file mode 100644 index 000000000..bba08a7b5 --- /dev/null +++ b/spec/marten/db/model/querying_spec/models/parent_post.cr @@ -0,0 +1,13 @@ +module Marten::DB::Model::QueryingSpec + class ParentPost < Marten::Model + field :id, :big_int, primary_key: true, auto: true + field :title, :string, max_size: 255 + field :content, :text + field :published, :bool, default: false + field :published_at, :date_time, blank: true, null: true + field :created_at, :date_time, auto_now_add: true + + scope :published { filter(published: true) } + scope :recent { filter(published_at__gt: 1.year.ago) } + end +end diff --git a/spec/marten/db/model/querying_spec/models/parent_post_with_default_scope.cr b/spec/marten/db/model/querying_spec/models/parent_post_with_default_scope.cr new file mode 100644 index 000000000..c8b14a909 --- /dev/null +++ b/spec/marten/db/model/querying_spec/models/parent_post_with_default_scope.cr @@ -0,0 +1,11 @@ +module Marten::DB::Model::QueryingSpec + class ParentPostWithDefaultScope < Marten::Model + field :id, :big_int, primary_key: true, auto: true + field :title, :string, max_size: 255 + field :content, :text + field :published, :bool, default: false + field :created_at, :date_time, auto_now_add: true + + default_scope { filter(published: true) } + end +end diff --git a/spec/marten/db/model/querying_spec/models/post.cr b/spec/marten/db/model/querying_spec/models/post.cr new file mode 100644 index 000000000..8b7d9f3b7 --- /dev/null +++ b/spec/marten/db/model/querying_spec/models/post.cr @@ -0,0 +1,16 @@ +module Marten::DB::Model::QueryingSpec + class Post < Marten::Model + field :id, :big_int, primary_key: true, auto: true + field :author, :many_to_one, to: Marten::DB::Model::QueryingSpec::Author, blank: true, null: true, related: :posts + field :title, :string, max_size: 255 + field :content, :text + field :published, :bool, default: false + field :published_at, :date_time, blank: true, null: true + field :tags, :many_to_many, to: Marten::DB::Model::QueryingSpec::Tag + field :created_at, :date_time, auto_now_add: true + + scope :published { filter(published: true) } + scope :recent { filter(published_at__gt: 1.year.ago) } + scope :prefixed { |prefix| filter(title__istartswith: prefix) } + end +end diff --git a/spec/marten/db/model/querying_spec/models/post_with_default_scope.cr b/spec/marten/db/model/querying_spec/models/post_with_default_scope.cr new file mode 100644 index 000000000..63758a250 --- /dev/null +++ b/spec/marten/db/model/querying_spec/models/post_with_default_scope.cr @@ -0,0 +1,11 @@ +module Marten::DB::Model::QueryingSpec + class PostWithDefaultScope < Marten::Model + field :id, :big_int, primary_key: true, auto: true + field :title, :string, max_size: 255 + field :content, :text + field :published, :bool, default: false + field :created_at, :date_time, auto_now_add: true + + default_scope { filter(published: true) } + end +end diff --git a/spec/marten/db/model/querying_spec/models/tag.cr b/spec/marten/db/model/querying_spec/models/tag.cr new file mode 100644 index 000000000..ffa830c76 --- /dev/null +++ b/spec/marten/db/model/querying_spec/models/tag.cr @@ -0,0 +1,9 @@ +module Marten::DB::Model::QueryingSpec + class Tag < Marten::Model + field :id, :big_int, primary_key: true, auto: true + field :name, :string, max_size: 255 + field :is_active, :bool, default: true + + scope :active { filter(is_active: true) } + end +end diff --git a/src/marten/db/field/many_to_many.cr b/src/marten/db/field/many_to_many.cr index 2d22c34c3..b8804a760 100644 --- a/src/marten/db/field/many_to_many.cr +++ b/src/marten/db/field/many_to_many.cr @@ -115,7 +115,7 @@ module Marten many: true, relation_name: {{ field_id }} )] - @_m2m_{{ field_id }} : Marten::DB::Query::ManyToManySet({{ related_model_klass }})? + @_m2m_{{ field_id }} : {{ related_model_klass }}::ManyToManyQuerySet? register_field( {{ @type }}.new( @@ -128,7 +128,7 @@ module Marten ) def {{ field_id }} - @_m2m_{{ field_id }} ||= Marten::DB::Query::ManyToManySet({{ related_model_klass }}).new( + @_m2m_{{ field_id }} ||= {{ related_model_klass }}::ManyToManyQuerySet.new( self, {{ field_id.stringify }}, {{ through_to_related_name }}, @@ -181,11 +181,11 @@ module Marten reverse: true, relation_name: {{ related_field_name.id }} )] - @_reverse_m2m_{{ related_field_name.id }} : Marten::DB::Query::Set({{ model_klass }})? + @_reverse_m2m_{{ related_field_name.id }} : {{ model_klass }}::QuerySet? def {{ related_field_name.id }} - @_reverse_m2m_{{ related_field_name.id }} ||= Marten::DB::Query::Set({{ model_klass }}).new + @_reverse_m2m_{{ related_field_name.id }} ||= {{ model_klass }}::QuerySet.new .filter( Marten::DB::Query::Node.new( {"{{ through_from_related_name.id }}__{{ through_model_to_field_id.id }}" => self} diff --git a/src/marten/db/field/many_to_one.cr b/src/marten/db/field/many_to_one.cr index 2b1a46f04..7902c7b3a 100644 --- a/src/marten/db/field/many_to_one.cr +++ b/src/marten/db/field/many_to_one.cr @@ -198,11 +198,11 @@ module Marten reverse: true, relation_name: {{ related_field_name.id }} )] - @_reverse_m2o_{{ related_field_name.id }} : Marten::DB::Query::RelatedSet({{ model_klass }})? + @_reverse_m2o_{{ related_field_name.id }} : {{ model_klass }}::RelatedQuerySet? def {{ related_field_name.id }} @_reverse_m2o_{{ related_field_name.id }} ||= - Marten::DB::Query::RelatedSet({{ model_klass }}).new(self, {{ field_id.stringify }}) + {{ model_klass }}::RelatedQuerySet.new(self, {{ field_id.stringify }}) end end end diff --git a/src/marten/db/model/querying.cr b/src/marten/db/model/querying.cr index 507d52648..d7a0ea847 100644 --- a/src/marten/db/model/querying.cr +++ b/src/marten/db/model/querying.cr @@ -4,6 +4,21 @@ module Marten module Querying macro included extend Marten::DB::Model::Querying::ClassMethods + + _begin_scoped_querysets_setup + + macro inherited + _begin_scoped_querysets_setup + _inherit_scoped_querysets + + macro finished + _finish_scoped_querysets_setup + end + end + + macro finished + _finish_scoped_querysets_setup + end end module ClassMethods @@ -106,13 +121,7 @@ module Marten # Returns the default queryset to use when creating "unfiltered" querysets for the model at hand. def default_queryset - {% begin %} - {% if @type.abstract? %} - raise "Records can only be queried from non-abstract model classes" - {% else %} - Query::Set({{ @type }}).new - {% end %} - {% end %} + unscoped end # Returns a queryset whose records do not match the given set of filters. @@ -709,6 +718,17 @@ module Marten default_queryset.sum(field) end + # Returns an unscoped queryset for the considered model. + def unscoped + {% begin %} + {% if @type.abstract? %} + raise "Records can only be queried from non-abstract model classes" + {% else %} + {{ @type }}::QuerySet.new + {% end %} + {% end %} + end + # Returns a queryset that will be evaluated using the specified database. # # A valid database alias must be used here (it must correspond to an ID of a database configured in the @@ -719,6 +739,188 @@ module Marten end end + # Allows to define a default scope for the model query set. + # + # The default scope is a set of filters that will be applied to all the queries performed on the model. For + # example: + # + # ``` + # class Post < Marten::Model + # field :id, :big_int, primary_key: true, auto: true + # field :title, :string, max_size: 255 + # field :is_published, :bool, default: false + # + # default_scope { filter(is_published: true) } + # end + # ``` + macro default_scope + {% MODEL_SCOPES[:default] = yield %} + end + + # Allows to define a custom scope for the model query set. + # + # Custom scopes allow to define reusable query sets that can be used to filter records in a specific way. For + # example: + # + # ``` + # class Post < Marten::Model + # field :id, :big_int, primary_key: true, auto: true + # field :title, :string, max_size: 255 + # field :is_published, :bool, default: false + # + # scope :published { filter(is_published: true) } + # scope :unpublished { filter(is_published: false) } + # end + # + # published_posts = Post.published + # unpublished_posts = Post.unpublished + # + # query_set = Post.all + # published_posts = query_set.published + # ``` + # + # Custom scopes can also receive arguments. To do so, required arguments must be defined within the scope block. + # For example: + # + # ``` + # class Post < Marten::Model + # field :id, :big_int, primary_key: true, auto: true + # field :title, :string, max_size: 255 + # field :author, :many_to_one, to: Author + # + # scope :by_author_id { |author_id| filter(author_id: author_id) } + # end + # + # posts_by_author = Post.by_author_id(123) + # ``` + macro scope(name, &block) + {% MODEL_SCOPES[:custom][name] = block %} + end + + # :nodoc: + macro _begin_scoped_querysets_setup + # :nodoc: + MODEL_SCOPES = { + default: nil, + custom: {} of Nil => Nil, + } + end + + # :nodoc: + macro _inherit_scoped_querysets + {% ancestor_model = @type.ancestors.first %} + + {% if ancestor_model.has_constant?("MODEL_SCOPES") %} + {% for key, value in ancestor_model.constant("MODEL_SCOPES") %} + {% MODEL_SCOPES[key] = value %} + {% end %} + {% end %} + end + + # :nodoc: + macro _finish_scoped_querysets_setup + {% verbatim do %} + {% if !@type.abstract? %} + class ::{{ @type }} + {% if !MODEL_SCOPES[:default].is_a?(NilLiteral) %} + def self.default_queryset + {{ @type }}::QuerySet.new.{{ MODEL_SCOPES[:default] }} + end + {% end %} + + {% for queryset_id, block in MODEL_SCOPES[:custom] %} + def self.{{ queryset_id.id }}{% if !block.args.empty? %}({{ block.args.join(", ").id }}){% end %} + default_queryset.{{ block.body }} + end + {% end %} + end + + class ::{{ @type }}::QuerySet < Marten::DB::Query::Set({{ @type }}) + def initialize( + @query = Marten::DB::Query::SQL::Query({{ @type }}).new, + @prefetched_relations = [] of ::String + ) + super(@query, @prefetched_relations) + end + + {% for queryset_id, block in MODEL_SCOPES[:custom] %} + def {{ queryset_id.id }}{% if !block.args.empty? %}({{ block.args.join(", ").id }}){% end %} + {{ block.body }} + end + {% end %} + + protected def clone(other_query = nil) + ::{{ @type }}::QuerySet.new( + other_query.nil? ? @query.clone : other_query.not_nil!, + prefetched_relations, + ) + end + end + + class ::{{ @type }}::RelatedQuerySet < Marten::DB::Query::RelatedSet({{ @type }}) + def initialize( + @instance : Marten::DB::Model, + @related_field_id : ::String, + query : Marten::DB::Query::SQL::Query({{ @type }})? = nil + ) + super(@instance, @related_field_id, query) + end + + {% for queryset_id, block in MODEL_SCOPES[:custom] %} + def {{ queryset_id.id }}{% if !block.args.empty? %}({{ block.args.join(", ").id }}){% end %} + {{ block.body }} + end + {% end %} + + protected def clone(other_query = nil) + ::{{ @type }}::RelatedQuerySet.new( + instance: @instance, + related_field_id: @related_field_id, + query: other_query.nil? ? @query.clone : other_query.not_nil! + ) + end + end + + class ::{{ @type }}::ManyToManyQuerySet < Marten::DB::Query::ManyToManySet({{ @type }}) + def initialize( + @instance : Marten::DB::Model, + @field_id : ::String, + @through_related_name : ::String, + @through_model_from_field_id : ::String, + @through_model_to_field_id : ::String, + query : Marten::DB::Query::SQL::Query({{ @type }})? = nil + ) + super( + @instance, + @field_id, + @through_related_name, + @through_model_from_field_id, + @through_model_to_field_id, + query + ) + end + + {% for queryset_id, block in MODEL_SCOPES[:custom] %} + def {{ queryset_id.id }}{% if !block.args.empty? %}({{ block.args.join(", ").id }}){% end %} + {{ block.body }} + end + {% end %} + + protected def clone(other_query = nil) + ::{{ @type }}::ManyToManyQuerySet.new( + instance: @instance, + field_id: @field_id, + through_related_name: @through_related_name, + through_model_from_field_id: @through_model_from_field_id, + through_model_to_field_id: @through_model_to_field_id, + query: other_query.nil? ? @query.clone : other_query.not_nil! + ) + end + end + {% end %} + {% end %} + end + # :nodoc: @prefetched_records_cache : Hash(String, Array(Model))?