[shuwenwei]

Description

COPY TO TsFile currently fails when a SQL query returns timestamps out of order within a target device, for example with ORDER BY time DESC. Add an outer sort by the target TAG columns and TIME after planning the complete inner query, so existing optimizers can use streaming scans, eliminate redundant sorts, and merge ordered region results. The inner query's ORDER BY, LIMIT, and OFFSET semantics are preserved.

Both table shorthand and SQL query exports use this path. Exports with generated timestamps retain their existing behavior, and duplicate timestamps for the same target device remain subject to TsFile writer validation. No SQL option is added.

Support EXPLAIN COPY ... TO ... and EXPLAIN ANALYZE COPY ... TO ... for both table shorthand and SQL query exports. EXPLAIN displays the export plan without creating a file. EXPLAIN ANALYZE executes the export, creates the TsFile, and returns runtime statistics for the scan and COPY TO operators. Existing output formats and VERBOSE are supported where applicable. Preserve the inner query headers and export summary symbols through optimization and distributed planning.

Normalize IOException failures during target-file creation and writer initialization to COPY_TO_WRITE_ERROR (725), matching existing write and seal failures and preserving the concrete error message, such as an existing target file, during cascading task failure.

Validation

• Add planner unit tests covering COPY TO entry points, streaming sort and distributed merge, TopK with OFFSET, aliases and target TAG order, and generated timestamps.
• Add five integration tests covering descending timestamps, field-based ordering, LIMIT/OFFSET, aliased TIME with reordered TAGs, and exports without TAGs. Read back all exported rows and check increasing timestamps per device; use small TsBlocks to exercise multiple batches.
• Set MEMORY_THRESHOLD 1000000 for the new integration cases, matching existing COPY TO tests.
• The five unordered-result integration tests passed according to the user's local validation.
• Add four integration tests for EXPLAIN and EXPLAIN ANALYZE, covering table shorthand, explicit columns, SQL queries, text/JSON output, and VERBOSE. Check that the returned output contains TableScan and CopyTo; use MEMORY_THRESHOLD 1000000 and clean up temporary export files.
• The EXPLAIN/ANALYZE integration tests and writer-initialization error handling have not been run or compiled by the agent. No formatting checks were run.

This PR has:

• been self-reviewed.
• added unit tests.
• added integration tests.

[codecov]

Codecov Report

❌ Patch coverage is 47.61905% with 44 lines in your changes missing coverage. Please review.
✅ Project coverage is 46.85%. Comparing base (f028736) to head (f1ec16b).
⚠️ Report is 11 commits behind head on master.

Files with missing lines	Patch %	Lines
...ngine/plan/planner/plan/node/PlanGraphPrinter.java	0.00%	24 Missing ⚠️
...e/plan/planner/plan/node/PlanGraphJsonPrinter.java	12.50%	7 Missing ⚠️
...n/operator/process/copyto/TableCopyToOperator.java	0.00%	4 Missing ⚠️
...yengine/plan/relational/sql/parser/AstBuilder.java	0.00%	4 Missing ⚠️
...ne/plan/relational/analyzer/StatementAnalyzer.java	50.00%	3 Missing ⚠️
...e/plan/relational/planner/TableLogicalPlanner.java	93.93%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #18928      +/-   ##
============================================
+ Coverage     46.42%   46.85%   +0.43%     
  Complexity      713      713              
============================================
  Files          5537     5537              
  Lines        404332   404719     +387     
  Branches      52852    52915      +63     
============================================
+ Hits         187717   189647    +1930     
+ Misses       216615   215072    -1543     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[JackieTien97]

Requesting changes for the reproducible no-FROM COPY regression and the stale EXPLAIN error-message assertions that already fail CI.

Validation: a clean reactor run of OrderingPropertyPropagationTest (25 tests passed), a clean TableClusterIT run of IoTDBCopyToTsFileIT (27 tests passed on 1C3D), and targeted live 1C1D probes.

[JackieTien97]

Both previously reported issues are fixed in 600ba96.

Revalidated with a clean reactor build: all 26 OrderingPropertyPropagationTest tests and the two targeted integration tests passed, including IoTDBInsertQueryIT.testExplain. Six live 1C1D checks also passed, covering constant-query COPY, EXPLAIN and EXPLAIN ANALYZE in text/JSON formats, exported-file readback, expected file-creation behavior, and missing TIME-column validation.

No remaining blocking findings from this review.