Add the user and migration guides and correct two stale API descriptions - #119
Merged
Merged
Conversation
Add docs/user-guide.md and docs/migration-guide.md for the IoTDB Table Mode ThingsBoard backend: how each of the three storage paths is activated, the configuration reference, schema and bootstrap behaviour, retention, and what a migration from an existing ThingsBoard backend does and does not carry over. Writing them surfaced two descriptions that no longer match the code. The experimentalRawOnly javadoc still said time-bucketed aggregation was outside the module's scope. Aggregation has been implemented since the date_bin and calendar-bucket read paths landed, so the flag now describes what it actually gates, why the name predates that support, and why it is still marked experimental. The user guide's unsupported-operations section said the batch latest read throws UnsupportedOperationException. It does not: findLatestByEntityIds and its async twin return empty, deliberately, because they back the includeSamples branch of the entity-query keys endpoint where a synchronous throw would surface as an HTTP 500 -- the same choice CassandraBaseTimeseriesLatestDao makes. findNextBatch is the only method in the module that throws, and that half of the sentence was correct. Also drops a comment reference to a document outside this repository from IoTDBTableTimeseriesDao. Signed-off-by: Zihan Dai <99155080+PDGGK@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the user and migration guides for the IoTDB Table Mode ThingsBoard backend, and corrects two descriptions that no longer match the code.
Docs
docs/user-guide.md— activation selectors for each of the three storage paths, what each DAO implements, schema and bootstrap behaviour, retention/TTL, the configuration reference, and the known limitations.docs/migration-guide.md— what a migration from an existing ThingsBoard backend carries over and what it does not, and the operational steps.Two corrections
Writing the guides surfaced two places where the shipped description had fallen behind the implementation.
1.
IoTDBTableConfig.Ts#experimentalRawOnlyjavadoc. It still read "This backend currently implements write, raw read, and delete only; time-bucketed aggregation is outside the current scope." Time-bucketed aggregation has been implemented since thedate_binand calendar-bucket read paths landed in #115, so the javadoc now describes what the flag actually gates, notes that the property name predates the aggregation support and is kept for compatibility, and states the Phase-1 relaxation that is the real reason it stays experimental.2. The unsupported-operations description. The guide's first draft said the batch latest read throws
UnsupportedOperationException. It does not —findLatestByEntityIdsandfindLatestByEntityIdsAsyncreturn empty deliberately, because they back theincludeSamplesbranch ofPOST /api/entitiesQuery/find/keys, where a synchronous throw would surface as an HTTP 500. That mirrorsCassandraBaseTimeseriesLatestDao.findNextBatchis the only method in the module that throws, and that half of the statement was correct; the two are now stated separately.Also drops a comment reference in
IoTDBTableTimeseriesDaopointing at a document outside this repository.Scope
Documentation and comments only — no behaviour change, no new dependency.
mvn -P with-thingsboard -pl iotdb-thingsboard-table spotless:check test-compilepasses.The ingestion-throughput benchmark from the same work is held back as a separate change so this one stays cheap to review.