In the Rails 3 docs, the build method for associations is described as being the same as the new method, but with the automatic assignment of the foreign key. Straight from the docs:


I've read similar elsewhere.

However, when I use new (e.g. some_firm.clients.new without any parameters), the new client's firm_id association is automatically created. I'm staring at the results right now in the console!

Am I missing something? Are the docs a bit out of date (unlikely)? What's the difference between build and new?

  • 3
    People looking for a quick answer, check the 2nd one down: "build" is just an alias for "new" – ivanreese Jan 21 '16 at 18:28

You're misreading the docs slightly. some_firm.client.new is creating a new Client object from the clients collection, and so it can automatically set the firm_id to some_firm.id, whereas the docs are calling Client.new which has no knowledge of any Firm's id at all, so it needs the firm_id passed to it.

The only difference between some_firm.clients.new and some_firm.clients.build seems to be that build also adds the newly-created client to the clients collection:

henrym:~/testapp$ rails c
Loading development environment (Rails 3.0.4)
r:001 > (some_firm = Firm.new).save # Create and save a new Firm
#=> true 
r:002 > some_firm.clients           # No clients yet
#=> [] 
r:003 > some_firm.clients.new       # Create a new client
#=> #<Client id: nil, firm_id: 1, created_at: nil, updated_at: nil> 
r:004 > some_firm.clients           # Still no clients
#=> [] 
r:005 > some_firm.clients.build     # Create a new client with build
r:006 > some_firm.clients           # New client is added to clients 
#=> [#<Client id: nil, firm_id: 1, created_at: nil, updated_at: nil>] 
r:007 > some_firm.save
#=> true 
r:008 > some_firm.clients           # Saving firm also saves the attached client
#=> [#<Client id: 1, firm_id: 1, created_at: "2011-02-11 00:18:47",
updated_at: "2011-02-11 00:18:47">] 

If you're creating an object through an association, build should be preferred over new as build keeps your in-memory object, some_firm (in this case) in a consistent state even before any objects have been saved to the database.

  • 7
    Using some_firm.client.new also adds the client to some_firm.clients, and calling save on some_firm resulted in a validation error indicating that client was invalid. If both new and build add the new client to some_firm's client collection, what does build do that new doesn't do? I'm sorry for being dense, here! – ClosureCowboy Feb 10 '11 at 14:37
  • 1
    +1 I received your result with 3.0.4. I'd love if someone with 3.0.3 could confirm I'm not crazy. – ClosureCowboy Feb 11 '11 at 1:32
  • 40
    @henrym It looks like in 3.2.6 clients.new and clients.build are similar in they both add the new object into the collection. I wanted to add a comment for anyone who came across this while Googling like I did – hubbard Aug 7 '12 at 4:55
  • 11
    Looks like there is no difference between them in Rails 3.2.3 – Aditya Kapoor Oct 26 '12 at 10:01
  • 4
    This answer is not correct for Rails >3.2.13, where 'build' is just an alias for 'new'. See @HatemMahmoud's answer below. – Andreas Feb 2 '14 at 12:50

build is just an alias for new:

alias build new

Full code can be found: https://github.com/rails/rails/blob/master/activerecord/lib/active_record/relation.rb#L74

  • 13
    alias build new as of rails 3.2.13 – fontno May 13 '13 at 23:06
  • 7
    This is only true of some associations/relations. Singular associations, for example, have entirely different definitions for build and build_#{association}. See here and here. – coreyward Feb 12 '14 at 1:54
  • 1
    Is this still true for Rails 4? – fatman13 Apr 22 '14 at 9:35
  • 2
    @fatman13 Yeah, still true for Rails 4 – Eyeslandic May 29 '14 at 21:30
  • 1
    here is the bug report... which suggests if you were using new like restaurant.customers.new, as a way of getting a new customer associated to restaurant without appending it to restaurant.customers, to use scoped... such as restaurant.customers.scoped.new – user3334690 Aug 20 '14 at 18:15

You are correct, the build and new functions have the same effect of setting the foreign key, when they are called through an association. I believe the reason the documentation is written like this is to clarify that a new Client object is being instantiated, as opposed to a new active record relationship. This is the same effect that calling .new on a class would have in Ruby. That is to say that the documentation is clarifying that calling build on an association is the same is creating a new object (calling .new) and passing the foreign keys to that object. These commands are all equivalent:

Client.new(:firm_id => Firm.first.id)

I believe the reason .build exists is that Firm.first.clients.new might be interpreted to mean that you are creating a new has_many relationship object, rather than an actual client, so calling .build is a way of clarifying this.

  • So they are equivalent. That's definitely what it seems. Thank you! – ClosureCowboy Feb 10 '11 at 14:49
  • 5
    This is not correct. The first two are equivalent in later versions of Rails (looks like at time of posting they were not). BUT, the last one has a significant difference in that Firm.first.clients will not contain the new client. – tybro0103 Feb 3 '14 at 18:29

build vs new:

mostly new and build are same but build stores object in memory,


for new:


For build:


Here clients are stored in memory, when save firm , associated records are also saved.



Tag.new post_id: 1 will instantiate a Tag with its post_id set.


@post.tags.build does the same AND the instantiated Tag will be in @post.tags even before it's saved.

This means @post.save will save both the @post and the newly built tag (assuming :inverse_of is set). This is great because Rails will validate both objects before saving, and neither will be saved if either one of them fails validation.

models.new vs models.build

@post.tags.build and @post.tags.new are equivalent (at least since Rails 3.2).

  • how about this The only difference between some_firm.clients.new and some_firm.clients.build seems to be that build also adds the newly-created client to the clients collection:? – アレックス Feb 2 '15 at 6:49

Your Answer

