通过ibm-lh工具进行Spark摄取
您可以使用 IBM Analytics Engine (Spark),通过命令行界面 (CLI) 运行 ibm-lh 工具,将数据摄取到 IBM® watsonx.data 中。 本主题中列出了用于运行摄入作业的命令。
准备工作
- 您必须在目录中拥有管理员角色和权限,才能通过网络控制台进行摄取。
- 添加并注册 IBM Analytics Engine (Spark)。 请参见 配置 Spark 引擎。
- 为目标目录添加存储器。 请参阅 添加存储。
- 在目录中为要采集的数据创建模式和表。 请参阅 创建模式 和 创建表。
过程
-
通过运行以下命令,在启动摄入作业之前,将必需环境变量
ENABLED_INGEST_MODE
设置为SPARK_LEGACY
:export ENABLED_INGEST_MODE=SPARK_LEGACY
-
通过运行以下命令,在启动摄入作业之前设置以下环境变量:
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。 -
您可以使用简单命令行或配置文件来运行采集作业,以 2 方式采集数据。
-
运行以下命令以从单个或多个源数据文件采集数据:
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 源文件或文件夹的页眉和分隔符值。 -
运行以下命令以从配置文件采集数据:
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'"
。 使用此语法,句点(.)不会被转义,在使用额外的单引号时也不需要使用转义字符。
-