PROJECTION

PROJECTION 是 Relation Projection ( RP )的简写，也就是关系投影的概念。

CREATE PROJECTION

创建明细或聚合投影。可通过 WITH PROPERTIES 设置单投影调度、增量构建和其他创建配置；表级刷新配置使用独立的 SET PROJECTION PROPERTIES 语句。

• 语法说明

创建明细 RP

ALTER (VIEW |TABLE) <tablePath> 
CREATE RAW PROJECTION [IF NOT EXISTS] <projectionName> 
USING
(DISPLAY (field1, field2, ...) | ALL FIELDS)
[PARTITION BY (field1, field2, ...)]
[SORT BY (field1, field2, ...)]
[DISTRIBUTE BY (field1, field2, ...)]
[WITH PROPERTIES ('key': 'value', ...)]

• 使用案例

-- 创建【表】的投影
ALTER TABLE catalogName.schemName.tableName
CREATE RAW PROJECTION projectName
USING
DISPLAY ("cc_call_center_sk", "cc_call_center_id");

-- 创建【视图】的投影
ALTER VIEW catalogName.schemName.tableName
CREATE RAW PROJECTION mv1
USING
DISPLAY ("cc_call_center_sk", "cc_call_center_id");

创建聚合 RP

ALTER VIEW|TABLE <name> 
CREATE AGGREGATE PROJECTION [IF NOT EXISTS] <PROJECTION_NAME> 
USING 
DIMENSIONS (x by day, y) 
MEASURES (b (COUNT, MIN, MAX, SUM, APPROXIMATE COUNT DISTINCT)) [PARTITION BY (field1, field2, ...)]
[SORT BY (field1, field2, ...)]
[DISTRIBUTE BY (field1, field2, ...)]
[WITH PROPERTIES ('key': 'value', ...)]

• 使用案例

ALTER TABLE "hive1"."tpcds_1_text"."catalog_sales" CREATE AGGREGATE PROJECTION table_agg_rp
USING DIMENSIONS (cs_bill_customer_sk)
MEASURES (cs_wholesale_cost(MAX, MIN, COUNT, SUM))

WITH PROPERTIES：与创建 API 对齐

Presto、MySQL 两种 SQL 方言的明细和聚合投影创建语句均支持 WITH PROPERTIES。基础字段仍由 DISPLAY、DIMENSIONS、MEASURES、PARTITION BY、SORT BY 指定；其他创建配置通过属性传入。

属性名区分大小写，使用下表中的 Tardis 原生 API 字段名。复杂配置传入 JSON 对象字符串，结构与 API 一致；SQL 字符串中的单引号写为两个单引号，例如 O''Reilly。键和值之间支持 : 或 =。

ALTER VIEW catalog_name.schema_name.view_name
CREATE RAW PROJECTION IF NOT EXISTS rp_name
USING ALL FIELDS
WITH PROPERTIES (
  'state': 'ENABLED',
  'scheduleConfig': '{"type":"SCHEDULE","cronTab":"0 0 * * * ?","refreshOnEnable":false,"dependUpstreamStatus":true}',
  'openStrongDependency': true,
  'partitionDataPersistDays': 30,
  'properties': '{"autoDetectPartitions":"false"}'
);

创建配置会转换为与 Tardis API 相同的 RPGoal / RPDetails 模型，并进入同一创建服务执行权限及业务校验。表/视图、列、投影类型、增量算子和目标引擎等限制与 API 一致；支持传参不代表任意配置组合都可使用。

