TsFile 데이터 로드

TsFile는 시계열 데이터를 위해 설계된 컬럼형 파일 형식으로, Apache IoTDB의 네이티브 저장 계층으로 사용됩니다. Parquet와 같은 범용 컬럼형 형식과 비교할 때, TsFile은 시계열 데이터 모델(타임스탬프, 디바이스, 측정값)을 인지하며, 전체 파일을 스캔하지 않고도 시간 범위 기반 프루닝을 가능하게 하는 내부 시간 인덱스를 유지합니다.

이 로더는 일반적인 1행 1레코드 테이블 형식의 관례를 따르지 않기 때문에 별도의 가이드로 제공됩니다. 각 출력 행은 하나의 device에 대응하며, 측정값은 Arrow list<...> 컬럼으로 반환됩니다. 매핑 방식은 아래에서 자세히 설명합니다.

설치

로더는 tsfile Python 패키지에 의존합니다:

pip install "tsfile>=2.3.0"

데이터 모델 및 출력 레이아웃

로더는 TsFile 테이블 모델을 따릅니다. 각 테이블의 열은 다음 중 하나입니다:

• TAG — 문자열 타입의 식별자이며, device(즉, 단일 시계열 소스)을 고유하게 식별하는 TAG 값의 튜플입니다.
• FIELD — 값이 시간에 따라 변화하는 측정값.
• TIME — 타임스탬프 컬럼으로, 기본적으로 time이라는 이름을 사용합니다.

로더는 장치별로 데이터셋 행 하나를 출력합니다. 행 내에서 time 컬럼과 모든 FIELD 컬럼은 해당 장치의 전체 시계열을 시간 오름차순으로 정렬하여 포함하는 Arrow list<...> 컬럼입니다. TAG 컬럼은 스칼라 string 컬럼으로 나타납니다.

구체적으로, 출력 스키마는 다음과 같은 형태를 가집니다:

<tag_1>:    string
<tag_2>:    string                       # one column per TAG
...
time:       list<timestamp[unit, tz]>
<field_1>:  list<original_type>          # one column per FIELD
<field_2>:  list<original_type>
...

같은 split의 여러 입력 파일에 동일한 디바이스가 나타나는 경우, 파일별 청크가 타임스탬프 기준으로 정렬된 후 연결되어 단일 행으로 출력됩니다. 동일한 디바이스에 대해 중복된 타임스탬프가 있으면 ValueError가 발생합니다.

기본 사용법

Load a single TsFile:

>>> from datasets import load_dataset
>>> dataset = load_dataset("tsfile", data_files="my_data.tsfile")

files를 splits에 명시적으로 매핑합니다:

>>> dataset = load_dataset(
...     "tsfile",
...     data_files={"train": "train_data.tsfile", "test": "test_data.tsfile"},
... )

Hub의 예시 데이터셋

사용 가능한 예제는 tsfile/lotsa_data에 있습니다. .tsfile 파일은 자동으로 인식되므로, data_files를 지정하지 않고 저장소 ID로 로드할 수 있습니다:

>>> from datasets import load_dataset
>>> dataset = load_dataset("tsfile/lotsa_data")
>>> dataset
DatasetDict({
    train: Dataset({
        features: ['timeseries_id', 'time', 'value'],
        num_rows: 91
    })
})

각 행은 하나의 장치를 나타냅니다. TAG 열인 timeseries_id는 장치를 식별하며, time과 value는 해당 장치의 전체 시계열을 담고 있는 list<...> 열입니다:

>>> row = dataset["train"][0]
>>> row["timeseries_id"]
'Bear_assembly_Angel'
>>> len(row["time"]), len(row["value"])
(8760, 8760)
>>> row["time"][:3]
[datetime.datetime(2017, 1, 1, 0, 0), datetime.datetime(2017, 1, 1, 1, 0), datetime.datetime(2017, 1, 1, 2, 0)]

테이블 선택

TsFile에는 여러 테이블이 포함될 수 있습니다. table_name이 생략되면, 첫 번째 유효한 파일에서 발견된 첫 번째 테이블이 사용됩니다. 조회는 대소문자를 구분하지 않습니다.

