aokolnychyi commented on code in PR #6012: URL: https://github.com/apache/iceberg/pull/6012#discussion_r1116278037
########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable Review Comment: How accurate is this description now after recent changes? ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns Review Comment: nit: What about `pre/post update images` instead of `update-row` in all places? ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input + * them as the procedure parameters. Here is an example of update-row with an identifier column(id). + * A pair of a delete row and an insert row with the same id: + * + * <ul> + * <li>(id=1, data='a', op='DELETE') + * <li>(id=1, data='b', op='INSERT') + * </ul> + * + * <p>will be marked as update-rows: + * + * <ul> + * <li>(id=1, data='a', op='UPDATE_BEFORE') + * <li>(id=1, data='b', op='UPDATE_AFTER') + * </ul> + */ +public class CreateChangeViewProcedure extends BaseProcedure { + private static final Logger LOG = LoggerFactory.getLogger(CreateChangeViewProcedure.class); + + private static final ProcedureParameter[] PARAMETERS = + new ProcedureParameter[] { + ProcedureParameter.required("table", DataTypes.StringType), + ProcedureParameter.optional("changelog_view", DataTypes.StringType), + ProcedureParameter.optional("options", STRING_MAP), + ProcedureParameter.optional("compute_updates", DataTypes.BooleanType), + ProcedureParameter.optional("remove_carryovers", DataTypes.BooleanType), + ProcedureParameter.optional("identifier_columns", DataTypes.StringType), Review Comment: Shouldn't this be an array of strings? That way, we don't have to deal with escaping and parsing. We can also define a helper variable for it in `BaseProcedure`, just like we have `STRING_MAP` today. ``` protected static final DataType STRING_ARRAY = DataTypes.createArrayType(DataTypes.StringType); ``` ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. Review Comment: nit: `iterator` -> `procedure`? ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input + * them as the procedure parameters. Here is an example of update-row with an identifier column(id). + * A pair of a delete row and an insert row with the same id: + * + * <ul> + * <li>(id=1, data='a', op='DELETE') + * <li>(id=1, data='b', op='INSERT') + * </ul> + * + * <p>will be marked as update-rows: + * + * <ul> + * <li>(id=1, data='a', op='UPDATE_BEFORE') + * <li>(id=1, data='b', op='UPDATE_AFTER') + * </ul> + */ +public class CreateChangeViewProcedure extends BaseProcedure { + private static final Logger LOG = LoggerFactory.getLogger(CreateChangeViewProcedure.class); + + private static final ProcedureParameter[] PARAMETERS = + new ProcedureParameter[] { + ProcedureParameter.required("table", DataTypes.StringType), + ProcedureParameter.optional("changelog_view", DataTypes.StringType), + ProcedureParameter.optional("options", STRING_MAP), + ProcedureParameter.optional("compute_updates", DataTypes.BooleanType), + ProcedureParameter.optional("remove_carryovers", DataTypes.BooleanType), + ProcedureParameter.optional("identifier_columns", DataTypes.StringType), + }; + + private static final StructType OUTPUT_TYPE = + new StructType( + new StructField[] { + new StructField("changelog_view", DataTypes.StringType, false, Metadata.empty()) + }); + + public static SparkProcedures.ProcedureBuilder builder() { + return new BaseProcedure.Builder<CreateChangeViewProcedure>() { + @Override + protected CreateChangeViewProcedure doBuild() { + return new CreateChangeViewProcedure(tableCatalog()); + } + }; + } + + private CreateChangeViewProcedure(TableCatalog tableCatalog) { + super(tableCatalog); + } + + @Override + public ProcedureParameter[] parameters() { + return PARAMETERS; + } + + @Override + public StructType outputType() { + return OUTPUT_TYPE; + } + + @Override + public InternalRow[] call(InternalRow args) { + String tableName = args.getString(0); Review Comment: We can't use the table name as string because procedures resolve tables differently. We should follow what we do in other procedures. ``` Identifier tableIdent = toIdentifier(args.getString(0), PARAMETERS[0].name()); ``` Under the hood, it will default the catalog to the catalog for which this procedure is invoked, which may be different from the default Spark catalog in the session. ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input + * them as the procedure parameters. Here is an example of update-row with an identifier column(id). + * A pair of a delete row and an insert row with the same id: + * + * <ul> + * <li>(id=1, data='a', op='DELETE') + * <li>(id=1, data='b', op='INSERT') + * </ul> + * + * <p>will be marked as update-rows: + * + * <ul> + * <li>(id=1, data='a', op='UPDATE_BEFORE') + * <li>(id=1, data='b', op='UPDATE_AFTER') + * </ul> + */ +public class CreateChangeViewProcedure extends BaseProcedure { + private static final Logger LOG = LoggerFactory.getLogger(CreateChangeViewProcedure.class); + + private static final ProcedureParameter[] PARAMETERS = + new ProcedureParameter[] { + ProcedureParameter.required("table", DataTypes.StringType), + ProcedureParameter.optional("changelog_view", DataTypes.StringType), + ProcedureParameter.optional("options", STRING_MAP), + ProcedureParameter.optional("compute_updates", DataTypes.BooleanType), + ProcedureParameter.optional("remove_carryovers", DataTypes.BooleanType), + ProcedureParameter.optional("identifier_columns", DataTypes.StringType), + }; + + private static final StructType OUTPUT_TYPE = + new StructType( + new StructField[] { + new StructField("changelog_view", DataTypes.StringType, false, Metadata.empty()) + }); + + public static SparkProcedures.ProcedureBuilder builder() { + return new BaseProcedure.Builder<CreateChangeViewProcedure>() { + @Override + protected CreateChangeViewProcedure doBuild() { + return new CreateChangeViewProcedure(tableCatalog()); + } + }; + } + + private CreateChangeViewProcedure(TableCatalog tableCatalog) { + super(tableCatalog); + } + + @Override + public ProcedureParameter[] parameters() { + return PARAMETERS; + } + + @Override + public StructType outputType() { + return OUTPUT_TYPE; + } + + @Override + public InternalRow[] call(InternalRow args) { + String tableName = args.getString(0); + + // Read data from the table.changes + Dataset<Row> df = changelogRecords(tableName, readOptions(args)); + + // compute remove carry-over rows by default + boolean removeCarryoverRow = args.isNullAt(4) ? true : args.getBoolean(4); + + if (computeUpdatedRow(args)) { + String[] identifierColumns = identifierColumns(args, tableName); + + Preconditions.checkArgument( + identifierColumns.length > 0, + "Cannot compute the update-rows because identifier columns are not set"); + + Column[] repartitionColumns = getRepartitionExpr(df, identifierColumns); + df = transform(df, repartitionColumns); + } else if (removeCarryoverRow) { + df = removeCarryoverRows(df); + } + + String viewName = viewName(args, tableName); + + // Create a view for users to query + df.createOrReplaceTempView(viewName); + + return toOutputRows(viewName); + } + + private boolean computeUpdatedRow(InternalRow args) { + if (!args.isNullAt(5)) { + return true; + } + + return args.isNullAt(3) ? false : args.getBoolean(3); + } + + private Dataset<Row> removeCarryoverRows(Dataset<Row> df) { + Column[] repartitionColumns = + Arrays.stream(df.columns()) + .filter(c -> !c.equals(MetadataColumns.CHANGE_TYPE.name())) + .map(df::col) + .toArray(Column[]::new); + return transform(df, repartitionColumns); + } + + private String[] identifierColumns(InternalRow args, String tableName) { + String[] identifierColumns = new String[0]; + if (!args.isNullAt(5) && !args.getString(5).isEmpty()) { + identifierColumns = args.getString(5).split(","); + } + + if (identifierColumns.length == 0) { + Identifier tableIdent = toIdentifier(tableName, PARAMETERS[0].name()); + Table table = loadSparkTable(tableIdent).table(); + identifierColumns = table.schema().identifierFieldNames().toArray(new String[0]); + } + + return identifierColumns; + } + + private Dataset<Row> changelogRecords(String tableName, Map<String, String> readOptions) { + // no need to validate the read options here since the reader will validate them + return spark() + .read() + .options(readOptions) + .table(tableName + "." + SparkChangelogTable.TABLE_NAME); + } + + private Map<String, String> readOptions(InternalRow args) { + Map<String, String> options = Maps.newHashMap(); + + if (!args.isNullAt(2)) { + args.getMap(2) + .foreach( + DataTypes.StringType, + DataTypes.StringType, + (k, v) -> { + options.put(k.toString(), v.toString()); + return BoxedUnit.UNIT; + }); + } + + return options; + } + + @NotNull + private static String viewName(InternalRow args, String tableName) { Review Comment: Let me think about defaulting the view name tomorrow. ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input + * them as the procedure parameters. Here is an example of update-row with an identifier column(id). + * A pair of a delete row and an insert row with the same id: + * + * <ul> + * <li>(id=1, data='a', op='DELETE') + * <li>(id=1, data='b', op='INSERT') + * </ul> + * + * <p>will be marked as update-rows: + * + * <ul> + * <li>(id=1, data='a', op='UPDATE_BEFORE') + * <li>(id=1, data='b', op='UPDATE_AFTER') + * </ul> + */ +public class CreateChangeViewProcedure extends BaseProcedure { + private static final Logger LOG = LoggerFactory.getLogger(CreateChangeViewProcedure.class); + + private static final ProcedureParameter[] PARAMETERS = + new ProcedureParameter[] { + ProcedureParameter.required("table", DataTypes.StringType), + ProcedureParameter.optional("changelog_view", DataTypes.StringType), + ProcedureParameter.optional("options", STRING_MAP), + ProcedureParameter.optional("compute_updates", DataTypes.BooleanType), + ProcedureParameter.optional("remove_carryovers", DataTypes.BooleanType), + ProcedureParameter.optional("identifier_columns", DataTypes.StringType), + }; + + private static final StructType OUTPUT_TYPE = + new StructType( + new StructField[] { + new StructField("changelog_view", DataTypes.StringType, false, Metadata.empty()) + }); + + public static SparkProcedures.ProcedureBuilder builder() { + return new BaseProcedure.Builder<CreateChangeViewProcedure>() { + @Override + protected CreateChangeViewProcedure doBuild() { + return new CreateChangeViewProcedure(tableCatalog()); + } + }; + } + + private CreateChangeViewProcedure(TableCatalog tableCatalog) { + super(tableCatalog); + } + + @Override + public ProcedureParameter[] parameters() { + return PARAMETERS; + } + + @Override + public StructType outputType() { + return OUTPUT_TYPE; + } + + @Override + public InternalRow[] call(InternalRow args) { + String tableName = args.getString(0); + + // Read data from the table.changes + Dataset<Row> df = changelogRecords(tableName, readOptions(args)); + + // compute remove carry-over rows by default + boolean removeCarryoverRow = args.isNullAt(4) ? true : args.getBoolean(4); + + if (computeUpdatedRow(args)) { + String[] identifierColumns = identifierColumns(args, tableName); + + Preconditions.checkArgument( + identifierColumns.length > 0, + "Cannot compute the update-rows because identifier columns are not set"); + + Column[] repartitionColumns = getRepartitionExpr(df, identifierColumns); + df = transform(df, repartitionColumns); + } else if (removeCarryoverRow) { + df = removeCarryoverRows(df); + } + + String viewName = viewName(args, tableName); + + // Create a view for users to query + df.createOrReplaceTempView(viewName); + + return toOutputRows(viewName); + } + + private boolean computeUpdatedRow(InternalRow args) { + if (!args.isNullAt(5)) { + return true; + } + + return args.isNullAt(3) ? false : args.getBoolean(3); + } + + private Dataset<Row> removeCarryoverRows(Dataset<Row> df) { + Column[] repartitionColumns = + Arrays.stream(df.columns()) + .filter(c -> !c.equals(MetadataColumns.CHANGE_TYPE.name())) + .map(df::col) + .toArray(Column[]::new); + return transform(df, repartitionColumns); + } + + private String[] identifierColumns(InternalRow args, String tableName) { + String[] identifierColumns = new String[0]; + if (!args.isNullAt(5) && !args.getString(5).isEmpty()) { + identifierColumns = args.getString(5).split(","); + } + + if (identifierColumns.length == 0) { + Identifier tableIdent = toIdentifier(tableName, PARAMETERS[0].name()); + Table table = loadSparkTable(tableIdent).table(); + identifierColumns = table.schema().identifierFieldNames().toArray(new String[0]); + } + + return identifierColumns; + } + + private Dataset<Row> changelogRecords(String tableName, Map<String, String> readOptions) { Review Comment: We will need an identifier in this method so that the resolution works correctly. We could have something like this. ``` private Dataset<Row> changelogDF(Identifier tableIdent, Map<String, String> options) { Identifier changelogTableIdent = changelogTableIdent(tableIdent); return loadTable(changelogTableIdent, options); } private Identifier changelogTableIdent(Identifier tableIdent) { List<String> namespace = Lists.newArrayList(); namespace.addAll(Arrays.asList(tableIdent.namespace())); namespace.add(tableIdent.name()); return Identifier.of(namespace.toArray(new String[0]), SparkChangelogTable.TABLE_NAME); } ``` And then add the following method to `BaseProcedure`: ``` protected Dataset<Row> loadTable(Identifier tableIdent, Map<String, String> options) { String tableName = Spark3Util.quotedFullIdentifier(tableCatalog().name(), tableIdent); return spark().read().options(options).table(tableName); } ``` ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, Review Comment: nit: `change-log` -> `changelog`? ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input Review Comment: nit: Identifier fields are not set in the table properties. They are set in the schema. ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input + * them as the procedure parameters. Here is an example of update-row with an identifier column(id). Review Comment: nit: `update-row` -> `pre/post update images` ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input Review Comment: nit: Just `identifier field IDs`? ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input + * them as the procedure parameters. Here is an example of update-row with an identifier column(id). + * A pair of a delete row and an insert row with the same id: + * + * <ul> + * <li>(id=1, data='a', op='DELETE') + * <li>(id=1, data='b', op='INSERT') + * </ul> + * + * <p>will be marked as update-rows: + * + * <ul> + * <li>(id=1, data='a', op='UPDATE_BEFORE') + * <li>(id=1, data='b', op='UPDATE_AFTER') + * </ul> + */ +public class CreateChangeViewProcedure extends BaseProcedure { Review Comment: What about calling it `CreateChangelogViewProcedure`? We kind of provide a real changelog with update images. ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input + * them as the procedure parameters. Here is an example of update-row with an identifier column(id). + * A pair of a delete row and an insert row with the same id: + * + * <ul> + * <li>(id=1, data='a', op='DELETE') + * <li>(id=1, data='b', op='INSERT') + * </ul> + * + * <p>will be marked as update-rows: + * + * <ul> + * <li>(id=1, data='a', op='UPDATE_BEFORE') + * <li>(id=1, data='b', op='UPDATE_AFTER') + * </ul> + */ +public class CreateChangeViewProcedure extends BaseProcedure { + private static final Logger LOG = LoggerFactory.getLogger(CreateChangeViewProcedure.class); + + private static final ProcedureParameter[] PARAMETERS = + new ProcedureParameter[] { + ProcedureParameter.required("table", DataTypes.StringType), + ProcedureParameter.optional("changelog_view", DataTypes.StringType), + ProcedureParameter.optional("options", STRING_MAP), + ProcedureParameter.optional("compute_updates", DataTypes.BooleanType), + ProcedureParameter.optional("remove_carryovers", DataTypes.BooleanType), + ProcedureParameter.optional("identifier_columns", DataTypes.StringType), + }; + + private static final StructType OUTPUT_TYPE = + new StructType( + new StructField[] { + new StructField("changelog_view", DataTypes.StringType, false, Metadata.empty()) + }); + + public static SparkProcedures.ProcedureBuilder builder() { + return new BaseProcedure.Builder<CreateChangeViewProcedure>() { + @Override + protected CreateChangeViewProcedure doBuild() { + return new CreateChangeViewProcedure(tableCatalog()); + } + }; + } + + private CreateChangeViewProcedure(TableCatalog tableCatalog) { + super(tableCatalog); + } + + @Override + public ProcedureParameter[] parameters() { + return PARAMETERS; + } + + @Override + public StructType outputType() { + return OUTPUT_TYPE; + } + + @Override + public InternalRow[] call(InternalRow args) { + String tableName = args.getString(0); + + // Read data from the table.changes + Dataset<Row> df = changelogRecords(tableName, readOptions(args)); + + // compute remove carry-over rows by default + boolean removeCarryoverRow = args.isNullAt(4) ? true : args.getBoolean(4); + + if (computeUpdatedRow(args)) { + String[] identifierColumns = identifierColumns(args, tableName); + + Preconditions.checkArgument( + identifierColumns.length > 0, + "Cannot compute the update-rows because identifier columns are not set"); + + Column[] repartitionColumns = getRepartitionExpr(df, identifierColumns); + df = transform(df, repartitionColumns); + } else if (removeCarryoverRow) { + df = removeCarryoverRows(df); + } + + String viewName = viewName(args, tableName); + + // Create a view for users to query Review Comment: nit: This seems to be fairly obvious, do we need this comment? ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input + * them as the procedure parameters. Here is an example of update-row with an identifier column(id). + * A pair of a delete row and an insert row with the same id: + * + * <ul> + * <li>(id=1, data='a', op='DELETE') + * <li>(id=1, data='b', op='INSERT') + * </ul> + * + * <p>will be marked as update-rows: + * + * <ul> + * <li>(id=1, data='a', op='UPDATE_BEFORE') + * <li>(id=1, data='b', op='UPDATE_AFTER') + * </ul> + */ +public class CreateChangeViewProcedure extends BaseProcedure { + private static final Logger LOG = LoggerFactory.getLogger(CreateChangeViewProcedure.class); Review Comment: Is this being used? ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input + * them as the procedure parameters. Here is an example of update-row with an identifier column(id). + * A pair of a delete row and an insert row with the same id: + * + * <ul> + * <li>(id=1, data='a', op='DELETE') + * <li>(id=1, data='b', op='INSERT') + * </ul> + * + * <p>will be marked as update-rows: + * + * <ul> + * <li>(id=1, data='a', op='UPDATE_BEFORE') + * <li>(id=1, data='b', op='UPDATE_AFTER') + * </ul> + */ +public class CreateChangeViewProcedure extends BaseProcedure { + private static final Logger LOG = LoggerFactory.getLogger(CreateChangeViewProcedure.class); + + private static final ProcedureParameter[] PARAMETERS = + new ProcedureParameter[] { + ProcedureParameter.required("table", DataTypes.StringType), + ProcedureParameter.optional("changelog_view", DataTypes.StringType), + ProcedureParameter.optional("options", STRING_MAP), + ProcedureParameter.optional("compute_updates", DataTypes.BooleanType), + ProcedureParameter.optional("remove_carryovers", DataTypes.BooleanType), + ProcedureParameter.optional("identifier_columns", DataTypes.StringType), + }; + + private static final StructType OUTPUT_TYPE = + new StructType( + new StructField[] { + new StructField("changelog_view", DataTypes.StringType, false, Metadata.empty()) + }); + + public static SparkProcedures.ProcedureBuilder builder() { + return new BaseProcedure.Builder<CreateChangeViewProcedure>() { + @Override + protected CreateChangeViewProcedure doBuild() { + return new CreateChangeViewProcedure(tableCatalog()); + } + }; + } + + private CreateChangeViewProcedure(TableCatalog tableCatalog) { + super(tableCatalog); + } + + @Override + public ProcedureParameter[] parameters() { + return PARAMETERS; + } + + @Override + public StructType outputType() { + return OUTPUT_TYPE; + } + + @Override + public InternalRow[] call(InternalRow args) { + String tableName = args.getString(0); + + // Read data from the table.changes + Dataset<Row> df = changelogRecords(tableName, readOptions(args)); + + // compute remove carry-over rows by default + boolean removeCarryoverRow = args.isNullAt(4) ? true : args.getBoolean(4); + + if (computeUpdatedRow(args)) { + String[] identifierColumns = identifierColumns(args, tableName); + + Preconditions.checkArgument( + identifierColumns.length > 0, + "Cannot compute the update-rows because identifier columns are not set"); + + Column[] repartitionColumns = getRepartitionExpr(df, identifierColumns); + df = transform(df, repartitionColumns); + } else if (removeCarryoverRow) { + df = removeCarryoverRows(df); + } + + String viewName = viewName(args, tableName); + + // Create a view for users to query + df.createOrReplaceTempView(viewName); + + return toOutputRows(viewName); + } + + private boolean computeUpdatedRow(InternalRow args) { + if (!args.isNullAt(5)) { + return true; + } + + return args.isNullAt(3) ? false : args.getBoolean(3); + } + + private Dataset<Row> removeCarryoverRows(Dataset<Row> df) { Review Comment: Can you explore the idea of using native `dropDuplicates` operation instead of applying the iterator? At least, this should avoid the conversion from the internal to the public row representation, which is required by the iterator at the moment. ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input + * them as the procedure parameters. Here is an example of update-row with an identifier column(id). + * A pair of a delete row and an insert row with the same id: + * + * <ul> + * <li>(id=1, data='a', op='DELETE') + * <li>(id=1, data='b', op='INSERT') + * </ul> + * + * <p>will be marked as update-rows: + * + * <ul> + * <li>(id=1, data='a', op='UPDATE_BEFORE') + * <li>(id=1, data='b', op='UPDATE_AFTER') + * </ul> + */ +public class CreateChangeViewProcedure extends BaseProcedure { + private static final Logger LOG = LoggerFactory.getLogger(CreateChangeViewProcedure.class); + + private static final ProcedureParameter[] PARAMETERS = + new ProcedureParameter[] { + ProcedureParameter.required("table", DataTypes.StringType), + ProcedureParameter.optional("changelog_view", DataTypes.StringType), + ProcedureParameter.optional("options", STRING_MAP), + ProcedureParameter.optional("compute_updates", DataTypes.BooleanType), + ProcedureParameter.optional("remove_carryovers", DataTypes.BooleanType), + ProcedureParameter.optional("identifier_columns", DataTypes.StringType), + }; + + private static final StructType OUTPUT_TYPE = + new StructType( + new StructField[] { + new StructField("changelog_view", DataTypes.StringType, false, Metadata.empty()) + }); + + public static SparkProcedures.ProcedureBuilder builder() { + return new BaseProcedure.Builder<CreateChangeViewProcedure>() { + @Override + protected CreateChangeViewProcedure doBuild() { + return new CreateChangeViewProcedure(tableCatalog()); + } + }; + } + + private CreateChangeViewProcedure(TableCatalog tableCatalog) { + super(tableCatalog); + } + + @Override + public ProcedureParameter[] parameters() { + return PARAMETERS; + } + + @Override + public StructType outputType() { + return OUTPUT_TYPE; + } + + @Override + public InternalRow[] call(InternalRow args) { + String tableName = args.getString(0); + + // Read data from the table.changes + Dataset<Row> df = changelogRecords(tableName, readOptions(args)); + + // compute remove carry-over rows by default + boolean removeCarryoverRow = args.isNullAt(4) ? true : args.getBoolean(4); + + if (computeUpdatedRow(args)) { + String[] identifierColumns = identifierColumns(args, tableName); + + Preconditions.checkArgument( + identifierColumns.length > 0, + "Cannot compute the update-rows because identifier columns are not set"); + + Column[] repartitionColumns = getRepartitionExpr(df, identifierColumns); + df = transform(df, repartitionColumns); + } else if (removeCarryoverRow) { + df = removeCarryoverRows(df); + } + + String viewName = viewName(args, tableName); + + // Create a view for users to query + df.createOrReplaceTempView(viewName); + + return toOutputRows(viewName); + } + + private boolean computeUpdatedRow(InternalRow args) { + if (!args.isNullAt(5)) { + return true; + } + + return args.isNullAt(3) ? false : args.getBoolean(3); + } + + private Dataset<Row> removeCarryoverRows(Dataset<Row> df) { + Column[] repartitionColumns = + Arrays.stream(df.columns()) + .filter(c -> !c.equals(MetadataColumns.CHANGE_TYPE.name())) + .map(df::col) + .toArray(Column[]::new); + return transform(df, repartitionColumns); + } + + private String[] identifierColumns(InternalRow args, String tableName) { + String[] identifierColumns = new String[0]; + if (!args.isNullAt(5) && !args.getString(5).isEmpty()) { + identifierColumns = args.getString(5).split(","); + } + + if (identifierColumns.length == 0) { + Identifier tableIdent = toIdentifier(tableName, PARAMETERS[0].name()); + Table table = loadSparkTable(tableIdent).table(); + identifierColumns = table.schema().identifierFieldNames().toArray(new String[0]); + } + + return identifierColumns; + } + + private Dataset<Row> changelogRecords(String tableName, Map<String, String> readOptions) { + // no need to validate the read options here since the reader will validate them + return spark() + .read() + .options(readOptions) + .table(tableName + "." + SparkChangelogTable.TABLE_NAME); + } + + private Map<String, String> readOptions(InternalRow args) { + Map<String, String> options = Maps.newHashMap(); + + if (!args.isNullAt(2)) { + args.getMap(2) + .foreach( + DataTypes.StringType, + DataTypes.StringType, + (k, v) -> { + options.put(k.toString(), v.toString()); + return BoxedUnit.UNIT; + }); + } + + return options; + } + + @NotNull + private static String viewName(InternalRow args, String tableName) { + String viewName = args.isNullAt(1) ? null : args.getString(1); + if (viewName == null) { + String shortTableName = + tableName.contains(".") ? tableName.substring(tableName.lastIndexOf(".") + 1) : tableName; + viewName = shortTableName + "_changes"; + } + return viewName; + } + + private Dataset<Row> transform(Dataset<Row> df, Column[] repartitionColumns) { Review Comment: If we decide to use `dropDuplicates` to remove carryovers, this may have a more specific name. ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input + * them as the procedure parameters. Here is an example of update-row with an identifier column(id). + * A pair of a delete row and an insert row with the same id: + * + * <ul> + * <li>(id=1, data='a', op='DELETE') + * <li>(id=1, data='b', op='INSERT') + * </ul> + * + * <p>will be marked as update-rows: + * + * <ul> + * <li>(id=1, data='a', op='UPDATE_BEFORE') + * <li>(id=1, data='b', op='UPDATE_AFTER') + * </ul> + */ +public class CreateChangeViewProcedure extends BaseProcedure { + private static final Logger LOG = LoggerFactory.getLogger(CreateChangeViewProcedure.class); + + private static final ProcedureParameter[] PARAMETERS = + new ProcedureParameter[] { + ProcedureParameter.required("table", DataTypes.StringType), + ProcedureParameter.optional("changelog_view", DataTypes.StringType), + ProcedureParameter.optional("options", STRING_MAP), + ProcedureParameter.optional("compute_updates", DataTypes.BooleanType), + ProcedureParameter.optional("remove_carryovers", DataTypes.BooleanType), + ProcedureParameter.optional("identifier_columns", DataTypes.StringType), + }; + + private static final StructType OUTPUT_TYPE = + new StructType( + new StructField[] { + new StructField("changelog_view", DataTypes.StringType, false, Metadata.empty()) + }); + + public static SparkProcedures.ProcedureBuilder builder() { + return new BaseProcedure.Builder<CreateChangeViewProcedure>() { + @Override + protected CreateChangeViewProcedure doBuild() { + return new CreateChangeViewProcedure(tableCatalog()); + } + }; + } + + private CreateChangeViewProcedure(TableCatalog tableCatalog) { + super(tableCatalog); + } + + @Override + public ProcedureParameter[] parameters() { + return PARAMETERS; + } + + @Override + public StructType outputType() { + return OUTPUT_TYPE; + } + + @Override + public InternalRow[] call(InternalRow args) { + String tableName = args.getString(0); + + // Read data from the table.changes + Dataset<Row> df = changelogRecords(tableName, readOptions(args)); + + // compute remove carry-over rows by default + boolean removeCarryoverRow = args.isNullAt(4) ? true : args.getBoolean(4); + + if (computeUpdatedRow(args)) { + String[] identifierColumns = identifierColumns(args, tableName); + + Preconditions.checkArgument( + identifierColumns.length > 0, + "Cannot compute the update-rows because identifier columns are not set"); + + Column[] repartitionColumns = getRepartitionExpr(df, identifierColumns); + df = transform(df, repartitionColumns); + } else if (removeCarryoverRow) { + df = removeCarryoverRows(df); + } + + String viewName = viewName(args, tableName); + + // Create a view for users to query + df.createOrReplaceTempView(viewName); + + return toOutputRows(viewName); + } + + private boolean computeUpdatedRow(InternalRow args) { + if (!args.isNullAt(5)) { + return true; + } + + return args.isNullAt(3) ? false : args.getBoolean(3); Review Comment: What about defining some static vars to give meaning to these numbers? ``` private static final int COMPUTE_UPDATES_ORDINAL = 3; ``` We do that in Spark functions. I will also think about a better approach to handle parsing of args. ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input + * them as the procedure parameters. Here is an example of update-row with an identifier column(id). + * A pair of a delete row and an insert row with the same id: + * + * <ul> + * <li>(id=1, data='a', op='DELETE') + * <li>(id=1, data='b', op='INSERT') + * </ul> + * + * <p>will be marked as update-rows: + * + * <ul> + * <li>(id=1, data='a', op='UPDATE_BEFORE') + * <li>(id=1, data='b', op='UPDATE_AFTER') + * </ul> + */ +public class CreateChangeViewProcedure extends BaseProcedure { + private static final Logger LOG = LoggerFactory.getLogger(CreateChangeViewProcedure.class); + + private static final ProcedureParameter[] PARAMETERS = + new ProcedureParameter[] { + ProcedureParameter.required("table", DataTypes.StringType), + ProcedureParameter.optional("changelog_view", DataTypes.StringType), + ProcedureParameter.optional("options", STRING_MAP), + ProcedureParameter.optional("compute_updates", DataTypes.BooleanType), + ProcedureParameter.optional("remove_carryovers", DataTypes.BooleanType), + ProcedureParameter.optional("identifier_columns", DataTypes.StringType), + }; + + private static final StructType OUTPUT_TYPE = + new StructType( + new StructField[] { + new StructField("changelog_view", DataTypes.StringType, false, Metadata.empty()) + }); + + public static SparkProcedures.ProcedureBuilder builder() { + return new BaseProcedure.Builder<CreateChangeViewProcedure>() { + @Override + protected CreateChangeViewProcedure doBuild() { + return new CreateChangeViewProcedure(tableCatalog()); + } + }; + } + + private CreateChangeViewProcedure(TableCatalog tableCatalog) { + super(tableCatalog); + } + + @Override + public ProcedureParameter[] parameters() { + return PARAMETERS; + } + + @Override + public StructType outputType() { + return OUTPUT_TYPE; + } + + @Override + public InternalRow[] call(InternalRow args) { + String tableName = args.getString(0); + + // Read data from the table.changes + Dataset<Row> df = changelogRecords(tableName, readOptions(args)); + + // compute remove carry-over rows by default + boolean removeCarryoverRow = args.isNullAt(4) ? true : args.getBoolean(4); + + if (computeUpdatedRow(args)) { + String[] identifierColumns = identifierColumns(args, tableName); + + Preconditions.checkArgument( + identifierColumns.length > 0, + "Cannot compute the update-rows because identifier columns are not set"); + + Column[] repartitionColumns = getRepartitionExpr(df, identifierColumns); + df = transform(df, repartitionColumns); + } else if (removeCarryoverRow) { + df = removeCarryoverRows(df); + } + + String viewName = viewName(args, tableName); + + // Create a view for users to query + df.createOrReplaceTempView(viewName); + + return toOutputRows(viewName); + } + + private boolean computeUpdatedRow(InternalRow args) { + if (!args.isNullAt(5)) { Review Comment: It is a good idea to compute update images if the user provided identifier columns but only if the flag is not set to false. If the flag to compute update images is explicitly set to false, we should respect it. ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input + * them as the procedure parameters. Here is an example of update-row with an identifier column(id). + * A pair of a delete row and an insert row with the same id: + * + * <ul> + * <li>(id=1, data='a', op='DELETE') + * <li>(id=1, data='b', op='INSERT') + * </ul> + * + * <p>will be marked as update-rows: + * + * <ul> + * <li>(id=1, data='a', op='UPDATE_BEFORE') + * <li>(id=1, data='b', op='UPDATE_AFTER') + * </ul> + */ +public class CreateChangeViewProcedure extends BaseProcedure { + private static final Logger LOG = LoggerFactory.getLogger(CreateChangeViewProcedure.class); + + private static final ProcedureParameter[] PARAMETERS = + new ProcedureParameter[] { + ProcedureParameter.required("table", DataTypes.StringType), + ProcedureParameter.optional("changelog_view", DataTypes.StringType), + ProcedureParameter.optional("options", STRING_MAP), + ProcedureParameter.optional("compute_updates", DataTypes.BooleanType), + ProcedureParameter.optional("remove_carryovers", DataTypes.BooleanType), + ProcedureParameter.optional("identifier_columns", DataTypes.StringType), + }; + + private static final StructType OUTPUT_TYPE = + new StructType( + new StructField[] { + new StructField("changelog_view", DataTypes.StringType, false, Metadata.empty()) + }); + + public static SparkProcedures.ProcedureBuilder builder() { + return new BaseProcedure.Builder<CreateChangeViewProcedure>() { + @Override + protected CreateChangeViewProcedure doBuild() { + return new CreateChangeViewProcedure(tableCatalog()); + } + }; + } + + private CreateChangeViewProcedure(TableCatalog tableCatalog) { + super(tableCatalog); + } + + @Override + public ProcedureParameter[] parameters() { + return PARAMETERS; + } + + @Override + public StructType outputType() { + return OUTPUT_TYPE; + } + + @Override + public InternalRow[] call(InternalRow args) { + String tableName = args.getString(0); + + // Read data from the table.changes + Dataset<Row> df = changelogRecords(tableName, readOptions(args)); + + // compute remove carry-over rows by default + boolean removeCarryoverRow = args.isNullAt(4) ? true : args.getBoolean(4); Review Comment: nit: What about defining a method `removeCarryovers(args)` like we have for other args? ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input + * them as the procedure parameters. Here is an example of update-row with an identifier column(id). + * A pair of a delete row and an insert row with the same id: + * + * <ul> + * <li>(id=1, data='a', op='DELETE') + * <li>(id=1, data='b', op='INSERT') + * </ul> + * + * <p>will be marked as update-rows: + * + * <ul> + * <li>(id=1, data='a', op='UPDATE_BEFORE') + * <li>(id=1, data='b', op='UPDATE_AFTER') + * </ul> + */ +public class CreateChangeViewProcedure extends BaseProcedure { + private static final Logger LOG = LoggerFactory.getLogger(CreateChangeViewProcedure.class); + + private static final ProcedureParameter[] PARAMETERS = + new ProcedureParameter[] { + ProcedureParameter.required("table", DataTypes.StringType), + ProcedureParameter.optional("changelog_view", DataTypes.StringType), + ProcedureParameter.optional("options", STRING_MAP), + ProcedureParameter.optional("compute_updates", DataTypes.BooleanType), + ProcedureParameter.optional("remove_carryovers", DataTypes.BooleanType), + ProcedureParameter.optional("identifier_columns", DataTypes.StringType), + }; + + private static final StructType OUTPUT_TYPE = + new StructType( + new StructField[] { + new StructField("changelog_view", DataTypes.StringType, false, Metadata.empty()) + }); + + public static SparkProcedures.ProcedureBuilder builder() { + return new BaseProcedure.Builder<CreateChangeViewProcedure>() { + @Override + protected CreateChangeViewProcedure doBuild() { + return new CreateChangeViewProcedure(tableCatalog()); + } + }; + } + + private CreateChangeViewProcedure(TableCatalog tableCatalog) { + super(tableCatalog); + } + + @Override + public ProcedureParameter[] parameters() { + return PARAMETERS; + } + + @Override + public StructType outputType() { + return OUTPUT_TYPE; + } + + @Override + public InternalRow[] call(InternalRow args) { + String tableName = args.getString(0); + + // Read data from the table.changes + Dataset<Row> df = changelogRecords(tableName, readOptions(args)); + + // compute remove carry-over rows by default + boolean removeCarryoverRow = args.isNullAt(4) ? true : args.getBoolean(4); + + if (computeUpdatedRow(args)) { + String[] identifierColumns = identifierColumns(args, tableName); + + Preconditions.checkArgument( + identifierColumns.length > 0, + "Cannot compute the update-rows because identifier columns are not set"); + + Column[] repartitionColumns = getRepartitionExpr(df, identifierColumns); + df = transform(df, repartitionColumns); + } else if (removeCarryoverRow) { + df = removeCarryoverRows(df); + } + + String viewName = viewName(args, tableName); + + // Create a view for users to query + df.createOrReplaceTempView(viewName); + + return toOutputRows(viewName); + } + + private boolean computeUpdatedRow(InternalRow args) { Review Comment: nit: What about `computeUpdateImages`? ########## spark/v3.3/spark/src/main/java/org/apache/iceberg/spark/procedures/CreateChangeViewProcedure.java: ########## @@ -0,0 +1,267 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.iceberg.spark.procedures; + +import java.util.Arrays; +import java.util.Map; +import org.apache.iceberg.MetadataColumns; +import org.apache.iceberg.Table; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.relocated.com.google.common.collect.Maps; +import org.apache.iceberg.spark.ChangelogIterator; +import org.apache.iceberg.spark.source.SparkChangelogTable; +import org.apache.spark.api.java.function.MapPartitionsFunction; +import org.apache.spark.sql.Column; +import org.apache.spark.sql.Dataset; +import org.apache.spark.sql.Row; +import org.apache.spark.sql.catalyst.InternalRow; +import org.apache.spark.sql.catalyst.encoders.RowEncoder; +import org.apache.spark.sql.connector.catalog.Identifier; +import org.apache.spark.sql.connector.catalog.TableCatalog; +import org.apache.spark.sql.connector.iceberg.catalog.ProcedureParameter; +import org.apache.spark.sql.types.DataTypes; +import org.apache.spark.sql.types.Metadata; +import org.apache.spark.sql.types.StructField; +import org.apache.spark.sql.types.StructType; +import org.apache.spark.unsafe.types.UTF8String; +import org.jetbrains.annotations.NotNull; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import scala.runtime.BoxedUnit; + +/** + * A procedure that creates a view for changed rows. + * + * <p>The procedure computes update-rows and removes the carry-over rows by default. You can disable + * them through parameters to get better performance. + * + * <p>Carry-over rows are the result of a removal and insertion of the same row within an operation + * because of the copy-on-write mechanism. For example, given a file which contains row1 (id=1, + * data='a') and row2 (id=2, data='b'). A copy-on-write delete of row2 would require erasing this + * file and preserving row1 in a new file. The change-log table would report this as (id=1, + * data='a', op='DELETE') and (id=1, data='a', op='INSERT'), despite it not being an actual change + * to the table. The iterator finds the carry-over rows and removes them from the result. + * + * <p>An update-row is converted from a pair of a delete row and an insert row. Identifier columns + * are used for determining whether an insert and a delete record refer to the same row. If the two + * records share the same values for the identity columns they are considered to be before and after + * states of the same row. You can either set Identifier Field IDs as the table properties or input + * them as the procedure parameters. Here is an example of update-row with an identifier column(id). + * A pair of a delete row and an insert row with the same id: + * + * <ul> + * <li>(id=1, data='a', op='DELETE') + * <li>(id=1, data='b', op='INSERT') + * </ul> + * + * <p>will be marked as update-rows: + * + * <ul> + * <li>(id=1, data='a', op='UPDATE_BEFORE') + * <li>(id=1, data='b', op='UPDATE_AFTER') + * </ul> + */ +public class CreateChangeViewProcedure extends BaseProcedure { + private static final Logger LOG = LoggerFactory.getLogger(CreateChangeViewProcedure.class); + + private static final ProcedureParameter[] PARAMETERS = + new ProcedureParameter[] { + ProcedureParameter.required("table", DataTypes.StringType), + ProcedureParameter.optional("changelog_view", DataTypes.StringType), + ProcedureParameter.optional("options", STRING_MAP), + ProcedureParameter.optional("compute_updates", DataTypes.BooleanType), + ProcedureParameter.optional("remove_carryovers", DataTypes.BooleanType), + ProcedureParameter.optional("identifier_columns", DataTypes.StringType), + }; + + private static final StructType OUTPUT_TYPE = + new StructType( + new StructField[] { + new StructField("changelog_view", DataTypes.StringType, false, Metadata.empty()) + }); + + public static SparkProcedures.ProcedureBuilder builder() { + return new BaseProcedure.Builder<CreateChangeViewProcedure>() { + @Override + protected CreateChangeViewProcedure doBuild() { + return new CreateChangeViewProcedure(tableCatalog()); + } + }; + } + + private CreateChangeViewProcedure(TableCatalog tableCatalog) { + super(tableCatalog); + } + + @Override + public ProcedureParameter[] parameters() { + return PARAMETERS; + } + + @Override + public StructType outputType() { + return OUTPUT_TYPE; + } + + @Override + public InternalRow[] call(InternalRow args) { + String tableName = args.getString(0); + + // Read data from the table.changes + Dataset<Row> df = changelogRecords(tableName, readOptions(args)); + + // compute remove carry-over rows by default + boolean removeCarryoverRow = args.isNullAt(4) ? true : args.getBoolean(4); + + if (computeUpdatedRow(args)) { + String[] identifierColumns = identifierColumns(args, tableName); + + Preconditions.checkArgument( + identifierColumns.length > 0, + "Cannot compute the update-rows because identifier columns are not set"); + + Column[] repartitionColumns = getRepartitionExpr(df, identifierColumns); + df = transform(df, repartitionColumns); + } else if (removeCarryoverRow) { + df = removeCarryoverRows(df); + } + + String viewName = viewName(args, tableName); + + // Create a view for users to query + df.createOrReplaceTempView(viewName); + + return toOutputRows(viewName); + } + + private boolean computeUpdatedRow(InternalRow args) { + if (!args.isNullAt(5)) { + return true; + } + + return args.isNullAt(3) ? false : args.getBoolean(3); + } + + private Dataset<Row> removeCarryoverRows(Dataset<Row> df) { + Column[] repartitionColumns = + Arrays.stream(df.columns()) + .filter(c -> !c.equals(MetadataColumns.CHANGE_TYPE.name())) + .map(df::col) + .toArray(Column[]::new); + return transform(df, repartitionColumns); + } + + private String[] identifierColumns(InternalRow args, String tableName) { + String[] identifierColumns = new String[0]; + if (!args.isNullAt(5) && !args.getString(5).isEmpty()) { + identifierColumns = args.getString(5).split(","); + } + + if (identifierColumns.length == 0) { + Identifier tableIdent = toIdentifier(tableName, PARAMETERS[0].name()); + Table table = loadSparkTable(tableIdent).table(); + identifierColumns = table.schema().identifierFieldNames().toArray(new String[0]); + } + + return identifierColumns; + } + + private Dataset<Row> changelogRecords(String tableName, Map<String, String> readOptions) { + // no need to validate the read options here since the reader will validate them + return spark() + .read() + .options(readOptions) + .table(tableName + "." + SparkChangelogTable.TABLE_NAME); + } + + private Map<String, String> readOptions(InternalRow args) { + Map<String, String> options = Maps.newHashMap(); + + if (!args.isNullAt(2)) { + args.getMap(2) + .foreach( + DataTypes.StringType, + DataTypes.StringType, + (k, v) -> { + options.put(k.toString(), v.toString()); + return BoxedUnit.UNIT; + }); + } + + return options; + } + + @NotNull + private static String viewName(InternalRow args, String tableName) { + String viewName = args.isNullAt(1) ? null : args.getString(1); + if (viewName == null) { + String shortTableName = + tableName.contains(".") ? tableName.substring(tableName.lastIndexOf(".") + 1) : tableName; + viewName = shortTableName + "_changes"; + } + return viewName; + } + + private Dataset<Row> transform(Dataset<Row> df, Column[] repartitionColumns) { + Column[] sortSpec = sortSpec(df, repartitionColumns); + StructType schema = df.schema(); + String[] identifierFields = + Arrays.stream(repartitionColumns).map(Column::toString).toArray(String[]::new); + + return df.repartition(repartitionColumns) + .sortWithinPartitions(sortSpec) + .mapPartitions( + (MapPartitionsFunction<Row, Row>) + rowIterator -> ChangelogIterator.create(rowIterator, schema, identifierFields), + RowEncoder.apply(df.schema())); + } + + @NotNull + private static Column[] getRepartitionExpr(Dataset<Row> df, String[] identifiers) { + Column[] repartitionSpec = new Column[identifiers.length + 1]; + for (int i = 0; i < identifiers.length; i++) { + try { + repartitionSpec[i] = df.col(identifiers[i]); + } catch (Exception e) { + throw new IllegalArgumentException( + String.format("Identifier column '%s' does not exist in the table", identifiers[i]), e); + } + } + repartitionSpec[repartitionSpec.length - 1] = df.col(MetadataColumns.CHANGE_ORDINAL.name()); + return repartitionSpec; + } + + @NotNull + private static Column[] sortSpec(Dataset<Row> df, Column[] repartitionSpec) { + Column[] sortSpec = new Column[repartitionSpec.length + 1]; + System.arraycopy(repartitionSpec, 0, sortSpec, 0, repartitionSpec.length); + sortSpec[sortSpec.length - 1] = df.col(MetadataColumns.CHANGE_TYPE.name()); + return sortSpec; + } + + private InternalRow[] toOutputRows(String viewName) { + InternalRow row = newInternalRow(UTF8String.fromString(viewName)); + return new InternalRow[] {row}; + } + + @Override + public String description() { + return "GenerateChangesProcedure"; Review Comment: This should be updated to reflect the new procedure name. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org For additional commands, e-mail: issues-h...@iceberg.apache.org
