Skip to content

About

Apache TsFile Viewer

Topics

Resources

Code of conduct

Security policy

Stars

31 stars

Watchers

18 watching

Forks

Latest commit

 

History

37 Commits

Folders and files

Repository files navigation

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:

  • Check docs/DEPLOYMENT.md for deployment help
  • Review API documentation
  • Open a GitHub issue

Acknowledgments

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

About

Apache TsFile Viewer

Topics

Resources

Code of conduct

Security policy

Stars

31 stars

Watchers

18 watching

Forks

Releases

Packages

Used by

Contributors

Languages