TSFile Viewer User Guide

Welcome to TSFile Viewer! This guide will help you get started with viewing and analyzing your TSFile data.

Table of Contents

Getting Started

Accessing the Application

  1. Open your web browser
  2. Navigate to the application URL:
    • Development: http://localhost:5173/view/
    • Production: Your configured domain + /view/

Understanding TSFile Models

TSFile Viewer supports two data models:

  1. Tree Model: Traditional hierarchical path-based model

    • Device paths like root.sensor1.temperature
    • Suitable for IoT sensor data

  2. Table Model: Relational table-based model (TSFile V4)

    • Tables with TAG columns (identifiers) and FIELD columns (measurements)
    • Suitable for structured time-series data

The application automatically detects which model your TSFile uses.

File Selection

Browsing Server Files

  1. On the home page, you'll see a file tree on the left
  2. Click the folder icon to expand directories
  3. Navigate through the directory structure
  4. Click on a .tsfile file to view its metadata

Note: Only directories configured in the server's whitelist are accessible.

Uploading Files

  1. On the home page, find the “Upload TSFile” card on the right
  2. Either:
    • Drag and drop a .tsfile file onto the upload area
    • Click the upload area to browse and select a file
  3. Wait for the upload to complete (progress bar shows status)
  4. The application will automatically navigate to the metadata view

Upload Requirements:

  • File must have .tsfile extension
  • Maximum file size: 100MB (configurable by administrator)

Recent Files

The “Recent Files” section shows your recently accessed files:

  • Click any file card to quickly return to its metadata view
  • Files are stored in your browser's local storage
  • Up to 10 recent files are kept

Viewing Metadata

After selecting a file, you'll see the metadata page with comprehensive information about your TSFile.

Basic Information

At the top, you'll see cards displaying:

  • Version: TSFile format version
  • Time Range: Start and end timestamps of the data
  • Device Count: Number of devices in the file
  • Measurement Count: Number of measurements
  • RowGroup Count: Number of RowGroups
  • Chunk Count: Number of data chunks

Switching Between Models

Use the “View Mode” toggle to switch between:

  • Tree Model: Shows measurements in a flat table
  • Table Model: Shows table schema with TAG and FIELD columns

Tree Model View

Measurements Table:

  • Lists all measurements with their properties
  • Columns: Name, Data Type, Encoding, Compression
  • Click column headers to sort
  • Use the search box to filter by name

RowGroups Table:

  • Shows data organization by device and time
  • Columns: Index, Device, Start Time, End Time, Chunk Count
  • Sort by any column
  • Filter by device name

Chunks Table:

  • Displays storage-level information
  • Columns: Measurement, Offset, Size, Compression Ratio
  • Sort by size or offset
  • Filter by measurement name

Table Model View

Table Schema:

  • Shows table name
  • TAG Columns: Identity columns (marked with blue badge)
  • FIELD Columns: Measurement columns (marked with green badge)
  • Each column shows: Name, Data Type, Encoding, Compression
  • Summary shows total TAG and FIELD column counts

Navigation

From the metadata page, you can:

  • Click “View Data” to preview the actual data
  • Click “Visualize” to create charts
  • Click “← Back to Files” to return to file selection

Previewing Data

The data preview page lets you explore your time-series data with powerful filtering options.

Filter Panel

Located on the left side, the filter panel offers:

Time Range:

  • Set start and end times using datetime pickers
  • Leave empty to query all data

Devices:

  • Multi-select dropdown to filter by specific devices
  • Leave empty to include all devices

Measurements:

  • Multi-select dropdown to filter by specific measurements
  • Leave empty to include all measurements

Value Range:

  • Set minimum and maximum values
  • Only data points within this range will be shown

Pagination:

  • Limit: Number of rows per page (1-1000)
  • Offset: Starting row number

Data Table

The main area displays your filtered data:

  • Timestamp: When the data was recorded
  • Device: Which device produced the data
  • Measurements: Values for each measurement

Features:

  • Click column headers to sort
  • Virtual scrolling for smooth performance with large datasets
  • Loading indicator while fetching data

Pagination Controls

At the bottom of the table:

  • “Previous” button: Go to previous page
  • “Next” button: Go to next page
  • Page information shows current range and total rows

Applying Filters

  1. Set your desired filters in the filter panel
  2. Filters are applied automatically (with a short delay)
  3. The table updates to show filtered results
  4. Adjust filters as needed to refine your view

Visualizing Data

The chart visualization page provides interactive charts for analyzing trends and patterns.

Chart Configuration

Measurements:

  • Enter measurement names separated by commas
  • Example: temperature, humidity, pressure
  • Multiple measurements create multi-series charts

Time Range:

  • Set start and end times to focus on specific periods
  • Leave empty to chart all available data

