Add to .forEach documentation how to deal with a iteration that you don't wanna write

[thelinuxlich]

trafficstars

This can happen when you delete with returnChanges = true and expect old_val to have the old data but if two processes are concurrently deleting, one can end with old_val = nil, so the user should know that in this case he needs to return an empty array from forEach.

[AtnNn]

The documentation for forEach could benefit from being more detailed. See https://github.com/rethinkdb/rethinkdb/issues/3798#issuecomment-75135022 and https://github.com/rethinkdb/rethinkdb/issues/3798#issuecomment-75139364

[chipotle]

I see the comment from @atnn that forEach is "a map that combines the results by adding numbers and concatenating arrays," but is that an actual use case for this command that needs to be documented, or is it a kind of quirky byproduct? My impression was that it's really only designed for write queries.

r.table('users').forEach(function (doc) {
  return r.table('foreach').insert({posts: doc('posts')});
})

That appears to return just what you'd expect from inserting n documents.

[danielmewes]

I see it as a by-product, but it would be good to document the exact behavior of the forEach somewhere. There are a few corner cases where these details actually matter, like in @thelinuxlich 's use case.

I don't think we should add any non-write examples though.