飞行数据请求

数据请求语法和属性

Cloud Pak for Data 中使用的数据请求具有以下结构。 数据请求的实际实例通常不包含列出的所有属性，并且可能使用特定于特定数据源的其他交互属性。

要了解哪个连接器支持哪些交互属性，请参阅定义的数据源类型列表。

请求示例:

curl --request GET --url 'https://<host:port>/v2/datasource_types?connection_properties=true&interaction_properties=true' --header 'Accept: application/json' --header 'Authorization: Bearer <token>'

数据请求对象语法

以下数据请求显示了 Python 表示法中的语法。 但是，该描述对于 R 也有效。

data_request = {

    # The Flight Service expects assets to be identified by their GUID.
    # "asset_id" is the ID of connected data asset or a connection asset.
    "asset_id": "ASSET_GUID",
    "project_id|space_id|catalog_id": "GUID",

    # itc_utils.flight_service adds support for using asset names
    # use either one of ...
    "data_name" : "name of a plain data asset",
    "connection_name" : "name of a connection asset",
    "connected_data_name" : "name of a 'connected data' asset",
    # by default the assets will be looked up in the current project
    # itc_utils will set "asset_id" from the provided name.

    # "asset_id" and "connection_properties" are mutually exclusive
    "connection_properties": { # optional
        # not needed in most cases
    },

    "interaction_properties": {
        # commonly used properties, all optional
        "file_name" : "file in a connected data source",
        "schema_name" : "schema of a table in a connected database",
        "table_name" : "name of a table in a connected database",
        "row_limit" : NROWS,
        "infer_schema" : false|true,
        "invalid_data_handling" : "fail|row|column",
        ...
    },
    "fields": [...] # optional
    "num_partitions": N, # optional
    "batch_size": NROWS, # optional
    "commit_frequency" : NROWS # optional

}

支持的属性，值和描述

在大多数情况下不使用 "connection_properties" ，尤其是在 Notebook 中，使用 "connection_properties" 会增加泄露凭证的风险。 如果您尚未添加任何项目资产，但想要从外部数据源访问数据或将数据写入外部数据源，那么将使用 "connection_properties"。 如果数据位于外部数据源中，请指定连接资产中的连接属性，并在数据请求中引用此连接。

"interaction_properties" 取决于数据源类型。 有关每个数据源支持的属性列表，请参阅定义的数据源类型列表。

属性的描述:

• "project_id": Cloud Pak for Data 项目的 GUID。

• "asset_id": 项目，目录或部署空间中数据资产，连接资产或已连接数据资产的 GUID。

• "num_partitions": 某些数据源可以通过多个端点提供对数据的访问。 这可用于读取并行线程中的多个流。 "num_partitions" 的值定义期望 Flight service 向客户机提供的端点数。 如果数据源不支持多个端点，那么将忽略 "num_partitions" 的值。 如果该值与其他属性 (例如 "row_limit") 冲突，那么该值也可能会被忽略。

• "batch_size": 飞行从数据块中的数据库读取行，在类型为 RecordBatch的对象中进行内部管理。 "batch_size" 设置每个区块要从源读取的行数。 设置较低的批处理大小可能会导致大量性能开销。

• "commit_frequency": 写入 n 行后自动落实数据库事务。 仅在将数据写入 SQL 数据库时使用。

• "interaction_properties.row_limit": 限制从源读取的行数。 通常，在浏览数据时应该从限制开始。 否则，运行时可能会耗尽内存。 设置 "row_limit" 通常会导致忽略 "num_partitions" 的任何值，缺省为 1。

• "interaction_properties.infer_schema": 您可以传递 "infer_schema": true ，飞行服务将读取文件并对字段格式进行最佳猜测。 它仅读取前 1000 行，因此如果某个字段在前 1000 行中未很好地混合使用可用属性，那么可能推断错误。 例如，通过读取前 1000 行中的 0 或 1 ，可能会得出以下结论: 当列应该是整数时，该列是布尔值，因为后面的行具有大于 1 的值。

