[Docs][HTTP] Clarify when to use batch-at-a-time vs. one-shot approach for receiving data

[ianmcook]

Describe the usage question you have. Please include as many useful details as possible.

Among the simple HTTP GET client examples in arrow-experiments/http/get_simple:

• Some iterate over the record batches as they stream in from the server (i.e. "streaming" approach).
• Some just make a single function call that collects the full data (i.e. "one-shot" approach).

For example:

• The Python client example shows how to iterate over the batches calling reader.read_next_batch(), whereas it could have just called reader.read_all() which would be simpler.
• The Ruby client example goes for the simpler all-at-once approach, whereas it could have used a batch-at-a-time approach like in this example.

For many use cases, it makes no difference which approach is used, and we should just prioritize whatever is syntactically simplest.

But for some use cases, the batch-at-a-time approach will be preferred or needed for specific reasons, such as:

• The receiver wants to start processing batches before the final batch is received.
• The receiver wants to stream the received data to a sink without accumulating it in memory.

We should clarify this in the Arrow-over-HTTP conventions doc, and wherever possible we should provide examples showing both approaches.

Component(s)

Documentation

[felipecrv]

It depends on what the client is going to do with the data. I think showing that data can be loaded batch by batch is more interesting. It's a streaming protocol after all.

A client performing some kind of aggregation can go through the batches updating its state and finalizing when all batches are read (e.g. calculating some weighted average on the stream).

People naturally tend to write code that buffers everything, so having the examples showing that batch-by-batch is possible only helps.

[thisisnic]

This issue has been marked as stale because it has had no activity in the past 365 days. Please remove the stale label or comment below, or this issue will be closed in 14 days. If this usage question has evolved into a feature request or docs update, please remove the 'Type: usage' label and add the 'Type: enhancement' label instead.