腾讯云数据仓库 TCHouse-X 使用 Spark-Submit 命令行工具连接实例

二、Step1：下载 CLI 工具

1. 登录你计划提交 Spark 作业的 Linux 客户端机器，使用 curl 或 wget 命令下载 TCHouse-X-Spark-Submit 命令行工具压缩包：

curl -O https://tchousex-doc-1375622477.cos.ap-guangzhou.myqcloud.com/spark-submit/tchouse-x-toolkit-spark-submit-1.0.0.zip或者wget https://tchousex-doc-1375622477.cos.ap-guangzhou.myqcloud.com/spark-submit/tchouse-x-toolkit-spark-submit-1.0.0.zip

注意：若你的 Linux 环境中未安装 curl 或 wget，请根据系统类型使用相应的包管理器进行安装（例如：sudo apt install wget 或 sudo yum install curl）。

2. 下载完成后，执行以下命令解压工具压缩包：

unzip tchouse-x-toolkit-spark-submit-1.0.0.zip

3. 解压操作将创建一个名为 tchouse-x-spark-submit 的目录。该目录是工具的根目录，其结构如下：

·<bin> 目录：包含核心的可执行程序 spark-submit，用于在 Linux 环境中提交作业。

·<conf> 目录：包含配置文件 spark-defaults.conf，用于配置 TCHouse-X 集群连接信息和默认运行参数。

三、Step2：配置连接参数

进入<tchouse-x-spark-submit> 根目录，编辑 conf/spark-defaults.conf 文件，配置连接 TCHouse-X 实例所需的参数。

四、默认配置文件内容预览

## 请配置腾讯云CAM用户的SecretID和SecretKey, 获取方式请参见: https://cloud.tencent.com/document/product/598/37140## 必填; 若不配置, 执行命令会失败secretId =secretKey =## 请配置TCHouse-X实例所在的地域, 暂仅支持广州地域(ap-guangzhou)## 必填; 暂不支持修改; 若修改, 执行命令会失败region = ap-guangzhou## 可配置默认使用的TCHouse-X实例ID, 实例ID可在控制台查看: https://console.cloud.tencent.com/tchousex?region=ap-guangzhou## 非必填; 若不配置、或配置后需使用其他实例, 可在执行命令时指定–instanceId <instanceId>#instanceId = ## 可配置默认使用的driver资源规格## 非必填; 默认值是2x-small, 可选值{2x-small, x-small, small, medium}, 分别对应{4, 8, 16, 32}CU, 1CU=1核CPU4GB内存spark.driver.resourceSpec = 2x-small## 可配置默认使用的executor资源规格## 非必填; 默认值是2x-small, 可选值{2x-small, x-small, small, medium}, 分别对应{4, 8, 16, 32}CU, 1CU=1核CPU4GB内存spark.executor.resourceSpec = 2x-small## 可配置默认使用的executor数量## 非必填; 默认值是1, 可选值[1, 999]spark.executor.instances = 1## 可配置默认使用的存储上传文件的COS桶名称## 非必填; 若不配置、或配置后需使用其他cos桶, 可在执行–upload命令时指定–bucket <bucketName>#cosUploadBucket = ## 可配置其他以spark开头的参数的默认值## 非必填; 若不配置、或配置后需使用其他参数值, 可在执行提交命令时通过–conf <key>=<value>指定

五、必填参数配置说明

参数名称	参数说明	参数值说明	示例
secretId	用户访问腾讯云 API 进行身份验证时需要用到的安全凭证，由 SecretId 和 SecretKey 一起组成，SecretId用于标识 API 调用者身份	获取方式请参见子账号访问密钥管理	secretId = q************************f
secretKey	用户访问腾讯云 API 进行身份验证时需要用到的安全凭证，由 SecretId 和 SecretKey 一起组成，SecretKey 用于验证 API 调用者身份	获取方式请参见子账号访问密钥管理	secretKey = b***********************n
region	TCHouse-X 实例所在的地域		region = ap-guangzhou

六、选填参数配置说明

