腾讯云数据仓库 TCHouse-X 使用 Spark-Submi

腾讯云数据仓库 TCHouse-X 提供了定制化的 Spark-Submit 命令行工具。该工具是向 TCHouse-X 离线计算引擎 提交 Spark 应用的官方接口。它在开源 Spark-Submit 的基础上进行了扩展和优化，旨在实现与 TCHouse-X 环境的深度集成和高效运行。
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. 参数优先级：
命令行中多次指定同一参数，取最后一次指定的值。
同时使用 -cores/-executors 和 --conf spark.***.resourceSpec/instances 时，以 --conf 指定的值为准。
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******************6
ErrorMsg
SparkJobId    batch-job-123456
SparkTaskId   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
请求示例
# 获取 batch-task-123456 任务中第一个 Executor 的日志，并按时间升序排列：
./bin/spark-submit --get-log \\
    --taskId batch-task-123456
    --pod exec-0
    --orderBy asc
返回参数说明
参数名称
描述
示例值
RequestId
腾讯云 API 请求的唯一标识 ID。
6********************************b
ErrorMsg
错误信息。
若查询成功，则该字段为空。
SparkLogList
Spark 任务的运行日志内容。
(返回实际的日志文本内容)
查看作业列表
进入 <tchouse-x-spark-submit> 目录，执行 --list 命令，查询目标 TCHouse-X 实例下用户提交的 Spark 作业（Job）列表。
./bin/spark-submit --list \\
    [--confPath <confPath>] \\
    [--instanceId <instanceId>] \\
    [--pageSize <pageSize>] \\
    [--pageNumber <pageNumber>]
请求参数说明
参数名称
是否必填
描述
默认值/说明
--list
是
指定执行查看作业列表的命令。
无参数值。
--instanceId <instanceId>
条件必填
期望查看的 Spark 作业列表所属的 TCHouse-X 实例 ID。
若已在配置文件中设置，可省略。主账号内实例 ID 唯一。
--pageSize <pageSize>
否
返回的 Spark 作业列表中每页显示的记录数。
默认值：10。可选值：大于 0 的整数。
--pageNumber <pageNumber>
否
期望查看的页数。
默认值：1。
--confPath <confPath>
否
指定自定义配置文件路径。
默认值：./conf/spark-defaults.conf。
返回参数说明
执行 --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
取消运行任务
进入 <tchouse-x-spark-submit> 目录，执行 --kill 命令可以中断并取消正在运行中的 Spark 作业任务。
./bin/spark-submit --kill \\
    --taskId <taskId> \\
    [--instanceId <instanceId>] 
请求参数说明
参数名称
是否必填
描述
默认值/说明
示例
--kill
是
指定执行取消运行任务的命令。
无参数值。
--kill
--taskId <taskId>
是
期望取消运行的 Spark 任务 ID。
可通过 --list 命令或提交成功后的返回结果获取。
--taskId batch-task-******g
--instanceId
条件必填
TCHouse-X 实例 ID。
若已在配置文件中设置，可省略。
--instanceId warehouse-p******m
请求示例
./spark-submit --kill \\
    --taskId batch-task-b***g
返回参数说明
参数名称
描述
示例
RequestId
取消运行命令的 API 请求 ID。
RequestId 6***************************b
ErrorMsg
错误信息或操作结果。
取消成功： ErrorMsg 字段将为空，表示任务已成功取消（任务状态变为 canceled）。
取消失败： 仅当 Spark 任务处于 initializing 或 running 状态时才能被取消。如果任务已结束（例如 success 或 failed），操作将失败，并在 ErrorMsg 中提示失败原因。
上传文件
要将您的本地文件上传至 腾讯云对象存储（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>
请求参数说明
参数名称
是否必填
描述
参数值说明
示例
--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
请求示例
./bin/spark-submit --upload \\
    --bucket my-bucket-12345678 \\
    --key folder1/subFolder1/myCosSparkJar.jar \\
    --localFilePath localSubFoler1/myLocalSparkJar.jar
返回示例
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
TCHouse-X 与社区版 Spark-Submit CLI 工具对比
配置参数对比
参数名称
参数说明 (社区版定义)
社区版是否支持
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 指定。
提交参数对比
参数名称
参数说明 (社区版定义)
社区版支持
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 参数指定。

参数名称	描述	参数值说明	示例
`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`

参数名称	描述	参数值说明	示例
`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`

参数名称	参数说明	参数值说明	示例
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

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

参数名称	描述	支持文件类型	格式与说明
--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"

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

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

参数名称	参数说明 (社区版定义)	社区版是否支持	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` 指定。

参数名称	参数说明 (社区版定义)	社区版支持	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` 参数指定。

使用 Spark-Submit 命令行工具连接实例

本页目录：

TCHouse-X Spark-Submit 用法指南

Step1：下载 CLI 工具

Step2：配置连接参数

默认配置文件内容预览

必填参数配置说明

选填参数配置说明

Step3：提交 Spark 作业

提交命令语法

请求参数说明

必填参数

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

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

环境参数

提交样例

返回参数说明

返回示例

其他操作说明

查看参数说明

查看任务运行状态

请求参数说明

返回参数说明

查看任务运行日志详情

请求参数说明

请求示例

返回参数说明

查看作业列表

请求参数说明

返回参数说明

取消运行任务

请求参数说明

请求示例

返回参数说明

上传文件

请求参数说明

请求示例

返回示例

TCHouse-X 与社区版 Spark-Submit CLI 工具对比

配置参数对比

提交参数对比