TsFile-Spark-Connector用户指南

1. TsFile-Spark-Connector简介

TsFile-Spark-Connector 实现了 Spark 对 Tsfile 类型的外部数据源的支持。这使用户能够通过Spark读取，写入和查询Tsfile。

使用此连接器，您可以

• 将单个 TsFile 从本地文件系统或 hdfs 加载到 Spark 中
• 将特定目录中的所有文件从本地文件系统或HDFS加载到Spark中
• 将数据从 Spark 写入 TsFile

2. 系统要求

注意：有关如何下载和使用 TsFile 的更多信息，请参阅以下链接：https://github.com/apache/incubator-iotdb/tree/master/tsfile.

3. 快速入门

本地模式

在本地模式下使用 TsFile-Spark-Connector 启动 Spark：

1. ./<spark-shell-path> --jars tsfile-spark-connector.jar,tsfile-0.10.0-jar-with-dependencies.jar

注意：

• is the real path of your spark-shell.
• Multiple jar packages are separated by commas without any spaces.

分布式模式

在分布式模式下使用 TsFile-Spark-Connector 启动 Spark（即 Spark 集群通过 spark-shell 连接）：

1. . /<spark-shell-path> --jars tsfile-spark-connector.jar,tsfile-{version}-jar-with-dependencies.jar --master spark://ip:7077

4. Data Type Correspondence

5. 模式推理

显示 TsFile 的方式取决于架构。以以下 TsFile 结构为例： TsFile 架构中有三个度量：状态、温度和硬件。这三项测量的基本信息如下：

TsFile 中的现有数据如下：

您也可以使用窄表形式，如下所示：（您可以看到第 6 部分有关如何使用窄格式）

6. Scala API

注意：请记住提前分配必要的读取和写入权限。

示例 1：从本地文件系统读取

1. import org.apache.iotdb.tsfile._
2. val wide_df = spark.read.tsfile("test.tsfile")
3. wide_df.show
5. val narrow_df = spark.read.tsfile("test.tsfile", true)
6. narrow_df.show

示例 2：从 Hadoop文件系统读取

1. import org.apache.iotdb.tsfile._
2. val wide_df = spark.read.tsfile("hdfs://localhost:9000/test.tsfile")
3. wide_df.show
5. val narrow_df = spark.read.tsfile("hdfs://localhost:9000/test.tsfile", true)
6. narrow_df.show

示例 3：从特定目录读取

1. import org.apache.iotdb.tsfile._
2. val df = spark.read.tsfile("hdfs://localhost:9000/usr/hadoop")
3. df.show

注 1：目前不支持目录中所有 TsFiles 的全局时间排序。

注 2：同名测量应具有相同的架构。

示例 4：宽格式查询

1. import org.apache.iotdb.tsfile._
2. val df = spark.read.tsfile("hdfs://localhost:9000/test.tsfile")
3. df.createOrReplaceTempView("tsfile_table")
4. val newDf = spark.sql("select * from tsfile_table where `device_1.sensor_1`>0 and `device_1.sensor_2` < 22")
5. newDf.show

1. import org.apache.iotdb.tsfile._
2. val df = spark.read.tsfile("hdfs://localhost:9000/test.tsfile")
3. df.createOrReplaceTempView("tsfile_table")
4. val newDf = spark.sql("select count(*) from tsfile_table")
5. newDf.show

示例 5：窄格式查询

1. import org.apache.iotdb.tsfile._
2. val df = spark.read.tsfile("hdfs://localhost:9000/test.tsfile", true)
3. df.createOrReplaceTempView("tsfile_table")
4. val newDf = spark.sql("select * from tsfile_table where device_name = 'root.ln.wf02.wt02' and temperature > 5")
5. newDf.show

1. import org.apache.iotdb.tsfile._
2. val df = spark.read.tsfile("hdfs://localhost:9000/test.tsfile", true)
3. df.createOrReplaceTempView("tsfile_table")
4. val newDf = spark.sql("select count(*) from tsfile_table")
5. newDf.show

示例 6：以宽格式写入

1. // we only support wide_form table to write
2. import org.apache.iotdb.tsfile._
4. val df = spark.read.tsfile("hdfs://localhost:9000/test.tsfile")
5. df.show
6. df.write.tsfile("hdfs://localhost:9000/output")
8. val newDf = spark.read.tsfile("hdfs://localhost:9000/output")
9. newDf.show

示例 6：以窄格式书写

1. // we only support wide_form table to write
2. import org.apache.iotdb.tsfile._
4. val df = spark.read.tsfile("hdfs://localhost:9000/test.tsfile", true)
5. df.show
6. df.write.tsfile("hdfs://localhost:9000/output", true)
8. val newDf = spark.read.tsfile("hdfs://localhost:9000/output", true)
9. newDf.show

附录 A：架构推理的旧设计

显示 TsFile 的方式与 TsFile 架构有关。以以下 TsFile 结构为例：TsFile 的架构中有三个度量：状态、温度和硬件。这三个测量的基本信息如下：

测量基本信息

文件中的现有数据如下所示：

一组时间序列数据

有两种方法可以显示它：

默认方式

将创建两列来存储设备的完整路径：time（LongType）和delta_object（StringType）。

• time：时间戳，长类型
• delta_object： Delta_object ID， 字符串类型

接下来，为每个度量创建一个列来存储特定数据。SparkSQL 表结构如下：

展开delta_object列

将设备列按“.”展开为多个列，忽略根目录“root”。方便进行更丰富的聚合操作。如果用户想使用这种显示方式，需要在表创建语句中设置参数“delta_object_name”（参考本手册第5.5节中的示例1），如本例中参数“delta_object_name”设置为“root.device.turbine”。路径层数需要一对一。此时，将为设备路径的每个层（“根”层除外）创建一列。列名是参数中的名称，值是设备相应层的名称。接下来，将为每个测量创建一个列来存储特定数据。

那么 SparkSQL 表结构如下：

TsFile-Spark-Connector 可以在 SparkSQL By SparkSQL 中将一个或多个 TsFiles 显示为表。它还允许用户指定单个目录或使用通配符来匹配多个目录。如果有多个 TsFiles，则所有 TsFiles 中测量值的并集将保留在表中，并且默认情况下，具有相同名称的度量将具有相同的数据类型。请注意，如果存在名称相同但数据类型不同的情况，TsFile-Spark-Connector 将不保证结果的正确性。

写入过程是将数据帧写入为一个或多个 TsFiles。默认情况下，需要包含两列：时间和delta_object。其余列用作度量。