SQL 属性	类型	对应 Tardis API 字段 / 说明
id	字符串	id；不指定时由服务生成，仅创建时可指定
tag	字符串	tag
state	枚举字符串	state；通常使用 ENABLED、DISABLED，SQL 默认 ENABLED
attachType	枚举字符串	attachType；当前为 DATASET
bizCode	枚举字符串	bizCode；USER、POLICY、ON_LINE_POLICY，默认 USER
streaming	布尔值	streaming；默认 false
openStrongDependency	布尔值	openStrongDependency；周期强依赖，默认 true
openDataSeam	布尔值	openDataSeam；数据拼接，默认 false，受投影类型限制
partitionDataPersistDays	整数	partitionDataPersistDays；分区保留天数，默认 -1
tableBuildScript	字符串	tableBuildScript；保留 API 字段，执行效果取决于对应引擎实现
scheduleConfig	JSON 对象字符串	scheduleConfig；支持 type、cronTab、refreshOnEnable、dependUpstreamStatus
incrementalConfigV2	JSON 对象字符串	details.incrementalConfigV2；推荐使用，与 /v2/rp/create 对齐
incrementalRefreshConfig	JSON 对象字符串	details.incrementalRefreshConfig；旧版配置，与 /v1/rp/create 对齐
partitionsReadConfig	JSON 对象字符串	details.partitionsReadConfig；支持 enable、partitionColumn、numPartitions
properties	JSON 对象字符串	properties；传入扩展属性，可包含对象、数组、布尔值等 JSON 值

scheduleConfig.type 可取 MANUAL（手动）、AUTO（自动）或 SCHEDULE（定时）。未指定调度配置时沿用系统默认行为；只希望控制创建/启用时是否刷新，可以使用下文的 refreshOnEnable 简写。

名称、投影类型和数据集路径由 SQL 主体指定，不能在属性中覆盖。owner、clusterId 来自当前会话，创建和修改时间由服务端生成；这些字段不能通过属性指定。

平台接口 /api/v1/rp 的 incrementalConfig 对应 SQL 的 incrementalConfigV2，partitionConfig 对应 partitionsReadConfig，streamed 对应 streaming；流式启动相关属性通过 properties 传递，具体键值与 Tardis 原生 API 一致。

V2 增量配置示例

ALTER VIEW catalog_name.schema_name.join_view
CREATE RAW PROJECTION rp_incremental
USING ALL FIELDS
WITH PROPERTIES (
  'incrementalConfigV2': '{
    "incrementalSources": [
      {"metadataPath":["catalog_name","schema_name","table_a"],"column":"a_seq","tableSourceColumn":"seq"},
      {"metadataPath":["catalog_name","schema_name","table_b"],"column":"b_seq","tableSourceColumn":"seq"}
    ],
    "writeMode":"MERGE",
    "allowLeftJoin":false,
    "expression":"ON t.a_id = s.a_id AND t.b_id = s.b_id WHEN MATCHED THEN UPDATE SET *",
    "errorHandle":"CONTINUE_INSERT"
  }',
  'refreshOnEnable': false
);

• writeMode 支持 INSERT、MERGE、DELETE_INSERT。
• incrementalSources 中每个增量源使用 metadataPath、column、tableSourceColumn 描述来源及字段。
• MERGE 可使用 expression、errorHandle、allowLeftJoin；LEFT JOIN 的适用限制见投影增量构建。
• DELETE_INSERT 可使用 deleteMatchConfig，包含 mode（REPLACE_KEYS / AFFECTED_KEY_SQL）、replaceKeys、affectedKeySql，具体组合遵循 API 校验。

原有属性兼容

以下简写继续支持，无需修改已有 SQL：

简写属性	作用
merge、expression、errorHandle	旧版 incrementalRefreshConfig；merge=true 时必须提供非空 expression，errorHandle 默认 CONTINUE_INSERT，也可用 IGNORE
writable、partitionColumn、numPartitions	partitionsReadConfig（其中 writable 映射为 JSON 的 enable）；使用简写时，省略项分别为 false、空字符串、0
autoDetectPartitions	properties.autoDetectPartitions；可传布尔值，持久化为布尔字符串
refreshOnEnable	scheduleConfig.refreshOnEnable；创建/启用时是否触发刷新

ALTER TABLE catalog_name.schema_name.table_name
CREATE RAW PROJECTION rp_legacy
USING DISPLAY (id, amount)
WITH PROPERTIES (
  'merge': true,
  'expression': 'ON t.id = s.id WHEN MATCHED THEN UPDATE SET *',
  'errorHandle': 'IGNORE',
  'writable': true,
  'partitionColumn': 'id',
  'numPartitions': 8,
  'refreshOnEnable': false
);

校验与配置边界

