{"id":49683974,"url":"https://github.com/apache/tsfile-viewer","last_synced_at":"2026-05-07T09:01:14.103Z","repository":{"id":65979475,"uuid":"565313329","full_name":"apache/tsfile-viewer","owner":"apache","description":"Apache TsFile Viewer","archived":false,"fork":false,"pushed_at":"2026-05-07T03:50:32.000Z","size":2313,"stargazers_count":26,"open_issues_count":1,"forks_count":8,"subscribers_count":18,"default_branch":"main","last_synced_at":"2026-05-07T05:36:57.669Z","etag":null,"topics":["java","timeseries","tsfile"],"latest_commit_sha":null,"homepage":"https://tsfile.apache.org/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apache.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-11-13T01:39:31.000Z","updated_at":"2026-05-07T03:49:21.000Z","dependencies_parsed_at":"2025-04-10T00:27:52.899Z","dependency_job_id":null,"html_url":"https://github.com/apache/tsfile-viewer","commit_stats":null,"previous_names":["apache/tsfile-viewer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/apache/tsfile-viewer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Ftsfile-viewer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Ftsfile-viewer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Ftsfile-viewer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Ftsfile-viewer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apache","download_url":"https://codeload.github.com/apache/tsfile-viewer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Ftsfile-viewer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32730282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-07T02:14:30.463Z","status":"ssl_error","status_checked_at":"2026-05-07T02:14:29.405Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","timeseries","tsfile"],"created_at":"2026-05-07T09:01:13.092Z","updated_at":"2026-05-07T09:01:14.096Z","avatar_url":"https://github.com/apache.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TsFile Viewer\n\nA web-based application for viewing and analyzing Apache TsFile format data. Built with Vue 3 and Spring Boot 4.\n\n[中文文档](README.zh-CN.md) | [English](README.md)\n\n## Features\n\n- **File Management**: Browse server directories and upload TsFile files\n- **Metadata Viewing**: Display comprehensive TsFile metadata including schema, devices, measurements, and statistics\n- **Data Preview**: Paginated data tables with advanced filtering (time range, devices, measurements, value range)\n- **Data Visualization**: Interactive charts using ECharts 6 with multi-series overlay, aggregation, and drill-down\n- **Tree \u0026 Table Models**: Support for both Tree Model (path-based) and Table Model (relational) TsFile formats\n- **Export**: Export filtered data as CSV or JSON, export charts as PNG or SVG\n- **Performance**: Chunk-level reading, metadata caching, automatic downsampling for large datasets\n- **Deployment Flexibility**: Support for both embedded (single JAR) and separate (frontend + backend) deployment\n\n## Technology Stack\n\n### Backend\n\n- Spring Boot 4.0.1 with JDK 21\n- Apache TsFile 2.2.0\n- Caffeine cache for metadata and reader caching\n- Maven 3.9+\n\n### Frontend\n\n- Vue 3.5.x with Composition API\n- Vite 8.x build tool\n- Nuxt UI components (Tailwind CSS-based)\n- Pinia 2.x state management\n- ECharts 6.0.x for visualization\n- TypeScript 5.4.x+\n\n## Quick Start\n\n### Prerequisites\n\n- JDK 17 or 21 (LTS)\n- Maven 3.9+\n- Node.js ^20.19.0 || \u003e=22.12.0\n- pnpm package manager\n\n### Development Mode\n\n1. **Start Backend:**\n\n   ```bash\n   cd backend\n   mvn spring-boot:run\n   ```\n\n   Backend will run at `http://localhost:8080`\n\n2. **Start Frontend:**\n\n   ```bash\n   cd frontend\n   pnpm install\n   pnpm dev\n   ```\n\n   Frontend will run at `http://localhost:5173`\n\n3. **Access Application:**\n   Open `http://localhost:5173/view/` in your browser\n\n### Production Build\n\n#### Embedded Deployment (Single JAR)\n\n```bash\n# Linux/Mac\n./build-embedded.sh\n\n# Windows\nbuild-embedded.bat\n\n# Run\njava -jar backend/target/tsfile-viewer-*.jar\n```\n\nAccess at `http://localhost:8080/view/`\n\n#### Separate Deployment\n\n```bash\n# Linux/Mac\n./build-separate.sh\n\n# Windows\nbuild-separate.bat\n```\n\nSee [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for detailed deployment instructions.\n\n## Configuration\n\n### Backend Configuration\n\nEdit `backend/src/main/resources/application.yml`:\n\n```yaml\ntsfile:\n  # Whitelist of allowed directories\n  allowed-directories:\n    - /data/tsfiles\n    - /uploads/tsfiles\n\n  # Upload directory\n  upload-directory: /uploads/tsfiles\n\n  # Cache settings\n  cache:\n    metadata:\n      max-size: 1000\n      ttl-minutes: 60\n    reader:\n      max-size: 100\n      ttl-minutes: 30\n```\n\n### Frontend Configuration\n\nCreate `frontend/.env.production`:\n\n```env\n# API base URL (default/recommended for reverse proxy)\nVITE_API_BASE_URL=/api\n```\n\n## Project Structure\n\n```\ntsfile-viewer/\n├── backend/              # Spring Boot Maven project\n│   ├── src/main/java/\n│   │   └── com/timecho/tsfile/viewer/\n│   │       ├── controller/   # REST API endpoints\n│   │       ├── service/      # Business logic\n│   │       ├── tsfile/       # TsFile parsing utilities\n│   │       ├── config/       # Spring configuration\n│   │       └── dto/          # Data transfer objects\n│   └── pom.xml\n├── frontend/             # Vue 3 + Vite SPA\n│   ├── src/\n│   │   ├── views/        # Page components\n│   │   ├── components/   # Reusable components\n│   │   ├── stores/       # Pinia state management\n│   │   ├── api/          # API client\n│   │   └── composables/  # Vue composables\n│   └── package.json\n├── tsfile-source/        # TsFile v2.2.0 source (reference)\n├── build-embedded.sh     # Embedded deployment build script\n├── build-separate.sh     # Separate deployment build script\n├── docs/                 # Project documentation\n│   ├── DEPLOYMENT.md     # Deployment guide\n│   ├── API.md            # API documentation\n│   └── ...\n└── README.md\n```\n\n## Usage\n\n### 1. File Selection\n\n- Browse server directories using the file tree\n- Upload local TsFile files (drag-drop or click to browse)\n- Access recently viewed files from the recent files list\n\n### 2. Metadata Viewing\n\n- View basic information: version, time range, device/measurement counts\n- Toggle between Tree Model and Table Model views\n- Explore measurements with data types, encoding, and compression\n- Browse RowGroups and Chunks with detailed statistics\n\n### 3. Data Preview\n\n- Apply filters: time range, devices, measurements, value range\n- Navigate paginated data with sortable columns\n- Export filtered data as CSV or JSON\n\n### 4. Data Visualization\n\n- Select measurements for multi-series charts\n- Apply aggregation functions (min, max, avg, count)\n- Zoom and pan with DataZoom controls\n- Click data points for drill-down details\n- Export charts as PNG or SVG\n\n## API Endpoints\n\n- `GET /api/files/tree` - Browse file tree\n- `POST /api/files/upload` - Upload TsFile\n- `GET /api/meta/{fileId}` - Get metadata\n- `POST /api/data/preview` - Preview data with filters\n- `POST /api/data/query` - Query chart data with aggregation\n\nSee API documentation at `/swagger-ui.html` (if enabled)\n\n## Development\n\n### Backend\n\n```bash\ncd backend\n\n# Run tests\nmvn test\n\n# Format code\nmvn spotless:apply\n\n# Check formatting\nmvn spotless:check\n\n# Build\nmvn clean package\n```\n\n### Frontend\n\n```bash\ncd frontend\n\n# Install dependencies\npnpm install\n\n# Run dev server\npnpm dev\n\n# Build for production\npnpm build\n\n# Run tests\npnpm test:unit\n\n# Lint\npnpm lint\n\n# Format\npnpm format\n\n# Type check\npnpm type-check\n```\n\n## Testing\n\n### Backend Tests\n\n131 tests covering:\n\n- TsFile parsing utilities\n- Data reading and filtering\n- Cache behavior\n- REST API endpoints\n- Error handling\n\nRun: `mvn test`\n\n### Frontend Tests\n\nComponent and integration tests using Vitest + Vue Test Utils\n\nRun: `pnpm test:unit`\n\n## Performance\n\n- **Chunk-level reading**: Streams data without loading entire files\n- **Metadata caching**: 1-hour TTL, 1000 entries max\n- **Reader caching**: 30-minute TTL, 100 entries max\n- **Automatic downsampling**: LTTB algorithm for \u003e1000 data points\n- **Virtual scrolling**: Efficient rendering for large tables\n- **Route-based code splitting**: Lazy loading for optimal bundle size\n\n## Security\n\n- **Directory whitelist**: Restricts file system access to configured paths\n- **Upload validation**: File extension and size checks\n- **Reverse Proxy Support**: Recommended way to connect in separate deployment\n- **Path traversal protection**: Rejects `..` and absolute paths outside whitelist\n\n## License\n\nSee [LICENSE](LICENSE) file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests and formatting\n5. Submit a pull request\n\n## Support\n\nFor issues and questions:\n\n- Check [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for deployment help\n- Review API documentation\n- Open a GitHub issue\n\n## Acknowledgments\n\n- Apache TsFile library\n- Vue.js and Spring Boot communities\n- ECharts visualization library\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Ftsfile-viewer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapache%2Ftsfile-viewer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Ftsfile-viewer/lists"}