投影

概述

在 AIR 中，投影是一种核心的查询加速数据表，旨在提升明细查询和聚合查询的性能。系统在执行查询时，会自动识别并匹配可用的投影数据，直接读取预处理结果，从而跳过部分计算过程，显著降低查询耗时。

功能入口

点击导航栏中“数据整合”下的“投影”，即可进入投影管理页面。投影_image_1.png

功能介绍

新建投影

支持基于基础视图和逻辑视图创建投影，下文以逻辑视图为例创建投影。点击“视图”，选择单个视图后，选择“投影”tab，再点击“新建投影”

投影_image_8

新建投影包含基础配置和高级配置，具体说明见下文

投影_image_9

基础配置

基础配置包含基础信息和投影配置两部分。

投影_image_10

1）基础信息说明如下

投影类型
明细投影：用于加速明细查询（SELECT 明细字段）
聚合投影：用于加速统计分析（GROUP BY + 聚合函数，如 SUM/COUNT/MAX/MIN）
实时投影：用于加速对实时/高频更新数据的查询（数据到达后快速可查），适用于对时效性要求高的场景（如分钟级看板、实时监控、实时明细检索等）
投影名称
支持中英文数字下划线，长度为3~256个字符
建议命名规则：业务_表名_投影类型_用途（例如：sales_order_detail_detail_list / sales_order_agg_by_day_store）
创建后立即启用
勾选后，新建投影默认处于启用状态，可立即参与查询加速
未勾选则为未启用状态，需要后续手动启用后才生效
调度方式
自动更新：根据上游数据变化自动触发投影更新
手动更新：手动点击按钮触发投影更新（适用于低频更新或临时验证场景）
自定义：按照自定义的时间和数据变化触发更新（适用于需要特定刷新时间/频率的场景）
调度周期：与基础视图的调度周期相同
依赖强弱
强依赖：基于该投影和上游投影的数据周期判断是否进行更新。当上游所有任务都完成目标周期（或更细粒度）的数据更新后，该任务才会执行
弱依赖：不校验数据周期的一致性（只要触发条件满足即可执行）

2）“投影配置-明细投影”说明如下

投影_image_11

扫描
勾选字段为扫描字段，用于查询（SELECT）场景的查询加速
建议勾选明细列表/导出/详情页中高频查询或展示的字段
分区
勾选字段为分区字段，当使用该字段进行排序或筛选时，会进行查询加速
建议选择低基数字段作为分区字段，建议选择字段值数量不超过 10,000的字段

3）“投影配置-聚合投影”说明如下

投影_image_12

维度
勾选字段为维度字段，用于分组（GROUP BY）场景的查询加速
建议勾选常用的分组字段（如日期、地区、门店、渠道、品类等）
度量
勾选字段为度量字段并选择聚合函数，用于聚合（SUM、COUNT…）场景的查询加速
常见选择：金额/数量→SUM；记录数→COUNT；极值→MAX/MIN
分区
请参考“明细投影”的说明

高级配置

支持设置增量配置和下推写入配置

投影_image_13

1）增量配置说明如下：

本节介绍界面中的配置项。如需了解首次全量构建、后续水位推进、多表增量分支以及 INSERT / MERGE / DELETE_INSERT 的选择，请参见投影增量构建。

功能说明
开启后，系统将根据配置的增量字段，对投影数据执行对应的 INSERT / MERGE / DELETE_INSERT 写入。
开启前提
视图上游的来源表（基础视图）中已配置增量字段
投影扫描字段中勾选增量字段
增量字段不包含复杂加工/转换逻辑
支持范围
分区视图：仅支持 INSERT
逻辑视图 / 方言视图 / 通过 CREATE 语句创建的表：支持 INSERT、MERGE、DELETE_INSERT

示例-INSERT（增量数据追加写入）

投影_image_14

配置项
增量类型：INSERT
增量字段：选择用于标识增量的字段（示例：C_CUSTKEY）
行为说明
系统仅写入本次增量范围内的新增数据，不对历史数据做更新或删除。

示例-MERGE（合并写入）

投影_image_15

配置项
增量类型：MERGE
增量字段：选择用于标识增量的字段（示例：C_CUSTKEY）
MERGE 条件：填写合并规则（WHEN MATCHED / WHEN NOT MATCHED 等）
错误数据处理：
- 继续插入：MERGE ON 条件匹配不上时将插入数据
- 忽略：MERGE ON 条件匹配不上时跳过此条数据
填写说明（可参考示例）
- ON 条件为主键/唯一键关联条件（示例：ON t.id = s.id）。
WHEN MATCHED 中的多个条件会按顺序匹配并执行
可按业务需要在 WHEN MATCHED 中编写 UPDATE / DELETE 行为，在 WHEN NOT MATCHED 中编写 INSERT 行为。

