CarbonData 配置

本教程介绍 CarbonData 的高级配置：

• 系统配置
• 性能配置
• 其他配置
• Spark 配置
• 使用 SET-RESET 动态配置 CarbonData

系统配置

本节提供了 CarbonData 系统所需所有配置的详细信息。

carbon.properties 中的系统配置

属性	默认值	描述
carbon.storelocation		CarbonData 创建存储并以自己的格式写入数据的位置。如果没有配置这个属性将使用 spark.sql.warehouse.dir 配置的路径。注意：存储路径需要设置成 HDFS 的路径。
carbon.ddl.base.hdfs.url		该属性用于配置 HDFS 的相对路径。在 carbon.ddl.base.hdfs.url 配置的路径将被附加到 fs.defaultFS 配置的 HDFS 路径中。如果用户配置了这个路径，在数据加载的时候就不需要提供完整的路径。比如： csv 文件的绝对路径为 hdfs://10.18.101.155:54310/data/cnbc/2016/xyz.csv，我们可以从 fs.defaultFS 属性获取到 "hdfs://10.18.101.155:54310"，用户可以将 carbon.ddl.base.hdfs.url 属性配置成 /data/cnbc/，加载数据的时候，用户只需要提供 /2016/xyz.csv 路径即可。
carbon.badRecords.location		存储坏记录的路径。
carbon.data.file.version	V3	如果这个属性的值设置成 1，则 CarbonData 将支持旧格式的数据加载（0.x版本）；如果这个属性的值设置成 2（1.x 以上版本），那么 CarbonData 将仅支持新格式的数据加载
carbon.streaming.auto.handoff.enabled	true	如果此参数值设置为 true，则会启用自动触发切换功能。
carbon.streaming.segment.max.size	1024000000	此参数定义 streaming segment 的最大大小。将此参数设置为适当的值可以避免对流数据摄取的影响。这个参数的单位是字节。
carbon.query.show.datamaps	true	如果此参数值设置为 true，show tables 命令将会列出包括 datatmaps(比如: 预聚合表) 的所有表；否则只会列出除 datamaps 之外的所有表。
carbon.segment.lock.files.preserve.hours	48	此属性值表示在数据加载之后 segment 锁文件将保留的小时数。这些锁文件将在配置的时间后用 clean 命令删除。

性能配置

本节提供了 CarbonData 性能优化所需的所有配置的详细信息。

carbon.properties 中的性能配置参数

• 数据加载配置

