Fix Version/s: None
Component/s: Legacy/Documentation and Website
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.