df.to _dict(orient='records') 是 Pandas DataFrame 的一個方法，用于將數據轉換為字典列表格式。以下是詳細解釋及實例說明：

一、核心含義

1. 作用
   將 DataFrame 的每一行轉換為一個字典，所有字典組成一個列表。
   每個字典的鍵（key）是 DataFrame 的列名，值（value）是該行對應列的數據。
   證據來源：

2. 參數 orient='records'

   • orient 指定輸出字典的格式：
     • 'records' 生成列表（每個元素為行字典）
     • 其他選項如 'dict'（列名→列值字典）、'index'（行索引→行值字典）等（詳見 ）
   • 注意：Pandas 1.1.x 后棄用短參數名（如 'records'），推薦完整寫法 orient='records' 。

---

二、實例說明

示例 1：基礎轉換

import pandas as pd# 創建示例 DataFrame
df = pd.DataFrame({'Name': ['Alice', 'Bob'],'Age': [30, 28],'City': ['Beijing', 'Shanghai']
})# 使用 orient='records'
records = df.to_dict(orient='records')
print(records)

輸出：

[{'Name': 'Alice', 'Age': 30, 'City': 'Beijing'},{'Name': 'Bob', 'Age': 28, 'City': 'Shanghai'}
]

每行數據轉換為獨立字典，鍵為列名（Name, Age, City）。

---

示例 2：特殊場景處理

1. 列名為數字字符串時
   若列名是整數格式的字符串（如 '0'），舊版本 Pandas（如 0.24.0）會自動添加下劃線（{'_0': value}）：

   df_bad = pd.DataFrame({str(i): [i] for i in range(3)})  # 列名為 ['0','1','2']
   print(df_bad.to_dict('records'))  # 輸出 [{'_0': 0, '_1': 1, '_2': 2}]
   

2. 空 DataFrame 時
   無數據的 DataFrame 返回空列表 []，而非預期的 [{}, {}, ...]（行為可能因版本而異）：

   empty_df = pd.DataFrame([{}, {}]) 
   print(empty_df.to_dict(orient='records'))  # 輸出 []
   

3. 性能對比
   大數據集下原生方法可能比自定義實現慢（如 500 萬行數據慢 3 倍），因需類型檢查和裝箱操作 。

---

三、典型應用場景

1. 數據序列化
   轉換為字典列表后可直接用于 JSON 序列化，方便 API 傳輸或存儲 ：

   import json
   json_data = json.dumps(df.to_dict(orient='records'))
   

2. 機器學習特征處理
   配合 sklearn.feature_extraction.DictVectorizer 對分類特征做 One-Hot 編碼 ：

   from sklearn.feature_extraction import DictVectorizer
   vec = DictVectorizer(sparse=False)
   X = vec.fit_transform(df.to_dict(orient='records'))
   

3. 數據遍歷
   直接迭代每行數據，代碼更簡潔 ：

   for record in df.to_dict(orient='records'):print(record['Name'], record['Age'])
   

---

四、注意事項

1. 版本兼容性

   • Pandas ≥1.1.x 需用 orient='records' 而非簡寫 'records'，否則觸發棄用警告 。
   • 列數 ≥255 時，舊版本（0.24.0）可能報錯 AttributeError，建議升級 Pandas 。

2. 數據類型保留
   默認保留 Pandas 內部類型（如 Timestamp），若需原生 Python 類型（如 datetime），需提前轉換：

   df['date'] = df['date'].astype(object)  # 將時間戳轉為 Python datetime
   records = df.to_dict(orient='records')
   

   *否則輸出可能包含非標準類型（如 Timestamp）導致序列化失敗 *。

3. 索引處理
   orient='records' 默認忽略行索引（index）。若需包含索引，應先重置索引：

   df.reset_index(inplace=True)  # 添加索引列
   records = df.to_dict(orient='records')
   

---

總結

df.to _dict(orient='records') 的核心功能是將 DataFrame 按行轉換為字典列表，每個字典代表一行數據，鍵為列名。它適用于數據序列化、機器學習特征工程和簡化數據遍歷，但需注意版本差異、列名格式和數據類型轉換問題。