databahn SDK 매뉴얼

databahn 은 IF-03 데이터 소비 규약의 조회 서비스를 파이썬에서 쓰는 클라이언트다. 이 문서만 보고 저장된 모든 데이터(관절 시계열, 카메라 영상, 작업 이벤트)를 찾고, 꺼내고, 학습용으로 내보낼 수 있도록 썼다.

0. 5분 만에 시작하기 — Foxglove 로 재생하기

실제로 녹화된 작업 하나(2026-11-16 17:53:39~17:54:09 KST, 30초)를 MCAP 파일로 받아 Foxglove 에서 관절 그래프로 본다.

1) 설치와 키

pip install "https://if03.data-bahn.com/sdk/databahn-0.4.1-py3-none-any.whl"
export FABRIC_URL=https://if03.data-bahn.com
export FABRIC_API_KEY_FILE=~/.config/databahn/key     # 관리자에게 받은 접근 토큰(API 키) 파일

2) MCAP 로 내보내기

from databahn import Fabric

fab = Fabric()                                   # 위 환경 변수를 읽는다
print(fab.datasets())                            # 내가 볼 수 있는 데이터셋

C = "testbed/so101/cell-01/"
job = fab.export(
    "mcap",
    dataset_id="plab-testbed-cell01",
    start="2026-11-16T17:53:39+09:00",           # 실제 녹화된 작업 구간 (에피소드 ep-20261116T085339Z)
    end="2026-11-16T17:54:09+09:00",
    channels=[C + "leader-arm/joint_state",      # 리더암 관절 (사람이 움직인 팔)
              C + "follower-arm/joint_state",    # 팔로우암 관절 (따라 움직인 팔)
              C + "follower-arm/joint_command"], # 팔로우암에 보낸 명령
    purpose="display",
)
print("내보내기 작업:", job.export_id)
paths = job.wait().download("foxglove")          # 서버가 파일을 다 만들면 내려받는다 (SHA-256 확인)
print(paths[0], paths[0].stat().st_size // 1024, "KB")
# foxglove/exp-20261116-xxxxxxxx.mcap 459 KB  (관절 3채널 × 1,799 메시지)

여러 원본 파일에 걸친 구간이어도 파일 하나로 받는다. 메시지 시각이 정렬 시각(실제 측정 순간 추정)이라 채널들이 맞춰진 채로 재생된다.

3) Foxglove 에서 열기

  1. Foxglove 에서 Open local file 로 받은 .mcap 을 연다.
  2. Plot 패널을 추가하고 + Add series 로 아래 경로를 넣는다 (토픽 이름 앞부분만 쳐도 자동완성된다).
"testbed/so101/cell-01/leader-arm/joint_state".joints[:]{name=="gripper"}.position
"testbed/so101/cell-01/follower-arm/joint_state".joints[:]{name=="gripper"}.position

리더와 팔로우를 한 그래프에 겹치면 팔로우암이 얼마나 늦게·정확하게 따라가는지 보인다. 다른 관절은 gripper 자리에 shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll 을 넣는다. 관절마다 Plot 패널을 하나씩 두면 보기 좋다.

보고 싶은 것 경로 ("testbed/so101/cell-01/…" 토픽 뒤)
관절 위치 leader-arm/joint_state / follower-arm/joint_state → .joints[:]{name=="<관절>"}.position
팔로우암에 보낸 명령 follower-arm/joint_command → .targets[:]{name=="<관절>"}.sent_position (요청값 requested_position)
시각 불확도·등급 follower-arm/joint_state/_align → .uncertainty_ns, .tier (메시지마다 하나)

시간축은 기본값(Receive time)을 그대로 둔다. 이 파일에서는 그것이 정렬 시각이다.

카메라도 보려면 channels 에 C + "wrist-cam/image", C + "top-cam/image" 를 더한다. 카메라 두 대면 30초에 약 60 MB 다. 영상은 테스트베드 전용 메시지 형식이라 Foxglove 에 이미지 변환 확장을 한 번 설치해야 한다: SDK 내려받기 에서 .foxe 파일을 받아 Foxglove 창에 끌어다 놓고, Image 패널에서 카메라 토픽을 고른다.

numpy 로 바로 받고 싶으면 파일 없이 조회한다 (5장).

b = fab.read(dataset_id="plab-testbed-cell01", channels=[C + "follower-arm/joint_state"],
             start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:53:50+09:00", purpose="analysis")
grip = b.select(C + "follower-arm/joint_state", "gripper/position")
print(len(grip.values), grip.unit)              # 600 range_0_100  (60 Hz × 10초)

여기까지 되면 나머지는 필요한 장만 골라 읽으면 된다.

하고 싶은 것 볼 곳
어떤 데이터가 언제 있는지 4장 카탈로그
관절 값을 numpy·pandas 로 5장 구간 조회
데이터가 빠진 곳·신뢰도 6장 품질 정보
작업(에피소드) 목록, 성공·실패 7장 이벤트
특정 작업의 데이터만 8장 연결키
카메라 이미지 9장 영상
학습 데이터셋 고정·Parquet 파일 11장 스냅샷, 12장 내보내기
긴 구간·카메라 포함 MCAP 12장 MCAP 내보내기
바로 쓸 수 있는 코드 15장 레시피

1. 설치

파이썬 3.10 이상. 의존 패키지(httpx, numpy, pyarrow)는 함께 설치된다.

pip install "https://if03.data-bahn.com/sdk/databahn-0.4.1-py3-none-any.whl"
python -c "import databahn; print(databahn.__version__)"     # 0.4.1

지금 판은 0.4.1 (2026-11-19: 모델 추론·배포 클라이언트 Models, semantic_drift 알림, get_mapping. 0.3: 데이터 사전 매핑, semantic_id 해석, 창 모듈). 판 이름은 서버 /sdk/ 목록에서 확인한다. 예전 판이 깔려 있으면 위 명령이 새 판으로 바꿔 설치한다.

서버가 자체 서명 인증서를 쓰면(주소가 IP 이고 브라우저가 경고를 띄우는 경우) CA 인증서로 wheel 을 받은 뒤 파일로 설치한다. pip install --cert 는 신뢰 목록을 통째로 바꿔서 PyPI 에서 의존 패키지를 받지 못하므로 쓰지 않는다.

curl -kO https://if03.data-bahn.com/sdk/ca.crt
curl --cacert ca.crt -O "https://if03.data-bahn.com/sdk/databahn-0.4.1-py3-none-any.whl"
pip install ./databahn-0.4.1-py3-none-any.whl
export FABRIC_CA_BUNDLE=$PWD/ca.crt

이 문서의 예제 중 일부는 pandas, matplotlib, Pillow 를 쓴다. 필요할 때만 설치한다.

pip install pandas matplotlib pillow

2. 연결

from databahn import Fabric

fab = Fabric("https://if03.data-bahn.com", api_key="fk_...")      # 직접 넘기기
fab = Fabric()                                    # 환경 변수에서 읽기 (권장)
인자 기본값 설명
url 환경 변수 FABRIC_URL, 없으면 http://127.0.0.1:8030 조회 서버 주소
api_key FABRIC_API_KEY, 없으면 FABRIC_API_KEY_FILE 파일 내용 접근 토큰(API 키). 관리자가 발급한다 (2.1)
verify FABRIC_CA_BUNDLE, 없으면 True TLS 인증서 확인. 자체 서명 서버면 CA 파일 경로
timeout 120 요청 하나의 시간 한도(초). 큰 구간·느린 네트워크면 늘린다
retries 3 서버 일시 장애(DAT-5031)·연결 오류 때 자동으로 다시 시도하는 횟수

토큰은 코드에 적지 않는다. 파일로 두고 경로만 환경 변수로 넘기면 코드가 git 에 올라가도 토큰이 새지 않는다.

mkdir -p ~/.config/databahn && chmod 700 ~/.config/databahn
cp 받은키파일 ~/.config/databahn/key && chmod 600 ~/.config/databahn/key
export FABRIC_URL=https://if03.data-bahn.com
export FABRIC_API_KEY_FILE=~/.config/databahn/key

토큰이 없으면 Fabric() 이 ValueError 를 낸다. 토큰이 틀리거나 만료됐으면 첫 요청에서 FabricError DAT-4031.

with 로 쓰면 끝날 때 연결을 닫는다(스크립트에서는 생략해도 된다).

with Fabric() as f:
    print(len(f.datasets()))

2.1 접근 토큰과 권한

SDK 인자 이름은 api_key 지만, 서버 쪽에서는 접근 토큰이다. 서버는 토큰 하나로 "누가, 어느 현장에서, 무엇을 할 수 있는지"를 안다. 권한을 정하는 것은 운영 커널(전북대)이고, 조회 서비스는 토큰에 담긴 권한대로 집행만 한다. 지금은 커널과의 합의 전이라 관리자가 등록한 고정 토큰과 정책 파일이 이 역할을 대신한다. 토큰 문자열 자체는 서버에 저장되지 않는다 (해시만).

토큰에 담긴 것:

항목 뜻 영향
신원 (sub) 사용자 또는 서비스 계정 접근 기록, 내보내기 작업의 주인
현장 (site_id) 소속 현장 (예: partridge-lab) restricted 데이터는 같은 현장만 볼 수 있다. 다른 현장에서 internal 데이터를 내보내려면 승인이 필요하다
권한 (grants) 데이터셋 × 목적 목록 허용되지 않은 데이터셋·목적은 DAT-4031. 내 권한은 fab.datasets() 의 allowed_purposes 로 본다
내보내기 승인 (export_scope) on_site 또는 off_site_approved 현장 밖에서 internal 데이터를 내보낼 때만 off_site_approved 가 필요하다
위임 (act, trace_id) 다른 요청을 대신 처리하는 토큰이면 원 요청자와 그 요청 ID 정해진 구간·목적만 읽을 수 있다. 응답의 trace_id 가 그 요청 ID 가 된다
만료 (exp) 지나면 쓸 수 없다 DAT-4031 "토큰 만료"

알아 둘 점:

3. 먼저 알아 둘 개념

3.1 데이터의 구조

데이터셋 plab-testbed-cell01          ← 권한·조회 단위 (테스트베드는 셀 하나)
 └ 채널 testbed/so101/cell-01/follower-arm/joint_state     ← 센서 하나의 데이터 흐름
    └ tag elbow_flex/position, gripper/position, …          ← 채널 안의 항목 (관절별 값)
       └ 레코드: 정렬 시각 ts_ns + 값 value + 단위 unit + 등급 tier + 불확도 uncertainty_ns …
개념 뜻
데이터셋 이름 붙인 채널 묶음. 권한을 주고 조회를 요청하는 단위. 이름에 기간을 넣지 않는다 — 데이터가 쌓여도 같은 이름
채널 데이터 흐름 하나. <구역>/<라인>/<셀>/<장치>/<신호>
tag 시계열 채널 안의 항목. 한 메시지에 여러 관절 값이 함께 들어 있고, 관절마다 tag 하나
레코드 조회 결과의 한 줄. 시계열은 (메시지 × tag) 마다, 영상은 프레임마다, 이벤트는 사건마다 하나

3.2 테스트베드 채널 (SO-101 셀 1)

채널 이름은 모두 testbed/so101/cell-01/ 로 시작한다. 아래 표는 그 뒤만 적었다.

채널 종류 주기 tag (관절마다) 단위
leader-arm/joint_state 시계열 60 Hz <관절>/position deg (그리퍼는 range_0_100)
follower-arm/joint_state 시계열 60 Hz <관절>/position 〃
follower-arm/joint_command 시계열 60 Hz <관절>/requested_position, <관절>/sent_position 〃
follower-arm/joint_health 시계열 1 Hz <관절>/temperature, <관절>/voltage degC, V
wrist-cam/image 영상 30 fps — (JPEG 640×480)
top-cam/image 영상 30 fps — (JPEG 640×480)
operator-console/episode 이벤트 작업자 입력 — (에피소드 시작·끝·폐기·표시)

관절 6개: shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll, gripper. 그리퍼는 0(닫힘)~100(열림), 나머지는 각도.

3.3 시각과 신뢰도

개념 뜻
정렬 시각 ts_ns 실제 사건 시각의 추정값 (관절은 측정 순간, 카메라는 노출 중앙). UTC 기준 int64 나노초. 구간·순서·채널 간 비교의 기준은 이것뿐
불확도 uncertainty_ns 정렬 시각이 실제와 다를 수 있는 최대 폭. 장치 지연 폭 + 컴퓨터 시계 오차. 예: 22 ms → 실제 시각은 ±22 ms 안
등급 tier 불확도로 정하는 신뢰 수준. Tier-1(≤1 µs) · Tier-2(≤1 ms) · Tier-3(≤100 ms) · Tier-4(그보다 큼) · Tier-U(추정 못 함)
미추정 Tier-U 시각을 추정하지 못한 기록. 기본 조회에서 빠진다. 작업자가 콘솔로 입력한 에피소드 이벤트가 여기 속한다 → include_unaligned=True
판본 correction_version 같은 데이터의 기록 버전. 처음 기록은 1, 시각을 다시 계산한 재정렬본은 2 이상. 조회는 늘 최신 판본을 준다
품질 quality 기록 당시 컴퓨터 시계 동기 상태. GOOD(동기됨) / UNCERTAIN(동기 근거가 오래됨·없음)

테스트베드 관절·카메라는 Tier-3 이다(불확도 10~50 ms). 채널 간 비교는 이 폭 안에서만 의미가 있다.

3.4 시각 적는 법과 구간 규칙

시각은 세 가지 중 하나로 적는다.

from datetime import datetime
from zoneinfo import ZoneInfo

"2026-11-16T17:53:40+09:00"                                   # ISO 8601 문자열 (시간대 필수: +09:00, Z)
1794819220000000000                                           # int 나노초 (UTC)
datetime(2026, 11, 16, 17, 53, 40, tzinfo=ZoneInfo("Asia/Seoul"))   # datetime (시간대 필수)
from datetime import datetime
from zoneinfo import ZoneInfo

def kst(ns):
    return datetime.fromtimestamp(ns / 1e9, ZoneInfo("Asia/Seoul")).strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]