示例-DELETE_INSERT（按受影响范围替换）

配置项
增量类型：DELETE_INSERT
增量字段：选择用于识别本轮变化的字段
删除匹配模式：
- 替换键：从投影最终输出字段中选择一个或多个业务范围键，例如订单明细投影中的 order_id
- 受影响键 SQL：使用一条只读查询返回本轮变化会影响的投影业务键
行为说明
系统先删除受影响键对应的全部历史投影行，再从完整视图插入该范围当前仍存在的全部结果。
适用于逻辑删除、过滤条件由真变假、Join 关系失效或一对多结果收缩等 MERGE 无法撤回旧结果的场景。
当前适用于使用 Spark 构建并写入 Iceberg 的非分区投影。

具体配置规则、SQL 要求和注意事项请参见投影增量构建。三种模式的业务选型示例请参见投影增量构建最佳实践。

下推写入

作用与适用场景

下推写入用于加快逻辑视图的投影构建。对于能够完整交给同一源数据库执行的过滤、关联、聚合等计算，AIR 先让源数据库生成结果表，再分批并行读取结果并写入投影存储。源数据库可利用自身的计算能力；当结果集明显小于原始数据时，还可减少传输的数据量。

普通查询下推用于执行查询；投影的下推写入在此基础上增加源端结果落表及后续读取步骤。最终投影仍写入 AIR 配置的投影存储，源端临时表用于本次构建过程。

执行原理

检查可下推性。 AIR 检查 catalog 的下推和写入配置，并判断投影计算是否能完整交给该数据源执行。仅部分算子可下推时，不满足开启条件。
在源端计算并落表。 使用写账号，在数据源“写入路径”指定的位置执行类似 CREATE TABLE ... AS SELECT ... 的操作，将计算结果写入 AIR 管理的临时结果表。
读取结果并构建投影。 构建引擎按自动推荐或手动配置的分批策略读取临时表，将结果写入投影存储。分批针对结果读取，不会为每一批重复执行整段视图计算。
清理临时表。 构建结束后，AIR 清理源端临时表；清理失败会由后台任务重试，因此写账号还需具备删除临时表的权限。

flowchart LR
    A[逻辑视图的投影计算] --> B[源数据库执行计算]
    B --> C[指定库或 Schema 中的临时结果表]
    C --> D[分批并行读取]
    D --> E[AIR 投影存储]
    E --> F[清理源端临时表]

例如，对订单和订单明细进行关联、过滤并按客户聚合时，源数据库先计算聚合结果并落表，AIR 再并行读取该结果构建投影。实际收益取决于源端计算能力、结果规模和读取并发；临时落表也会增加源端计算、存储和 I/O 开销，并非所有任务开启后都会更快。

开启前提

对逻辑视图的投影进行配置，所有参与计算的数据来自同一 catalog，不支持跨源构建。
数据源支持相应下推能力，且完整投影计算逻辑能够下推。
DWS 已为该数据源提供写账号配置入口，并已在“数据连接”中启用下推、配置写账号和写入路径。未提供写账号入口的数据源尚未经过充分测试，暂不建议使用下推写入。
写账号可查询依赖表并创建、写入和删除临时表；连接账号可读取生成的临时表。

先按数据源配置步骤完成 catalog 设置，再在投影“高级配置”中开启“下推写入”。源端配置与投影开关需要同时满足。

拉取配置

配置项	说明
拉取方式	可选择“自动推荐”或“手动配置”；自动推荐由系统确定读取策略
分批字段	手动配置时必填，从已选投影字段中选择；尽量选择取值分布较均匀、适合范围划分的字段
分批数量	手动配置时必填，范围为 1～20；需结合源端连接和并发承载能力设置

下图为手动配置的分批字段与数量：

下推写入的手动分批配置

分批数量控制读取并行度，不是投影的存储分区数，也不表示只读取部分数据。字段类型和取值分布会影响分批效果，批次数越多不一定越快。

验证与问题处理

保存后执行一次构建，检查构建耗时、结果行数、数据内容及源端临时表清理情况。

现象	检查方向
无法开启下推写入	catalog 是否开启下推和写入；是否跨源；完整计算是否支持下推
源端建表或计算失败	写账号是否有效，是否能查询依赖表，目标库或 Schema 是否存在且有建表权限
建表成功但读取失败	连接账号是否有临时表的读取权限，源端连接数和并发是否达到限制
构建未明显加速	源端计算与落表开销、结果规模、分批字段分布、读取并发及网络吞吐
临时表未清理	写账号的删除权限、源端连接状态及后台清理任务结果