[PECO-1263] Implement a .returned_as_direct_result property for AsyncExecution status

[susodapop]

Description

This PR implements an additional boolean flag on AsyncExecution that indicates whether this execution returned directResults. When this happens, results cannot be fetched from the server again. Because when a directResults query returns its operation is closed immediately.

I determined this is necessary while documenting the new execute_async() behaviour. For context, when we send a TExecuteStatementReq to the thrift server, there are two possible return conditions:

1. If the query completes within five seconds, the resulting TExecuteStatementResp will actually include the results!
2. If the query takes longer than five seconds to complete, the resulting TExecuteStatementResp will only include the query_id for the query, which we can use to poll for the results until they are ready.

In case 1, the result is sent within the initial TExecuteStatementResp and they cannot be fetched a second time. What this means for users is that if they are going to call .serialize() to persist a query_id and secret for use by another thread, they need a way to verify that the results will actually be available to another thread.

This new .returned_as_direct_result property makes that easier.

One unfortunate implication of this behaviour is that users cannot use one thread to kickoff all their queries and a separate thread to fetch their results. Because not all AsyncExecution objects can actually be picked up separately.

[benc-db]

If the query completes within five seconds, the resulting TExecuteStatementResp will actually include the results!
If the query takes longer than five seconds to complete, the resulting TExecuteStatementResp will only include the query_id for the query, which we can use to poll for the results until they are ready.

Oh man, why? This is really unfortunate behavior.

[benc-db]

How long is it available for? How does this limitation work in the CUJ of recovering from a user-space crash?

[susodapop]

I'm going to check with the thrift server folks to get that answer. I believe it's available for a few hours. With cloud fetch enabled it's 24 hours.

What do you think of the name is_available? I'd like a name that's reflective but also easy enough to type.

[benc-db]

Its really a tough one; I think this might be a little misleading, because isn't the answer 'Unknown' for crash recovery CUJ?

[susodapop]

I don't think so. Because under this situation, if the client crashes it will do so before the query_id is returned. Which means there would be no way to pick up the execution anyway.

[benc-db]

Ah, so if it gets a query_id, then it must be available, unless its been a long time? Although, again, available doesn't sound quite right because the query could still be executing. Maybe just returned_as_direct_result?

[susodapop]

Good idea. I've done the rename and pushed.

Note: we could get around this by allowing users to disable directResults when the TExecuteStatementReq is emitted.

[jadewang-db]

is really unfortunate behavior.

will this cause any issues?

[benc-db]

is really unfortunate behavior.

will this cause any issues?

Jade, this is the issue:

In case 1, the result is sent within the initial TExecuteStatementResp and they cannot be fetched a second time. What this means for users is that if they are going to call .serialize() to persist a query_id and secret for use by another thread, they need a way to verify that the results will actually be available to another thread.

[jadewang-db]

do we need change get_result method to also check this flag?