harvard-artifacts-data-engineering-streamlit

用途

本项目提供一个面向哈佛艺术博物馆（Harvard Art Museums）API 的端到端数据工程与分析应用。它演示真实世界中的 ETL 管道、SQL 数据库设计、分析型查询以及交互式仪表板，用于探索博物馆艺术品数据。

主要能力

数据采集：从哈佛艺术博物馆 API 获取艺术品数据，支持分页与限流。
ETL 管道：提取、转换并加载艺术品元数据、媒体和颜色信息到关系型 SQL 数据库。
SQL 分析：运行 20 多个预定义分析查询，按文化、世纪、部门、媒体等维度提供洞察。
可视化：在 Streamlit 中使用 Plotly 创建交互式仪表板，用于浏览查询结果。
数据库管理：管理 MySQL/TiDB Cloud 模式，并设置适当的外键关系。

使用方式

环境准备

所需的 Python 包：

pip install streamlit pandas requests mysql-connector-python plotly python-dotenv

或使用 requirements 文件：

pip install -r requirements.txt

环境变量设置

在项目根目录创建 .env 文件：

# Harvard Art Museums API
HARVARD_API_KEY=your_api_key_here

# Database Configuration
DB_HOST=your_database_host
DB_PORT=3306
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=harvard_artifacts

哈佛艺术博物馆 API 密钥获取地址：https://www.harvardartmuseums.org/collections/api

数据库设置

-- Create database
CREATE DATABASE harvard_artifacts;
USE harvard_artifacts;

-- Artifact metadata table
CREATE TABLE artifactmetadata (
    id INT PRIMARY KEY,
    title VARCHAR(500),
    culture VARCHAR(200),
    century VARCHAR(100),
    department VARCHAR(200),
    classification VARCHAR(200),
    period VARCHAR(200),
    dated VARCHAR(200),
    url TEXT,
    rank INT
);

-- Artifact media table
CREATE TABLE artifactmedia (
    id INT AUTO_INCREMENT PRIMARY KEY,
    artifact_id INT,
    media_type VARCHAR(100),
    media_url TEXT,
    FOREIGN KEY (artifact_id) REFERENCES artifactmetadata(id)
);

-- Artifact colors table
CREATE TABLE artifactcolors (
    id INT AUTO_INCREMENT PRIMARY KEY,
    artifact_id INT,
    color_hex VARCHAR(10),
    color_name VARCHAR(100),
    color_percent FLOAT,
    FOREIGN KEY (artifact_id) REFERENCES artifactmetadata(id)
);

运行应用

streamlit run app.py

在 http://localhost:8501 访问仪表板。

核心组件

项目包含以下核心组件：API 数据采集、ETL 管道、数据库连接、分析型 SQL 查询、Streamlit 仪表板。其中 API 采集使用 requests 与 dotenv，支持按尺寸和页码抓取，并可筛选带图像的艺术品；ETL 管道分别提取元数据、媒体与颜色数据，并通过 executemany 批量写入，元数据表使用 ON DUPLICATE KEY UPDATE 处理重复键；数据库连接使用 mysql-connector-python，并基于环境变量构建连接。

分析查询示例包括：按文化统计艺术品、按世纪统计、部门分布、带媒体艺术品占比、最常用颜色、按时期的文化分布等。Streamlit 仪表板提供侧边栏配置、数据采集与 ETL 按钮、SQL 分析选择与运行、结果表格与 Plotly 柱状图。

常见模式

批量处理大数据集：使用分页分批抓取，并加入 time.sleep(0.5) 限流。
ETL 错误处理：使用事务与回滚，配合断言校验。
自定义查询构建器：按分组字段、过滤条件与限制数量动态拼接查询。

故障排除

API 限流：使用指数退避重试处理 429 状态码。
数据库连接问题：使用带重试逻辑的连接函数。
内存高效处理：以流式方式逐页抓取、处理并立即加载，及时释放内存。

适用场景

适合需要学习或演示端到端数据工程流程的开发者、数据工程师与数据分析师，尤其是希望结合真实 API、关系型数据库、SQL 分析与 Streamlit 可视化进行实践的场合。

限制

依赖哈佛艺术博物馆 API 密钥，需自行申请。
数据库需为 MySQL 或 TiDB Cloud 等兼容环境，并需手动创建表结构。
收费、价格、平台可用性、效果指标等信息暂未提供。
项目代码与命令应保持原样，未提供额外的部署或生产化说明。