apache / apache/tsfile

More docs for Java examples?

Open
#795 0 comments 2 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
203
Forks
104
Avg merge
2d 6h
Merged PRs (30d)
33

Description

The Java examples are poorly documented. The only page mentioning the examples is the [QuickStart](https://tsfile.apache.org/zh/UserGuide/latest/QuickStart/QuickStart.html) tutorial. I encountered a few questions while studying the examples:

First, how to run the examples? I cloned the repository and built the Java packages, but can't figure out how to run the examples. Copilot gave me the following command:

```
$ ./mvnw -f java/examples/pom.xml -DskipTests exec:java -Dexec.mainClass=org.apache.tsfile.XXX
```

Is this correct?

Second, what are the functions of each example? The only two examples mentioned by QuickStart are `org.apache.tsfile.v4.WriteTabletWithITsFileWriter` (for writing TsFiles) and `org.apache.tsfile.v4.ITsFileReaderAndITsFileWriter` (for reading and writing TsFiles), and it seems that the former one is just a subset of the latter one. Besides, both of them are prefixed with `v4`. This is confusing because TsFile Java only has v1 and v2. What does v4 stand for? Does that mean that examples outside the `v4` package are outdated?

Finally, I stumbled upon the [TsFile API](https://tsfile.apache.org/zh/stage/QuickStart.html) page, which doesn't have any backlinks. I noticed that it is under the "stage" directory, is it a "staging" page? Will it be published one day?

Above all, could you please provide more docs for the Java examples?

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the QuickStart page, java/examples/pom.xml, and the example classes named in the issue, including the org.apache.tsfile.v4 examples. Document how to run the Java examples, explain each example and the v4 naming, and clarify the status of the TsFile API page under stage; done means these questions are answered in discoverable documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.