print(kst(1794819220000756000))      # 2026-11-16 17:53:40.000

3.5 정렬 시각은 어떻게 만들어지나 — 보정 모델 M3

테스트베드의 관절과 카메라는 장치가 자기 시각을 찍어 보내지 않는다. 그래서 수집 컴퓨터가 데이터를 받은 시각에서 장치에서 거기까지 걸리는 지연을 빼서 실제 사건 시각을 추정한다. 이것이 규약(TS 2.5)의 M3 지연 모델이다.

실제 사건 (관절 측정·카메라 노출 중앙)
   │  ← 장치 지연: 평균 d, 흔들림 폭 b  (채널마다 미리 실측해 프로파일에 적어 둔다)
   ▼
수집 컴퓨터가 받은 시각  ts_gateway
   → 정렬 시각  ts_ns          = ts_gateway − d
   → 불확도     uncertainty_ns = b + 컴퓨터 시계 오차
   → 등급       tier           = 불확도로 결정 (≤1 ms Tier-2, ≤100 ms Tier-3, 그 위 Tier-4)

채널별 모델 (프로파일 0.2.0, 컴퓨터 시계 오차는 측정값에 따라 다르다. 아래는 약 17 ms 일 때):

채널 시각 기준점 d (평균 지연) b (흔들림 폭) 불확도 = b + 시계 등급 d·b 를 잰 방법
follower-arm/joint_state 모터 읽기 요청·응답 0.6 ms 5 ms 약 22 ms Tier-3 요청 직전·응답 직후 시각의 중간을 측정 순간으로, 왕복 시간 실측
leader-arm/joint_state 〃 0.6 ms 6 ms 약 23 ms Tier-3 〃
follower-arm/joint_command 모터 쓰기 0.1 ms 3 ms 약 20 ms Tier-3 〃
follower-arm/joint_health 모터 읽기 1.1 ms 4 ms 약 21 ms Tier-3 〃
wrist-cam/image 프레임 수신, 노출 중앙 기준 36 ms 31 ms 약 48 ms Tier-3 팔을 움직이며 영상 변화와 엔코더 움직임의 상관이 최대인 지연
top-cam/image 〃 40 ms 35 ms 약 52 ms Tier-3 〃
operator-console/episode 사람 입력 — — — Tier-U 사람 반응 지연은 잴 수 없어 추정하지 않는다

왜 Tier-3 인가. Tier-2 가 되려면 불확도가 1 ms 이하여야 한다. 지금은 컴퓨터 시계 오차(Wi-Fi NTP, 10~20 ms)만으로도 넘고, 관절의 흔들림 폭(USB 시리얼 왕복 3~6 ms)도 넘는다. 하드웨어 시각 기록(PTP 등)과 장치 자체 타임스탬프가 있어야 Tier-2 가 된다. 반대로 Tier-3 의 뜻은 "수십 ms 범위 안에서 채널끼리 비교해도 된다"이다. 관절 궤적과 영상 프레임을 맞추는 정도는 충분하다.

모델 값은 데이터셋 상세(4.2)의 채널 정보 latency_model 로 볼 수 있고, 레코드에서 직접 확인할 수도 있다.

F = "testbed/so101/cell-01/follower-arm/joint_state"
W = "testbed/so101/cell-01/wrist-cam/image"

profile = {c["channel_id"]: c for c in fab.dataset("plab-testbed-cell01")["channels"]}
b = fab.read(dataset_id="plab-testbed-cell01", channels=[F, W],
             start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:53:41+09:00",
             purpose="analysis", include_raw_times=True)

for ch in (F, W):
    m = profile[ch]["latency_model"]
    r = next(x for x in b.records if x["channel_id"] == ch)
    d = r["raw_times"]["ts_gateway_ns"] - r["ts_ns"]           # 받은 시각 − 정렬 시각 = 당긴 만큼
    clock = r["uncertainty_ns"] - m["bound_ns"]                 # 불확도 − 흔들림 폭 = 그때의 시계 오차
    print(f"{ch.split('cell-01/')[1]:24s} {profile[ch]['align_method']} "
          f"d={d / 1e6:.1f} ms (프로파일 {m['mean_ns'] / 1e6:.1f})  "
          f"불확도 {r['uncertainty_ns'] / 1e6:.0f} ms = b {m['bound_ns'] / 1e6:.0f} + 시계 {clock / 1e6:.0f}  → {r['tier']}")
# follower-arm/joint_state  M3 d=0.6 ms (프로파일 0.6)  불확도 22 ms = b 5 + 시계 17  → Tier-3
# wrist-cam/image           M3 d=36.0 ms (프로파일 36.0)  불확도 48 ms = b 31 + 시계 17  → Tier-3

이 지식으로 할 수 있는 것:

3.6 목적 purpose

모든 조회에 "무엇에 쓰려는지"를 밝힌다. 돌려받는 데이터는 목적과 상관없이 같다. 서버는 이 값으로 권한을 확인하고 기록(감사 로그)을 남긴다.

purpose 쓰는 경우
analysis 분석·탐색·그래프
display 화면 표시·재생 (대시보드, Foxglove)
training 모델 학습 데이터
evaluation 모델 평가
inference 운영 중인 모델의 추론 입력
audit 감사·검증 열람

