[CASSANDRA-14478] Improve the documentation of UPDATE vs INSERT

• Type: Improvement
• Status: Open
• Priority: Low
• Resolution: Unresolved
• Component/s: Legacy/Documentation and Website
• Assignee: Unassigned
• Reporter: Nadav Har'El
• Created: 30/May/18 07:46
• Updated: 16/Apr/19 09:29

Description

New Cassandra users often wonder about the difference between the INSERT and UPDATE cql commands when applied to ordinary data (not counters or transactions). Usually, they are told them that there is really no difference between the two - both of them can insert a new row or update an existing one.

The Cassandra CQL documentation http://cassandra.apache.org/doc/latest/cql/dml.html#update

is fairly silent on the question - on the one hand it doesn't explicitly say they are the same, but on the other hand describes them both as doing the same things, and doesn't explicitly mention any difference.

 

But there is an important difference, which was raised in the past in CASSANDRA-11805: INSERT adds a row marker, while UPDATE does not. What does this mean? Basically an UPDATE requests that individual cells of the row be added, but not that the row itself be added; So if one later deletes the same individual cells with DELETE, the entire row goes away. However, an "INSERT" not only adds the cells, it also requests that the row be added (this is implemented via a "row marker"). So if later all the row's individual cells are deleted, an empty row remains behind (i.e., the primary of the row which now has no content is still remembered in the table). 

I'm not sure what is the best way to explain this, but what I wrote in the paragraph above is a start.

Issue Links

• relates to: CASSANDRA-14505 Removal of last element on a List deletes the entire row