DeepSeek总结的DuckDB Eurostat 扩展

原文地址：https://github.com/ahuarte47/duckdb-eurostat

DuckDB Eurostat 扩展

这是什么？

这是一个 DuckDB 扩展，用于使用 SQL 从 EUROSTAT 数据库读取数据。

Eurostat 是欧盟的官方统计机构，负责提供关于欧洲经济、社会、环境等方面的高质量、可比且协调统一的统计数据。

Eurostat 与各国统计机构合作，为欧洲官方统计数据的生产制定协调统一的定义、分类和方法论。它使用各国统计机构根据协调统一标准收集的数据，计算欧盟和欧元区的汇总数据。Eurostat 通过其网站、社交媒体和其他渠道，免费向决策者和公众提供欧洲统计数据。

如何获取？

从社区加载

DuckDBEUROSTAT 扩展可作为已签名的社区扩展使用。
更多详情请访问其 DuckDB CE 网页。

要安装并加载它，您可以在 DuckDB 中运行以下 SQL 命令：

INSTALL eurostatFROMcommunity;LOADeurostat;

从源代码构建

此扩展基于 DuckDB 扩展模板。

使用示例

首先，请确保在您的 DuckDB 会话中加载了该扩展。

然后，您可以使用该扩展从 EUROSTAT 数据库读取元数据和数据集。

以下是可用的函数列表：

• EUROSTAT_Endpoints

  返回支持的 EUROSTAT API 端点列表。

  SELECTprovider_id,organization,descriptionFROMEUROSTAT_Endpoints();┌─────────────┬──────────────┬──────────────────────────────────────────────────────┐ │ provider_id │ organization │ description │ │varchar│varchar│varchar│ ├─────────────┼──────────────┼──────────────────────────────────────────────────────┤ │ ECFIN │ DG ECFIN │ 经济与金融事务 │ │ EMPL │ DG EMPL │ 就业、社会事务与社会包容 │ │ ESTAT │ EUROSTAT │ EUROSTAT 数据库 │ │ GROW │ DG GROW │ 内部市场、产业、创业与中小企业 │ │ TAXUD │ DG TAXUD │ 税收与关税同盟 │ └─────────────┴──────────────┴──────────────────────────────────────────────────────┘

• EUROSTAT_Dataflows

  返回 EUROSTAT 提供方所提供数据流的信息。

  SELECT*FROMEUROSTAT_Dataflows();SELECT*FROMEUROSTAT_Dataflows(providers=['ESTAT','ECFIN'],language:='en');

  您也可以按特定的数据流进行筛选：

  SELECTprovider_id,dataflow_id,class,version,labelFROMEUROSTAT_Dataflows(providers=['ESTAT'],dataflows=['DEMO_R_D2JAN'],language:='de');┌─────────────┬──────────────┬─────────┬─────────┬───────────────────────────────────────────────────────────────────┐ │ provider_id │ dataflow_id │ class │ version │ label │ │varchar│varchar│varchar│varchar│varchar│ ├─────────────┼──────────────┼─────────┼─────────┼───────────────────────────────────────────────────────────────────┤ │ ESTAT │ DEMO_R_D2JAN │ dataset │1.0│ 按年龄、性别和 NUTS-2区域划分的1月1日人口数据 │ └─────────────┴──────────────┴─────────┴─────────┴───────────────────────────────────────────────────────────────────┘

• EUROSTAT_DataStructure

  返回 EUROSTAT 数据流的数据结构信息。

  SELECTprovider_id,dataflow_id,position,dimension,conceptFROMEUROSTAT_DataStructure('ESTAT','DEMO_R_D2JAN',language:='en');┌─────────────┬──────────────┬──────────┬─────────────┬─────────────────────────────────┐ │ provider_id │ dataflow_id │ position │ dimension │ concept │ │varchar│varchar│ int32 │varchar│varchar│ ├─────────────┼──────────────┼──────────┼─────────────┼─────────────────────────────────┤ │ ESTAT │ DEMO_R_D2JAN │1│ freq │ 时间频率 │ │ ESTAT │ DEMO_R_D2JAN │2│ unit │ 计量单位 │ │ ESTAT │ DEMO_R_D2JAN │3│ sex │ 性别 │ │ ESTAT │ DEMO_R_D2JAN │4│ age │ 年龄组 │ │ ESTAT │ DEMO_R_D2JAN │5│ geo │ 地理政治实体（报告单位） │ │ ESTAT │ DEMO_R_D2JAN │-1│ geo_level │ NUTS 分类层级 │ │ ESTAT │ DEMO_R_D2JAN │6│ time_period │ 时间 │ └─────────────┴──────────────┴──────────┴─────────────┴─────────────────────────────────┘

  geo_level维度并非数据流源的一部分，而是根据geo维度的值计算得出的。
  更多细节请参见下面的函数 EUROSTAT_GetGeoLevelFromGeoCode。

