Data Formulator 数据源连接与导入指南：从数据库、BI 与云存储加载数据的完整实战

Data Formulator 数据源连接与导入指南从数据库、BI 与云存储加载数据的完整实战【免费下载链接】data-formulator Data Formulator is an interactive AI-powered data analysis system makes it easy to connect, explore and visualize data.项目地址: https://gitcode.com/GitHub_Trending/da/data-formulator适用版本Data Formulator 0.7 面向读者使用 Data Formulator 连接数据库、文件存储或 BI 系统的用户与管理员导读Data Formulator 的Load Data页面以「连接卡片」的方式组织所有可用的数据来源用户无需再进入旧的逐层目录去翻阅数据源而是直接点击卡片完成浏览、预览与导入。本文以官方指南 docs/docs-cn/1-data-source-connections.md 为主体结合仓库后端 data_connector.py 与加载器框架 external_data_loader.py 的源码实现系统讲解新增连接、目录浏览、源端筛选、Dashboard 批量导入、数据刷新、断开/删除、凭证加密保存以及 Local Folder 本地目录连接的全流程帮助你在桌面与多用户服务器两种部署模式下安全、高效地把外部数据加载进 workspace。1. 功能简介Load Data 页面与数据源卡片从 0.7 版本开始Data Formulator 把「已经配置或已经连接的数据源」直接展示为 Load Data 页面上的独立卡片替代了旧的 Database 标签页逐层选择的方式。常见入口包括本地数据示例数据、上传文件、粘贴数据、从 URL 加载数据源连接MySQL、PostgreSQL、Superset、S3、BigQuery 等连接卡片Add Connection新增一个数据库或数据服务连接Connect Local Folder本地模式下连接本机目录。从后端实现看这一卡片化界面由一套统一的 REST API 驱动服务启动时通过register_data_connectors(app)注册全局connectors_bp蓝图并加载管理员预配置的数据源用户在页面上的每一次「添加、连接、浏览、预览、导入、刷新」操作最终都落在/api/connectors/*系列路由上见 data_connector.py。这套接口由DataConnector泛型包装类统一提供任何实现ExternalDataLoader接口的数据源接入后即可自动获得完整的生命周期管理能力无需为每种数据源单独编写路由。2. 新增连接Add Connection2.1 操作步骤在 Load Data 页面点击Add Connection选择数据源类型例如 PostgreSQL、MySQL、Superset填写显示名称和连接参数点击Add Connect连接成功后新的数据源卡片会出现在 Load Data 页面。如果连接失败请检查主机、端口、数据库名、用户名、密码或 token 是否正确。部分数据源还需要管理员先安装对应依赖包例如数据库驱动缺失的驱动会被放入/api/data-loaders返回的disabled列表。2.2 后端做了什么创建连接与自动连接前端点击 Add Connect 后后端依次执行两个动作创建连接定义POST /api/connectors根据loader_type如mysql从注册表DATA_LOADERS中找到加载器类结合用户填写的显示名与参数生成连接实例并持久化到DATA_FORMULATOR_HOME/users/identity/connectors/source_id.json见 data_connector.py。实例 ID 由loader_type:slug组成重复名称会自动追加-2、-3后缀避免冲突。自动连接测试若请求中带connect_params后端会实例化 loader 并调用test_connection()。测试成功则将凭证写入保险箱并返回connected: true测试失败则返回connection_error结构含ErrorCode.DB_CONNECTION_FAILED、retry: true连接卡片保留但标记为未连接便于用户修正参数后重试。2.3 连接参数从哪来list_params 声明式定义每个加载器通过静态方法list_params()声明其连接表单字段每个参数包含名称、类型、是否必填、默认值、所属层级tier与说明。以 MySQL 为例见 mysql_data_loader.py{name: user, type: string, required: True, default: root, tier: auth, description: MySQL username}, {name: password, type: string, required: False, default: , sensitive: True, tier: auth, description: leave blank for no password}, {name: host, type: string, required: True, default: localhost, tier: connection, description: server address}, {name: port, type: int, required: False, default: 3306, tier: connection, advanced: True, description: server port}, {name: database, type: string, required: False, default: , tier: filter, description: Database name (leave empty to browse all databases)}tier: auth的参数属于认证层在 SSO/token 流程中可被跳过校验sensitive: True的参数密码、token、API key 等不会写入前端表单回显也不会进入持久化的连接配置只进入加密凭证库tier: filter的参数如 MySQL 的database通常对应目录层级填写后该层级会被「固定pinned」并直接从浏览目录中隐藏让你直接看到该库下的表。系统还会为每个加载器的表单自动追加一个通用的table_filter参数Filter table by keywords (e.g. sales)用于在浏览目录时按关键字过滤表名见 data_connector.py。2.4 管理员如何预配置连接管理员可以在服务器端提前配置好带固定参数的数据源普通用户打开页面即可看到对应卡片、无需自己填参数。预配置有两个来源见 data_connector.py方式一DATA_FORMULATOR_HOME/connectors.yamlconnectors: - id: pg_analytics type: postgresql name: PostgreSQL · analytics params: host: db.corp port: 5432 database: analytics user: ${PG_USER} # 支持 ${ENV_VAR} 环境变量引用 auto_connect: false方式二DF_SOURCES__*环境变量优先级最高覆盖 YAMLexport DF_SOURCES__pg_analytics__typepostgresql export DF_SOURCES__pg_analytics__namePostgreSQL · analytics export DF_SOURCES__pg_analytics__params__hostdb.corp export DF_SOURCES__pg_analytics__params__port5432 export DF_SOURCES__pg_analytics__params__databaseanalytics此外Superset 有一个快捷环境变量PLG_SUPERSET_URL一旦设置系统会自动注册一个名为superset的管理员连接免去手写 YAML。管理员预配置的连接会进入_ADMIN_CONNECTOR_IDS集合普通用户不能删除、不能重命名这类连接删除接口会返回 403。3. 数据源卡片一个类型、多个连接实例每个连接实例在 Load Data 页面显示为一张卡片例如PostgreSQL · analytics MySQL · staging Superset · prod同一种数据源可以有多个连接例如同时保留MySQL · prod和MySQL · staging。它们是两个独立连接互不共享连接状态和凭证。从实现上看每个连接实例都对应注册表DATA_CONNECTORS中的一个条目管理员连接以source_id作为全局注册键用户连接以user::identity::source_id作为注册键实现了严格的按身份隔离见 data_connector.py。同一用户在列表接口看到的连接与另一用户看到的是完全隔离的。卡片的「连接状态」通过GET /api/connectors返回的connected、has_stored_credentials、sso_auto_connect等字段驱动无认证的数据源如内置示例数据集始终处于已连接状态。4. 浏览、预览与导入4.1 目录树从「层级声明」到「浏览」点击数据源卡片后进入数据浏览界面左侧展开目录树例如 database、schema、table或 dashboard、dataset选择一个表、文件或数据集右侧查看预览数据、列信息和行数设置行数上限、排序或筛选条件点击导入按钮把数据加载到当前 workspace。目录树的形状由每个加载器声明的catalog_hierarchy()决定它是一个「从根到叶」的有序层级列表最后一级是可导入的叶子表/文件/数据集。源码注释中给出了典型示例见 external_data_loader.pyMySQL: database → table PostgreSQL: database → schema → table BigQuery: project → dataset → table S3: bucket → file Superset: dashboard → dataset目录树支持两种获取方式GET /api/connectors/get-catalog-tree一次性返回嵌套树优先读取磁盘上的catalog_cache缓存缺失时才回源实时枚举Local Folder 除外本地目录始终实时重扫GET /api/connectors/get-catalog按path逐层惰性浏览单个节点支持limit/offset分页单页上限 1000 条与关键字过滤。对大目录的实时枚举例如 Kusto 逐个枚举数据库后端会通过progress_callback上报进度前端轮询/api/connectors/get-catalog-progress在加载动画旁显示「正在查询哪个库」的实时消息。4.2 节点类型与元数据状态目录树中的节点有三种类型CatalogNode见 external_data_loader.py类型含义是否可导入namespace可展开的容器database、schema、bucket…否table可导入的叶子表、文件、数据集…是table_group一组相关表的可加载集合如 BI dashboard成员表在metadata[tables]中是批量每个叶子节点还带有source_metadata_status元数据状态取值包括synced列元数据完整、partial仅有表级描述、unavailable无可用元数据用于指导前端决定列信息是否可信。4.3 预览与导入Arrow 管道预览POST /api/connectors/preview-data调用loader.fetch_data_as_arrow()拉取数据默认 10 行经df_to_safe_records转成安全 JSON 返回给前端同时返回row_count与total_row_count。预览只返回内容列类型与描述等元数据由前端从目录缓存合并避免每次预览都回源查询。导入POST /api/connectors/import-data将所选source_table与import_options交给loader.ingest_to_workspace()。其核心管道为External Source → PyArrow Table → Parquet (workspace)导入过程中会进行列名与表名净化sanitize_table_name并做元数据富化优先从目录缓存读取源表/列描述避免额外的回源往返缓存缺失才实时获取元数据失败不会阻断导入。导入完成后新表进入 Data Formulator 的普通数据表列表可继续用于可视化、清洗和 Agent 分析且带上了source_info加载器类型、安全参数、源表名、导入选项为后续刷新提供依据。行数上限所有加载器共享MAX_IMPORT_ROWS 2_000_000的硬上限见 external_data_loader.py任何导入请求的size参数都会被此上限约束。5. 筛选与列值提示智能筛选与源端下推支持智能筛选的数据源会在预览面板显示筛选控件。用户可以按文本、数值、日期或布尔值添加条件。导入时筛选条件会尽量下推到外部数据源执行从而只把满足条件的行拉回来大幅减少导入数据量。当前主要支持 PostgreSQL、MySQL、Superset其他数据源可能只支持预览和导入不一定支持源端筛选——若连接器不支持筛选控件不会显示或不会生效。5.1 源无关的筛选操作符为了不让前端为每种 SQL 方言分别构造查询后端定义了一套源无关操作符词汇表_SOURCE_FILTER_OPERATOR_MAP见 external_data_loader.py由各 SQL 加载器编译成自己的方言前端操作符编译结果说明EQ等于NEQ!不等于GT/GTE/LT/LTE大小比较LIKELIKE模糊匹配ILIKEILIKEMySQL 编译为LOWER(col) LIKE LOWER(...)忽略大小写匹配IN/NOT_ININ (...)/NOT IN (...)列表匹配BETWEENBETWEEN x AND y区间匹配IS_NULL/IS_NOT_NULLIS NULL/IS NOT NULL空值判断编译过程通过build_source_filter_where_clause_inline()完成。它对列名做标识符转义反引号包裹、双写内嵌引号拒绝分号/空字节/SQL 注释序列对字面量做字符串逃逸从源头防御 SQL 注入见 external_data_loader.py。这些底层能力同样服务于 Agent 的数据探查probe与 SPJ 查询。5.2 列值提示当用户需要对某一列设置条件时前端会调用POST /api/connectors/column-values获取该列的去重值候选。加载器基类get_column_values()的默认实现返回空列表此时前端回退为自由文本输入Superset 等加载器则会覆写此方法、通过原生 API 返回带has_more分页标记的选项列表见 external_data_loader.py。6. Dashboard / Table Group 导入BI 系统可以把一个 dashboard 表示为一个可批量导入的数据包table_group节点。以 Superset 为例点击 Superset 连接卡片选择一个 dashboard右侧会显示该 dashboard 包含的数据集勾选需要导入的数据集设置每个数据集的行数上限点击导入Data Formulator 会把每个数据集作为独立表导入 workspace。从源码看Superset 被建模为「dashboardtable_group→ datasettable」的层级结构未挂载到任何 dashboard 的数据集会出现在根级的合成命名空间 All Datasets 下见 superset_data_loader.py。批量导入由POST /api/connectors/import-group处理见 data_connector.py请求体携带tables含dataset_id与名称、可选的row_limit-1 表示不限、source_filters可按applies_to指定该筛选应用到哪些数据集以及group_name每个数据集独立导入导入后的表名形如group_name / dataset_name某个数据集失败不影响其他数据集继续导入结果以数组形式返回每项包含statussuccess/error、table_name、row_count或错误信息导入完成后务必查看提示中的成功/失败明细。7. 刷新数据从连接器导入的表会记录来源信息source_table与import_options。只要连接仍然可用就可以在数据表上执行刷新POST /api/connectors/refresh-data会读取表元数据中保存的源表名与导入选项重新调用fetch_data_as_arrow()拉取最新数据并原子替换 workspace 中的 parquet 文件同时返回data_changed标志见 data_connector.py。刷新会原样复用导入时保存的源表、行数、排序和筛选条件。若外部系统权限变化、表被删除或凭证过期刷新可能失败需要重新连接或重新导入。关于「连接不可用时如何恢复」后端内置了三层自动重连机制见 data_connector.py保险箱凭证重连从 credential vault 读取保存的用户凭证重建 loader 并test_connection()SSO 自动连接token/sso_exchange 模式加载器在没有保险箱凭证时尝试用当前 SSO token 或 TokenStore 换取目标系统 token环境凭证重连对于使用宿主环境凭证如 Kusto 的DefaultAzureCredential、服务主体的加载器直接用持久化的连接参数重建 loader。每次重连最多尝试 3 次退避间隔为 0.5s、1.0s以扛过网络抖动等瞬时故障全部失败后才会清理失效凭证。8. 断开与删除操作适用场景结果Disconnect临时断开、切换账号、清理当前登录状态卡片保留但当前连接状态和保存的服务凭证会被清除Delete不再需要这个连接卡片移除用户连接配置和保存凭证被删除后端实现与上表完全对应见 data_connector.py 与 data_connector.pyDisconnectPOST /api/connectors/disconnect弹出进程内缓存的 loader、删除保险箱中该 identitysource 的凭证、并清理 TokenStore 中的服务 token目录缓存被有意保留因此 Agent 在离线状态下仍能基于缓存元数据做数据发现。无认证的加载器如示例数据集不可断开。DeleteDELETE /api/connectors/connector_id在 Disconnect 的基础上额外删除用户连接配置文件connectors/source_id.json、删除目录缓存delete_catalog并从注册表中移除条目。管理员预配置的数据源通常不能删除用户只能删除自己创建的连接。9. 凭证保存Credential Vault 加密保险箱连接数据库或外部系统时密码、token 等敏感信息不会写入前端也不会写入普通连接配置。后端通过凭证保险箱加密保存这些信息本地模式下系统会自动创建DATA_FORMULATOR_HOME/.vault_key DATA_FORMULATOR_HOME/credentials.db目录结构示意~/.data_formulator/ ├── .vault_key ├── credentials.db ├── connectors.yaml # 可选管理员预配置连接 └── users/ └── identity/ ├── connectors/source_id.json # 用户创建的连接仅非敏感参数 └── ...9.1 安全模型方面设计加密算法FernetAES-128-CBC HMAC-SHA256密钥存储DATA_FORMULATOR_HOME/.vault_key或CREDENTIAL_VAULT_KEY环境变量数据库位置DATA_FORMULATOR_HOME/credentials.db访问隔离按(user_identity, connector_id)逻辑隔离前端隔离明文凭证不返回前端前端只看到连接状态、参数表单和非敏感配置传输安全生产环境应使用 HTTPSVault 是逻辑隔离而非每用户一个数据库文件服务端进程持有加密密钥因此备份与权限管理应以整个DATA_FORMULATOR_HOME为单位处理。完整的安全细节与手动 API/api/credentials/list|store|delete见 docs/docs-cn/6-credential-vault.md。9.2 数据流何时写入、何时读取写入连接测试成功后非敏感参数写入users/identity/connectors/source_id.json敏感凭证经_vault_store()加密写入credentials.db读取点击已存在卡片重连时_try_auto_reconnect()从 vault 取出凭证重建 loader服务重启后用户连接会在首次请求时被惰性重新加载load_connectors(identity)避免出现「Connector not found」。9.3 迁移与备份服务器迁移、备份或 Docker 部署时.vault_key与credentials.db必须和用户数据一起保留否则已保存凭证无法恢复用户需要重新输入密码或重新授权。Docker 部署时直接挂载整个数据目录volumes: - df-data:/root/.data_formulator如需使用外部密钥管理可用环境变量注入 Fernet 密钥设置后.vault_key文件被忽略CREDENTIAL_VAULT_KEYyour-fernet-key生成密钥的方法python -c from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())更多迁移细节见 docs/docs-cn/7-server-migration-guide.md。10. Local Folder本地模式专属的目录连接Connect Local Folder只在本地模式可用。它允许 Data Formulator 直接读取本机某个目录中的文件适合桌面或个人使用场景。在多人服务器或云部署中本机目录连接会被禁用避免用户读取服务器上的任意文件见 data_connector.py 中local_folder在非本地模式下被隐藏的逻辑。后端还提供POST /api/local/pick-directory打开操作系统原生目录选择器macOS通过osascriptAppleScriptWindows通过 PowerShell 的FolderBrowserDialogLinux依次尝试zenityGNOME→kdialogKDE→tkinterPython 标准库需带 Tk 编译。如果无任何对话框工具可用无头服务器、精简容器接口返回 501前端回退为文本输入框。Local Folder 连接有两个特殊行为目录树始终实时重扫磁盘避免缓存过期导致 Agent 搜索漏掉新文件且 Agent 可以基于最新目录内容做检索。11. 常见问题为什么看不到某种数据源可能是对应 Python 依赖未安装。管理员可以查看GET /api/data-loaders返回的disabled列表每个条目含install_hint安装提示或查看服务端启动日志中的安装提示。另外local_folder类型在服务器模式下会被有意隐藏示例数据集sample_datasets则始终可用。为什么点击卡片后需要重新连接可能是服务重启、token 过期、手动断开或凭证已被清除。后端会依次尝试保险箱凭证、SSO token 与宿主环境凭证三类自动重连若全部失败重新输入凭证或通过 SSO 登录即可。Delete 和 Disconnect 有什么区别Disconnect 适合临时断开连接卡片仍会保留仅清除当前连接状态与已保存凭证目录缓存保留Delete 会删除用户创建的连接卡片、配置文件和保存凭证并清除目录缓存。管理员预配置的连接不可删除。为什么筛选控件不是所有连接都有不同数据源支持能力不同。PostgreSQL、MySQL 和 Superset 已支持主要的源端筛选筛选条件下推到源端执行其他数据源需要等待对应 connector 实现ExternalDataLoader中的筛选支持。结语从卡片到数据的完整链路整个数据源连接与导入体系可以概括为一条清晰的链路list_params 声明表单 → Add Connection 创建连接 → test_connection 验证 → catalog_hierarchy 目录浏览 → 智能筛选下推 → Arrow 管道导入 Parquet → source_info 记录来源 → 一键刷新 → Disconnect/Delete 生命周期清理 → credential vault 全程加密保存凭证无论是单机桌面使用Local Folder、本地数据库还是多用户服务器部署管理员预配置连接、SSO 认证、凭证隔离Data Formulator 都通过统一的ExternalDataLoader接口与DataConnector生命周期包装把复杂度收敛到后端让用户专注于「连接、探索、可视化」本身。若需深入底层协议可继续阅读 docs/dev-guides/5-data-connector-api.md连接器 API 设计与 docs/dev-guides/11-catalog-metadata-sync.md目录元数据同步。【免费下载链接】data-formulator Data Formulator is an interactive AI-powered data analysis system makes it easy to connect, explore and visualize data.项目地址: https://gitcode.com/GitHub_Trending/da/data-formulator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考