As documented in https://www.mongodb.com/docs/mongoid/master/reference/crud/, Model#upsert actually performs replace_one and not update_one as one might expect.

Changing this behavior is a BC break.

AR has upsert & upsert_all as of 6.0: https://edgeapi.rubyonrails.org/classes/ActiveRecord/Persistence/ClassMethods.html#method-i-upsert_all. The documentation appears to imply that the behavior is an update with upsert rather than replacement with upsert.

Todo:
add :replace option, with default being false in 9.0
test :replace option
add release notes in 8.1 for adding the flag
add release notes in 9.0 for flipping the flag
update the documentation for upsert
update the default in 8.1
update the default tests in 8.1
change all the doc(string)s for 8.1

Open question:

I filed MONGOID-5512 to add the upsert_all method, should that one be done for 9.0 so that we dont have to deal with switching the default on a potential replace option? Should we put in 8.1 and have default inconsistencies across the methods? Or should we change defaults in the next major version?