CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Apache TsFile is a columnar storage file format designed for time series data. The project provides implementations in three languages, each in its own top-level directory. The main branch is develop.

TsFile uses a hierarchical storage model: Page → Chunk → ChunkGroup → File. Data is organized by device, with each device's measurements stored as individual time series. Two write models exist: aligned (all measurements share timestamps) and non-aligned (independent timestamps per measurement).

Repository Structure

DirectoryLanguageBuild SystemDetails
java/JavaMavenjava/CLAUDE.md
cpp/C++CMakecpp/CLAUDE.md
python/Pythonsetuptools + Cythonpython/CLAUDE.md

The root pom.xml orchestrates all three via Maven profiles:

./mvnw clean verify -P with-java       # Java only
./mvnw clean verify -P with-cpp        # C++ only
./mvnw clean verify -P with-python     # Python (requires C++ built first)

Cross-Module Dependencies

  • Python depends on C++: The Python module uses Cython to bind to the C++ shared library (libtsfile). C++ must be built before Python (-P with-python implies C++ build).
  • Java is independent: The Java implementation shares no build-time dependency with C++ or Python.
  • All three implementations read/write the same TsFile binary format.

Code Formatting

./mvnw spotless:apply    # Format all languages (Java: Google Java Format, C++: clang-format, Python: Black)
./mvnw spotless:check    # Check formatting without modifying

Internationalization

Java logs and exception messages use a runtime ResourceBundle approach so the same JAR can emit English or Simplified Chinese based on a JVM startup property. See java/CLAUDE.md for the convention. Switch language with -Dtsfile.locale=zh.

License Header

Every new file must include the Apache License 2.0 header at the top. Use the comment style appropriate for the file type (e.g., <!-- --> for Markdown, /* */ for Java/C++, # for Python). See any existing file for the exact wording.

Git Commit

  • Do NOT add Co-Authored-By trailer to commit messages.