数据目录简介¶

在Kedro项目中，数据目录(Data Catalog)是一个注册表，记录了项目可用的所有数据源。它通过YAML格式的目录文件进行配置，该文件将节点输入输出的名称映射为DataCatalog类中的键。

本页介绍catalog.yml文件的基本组成部分，该文件是Kedro用于为项目注册数据源的配置文件。

警告

从Kedro 0.19.0版本开始，数据集不再包含在核心Kedro包中。请改为从kedro-datasets包中导入它们。从kedro-datasets的2.0.0版本开始，所有数据集名称都已更改，将"DataSet"中的大写字母"S"替换为小写字母"s"。例如，CSVDataSet现在改为CSVDataset。

`catalog.yml`基础¶

数据目录YAML示例的单独页面提供了更多关于如何使用catalog.yml的示例，但这里我们重新回顾太空飞行教程中介绍的基本catalog.yml。

以下示例注册了两个csv数据集和一个xlsx数据集。在本地文件系统中加载和保存文件所需的最少信息包括：数据集名称的键(key)、指示要使用数据集的类型(type)以及文件位置(filepath)。

companies:
  type: pandas.CSVDataset
  filepath: data/01_raw/companies.csv

reviews:
  type: pandas.CSVDataset
  filepath: data/01_raw/reviews.csv

shuttles:
  type: pandas.ExcelDataset
  filepath: data/01_raw/shuttles.xlsx
  load_args:
    engine: openpyxl # Use modern Excel engine (the default since Kedro 0.18.0)

在`catalog.yml`中配置数据集参数¶

catalog.yml 中的数据集配置定义如下：

顶层键是目录中用作数据集标识符的数据集名称 - 如下例中的 shuttles, weather。
下一层级包含多个键。第一个是必填键 - type，用于定义要使用的数据集类型。其余键是数据集参数，具体取决于实现方式。要获取完整的数据集参数列表，请参阅The kedro-datasets package documentation并导航至目标数据集的__init__方法。
某些数据集参数可以根据底层数据集实现库进行进一步配置。在下面的示例中，shuttles数据集的配置包含由pandas加载CSV文件选项定义的load_args参数。而weather数据集配置中的save_args参数则由snowpark的saveAsTable方法定义。要获取完整的数据集参数列表，请参阅The kedro-datasets package documentation并导航至数据集__init__定义中的目标参数。对于这些参数，我们提供了底层库配置参数的参考。例如，在pandas.ExcelDataset的load_args参数部分下，您可以找到定义所接受参数完整集的pandas.read_excel方法参考。

注意

Kedro数据集直接将任何load_args / save_args委托给底层实现。

以下示例展示了两个数据集的配置 - shuttles类型为pandas.ExcelDataset，以及weather类型为snowflake.SnowparkTableDataset。

shuttles: # Dataset name
  type: pandas.ExcelDataset # Dataset type
  filepath: data/01_raw/shuttles.xlsx # pandas.ExcelDataset parameter
  load_args: # pandas.ExcelDataset parameter
    engine: openpyxl # Pandas option for loading CSV files

weather: # Dataset name
  type: snowflake.SnowparkTableDataset # Dataset type
  table_name: "weather_data"
  database: "meteorology"
  schema: "observations"
  credentials: snowflake_client
  save_args: # snowflake.SnowparkTableDataset parameter
    mode: overwrite # Snowpark saveAsTable input option
    column_order: name
    table_type: ''

数据集 `type`¶

Kedro支持多种连接器，可用于CSV文件、Excel电子表格、Parquet文件、Feather文件、HDF5文件、JSON文档、pickle对象、SQL表、SQL查询等。这些功能通过pandas、PySpark、NetworkX和Matplotlib等库实现支持。

The kedro-datasets package documentation 包含了所有可用文件类型的完整列表。

数据集 `filepath`¶

Kedro依赖fsspec来从多种数据存储中读写数据，包括本地文件系统、网络文件系统、云对象存储和Hadoop。在filepath:中指定存储位置时，应使用通用格式protocol://path/to/data提供URL。如果未指定协议，则默认为本地文件系统（等同于file://）。

以下协议可用：

本地或网络文件系统: file:// - 在没有指定任何协议时默认使用本地文件系统，同时也允许使用相对路径。
Hadoop文件系统(HDFS): hdfs://user@server:port/path/to/data - Hadoop分布式文件系统，用于在集群中存储具有容错性和复制功能的文件。
Amazon S3: s3://my-bucket-name/path/to/data - Amazon S3远程二进制存储，通常与Amazon EC2配合使用，通过s3fs库实现。
S3兼容存储: s3://my-bucket-name/path/_to/data - 例如使用s3fs库的MinIO。
Google Cloud Storage: gcs:// - Google云存储，通常与使用gcsfs的Google计算资源一起使用（开发中）。
Azure Blob Storage / Azure Data Lake Storage Gen2: abfs:// - Azure Blob存储，通常在Azure环境中工作时使用。
HTTP(s): http:// 或 https:// 用于直接从HTTP网络服务器读取数据。

fsspec 还提供其他文件系统，例如 SSH、FTP 和 WebHDFS。See the fsspec documentation for more information。

`catalog.yml`中的其他设置¶

本节介绍在catalog.yml中可用的其他设置。

加载、保存及文件系统参数¶

Kedro数据目录还接受不同组的*_args参数，这些参数具有不同的用途：

load_args 和 save_args: 配置第三方库如何从文件加载/保存数据。在上面的spaceflights示例中，load_args作为关键字参数传递给excel文件读取方法(pd.read_excel)。虽然这里没有指定，但对应的输出是save_args，其值将被传递给pd.DataFrame.to_excel方法。

