feat: document the new BulkLoad streaming API

[Christian d'Heureuse]

The old BulkLoad streaming API and its documentation have been removed (commit, #1307, #1352), but the new API (#1280) has not yet been properly documented.

[Michael Sun]

Hi @chdh , Thanks for bringing this up. We just did read through the doc again and seems the docs have been updated to the new APIs by changes from #1352
For example: under the bulk load page: under the example, instead of calling add rows, it now uses a rows array:

connection.execBulkLoad(bulkLoad, [
  { myInt: 7, myString: 'hello' },
  { myInt: 23, myString: 'world' }
]);

Also, the function declaration has been updated from the connection API page as well.

I am kind of wondering which part of the doc you worried that is not yet been properly documented yet? Can you give us an example or there is some other docs that are outdated and missing this update?

[Christian d'Heureuse]

1. It's not documented how to use BulkLoad with a Stream.
   Instead of an array (or another Iterable), an AsyncIterable (e.g. stream.Readable) can be passed in the rows parameter of connection.execBulkLoad().
   There is no explicit description for the rows parameter.
2. The options parameter is missing in the function signature of connection.newBulkLoad().
   The missing options parameter is documented under usage instead.
3. It's not documented that two kinds of record structures can be used for the rows of the data stream:
   a) Name/value object structure: {columnName1: columnValue1, columnName2: columnValue2, ...}
   b) Array of values: [columnValue1, columnValue2, ...]

Btw: #1307 is still open, but BulkLoad.addRow() and BulkLoad.getRowStream()have been removed in version 14.0.0.

[Michael Sun]

Hi @chdh, we just created a task for adding the missing detail for this new Bulk API. We will also include you in the reviewer list when we actually finish the changes for the doc. Thanks for bringing this up!

[mShan0]

Hi @chdh, we've merged #1429. You can take a look and see if there is anything missing.

[Christian d'Heureuse]

Thanks @mShan0, looks fine.