属性	默认值	描述	范围
carbon.number.of.cores.while.loading	2	数据加载时所用到核的个数。
carbon.sort.size	100000	排序并将中间文件写入临时文件的记录条数。
carbon.max.driver.lru.cache.size	-1	数据在 driver 端加载的最大 LRU 缓存大小。这个值的单位是 MB。默认值为 -1，意味着没有缓存内存限制。这个属性只能配置大于 0 的值。
carbon.max.executor.lru.cache.size	-1	数据在 executor 端加载的最大 LRU 缓存大小。这个值的单位是 MB。默认值为 -1，意味着没有缓存内存限制。这个属性只能配置大于 0 的值。如果没有配置这个属性，则会使用 carbon.max.driver.lru.cache.size 属性配置的值。
carbon.merge.sort.prefetch	true	数据加载期间，从排序临时文件中读取数据，允许在合并排序期间启用预取数据功能。
carbon.update.persist.enable	true	持久化数据时启用此参数，启用它将减少 UPDATE 操作的执行时间。
carbon.load.global.sort.partitions	0	当对排序的数据进行 shuffling 时使用的分区数。如果用户没有配置或者将该属性配置成小于 1 的值，将使用 map 任务的数量作为 reduce 任务的数量。一般来说，建议集群中每个 CPU 核处理 2-3 个任务。
carbon.options.bad.records.logger.enable	false	是否创建坏记录详细信息的日志。
carbon.bad.records.action	FORCE	对坏记录主要有四种类型的操作：FORCE，REDIRECT，IGNORE 和 FAIL。如果设置为 FORCE，则通过将不良记录存储为 NULL 来自动更正数据。如果设置为 REDIRECT，则坏记录将被写入到 csv 文件中而不被加载。如果设置为 IGNORE，则坏记录既不会被写入到 csv 文件中，也不会被加载。如果设置为 FAIL，数据加载过程中遇到坏记录，则整个数据加载失败。
carbon.options.is.empty.data.bad.record	false	如果为 false，则空（"" 或 '' 或 ,,）的数据不会被视为坏记录，反之亦然。
carbon.options.bad.record.path		存储坏记录的 HDFS 路径。默认情况下这个属性的值为 Null。如果启用了坏记录详细信息日志功能或坏记录操作被重定向，则用户必须配置这个属性。
carbon.enable.vector.reader	true	该参数提高了 select 查询的性能，因为它可以一次读取 4*1024 行的数据，而不是逐行读取数据。
carbon.blockletgroup.size.in.mb	64 MB	数据读取以 blocklets 为单位，这些 blocklets 称为 blocklet groups。这个参数指定 blocklet groups 的大小。较高的值会导致更好的顺序 IO 访问。最小值为 16MB，小于 16MB 的任何值都将被重置为默认值（64MB）。
carbon.task.distribution	block	block: 设置此值将为每个块启动一个任务处理。在并发查询且查询具有 shuffling 过程的场景下建议使用此设置。 custom: 设置此值将对块进行分组并将块均匀地分配到集群中可用的资源。这个设置提升了查询性能，但在并发查询且查询具有很多 shuffling 过程的场景下不建议使用此设置。 blocklet: 设置此值将为每个 blocklet 启动一个任务处理。在并发查询且查询具有很多 shuffling 过程的场景下建议使用此设置。 merge_small_files: 设置此值将在查询过程中将所有小分区合并成大小为 128 MB（128MB 是 "spark.sql.files.maxPartitionBytes" 参数的默认值，这个参数是可配置的）。小分区被组合到一个 map 任务中，以减少读取任务的数量。 这个可以提升性能。

• 压缩配置

属性	默认值	描述	范围
carbon.number.of.cores.while.compacting	2	在压缩过程中写数据使用到的核数。
carbon.compaction.level.threshold	4, 3	该属性在 minor compaction 时使用，决定要合并多少个 segments。比如：如果将这个属性设置为 2, 3，那么每 2 个 segments 会触发一次 Level 1 的 minor compaction。每 3 个 Level 1 的 compacted segment 将会进一步压缩成新的 segment。	有效值的范围为 0-100。
carbon.major.compaction.size	1024	Major compaction 大小可以使用这个参数进行配置。segments 大小总和低于此阈值的将会被合并。此值的单位为 MB。
carbon.horizontal.compaction.enable	true	此属性用于打开/关闭 horizontal compaction。每次 DELETE 或 UPDATE statement 之后， 如果增量（DELETE/UPDATE）文件的个数超过指定的阈值，可能会发生 horizontal compaction。
carbon.horizontal.UPDATE.compaction.threshold	1	此属性用于限制 segment 中 UPDATE 增量文件的数量。如果增量文件的数量超出此阈值，则该 segment 内的 UPDATE 增量文件将会进行 horizontal compaction，并且会被压缩成单个 UPDATE 增量文件。	有效值的范围为 0-10000。
carbon.horizontal.DELETE.compaction.threshold	1	此属性用于限制 segment 中一个块的 DELETE 增量文件的数量。如果增量文件的数量超出此阈值，则 segment 内某个块的 DELETE 增量文件将会进行 horizontal compaction，并且会被压缩成单个 DELETE 增量文件。	有效值的范围为 0-10000。
carbon.update.segment.parallelism	1	此属性指定更新期间每个 segment 的并行数。如果存在包含太多需要更新的记录的 segments，并且 spark 作业遇到数据溢出相关问题，则最好增加此属性值。	有效值的范围为 0-1000。