参数名称	描述	默认值及可选值	示例配置
instanceId	TCHouse-X 实例 ID。	非必填。配置后，提交命令将默认使用该实例。若要覆盖，可在提交时指定 –instanceId。	instanceId = warehouse-p******m
spark.driver.resourceSpec	Spark 作业 Driver 进程的资源规格。	默认值：2x-small。可选值：{2x-small, x-small, small, medium}规格对应：2x-small=4C16G；medium=32C128G。	spark.driver.resourceSpec = 2x-small
spark.executor.resourceSpec	Spark 作业 Executor 进程的资源规格。	默认值：2x-small。可选值：{2x-small, x-small, small, medium}规格对应：2x-small=4C16G；medium=32C128G。	spark.executor.resourceSpec = x-small
spark.executor.instances	运行 Spark 作业所需的 Executor 数量。	默认值：1。可选值：[1, 999]。	spark.executor.instances = 5
cosUploadBucket	用于文件上传（如 JAR 包）的 COS 存储桶名称。	非必填。若不配置，执行 –upload 命令时必须指定 –bucket 参数。	cosUploadBucket = my-bucket-12345678

注意：1. 大小写敏感：所有参数名称及其对应值都是大小写敏感的。

注意：2. 配置扩展：允许添加其他以 spark. 开头的配置参数作为默认值，但不支持添加其他非 spark 开头的 option 参数。

注意：3. 优先级： spark-defaults.conf 中的配置项会被命令行提交时通过 –conf <key>=<value> 指定的参数覆盖（仅单次提交生效）。

七、Step3：提交 Spark 作业

进入 <tchouse-x-spark-submit> 目录，执行 bin/spark-submit 命令提交你的 Spark 应用程序。

八、提交命令语法

以下是 Spark-Submit 命令的完整结构。请注意，应用程序文件和程序参数必须放在命令的末尾。

./bin/spark-submit \\ –name <job-name> \\ [–class <main-class>] \\ [–jars <dependency-jar-path>] \\ [–py-files <dependency-py-files-path>] \\ [–files <dependency-files-path>] \\ [–archives <dependency-archives-path>] [–driver-cores <value> | –conf spark.driver.resourceSpec=<value>] \\ [–executor-cores <value> | –conf spark.executor.resourceSpec=<value>] \\ [–num-executors <value> | –conf spark.executor.instances=<value>] \\ [–config <key>=<value> | –conf <key>=<value>] \\ [–confPath <confPath>] \\ [–instanceId <instanceId>] \\ <application-file> [<application-arguments>]

九、请求参数说明

必填参数

参数名称	描述	约束与说明	示例
–name <job-name>	作业的显示名称，将显示在 TCHouse-X 控制台页面。	必填。支持中文、英文、数字、_ 和 -，最多 100 个字符。	–name Submit_ETL_Job
<application-file>	Spark 主程序包的存储路径。	必填。必须是 cosn:// 开头的绝对路径。支持 JAR 和 Py 文件。	cosn://bucket1/dir1/sparkjar.jar