권한은 "내 토큰 × 데이터셋 × 목적" 조합으로 주어진다 (2.1). 내 토큰에 허용된 목적은 fab.datasets() 의 allowed_purposes 에 나온다. 스냅샷(11장)은 training, evaluation, audit 에만 만들 수 있다.

4. 데이터 찾기 — 카탈로그

이 장부터의 예제는 fab = Fabric() (2장) 과 시각을 읽기 쉽게 바꾸는 kst() (3.4) 가 있다고 보고 쓴다. 예제의 날짜·시각은 테스트베드에 실제로 있는 녹화 구간이다 (에피소드 ep-20261116T085339Z, 2026-11-16 17:53:39~17:54:08 KST).

4.1 데이터셋 목록 fab.datasets()

for ds in fab.datasets():
    print(ds)
# {'dataset_id': 'plab-testbed-cell01', 'site_id': 'partridge-lab', 'modality': ['timeseries', 'image', 'event'],
#  'channel_count': 7, 'security_level': 'internal', 'allowed_purposes': ['analysis', 'display', 'training']}

권한이 있는 데이터셋만 나온다. 걸러 볼 수도 있다: fab.datasets(site_id="partridge-lab"), fab.datasets(modality="image"), fab.datasets(purpose="training").

필드 뜻
dataset_id 조회에 쓰는 이름
site_id 현장
modality 들어 있는 데이터 종류 (timeseries, image, event)
channel_count 채널 수
security_level open / internal / restricted (restricted 는 현장 안 소비자만)
allowed_purposes 내 키로 쓸 수 있는 목적

4.2 데이터셋 상세 fab.dataset(id)

채널마다 주기, 기대 등급, 데이터가 있는 기간, 메시지 수, 판본을 알려 준다. 어느 시각을 조회할지 정할 때 먼저 본다.

detail = fab.dataset("plab-testbed-cell01")
for c in detail["channels"]:
    p = c["data_period"]
    print(f"{c['channel_id'].split('cell-01/')[1]:28s} {c['sampling_rate_hz'] or '-':>5} Hz "
          f"{c['expected_tier']:7s} {kst(p['first_ns']) if p else '-'} ~ {kst(p['last_ns']) if p else '-'} "
          f"메시지 {c['message_count']:>7}  판본 {c['correction_versions']}")
필드 뜻
channels[].channel_id 채널 이름
channels[].signal_type continuous(연속 측정) / event(사건)
channels[].sampling_rate_hz 기대 주기 (이벤트 채널은 None)
channels[].expected_tier 이 채널이 정상일 때 나와야 하는 등급
channels[].align_method 정렬 방식. M3(지연 모델) / NONE(추정 안 함, Tier-U)
channels[].latency_model M3 지연 모델 {mean_ns(d), bound_ns(b), measured_at, method} (3.5). 없으면 None
channels[].time_origin, event_point 시각 기준점(gateway_poll, receiver, human_entry), 사건 시점(exposure_mid 등)
channels[].min_detectable_ns 이보다 짧은 간격의 두 사건은 구별할 수 없다 (보통 샘플 주기)
channels[].data_period {first_ns, last_ns} 저장된 데이터의 처음·마지막 시각 (없으면 None)
channels[].message_count 저장된 메시지 수
channels[].correction_versions 있는 판본 목록 (2 이상이 있으면 재정렬된 구간이 있다)
link_rules 연결키 규칙 (8장)
corrections 재정렬 알림: 언제 어느 채널·구간이 몇 판으로 다시 계산됐는지 (최근 100건)

data_period 는 전체의 처음과 끝일 뿐, 중간이 비어 있을 수 있다(장치를 켜 둔 시간에만 기록된다). 실제로 녹화된 구간을 찾으려면 에피소드 이벤트(7장)를 보거나, 넓은 구간을 조회해 gaps(6장)를 본다.

5. 구간 조회 — fab.read

5.1 기본

b = fab.read(dataset_id="plab-testbed-cell01",
             channels=["testbed/so101/cell-01/follower-arm/joint_state",
                       "testbed/so101/cell-01/leader-arm/joint_state"],
             start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:54:00+09:00",
             purpose="analysis")
print(b)                     # Batch(14394 records, 12 series, versions={...})
인자 기본값 설명
dataset_id — 조회할 데이터셋. snapshot_id 를 주면 생략
snapshot_id — 스냅샷으로 조회 (11장). 구간을 생략하면 스냅샷 전체
start, end — 구간 [start, end). 한 번에 최대 1시간 (넘으면 DAT-4002 → 5.7 처럼 나눠 받기)
window — {"start": …, "end": …} 로 구간을 줄 때 (start/end 대신)
channels 전부 고를 채널 (전체 이름). 관절 하나만 받는 기능은 없다 — 채널로 받고 select 로 고른다
purpose (필수) 3.6
min_tier "Tier-4" 이보다 낮은 등급 레코드 제외. "Tier-3" 이면 불확도 100 ms 넘는 것은 뺀다
include_unaligned False 미추정(Tier-U) 레코드도 포함. 에피소드 이벤트를 같이 받으려면 True
include_raw_times False 레코드에 원래 시각(raw_times)을 붙인다 (5.8)
link_keys, link_filter, link_ambiguous — 연결키 (8장)
format "arrow" "arrow"(압축 열 형식, 빠름) 또는 "json". 결과 사용법은 같다
data_ref — 다른 시스템이 넘겨준 data_ref 로 같은 요청을 만든다 (13장)
trace_id 자동 요청 추적 ID. 지정하지 않으면 서버가 만든다

결과가 크면 서버가 여러 조각으로 나눠 보내는데, SDK 가 끝까지 이어 받아 하나의 Batch 로 돌려준다. 조각 사이에 새 데이터나 재정렬본이 들어와도 첫 조각과 같은 판본으로 이어 받는다.

5.2 결과 Batch

속성·메서드 내용
b.series 시계열 전부. {"채널:tag": Series}
b.select(채널, tag) 시계열 하나 → Series
b.values, b.time_ns 시계열이 하나면 배열, 여럿이면 {"채널:tag": 배열}
b.images 영상 레코드 목록 (dict, 9장)
b.events 이벤트 레코드 목록 (dict, 7장)
b.records 모든 레코드 (dict 목록, 5.6)
b.by_modality(m) 종류별 레코드 ("timeseries", "image", "event")
b.table pyarrow.Table 원본 (format="arrow" 일 때). b.table.to_pandas() 로 바로 DataFrame
b.gaps 데이터가 빠진 구간 (6장)
b.quality 채널별 품질 요약 (6장)
b.versions 채널별 실제로 읽은 판본 {채널: 1}
b.window 실제로 적용된 구간 {start_ns, end_ns}
b.trace_id 요청 추적 ID — 문의할 때 알려 주면 서버 기록을 찾을 수 있다
b.snapshot_id 스냅샷으로 읽었으면 그 ID

Series 는 시계열 하나를 numpy 배열로 담는다. 배열들은 같은 길이이고 정렬 시각 순서다.

필드 형 내용
channel_id, tag, unit str 채널, 항목, 단위
time_ns int64 배열 정렬 시각 (UTC ns)
values float64 배열 값
tier str 배열 등급
uncertainty_ns int64 배열 불확도 (모르면 -1)

5.3 관절 하나 꺼내기

F = "testbed/so101/cell-01/follower-arm/joint_state"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[F],
             start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:54:00+09:00", purpose="analysis")

s = b.select(F, "elbow_flex/position")
print(s.unit, len(s.values))                                  # deg 1200
print("최소·최대", s.values.min(), s.values.max())
print("평균 주기 ms", (s.time_ns[-1] - s.time_ns[0]) / (len(s.time_ns) - 1) / 1e6)
print("불확도 최대 ms", s.uncertainty_ns.max() / 1e6)

5.4 모든 관절을 표 하나로 (pandas)

같은 채널의 tag 들은 같은 메시지에서 나왔으므로 시각이 정확히 같다. 시각을 인덱스로 붙이면 관절별 열이 된다.

import pandas as pd

F = "testbed/so101/cell-01/follower-arm/joint_state"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[F],
             start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:54:00+09:00", purpose="analysis")

df = pd.DataFrame({s.tag.split("/")[0]: pd.Series(s.values, index=pd.to_datetime(s.time_ns, utc=True))
                   for s in b.series.values()})
df.index = df.index.tz_convert("Asia/Seoul")
print(df.head())
#                                   elbow_flex  gripper  shoulder_lift  shoulder_pan  wrist_flex  wrist_roll
# 2026-11-16 17:53:40.000756+09:00    94.68      ...

긴 형식(한 줄 = 레코드 하나)이 편하면 arrow 표를 그대로 바꾼다.

import pandas as pd

