Skip to main content

Annotated CSV Format (InfluxDB)

Description​

Annotated CSV is a format used by InfluxDB for exporting time series data. It extends standard CSV with metadata annotations that describe data types, groups, and other information. The format includes a header section with annotations followed by data rows.

File Extensions​

  • .annotatedcsv - Annotated CSV files

Implementation Details​

Reading​

The Annotated CSV implementation:

  • Parses InfluxDB Annotated CSV format
  • Extracts metadata annotations from header
  • Converts data types based on annotations
  • Handles datetime, numeric, and boolean types
  • Converts each row to a dictionary

Writing​

Writing support:

  • Writes InfluxDB annotated CSV with optional datatype annotations
  • Pass column names via keys when writing

Key Features​

  • Type conversion: Automatically converts values based on annotations
  • Metadata support: Extracts and uses metadata annotations
  • InfluxDB format: Designed for InfluxDB data export
  • Totals support: Can count total rows
  • Time series: Optimized for time series data

Usage​

from iterable import open_iterable

# Basic reading
with open_iterable('data.annotatedcsv') as source:
    for row in source:
        print(row)

# Writing
with open_iterable('output.annotatedcsv', mode='w', iterableargs={'keys': ['time', 'value']}) as dest:
    dest.write({'time': '2024-01-01T00:00:00Z', 'value': 1.2})

Parameters​

  • encoding (str): File encoding (default: utf8)
  • delimiter (str): Field delimiter (default: ,)

Limitations​

  1. InfluxDB-specific: Designed specifically for InfluxDB
  2. Format complexity: Requires understanding of InfluxDB annotations
  3. Type conversion: Some complex types may not convert perfectly

Compression Support​

Annotated CSV files can be compressed with all supported codecs:

  • GZip (.annotatedcsv.gz)
  • BZip2 (.annotatedcsv.bz2)
  • LZMA (.annotatedcsv.xz)
  • LZ4 (.annotatedcsv.lz4)
  • ZIP (.annotatedcsv.zip)
  • Brotli (.annotatedcsv.br)
  • ZStandard (.annotatedcsv.zst)

Use Cases​

  • InfluxDB export: Exporting data from InfluxDB
  • Time series data: Working with time series data
  • Data migration: Migrating InfluxDB data
  • Data analysis: Analyzing time series data

Error Handling​

  • Missing dependency: optional libraries raise ImportError with an install hint (pip install 'iterabledata[<extra>]' when an extra exists).
  • Write mode: read-only formats raise WriteNotSupportedError or ValueError when opened with mode="w".
  • Bad or unsupported input: may raise ValueError, OSError, or library-specific errors.
  • See Troubleshooting for decoding, detection, and engine issues.
  • CSV - Standard CSV format
  • ILP - InfluxDB Line Protocol format