迁移指南：结构化流

请注意，本迁移指南描述了结构化流特有的内容。迁移结构化流到更高版本时，许多 SQL 迁移内容也适用。请参考迁移指南：SQL、Dataset 和 DataFrame。

从结构化流 3.3 升级到 3.4

从 Spark 3.4 开始，Trigger.Once 已被弃用，建议用户从 Trigger.Once 迁移到 Trigger.AvailableNow。有关更多详细信息，请参考 SPARK-39805。
从 Spark 3.4 开始，Kafka 偏移量获取配置的默认值 (spark.sql.streaming.kafka.useDeprecatedOffsetFetching) 已从 true 更改为 false。默认情况下不再依赖于基于消费者组的调度，这会影响所需的 ACL。有关更多详细信息，请参见结构化流 Kafka 集成。

从 Spark 3.3 开始，所有有状态操作都需要使用精确分组键进行哈希分区。在之前的版本中，除了流-流连接之外的所有有状态操作都需要宽松的分区标准，这会导致正确性问题。（有关更多详细信息，请参见 SPARK-38204。）为了确保向后兼容性，我们保留了使用旧版本构建的检查点的旧行为。

在 Spark 3.0 及之前版本中，对于具有有状态操作的查询，这些操作可能会发出比当前水位线加上允许的延迟记录延迟更早的行，这些行在下游有状态操作中被称为“延迟行”，这些行可能会被丢弃，Spark 仅会打印警告消息。从 Spark 3.1 开始，Spark 会默认检查此类可能存在正确性问题的查询，并为其抛出 AnalysisException。对于了解正确性问题可能存在的风险，并仍决定运行查询的用户，请通过将配置 spark.sql.streaming.statefulOperator.checkCorrectness.enabled 设置为 false 来禁用此检查。
在 Spark 3.0 及之前版本中，Spark 使用 KafkaConsumer 进行偏移量获取，这可能会导致驱动程序无限等待。在 Spark 3.1 中，添加了一个新的配置选项 spark.sql.streaming.kafka.useDeprecatedOffsetFetching（默认值：true），可以将其设置为 false，允许 Spark 使用使用 AdminClient 的新偏移量获取机制。有关更多详细信息，请参见结构化流 Kafka 集成。

在 Spark 3.0 中，结构化流在通过 spark.readStream(...) 使用基于文件的 Data Source（如文本、JSON、CSV、Parquet 和 ORC）时，会强制将源模式转换为可空。之前，它会尊重源模式中的可空性；但是，这会导致难以调试的 NPE 问题。要恢复之前的行为，请将 spark.sql.streaming.fileSource.schema.forceNullable 设置为 false。
Spark 3.0 修复了流-流外连接的正确性问题，这会更改状态的模式。（有关更多详细信息，请参见 SPARK-26154）。如果您从使用流-流外连接的 Spark 2.x 构建的检查点启动查询，Spark 3.0 会失败。要重新计算输出，请丢弃检查点并重新播放之前的输入。
在 Spark 3.0 中，已删除弃用的类 org.apache.spark.sql.streaming.ProcessingTime。请改用 org.apache.spark.sql.streaming.Trigger.ProcessingTime。同样，org.apache.spark.sql.execution.streaming.continuous.ContinuousTrigger 已被删除，取而代之的是 Trigger.Continuous，而 org.apache.spark.sql.execution.streaming.OneTimeTrigger 已被隐藏，取而代之的是 Trigger.Once。