IBM Cloud Docs
通过ibm-lh工具进行Spark摄取

通过ibm-lh工具进行Spark摄取

您可以使用 IBM Analytics Engine (Spark),通过命令行界面 (CLI) 运行 ibm-lh 工具,将数据摄取到 IBM® watsonx.data 中。 本主题中列出了用于运行摄入作业的命令。

准备工作

  • 您必须在目录中拥有管理员角色和权限,才能通过网络控制台进行摄取。
  • 添加并注册 IBM Analytics Engine (Spark)。 请参见 配置 Spark 引擎
  • 为目标目录添加存储器。 请参阅 添加存储
  • 在目录中为要采集的数据创建模式和表。 请参阅 创建模式创建表

过程

  1. 通过运行以下命令,在启动摄入作业之前,将必需环境变量 ENABLED_INGEST_MODE 设置为 SPARK_LEGACY :

    export ENABLED_INGEST_MODE=SPARK_LEGACY
    
  2. 通过运行以下命令,在启动摄入作业之前设置以下环境变量:

    export IBM_LH_BEARER_TOKEN=<token>
    export IBM_LH_SPARK_JOB_ENDPOINT=https://<cpd_url>/v4/analytics_engines/<instance_id>/spark_applications
    export HMS_CLIENT_USER=lakehouse
    export HMS_CLIENT_PASSWORD=<instance secret>
    export SOURCE_S3_CREDS="AWS_ACCESS_KEY_ID=*******,AWS_SECRET_ACCESS_KEY=*******,ENDPOINT_URL=<endpoint_url>,AWS_REGION=<region>,BUCKET_NAME=<bucket_name>"
    export TARGET_S3_CREDS="AWS_ACCESS_KEY_ID=*******,AWS_SECRET_ACCESS_KEY=*******,ENDPOINT_URL=<endpoint_url>,AWS_REGION=<region>,BUCKET_NAME=<bucket_name>"
    export IBM_LH_SPARK_EXECUTOR_CORES=<value>
    export IBM_LH_SPARK_EXECUTOR_MEMORY=<value>
    export IBM_LH_SPARK_EXECUTOR_COUNT=<value>
    export IBM_LH_SPARK_DRIVER_CORES=<value>
    export IBM_LH_SPARK_DRIVER_MEMORY=<value>
    export INSTANCE_ID=<instance_id>
    export USE_NATIVE_SPARK=<true/false>
    export USE_EXTERNAL_SPARK=<true/false>
    export IBM_LH_URL=https://<lh_hostname>
    export IBM_LH_USER_BEARER_TOKEN=<token>
    

    如果 IBM Analytics Engine 上的 IBM Cloud Serverless 实例在 watsonx.data 上注册为外部 Spark,则 Spark 驱动程序、执行器 vCPU 和内存组合的比例必须为 1:2、1:4 或 1:8。 请参阅 Analytics Engine 实例的默认限制和配额

    表 1
    环境变量名称 描述
    IBM_LH_BEARER_TOKEN 授权不记名令牌。 更多信息,请参阅 https://cloud.ibm.com/docs/account?topic=account-iamtoken_from_apikey。 对于 USE_EXTERNAL_SPARK=true,应使用外部 Spark 引擎 API 密钥生成承载令牌。
    IBM_LH_SPARK_JOB_ENDPOINT 用于 CPD 的 Spark 应用程序 v4 端点和用于 SaaS的 v3 端点。 检索 SaaS Spark 端点:https://cloud.ibm.com/docs/AnalyticsEngine?topic=AnalyticsEngine-retrieve-endpoints-serverless
    HMS_CLIENT_USER 元数据服务客户端的用户。 SaaS Spark 实施使用 ibmlhapikey
    HMS_CLIENT_PASSWORD 元数据服务客户端的密码。 对于 SaaS, 您可以使用已部署 watsonx.data 的云账户中名为 ibmlhapikey 的 API 密钥。
    SOURCE_S3_CREDS S3 源文件存储凭证,格式为:“AWS_ACCESS_KEY_ID=<access_key>,AWS_SECRET_ACCESS_KEY=<secret_key>,ENDPOINT_URL=<endpoint_url>,AWS_REGION=<region>,BUCKET_NAME=<bucket_name>”
    TARGET_S3_CREDS S3 目标表存储的证书格式:“AWS_ACCESS_KEY_ID=<access_key>,AWS_SECRET_ACCESS_KEY=<secret_key>,ENDPOINT_URL=<endpoint_url>,AWS_REGION=<region>,BUCKET_NAME=<bucket_name>”
    IBM_LH_SPARK_EXECUTOR_CORES 执行核心的可选火花引擎配置设置。
    IBM_LH_SPARK_EXECUTOR_MEMORY 执行器内存的可选火花引擎配置设置。
    IBM_LH_SPARK_EXECUTOR_COUNT 执行器数量的可选火花引擎配置设置。
    IBM_LH_SPARK_DRIVER_CORES 用于驱动核的可选火花引擎配置设置。
    IBM_LH_SPARK_DRIVER_MEMORY 可选的火花发动机配置设置,供驾驶员记忆。
    INSTANCE_ID 确定独特的实例。 在 SaaS 环境中,CRN 是实例 ID。 这是一个强制性参数。
    USE_NATIVE_SPARK 如果使用本地 spark 进行摄取,该参数值必须为 true。 这是一个强制性参数。
    USE_EXTERNAL_SPARK 当使用外部火花进行摄取时,该参数值必须为 true
    IBM_LH_URL 该参数仅在 USE_EXTERNAL_SPARK=true 时使用。 值为 https://<lh_hostname><lh_hostname> 是 watsonx.data 实例的主机名。
    IBM_LH_USER_BEARER_TOKEN 该参数仅在 USE_EXTERNAL_SPARK=true 时使用。 承载令牌应使用用户 API 密钥生成。 更多信息,请参阅 https://cloud.ibm.com/docs/account?topic=account-iamtoken_from_apikey。
  3. 您可以使用简单命令行或配置文件来运行采集作业,以 2 方式采集数据。

    1. 运行以下命令以从单个或多个源数据文件采集数据:

      ibm-lh data-copy --source-data-files s3://path/to/file/or/folder \
      --target-table <catalog>.<schema>.<table> \
      --ingestion-engine-endpoint "hostname=<hostname>,port=<port>,type=spark" \
      --trust-store-password <truststore password> \
      --trust-store-path <truststore path> \
      --log-directory /tmp/mylogs \
      --partition-by "<columnname1>, <columnname2> \
      --target-catalog-uri 'thrift://<mds_thrift_uri>'
      

      其中使用的参数列示如下:

      表 2
      参数 描述
      --source-data-files s3parquet 或 CSV 文件或文件夹的路径。 文件夹路径必须以 "/" 结尾。 文件名区分大小写。
      --target-table 目标表格式为 <catalogname>.<schemaname>.<tablename>
      --log-directory 该选项用于指定日志文件的位置。
      --ingestion-engine-endpoint 摄取引擎端点的格式为 hostname=’’,port=’’,type=spark”。 类型必须设置为火花。
      --partition-by 该参数支持 partition-by 列表中时间戳的年、月、日、小时功能。 如果目标表已经存在或未提及 create-if-not-exist 参数,则分区-by 不会对数据产生任何影响。
      --trust-store-password spark 作业 pod 内信任存储证书的密码。 CPD 和SaaS中 Spark 的当前密码为 changeit
      --trust-store-path 火花任务 pod 中信任存储证书的路径。 目前 Spark 在 CPD 和SaaS领域的发展方向是 file:///opt/ibm/jdk/lib/security/cacerts
      --target-catalog-uri MDS 节俭终点。
      SaaS endpoint example: thrift://<metastore_host_value>. <metastore_host_value> is taken from the details tab of the catalog in the Infrastructure page.
      --create-if-not-exist 如果未创建目标模式或表,请使用此选项。 如果目标模式或表已创建,请勿使用。
      --schema 使用该选项时,其值格式为 path/to/csvschema/config/file。 使用schema.cfg文件的路径,该文件指定 CSV 源文件或文件夹的页眉和分隔符值。
    2. 运行以下命令以从配置文件采集数据:

      ibm-lh data-copy --ingest-config /<your_ingest_configfilename>
      

      其中配置文件具有以下信息:

      [global-ingest-config]
      target-tables:<catalog>.<schema>.<table>
      ingestion-engine:hostname='',port='',type=spark
      create-if-not-exist:true/false
      
      [ingest-config1]
      source-files:s3://path/to/file/or/folder
      target-catalog-uri:thrift://<mds_thrift_uri>
      trust-store-path:<truststore path>
      trust-store-password:<truststore password>
      log-directory /tmp/mylogs
      partition-by "<columnname1>, <columnname2>
      schema:/path/to/csvschema/config/file [Optional]
      

      配置文件摄入作业中使用的参数列示如下:

      表 3
      参数 描述
      source-files s3parquet 或 CSV 文件或文件夹的路径。 文件夹路径必须以"/"结尾
      target-table 目标表格式为 <catalogname>.<schemaname>.<tablename>
      ingestion-engine 摄取引擎端点的格式为 hostname=’’, port=’’,type=spark”。 类型必须设置为火花。
      log-directory 该选项用于指定日志文件的位置。
      --partition-by 该参数支持 partition-by 列表中时间戳的年、月、日、小时功能。 如果目标表已经存在或未提及 create-if-not-exist 参数,则分区-by 不会对数据产生任何影响。
      trust-store-password spark 作业 pod 内信任存储证书的密码。 CPD 和SaaS中 Spark 的当前密码为 changeit
      trust-store-path 火花任务 pod 中信任存储证书的路径。 目前 Spark 在 CPD 和SaaS领域的发展方向是 file:///opt/ibm/jdk/lib/security/cacerts
      target-catalog-uri MDS 节俭终点。
      CPD endpoint example: thrift://<metastore_host_value>. <metastore_host_value> is taken from the details tab of the catalog in the Infrastructure page.
      SaaS endpoint example: thrift://<metastore_host_value>. <metastore_host_value> is taken from the details tab of the catalog in the Infrastructure page.
      create-if-not-exist 如果未创建目标模式或表,请使用此选项。 如果目标模式或表已创建,请勿使用。
      schema 使用该选项时,其值格式为 path/to/csvschema/config/file。 使用schema.cfg文件的路径,该文件指定 CSV 源文件或文件夹的页眉和分隔符值。

    处理表和架构名称中的特殊字符的能力受到底层引擎(Spark、Presto) 及其各自的特殊字符支持。

    • 常规语法:--target-tables <catalogname>.<schemaname>.<tablename>
    • 带有特殊字符选项 1 的语法:--target-tables <catalogname>.<schemaname>."table\.name"。 使用此语法,转义字符 \ 在双引号内使用以转义句点 (.)。转义字符 \ 仅当表名中存在特殊字符句点(.)时使用。
    • 特殊字符选项 2 的语法:--target-tables <catalogname>.<schemaname>."'table.name'"。 使用此语法,句点(.)不会被转义,在使用额外的单引号时也不需要使用转义字符。