b = fab.read(dataset_id="plab-testbed-cell01", channels=["testbed/so101/cell-01/follower-arm/joint_state"],
             start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:53:45+09:00", purpose="analysis")
long = b.table.to_pandas()[["ts_ns", "tag", "value", "unit", "tier", "uncertainty_ns"]]
wide = long.pivot(index="ts_ns", columns="tag", values="value")
print(long.shape, wide.shape)          # (1800, 6) (300, 6)

5.5 채널 사이 비교 — 리더암과 팔로우암

채널마다 측정 시각이 다르므로 같은 시각축으로 맞춘 뒤 비교한다. 아래는 팔로우암 시각에 리더암 값을 선형 보간해 추종 오차를 구한다.

import numpy as np

L = "testbed/so101/cell-01/leader-arm/joint_state"
F = "testbed/so101/cell-01/follower-arm/joint_state"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[L, F],
             start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:54:00+09:00", purpose="analysis")

for joint in ["shoulder_pan", "shoulder_lift", "elbow_flex", "wrist_flex", "wrist_roll", "gripper"]:
    lead, follow = b.select(L, f"{joint}/position"), b.select(F, f"{joint}/position")
    lead_at_follow = np.interp(follow.time_ns, lead.time_ns, lead.values)     # 팔로우 시각의 리더 값
    err = follow.values - lead_at_follow
    print(f"{joint:14s} 평균 오차 {err.mean():7.2f}  RMS {np.sqrt((err ** 2).mean()):6.2f}  {follow.unit}")

보간은 이 문서의 예제가 하는 것이다. 서버는 값을 만들어 내지 않는다(누락 구간도 채우지 않는다, 6장).

5.6 레코드 직접 보기

b.records 는 모든 레코드를 dict 로 준다. 모든 종류에 공통인 필드:

필드 뜻
channel_id 채널
seq 메시지 번호 (채널 안에서 고유). 같은 메시지에서 나온 시계열 tag 들은 같은 seq
ts_ns 정렬 시각
aligned 시각 추정 여부 (Tier-U 면 False)
tier, uncertainty_ns 등급, 불확도 (Tier-U 면 불확도 None)
quality GOOD / UNCERTAIN
correction_version 판본
modality timeseries / image / event
asset_id 장치 식별자 (aas://partridge-lab/testbed/so101/cell-01/follower-arm)

시계열 레코드에는 tag, value, unit, sampling_rate_hz 가 더 있다. 영상은 9장, 이벤트는 7장.

b = fab.read(dataset_id="plab-testbed-cell01", channels=["testbed/so101/cell-01/follower-arm/joint_health"],
             start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:53:43+09:00", purpose="analysis")
for r in b.records[:4]:
    print(kst(r["ts_ns"]), r["tag"], r["value"], r["unit"], r["tier"])

5.7 1시간보다 긴 구간

조회는 한 번에 1시간까지다. 더 길면 나눠 부르고 이어 붙인다. 구간이 [start, end) 이므로 경계에서 겹치거나 빠지지 않는다. 여러 시간을 통째로 파일로 받으려면 내보내기(12장)가 낫다.

import numpy as np
from databahn import to_ns

HOUR = 3600 * 10**9

def read_long(fab, start, end, **kw):
    """1시간씩 나눠 조회해 Batch 목록을 돌려준다."""
    s, e, out = to_ns(start), to_ns(end), []
    while s < e:
        out.append(fab.read(start=s, end=min(s + HOUR, e), **kw))
        s += HOUR
    return out

def concat(batches, channel, tag):
    parts = [b.select(channel, tag) for b in batches if f"{channel}:{tag}" in b.series]
    return np.concatenate([p.time_ns for p in parts]), np.concatenate([p.values for p in parts])

from datetime import datetime
from zoneinfo import ZoneInfo
seoul = ZoneInfo("Asia/Seoul")
batches = read_long(fab, datetime(2026, 11, 16, 17, 0, tzinfo=seoul), datetime(2026, 11, 16, 19, 30, tzinfo=seoul),
                    dataset_id="plab-testbed-cell01", channels=["testbed/so101/cell-01/follower-arm/joint_health"],
                    purpose="analysis")
t, v = concat(batches, "testbed/so101/cell-01/follower-arm/joint_health", "gripper/temperature")
print(len(batches), "번 조회,", len(v), "점, 그리퍼 온도 최고", v.max(), "degC")

5.8 원래 시각 보기 (include_raw_times)

정렬 시각이 어떻게 나왔는지 확인하고 싶을 때 쓴다. 분석에는 정렬 시각만 쓴다.

b = fab.read(dataset_id="plab-testbed-cell01", channels=["testbed/so101/cell-01/follower-arm/joint_state"],
             start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:53:41+09:00", purpose="analysis",
             include_raw_times=True)
r = b.records[0]
print(r["ts_ns"], r["raw_times"])
# raw_times = {ts_source_ns: 장치 자체 시각(없으면 None), ts_gateway_ns: 수집기가 받은 시각, ts_ingest_ns: 셀 로거가 받은 시각}

5.9 arrow 와 json

기본 format="arrow" 는 열 단위 압축 형식으로 받아 numpy 로 바로 바꾼다. 수십만 레코드도 빠르다. format="json" 은 사람이 읽기 쉬운 대신 크고 느리다. 결과 사용법(select, records 등)은 같고, b.table 만 arrow 일 때 있다.

6. 품질 정보 — 누락, 등급, 판본

서버는 값을 보간하거나 지어내지 않는다. 대신 무엇이 빠졌고 얼마나 믿을 수 있는지를 함께 준다. 분석 전에 확인한다.

6.1 누락 구간 b.gaps

기대 주기의 3배 넘게 기록이 없으면 누락으로 본다.

F = "testbed/so101/cell-01/follower-arm/joint_state"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[F],
             start="2026-11-16T19:26:00+09:00", end="2026-11-16T19:26:20+09:00", purpose="analysis")
for g in b.gaps:
    print(g["channel_id"].split("cell-01/")[1], kst(g["start_ns"]), "~", kst(g["end_ns"]), g["reason"])
# follower-arm/joint_state 2026-11-16 19:26:00.000 ~ 2026-11-16 19:26:02.577 no_data
# follower-arm/joint_state 2026-11-16 19:26:10.930 ~ 2026-11-16 19:26:20.000 no_data
reason 뜻
no_data 구간 앞이나 뒤가 통째로 비었다 (장치가 꺼져 있었음)
missing 기록 중간에 빠졌다 (통신 끊김 등)

6.2 품질 요약 b.quality

for ch, q in b.quality.items():
    print(ch.split("cell-01/")[1], q)
# follower-arm/joint_state {'tier': {'Tier-3': 1.0}, 'max_uncertainty_ns': 15000000, 'missing_ratio': 0.582,
#                           'excluded_count': 0, 'delivery_delay': {'p50_ns': 344500, 'p95_ns': 643000}}
필드 뜻
tier 등급 분포 (비율)
max_uncertainty_ns 가장 큰 불확도
missing_ratio 구간 중 누락 비율 (0~1). 위 예는 20초 중 58% 가 비었다
excluded_count min_tier·미추정 때문에 뺀 레코드 수
delivery_delay 측정 순간부터 서버에 들어오기까지 걸린 시간 (p50, p95)

quality 에는 요청한 채널이 모두 들어 있다. 데이터가 없는 채널은 missing_ratio 가 1.0 이다. 조건에 맞는 레코드가 하나도 없어도 오류가 아니다 — 빈 Batch 가 온다. len(b.records) == 0 이나 missing_ratio 로 확인한다.

6.3 등급으로 거르기

b = fab.read(dataset_id="plab-testbed-cell01", start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:53:50+09:00",
             purpose="analysis", min_tier="Tier-3")          # 불확도 100 ms 넘는 레코드는 뺀다
print({ch.split("cell-01/")[1]: q["excluded_count"] for ch, q in b.quality.items()})

s = b.select("testbed/so101/cell-01/follower-arm/joint_state", "gripper/position")
tight = s.values[(s.uncertainty_ns >= 0) & (s.uncertainty_ns <= 25_000_000)]   # 더 엄격하게: 불확도 25 ms 이내만
print(len(s.values), len(tight))     # 600 600  (이 구간의 관절은 모두 22 ms 이내)

6.4 판본

print(b.versions)      # {'testbed/so101/cell-01/follower-arm/joint_state': 1, ...}

같은 구간도 나중에 재정렬되면(시각 계산을 고쳐 다시 기록) 판본이 올라가고, 조회는 새 판본을 준다. 그래서 같은 요청이라도 시점에 따라 값이 조금 달라질 수 있다. 결과를 고정해야 하면 스냅샷(11장)을 쓴다. 재정렬이 있었는지는 fab.dataset(id)["corrections"] 에 나온다.

7. 이벤트 — 작업(에피소드)

작업자는 콘솔에서 작업 시작(start)과 끝(ok/fail)을 입력한다. 서버는 이 입력을 에피소드 구간 이벤트로 묶어 준다. 작업자 입력은 시각을 추정할 수 없어(사람의 반응 지연) Tier-U 이므로 include_unaligned=True 가 필요하다.

7.1 에피소드 목록

ev = fab.events(dataset_id="plab-testbed-cell01",
                start="2026-11-16T00:00:00+09:00", end="2026-11-17T00:00:00+09:00",
                purpose="analysis", include_unaligned=True, event_types=["episode"])
for e in ev["events"]:
    print(e["episode_id"], kst(e["start_ns"]), "~", kst(e["end_ns"]),
          f"{(e['end_ns'] - e['start_ns']) / 1e9:.1f}초", e["task"], e["inspection_result"],
          "폐기" if e["discarded"] else "", e["status"])
# ep-20261116T085339Z 2026-11-16 17:53:39.657 ~ 2026-11-16 17:54:08.453 28.8초 칼집기 success  closed
인자 설명
dataset_id / snapshot_id, start, end, window, channels, purpose, min_tier, include_unaligned read 와 같다
event_types 고를 종류. 생략하면 전부 (episode 구간 + 아래 점 이벤트)
(구간 한도) 이벤트 조회는 한 번에 31일까지 (값 조회의 1시간보다 길다)

에피소드(event_type == "episode") 필드:

필드 뜻
episode_id (= event_id) 에피소드 ID (ep-<시작 UTC>)
start_ns, end_ns 시작·끝 시각 (작업자 입력 시각)
task 작업 이름
operator_id 작업자
inspection_result success(ok) / fail
discarded 작업자가 이 에피소드를 폐기했는지 (discard). 학습에서 빼야 한다
marks_ns 작업 중 표시(mark)한 시각 목록
status closed(시작·끝 다 있음) / open(아직 안 끝남) / start_unknown(시작이 구간 밖)
derived_from 이 구간을 만든 점 이벤트들의 ID

점 이벤트(event_types 로 고른다): episode_start, episode_stop, episode_discard, episode_mark. 필드는 같고 start_ns == end_ns, 작업자가 쓴 메모는 note, 콘솔 입력 시각은 ts_entry_ns.

응답의 나머지 키: versions(판본), window(적용 구간), excluded_count, trace_id.

7.2 성공률 집계

from collections import Counter

ev = fab.events(dataset_id="plab-testbed-cell01", start="2026-11-01T00:00:00+09:00", end="2026-12-01T00:00:00+09:00",
                purpose="analysis", include_unaligned=True, event_types=["episode"])["events"]
valid = [e for e in ev if e["status"] == "closed" and not e["discarded"]]
print(Counter((e["task"], e["inspection_result"]) for e in valid))
print("평균 작업 시간", sum(e["end_ns"] - e["start_ns"] for e in valid) / len(valid) / 1e9, "초")

8. 연결키 — 특정 작업의 데이터만

에피소드 구간 안에 든 관절·영상 데이터를 "그 에피소드의 데이터"로 고르는 기능이다. 데이터셋의 link_rules 에 정의되어 있고, 테스트베드의 연결키는 episode_id 하나다.

ep = "ep-20261116T085339Z"
F = "testbed/so101/cell-01/follower-arm/joint_state"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[F],
             start="2026-11-16T17:53:00+09:00", end="2026-11-16T17:55:00+09:00",
             purpose="analysis", link_filter={"episode_id": ep})
s = b.select(F, "gripper/position")
print(len(s.values), kst(s.time_ns[0]), "~", kst(s.time_ns[-1]))
# 1605 2026-11-16 17:53:40.684 ~ 2026-11-16 17:54:07.425   (에피소드 17:53:39.657~17:54:08.453 의 경계 ±약 1초 안쪽만)

조회 구간(start~end)은 에피소드를 덮도록 넉넉히 준다. 에피소드 시각은 7장으로 찾는다.

경계 판정. 작업자 입력 시각은 약 1초 불확도가 있어서 경계 근처 데이터는 확실히 안인지 밖인지 알 수 없다.

판정 조건 기본 동작
inside 두 경계 모두와의 시각 차가 (데이터 불확도 + 경계 불확도)보다 크다 포함
ambiguous 경계와 너무 가깝다 제외 (link_ambiguous="include" 면 포함)
(없음) 구간 밖 제외

거르지 않고 레코드마다 어느 에피소드에 속하는지만 붙이려면 link_keys 를 쓴다.

b = fab.read(dataset_id="plab-testbed-cell01", channels=["testbed/so101/cell-01/follower-arm/joint_state"],
             start="2026-11-16T17:53:38+09:00", end="2026-11-16T17:53:42+09:00", purpose="analysis",
             link_keys=["episode_id"])
from collections import Counter
print(Counter(str((r.get("links") or {}).get("episode_id", {}).get("match")) for r in b.records))
# Counter({'None': ..., 'ambiguous': ..., 'inside': ...})   — None 은 어느 에피소드에도 안 속함

9. 영상

9.1 영상 레코드

조회 결과의 영상 레코드에는 이미지 본문 대신 본문을 받을 수 있는 참조(content_ref)가 들어 있다. 수천 장을 한꺼번에 받지 않고 필요한 프레임만 받기 위해서다.

W = "testbed/so101/cell-01/wrist-cam/image"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[W],
             start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:53:41+09:00", purpose="analysis")
print(len(b.images), "프레임")             # 29 (30 fps, 1초)
img = b.images[0]
print({k: img[k] for k in ["ts_ns", "format", "resolution", "is_keyframe", "uncertainty_ns", "content_hash"]})
필드 뜻
ts_ns 노출 중앙 시각 (정렬 시각)
format, resolution jpeg, 640x480
content_ref 본문 참조. fab.content 에 넘긴다. 서버가 서명한 값이라 고치면 거부된다
content_hash 본문 sha256. 받은 바이트를 확인할 수 있다
is_keyframe JPEG 는 모든 프레임이 독립이라 늘 True
roi, product_key 테스트베드는 None

9.2 이미지 받기·저장·디코드

import hashlib
from pathlib import Path

jpeg = fab.content(img["content_ref"], purpose="analysis")       # bytes
assert hashlib.sha256(jpeg).hexdigest() == img["content_hash"]
Path("frames").mkdir(exist_ok=True)
Path(f"frames/wrist_{img['ts_ns']}.jpg").write_bytes(jpeg)

import io
from PIL import Image
im = Image.open(io.BytesIO(jpeg))
print(im.size, im.mode)                    # (640, 480) RGB
# numpy 배열: np.asarray(im)   /  OpenCV: cv2.imdecode(np.frombuffer(jpeg, np.uint8), cv2.IMREAD_COLOR)

9.3 프레임과 같은 순간의 관절 값

영상과 관절은 주기가 다르므로 프레임 시각에 가장 가까운 관절 샘플을 찾는다.

import numpy as np

W = "testbed/so101/cell-01/wrist-cam/image"
F = "testbed/so101/cell-01/follower-arm/joint_state"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[W, F],
             start="2026-11-16T17:53:45+09:00", end="2026-11-16T17:53:46+09:00", purpose="analysis")
