hongzhi-gao opened a new pull request, #19308:
URL: https://github.com/apache/iotdb/pull/19308
## Description
Existing tree-model test insertion APIs only acknowledge reception by the
server. This PR adds explicit completion stages so callers can exercise
decoding, read-only analysis, distributed planning, and delivery to write
targets without inserting data or changing metadata.
### Public Java APIs
Add eight stage-aware overloads to `ISession` / `Session`:
- `testInsertTablet(Tablet, TestInsertStage)` and `testInsertTablet(Tablet,
boolean sorted, TestInsertStage)`.
- `testInsertTablets(Map<String, Tablet>, TestInsertStage)` and the overload
with `boolean sorted`.
- `testInsertRecord` with a trailing `TestInsertStage`, for both string
values and explicit data types/values.
- `testInsertRecords` with a trailing `TestInsertStage`, for both batched
string values and explicit data types/values.
Add `ITableSession.testInsert(Tablet)` and `ITableSession.testInsert(Tablet,
TestInsertStage)`, implemented by `TableSession` and pooled table sessions. The
default table overload stops at `UNTIL_RPC_PROCESSED`.
`Session.testInsertRelationalTablet(Tablet, TestInsertStage)` provides the
underlying table-model implementation. Existing tree-model overloads retain
their behavior.
### Completion boundaries
| Stage | Acknowledged work |
| --- | --- |
| `UNTIL_RPC_PROCESSED` | Login, stage and payload-count checks; no
Statement decoding |
| `UNTIL_DECODED` | Insertion payload decoded into a Statement |
| `UNTIL_ANALYZED` | Read-only analysis completed |
| `UNTIL_PLANNED` | Logical and distributed plans generated |
| `UNTIL_WRITE_TARGET_RECEIVED` | All plan targets have deserialized their
plans and checked the insertion plan type and target DataRegion existence |
For example, given an existing table/device, unchanged attributes and a data
partition covering the tablet timestamps:
```java
// Only acknowledge reception.
tableSession.testInsert(tablet);
// Complete distributed planning without inserting any rows.
tableSession.testInsert(tablet, TestInsertStage.UNTIL_PLANNED);
// Deliver and check all target plans without executing writes.
tableSession.testInsert(tablet, TestInsertStage.UNTIL_WRITE_TARGET_RECEIVED);
```
Queries return the same rows after each call. If analysis would require a
new device, an attribute update, schema creation, or a new data partition,
analysis and later stages fail instead of performing that change.
### Execution and compatibility
- Add client RPC `testInsert(TSTestInsertReq)`, response `TSTestInsertResp`,
and `TestInsertStage`.
- Add internal RPC `testInsertPlanNodes(TSendBatchPlanNodeReq)` for target
validation. Separate RPCs prevent older nodes from silently ignoring a test
flag and executing a write.
- Check the acknowledged stage on the client. An unsupported server fails
explicitly; there is no fallback to normal insertion.
- Reuse the tree/table planners while guarding metadata mutation paths and
using read-only partition lookup.
- Never enter trigger, consensus, WAL or storage write execution. Release
frontend memory reservations and schema read locks in `finally`.
- Preserve upstream pool synchronization and close handling; connection
failures discard the session, while statement failures allow reuse.
- Localize new diagnostics in English and Chinese and clarify the documented
stage prerequisites.
Targets are checked sequentially. This API does not establish WAL
durability, replication success, or production write-throughput performance.
### Validation
Verified on the changes based on `ad0900813f` (2.0.11-SNAPSHOT):
- English and Chinese full-reactor test compilation passed.
- 157 focused unit tests passed: `SessionTest` (99), `SessionConnectionTest`
(36), `TableSessionTest` (1), `TableSessionWrapperTest` (3),
`SessionPoolCloseTest` (17), and `TestInsertPlanValidatorTest` (1).
- All four `IoTDBStagedTestInsertIT` cases passed on both 1 ConfigNode + 1
DataNode and 1 ConfigNode + 3 DataNodes, with no failures, errors or skips.
Coverage includes quoted measurement names, multiple databases/regions, missing
metadata/partitions, template activation/extension, table device/attribute
preservation, and pooled sessions.
- The unsupported-server unit case also passed under `with-zh-locale`.
- Formatting, Checkstyle, dependency/license checks in `verify`, IT
selection checks, added-message locale parity checks and `git diff --check`
passed.
<details>
<summary>Executed build and test commands</summary>
```bash
mvn test-compile -DskipTests -Pwith-integration-tests -Ddevelocity.off=true
mvn verify -o -pl integration-test -am -Pwith-integration-tests,ClusterIT \
-Dtest=SessionTest,SessionConnectionTest,TableSessionTest,TableSessionWrapperTest,SessionPoolCloseTest,TestInsertPlanValidatorTest
\
-Dsurefire.failIfNoSpecifiedTests=false -Dit.test=IoTDBStagedTestInsertIT \
-DfailIfNoTests=false -Dfailsafe.failIfNoSpecifiedTests=false
-Ddevelocity.off=true
mvn verify -o -pl integration-test -am -Pwith-integration-tests,SimpleIT
-DskipUTs=true \
-Dtest=SessionTest,SessionConnectionTest,TableSessionTest,TableSessionWrapperTest,SessionPoolCloseTest,TestInsertPlanValidatorTest
\
-Dsurefire.failIfNoSpecifiedTests=false -Dit.test=IoTDBStagedTestInsertIT \
-DfailIfNoTests=false -Dfailsafe.failIfNoSpecifiedTests=false
-Ddevelocity.off=true
mvn test-compile -o -DskipTests -Pwith-integration-tests,with-zh-locale
-Ddevelocity.off=true
mvn test -o -pl iotdb-client/session -am -Pwith-zh-locale \
'-Dtest=SessionConnectionTest#testOldServerRejectsStagedInsertionWithoutFallback'
\
-Dsurefire.failIfNoSpecifiedTests=false -DfailIfNoTests=false
-Ddevelocity.off=true
python3 .github/scripts/check-it-selection.py
git diff --cached --check
```
</details>
No live mixed-version cluster, remote-node fault injection, or performance
benchmark was run.
### Review
Independent source review covered metadata mutation paths, partition lookup,
target validation, memory/lock cleanup and pool synchronization. A
locale-dependent assertion was corrected to use the localized message constant.
This PR has:
- [x] been self-reviewed and independently reviewed.
- [x] documented the new APIs and stage boundaries.
- [x] added unit tests and integration tests.
- [x] been tested in a test IoTDB cluster.
### Key changed classes
`ISession`, `ITableSession`, `Session`, `SessionConnection`, `TableSession`,
`TableSessionWrapper`, `ClientRPCServiceImpl`, `Coordinator`,
`MPPQueryContext`, `ClusterPartitionFetcher`, schema validators and
`TestInsertPlanValidator`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]