• 查询配置

属性	默认值	描述	范围
carbon.number.of.cores	4	查询时使用核的数量。
carbon.enable.quick.filter	false	提高过滤查询的性能.

其他配置

carbon.properties 的其他配置

• CarbonData 的时间格式

属性	默认格式	描述
carbon.timestamp.format	yyyy-MM-dd HH:mm:ss	输入数据中时间戳数据类型的时间格式。

• 数据加载配置

属性	默认值	描述
carbon.sort.file.write.buffer.size	16384	排序过程中写文件缓冲区的大小。最小允许的缓存区大小为 10240 字节，最大允许的缓存区大小为 10485760 字节。
carbon.lock.type	LOCALLOCK	此配置指定在表上执行并发操作期间需要获取的锁类型。有以下类型的锁实现： LOCALLOCK: 锁以文件的形式在本地文件系统上创建。如果一台机器上仅仅有一个 spark driver (thrift server) 运行并且没有其他 CarbonData spark 应用程序同时启动的情况下很有用。 HDFSLOCK: 锁以文件的形式在 HDFS 文件系统上创建。当启动多个 CarbonData spark 应用程序并且集群中没有运行 ZooKeeper，而且 HDFS 支持基于文件的锁的情况下很有用。
carbon.sort.intermediate.files.limit	20	启动合并排序的最小中间文件的数量。(minValue = 2, maxValue=50).
carbon.block.meta.size.reserved.percentage	10	在 CarbonData 文件中为写入块元数据需要保留的空间，单位为百分比。
carbon.csv.read.buffersize.byte	1048576	csv 读取缓冲区的大小。
carbon.merge.sort.reader.thread	3	读取中间文件进行最终合并的最大线程数。
carbon.concurrent.lock.retries	100	并发操作获取锁的最大重试次数。主要用于并发加载。
carbon.concurrent.lock.retry.timeout.sec	1	并发操作获取锁的重试时间间隔。
carbon.lock.retries	3	除加载之外的任何操作获取锁的最大重试次数。
carbon.lock.retry.timeout.sec	5	除加载之外的任何操作获取锁的重试时间间隔。
carbon.skip.empty.line	false	在数据加载过程中，是否忽略 CSV 文件中的空行。
carbon.enable.calculate.size	true	用于加载操作: 设置此属性会在每次加载的时候计算 carbon 数据文件（.carbondata）和 carbon 索引文件（.carbonindex）的大小，并更新表的状态文件。 用于格式化描述: 设置此属性会为特定表计算 carbon 数据文件和 carbon 索引文件的总大小，并且以格式化的形式显示。

• 压缩配置

属性	默认值	描述
carbon.numberof.preserve.segments	0	如果用户想防止一些 segments 被压缩，可以通过设置这个参数。比如 carbon.numberof.preserve.segments = 2，那么 2 个最新的 segments 总是被排除在压缩之外。默认没有 segments 被保留。
carbon.allowed.compaction.days	0	在指定的天数内加载的 segment 将被合并。如果配置为 2，仅在 2 天内加载的 segment 被合并，2 天之前的 segment 不会被合并。默认没有被启用。
carbon.enable.auto.load.merge	false	数据加载的时候启用压缩。
carbon.enable.page.level.reader.in.compaction	true	为压缩启用页面级读取器可减少内存的使用量，同时压缩更多数量的 segments 。它只允许逐页读取，而不是将整个 blocklet 加载到内存中。

• 查询配置