grip = b.select(F, "gripper/position")
for img in b.images[::10]:                                       # 3장만
    i = np.clip(np.searchsorted(grip.time_ns, img["ts_ns"]), 1, len(grip.time_ns) - 1)
    i = i - 1 if img["ts_ns"] - grip.time_ns[i - 1] < grip.time_ns[i] - img["ts_ns"] else i
    gap_ms = abs(int(grip.time_ns[i]) - img["ts_ns"]) / 1e6
    print(kst(img["ts_ns"]), f"그리퍼 {grip.values[i]:.1f}", f"(시각 차 {gap_ms:.1f} ms,",
          f"불확도 영상 {img['uncertainty_ns'] / 1e6:.0f} ms / 관절 {grip.uncertainty_ns[i] / 1e6:.0f} ms)")

시각 차가 두 불확도보다 작으면 "같은 순간"으로 볼 수 있다. 테스트베드에서는 수십 ms 단위까지만 의미가 있다.

10. 최신값

채널마다 마지막으로 저장된 값을 준다. 대시보드의 "현재 상태" 같은 데 쓴다.

lat = fab.latest(dataset_id="plab-testbed-cell01", purpose="display",
                 channels=["testbed/so101/cell-01/follower-arm/joint_health"])["latest"]
for ch, v in lat.items():
    print(ch.split("cell-01/")[1], kst(v["ts_ns"]), f"{v['age_ns'] / 1e9:.0f}초 전")
    for r in v["records"][:4]:
        print("   ", r["tag"], r["value"], r["unit"])
필드 뜻
ts_ns 마지막 메시지의 정렬 시각
age_ns 지금으로부터 얼마나 지났는지
records 그 메시지의 레코드들 (관절 tag 전부)
correction_version, closed_until_ns 판본, 저장이 끝난 시각

실시간이 아니다. 서버는 저장이 끝난 파일만 보므로, 기록 중인 데이터는 파일이 닫히는(최대 10분) 뒤에 나타난다.

11. 스냅샷 — 학습 데이터 고정

조회는 늘 최신 판본을 주므로 같은 요청도 나중에 결과가 달라질 수 있다(6.4). 학습·평가는 같은 데이터를 다시 읽을 수 있어야 하므로 "이 구간·이 채널의 지금 판본 파일 목록"을 고정해 이름(snapshot_id)을 붙인다. 같은 snapshot_id 는 언제 읽어도 같은 데이터다.

11.1 만들기

snap = fab.create_snapshot(
    dataset_id="plab-testbed-cell01",
    start="2026-11-16T17:53:39+09:00", end="2026-11-16T17:54:09+09:00",
    channels=["testbed/so101/cell-01/leader-arm/joint_state",
              "testbed/so101/cell-01/follower-arm/joint_state",
              "testbed/so101/cell-01/wrist-cam/image"],
    purpose="training", label="grip-2026w47")
print(snap["snapshot_id"], snap["file_count"], snap["status"])
인자 설명
dataset_id, start/end (또는 window) 고정할 범위. 길이 제한은 없다. 범위에 저장된 파일이 하나도 없으면 DAT-4001
channels 고를 채널. 생략하면 전부
purpose training / evaluation / audit 중 하나
label 사람이 알아볼 이름 (선택)

응답 필드:

필드 뜻
snapshot_id 이후 조회·내보내기에 쓰는 ID
scope {dataset_id, channels, window} 고정한 범위
items 채널별 {file_count, correction_version, hash_digest} — 고정된 파일과 판본
coverage 채널별 실제 데이터의 처음·끝
status active / released(더 이상 보존하지 않음)
referenced_by 이 스냅샷으로 학습한 모델 목록
algorithm_version 판본 선택 방식 버전

11.2 읽기·목록

sid = fab.snapshots("plab-testbed-cell01")[0]["snapshot_id"]       # 목록은 최신순 → 방금 만든 것
b = fab.read(snapshot_id=sid, purpose="training")                   # 구간을 생략하면 스냅샷 전체
print(b, b.snapshot_id, b.window)
ev = fab.events(snapshot_id=sid, purpose="training", include_unaligned=True)   # 이벤트도 같은 방식
print(fab.snapshot(sid)["scope"])