依赖文件参数 (路径均需以 cosn:// 开头)

参数名称	描述	支持文件类型	格式与说明
–jars	依赖的 Java/Scala JAR 文件。	jar	多个文件间以英文逗号 , 分隔。
–py-files	PySpark 依赖文件。	py, zip, egg	多个文件间以英文逗号 , 分隔。
–files	分发到所有节点的附加文件（如配置文件）。	jar, zip	多个文件间以英文逗号 , 分隔。
–archives	分发的归档文件（如虚拟环境）。	gz, tgz, tar	必须在路径后配置打包方式（如 #venv）。

资源与配置参数 (可覆盖配置文件中的默认值)

参数名称	别名/配置键	描述	可选值	优先级说明	示例
–driver-cores	spark.driver.resourceSpec	Driver 进程的资源规格。	Cores: [4, 8, 16, 32]Spec: {2x-small, x-small, small, medium}	两者任选其一；–conf 优先级高于 –driver-cores。	–conf spark.driver.resourceSpec=x-small
–executor-cores	spark.executor.resourceSpec	Executor 进程的资源规格。	Cores: [4, 8, 16, 32]Spec: {2x-small, x-small, small, medium}	两者任选其一；–conf 优先级高于 –executor-cores。	–executor-cores 16
–num-executors	spark.executor.instances	Executor 数量。	[1, 999]	两者任选其一；–conf 优先级高于 –num-executors。	–num-executors 8
–conf 或 –config	N/A	配置其他以 spark. 开头的参数。	<key>=<value> 格式的 Spark 参数。	每次提交生效；命令行指定的值会覆盖 spark-defaults.conf。	–conf spark.sql.shuffle.partitions=20000
–confPath	N/A	指定自定义配置文件路径。	相对路径或绝对路径。	默认值：./conf/spark-defaults.conf。	–confPath /data/custom.conf

环境参数

参数名称	别名	描述	说明	示例
–instanceId	N/A	目标 TCHouse-X 实例 ID。	若未在配置文件中设置，则必填。	–instanceId instance-p******m
–class	N/A	Java/Scala 程序的主入口类名。	如果提交的是 JAR 文件，则必填。PySpark 不需此参数。	–class org.apache.spark.examples.SparkPi
<application-arguments>	N/A	主程序包的程序入口参数。	必须放在命令末尾。包含空格等特殊字符时，请使用英文双引号包裹。	arg1 "SQL statement"

注意：1. 位置严格要求： <application-file> 和 <application-arguments> 必须按顺序放在命令行的末尾。其他参数顺序可自由调整。

注意：2. 参数优先级：

注意：3. 覆盖关系：命令行参数会覆盖 spark-defaults.conf 中的默认配置。

十、提交样例

./bin/spark-submit \\–name submit-Cli_job1 \\–class org.apache.spark.examples.SparkSql \\–-jars cosn://bucket1/path1/jar1.jar,cosn://bucket1/path1/jar2.jar, cosn://bucket1/path1/jar3.jar \\cosn://bucket1/dir1/sparkjar.jar "-sql create table db1.dt3 as select * from db1.dt1;"

十一、返回参数说明

成功提交 Spark 作业后，命令行工具将立即返回以下信息。TCHouse-X 会自动生成作业 ID 和运行任务 ID。

字段名称	描述	示例值
RequestId	腾讯云 API 请求的唯一标识。	1******************6
ErrorMsg	错误信息（提交成功时为空）。	(空)
SparkJobId	TCHouse-X 中生成的作业 ID（Job ID）。	batch-job-123456
SparkTaskId	当前提交的运行任务 ID（Task ID）。	batch-task-123456

十二、返回示例

RequestId 1******************6ErrorMsgSparkJobId batch-job-123456SparkTaskId batch-task-123456

十四、查看参数说明

进入<tchouse-x-spark-submit>目录, 执行以下命令, 查看操作说明：

./bin/spark-submit –help

十五、查看任务运行状态

进入 <tchouse-x-spark-submit> 目录，执行以下命令，使用已获取的 SparkTaskId 查询 Spark 作业任务的实时状态和详情。

./bin/spark-submit –status \\–taskId <taskId> \\

十六、请求参数说明

参数名称	是否必填	描述	示例
–status	是	指定执行查看任务状态的命令。	–status
–taskId <taskId>	是	需要查询的 Spark 作业任务 ID。	–taskId batch-task-123456

十七、返回参数说明

参数名称	描述	参数值说明	示例
RequestId	腾讯云 API 请求的唯一标识 ID。	–	RequestId 6******************************b
ErrorMsg	错误信息。	若查询成功，则该字段为空。	ErrorMsg error: wrong taskId
Status	任务运行状态。	任务状态列表initializing: 初始化中running: 运行中success: 运行成功failed: 运行失败canceled: 已取消运行	Status running
BeginTime	Spark 任务开始运行的时间。	格式：YYYY-MM-DD HH:MM:SS	BeginTime 2024-10-29 10:02:45
EndTime	Spark 任务结束运行的时间。	仅在任务状态为 success、failed 或 canceled 时存在。	EndTime 2024-10-29 10:03:30
ExecuteTime	Spark 任务运行总耗时。	带有单位（如 s、min）。	ExecuteTime 45s
SparkErrLog	Spark 任务运行中的错误日志摘要。	若任务无错误，则值为空。	SparkErrLog wrong sparkContext

十八、查看任务运行日志详情

进入 <tchouse-x-spark-submit> 目录，执行 –get-log 命令获取指定 Spark 作业任务的详细运行日志，以便进行故障诊断和流程跟踪。

./bin/spark-submit –get-log \\ –taskId <taskId> \\ [–pod <podName>] \\ [–orderBy <desc | asc>] \\ [–limit <limit>] \\ [–confPath <confPath>] \\

十九、请求参数说明

参数名称	是否必填	描述	可选值/说明	默认值/示例
–get-log	是	指定执行查看任务日志的命令。	无参数值。	–get-log
–taskId <taskId>	是	需要查询日志的 Spark 任务 ID。	可通过 –list 命令查看已提交的任务列表。	–taskId batch-task-123456
–pod <podName>	否	期望查看的 Pod（Driver 或 Executor）日志。	可选值：{driver, exec-0, exec-1, …} (Executor 编号从 0 开始)。	默认值：driver 示例：–pod exec-1
–orderBy <desc \| asc>	否	日志的排序方式（时间戳）。	可选值：{desc, asc}。	默认值：desc
–limit <limit>	否	单次请求返回的日志行数限制。	范围：(0, 1000]。	默认值：1000示例：–limit 100
–confPath <confPath>	否	指定自定义配置文件路径。	支持相对路径、绝对路径。	默认值：./conf/spark-defaults.conf

20、请求示例

# 获取 batch-task-123456 任务中第一个 Executor 的日志，并按时间升序排列：./bin/spark-submit –get-log \\ –taskId batch-task-123456 –pod exec-0 –orderBy asc

21、返回参数说明

参数名称	描述	示例值
RequestId	腾讯云 API 请求的唯一标识 ID。	6********************************b
ErrorMsg	错误信息。	若查询成功，则该字段为空。
SparkLogList	Spark 任务的运行日志内容。	(返回实际的日志文本内容)

22、查看作业列表

进入 <tchouse-x-spark-submit> 目录，执行 –list 命令，查询目标 TCHouse-X 实例下用户提交的 Spark 作业（Job）列表。

./bin/spark-submit –list \\ [–confPath <confPath>] \\ [–instanceId <instanceId>] \\ [–pageSize <pageSize>] \\ [–pageNumber <pageNumber>]

23、请求参数说明

参数名称	是否必填	描述	默认值/说明
–list	是	指定执行查看作业列表的命令。	无参数值。
–instanceId <instanceId>	条件必填	期望查看的 Spark 作业列表所属的 TCHouse-X 实例 ID。	若已在配置文件中设置，可省略。主账号内实例 ID 唯一。
–pageSize <pageSize>	否	返回的 Spark 作业列表中每页显示的记录数。	默认值：10。可选值：大于 0 的整数。
–pageNumber <pageNumber>	否	期望查看的页数。	默认值：1。
–confPath <confPath>	否	指定自定义配置文件路径。	默认值：./conf/spark-defaults.conf。

24、返回参数说明

执行 –list 命令后，系统返回结果将包含请求信息摘要、总数以及作业列表的详细字段。

参数名称	描述	参数值说明	示例
RequestId	腾讯云 API 请求的唯一标识 ID。	–	RequestId 6*************************b
ErrorMsg	错误信息。	若请求成功，该字段为空。	ErrorMsg error: wrong instanceId
TotalCount	符合查询条件的总作业数量。	–	TotalCount 70
InstanceId	Spark 作业所属的 TCHouse-X 实例 ID。	–	InstanceId warehouse-p******m
JobId	Spark 作业 ID（Job ID）。	提交作业时自动生成的唯一标识。	SparkJobId batch-job-*****
SparkName	Spark 作业名称。	提交时 –name 参数的值。	SparkName ETL_Processing_Job
File	Spark 作业主程序包的 COS 存储路径。	提交时 <application-file> 参数的值。	File cosn://bucket1/dir1/sparkjar.jar
ClassName	Java 或 Scala 程序的主入口类名。	提交时 –class 参数的值。	ClassName org.apache.spark.examples.SparkPi
Args	Spark 主程序包的程序入口参数。	提交时 <application-arguments> 参数的值。	Args arg1 arg2
Configs	Spark 运行时配置参数。	提交时 –conf 参数的值。	Configs spark.network.timeout=120s
Jars	依赖的 Jar 文件路径列表。	提交时 –jars 参数的值。	Jars cosn://bucket1/path1/jar1.jar
Files	依赖的 Files 文件路径列表。	提交时 –files 参数的值。	Files cosn://bucket1/path1/jar1.zip
PyFiles	依赖的 PyFiles 文件路径列表。	提交时 –py-files 参数的值。	PyFiles cosn://bucket1/path1/pyfiles.py
Archives	依赖的 Archives 文件路径列表。	提交时 –archives 参数的值。	Archives cosn://bucket1/path1/archives.gz#venv
DriverCores	Spark Driver 资源的核数。	根据提交时配置的资源规格 (spark.driver.resourceSpec 或 –driver-cores) 转换。	DriverCores 4
ExecutorCores	Spark Executor 资源的核数。	根据提交时配置的资源规格 (spark.executor.resourceSpec 或 –executor-cores) 转换。	ExecutorCores 4
ExecutorNum	Spark Executor 的数量。	提交时配置的 spark.executor.instances 或 –num-executors 参数的值。	ExecutorNum 4
CreateTime	Spark 作业在服务端创建的时间。	–	CreateTime 2024-10-29 00:06:24
ModifyTime	Spark 作业的最后修改时间。	–	ModifyTime 2024-10-29 00:06:28
Creator	提交 Spark 作业的用户 UIN (主账号 ID)。	配置文件中 secretId 对应的用户 UIN。	Creator 747951370
UserName	提交 Spark 作业时使用的 TCHouse-X 用户名。	–	UserName user1
CurrentTaskNum	该 Spark 作业下当前正在运行的任务数量。	–	CurrentTaskNum 0

25、取消运行任务

进入 <tchouse-x-spark-submit> 目录，执行 –kill 命令可以中断并取消正在运行中的 Spark 作业任务。

./bin/spark-submit –kill \\ –taskId <taskId> \\ [–instanceId <instanceId>]

26、请求参数说明

参数名称	是否必填	描述	默认值/说明	示例
–kill	是	指定执行取消运行任务的命令。	无参数值。	–kill
–taskId <taskId>	是	期望取消运行的 Spark 任务 ID。	可通过 –list 命令或提交成功后的返回结果获取。	–taskId batch-task-******g
–instanceId	条件必填	TCHouse-X 实例 ID。	若已在配置文件中设置，可省略。	–instanceId warehouse-p******m

27、请求示例

./spark-submit –kill \\ –taskId batch-task-b***g

28、返回参数说明

参数名称	描述	示例
RequestId	取消运行命令的 API 请求 ID。	RequestId 6***************************b
ErrorMsg	错误信息或操作结果。	取消成功： ErrorMsg 字段将为空，表示任务已成功取消（任务状态变为 canceled）。取消失败：仅当 Spark 任务处于 initializing 或 running 状态时才能被取消。如果任务已结束（例如 success 或 failed），操作将失败，并在 ErrorMsg 中提示失败原因。

29、上传文件

要将你的本地文件上传至腾讯云对象存储（COS），请首先进入 <tchouse-x-spark-submit> 目录，然后使用以下格式运行 spark-submit –upload 命令。

./bin/spark-submit –upload \\ [–confPath <confPath>] \\ [–bucket-name <bucket-name>] \\ –key <cosPath/fileName.fileFormat> \\ –localFilePath <localPath/fileName.fileFormat>

30、请求参数说明

参数名称	是否必填	描述	参数值说明	示例
–upload	是	指定运行上传操作。	无参数值。	–upload
–confPath <path>	否	指定配置文件的路径。默认值：./conf/spark-defaults.conf	支持相对路径或绝对路径。	–confPath ./conf/custom-config.conf
–bucket <name>	条件必填	存储上传文件的 COS 存储桶名称。说明：若配置文件中已配置 cosUploadBucket 参数且你希望上传到该桶，则可省略此参数。	COS 存储桶名称。无需指定地域。	–bucket my-data-bucket-12345678
–key <cosPath>	是	文件在 COS 存储桶中的目标路径。注意：如果目标文件夹不存在，你的 secretId 必须具有创建 COS 文件夹的权限，否则上传将失败。	完整路径，包括文件夹、文件名和文件格式。	–key project/jars/mySparkJob.jar
–localFilePath <path>	是	本地待上传文件的完整路径。	本地文件路径，支持相对路径或绝对路径。	–localFilePath /tmp/data/localFile.csv

31、请求示例

./bin/spark-submit –upload \\ –bucket my-bucket-12345678 \\ –key folder1/subFolder1/myCosSparkJar.jar \\ –localFilePath localSubFoler1/myLocalSparkJar.jar

32、返回示例

Transfer Start [ConsumedBytes/TotalBytes: 0/26722018]Transfer Data [ConsumedBytes/TotalBytes: 26722018/26722018, 100%]Transfer Complete [ConsumedBytes/TotalBytes: 26722018/26722018]upload file success, cos path: cosn://my-bucket-12345678/–key folder1/subFolder1/myCosSparkJar.jar

34、配置参数对比

参数名称	参数说明 (社区版定义)	社区版是否支持	TCHouse-X 是否支持	TCHouse-X 定制化说明
spark.driver.cores	Driver 进程使用的核心数（仅限 cluster 模式）。	是 (默认值 1)	否	参数名称已调整为 spark.driver.resourceSpec，值必须是规格名称（如 x-small）。资源配比固定为 CPU:内存 ≈ 1:4。
spark.driver.memory	Driver 进程使用的内存量（带单位，如 512m, 2g）。	是 (默认值 1g)	否
spark.executor.cores	每个 Executor 使用的核心数。	是 (默认值 1)	否	参数名称已调整为 spark.executor.resourceSpec，值必须是规格名称（如 small）。资源配比固定为 CPU:内存 ≈ 1:4。
spark.executor.memory	每个 Executor 进程使用的内存量（带单位，如 512m, 2g）。	是 (默认值 1g)	否
spark.executor.instances	运行的 Executor 数量。	是	是	TCHouse-X 完全兼容此参数，用于配置 Executor 实例数。
其他 spark. 开头的配置参数	其他配置参数（如超时、分区等）。	是	是	TCHouse-X 在服务端配置了默认值。如需针对特定作业任务调整，可在配置文件或提交命令中通过 –conf 指定。

35、提交参数对比

参数名称	参数说明 (社区版定义)	社区版支持	TCHouse-X 支持	TCHouse-X 定制化说明
–deploy-mode	指定 Spark 应用的部署模式（client 或 cluster）。	是	否	TCHouse-X 采用统一的 cluster 模式运行，无需用户显式指定。
–master	指定 Spark 集群的 URL 或集群管理器类型 (yarn, mesos, spark://, k8s, local)。	是	否	TCHouse-X 引擎环境固定，通过配置文件中的 instanceId 连接，无需此参数。
–driver-cores	Driver 进程使用的核心数。	是	是 (兼容)	TCHouse-X 兼容此参数，用于配置 Driver 核心数。但推荐使用 spark.driver.resourceSpec 统一配置。
–driver-memory	Driver 进程使用的内存量（带单位，如 2g）。	是	否	资源规格统一化。请使用 spark.driver.resourceSpec 间接控制内存，资源配比固定为 1:4。
–executor-cores	每个 Executor 使用的核心数。	是	是 (兼容)	TCHouse-X 兼容此参数，用于配置 Executor 核心数。但推荐使用 spark.executor.resourceSpec 统一配置。
–executor-memory	每个 Executor 进程使用的内存量。	是	否	资源规格统一化。请使用 spark.executor.resourceSpec 间接控制内存，资源配比固定为 1:4。
–num-executors	运行的 Executor 实例数量。	是	是	完全兼容，或使用别名 spark.executor.instances。
–total-executor-cores	所有 Executor 总共使用的核心数限制（Standalone 模式常用）。	是	否	TCHouse-X 集群资源由 num-executors 和 executor-cores 确定，不支持此总数限制。
–verbose	显示详细信息，将配置写入日志文件。	是	否	TCHouse-X 的 CLI 暂不支持此参数。作业日志请通过 –get-log 命令查看。
–conf <key>=<value> / –config	指定任意 Spark 配置属性 (key=value 格式)。	是	是	完全兼容，用于覆盖 spark-defaults.conf 中的默认值或设置其他 Spark 参数。
–files	指定供 Spark 应用使用的附加文件（逗号分隔）。	是	是	完全兼容。文件必须先上传到 COS 并使用 cosn:// 路径。
–packages	指定 Maven 坐标，用于自动处理依赖包及其传递性依赖。	是	否	TCHouse-X 提交时不支持 Maven 依赖解析。请将所有依赖 JAR 包手动上传至 COS，并使用 –jars 参数指定。