>>> dataset = load_dataset("tsfile", data_files="my_data.tsfile", table_name="sensor_data")

열 선택

columns는 읽히는 FIELD 컬럼을 제한합니다. TAG 컬럼과 time 컬럼은 디바이스와 해당 타임라인을 식별하기 때문에 항상 반환됩니다. columns에 TAG 또는 time 컬럼을 가리키는 이름이 포함된 경우 조용히 무시됩니다(통상대로 한 번만 출력됨). 모든 파일에 존재하지 않는 필드와 일치하는 이름은 모든 값이 null인 리스트 컬럼이 됩니다.

>>> dataset = load_dataset(
...     "tsfile",
...     data_files="my_data.tsfile",
...     columns=["temperature", "humidity"],
... )

시간 범위로 필터링

start_time와 end_time은 포함 경계이며, 둘 중 하나를 생략할 수 있습니다. 경계 값은 TsFile의 내부 시간 인덱스로 전달되어, 일치하는 데이터 블록만 디스크에서 읽힙니다. 두 경계 값 모두 다음 중 하나를 사용할 수 있습니다:

• int — timestamp_unit 단위(기본값: 밀리초)의 원시 epoch;
• datetime.datetime — naive 값은 UTC로 해석되며, tz-aware 값은 UTC로 변환됩니다;
• datetime.date;
• ISO-8601 str, 예: "2024-01-01T00:00:00";
• pyarrow.TimestampScalar.

>>> from datetime import datetime
>>> dataset = load_dataset(
...     "tsfile",
...     data_files="my_data.tsfile",
...     start_time=datetime(2023, 11, 14),
...     end_time="2023-11-15T00:00:00",
... )

파일 간 스키마 진화

서로 다른 파일에서 서로 다른 컬럼을 노출하는 경우(예: 나중에 새로운 센서 필드가 도입되는 경우) 로더는 모든 FIELD 컬럼의 합집합을 취하고 누락된 값은 null로 채웁니다. 숫자 타입의 FIELD는 IoTDB의 확장 규칙(INT32 → INT64 → DOUBLE, INT32 → FLOAT → DOUBLE)에 따라 타입이 승격됩니다.

>>> dataset = load_dataset("tsfile", data_files=["day1.tsfile", "day2.tsfile"])

읽을 수 없는 파일 처리

기본적으로 읽을 수 없거나 TsFile이 아닌 입력은 오류를 발생시킵니다. on_bad_files를 "warn"으로 설정하면 로그를 기록하고 계속 진행하며, "skip"으로 설정하면 파일을 조용히 무시합니다.

>>> dataset = load_dataset("tsfile", data_files="data/*.tsfile", on_bad_files="skip")

Timestamp 단위 및 시간대

timestamp_unit(기본값 "ms", IoTDB와 일치)은 time 열의 해상도와 정수 시간 경계의 해석을 제어합니다. timestamp_tz은 Arrow timestamp 유형에 시간대를 연결하며, None(기본값)은 시간대 없는(timezone-naive) 유형을 생성합니다.

>>> dataset = load_dataset(
...     "tsfile",
...     data_files="my_data.tsfile",
...     timestamp_unit="us",
...     timestamp_tz="UTC",
... )

메모리 및 배치

메모리 사용량을 제어하는 두 가지 매개변수가 있습니다:

• input_batch_size (기본값 65_536) — TsFileReader.query_table에서 Arrow 배치별로 가져오는 최대 행 수입니다. 단일 디바이스를 스트리밍할 때 피크 메모리를 제한합니다.
• output_batch_size (기본값 32) — writer에 전달되는 각 Arrow record batch에 포함될 장치의 수입니다. 값이 작을수록 진행 상황 보고가 더 반응적으로 이루어지며, 값이 클수록 배치당 오버헤드가 줄어듭니다.

>>> dataset = load_dataset(
...     "tsfile",
...     data_files="large_data.tsfile",
...     input_batch_size=32_768,
...     output_batch_size=128,
... )

피크 메모리는 분할 전체의 크기가 아니라, 분할에 걸친 단일 디바이스의 페이로드에 의해 제한됩니다.

전체 매개변수 목록은 TsFileConfig를 참조하세요.