• EUROSTAT_Read

  读取 EUROSTAT 数据流的数据集。

  SELECT*FROMEUROSTAT_Read('ESTAT','DEMO_R_D2JAN')LIMIT5;┌─────────┬─────────┬─────────┬─────────┬─────────┬───────────┬─────────────┬───────────────────┐ │ freq │ unit │ sex │ age │ geo │ geo_level │ TIME_PERIOD │ observation_value │ │varchar│varchar│varchar│varchar│varchar│varchar│varchar│double│ ├─────────┼─────────┼─────────┼─────────┼─────────┼───────────┼─────────────┼───────────────────┤ │ A │ NR │ F │ TOTAL │ AL │ country │2000│1526762.0│ │ A │ NR │ F │ TOTAL │ AL │ country │2001│1535822.0│ │ A │ NR │ F │ TOTAL │ AL │ country │2002│1532563.0│ │ A │ NR │ F │ TOTAL │ AL │ country │2003│1526180.0│ │ A │ NR │ F │ TOTAL │ AL │ country │2004│1520481.0│ └─────────┴─────────┴─────────┴─────────┴─────────┴───────────┴─────────────┴───────────────────┘

  该扩展支持对维度的 T-SQL 过滤器进行下推，这些过滤器会被编码并发送到 EUROSTAT API，以便在数据加载到 DuckDB 之前进行筛选。

  EUROSTAT API 仅支持对维度进行相等条件（例如WHERE geo = 'DE'）或 IN 条件（例如WHERE geo IN ('DE', 'FR')）的筛选。其他类型的过滤器（例如WHERE geo LIKE 'D%'）不受支持，将在数据加载后于 DuckDB 本地进行评估。

  时间过滤器（例如WHERE time_period >= '2000' AND time_period <= '2010'）也受支持，并将被编码为 EUROSTAT API 中的范围过滤器。

  geo_level维度不是数据流源的一部分，而是根据geo维度的值计算得出的。您也可以对其进行筛选（例如WHERE geo_level = 'country'），但这将在数据加载后于 DuckDB 本地进行评估。

• EUROSTAT_GetGeoLevelFromGeoCode

  标量函数，根据 NUTS 分类中的地理代码返回其层级，或判断其是否为聚合区域。

  SELECTEUROSTAT_GetGeoLevelFromGeoCode('DE');-- 返回 'country'SELECTEUROSTAT_GetGeoLevelFromGeoCode('DE1');-- 返回 'nuts1'SELECTEUROSTAT_GetGeoLevelFromGeoCode('DE12');-- 返回 'nuts2'SELECTEUROSTAT_GetGeoLevelFromGeoCode('DE123');-- 返回 'nuts3'SELECTEUROSTAT_GetGeoLevelFromGeoCode('DE_DEL1');-- 返回 'city'SELECTEUROSTAT_GetGeoLevelFromGeoCode('EU27_2020');-- 返回 'aggregate'

  EUROSTAT_Read函数使用此标量函数将geo_level维度作为普通列添加。

  支持的层级有：

  • aggregate（聚合区域）
  • country（国家）
  • nuts1（NUTS 1 级区域）
  • nuts2（NUTS 2 级区域）
  • nuts3（NUTS 3 级区域）
  • city（城市）

  关于geo_level的更多细节，请参见此处。

支持的函数与文档

完整的函数列表及其文档可在 函数参考 中找到。

如何构建它？

依赖项

您需要 CMake（版本 3.5 或更高）和一个兼容 C++14 的编译器。

我们强烈建议您安装 Ninja，您可以在构建时通过设置环境变量GEN=ninja来选用它。

gitclone --recurse-submodules https://github.com/ahuarte47/duckdb-eurostatcdduckdb-eurostatmakerelease

然后，您可以调用已构建的 DuckDB（其中已静态链接了扩展）：

./build/release/duckdb

更多选项请参阅 Makefile，或查看扩展模板文档以了解更多细节。

运行测试

可以为 DuckDB 扩展创建不同的测试。测试 DuckDB 扩展的主要方式应该是./test/sql中的 SQL 测试。这些 SQL 测试可以通过以下命令运行：

maketest

安装已部署的二进制文件

要从 S3 安装您的扩展二进制文件，您需要做两件事。首先，启动 DuckDB 时应将allow_unsigned_extensions选项设置为 true。设置方式取决于您使用的客户端。以下是一些示例：

CLI：

duckdb -unsigned

Python：

con=duckdb.connect(':memory:',config={'allow_unsigned_extensions':'true'})

NodeJS：

db=newduckdb.Database(':memory:',{"allow_unsigned_extensions":"true"});

其次，您需要将 DuckDB 中的存储库端点设置为您的存储桶的 HTTP URL + 您想要安装的扩展版本。为此，请在 DuckDB 中运行以下 SQL 查询：

SETcustom_extension_repository='bucket.s3.eu-west-1.amazonaws.com/<your_extension_name>/latest';

请注意，/latest路径将允许您安装适用于当前 DuckDB 版本的最新扩展版本。要指定特定版本，您可以传递版本号。

完成这些步骤后，您可以使用 DuckDB 中常规的 INSTALL/LOAD 命令来安装和加载您的扩展：

INSTALL eurostat;LOADeurostat;

祝您使用愉快！