属性	默认值	描述
max.query.execution.time	60	查询执行的最大时间。该值的单位是分钟。
carbon.enableMinMax	true	Min max 功能的添加可以增强查询性能。如果想禁用此功能，可以将这个参数设置为 false。
carbon.dynamicallocation.schedulertimeout	5	scheduler 认为 executor 除于活动状态的最长时间（单位是秒）。最小值为 5 秒，最大值为 15 秒。
carbon.scheduler.minregisteredresourcesratio	0.8	启动块分配所需的最小资源比率。默认值是 0.8，意味着 80% 的请求资源被用于执行块分配。最小值为 0.1，最大值为 1。
carbon.search.enabled	false	如果设置为 true，将使用 CarbonReader 直接执行分布式扫描，而不是像 spark 那样使用计算框架，从而可以避免计算框架带来的限制，比如 SQL 优化和任务调度开销。

• 全局字典配置

属性	默认值	描述
carbon.cutOffTimestamp		设置计算时间戳的开始日期。Java 从 "1970-01-01 00:00:00" 开始计算时间戳。该属性用于自定义开始位置。比如 "2000-01-01 00:00:00"。时间的格式必须符合 carbon.timestamp.format 参数配置的。
carbon.timegranularity	SECOND	该属性用于设置数据粒度级别，有效值为 DAY，HOUR，MINUTE 或 SECOND。

Spark 配置

Spark 配置请参考 spark-defaults.conf

属性	默认值	描述
spark.driver.memory	1g	driver 进程需要用到的内存
spark.executor.memory	1g	executor 进程需要用到的内存

使用 SET-RESET 动态配置 CarbonData

SET/RESET 命令主要用于动态地添加、更新、显示或者重置 carbondata 属性，这些操作不需要重启 driver。

语法

• 添加或更新 : 这个命令用于更新 parameter_name 属性的值.

SET parameter_name=parameter_value

• 显示属性的值: 这个命令用于显示 parameter_name 属性的值.

SET parameter_name

• 显示会话参数: 这个命令显示所有支持的会话参数.

SET

• 显示会话参数以及使用细节: 这个命令显示所有支持的会话参数及其使用详细信息.

SET -v

• 重置: 这个命令清除所有会话参数。

RESET

参数说明:

属性	描述
parameter_name	需要动态添加、更新或显示值的属性名称。
parameter_value	parameter_name 属性需要设置的值。

CarbonData 动态可配置属性

属性	描述
carbon.options.bad.records.logger.enable	启用或关闭坏记录日志记录。
carbon.options.bad.records.action	对坏记录主要有四种类型的操作：FORCE，REDIRECT，IGNORE 和 FAIL。如果设置为 FORCE，则通过将不良记录存储为 NULL 来自动更正数据。如果设置为 REDIRECT，则坏记录将被写入到 csv 文件中而不被加载。如果设置为 IGNORE，则坏记录既不会被写入到 CSV 文件中，也不会被加载。如果设置为 FAIL，数据加载过程中遇到坏记录，则整个数据加载失败。
carbon.options.is.empty.data.bad.record	如果为 false，则空（"" 或 '' 或 ,,）的数据不会被视为坏记录，反之亦然。
carbon.options.batch.sort.size.inmb	保存在内存中批量数据的大小，根据经验法则，这个属性最好配置成小于 sort.inmemory.size.inmb 参数的 45%，否则会将中间数据溢出到磁盘。
carbon.options.single.pass	Single Pass 加载可以使用单个作业即时完成数据加载以及字典生成。它增强了在初始加载数据之后的涉及字典上很少增量更新的后续数据加载场景下的性能。该选项指定是否使用 single pass 来加载数据，默认情况下这个属性的值为 FALSE。
carbon.options.bad.record.path	存储坏记录的 HDFS 路径。
carbon.custom.block.distribution	指定是否使用 Spark 或 Carbon 块分布功能。
enable.unsafe.sort	指定在数据加载期间是否使用不安全排序(unsafe sort)。不安全排序会减少数据加载过程中的垃圾回收，从而提高性能。

示例:

• 添加或更新:

SET enable.unsafe.sort =true

• 显示属性的值:

SET enable.unsafe.sort

• 重置:

RESET

系统响应:

• 成功的信息将会记录到 driver 的日志中。

• 错误的信息将显示在 UI 上。