• "interaction_properties.invalid_data_handling": 定义如何处理无效的值，例如，使作业失败，列为空或删除行。

• "fields": 在读取数据时使用，在写入数据时不使用。 "fields" 枚举要从数据源中选择的字段 (也称为列)。 从 CSV 或定界文件中读取时，此字段列表定义文件中字段的名称和类型。 文件中值的布局必须与字段列表完全匹配。 每个字段都必须同时指定名称和数据类型。

  但是，对于某些数据源，例如从 Parquet 文件或外部 SQL 数据库中的表进行读取时，字段列表可以指定要从源中读取的列的子集。

  Flight service 不会读取其他列。 缺省情况下，将检索表的所有列。 每个字段都必须同时指定名称和数据类型。 该类型可以覆盖外部表中列的类型。 例如，存储为 VARCHAR(10) 的列可以映射到 Flight 中的 bigint 。 写入数据库时不使用 "fields" 属性; 相反， Flight service 使用 do_put(...)中提供的模式。

  "fields" 编写为字典列表，其中必须至少包含 "name" 和 "type" 属性。

  以下示例显示了如何使用 Python 表示法中的 "fields" 属性。 但是，该描述对于 R 也有效。

      "fields": [{"name":"a","type":{"type":"bigint"}},
             {"name":"b","type":{"type":"varchar"}}
            ]
  

  请注意， type 属性的值是另一个具有另一个 type 属性的字典。

  如果在数据请求中提供了 "fields" 属性，那么 "劣模式" 属性将隐式设置为 false ，因为 "fields" 已定义数据类型。

  "fields" 中的 "type" 属性支持的值为 (名称不区分大小写) :ARRAY ， BIGINT ， BINARY ， BIT ， BLOB ， BOOLEAN ， CHAR ， CLOB ， DATALINK ， DATE ， DECIMAL ， DISTINCT ， DOUBLE ， FLOAT ， INTEGER ， JAVA_OBJECT ， LONGNVARCHAR ， LONGVARBINARY ， LONGVARCHAR ， NCHAR ， NCLOB ， NULL ， NUMERIC ， NVARCHAR ， OTHER ， REAL ， REF ， REF_CURSOR ， ROWID ， SMALLINT ， SQLXML ， STRUCT ， TIME ， TIME_WITH_TIMEZONE ，

  "fields" 中 "type" 属性的值是 Cloud Pak for Data中的 Flight service 所使用的名称。 读取数据时，这些类型会映射到开源 Arrow Flight 中使用的数据类型。 请参阅数据类型和内存数据模型。 例如， TINYINT 映射到 int8() ， BIGINT 映射到 int64()。

  如果您使用 pandas DataFrames 并想检查 Flight 和 pandas 中数据类型之间的映射，请参阅类型差异。

  "fields" 属性不仅指定列的名称和数据类型，还定义更多详细信息。 以下示例显示了 Python 表示法中 "fields" 模板的结构。 但是，该描述对于 R 也有效。

  {
      "name": "fieldname",
      "type": {
          "type": "typename",
          "length": L ,     # integer, depends on type
          "scale": S,       # integer depends on type, only numeric and decimal
          "signed": true or false   # for numeric types
      }
  }
  

  "length" 和 "scale" 的组合定义了数字或十进制数据类型的精度和小数位。

  属性 "signed" 影响被认为有效的值的类型和范围。 例如：

  • {"type":"TINYINT","signed":true} 映射到 Flight 中的类型 int8() 。 有效值为 -128 <= signed tinyint <= 127
  • {"type":"TINYINT","signed":False} 映射到 Flight 中的类型 uint8() 。 有效值为 0 <= unsigned tinyint <= 255

了解更多

• 使用 Python的Flight service
• Flight service

父主题: Flight service ，用于访问数据源