Repository navigation
[7/7] Enable insert batching by default - #1634
sreekanth-db wants to merge 5 commits into
Conversation
There was a problem hiding this comment.
Verdict: 1 Low
Clean activation PR — verified the native/legacy routing so enabling both defaults is safe (native prioritized, legacy fallback, no double execution) and the test updates match the new defaults. One low note on the legacy fallback's hardcoded per-row update counts becoming the default behavior. Reminder (already documented by the author): this is intentionally a draft and must not merge until native BINARY parameter support lands on SEA and Thrift.
Scope: reviewed as a stacked increment (07968b8..head); the parent's changes are reviewed on the parent PR.
| "Timeout in seconds for metadata polling operations (e.g. GetTables, GetColumns). 0 means no timeout", | ||
| "300"), | ||
| ENABLE_BATCHED_INSERTS("EnableBatchedInserts", "Enable batched INSERT optimization", "0"), | ||
| ENABLE_BATCHED_INSERTS("EnableBatchedInserts", "Enable batched INSERT optimization", "1"), |
There was a problem hiding this comment.
🔵 Low — Flipping EnableBatchedInserts to 1 by default turns on the legacy client-side multi-row rewrite for the DBR < 18.2 fallback path. Note that this path does not read real per-row update counts from the server — executeBatchedInsert hardcodes allUpdateCounts[i] = 1 for every row (see the loop that sets each chunk's counts). So on the new default, callers that inspect executeBatch() return values will always see 1 per row rather than the actual affected-row count, whereas the previous default (batched inserts off) returned the server's real getUpdateCount() per statement. This is the intended design of the batching feature, but it is a user-visible behavior change worth calling out explicitly in the changelog entry (which currently only describes native batching's parameter/size limits, not the update-count semantics of the legacy fallback).
8cb3849 to
f4e3ff2
Compare
There was a problem hiding this comment.
Verdict: 1 Low
Looks good — a clean activation PR. Default flips (EnableBatchedInserts/EnableNativeBatching → 1), the supportsBatchUpdates() OR of both strategies, and the fake-service opt-out are all correct and covered by the updated unit tests. One low note: the fixture-preserving opt-out is applied only in the two getValidJDBCConnection helpers, not the M2M/Benchfood URL builders (harmless today since those back only auth/metadata replays).
Scope: reviewed as a stacked increment (2d0f4da..head); the parent's changes are reviewed on the parent PR.
| FakeServiceConfigLoader.shouldUseThriftClient()); | ||
| // Existing replay fixtures characterize the previous batching defaults. Batching-specific | ||
| // tests opt in explicitly so activation does not invalidate unrelated recordings. | ||
| connectionProperties.putIfAbsent( |
There was a problem hiding this comment.
🔵 Low — The batching opt-out (ENABLE_NATIVE_BATCHING=0 / ENABLE_BATCHED_INSERTS=0) is applied only in the two getValidJDBCConnection fake-service paths. The other fake-service URL builders (getFakeServiceM2MUrl, getFakeServiceM2MPrivateKeyCredentialsUrl, getFakeServiceBenchfoodJDBCUrl) build connections that now pick up the new default =1 values. Today those entrypoints back only auth and catalog-metadata replay tests (no PreparedStatement INSERT batches), so no recording is invalidated by this change. But if a future replay test that exercises INSERT batching is added on those URLs, it will silently diverge from its recorded fixture because the guard lives in the helper rather than being centralized. Consider centralizing the batching-default pin so every fake-service connection inherits it, rather than duplicating it in two call sites.
|
This final activation PR is the canonical coverage-fan-out trigger for the complete native PreparedStatement batching stack (#1620, #1621, #1623, #1625, #1632, #1633, #1634). Intermediate open PRs are labeled skip-coverage to avoid duplicate fan-outs. After this PR merges, coverage should validate the full user-visible executeBatch flow end to end across supported drivers, with capability skips for drivers that do not expose native batching. |
shiminlin-db
left a comment
There was a problem hiding this comment.
The change itself LGTM overall!
Just some questions about regression prevention. Will be happy to stamp after they're addressed!
| public void supportsBatchUpdates_returnsTrueWhenBatchedInsertsEnabled() throws Exception { | ||
| String urlWithBatchedInserts = WAREHOUSE_JDBC_URL + ";EnableBatchedInserts=1"; | ||
| String urlWithBatchedInserts = | ||
| WAREHOUSE_JDBC_URL + ";EnableNativeBatching=0;EnableBatchedInserts=1"; |
There was a problem hiding this comment.
nit: Can we additionally test that EnableNativeBatching=1;EnableBatchedInserts=1 and EnableNativeBatching=1;EnableBatchedInserts=0 will enable it?
| ## [Unreleased] | ||
|
|
||
| ### Added | ||
| - Added native server-side batching (supported on DBR 18.2 and later) for parameterized `INSERT INTO ... VALUES (?, ...)` statements executed with `PreparedStatement`. The driver sends all parameter sets in one request instead of rewriting INSERT statements on the client. Each batch is limited to 10,000 parameters or 1 MB of parameter data, whichever limit is reached first. Native batching is enabled by default; set `EnableNativeBatching=0` to use legacy batching. `EnableBatchedInserts` now defaults to `1`, enabling client-side batching for compute running DBR versions earlier than 18.2. The `BINARY` data type is not supported in native batching; to batch binary values, set `EnableNativeBatching=0` and `supportManyParameters=1` to use legacy client-side batching. |
There was a problem hiding this comment.
The
BINARYdata type is not supported in native batching; to batch binary values, setEnableNativeBatching=0andsupportManyParameters=1to use legacy client-side batching.
Ah interesting. DBR never supported BINARY parameters, so I didn't realize this would be an issue. However, this does become a regression given that the legacy interpolation batching supported BINARY.
Can we detect BINARY and force interpolation batching?
| | `deletesAreDetected(int)` | YES | - | No | RARE | Returns false | | ||
| | `insertsAreDetected(int)` | YES | - | No | RARE | Returns false | | ||
| | `supportsBatchUpdates()` | YES | - | No | RARE | Returns false | | ||
| | `supportsBatchUpdates()` | YES | - | No | RARE | Returns true when native or legacy batching is enabled | |
There was a problem hiding this comment.
Can we make sure to address the multi-row VALUES clause fallback before this enablement?
f4e3ff2 to
0780bae
Compare
There was a problem hiding this comment.
Verdict: 1 High · 1 Medium · 1 Low
The routing and kill-switch design looks solid, but turning native batching on by default has one high-severity regression. Large batches are not split to respect the documented 10,000-parameter / 1 MB limits and get no fallback, so batches that work today will fail outright after upgrade. There are also two smaller issues: timeout handling closes the statement, and the fallback probe is repeated on every batch call.
| || !nativeExecutor.isSupported()) { | ||
| return legacyExecutor.executeBatch(batchParameterSets); | ||
| } | ||
| try { |
There was a problem hiding this comment.
🟠 High — Native batching is now on by default, but the whole batchParameterSets list goes out in one request. Nothing splits it to stay under the documented 10,000-parameter / 1 MB server limit. When the server rejects an oversized batch (e.g. [PARAMETER_BATCH_ERROR]), the error does not match isUnsupportedNativeBatching, so there is no legacy fallback either. The caller just gets a BatchUpdateException with every entry set to EXECUTE_FAILED.
This breaks existing applications on upgrade. A batch that worked before with the old defaults (one execution per row, or legacy chunking) now fails outright: for example, 4,000 rows × 3 columns is 12,000 parameters, and a few hundred wide rows of strings can exceed 1 MB. The legacy executor already chunks (MAX_QUERY_PARAMETERS / parametersPerRow). The native path should split batchParameterSets into sub-batches that respect both limits and concatenate the update counts. At minimum, it should fall back to legacy when the batch is over the limit. Please also add a unit test for a batch above 10,000 parameters.
(Anchored to the nearest changed line — see the description for the exact location.)
| sql, | ||
| stackTraceMessage, | ||
| getFutureBatchResult(sql, parameterSets, StatementType.UPDATE), | ||
| true); |
There was a problem hiding this comment.
🟡 Medium — executeNativeBatchInternal passes closeStatement=true to waitForExecutionResult. If the native batch hits the query timeout, close() runs on the user's PreparedStatement. The legacy batch paths, which were the default until now, pass false and leave the statement open after a timeout.
The result is a behavior change that comes with the new default: after a batch timeout, a retry, clearBatch() or addBatch() on the same statement throws Statement is closed. Also, executeLargeBatch's clearBatchAfterExecution path is skipped because the exception is wrapped as a BatchUpdateException. Passing false here would match the legacy batch semantics.
| } catch (NativeBatchResultException e) { | ||
| throw e; | ||
| } catch (SQLException e) { | ||
| if (isUnsupportedNativeBatching(e)) { |
There was a problem hiding this comment.
🔵 Low — The [UNBOUND_SQL_PARAMETER] compatibility fallback is not remembered. Every executeBatch() against a backend without native batching first sends the native request, waits for it to fail, and only then runs the legacy rewrite. Thrift reports true for every Warehouse regardless of version, so this can hit every batch call. Consider caching the negative result on the connection or session after the first compatibility failure, so later batches go straight to legacy.
0780bae to
373e228
Compare
There was a problem hiding this comment.
Verdict: 2 Medium · 1 Low
The config flip itself is fine, but turning on both batching strategies by default causes two medium-severity problems for users who never set these properties: wrong partial-failure counts in the legacy rewrite path, and possible failures for BINARY batches on the native path. The fake-service test helper turns batching off by default, so those suites don't exercise the new defaults unless a test opts in.
| "300"), | ||
| ENABLE_BATCHED_INSERTS("EnableBatchedInserts", "Enable batched INSERT optimization", "0"), | ||
| ENABLE_NATIVE_BATCHING("EnableNativeBatching", "Enable native parameter batch execution", "0"), | ||
| ENABLE_BATCHED_INSERTS("EnableBatchedInserts", "Enable batched INSERT optimization", "1"), |
There was a problem hiding this comment.
🟡 Medium — Changing the EnableBatchedInserts default to 1 means every parameterized INSERT batch that does not use native batching (DBR < 18.2, all-purpose clusters, or EnableNativeBatching=0) now goes through the multi-row rewrite by default. Users with the property unset used to get per-statement execution. Two things change for them:
- Wrong counts on partial failure.
executeBatchedInsertruns chunks one after another, each committed as it goes. If any chunk fails, the genericcatch (Exception e)builds afailedCountsarray with every row set toEXECUTE_FAILED, including rows in chunks that already committed. The old default path (executeIndividualStatements) reported which rows succeeded. A client retrying on that report could insert duplicate rows. - Synthesized counts. On success the rewrite returns
1for every row instead of the count the server reports.
Since this is now default behavior, either fill the failedCounts slots for already-executed chunks with 1 (and only mark the failed chunk and later ones as failed), or call out the partial-failure semantics clearly in the changelog. A unit test where the second chunk fails would lock in the intended behavior.
| ENABLE_BATCHED_INSERTS("EnableBatchedInserts", "Enable batched INSERT optimization", "0"), | ||
| ENABLE_NATIVE_BATCHING("EnableNativeBatching", "Enable native parameter batch execution", "0"), | ||
| ENABLE_BATCHED_INSERTS("EnableBatchedInserts", "Enable batched INSERT optimization", "1"), | ||
| ENABLE_NATIVE_BATCHING( |
There was a problem hiding this comment.
🟡 Medium — Turning EnableNativeBatching on by default means existing PreparedStatement INSERT batches that bind byte[]/BINARY values on DBR 18.2+ now go to the native path, which the changelog says does not support BINARY. I found no client-side check that sends binary parameter sets to the legacy executor. PreparedStatementBatchExecutor.executeBatch only falls back on the warehouse UNBOUND_SQL_PARAMETER error, so other server rejections surface as a DatabricksBatchUpdateException. That is a regression for users who batched binary values successfully under the old defaults without setting anything. I didn't trace what the server actually returns, so this needs confirming. Consider detecting byte[] / BINARY bindings in PreparedStatementBatchExecutor and routing those batches to the legacy executor automatically, instead of asking users to set EnableNativeBatching=0.
| ## [Unreleased] | ||
|
|
||
| ### Added | ||
| - Added native server-side batching (supported on DBR 18.2 and later) for parameterized `INSERT INTO ... VALUES (?, ...)` statements executed with `PreparedStatement`. The driver sends all parameter sets in one request instead of rewriting INSERT statements on the client. Each batch is limited to 10,000 parameters or 1 MB of parameter data, whichever limit is reached first. Native batching is enabled by default; set `EnableNativeBatching=0` to use legacy batching. `EnableBatchedInserts` now defaults to `1`, enabling client-side batching for compute running DBR versions earlier than 18.2. The `BINARY` data type is not supported in native batching; to batch binary values, set `EnableNativeBatching=0` and `supportManyParameters=1` to use legacy client-side batching. |
There was a problem hiding this comment.
🔵 Low — This entry is under ### Added, but it also flips the default of an existing property (EnableBatchedInserts 0→1) and changes what supportsBatchUpdates() returns by default. Both are behavior changes for existing users. Consider moving the default flip (and the partial-failure / update-count semantics described in the PR notes) into ### Updated so upgraders notice it.
## 🥞 Stacked PR Use this [link](https://github.com/databricks/databricks-jdbc/pull/1623/files) to review incremental changes. - [**stack/native-batch-routing**](databricks#1623) [[Files changed](https://github.com/databricks/databricks-jdbc/pull/1623/files)] ← _this PR_ - [stack/native-batch-thrift](databricks#1625) [[Files changed](https://github.com/databricks/databricks-jdbc/pull/1625/files/597237e946403890862ba875b54121b489cfec12..b88cd288f12efdd3126506dc37a443dfea7c1842)] - [stack/native-batch-sea](databricks#1632) [[Files changed](https://github.com/databricks/databricks-jdbc/pull/1632/files/b88cd288f12efdd3126506dc37a443dfea7c1842..07f31353e7ff8c94a644c74a4ace3d970dd63bac)] - [stack/native-batch-integration-tests](databricks#1633) [[Files changed](https://github.com/databricks/databricks-jdbc/pull/1633/files/07f31353e7ff8c94a644c74a4ace3d970dd63bac..2d0f4da302b183f15de9804af1c12346b5531bf4)] - [stack/native-batch-activation](databricks#1634) [[Files changed](https://github.com/databricks/databricks-jdbc/pull/1634/files/2d0f4da302b183f15de9804af1c12346b5531bf4..f4e3ff24e5d54451eec9603e429fce7549f291b8)] --------- ## Description Add the left-side capture and routing boundary for native prepared-statement batching. - Snapshot ordered parameter sets when `addBatch()` is called. - Preserve one-based JDBC indexes in the shared model; transport adapters will convert wire ordinals. - Use the same parameter-set model for existing legacy execution. - Add an injectable `NativeBatchExecutor` capability boundary. - Route native-enabled parameterized INSERTs to that boundary when supported. Production still supplies an unsupported native executor, so customer execution remains on the existing legacy path. ## Testing - Focused batch capture, routing, and PreparedStatement tests: 69 passed. - Live serverless warehouse validation passed for individual, parameterized rewrite, and interpolated rewrite flows. - Isaac review completed with zero final findings. ## Additional Notes to the Reviewer This PR does not add a Thrift/SEA native transport implementation, result extraction, fallback, telemetry, or customer-visible behavior changes. NO_CHANGELOG=true --------- Signed-off-by: Sreekanth Vadigi <sreekanth.vadigi@databricks.com>
9fb5f65 to
69036d7
Compare
373e228 to
5ac2812
Compare
There was a problem hiding this comment.
Verdict: 1 Low
Looks good, with one low-severity test gap: no test covers the case where only native batching is turned on. Follow-up worth considering, not caused by this PR: EnableBatchedInserts now defaults to 1, so every user on DBR versions before 18.2 gets the legacy multi-row rewrite. If a later chunk fails there, LegacyPreparedStatementBatchExecutor.executeBatchedInsert marks every row EXECUTE_FAILED, including rows from chunks that already committed. A caller that retries the batch could then insert those rows twice.
| return session.getConnectionContext().isBatchedInsertsEnabled(); | ||
| // Advertise batch support when either native parameter batching or the legacy multi-row | ||
| // optimization is enabled, so batch-aware clients use executeBatch(). | ||
| return session.getConnectionContext().isNativeBatchingEnabled() |
There was a problem hiding this comment.
🔵 Low — The new isNativeBatchingEnabled() || operand has no test of its own. The default test has both flags on, the 'both disabled' test has both off, and returnsTrueWhenBatchedInsertsEnabled uses EnableNativeBatching=0;EnableBatchedInserts=1. No test uses EnableNativeBatching=1;EnableBatchedInserts=0, so if the native check were dropped or broken, all of these tests would still pass. Please add a native-only case that asserts true.
5ac2812 to
e820fb1
Compare
69036d7 to
b200ff9
Compare
There was a problem hiding this comment.
Verdict: 1 Low
Looks good: the default flip, the metadata OR, and the tests are consistent with the routing in PreparedStatementBatchExecutor. One low concern: the changelog doesn't describe how update counts and failure reporting change now that legacy batching is on by default. Nit: the new changelog bullet is followed by a stray blank line that splits the ### Added list.
| ## [Unreleased] | ||
|
|
||
| ### Added | ||
| - Added native server-side batching (supported on DBR 18.2 and later) for parameterized `INSERT INTO ... VALUES (?, ...)` statements executed with `PreparedStatement`. The driver sends all parameter sets in one request instead of rewriting INSERT statements on the client. Each batch is limited to 10,000 parameters or 1 MB of parameter data, whichever limit is reached first. Native batching is enabled by default; set `EnableNativeBatching=0` to use legacy batching. `EnableBatchedInserts` now defaults to `1`, enabling client-side batching for compute running DBR versions earlier than 18.2. The `BINARY` data type is not supported in native batching; to batch binary values, set `EnableNativeBatching=0` and `supportManyParameters=1` to use legacy client-side batching. |
There was a problem hiding this comment.
🔵 Low — Turning EnableBatchedInserts on by default changes what users get back from executeBatch() on the legacy path (DBR < 18.2, or EnableNativeBatching=0). Before this change, each parameter set ran on its own: executeBatch() returned the server's real getUpdateCount() for each row, and on failure BatchUpdateException.getUpdateCounts() kept the counts of the rows that had already succeeded. With the rewrite on by default:
- every row in a successful chunk is reported as
1(lines 146-149); - any failure marks all rows
EXECUTE_FAILED(lines 156-165), even rows in earlier chunks that were already committed.
The PR description mentions the first point, but the changelog entry doesn't mention either one. Users whose code checks update counts, or retries based on per-row failure status, will see different results after upgrading. Please add a sentence to the entry describing both changes and noting that EnableBatchedInserts=0 restores per-statement counts.
Record real SEA and Thrift responses to guard native parameter batching end to end. Signed-off-by: Sreekanth Vadigi <sreekanth.vadigi@databricks.com>
Validate exact parameter values and array order so replay coverage detects reordered native batches. Signed-off-by: Sreekanth Vadigi <sreekanth.vadigi@databricks.com>
Signed-off-by: Sreekanth Vadigi <sreekanth.vadigi@databricks.com>
Activate native server-side batching while enabling the legacy rewrite fallback for older compute, with explicit kill switches for both paths. Signed-off-by: Sreekanth Vadigi <sreekanth.vadigi@databricks.com>
Document the DBR version requirement, backend limits, and legacy configuration for binary batches. Signed-off-by: Sreekanth Vadigi <sreekanth.vadigi@databricks.com>
b200ff9 to
7437989
Compare
e820fb1 to
0c01c18
Compare
🥞 Stacked PR
Description
PreparedStatementINSERT batches on DBR 18.2 and later.EnableNativeBatching=0andEnableBatchedInserts=0as independent kill switches.BINARYlimitation.Testing
Additional Notes to the Reviewer
BINARYvalues. Binary batches must use legacy client-side batching withEnableNativeBatching=0andsupportManyParameters=1(EnableBatchedInsertsdefaults to1).1for each submitted row because the backend returns a count for the combined multi-row statement rather than separate per-row counts.