文件
Python API
Metadater API（更新中）

Metadater API（更新中）

資料結構描述管理器，提供資料集的詮釋資料（Metadata）定義、比較與對齊功能。

類別架構 

classDiagram
    class Metadater {
        <<main>>
        +from_data(data: dict) Metadata
        +from_dict(config: dict) Metadata
        +diff(metadata: Metadata, data: dict) dict
        +align(metadata: Metadata, data: dict) dict
        +get(metadata: Metadata, name: str) Schema
        +add(metadata: Metadata, schema: Schema) Metadata
        +update(metadata: Metadata, schema: Schema) Metadata
        +remove(metadata: Metadata, name: str) Metadata
    }

    class SchemaMetadater {
        <<operation>>
        +from_data(data: DataFrame) Schema
        +from_dict(config: dict) Schema
        +diff(schema: Schema, data: DataFrame) dict
        +align(schema: Schema, data: DataFrame) DataFrame
        +get(schema: Schema, name: str) Attribute
        +add(schema: Schema, attribute: Attribute) Schema
        +update(schema: Schema, attribute: Attribute) Schema
        +remove(schema: Schema, name: str) Schema
    }

    class AttributeMetadater {
        <<operation>>
        +from_data(data: Series) Attribute
        +from_dict(config: dict) Attribute
        +diff(attribute: Attribute, data: Series) dict
        +align(attribute: Attribute, data: Series) Series
        +validate(attribute: Attribute, data: Series) tuple
    }

    class Metadata {
        <<dataclass>>
        +id: str
        +schemas: dict[str, Schema]
    }

    class Schema {
        <<dataclass>>
        +id: str
        +attributes: dict[str, Attribute]
    }

    class Attribute {
        <<dataclass>>
        +name: str
        +type: str
        +nullable: bool
        +logical_type: str
    }

    %% 操作關係
    Metadater ..> Metadata : creates/operates
    SchemaMetadater ..> Schema : creates/operates
    AttributeMetadater ..> Attribute : creates/operates
    
    %% 組合關係
    Metadata *-- Schema : contains
    Schema *-- Attribute : contains
    
    %% 階層呼叫
    Metadater --> SchemaMetadater : calls
    SchemaMetadater --> AttributeMetadater : calls

    %% 樣式標示
    style Metadater fill:#e6f3ff,stroke:#4a90e2,stroke-width:3px
    style SchemaMetadater fill:#fff2e6,stroke:#ff9800,stroke-width:2px
    style AttributeMetadater fill:#fff2e6,stroke:#ff9800,stroke-width:2px
    style Metadata fill:#f0f8ff,stroke:#6495ed,stroke-width:2px
    style Schema fill:#f0f8ff,stroke:#6495ed,stroke-width:2px
    style Attribute fill:#f0f8ff,stroke:#6495ed,stroke-width:2px

圖例說明：

  • 藍色框：主要操作類別
  • 橘色框：操作子類別
  • 淺藍框：資料設定類別
  • ..>：建立/操作關係
  • *--：組合關係
  • -->：呼叫關係

基本使用

Metadater 主要作為內部元件使用，通常透過 Loader 的 schema 參數間接使用：

# 在 YAML 中定義
Loader:
  my_experiment:
    filepath: data/users.csv
    schema: schemas/user_schema.yaml

若需直接使用 Metadater 類別方法：

from petsard.metadater import Metadater
import pandas as pd

# 從資料自動推斷結構
data = {'users': pd.DataFrame(...)}
metadata = Metadater.from_data(data)

# 從字典建立詮釋資料
config = {'tables': {...}}
metadata = Metadater.from_dict(config)

# 比較資料差異
diff = Metadater.diff(metadata, new_data)

# 對齊資料結構
aligned = Metadater.align(metadata, new_data)

類別方法說明

Metadater 提供靜態類別方法（@classmethod 或 @staticmethod），不需要實例化即可使用：

建立詮釋資料

  • from_data()：從資料自動推斷並建立 Metadata
  • from_dict()：從配置字典建立 Metadata

比較與對齊

  • diff()：比較 Metadata 與實際資料的差異
  • align()：根據 Metadata 對齊資料結構

資料結構

Metadata

最上層，管理整個資料集：

  • id: 資料集識別碼
  • name: 資料集名稱（選填）
  • description: 資料集描述（選填）
  • schemas: 表格結構字典 {table_name: Schema}

Schema

中間層，描述單一表格：

  • id: 表格識別碼
  • name: 表格名稱（選填）
  • description: 表格描述（選填）
  • attributes: 欄位屬性字典 {field_name: Attribute}

Attribute

最底層，定義單一欄位：

  • name: 欄位名稱
  • type: 資料型別（int, float, str, bool, datetime 等）
  • nullable: 是否允許空值（True/False）
  • logical_type: 邏輯型別（選填，如 email, phone, url 等）
  • na_values: 自訂空值表示（選填）

使用情境

1. 資料載入時的 Schema 管理

Loader 內部使用 Metadater 處理 schema：

# Loader 內部流程（簡化）
schema = Metadater.from_dict(schema_config)  # 從 YAML 載入
data = pd.read_csv(filepath)                  # 讀取資料
aligned_data = Metadater.align(schema, data)  # 對齊資料結構

2. 資料結構驗證

比較期望結構與實際資料：

# 定義期望的 schema
expected_schema = Metadater.from_dict(config)

# 比較實際資料
diff = Metadater.diff(expected_schema, {'users': actual_data})

if diff:
    print("發現結構差異：", diff)

3. 多資料集結構統一

確保多個資料集具有相同結構：

# 定義標準結構
standard_schema = Metadater.from_data({'users': reference_data})

# 對齊其他資料集
aligned_data1 = Metadater.align(standard_schema, {'users': data1})
aligned_data2 = Metadater.align(standard_schema, {'users': data2})

注意事項

  • 內部使用為主：Metadater 主要供 PETsARD 內部模組使用，一般使用者透過 Loader 的 schema 參數即可
  • 類別方法設計：所有方法都是類別方法，不需要實例化 Metadater
  • 自動推斷：from_data() 會自動推斷欄位類型和是否可為空值
  • 對齊行為：align() 會根據 schema 調整欄位順序、補充缺失欄位、轉換資料類型
  • 差異檢測：diff() 檢測欄位名稱、類型、空值處理等差異
  • YAML 配置：詳細的 Schema YAML 配置請參閱 Schema YAML 文檔
  • 文件說明：本段文件僅供開發團隊內部參考，不保證向後相容