例如，要在本地文件系统上加载或保存CSV文件，并使用指定的加载/保存参数：

cars:
  type: pandas.CSVDataset
  filepath: data/01_raw/company/cars.csv
  load_args:
    sep: ','
  save_args:
    index: False
    date_format: '%Y-%m-%d %H:%M'
    decimal: .

fs_args: 配置与文件系统的交互。fs_args的所有顶级参数（除了open_args_load和open_args_save）将被传递给底层的文件系统类。

例如，要为底层文件系统类(GCSFileSystem)提供project值以便与Google云存储交互：

test_dataset:
  type: ...
  fs_args:
    project: test_project

open_args_load 和 open_args_save 参数会被传递给文件系统的 open 方法，分别用于配置在加载或保存操作期间如何打开数据集文件（在特定文件系统上）。

例如，使用utf-8编码从本地二进制文件加载数据：

test_dataset:
  type: ...
  fs_args:
    open_args_load:
      mode: "rb"
      encoding: "utf-8"

如果要以追加模式而非覆盖模式保存文件，可以使用 open_args_save 的 mode 参数：

test_dataset:
  type: ...
  fs_args:
    open_args_save:
      mode: "a"

注意

默认的加载、保存和文件系统参数分别在特定数据集实现中定义为DEFAULT_LOAD_ARGS、DEFAULT_SAVE_ARGS和DEFAULT_FS_ARGS。您可以在the dataset API documentation中查看这些参数。

数据集访问凭证¶

数据目录还与conf/local/中的credentials.yml文件配合使用，允许您指定加载某些数据集所需的用户名和密码。

在实例化DataCatalog之前，Kedro会首先尝试从项目配置中读取凭证。然后将生成的字典作为credentials参数传递给DataCatalog.from_config()。

假设项目中包含文件 conf/local/credentials.yml，其内容如下：

dev_s3:
  client_kwargs:
    aws_access_key_id: key
    aws_secret_access_key: secret

数据目录在catalog.yml中定义如下：

motorbikes:
  type: pandas.CSVDataset
  filepath: s3://your_bucket/data/02_intermediate/company/motorbikes.csv
  credentials: dev_s3
  load_args:
    sep: ','

在上面的示例中，catalog.yml文件包含对凭证密钥dev_s3的引用。数据目录首先从接收到的credentials字典中读取dev_s3，然后将其值作为credentials参数传递给__init__的数据集。

数据集版本控制¶

Kedro 通过 versioned 定义实现数据集和机器学习模型版本控制。例如：

cars:
  type: pandas.CSVDataset
  filepath: data/01_raw/company/cars.csv
  versioned: True

在这个示例中，filepath被用作存储cars数据集版本的文件夹基础路径。每次通过流水线运行创建新版本时，数据会被存储在data/01_raw/company/cars.csv//cars.csv路径下，其中对应格式为YYYY-MM-DDThh.mm.ss.sssZ的版本字符串。

默认情况下，kedro run会加载数据集的最新版本。不过，你也可以通过--load-version标志指定特定版本的数据集，如下所示：

kedro run --load-versions=cars:YYYY-MM-DDThh.mm.ss.sssZ

其中 --load-versions 是数据集名称和版本时间戳，由 : 分隔。

如果一个数据集扩展了AbstractVersionedDataset类，接受版本关键字参数作为构造函数的一部分，并调整_save和_load方法以使用分别从_get_save_path和_get_load_path获取的版本化数据路径，则该数据集提供版本控制支持。

要验证数据集是否支持版本控制，您应检查数据集类的代码以查看其继承关系（可在kedro-datasets代码库中找到贡献的数据集）。确认数据集类是否继承自AbstractVersionedDataset。例如，如果您遇到类似CSVDataset(AbstractVersionedDataset[pd.DataFrame, pd.DataFrame])的类，这表明该数据集已配置为支持版本控制。

注意

请注意，在数据集实现中支持HTTP(S)文件系统，但如果使用它，则无法同时使用版本控制功能。

在Kedro配置中使用数据目录¶

Kedro配置使您能够为数据管道的不同阶段组织项目。例如，您可能需要对开发、测试和生产环境使用不同的数据目录设置。

默认情况下，Kedro有一个base和一个local文件夹用于配置。数据目录配置通过配置加载器类加载，该类会递归扫描conf文件夹内的配置文件，首先在conf/base中查找，然后在conf/local中查找（这是指定的覆盖环境）。Kedro会根据配置文档中规定的规则合并配置信息并返回一个配置字典。

总之，如果您需要为不同环境配置数据集，可以同时创建conf/base/catalog.yml和conf/local/catalog.yml。例如，您可以使用conf/base/目录中的catalog.yml文件注册生产环境运行的数据集位置，同时在conf/local/目录中添加第二个版本的catalog.yml来注册原型设计数据管道时使用的样本数据集位置。

为了说明这一点，请查看以下针对名为cars的数据集的目录条目，该条目位于conf/base/catalog.yml中，指向存储在AWS S3存储桶中的csv文件：

cars:
  filepath: s3://my_bucket/cars.csv
  type: pandas.CSVDataset

你可以在conf/local/catalog.yml中覆盖此目录条目，使其指向本地存储的文件：

cars:
  filepath: data/01_raw/cars.csv
  type: pandas.CSVDataset

在您的流水线代码中，当使用cars数据集时，它将使用来自conf/local/catalog.yml的重写目录条目，并依赖Kedro来检测在流水线中使用哪个cars数据集定义。

数据目录简介¶

catalog.yml基础¶

在catalog.yml中配置数据集参数¶

数据集 type¶

数据集 filepath¶

catalog.yml中的其他设置¶