스냅샷의 일부 구간만 읽으려면 start/end 를 함께 준다. 나중에 재정렬본이 생겨도 스냅샷은 고정된 판본을 계속 준다. read 의 1시간 한도는 스냅샷에도 적용된다(스냅샷 구간으로 자른 뒤의 길이 기준). 1시간 넘는 스냅샷은 start/end 로 나눠 읽거나 Parquet 로 내보낸다(12장).

11.3 모델 기록

스냅샷으로 학습한 모델을 기록해 두면 "이 모델은 어떤 데이터로 학습했나"를 추적할 수 있고, 그 스냅샷의 파일은 보존된다.

fab.add_model_reference(sid, package_id="pkg-grip-policy", version="1.0.0")
print(fab.snapshot(sid)["referenced_by"])

12. 내보내기 — 파일로 받기

조회는 1시간 한도가 있고 메모리로 받는다. 큰 데이터를 파일로 받으려면 내보내기를 쓴다. 서버가 뒤에서 파일을 만들고(비동기 작업), 다 되면 내려받는다.

kind 형식 쓰는 곳 범위
"parquet" 종류별 Parquet + manifest.json 학습 (pandas, PyTorch 등) 스냅샷 필수
"mcap" MCAP 파일 하나 Foxglove 재생, ROS 도구 데이터셋 + 구간, 또는 스냅샷

내보내기는 데이터를 밖으로 가져가는 일이라 조회보다 한 단계 더 확인한다: 내 토큰의 현장이 데이터셋 현장과 다르면(현장 밖) internal 데이터는 내보내기 승인(export_scope=off_site_approved)이 있어야 하고, restricted 는 내보낼 수 없다 (2.1). 승인이 없으면 DAT-4031 "현장 밖 내보내기 승인 없음". 같은 확인을 파일을 받을 때 한 번 더 한다.

12.1 Parquet (학습용)

job = fab.export("parquet", snapshot_id=sid, purpose="training")
job.wait()                                    # 끝날 때까지 기다린다 (기본 600초)
paths = job.download("out/train")             # 받으면서 sha256 확인
print([p.name for p in paths])                # ['image.parquet', 'timeseries.parquet', 'manifest.json']

import pandas as pd
ts = pd.read_parquet("out/train/timeseries.parquet")
print(ts.columns.tolist())
print(ts.groupby(["channel_id", "tag"]).size().head())
파일 내용 (열)
timeseries.parquet channel_id, seq, ts_ns, aligned, tier, uncertainty_ns, quality, correction_version, ts_gateway_ns, ts_ingest_ns, asset_id, tag, value, unit, sampling_rate_hz
image.parquet 위 공통 열 + format, resolution, content_hash, content_ref (본문은 fab.content 로)
event.parquet 이벤트가 있을 때. 7장의 필드
manifest.json 요청 범위, 파일별 크기·sha256·레코드 수, gaps, quality_summary, 판본

12.2 MCAP (Foxglove 재생용)

job = fab.export("mcap", dataset_id="plab-testbed-cell01",
                 start="2026-11-16T17:53:39+09:00", end="2026-11-16T17:54:09+09:00",
                 channels=["testbed/so101/cell-01/leader-arm/joint_state",
                           "testbed/so101/cell-01/follower-arm/joint_state"],
                 purpose="display")
