activerecord-summarize 0.4.0 → 0.5.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +6 -0
- data/Gemfile.lock +2 -2
- data/README.md +15 -11
- data/docs/use_case_moderator_dashboard.md +4 -4
- data/lib/activerecord/summarize/version.rb +1 -1
- data/lib/activerecord/summarize.rb +3 -3
- data/lib/chainable_result.rb +15 -4
- metadata +3 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: d3349ef226e79ac7b8182798fbe3f0966a94bd29a5ec31202fe14c74e681bc68
|
4
|
+
data.tar.gz: f257baecb4562c791d0d7648f45ec2549e1ae6faff2cfcd386d95a5e68fb233a
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: fdf0dece89a7d1db578414a1682adb956e8a973c7d575b7d589d0645ef906bdba2f9d849a1833fd1cc10a7b6f1e105c2c36b54532624005d67d8501e1e03aa13
|
7
|
+
data.tar.gz: a21a8e232e86706283954d4690b99c824c80b3521337c2dba10dc3f415f295844670f6d0c4ac94d7a0a8fa58c5fe408a07a64b3d31b65f20086a1d6920409382
|
data/CHANGELOG.md
CHANGED
@@ -1,3 +1,9 @@
|
|
1
|
+
## [0.5.0] - 2023-05-14
|
2
|
+
|
3
|
+
- **FEATURE:** Your `summarize` blocks won't need to accept the proc second argument as often, because `ChainableResult` methods will also resolve their arguments. E.g., `query.summarize {|q| @mult = q.sum(:a) * q.sum(:b) }` now works, where previously you would have needed to write `query.summarize {|q,with| @mult = with[q.sum(:a),q.sum(:b)] {|a,b| a * b } }`.
|
4
|
+
|
5
|
+
- **IMPROVEMENT:** The conventional name of the proc provided as an optional second argument to `summarize` blocks is now `with_resolved` instead of `with`. Interactively teaching `activerecord-summarize` to some people showed that this was an improvement in clarity. The local name of the proc has always been under your control (it's your block!), so this doesn't affect anything besides documentation and tests, but if for some reason you accessed the proc at its internal name of `ChainableResult::WITH`, that will still work, too, even though we now refer to it as `ChainableResult::WITH_RESOLVED`.
|
6
|
+
|
1
7
|
## [0.4.0] - 2023-02-27
|
2
8
|
|
3
9
|
- **FEATURE:** Support for top-level .group(:belongs_to_association), returning hash with models as keys.
|
data/Gemfile.lock
CHANGED
data/README.md
CHANGED
@@ -59,7 +59,7 @@ Purchase.complete.left_joins(:region).summarize do |purchases|
|
|
59
59
|
end
|
60
60
|
```
|
61
61
|
|
62
|
-
Until the `summarize` block ends, the return value of your calculations are `ChainableResult::Future` instances, a bit like a Promise with a more convenient API. You can call any method you like on a `ChainableResult`, and you'll get back another `ChainableResult`, and they'll all turn out alright in the end—provided you called methods that would have worked if you had run that calculation without `summarize`. OTOH, using a `ChainableResult` as an argument to
|
62
|
+
Until the `summarize` block ends, the return value of your calculations are `ChainableResult::Future` instances, a bit like a Promise with a more convenient API. You can call any method you like on a `ChainableResult`, and you'll get back another `ChainableResult`, and they'll all turn out alright in the end—provided you called methods that would have worked if you had run that calculation without `summarize`. OTOH, using a `ChainableResult` as an argument to a method of a non-`ChainableResult` generally will not work.
|
63
63
|
|
64
64
|
```ruby
|
65
65
|
Purchase.last_quarter.complete.summarize do |purchases|
|
@@ -68,24 +68,28 @@ Purchase.last_quarter.complete.summarize do |purchases|
|
|
68
68
|
@vc_projection = @sales * 3
|
69
69
|
# And this won't:
|
70
70
|
@vc_projection = 3 * @sales
|
71
|
+
# But this will work since v0.5.0...
|
72
|
+
@units_sold = purchases.sum(:units)
|
73
|
+
# ...because methods of `ChainableResult` now resolve their argument(s)
|
74
|
+
@avg_unit_price = @sales / @units_sold
|
71
75
|
end
|
72
76
|
```
|
73
77
|
|
74
|
-
If, within a `summarize` block, you want to combine data from more than one `ChainableResult`, you
|
78
|
+
If, within a `summarize` block, you want to combine data from more than one `ChainableResult`, you may need to use the otherwise-optional second argument yielded to the block, a `proc` I like to name `with_resolved`. Pass it all the results you want to combine and a block that combines them and returns the new result:
|
75
79
|
|
76
80
|
```ruby
|
77
|
-
Purchase.complete.left_joins(:promotion).summarize do |purchases,
|
81
|
+
Purchase.complete.left_joins(:promotion).summarize do |purchases, with_resolved|
|
78
82
|
@all_revenue = purchases.sum(:amount)
|
79
83
|
promotions = purchases.where.not(promotions: {id: nil})
|
80
84
|
@promotion_sales = promotions.count
|
81
85
|
@promotion_discounts = promotions.sum("promotions.discount_amount")
|
82
|
-
@avg_discount =
|
86
|
+
@avg_discount = with_resolved[@promotion_sales, @promotion_discounts] do |sales, discounts|
|
83
87
|
sales.zero? ? 0 : discounts / sales
|
84
88
|
end
|
85
89
|
end
|
86
90
|
```
|
87
91
|
|
88
|
-
Treat a `
|
92
|
+
Treat a `with_resolved` block as a pure function: i.e., return the value you care about, and don't set or change any other state within the block. Behavior in any other case is undefined.
|
89
93
|
|
90
94
|
## Escape hatch
|
91
95
|
|
@@ -93,7 +97,7 @@ The query generated by `summarize` is often much faster than equivalent queries
|
|
93
97
|
|
94
98
|
By design, every operation performed with `summarize` is correct and corresponds to normal `ActiveRecord` behavior, and any operations that can't be done correctly this way or aren't yet will raise exceptions. But only imperfect humans have worked on this gem, so you might also wonder if `summarize` is producing correct results.
|
95
99
|
|
96
|
-
Fortunately, you can easily check both with `summarize(noop: true)`, which causes `summarize` to yield the original relation it was called on and a trivial `
|
100
|
+
Fortunately, you can easily check both with `summarize(noop: true)`, which causes `summarize` to yield the original relation it was called on and a trivial `with_resolved` proc. The block will be executed as though `summarize` were not involved, with each calculation executing separately and immediately returning numbers or hashes.
|
97
101
|
|
98
102
|
If you do find any case where you get different results with `summarize(noop: true)`, I'd be grateful if you filed an issue.
|
99
103
|
|
@@ -117,10 +121,10 @@ When the parent relation already has `.group` applied, `pure: true` is implied a
|
|
117
121
|
Build even more complex queries by using `summarize` on a relation that already has `.group` applied. Results are grouped just like a standard `.group(*expressions).count`, but instead of single numbers, the values are whatever set of calculations you return from the block, including further `.group(*more).calculate(:sum|:count,*args)` calculations, in whatever `Array` or `Hash` shape you arrange them. For example:
|
118
122
|
|
119
123
|
```ruby
|
120
|
-
puts Purchase.last_year.complete.group(:region_id).summarize do |purchases,
|
124
|
+
puts Purchase.last_year.complete.group(:region_id).summarize do |purchases,with_resolved|
|
121
125
|
total = purchases.count
|
122
126
|
by_quarter = purchases.group(CREATED_TO_YEAR_SQL, CREATED_TO_QUARTER_SQL).count.sort.to_h
|
123
|
-
target =
|
127
|
+
target = with_resolved[total / 4, by_quarter.values.max] {|avg_q, best_q| [avg_q * 1.25, best_q].max.round }
|
124
128
|
{last_year: total, quarters: by_quarter, unit_target: target}
|
125
129
|
end
|
126
130
|
# Output:
|
@@ -150,13 +154,13 @@ When the relation already has `group` applied, for correct results, `summarize`
|
|
150
154
|
|
151
155
|
```ruby
|
152
156
|
# A trivial example:
|
153
|
-
Purchase.complete.group(:
|
157
|
+
Purchase.complete.group(:region).summarize {|purchases| purchases.sum(:amount) }
|
154
158
|
|
155
159
|
# ...is exactly equivalent to:
|
156
|
-
Purchase.complete.group(:
|
160
|
+
Purchase.complete.group(:region).sum(:amount)
|
157
161
|
|
158
162
|
# But if there were three regions, what should the value of @target be in this case?
|
159
|
-
region_targets = Purchase.last_quarter.complete.group(:
|
163
|
+
region_targets = Purchase.last_quarter.complete.group(:region).summarize do |purchases|
|
160
164
|
@target = purchases.sum(:amount) * 1.25
|
161
165
|
end
|
162
166
|
```
|
@@ -69,19 +69,19 @@ def dashboard
|
|
69
69
|
# If you forget, `daily_posts.popular.count` will raise `Unsummarizable` with a helpful message.
|
70
70
|
all_posts = Post.where(subreddit: @subreddits.select(:id)).where(created_at: 30.days.ago..)
|
71
71
|
.left_joins(:popularity_threshold_setting).order(:created_at)
|
72
|
-
@subreddit_stats = all_posts.group(:subreddit_id).summarize do |posts,
|
72
|
+
@subreddit_stats = all_posts.group(:subreddit_id).summarize do |posts, with_resolved|
|
73
73
|
daily_posts = posts.group("posts.created_at::date")
|
74
74
|
dow_not_burried = posts.where(karma: 0..).group("EXTRACT(DOW FROM posts.created_at)")
|
75
75
|
{
|
76
76
|
posts_created: posts.count,
|
77
77
|
buried_posts: posts.where(karma: ...0).count,
|
78
|
-
daily_popular_rate:
|
78
|
+
daily_popular_rate: with_resolved[
|
79
79
|
daily_posts.popular.count,
|
80
80
|
daily_posts.count
|
81
81
|
] do |popular, total|
|
82
82
|
total.map { |date, count| [date, (popular[date]||0).to_f / count] }.to_h
|
83
83
|
end,
|
84
|
-
dow_avg_comments:
|
84
|
+
dow_avg_comments: with_resolved[
|
85
85
|
dow_not_buried.sum(:comments_count),
|
86
86
|
dow_not_buried.count
|
87
87
|
] do |comments, posts|
|
@@ -94,4 +94,4 @@ end
|
|
94
94
|
|
95
95
|
Since `summarize` runs a single query that visits each relevant `posts` row just once, adding additional calculations is pretty close to free.
|
96
96
|
|
97
|
-
Even with the mental overhead of needing to join outside the block and use `
|
97
|
+
Even with the mental overhead of needing to join outside the block and use `with_resolved` to combine calculations (see [README](../README.md) for details), I think this is still easy to read, write, and reason about, and it beats the heck out of walls of SQL. What do you think?
|
@@ -48,8 +48,8 @@ module ActiveRecord::Summarize
|
|
48
48
|
end
|
49
49
|
|
50
50
|
def process(&block)
|
51
|
-
# For noop, just yield the original relation and a transparent `
|
52
|
-
return yield(@relation, ChainableResult::
|
51
|
+
# For noop, just yield the original relation and a transparent `with_resolved` proc.
|
52
|
+
return yield(@relation, ChainableResult::SYNC_WITH_RESOLVED) if noop?
|
53
53
|
# Within the block, the relation and its future clones intercept calls to
|
54
54
|
# `count` and `sum`, registering them and returning a ChainableResult via
|
55
55
|
# summarize.add_calculation.
|
@@ -60,7 +60,7 @@ module ActiveRecord::Summarize
|
|
60
60
|
include InstanceMethods
|
61
61
|
end
|
62
62
|
end,
|
63
|
-
ChainableResult::
|
63
|
+
ChainableResult::WITH_RESOLVED
|
64
64
|
))
|
65
65
|
ChainableResult.with_cache(!pure?) do
|
66
66
|
# `resolve` builds the single query that answers all collected calculations,
|
data/lib/chainable_result.rb
CHANGED
@@ -12,9 +12,19 @@ class ChainableResult
|
|
12
12
|
if use_cache?
|
13
13
|
return @value if @cached
|
14
14
|
@cached = true
|
15
|
-
@value = resolve_source.send(
|
15
|
+
@value = resolve_source.send(
|
16
|
+
@method,
|
17
|
+
*@args.map(&RESOLVE_ITEM),
|
18
|
+
**@opts.transform_values(&RESOLVE_ITEM),
|
19
|
+
&@block
|
20
|
+
)
|
16
21
|
else
|
17
|
-
resolve_source.send(
|
22
|
+
resolve_source.send(
|
23
|
+
@method,
|
24
|
+
*@args.map(&RESOLVE_ITEM),
|
25
|
+
**@opts.transform_values(&RESOLVE_ITEM),
|
26
|
+
&@block
|
27
|
+
)
|
18
28
|
end
|
19
29
|
end
|
20
30
|
|
@@ -86,8 +96,9 @@ class ChainableResult
|
|
86
96
|
(results.size == 1 ? results.first : results).then(&block)
|
87
97
|
end
|
88
98
|
|
89
|
-
|
90
|
-
|
99
|
+
# Shorter names are deprecated
|
100
|
+
WITH_RESOLVED = WITH = method(:with)
|
101
|
+
SYNC_WITH_RESOLVED = SYNC_WITH = method(:sync_with)
|
91
102
|
|
92
103
|
def self.resolve_item(item)
|
93
104
|
case item
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: activerecord-summarize
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.5.0
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Joshua Paine
|
8
8
|
autorequire:
|
9
9
|
bindir: exe
|
10
10
|
cert_chain: []
|
11
|
-
date: 2023-
|
11
|
+
date: 2023-05-20 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: activerecord
|
@@ -84,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
84
84
|
- !ruby/object:Gem::Version
|
85
85
|
version: '0'
|
86
86
|
requirements: []
|
87
|
-
rubygems_version: 3.3.
|
87
|
+
rubygems_version: 3.3.7
|
88
88
|
signing_key:
|
89
89
|
specification_version: 4
|
90
90
|
summary: Run many .count and/or .sum queries in a single efficient query with minimal
|