Google Git
Sign in
apache/tsfile-viewer/HEAD
commit
da33a2670dd80b40016e987a238bec2a4e8ecc2f
[log]
author
CritasWang <critas@outlook.com>
Fri May 15 12:27:33 2026 +0800
committer
GitHub <noreply@github.com>
Fri May 15 12:27:33 2026 +0800
tree
83ed693cb3a4f6da62b23987bf15be9ae2756b8b
parent
1960fa4529b8a113dccca2d1fd8e7e438798fee1 [diff]
Fix/upgrade tsfile to 2.3.0 (#20)

* fix: upgrade tsfile library from 2.2.0 to 2.3.0

Fixes ArrayIndexOutOfBoundsException in TableSchema.deserialize when
reading TsFile files created by newer SDK versions.

* docs: update TsFile version references to 2.3.0 in READMEs

* docs: update READMEs to reflect actual project structure

- Fix package path: com/timecho → org/apache/tsfile
- Replace non-existent build scripts with actual build-dist.sh
- Update frontend stack: Nuxt UI → antdv-next + UnoCSS
- Update versions: Pinia 3.x, TypeScript 5.9.x
- Add missing directories: exception, router, theme
- Remove non-existent tsfile-source directory
2 files changed
tree: 83ed693cb3a4f6da62b23987bf15be9ae2756b8b
  1. .github/
  2. backend/
  3. docs/
  4. frontend/
  5. .asf.yaml
  6. .gitignore
  7. build-dist.sh
  8. LICENSE
  9. NOTICE
  10. README.md
  11. README.zh-CN.md
README.md

TsFile Viewer

A web-based application for viewing and analyzing Apache TsFile format data. Built with Vue 3 and Spring Boot 4.

中文文档 | English

Features

  • File Management: Browse server directories and upload TsFile files
  • Metadata Viewing: Display comprehensive TsFile metadata including schema, devices, measurements, and statistics
  • Data Preview: Paginated data tables with advanced filtering (time range, devices, measurements, value range)
  • Data Visualization: Interactive charts using ECharts 6 with multi-series overlay, aggregation, and drill-down
  • Tree & Table Models: Support for both Tree Model (path-based) and Table Model (relational) TsFile formats
  • Export: Export filtered data as CSV or JSON, export charts as PNG or SVG
  • Performance: Chunk-level reading, metadata caching, automatic downsampling for large datasets
  • Deployment Flexibility: Embedded deployment as a single JAR with built-in frontend

Technology Stack

Backend

  • Spring Boot 4.0.1 with JDK 21
  • Apache TsFile 2.3.0
  • Caffeine cache for metadata and reader caching
  • Maven 3.9+

Frontend

  • Vue 3.5.x with Composition API
  • Vite build tool
  • Ant Design Vue (antdv-next) components with UnoCSS
  • Pinia 3.x state management
  • ECharts 6.0.x for visualization
  • TypeScript 5.9.x

Quick Start

Prerequisites

  • JDK 17 or 21 (LTS)
  • Maven 3.9+
  • Node.js ^20.19.0 || >=22.12.0
  • pnpm package manager

Development Mode

  1. Start Backend:

    cd backend
mvn spring-boot:run

    Backend will run at http://localhost:8080

  2. Start Frontend:

    cd frontend
pnpm install
pnpm dev

    Frontend will run at http://localhost:5173

  3. Access Application: Open http://localhost:5173/view/ in your browser

Production Build

# Build distribution package (embedded JAR + scripts)
./build-dist.sh

# Run
java -jar backend/target/tsfile-viewer-*.jar

Access at http://localhost:8080/view/

See docs/DEPLOYMENT.md for detailed deployment instructions.

Configuration

Backend Configuration

Edit backend/src/main/resources/application.yml:

tsfile:
  # Whitelist of allowed directories
  allowed-directories:
    - /data/tsfiles
    - /uploads/tsfiles

  # Upload directory
  upload-directory: /uploads/tsfiles

  # Cache settings
  cache:
    metadata:
      max-size: 1000
      ttl-minutes: 60
    reader:
      max-size: 100
      ttl-minutes: 30

Frontend Configuration

Create frontend/.env.production:

# API base URL (default/recommended for reverse proxy)
VITE_API_BASE_URL=/api

Project Structure

tsfile-viewer/
├── backend/              # Spring Boot Maven project
│   ├── src/main/java/
│   │   └── org/apache/tsfile/viewer/
│   │       ├── controller/   # REST API endpoints
│   │       ├── service/      # Business logic
│   │       ├── tsfile/       # TsFile parsing utilities
│   │       ├── config/       # Spring configuration
│   │       ├── dto/          # Data transfer objects
│   │       └── exception/    # Custom exceptions
│   └── pom.xml
├── frontend/             # Vue 3 + Vite SPA
│   ├── src/
│   │   ├── views/        # Page components
│   │   ├── components/   # Reusable components
│   │   ├── stores/       # Pinia state management
│   │   ├── api/          # API client
│   │   ├── router/       # Vue Router configuration
│   │   ├── i18n/         # Internationalization
│   │   ├── theme/        # Theme configuration
│   │   └── composables/  # Vue composables
│   └── package.json
├── build-dist.sh         # Distribution build script
├── docs/                 # Project documentation
│   ├── DEPLOYMENT.md     # Deployment guide
│   ├── API.md            # API documentation
│   └── ...
└── README.md

Usage

1. File Selection

  • Browse server directories using the file tree
  • Upload local TsFile files (drag-drop or click to browse)
  • Access recently viewed files from the recent files list

2. Metadata Viewing

  • View basic information: version, time range, device/measurement counts
  • Toggle between Tree Model and Table Model views
  • Explore measurements with data types, encoding, and compression
  • Browse RowGroups and Chunks with detailed statistics

3. Data Preview

  • Apply filters: time range, devices, measurements, value range
  • Navigate paginated data with sortable columns
  • Export filtered data as CSV or JSON

4. Data Visualization

  • Select measurements for multi-series charts
  • Apply aggregation functions (min, max, avg, count)
  • Zoom and pan with DataZoom controls
  • Click data points for drill-down details
  • Export charts as PNG or SVG

API Endpoints

  • GET /api/files/tree - Browse file tree
  • POST /api/files/upload - Upload TsFile
  • GET /api/meta/{fileId} - Get metadata
  • POST /api/data/preview - Preview data with filters
  • POST /api/data/query - Query chart data with aggregation

See API documentation at /swagger-ui.html (if enabled)

Development

Backend

cd backend

# Run tests
mvn test

# Format code
mvn spotless:apply

# Check formatting
mvn spotless:check

# Build
mvn clean package

Frontend

cd frontend

# Install dependencies
pnpm install

# Run dev server
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test:unit

# Lint
pnpm lint

# Format
pnpm format

# Type check
pnpm type-check

Testing

Backend Tests

131 tests covering:

  • TsFile parsing utilities
  • Data reading and filtering
  • Cache behavior
  • REST API endpoints
  • Error handling

Run: mvn test

Frontend Tests

Component and integration tests using Vitest + Vue Test Utils

Run: pnpm test:unit

Performance

  • Chunk-level reading: Streams data without loading entire files
  • Metadata caching: 1-hour TTL, 1000 entries max
  • Reader caching: 30-minute TTL, 100 entries max
  • Automatic downsampling: LTTB algorithm for >1000 data points
  • Virtual scrolling: Efficient rendering for large tables
  • Route-based code splitting: Lazy loading for optimal bundle size

Security

  • Directory whitelist: Restricts file system access to configured paths
  • Upload validation: File extension and size checks
  • Reverse Proxy Support: Recommended way to connect in separate deployment
  • Path traversal protection: Rejects .. and absolute paths outside whitelist

License

See LICENSE file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests and formatting
  5. Submit a pull request

Support

For issues and questions:

Acknowledgments

  • Apache TsFile library
  • Vue.js and Spring Boot communities
  • ECharts visualization library