Logstash elasticsearch output plugin Document_id and Upserts

Question, does a customized document_id require an upsert to update the document or can this be accomplished with just the document_id? I've read that upserts are used if you want create a new document if the document does not exist, but I'm not sure if I'm clear on how it works.

By default (action => index), if you write a document to elasticsearch with a custom id and a document with that id already exists, then it is completely replaced by the new document.

If you set the action option to update, then if the document already exists, it is updated with fields from the event (and if it does not exist then an error is returned).

If you enable upsert then if an update is sent for a document that does not exists then elasticsearch creates it.

Does that help? If you want more detail it might be better to move this to the elasticsearch forum, since it is really a question about the Bulk API, not logstash.