paths = job.wait().download("out/mcap")
print(paths[0], paths[0].stat().st_size // 1024, "KB")

12.3 내보내기 인자와 작업 객체

fab.export 인자 설명
kind "parquet" / "mcap"
snapshot_id 또는 dataset_id + start/end 범위. parquet 는 스냅샷만
channels, min_tier, include_unaligned 조회와 같다
purpose 목적. 학습용은 training
label 사람이 알아볼 이름
ExportJob 내용
job.export_id 작업 ID
job.status 마지막으로 받은 상태 dict. status 는 PENDING → RUNNING → SUCCEEDED / FAILED
job.refresh() 상태를 다시 받는다
job.wait(timeout=600, poll=1.0) 끝날 때까지 기다린다. 실패면 FabricError, 시간 초과면 TimeoutError
job.files 결과 파일 목록 [{name, size, sha256}]
job.download(폴더) 모두 내려받고 sha256 을 확인해 경로 목록을 돌려준다

기다리지 않고 나중에 받으려면 export_id 를 저장해 두었다가 작업 객체를 다시 만든다.

from databahn import ExportJob

eid = job.export_id                                   # 저장해 둔 ID
again = ExportJob(fab, {"export_id": eid, "status": "PENDING"}).wait()
print(again.status["status"], [f["name"] for f in again.files])

12-1. 데이터 사전 매핑 — 채널의 뜻을 표준 항목으로

데이터 사전(항목 ID·이름·정의·단위)은 TTA 가 관리한다. 조회 서비스는 "이 채널(또는 필드)은 사전의 어느 항목인가"라는 매핑만 등록·조회한다. 같은 항목을 가진 다른 설비의 채널을 찾거나, 모델 입력(IF-20 semantic_id)을 어느 설비에 붙일 수 있는지 볼 때 쓴다.

# 조회 (인증된 누구나)
m = fab.mapping("channel", "testbed/so101/cell-01/follower-arm/joint_state")
print(m["active"])            # 지금 매핑 (없으면 None): dict_item_id, dict_version, verification …
for x in fab.mappings_for_item("TTA-GRIP-POS"):   # 같은 사전 항목을 가진 채널·필드
    print(x["target_type"], x["target_id"])
print(fab.dataset("plab-testbed-cell01")["channels"][0]["semantic_id"])   # 카탈로그에도 나온다

등록·교체·사용 중지는 관리 권한(dict_admin) 토큰만 할 수 있다.

m1 = fab.register_mapping("tag", "testbed/so101/cell-01/follower-arm/joint_state#gripper/position", "TTA-GRIP-POS", "1")
m2 = fab.register_mapping("tag", m1["target_id"], "TTA-GRIP-POS", "2", replaces=m1["mapping_id"])  # 새 버전으로 교체
fab.deprecate_mapping(m2["mapping_id"])                                                           # 사용 중지 (지우지 않음)
알아 둘 것
대상 channel, field(규약 필드 이름, 예 ts_aligned), dataset_field, tag(<채널>#<tag>, 테스트베드 확장)
교체 활성 매핑이 있는 대상에 다른 항목을 등록하려면 replaces=<지금 mapping_id>. 없으면 DAT-4093. 같은 매핑을 다시 등록하면 그대로 (created=False)
verification TTA 사전 연동 전에는 unverified (항목이 실제로 있는지 확인 못 함). 연동 뒤 관리자가 다시 확인한다
보이는 범위 채널·tag 매핑은 그 데이터셋 권한이 있어야 보인다

모델 입력을 사전 항목으로 선언할 때(IF-20 data_requirements) 쓰는 두 함수:

fab.semantic_of(channel_id, tag=None)        # 채널(또는 tag)의 지금 사전 항목. tag 매핑이 우선
fab.resolve_semantic("plab-testbed-cell01", "TTA-GRIP-POS", select={"channel": "*/follower-arm/*"})
# → [{"channel_id", "tag", "target_type", "mapping_id", "dict_version"}]  비면 대응 없음, 둘 이상이면 select 를 좁힌다

12-2. 창 — 모델 입력 텐서 만들기 (databahn.window)

모델 입력은 "구간 하나 → 고정 칸 수 텐서"다. 학습(스냅샷을 내보낸 parquet)과 추론(IF-03 조회)이 같은 규칙으로 텐서를 만들어야 학습과 서빙이 어긋나지 않는다. 창을 직접 자르지 말고 이 모듈을 쓴다 (IF-20 데이터 요구의 규칙과 같다).

from databahn import window as W

JOINTS = [f"{j}/position" for j in ("shoulder_pan", "shoulder_lift", "elbow_flex", "wrist_flex", "wrist_roll", "gripper")]
spec = W.Spec(window_ns=1_000_000_000, steps=60, min_tier="Tier-3", max_missing_ratio=0.05, inputs=[
    W.Input("state", channel="testbed/so101/cell-01/follower-arm/joint_state", tags=JOINTS),   # tags = 마지막 축 순서
])

w = W.read(fab, spec, dataset_id="plab-testbed-cell01", start="2026-11-16T17:53:40+09:00", purpose="analysis")
w.tensors["state"].shape      # (60, 6) float32, 빈 칸은 NaN
w.missing_ratio, w.quality    # {"state": 0.0}, {"tier": {...}, "min_tier": "Tier-3", "versions": {채널: [판본]}}

ws = W.from_export("내려받은_내보내기_폴더", spec, stride_ns=500_000_000)   # 학습: 창 여러 개 [N, 60, 6]
spec.requirements(modes=["sync"])                                         # IF-20 manifest 의 data_requirements
규칙
시간축 정렬 시각만. 미추정(Tier-U)과 min_tier 미달은 뺀다
격자 창 [start, start + window_ns) 를 steps 칸으로(정수 경계). 칸마다 그 칸 안의 마지막 값
누락 보간하지 않는다. 빈 칸은 NaN (fill="hold" 면 앞 칸 값 유지). 누락 비율 = 빈 칸 / 전체 칸. max_missing_ratio 를 넘는 창은 학습에서 빠지고(dropped), 추론에서는 usable() 가 False
tag 채널에 데이터가 있는데 요청한 tag 가 없으면 오류 (빈 구간은 NaN, tag 이름 실수는 오류). 관절 명령의 tag 는 <관절>/sent_position·requested_position
격자 칸 수 표본 주기보다 넓게 잡는다. 60 Hz 관절을 60칸/초로 나누면 표본 간격 흔들림으로 빈 칸이 생긴다 (실측: 30칸이면 모든 창이 누락 5% 이하)
채널 고르기 channel(채널 ID·패턴) 또는 semantic_id + select(12-1). spec.resolve(fab, 데이터셋) 이 하나로 풀리지 않으면 WindowError (none·ambiguous)
학습 → 사전 항목 spec.with_semantics(fab): 채널로 정의한 입력에 IF-03 매핑의 semantic_id 와 select(장치 패턴)를 채운다

12-3. 모델 추론 — databahn.Models (IF-20)

학습한 모델은 IF-20 게이트웨이에 등록·배포되고, 추론도 게이트웨이로 부른다. Models 는 그 클라이언트다. 토큰은 IF-03 과 같다. 다만 토큰에 IF-20 권한(scope)이 붙어 있어야 한다: 추론 if20.infer, 조회 if20.read, 배포·롤백 if20.deploy (관리자에게 요청). HTTP 형식은 API 명세 10장.

from databahn import Models

m = Models("https://if20.data-bahn.com", site_id="partridge-lab")   # 키는 Fabric 과 같은 환경 변수에서
# 주소를 빼면 IF20_URL, 그다음 FABRIC_URL (IF-03 주소로도 /if20 이 연결된다)

m.health()                       # {"status": "DEGRADED", "endpoints": [{..., "current": {"version": "0.1.0", "ready": True}, "previous": None}]}
m.deployments()                  # [{"package_id": "so101-tracking-baseline", "version": "0.1.0", "role": "current", ...}]
m.metadata("so101-tracking-baseline")["inputs"]
# [{'name': 'command', 'datatype': 'FP32', 'shape': [-1, 30, 6]}, {'name': 'state', 'datatype': 'FP32', 'shape': [-1, 30, 6]}]

12-3.1 참조 전달 — 데이터 위치만 보낸다

데이터셋과 창 시작만 주면 게이트웨이가 모델의 데이터 요구(창 1초, 30칸, Tier-3 이상, 누락 5% 이하)대로 IF-03 에서 읽는다. 읽는 권한은 내 토큰의 inference 권한으로 판정한다 (게이트웨이가 내 대신 읽고, IF-03 접근 기록에 내 이름이 남는다).

p = m.infer("so101-tracking-baseline", dataset_id="plab-testbed-cell01", start="2026-11-18T11:10:20Z")
p.value          # array([[2.2844577]], dtype=float32)  — 출력이 하나면 그 배열 (여럿이면 p.outputs[이름])
p.version        # '0.1.0'  — 이 현장의 current
p.latency_ms     # 122.4    — 게이트웨이 처리 시간
p.data_quality   # {'tier': {'Tier-3': 1.0}, 'min_tier': 'Tier-3', 'missing_ratio': {'command': 0.0, 'state': 0.0}}
p.data_window    # {'start_ns': ..., 'end_ns': ..., 'if03_dataset': 'plab-testbed-cell01', 'time_basis': 'aligned'}
p.semantic_resolution   # 입력 → 채널 (배포 때 사전 매핑으로 고정한 것)
p.semantic_drift        # [] — 고정한 매핑이 그 뒤 사용 중지되면 여기에 (아래)
p.trace_id

매핑이 바뀌면 (semantic_drift): 사전 관리자가 채널의 매핑을 새 판으로 교체해도 이미 배포된 모델의 입력은 바뀌지 않는다. 고정한 채널로 계속 추론하고, 응답에 사용 중지된 매핑과 대체 매핑을 알린다. 다시 배포할지는 운영 기관이 정한다.

for d in p.semantic_drift:
    print(d["input"], d["mapping_id"], d["status"], "→ 대체", d["replacement"])
# state map-… deprecated → 대체 {'mapping_id': 'map-…', 'dict_item_id': '…', 'dict_version': '2'}

end 를 주면 모델 창 길이와 같아야 한다. 다른 시스템에서 받은 data_ref(13장)는 m.infer(pkg, data_ref=ref) 로 그대로.

12-3.2 값 전달 — 내가 만든 텐서를 보낸다

12-2 의 창 모듈로 만든 Window 를 그대로 넘기면 텐서와 창 구간이 함께 간다. 같은 창이면 참조 전달과 결과가 같다.

from databahn import Fabric, window

fab = Fabric("https://if03.data-bahn.com")
man = m.version("so101-tracking-baseline", "0.1.0")["manifest"]
spec = window.Spec.from_requirements(man["data_requirements"])          # 모델과 같은 창 규칙
w = window.read(fab, spec, dataset_id="plab-testbed-cell01", start="2026-11-18T11:10:20Z", purpose="inference")
m.infer("so101-tracking-baseline", window=w).value                      # array([[2.2844577]]) — 참조 전달과 같다

배열을 직접 줄 때는 그 배열을 만든 창 구간(data_window)을 함께 준다. 2차원 [칸, 원소] 는 배치 축을 붙여 보낸다. NaN 은 빈 칸으로 간다.

import numpy as np
m.infer("so101-tracking-baseline",
        inputs={"state": state_30x6, "command": command_30x6},
        data_window={"start_ns": t0, "end_ns": t0 + 1_000_000_000})

값 전달에서는 데이터 품질·판본을 게이트웨이가 모른다 (p.data_quality is None). 품질 확인은 w.missing_ratio·w.quality 로 직접.

12-3.3 버전 고르기, 시간 제한

m.infer(pkg, version="0.2.0", dataset_id=..., start=...)   # current 가 아닌 버전 (previous 로 비교할 때)
m.infer(pkg, ..., timeout_ms=10_000)                        # 동기 제한, 기본 3초·최대 10초 (넘으면 MDL-5040)
m.infer(pkg, ..., trace_id="tr-my-run-001")                 # 내 추적 ID — 감사 기록·IF-03 접근 기록까지 이어진다

12-3.4 패키지 찾기

m.packages()                                        # [{"package_id", "version", "semantic_ids", "lifecycle", "owner"}]
m.packages(semantic_id="<사전 항목>")                # 그 물리량을 입력으로 쓰는 모델만
v = m.version("so101-tracking-baseline", "0.1.0")
v["manifest"]["inputs"], v["training_history"]["snapshot_id"], v["deployments"]
m.applicability("so101-tracking-baseline", "0.2.0")["applicable"]   # 이 현장 데이터로 입력을 풀 수 있는지

12-3.5 배포·롤백 (scope if20.deploy)

job = m.deploy("so101-tracking-baseline", "0.2.0")        # 끝날 때까지 기다린다 (실측 약 9초)
job.result["resolved_inputs"]                             # 배포 때 고정한 입력 채널
m.rollback("so101-tracking-baseline", reason="점수 이상") # {"current": "0.1.0", "rolled_back": "0.2.0", ...}
r = Models("https://if20.data-bahn.com")                       # 연구자 토큰
r.deploy("so101-tracking-baseline", "0.4.0", site_id="partridge-lab-test")
r.infer("so101-tracking-baseline", site_id="partridge-lab-test", dataset_id="plab-testbed-cell01", start="…").value

12-3.6 오류

from databahn import ModelError

try:
    m.infer("so101-tracking-baseline", dataset_id="plab-testbed-cell01", start="2026-11-18T09:00:00Z")  # 녹화 없는 시각
except ModelError as e:
    print(e.code, e.cause, e.p4_code, e.retryable, e.message, e.trace_id)
    print(e.detail)
# MDL-4221 None None False 누락 비율 1.000 > 허용 0.05 tr-…
# {'data_quality': {'tier': {}, 'min_tier': None, 'missing_ratio': {'command': 1.0, 'state': 1.0}}}
코드 흔한 원인 대응
MDL-4031 scope 없음, 또는 그 데이터셋의 inference 권한 없음(e.cause = DAT-4031) 관리자에게 권한 요청
MDL-4042 현장에 배포된 버전 없음, 롤백할 previous 없음 m.deployments() 확인
MDL-4221 창에 데이터가 모자람(녹화 없는 구간·누락 5% 초과·등급 미달), 값 전달 shape 불일치 녹화가 있는 시각으로, e.detail 확인
MDL-5031·5040 서빙 준비 중, 시간 제한 초과 SDK 가 MDL-5031 은 자동 재시도. 5040 은 timeout_ms 를 늘리거나 다시

전체 표는 API 명세 10.7.

13. data_ref — 다른 시스템과 같은 데이터 가리키기

다른 시스템(IF-20 등)이 "이 데이터"를 가리킬 때 data_ref 라는 dict 를 넘긴다. 받은 쪽은 그대로 read 에 넘기면 같은 요청이 된다.

ref = {"if03_dataset": "plab-testbed-cell01",
       "channels": ["testbed/so101/cell-01/follower-arm/joint_state"],
       "window": {"start": "2026-11-16T17:53:40+09:00", "end": "2026-11-16T17:53:41+09:00"},
       "min_tier": "Tier-3"}
b = fab.read(data_ref=ref, purpose="analysis")
print(b)

data_ref 의 키: if03_dataset 또는 snapshot_id, channels, window, min_tier. 학습 데이터를 가리킬 때는 snapshot_id 를 쓴다(값이 고정).

14. 오류 처리

서버 오류는 모두 FabricError 로 온다. (모델 추론 Models 의 오류는 ModelError, 12-3.6)

from databahn import FabricError

try:
    fab.read(dataset_id="plab-testbed-cell01", start="2026-11-16T17:00:00+09:00",
             end="2026-11-16T18:30:00+09:00", purpose="analysis")
except FabricError as e:
    print(e.code, e.status, e.message, e.trace_id)
# DAT-4002 400 구간이 한도(3600초)를 넘음. 나눠서 조회하거나 내보내기를 쓰세요 tr-…
코드 HTTP 뜻 대응
DAT-4001 400 요청 형식 오류 (필수 값 없음, 구간 역전, 시간대 없는 시각, 잘못된 값) 메시지대로 요청 수정
DAT-4002 400 구간·응답 크기 한도 초과 (조회 1시간) 나눠 조회(5.7) 또는 내보내기(12장)
DAT-4011 404 데이터셋에 없는 채널, 또는 남의 내보내기 작업 채널 이름 확인 (fab.dataset(id)["channels"])
DAT-4031 403 권한 없음: 토큰이 틀리거나 만료됨, 그 데이터셋·목적 권한 없음(데이터셋 이름이 틀려도 같다), 현장 밖 내보내기 승인 없음 키·allowed_purposes 확인, 관리자에게 요청
DAT-4032 403 보안 등급 제한 (restricted 는 현장 안 소비자만) —
DAT-4041 404 스냅샷 없음, 또는 released ID 확인
DAT-4091 409 파일 해시 불일치 (저장 파일 변조·손상 감지, 또는 내려받기 중 손상) 다시 받기. 반복되면 관리자에게 trace_id 와 함께
DAT-5031 503 서비스 일시 장애 SDK 가 retries 번 자동 재시도
DAT-5041 — 내보내기 작업 실패 job.status["error"] 확인

SDK 자체 예외: 키가 없으면 ValueError(연결 때), 시간대 없는 datetime 이면 ValueError, job.wait 시간 초과면 TimeoutError.

문의할 때는 trace_id(e.trace_id, b.trace_id)를 함께 알려 주면 서버 기록에서 그 요청을 찾을 수 있다.

15. 레시피

15.1 에피소드마다 관절 궤적 배열 만들기 (학습 입력)

import numpy as np

DS = "plab-testbed-cell01"
L = "testbed/so101/cell-01/leader-arm/joint_state"
F = "testbed/so101/cell-01/follower-arm/joint_state"
JOINTS = ["shoulder_pan", "shoulder_lift", "elbow_flex", "wrist_flex", "wrist_roll", "gripper"]

eps = fab.events(dataset_id=DS, start="2026-11-16T00:00:00+09:00", end="2026-11-17T00:00:00+09:00",
                 purpose="training", include_unaligned=True, event_types=["episode"])["events"]
episodes = {}
for e in eps:
    if e["status"] != "closed" or e["discarded"]:
        continue
    b = fab.read(dataset_id=DS, channels=[L, F], start=e["start_ns"] - 2 * 10**9, end=e["end_ns"] + 2 * 10**9,
                 purpose="training", min_tier="Tier-3", link_filter={"episode_id": e["episode_id"]})
    t = b.select(F, "gripper/position").time_ns                       # 팔로우 시각을 기준 축으로
    obs = np.stack([b.select(F, f"{j}/position").values for j in JOINTS], axis=1)                 # (N, 6) 상태
    act = np.stack([np.interp(t, b.select(L, f"{j}/position").time_ns, b.select(L, f"{j}/position").values)
                    for j in JOINTS], axis=1)                                                     # (N, 6) 리더 = 행동
    episodes[e["episode_id"]] = {"t_ns": t, "obs": obs, "act": act, "success": e["inspection_result"] == "success"}
    print(e["episode_id"], obs.shape, act.shape, e["inspection_result"])

재현이 필요하면 이 구간들로 스냅샷을 만든 뒤(11장) snapshot_id 로 읽는다.

15.2 그래프 그리기

import matplotlib
matplotlib.use("Agg")                    # 화면 없이 파일로 (주피터에서는 생략)
import matplotlib.pyplot as plt
import numpy as np

L = "testbed/so101/cell-01/leader-arm/joint_state"
F = "testbed/so101/cell-01/follower-arm/joint_state"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[L, F],
             start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:54:08+09:00", purpose="analysis")
t0 = b.select(F, "gripper/position").time_ns[0]
fig, ax = plt.subplots(figsize=(10, 4))
for ch, name in [(L, "leader"), (F, "follower")]:
    s = b.select(ch, "gripper/position")
    ax.plot((s.time_ns - t0) / 1e9, s.values, label=name)
ax.set_xlabel("s"); ax.set_ylabel("gripper (0-100)"); ax.legend()
fig.savefig("gripper.png", dpi=120)

15.3 날짜별 녹화량 확인

from collections import defaultdict

eps = fab.events(dataset_id="plab-testbed-cell01", start="2026-11-01T00:00:00+09:00", end="2026-12-01T00:00:00+09:00",
                 purpose="analysis", include_unaligned=True, event_types=["episode"])["events"]
per_day = defaultdict(lambda: [0, 0.0])
for e in eps:
    day = kst(e["start_ns"])[:10]
    per_day[day][0] += 1
    per_day[day][1] += (e["end_ns"] - e["start_ns"]) / 1e9
for day, (n, sec) in sorted(per_day.items()):
    print(day, f"에피소드 {n}개, {sec / 60:.1f}분")

15.4 에피소드 하나의 손목 영상을 파일로

from pathlib import Path

ep = fab.events(dataset_id="plab-testbed-cell01", start="2026-11-16T00:00:00+09:00", end="2026-11-17T00:00:00+09:00",
                purpose="analysis", include_unaligned=True, event_types=["episode"])["events"][-1]
W = "testbed/so101/cell-01/wrist-cam/image"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[W], start=ep["start_ns"], end=ep["end_ns"],
             purpose="analysis", link_filter={"episode_id": ep["episode_id"]})
out = Path("frames") / ep["episode_id"]
out.mkdir(parents=True, exist_ok=True)
for img in b.images[::30]:                                   # 1초에 한 장
    (out / f"{img['ts_ns']}.jpg").write_bytes(fab.content(img["content_ref"], purpose="analysis"))
print(len(list(out.glob("*.jpg"))), "장 저장:", out)

16. 메서드 요약

메서드 돌려주는 것 장
Fabric(url, *, api_key, verify, timeout, retries) 클라이언트 2
fab.datasets(**filters) 데이터셋 목록 (list[dict]) 4.1
fab.dataset(dataset_id) 데이터셋 상세 (dict) 4.2
fab.read(*, dataset_id / snapshot_id / data_ref, start, end, channels, purpose, min_tier, include_unaligned, include_raw_times, link_keys, link_filter, link_ambiguous, format) Batch 5, 6, 8
fab.events(*, dataset_id / snapshot_id, start, end, purpose, event_types, channels, min_tier, include_unaligned) {events, versions, window, excluded_count, trace_id} 7
fab.latest(*, dataset_id, purpose, channels, min_tier, include_unaligned) {latest: {채널: {...}}} 10
fab.content(content_ref, *, purpose) 이미지 bytes 9
fab.create_snapshot(*, dataset_id, start, end, channels, purpose, label) 스냅샷 (dict) 11
fab.snapshot(snapshot_id) / fab.snapshots(dataset_id) 스냅샷 / 목록 11
fab.add_model_reference(snapshot_id, package_id, version) 스냅샷 (dict) 11
fab.export(kind, *, purpose, snapshot_id / dataset_id, start, end, channels, min_tier, include_unaligned, label) ExportJob 12
fab.mapping(target_type, target_id) / fab.mappings_for_item(dict_item_id, include_deprecated) / fab.get_mapping(mapping_id) 매핑 (대상 기준 / 사전 기준 / 하나) 12-1
fab.register_mapping(target_type, target_id, dict_item_id, dict_version, *, replaces) / fab.deprecate_mapping(mapping_id) 매핑 (관리 권한) 12-1
fab.semantic_of(channel_id, tag) / fab.resolve_semantic(dataset_id, semantic_id, *, version, select) 채널의 사전 항목 / 사전 항목 → 채널·tag 12-1
window.Spec, window.Input, window.read(fab, spec, *, start, dataset_id / snapshot_id / data_ref), window.from_export(path, spec, *, stride_ns) 모델 입력 텐서 (Window / Windows) 12-2
Models(url, *, api_key, site_id, verify, timeout, retries) IF-20 클라이언트 12-3
m.infer(package_id, *, dataset_id+start / data_ref / window / inputs+data_window, version, site_id, timeout_ms, trace_id) Prediction (value, outputs, version, data_quality, data_window, semantic_drift, latency_ms, trace_id) 12-3.1~3
m.metadata(package_id) / m.health() / m.deployments(site_id) 입출력 형식 / 서빙 상태 / 현장 배포 12-3
m.packages(semantic_id) / m.version(package_id, version) / m.applicability(package_id, version) 패키지 목록 / 버전 상세 / 현장 적용 가능 여부 12-3.4
m.deploy(package_id, version, *, wait) / m.job(job_id) / m.rollback(package_id, *, reason) / m.audit(trace_id) DeploymentJob / 작업 / 롤백 결과 / 감사 기록 12-3.5
databahn.to_ns(시각) datetime → int ns (문자열·int 는 그대로) 3.4

17. 한도와 성능

항목 값 넘으면
조회 구간 1시간 DAT-4002 → 나눠 조회 또는 내보내기
이벤트 조회 구간 31일 DAT-4002 → 나눠 조회
스냅샷 만들기 제한 없음 읽을 때는 1시간씩 (11.2)
내보내기 구간 제한 없음 크기·시간만 늘어난다
저장 데이터 양 관절 4채널 합쳐 1분에 약 1 MB, 카메라 2대 1분에 약 120 MB
새 데이터가 조회되기까지 녹화 후 최대 약 11분 (파일이 10분 단위로 닫히고, 서버가 30초마다 읽어 들인다)

API 를 직접 부르려면 API 명세 와 대화형 API 를 본다. SDK 와 결과는 같다.