Aggregation:

  • Select aggregation type: Min, Max, Average, or Count
  • Set window size in milliseconds (e.g., 60000 for 1 minute)
  • Aggregation groups data points within time windows

Max Points:

  • Limits the number of data points displayed
  • Higher values show more detail but may slow rendering
  • Automatic downsampling preserves visual trends

Loading Chart Data

  1. Configure your chart settings
  2. Click “Load Chart Data” button
  3. Wait for data to load (progress indicator shows status)
  4. Chart appears with your data

Interacting with Charts

Zoom and Pan:

  • Use the DataZoom slider at the bottom to select time ranges
  • Drag the slider handles to zoom in/out
  • Click and drag the chart to pan

Tooltips:

  • Hover over data points to see exact values
  • Tooltip shows timestamp and measurement values

Drill-Down:

  • Click any data point to see detailed information
  • A dialog shows the exact timestamp and all measurement values
  • Click “Close” to return to the chart

Legend:

  • Click legend items to show/hide series
  • Useful for comparing specific measurements

Exporting Charts

Charts can be exported in two formats:

  • PNG: Raster image format, good for documents
  • SVG: Vector format, scalable without quality loss

Click the export button and select your preferred format.

Downsampling Indicator

When your data exceeds the max points limit:

  • A “downsampled” indicator appears
  • The LTTB algorithm reduces points while preserving trends
  • Visual appearance remains accurate
  • Increase max points if you need more detail

Exporting Data

CSV Export

  1. Apply your desired filters in the data preview page
  2. Click the “Export CSV” button
  3. A CSV file downloads with:
    • Headers: Timestamp, Device, Measurement names
    • Rows: Your filtered data
    • Format: Standard CSV (comma-separated)

Use Cases:

  • Import into Excel or Google Sheets
  • Process with data analysis tools
  • Share with colleagues

JSON Export

  1. Apply your desired filters in the data preview page
  2. Click the “Export JSON” button
  3. A JSON file downloads with:
    • Array of data row objects
    • Each row contains timestamp, device, and measurements
    • Format: Pretty-printed JSON

Use Cases:

  • Import into programming environments
  • Process with custom scripts
  • API integration

Note: Exports respect your current filter settings. Only filtered data is exported.

Tips and Best Practices

Performance Tips

  1. Use Time Range Filters: Narrow your time range to improve query speed
  2. Limit Result Size: Use smaller page sizes for faster loading
  3. Aggregate Large Datasets: Use aggregation for charts with millions of points
  4. Cache Metadata: Metadata is cached automatically for faster subsequent access

Data Analysis Tips

  1. Start with Metadata: Review metadata before querying data
  2. Use Aggregation: For trend analysis, aggregate data to reduce noise
  3. Compare Measurements: Use multi-series charts to compare related measurements
  4. Export for Deep Analysis: Export data for advanced analysis in specialized tools

Troubleshooting Common Issues

“File not found” error:

  • Ensure the file still exists on the server
  • Check if the file was moved or deleted
  • Try uploading the file again

“Query timeout” error:

  • Reduce the time range
  • Use aggregation to reduce data points
  • Increase the query timeout (contact administrator)

Slow performance:

  • Use smaller page sizes
  • Apply more specific filters
  • Enable aggregation for charts
  • Clear browser cache

Upload fails:

  • Check file extension is .tsfile
  • Verify file size is under 100MB
  • Ensure file is not corrupted
  • Check network connection

Charts not displaying:

  • Verify measurements exist in the file
  • Check time range includes data
  • Try reducing max points
  • Refresh the page

Browser Compatibility

TSFile Viewer works best with modern browsers:

  • Chrome 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+

Keyboard Shortcuts

  • Ctrl/Cmd + F: Focus search/filter input
  • Esc: Close dialogs and modals
  • Arrow keys: Navigate through data tables

Getting Help

If you encounter issues:

  1. Check Error Messages: Error messages provide specific information
  2. Review This Guide: Many common questions are answered here
  3. Check API Documentation: See API.md for technical details
  4. Contact Administrator: For server configuration issues
  5. Report Bugs: Open a GitHub issue with details

Advanced Features

View Persistence (Optional)

If enabled by your administrator:

  • Save your current filter and chart configurations
  • Name and organize saved views
  • Quickly return to frequently used analysis setups

Custom Aggregation Windows

Experiment with different window sizes:

  • Small windows (1-60 seconds): Detailed trends
  • Medium windows (1-60 minutes): Hourly patterns
  • Large windows (1-24 hours): Daily patterns

Multi-Device Comparison

Compare data across devices:

  1. Select multiple devices in filters
  2. Create charts with the same measurements
  3. Use the legend to toggle device visibility
  4. Identify patterns and anomalies

Conclusion

TSFile Viewer provides a powerful yet intuitive interface for exploring your time-series data. Start with file selection, review metadata, preview data with filters, and create insightful visualizations.

For technical details, see:

Happy analyzing!