Implement Session::insert

[Lorak-mmk]

After our paging API refactor there are now 3 main request execution methods on Session:

• execute_unpaged
• execute_single_page
• execute_iter

This distinction makes sense for SELECT requests, where the type of paging is something important to consider.

There is unfortunately an ergonomics problem: when INSERTing / UPDATing data paging has no relevance at all, but the user has to choose one of the above methods anyway - usually execute_unpaged. This does not look nice in the code.

We could improve this by adding Session::insert, which would return error if the received response contains rows.

LWT Inserts

There is one problem: What about LWT inserts? They do return rows, so it would not be possible to execute them using this new method.
We could allow rows response for insert if PreparedStatement::is_confirmed_lwt is true. This would only work for Scylla - Cassandra does not have this extension. This would unfortunately cause insert to also allow LWT SELECTs. I don't see a good solution here, unless we want to do some heuristic statement parsing.

Maybe allowing LWT SELECTs is acceptable? Do those even support paging?

Naming

execute_insert vs insert: I'd strongly favor the latter because of ergonomics. I don't think we need similar method for unprepared statements, so there should be no need for execute_ prefix.

[wprzytula]

1. As you once stated @Lorak-mmk (while we were discussing Implement ?fields for deriving column names from a custom struct #1006), the driver is not an ORM layer and thus it should expose a moderately low-level API to execute CQL statements.
   Keeping in mind that the central assumption that the driver does not parse CQL statements, it believe it should remain statement content-agnostic. Therefore, it should remain the user's responsibility to choose the correct execution method.

2. Are you sure that execute_unpaged() is the way we should always execute INSERTs underneath? No doubt?

3. I don't think we need similar method for unprepared statements

   Why??? I don't see a reason to introduce such asymmetry between prepared and unprepared statements.

[wprzytula]

Also, if you suggest introducing an insert() method, I don't see why this one should be added alone. Together with it, I believe we should bring:

• select_unpaged() (with a huge warning on it)
• select_iter[_pages]()
• select_single_page()
• update()
• truncate()
• schema_modification() (or even split it into various kinds of schema modification)
• probably more, which I can't think of ATM.

In other words, why have a special case just for INSERTs?
I don't think we should go this way.

[Lorak-mmk]

1. As you once stated @Lorak-mmk (while we were discussing Implement ?fields for deriving column names from a custom struct #1006), the driver is not an ORM layer and thus it should expose a moderately low-level API to execute CQL statements.
   Keeping in mind that the central assumption that the driver does not parse CQL statements, it believe it should remain statement content-agnostic. Therefore, it should remain the user's responsibility to choose the correct execution method.

And I still think that we should not parse statements. I did mention this possibility, but I'm not in favor of it. However, the type of the response (rows vs void etc) is something present at the protocol level, so it has nothing to do with parsing strings.

2. Are you sure that `execute_unpaged()` is the way we should always execute INSERTs underneath? No doubt?

INSERTs and UPDATEs, yes

   Why??? I don't see a reason to introduce such asymmetry between prepared and unprepared statements.

Unprepared statements are only for one-off requests, usually DDL. We don't need to have a functionality parity between recommended way to make normal requests, and the discouraged one.
Note that what I'm proposing is not something unachievable in the user code with the current APIs - it is merely a matter of convenience. Don't you agree that making the indended way more convenient is a good thing?

Also, if you suggest introducing an insert() method, I don't see why this one should be added alone. Together with it, I believe we should bring:

* `select_unpaged()` (with a huge warning on it)

* `select_iter[_pages]()`

* `select_single_page()`

execute_* methods are perfectly fine for SELECTs. Those methods are however very weird to use with INSERTs / UPDATEs however, that's why I proposed this convenience method.

* `update()`

insert method covers UPDATEs too. Also there is no way to distinguish them at the protocol level from inserts, so I don't see how you would like to implement that.

* `truncate()`

Again, no way to distinguish at the protocol level afaik.

* `schema_modification()` (or even split it into various kinds of schema modification)

That could possibly make sense (apart from the part about various kinds). It would cover the biggest use case for unprepared statements, which could allow us to get rid of them in the future.
However the difference from what I'm proposing is the very reason I proposed insert: convenience.
DDLs are very rare in the application code compared to data requests. New method for DDLs is not very beneficial. New method for INSERT / UPDATE is, because it gets rid of those ugly execute_unpaged that make no sense with upsert requests.

* probably more, which I can't think of ATM.

In other words, why have a special case just for INSERTs? I don't think we should go this way.

Because applications will have a lot of those calls, and the paging method is not relevant for them, so it makes sense to expose easier to use API.

[Lorak-mmk]

We could name it write so that the name covers UPDATE too, and make it just work with requests returning VOID response. LWT are not just writes - they read the data, check conditions and then write back - so it makes sense to not allow them.

[wprzytula]

And I still think that we should not parse statements. I did mention this possibility, but I'm not in favor of it. However, the type of the response (rows vs void etc) is something present at the protocol level, so it has nothing to do with parsing strings.

Just as you pointed out (LWTs), there is no strict relationship between what requests should be paged and what requests return RESULT::Rows. That's one of my counterarguments.

insert method covers UPDATEs too.

This is extremely unintuitive. You call a method as one of the CQL statements (INSERT), and then you say that it accepts INSERTs and also UPDATEs. Why not insert_or_update() then?
Moreover, you do not propose to introduce equivalent select[_*]() methods. As a user, I'd be utterly lost (I just imagined it in some typical SQL driver) if I saw just an insert() method without accompanying methods for other kinds of statements.

upsert requests

I wasn't aware that such name really exist in the DB world. Maybe this should be the name of the method you're suggesting?

To sum up:

If we introduce the upsert method:

• with the "empty result" assertion, then we end up with a heuristic that does not work in a significant subset of cases (LWTs). I've thought we are not into entering the waters of such leaky heuristics. At least I am not into them.
• without the "empty result" assertion, I don't see how the only benefit (no "ugliness" that you mention) outweigh the mental cost (confusion) that the users will pay for having a strange special-case method just for the insert (and maybe update? depending on naming) case.

[Lorak-mmk]

Just as you pointed out (LWTs), there is no strict relationship between what requests should be paged and what requests return RESULT::Rows. That's one of my counterarguments.

WDYM? Paging makes no sense for INSERT and UPDATE, no matter if they are LWT or not.

This is extremely unintuitive.

We could name it write or upsert.

with the "empty result" assertion, then we end up with a heuristic that does not work in a significant subset of cases (LWTs). I've thought we are not into entering the waters of such leaky heuristics. At least I am not into them.

As I mentioned in my second comment, LWT INSERT / LWT UPDATE is not just a write - so it makes sense to not allow them in such method.

As a user, I'd be utterly lost (I just imagined it in some typical SQL driver) if I saw just an insert() method without accompanying methods for other kinds of statements.

In that case it is great that we have documentation, so we can guide users to correct methods in the Session API doc!
Also I imagine the typical user flow more like this:

For SELECT:

• How do I SELECT data with this driver?
• Ah, there are execute_* methods, similarly to most database drivers in existence. But why are there 3 of them, wtf?
• < Reads about the difference, chooses the appropriate one >
• < Continues to code happily >

For INSERT / UPDATE:

• How do I insert data?
• Ah, there are execute_* methods. But why are there 3 of them, wtf?
• < Reads about the difference >
• < Learns from the docs that execute_unpaged is the correct one here, and uses it >
• [Optional] < Notices in the docs for execute_unpaged / Session we recommend insert for this, and uses this, improving the code >

The only case where this change causes problems, is a user that:

• Looks through the whole Session API before using execute.
• But is not capable of reading the docs.

I suspect that it is a very rare case.