• 未知属性、重复属性、非法布尔值/整数/枚举、无效 JSON，以及结构化配置内的未知字段会报错，不会静默忽略。properties 对象允许业务扩展键。
• incrementalConfigV2、incrementalRefreshConfig、旧版 merge/expression/errorHandle 三种配置方式不能混用。
• partitionsReadConfig 不能与 writable/partitionColumn/numPartitions 简写混用。
• 同一 refreshOnEnable 或 autoDetectPartitions 不能同时在 JSON 对象与简写属性中重复指定。
• JSON 配置值必须为对象，不接受 null 或数组作为整个配置；对象内的字段遵循相应 DTO 类型。
• ALTER TABLE ... SET PROJECTION PROPERTIES 修改的是表级刷新配置，与这里的单投影 scheduleConfig、增量配置不同。
• DISTRIBUTE BY 仍是历史保留语法，当前没有对应的 Tardis 创建配置和执行映射；不能用于保证数据分布。本次属性兼容不增加该能力。
• Presto 方言的 ALTER RAW/AGGREGATE PROJECTION ... WITH PROPERTIES 同样可使用上述配置。未指定的配置保留；指定的结构化配置整体替换，properties 按键合并。id 不可修改，投影类型、流式类型等其他不可变约束由公共更新服务校验。MySQL 本节仅扩展创建语句。

ALTER PROJECTION

修改投影字段定义。Presto 方言可在语句末尾使用 WITH PROPERTIES 修改单投影配置，未指定的配置保留；字段约束和不可变属性与 API 更新接口一致。

• 语法说明

ALTER RAW PROJECTION 'prpjectionId'
USING
DISPLAY (field1, field2, field3...)
[ PARTITION BY (field1, field2, field3...) ]
[ SORT BY (field1, field2, field...) ]
[ DISTRIBUTE BY (field1, field2, field3...) ]
ALTER AGGREGATE PROJECTION 'prpjectionId'
USING 
DIMENSIONS (x by day, y) 
MEASURES (b (COUNT, MIN, MAX, SUM, APPROXIMATE COUNT DISTINCT)) 
[ PARTITION BY (field1, field2, field3...) ]
[ SORT BY (field1, field2, field...) ]
[ DISTRIBUTE BY (field1, field2, field3...) ]

REFRESH PROJECTION

刷新投影数据。

• 语法说明

REFRESH PROJECTION 'rpId' [ AS 'materializationId' ]

SHOW PROJECTION

查看表的投影配置

• 语法说明

SHOW PROJECTION PROPERTIES IN <tableName>

• 返回结果

refresh_mode = 'On_Demand'
refresh_type = 'Complete'
active_interval = 'Infinite'

PROJECTIONS

查看表或视图下面的投影名称

• 语法说明

SHOW PROJECTIONS IN <projectionName>

• 使用示例

SHOW PROJECTIONS IN <projectionName>

• 返回结果

显示指定表或视图下面的投影列表。

Projection name | Projection Id | Projection Type | Status | Last Update Time
----------------+---------------+-----------------+--------+-------------------

DESC PROJECTION

查看RP详情

• 语法说明

DESC PROJECTION 'rpId';

• 返回结果

返回投影定义+投影状态+最近更新时间

对返回结果字段的说明如下。

字段名	说明
Projection Type	RawAggregate
DIMENSIONS	x by day, y
MEASURES	b (COUNT, MIN, MAX, SUM, APPROXIMATE COUNT DISTINCT)
PARTITION BY	field1
SORT BY	field2
DISTRIBUTE BY	field2
Status	Enabled，开启状态Disabled，关闭状态Error，数据集编辑了之后，Schema Failed的状态
Last Update Time	2022-09-28 12:00:00

ENABLE PROJECTION

开启投影。

• 语法说明

ENABLE PROJECTION 'rpId'
ALTER (TABLE | VIEW ) <name> ENABLE PROJECTION <projectionName>

DISABLE PROJECTION

关闭投影。

• 语法说明

DISABLE PROJECTION 'rpId'
ALTER (TABLE | VIEW ) <name> DISABLE PROJECTION <projectionName>

DROP PROJECTION

删除投影。

• 语法说明

DROP PROJECTION [IF EXISTS] 'rpId'
ALTER (TABLE | VIEW ) <name> DROP PROJECTION [IF EXISTS] <projectionName>