From 6958f09cbd27f613440e4d57ac79b109d8d368f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesse=20Tu=C4=9Flu?= Date: Fri, 23 Jan 2026 16:51:51 -0800 Subject: [PATCH 1/3] Allow failing on residual for Iceberg filters on non-partition cols --- .../development/extensions-contrib/iceberg.md | 31 ++++ docs/ingestion/input-sources.md | 1 + .../druid/iceberg/input/IcebergCatalog.java | 66 ++++++- .../iceberg/input/IcebergInputSource.java | 17 +- .../iceberg/input/ResidualFilterMode.java | 77 ++++++++ .../iceberg/input/IcebergInputSourceTest.java | 164 +++++++++++++++++- .../iceberg/input/ResidualFilterModeTest.java | 73 ++++++++ website/.spelling | 1 + 8 files changed, 425 insertions(+), 5 deletions(-) create mode 100644 extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/ResidualFilterMode.java create mode 100644 extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/ResidualFilterModeTest.java diff --git a/docs/development/extensions-contrib/iceberg.md b/docs/development/extensions-contrib/iceberg.md index e2a5a06cb9ec..ef5f7ac4ed06 100644 --- a/docs/development/extensions-contrib/iceberg.md +++ b/docs/development/extensions-contrib/iceberg.md @@ -139,6 +139,37 @@ java \ See [Loading community extensions](../../configuration/extensions.md#loading-community-extensions) for more information. +## Residual filter handling + +When an Iceberg filter is applied on a non-partition column, the filtering happens at the file metadata level only (using column statistics). Files that might contain matching rows are returned, but these files may include "residual" rows that don't actually match the filter. These residual rows would be ingested unless filtered by a `transformSpec` filter on the Druid side. + +To control this behavior, you can set the `residualFilterMode` property on the Iceberg input source: + +| Mode | Description | +|------|-------------| +| `ignore` | Default. Residual rows are ingested unless filtered by `transformSpec`. | +| `warn` | Log a warning when residual filters are detected, but continue with ingestion. | +| `fail` | Fail the ingestion job when residual filters are detected. Use this to ensure that filters only target partition columns. | + +Example: +```json +{ + "type": "iceberg", + "tableName": "events", + "namespace": "analytics", + "icebergCatalog": { ... }, + "icebergFilter": { + "type": "timeWindow", + "filterColumn": "event_time", + "lookbackDuration": "P1D" + }, + "residualFilterMode": "fail", + "warehouseSource": { ... } +} +``` + +When `residualFilterMode` is set to `fail` and a residual filter is detected, the job will fail with an error message indicating which filter expression produced the residual. This helps ensure data quality by preventing unintended rows from being ingested. + ## Known limitations This section lists the known limitations that apply to the Iceberg extension. diff --git a/docs/ingestion/input-sources.md b/docs/ingestion/input-sources.md index 49cf90cdbf58..552e5ff82900 100644 --- a/docs/ingestion/input-sources.md +++ b/docs/ingestion/input-sources.md @@ -1063,6 +1063,7 @@ The following is a sample spec for a S3 warehouse source: |icebergCatalog|The JSON Object used to define the catalog that manages the configured Iceberg table.|yes| |warehouseSource|The JSON Object that defines the native input source for reading the data files from the warehouse.|yes| |snapshotTime|Timestamp in ISO8601 DateTime format that will be used to fetch the most recent snapshot as of this time.|no| +|residualFilterMode|Controls how residual filters are handled when filtering on non-partition columns. When an Iceberg filter targets a non-partition column, files may contain rows that don't match the filter (residual rows). Valid values are: `ignore` (default, ingest all rows), `warn` (log a warning but continue), `fail` (fail the ingestion job). Use `fail` to ensure filters only target partition columns.|no| ### Catalog Object diff --git a/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergCatalog.java b/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergCatalog.java index 5dc5aa85a9a9..6f8aafd1a1d6 100644 --- a/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergCatalog.java +++ b/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergCatalog.java @@ -24,15 +24,19 @@ import org.apache.druid.iceberg.filter.IcebergFilter; import org.apache.druid.java.util.common.IAE; import org.apache.druid.java.util.common.RE; +import org.apache.druid.java.util.common.StringUtils; import org.apache.druid.java.util.common.logger.Logger; import org.apache.iceberg.FileScanTask; import org.apache.iceberg.TableScan; import org.apache.iceberg.catalog.Catalog; import org.apache.iceberg.catalog.Namespace; import org.apache.iceberg.catalog.TableIdentifier; +import org.apache.iceberg.expressions.Expression; +import org.apache.iceberg.expressions.Expressions; import org.apache.iceberg.io.CloseableIterable; import org.joda.time.DateTime; +import javax.annotation.Nullable; import java.util.ArrayList; import java.util.List; @@ -70,12 +74,35 @@ public List extractSnapshotDataFiles( IcebergFilter icebergFilter, DateTime snapshotTime ) + { + return extractSnapshotDataFiles(tableNamespace, tableName, icebergFilter, snapshotTime, null); + } + + /** + * Extract the iceberg data files upto the latest snapshot associated with the table + * + * @param tableNamespace The catalog namespace under which the table is defined + * @param tableName The iceberg table name + * @param icebergFilter The iceberg filter that needs to be applied before reading the files + * @param snapshotTime Datetime that will be used to fetch the most recent snapshot as of this time + * @param residualFilterMode Controls how residual filters are handled. When filtering on non-partition + * columns, residual rows may be returned that need row-level filtering. + * @return a list of data file paths + */ + public List extractSnapshotDataFiles( + String tableNamespace, + String tableName, + IcebergFilter icebergFilter, + DateTime snapshotTime, + @Nullable ResidualFilterMode residualFilterMode + ) { Catalog catalog = retrieveCatalog(); Namespace namespace = Namespace.of(tableNamespace); String tableIdentifier = tableNamespace + "." + tableName; List dataFilePaths = new ArrayList<>(); + ResidualFilterMode effectiveMode = residualFilterMode != null ? residualFilterMode : ResidualFilterMode.IGNORE; ClassLoader currCtxClassloader = Thread.currentThread().getContextClassLoader(); try { @@ -100,12 +127,47 @@ public List extractSnapshotDataFiles( tableScan = tableScan.caseSensitive(isCaseSensitive()); CloseableIterable tasks = tableScan.planFiles(); - CloseableIterable.transform(tasks, FileScanTask::file) - .forEach(dataFile -> dataFilePaths.add(dataFile.path().toString())); + + Expression detectedResidual = null; + for (FileScanTask task : tasks) { + dataFilePaths.add(task.file().path().toString()); + + // Check for residual filters if mode is not IGNORE + if (effectiveMode != ResidualFilterMode.IGNORE && detectedResidual == null) { + Expression residual = task.residual(); + if (residual != null && !residual.equals(Expressions.alwaysTrue())) { + detectedResidual = residual; + } + } + } + + // Handle residual filter based on mode + if (detectedResidual != null) { + String message = StringUtils.format( + "Iceberg filter produced residual expression that requires row-level filtering. " + + "This typically means the filter is on a non-partition column. " + + "Residual rows may be ingested unless filtered by transformSpec. " + + "Residual filter: [%s]", + detectedResidual + ); + + if (effectiveMode == ResidualFilterMode.FAIL) { + throw new IAE( + "%s To allow residual rows, set residualFilterMode to 'ignore' or 'warn', " + + "or add a corresponding filter in transformSpec.", + message + ); + } else if (effectiveMode == ResidualFilterMode.WARN) { + log.warn(message); + } + } long duration = System.currentTimeMillis() - start; log.info("Data file scan and fetch took [%d ms] time for [%d] paths", duration, dataFilePaths.size()); } + catch (IAE e) { + throw e; + } catch (Exception e) { throw new RE(e, "Failed to load iceberg table with identifier [%s]", tableIdentifier); } diff --git a/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergInputSource.java b/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergInputSource.java index 44df3e318611..8bbf762f797b 100644 --- a/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergInputSource.java +++ b/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergInputSource.java @@ -72,6 +72,9 @@ public class IcebergInputSource implements SplittableInputSource> @JsonProperty private final DateTime snapshotTime; + @JsonProperty + private final ResidualFilterMode residualFilterMode; + private boolean isLoaded = false; private SplittableInputSource delegateInputSource; @@ -83,7 +86,8 @@ public IcebergInputSource( @JsonProperty("icebergFilter") @Nullable IcebergFilter icebergFilter, @JsonProperty("icebergCatalog") IcebergCatalog icebergCatalog, @JsonProperty("warehouseSource") InputSourceFactory warehouseSource, - @JsonProperty("snapshotTime") @Nullable DateTime snapshotTime + @JsonProperty("snapshotTime") @Nullable DateTime snapshotTime, + @JsonProperty("residualFilterMode") @Nullable ResidualFilterMode residualFilterMode ) { this.tableName = Preconditions.checkNotNull(tableName, "tableName cannot be null"); @@ -92,6 +96,7 @@ public IcebergInputSource( this.icebergFilter = icebergFilter; this.warehouseSource = Preconditions.checkNotNull(warehouseSource, "warehouseSource cannot be null"); this.snapshotTime = snapshotTime; + this.residualFilterMode = residualFilterMode; } @Override @@ -177,6 +182,13 @@ public DateTime getSnapshotTime() return snapshotTime; } + @Nullable + @JsonProperty + public ResidualFilterMode getResidualFilterMode() + { + return residualFilterMode; + } + public SplittableInputSource getDelegateInputSource() { return delegateInputSource; @@ -188,7 +200,8 @@ protected void retrieveIcebergDatafiles() getNamespace(), getTableName(), getIcebergFilter(), - getSnapshotTime() + getSnapshotTime(), + getResidualFilterMode() ); if (snapshotDataFiles.isEmpty()) { delegateInputSource = new EmptyInputSource(); diff --git a/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/ResidualFilterMode.java b/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/ResidualFilterMode.java new file mode 100644 index 000000000000..58e2bedcc704 --- /dev/null +++ b/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/ResidualFilterMode.java @@ -0,0 +1,77 @@ +/* + * 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.druid.iceberg.input; + +import com.fasterxml.jackson.annotation.JsonValue; + +/** + * Controls how residual filters are handled during Iceberg table scanning. + * + * When an Iceberg filter is applied on a non-partition column, the filtering happens at the + * file metadata level only. Files that might contain matching rows are returned, but these + * files may include "residual" rows that don't actually match the filter. These residual rows + * would need to be filtered on the Druid side using a filter in transformSpec. + */ +public enum ResidualFilterMode +{ + /** + * Ignore residual filters. This is the default behavior for backward compatibility. + * Residual rows will be ingested unless filtered by transformSpec. + */ + IGNORE("ignore"), + + /** + * Log a warning when residual filters are detected, but continue with ingestion. + * Useful for identifying potential data quality issues without failing the job. + */ + WARN("warn"), + + /** + * Fail the ingestion job when residual filters are detected. + * Use this mode to ensure that only partition-column filters are used, + * preventing unintended residual rows from being ingested. + */ + FAIL("fail"); + + private final String value; + + ResidualFilterMode(String value) + { + this.value = value; + } + + @JsonValue + public String getValue() + { + return value; + } + + public static ResidualFilterMode fromString(String value) + { + for (ResidualFilterMode mode : values()) { + if (mode.value.equalsIgnoreCase(value)) { + return mode; + } + } + throw new IllegalArgumentException( + "Unknown residualFilterMode: " + value + ". Valid values are: ignore, warn, fail" + ); + } +} diff --git a/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/IcebergInputSourceTest.java b/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/IcebergInputSourceTest.java index 5a2429d6c7cf..e52efd4bb4c4 100644 --- a/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/IcebergInputSourceTest.java +++ b/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/IcebergInputSourceTest.java @@ -28,6 +28,7 @@ import org.apache.druid.iceberg.filter.IcebergEqualsFilter; import org.apache.druid.java.util.common.DateTimes; import org.apache.druid.java.util.common.FileUtils; +import org.apache.druid.java.util.common.IAE; import org.apache.iceberg.DataFile; import org.apache.iceberg.Files; import org.apache.iceberg.PartitionSpec; @@ -97,6 +98,7 @@ public void testInputSource() throws IOException null, testCatalog, new LocalInputSourceFactory(), + null, null ); Stream>> splits = inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)); @@ -132,6 +134,7 @@ public void testInputSourceWithEmptySource() throws IOException new IcebergEqualsFilter("id", "0000"), testCatalog, new LocalInputSourceFactory(), + null, null ); Stream>> splits = inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)); @@ -147,6 +150,7 @@ public void testInputSourceWithFilter() throws IOException new IcebergEqualsFilter("id", "123988"), testCatalog, new LocalInputSourceFactory(), + null, null ); Stream>> splits = inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)); @@ -182,7 +186,8 @@ public void testInputSourceReadFromLatestSnapshot() throws IOException null, testCatalog, new LocalInputSourceFactory(), - DateTimes.nowUtc() + DateTimes.nowUtc(), + null ); Stream>> splits = inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)); Assert.assertEquals(1, splits.count()); @@ -201,6 +206,7 @@ public void testCaseInsensitiveFiltering() throws IOException new IcebergEqualsFilter("name", "Foo"), caseInsensitiveCatalog, new LocalInputSourceFactory(), + null, null ); @@ -215,6 +221,119 @@ public void testCaseInsensitiveFiltering() throws IOException Assert.assertEquals(1, localInputSourceList.size()); } + @Test + public void testResidualFilterModeIgnore() throws IOException + { + // Filter on non-partition column with IGNORE mode should succeed + IcebergInputSource inputSource = new IcebergInputSource( + TABLENAME, + NAMESPACE, + new IcebergEqualsFilter("id", "123988"), + testCatalog, + new LocalInputSourceFactory(), + null, + ResidualFilterMode.IGNORE + ); + Stream>> splits = inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)); + Assert.assertEquals(1, splits.count()); + } + + @Test + public void testResidualFilterModeWarn() throws IOException + { + // Filter on non-partition column with WARN mode should succeed (warning logged) + IcebergInputSource inputSource = new IcebergInputSource( + TABLENAME, + NAMESPACE, + new IcebergEqualsFilter("id", "123988"), + testCatalog, + new LocalInputSourceFactory(), + null, + ResidualFilterMode.WARN + ); + Stream>> splits = inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)); + Assert.assertEquals(1, splits.count()); + } + + @Test + public void testResidualFilterModeFail() throws IOException + { + // Filter on non-partition column with FAIL mode should throw exception + IcebergInputSource inputSource = new IcebergInputSource( + TABLENAME, + NAMESPACE, + new IcebergEqualsFilter("id", "123988"), + testCatalog, + new LocalInputSourceFactory(), + null, + ResidualFilterMode.FAIL + ); + IAE exception = Assert.assertThrows( + IAE.class, + () -> inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)) + ); + Assert.assertTrue( + exception.getMessage().contains("residual") + ); + } + + @Test + public void testResidualFilterModeFailWithPartitionedTable() throws IOException + { + // Create a partitioned table and filter on the partition column + TableIdentifier partitionedTableId = TableIdentifier.of(Namespace.of(NAMESPACE), "partitionedTable"); + createAndLoadPartitionedTable(partitionedTableId); + + try { + // Filter on partition column with FAIL mode should succeed (no residual) + IcebergInputSource inputSource = new IcebergInputSource( + "partitionedTable", + NAMESPACE, + new IcebergEqualsFilter("id", "123988"), + testCatalog, + new LocalInputSourceFactory(), + null, + ResidualFilterMode.FAIL + ); + Stream>> splits = inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)); + Assert.assertEquals(1, splits.count()); + } + finally { + dropTableFromCatalog(partitionedTableId); + } + } + + @Test + public void testResidualFilterModeFailWithPartitionedTableNonPartitionColumn() throws IOException + { + // Create a partitioned table and filter on a non-partition column + TableIdentifier partitionedTableId = TableIdentifier.of(Namespace.of(NAMESPACE), "partitionedTable2"); + createAndLoadPartitionedTable(partitionedTableId); + + try { + // Filter on non-partition column with FAIL mode should throw exception + IcebergInputSource inputSource = new IcebergInputSource( + "partitionedTable2", + NAMESPACE, + new IcebergEqualsFilter("name", "Foo"), + testCatalog, + new LocalInputSourceFactory(), + null, + ResidualFilterMode.FAIL + ); + IAE exception = Assert.assertThrows( + IAE.class, + () -> inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)) + ); + Assert.assertTrue( + exception.getMessage().contains("residual") + ); + } + finally { + dropTableFromCatalog(partitionedTableId); + } + } + @After public void tearDown() { @@ -255,6 +374,49 @@ private void createAndLoadTable(TableIdentifier tableIdentifier) throws IOExcept } + private void createAndLoadPartitionedTable(TableIdentifier tableIdentifier) throws IOException + { + // Create a partitioned table with 'id' as the partition column + PartitionSpec partitionSpec = PartitionSpec.builderFor(tableSchema) + .identity("id") + .build(); + Table icebergTable = testCatalog.retrieveCatalog().createTable(tableIdentifier, tableSchema, partitionSpec); + + // Generate an iceberg record and write it to a file + GenericRecord record = GenericRecord.create(tableSchema); + ImmutableList.Builder builder = ImmutableList.builder(); + + builder.add(record.copy(tableData)); + String filepath = icebergTable.location() + "/data/id=123988/" + UUID.randomUUID() + ".parquet"; + OutputFile file = icebergTable.io().newOutputFile(filepath); + + // Create a partition key for the partition spec + org.apache.iceberg.PartitionKey partitionKey = new org.apache.iceberg.PartitionKey(partitionSpec, tableSchema); + partitionKey.partition(record.copy(tableData)); + + DataWriter dataWriter = + Parquet.writeData(file) + .schema(tableSchema) + .createWriterFunc(GenericParquetWriter::buildWriter) + .overwrite() + .withSpec(partitionSpec) + .withPartition(partitionKey) + .build(); + + try { + for (GenericRecord genRecord : builder.build()) { + dataWriter.write(genRecord); + } + } + finally { + dataWriter.close(); + } + DataFile dataFile = dataWriter.toDataFile(); + + // Add the data file to the iceberg table + icebergTable.newAppend().appendFile(dataFile).commit(); + } + private void dropTableFromCatalog(TableIdentifier tableIdentifier) { testCatalog.retrieveCatalog().dropTable(tableIdentifier); diff --git a/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/ResidualFilterModeTest.java b/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/ResidualFilterModeTest.java new file mode 100644 index 000000000000..eb765a8600bb --- /dev/null +++ b/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/ResidualFilterModeTest.java @@ -0,0 +1,73 @@ +/* + * 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.druid.iceberg.input; + +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.Assert; +import org.junit.Test; + +public class ResidualFilterModeTest +{ + @Test + public void testFromString() + { + Assert.assertEquals(ResidualFilterMode.IGNORE, ResidualFilterMode.fromString("ignore")); + Assert.assertEquals(ResidualFilterMode.WARN, ResidualFilterMode.fromString("warn")); + Assert.assertEquals(ResidualFilterMode.FAIL, ResidualFilterMode.fromString("fail")); + + // Test case insensitivity + Assert.assertEquals(ResidualFilterMode.IGNORE, ResidualFilterMode.fromString("IGNORE")); + Assert.assertEquals(ResidualFilterMode.WARN, ResidualFilterMode.fromString("Warn")); + Assert.assertEquals(ResidualFilterMode.FAIL, ResidualFilterMode.fromString("FAIL")); + } + + @Test + public void testFromStringInvalid() + { + Assert.assertThrows( + IllegalArgumentException.class, + () -> ResidualFilterMode.fromString("invalid") + ); + } + + @Test + public void testGetValue() + { + Assert.assertEquals("ignore", ResidualFilterMode.IGNORE.getValue()); + Assert.assertEquals("warn", ResidualFilterMode.WARN.getValue()); + Assert.assertEquals("fail", ResidualFilterMode.FAIL.getValue()); + } + + @Test + public void testJsonSerialization() throws Exception + { + ObjectMapper mapper = new ObjectMapper(); + + // Test serialization + Assert.assertEquals("\"ignore\"", mapper.writeValueAsString(ResidualFilterMode.IGNORE)); + Assert.assertEquals("\"warn\"", mapper.writeValueAsString(ResidualFilterMode.WARN)); + Assert.assertEquals("\"fail\"", mapper.writeValueAsString(ResidualFilterMode.FAIL)); + + // Test deserialization + Assert.assertEquals(ResidualFilterMode.IGNORE, mapper.readValue("\"ignore\"", ResidualFilterMode.class)); + Assert.assertEquals(ResidualFilterMode.WARN, mapper.readValue("\"warn\"", ResidualFilterMode.class)); + Assert.assertEquals(ResidualFilterMode.FAIL, mapper.readValue("\"fail\"", ResidualFilterMode.class)); + } +} diff --git a/website/.spelling b/website/.spelling index 3486f8a8d882..905a4ae8aa08 100644 --- a/website/.spelling +++ b/website/.spelling @@ -224,6 +224,7 @@ ROUTINE_SCHEMA ROUTINE_TYPE Rackspace Redis +residualFilterMode S3 SAS SDK From 93c8f3ec693e1994147368caefb1b4c18ba464bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesse=20Tu=C4=9Flu?= Date: Tue, 27 Jan 2026 19:56:07 -0800 Subject: [PATCH 2/3] Comments --- .../development/extensions-contrib/iceberg.md | 5 +-- docs/ingestion/input-sources.md | 2 +- .../druid/iceberg/input/IcebergCatalog.java | 43 +++++-------------- .../iceberg/input/IcebergInputSource.java | 3 +- .../iceberg/input/ResidualFilterMode.java | 8 +--- .../iceberg/input/IcebergInputSourceTest.java | 32 ++++---------- .../iceberg/input/ResidualFilterModeTest.java | 5 --- 7 files changed, 25 insertions(+), 73 deletions(-) diff --git a/docs/development/extensions-contrib/iceberg.md b/docs/development/extensions-contrib/iceberg.md index ef5f7ac4ed06..c2652cc78588 100644 --- a/docs/development/extensions-contrib/iceberg.md +++ b/docs/development/extensions-contrib/iceberg.md @@ -147,8 +147,7 @@ To control this behavior, you can set the `residualFilterMode` property on the I | Mode | Description | |------|-------------| -| `ignore` | Default. Residual rows are ingested unless filtered by `transformSpec`. | -| `warn` | Log a warning when residual filters are detected, but continue with ingestion. | +| `ignore` | Default. Residual rows are ingested with a warning log unless filtered by `transformSpec`. | | `fail` | Fail the ingestion job when residual filters are detected. Use this to ensure that filters only target partition columns. | Example: @@ -177,4 +176,4 @@ This section lists the known limitations that apply to the Iceberg extension. - This extension does not fully utilize the Iceberg features such as snapshotting or schema evolution. - The Iceberg input source reads every single live file on the Iceberg table up to the latest snapshot, which makes the table scan less performant. It is recommended to use Iceberg filters on partition columns in the ingestion spec in order to limit the number of data files being retrieved. Since, Druid doesn't store the last ingested iceberg snapshot ID, it cannot identify the files created between that snapshot and the latest snapshot on Iceberg. - It does not handle Iceberg [schema evolution](https://iceberg.apache.org/docs/latest/evolution/) yet. In cases where an existing Iceberg table column is deleted and recreated with the same name, ingesting this table into Druid may bring the data for this column before it was deleted. -- The Hive catalog has not been tested on Hadoop 2.x.x and is not guaranteed to work with Hadoop 2. \ No newline at end of file +- The Hive catalog has not been tested on Hadoop 2.x.x and is not guaranteed to work with Hadoop 2. diff --git a/docs/ingestion/input-sources.md b/docs/ingestion/input-sources.md index 552e5ff82900..cf6aecfe8c57 100644 --- a/docs/ingestion/input-sources.md +++ b/docs/ingestion/input-sources.md @@ -1063,7 +1063,7 @@ The following is a sample spec for a S3 warehouse source: |icebergCatalog|The JSON Object used to define the catalog that manages the configured Iceberg table.|yes| |warehouseSource|The JSON Object that defines the native input source for reading the data files from the warehouse.|yes| |snapshotTime|Timestamp in ISO8601 DateTime format that will be used to fetch the most recent snapshot as of this time.|no| -|residualFilterMode|Controls how residual filters are handled when filtering on non-partition columns. When an Iceberg filter targets a non-partition column, files may contain rows that don't match the filter (residual rows). Valid values are: `ignore` (default, ingest all rows), `warn` (log a warning but continue), `fail` (fail the ingestion job). Use `fail` to ensure filters only target partition columns.|no| +|residualFilterMode|Controls how residual filters are handled when the filter results in a residual. This typically happens when an Iceberg filter targets a non-partition column: files may contain rows that don't match the filter (residual rows). Valid values are: `ignore` (default, ingest all rows, and log a warning), and `fail` (fail the ingestion job). Use `fail` to ensure no excess data is being ingested if you don't have filters in transformSpec.|no| ### Catalog Object diff --git a/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergCatalog.java b/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergCatalog.java index 6f8aafd1a1d6..d4bfe4f53ba9 100644 --- a/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergCatalog.java +++ b/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergCatalog.java @@ -21,6 +21,7 @@ import com.fasterxml.jackson.annotation.JsonTypeInfo; import org.apache.druid.data.input.InputFormat; +import org.apache.druid.error.DruidException; import org.apache.druid.iceberg.filter.IcebergFilter; import org.apache.druid.java.util.common.IAE; import org.apache.druid.java.util.common.RE; @@ -36,7 +37,6 @@ import org.apache.iceberg.io.CloseableIterable; import org.joda.time.DateTime; -import javax.annotation.Nullable; import java.util.ArrayList; import java.util.List; @@ -59,25 +59,6 @@ public boolean isCaseSensitive() return true; } - /** - * Extract the iceberg data files upto the latest snapshot associated with the table - * - * @param tableNamespace The catalog namespace under which the table is defined - * @param tableName The iceberg table name - * @param icebergFilter The iceberg filter that needs to be applied before reading the files - * @param snapshotTime Datetime that will be used to fetch the most recent snapshot as of this time - * @return a list of data file paths - */ - public List extractSnapshotDataFiles( - String tableNamespace, - String tableName, - IcebergFilter icebergFilter, - DateTime snapshotTime - ) - { - return extractSnapshotDataFiles(tableNamespace, tableName, icebergFilter, snapshotTime, null); - } - /** * Extract the iceberg data files upto the latest snapshot associated with the table * @@ -94,7 +75,7 @@ public List extractSnapshotDataFiles( String tableName, IcebergFilter icebergFilter, DateTime snapshotTime, - @Nullable ResidualFilterMode residualFilterMode + ResidualFilterMode residualFilterMode ) { Catalog catalog = retrieveCatalog(); @@ -102,7 +83,6 @@ public List extractSnapshotDataFiles( String tableIdentifier = tableNamespace + "." + tableName; List dataFilePaths = new ArrayList<>(); - ResidualFilterMode effectiveMode = residualFilterMode != null ? residualFilterMode : ResidualFilterMode.IGNORE; ClassLoader currCtxClassloader = Thread.currentThread().getContextClassLoader(); try { @@ -132,8 +112,8 @@ public List extractSnapshotDataFiles( for (FileScanTask task : tasks) { dataFilePaths.add(task.file().path().toString()); - // Check for residual filters if mode is not IGNORE - if (effectiveMode != ResidualFilterMode.IGNORE && detectedResidual == null) { + // Check for residual filters + if (detectedResidual == null) { Expression residual = task.residual(); if (residual != null && !residual.equals(Expressions.alwaysTrue())) { detectedResidual = residual; @@ -151,21 +131,18 @@ public List extractSnapshotDataFiles( detectedResidual ); - if (effectiveMode == ResidualFilterMode.FAIL) { - throw new IAE( - "%s To allow residual rows, set residualFilterMode to 'ignore' or 'warn', " - + "or add a corresponding filter in transformSpec.", - message - ); - } else if (effectiveMode == ResidualFilterMode.WARN) { - log.warn(message); + if (residualFilterMode == ResidualFilterMode.FAIL) { + throw DruidException.forPersona(DruidException.Persona.DEVELOPER) + .ofCategory(DruidException.Category.RUNTIME_FAILURE) + .build(message); } + log.warn(message); } long duration = System.currentTimeMillis() - start; log.info("Data file scan and fetch took [%d ms] time for [%d] paths", duration, dataFilePaths.size()); } - catch (IAE e) { + catch (DruidException e) { throw e; } catch (Exception e) { diff --git a/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergInputSource.java b/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergInputSource.java index 8bbf762f797b..dc2b84d22971 100644 --- a/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergInputSource.java +++ b/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergInputSource.java @@ -22,6 +22,7 @@ import com.fasterxml.jackson.annotation.JsonCreator; import com.fasterxml.jackson.annotation.JsonProperty; import com.google.common.base.Preconditions; +import org.apache.druid.common.config.Configs; import org.apache.druid.data.input.InputFormat; import org.apache.druid.data.input.InputRow; import org.apache.druid.data.input.InputRowListPlusRawValues; @@ -96,7 +97,7 @@ public IcebergInputSource( this.icebergFilter = icebergFilter; this.warehouseSource = Preconditions.checkNotNull(warehouseSource, "warehouseSource cannot be null"); this.snapshotTime = snapshotTime; - this.residualFilterMode = residualFilterMode; + this.residualFilterMode = Configs.valueOrDefault(residualFilterMode, ResidualFilterMode.IGNORE); } @Override diff --git a/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/ResidualFilterMode.java b/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/ResidualFilterMode.java index 58e2bedcc704..dd3a56bdb422 100644 --- a/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/ResidualFilterMode.java +++ b/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/ResidualFilterMode.java @@ -37,12 +37,6 @@ public enum ResidualFilterMode */ IGNORE("ignore"), - /** - * Log a warning when residual filters are detected, but continue with ingestion. - * Useful for identifying potential data quality issues without failing the job. - */ - WARN("warn"), - /** * Fail the ingestion job when residual filters are detected. * Use this mode to ensure that only partition-column filters are used, @@ -71,7 +65,7 @@ public static ResidualFilterMode fromString(String value) } } throw new IllegalArgumentException( - "Unknown residualFilterMode: " + value + ". Valid values are: ignore, warn, fail" + "Unknown residualFilterMode: " + value + ". Valid values are: ignore, fail" ); } } diff --git a/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/IcebergInputSourceTest.java b/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/IcebergInputSourceTest.java index e52efd4bb4c4..ed0e4d6de27d 100644 --- a/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/IcebergInputSourceTest.java +++ b/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/IcebergInputSourceTest.java @@ -25,12 +25,13 @@ import org.apache.druid.data.input.MaxSizeSplitHintSpec; import org.apache.druid.data.input.impl.LocalInputSource; import org.apache.druid.data.input.impl.LocalInputSourceFactory; +import org.apache.druid.error.DruidException; import org.apache.druid.iceberg.filter.IcebergEqualsFilter; import org.apache.druid.java.util.common.DateTimes; import org.apache.druid.java.util.common.FileUtils; -import org.apache.druid.java.util.common.IAE; import org.apache.iceberg.DataFile; import org.apache.iceberg.Files; +import org.apache.iceberg.PartitionKey; import org.apache.iceberg.PartitionSpec; import org.apache.iceberg.Schema; import org.apache.iceberg.Table; @@ -238,23 +239,6 @@ public void testResidualFilterModeIgnore() throws IOException Assert.assertEquals(1, splits.count()); } - @Test - public void testResidualFilterModeWarn() throws IOException - { - // Filter on non-partition column with WARN mode should succeed (warning logged) - IcebergInputSource inputSource = new IcebergInputSource( - TABLENAME, - NAMESPACE, - new IcebergEqualsFilter("id", "123988"), - testCatalog, - new LocalInputSourceFactory(), - null, - ResidualFilterMode.WARN - ); - Stream>> splits = inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)); - Assert.assertEquals(1, splits.count()); - } - @Test public void testResidualFilterModeFail() throws IOException { @@ -268,11 +252,12 @@ public void testResidualFilterModeFail() throws IOException null, ResidualFilterMode.FAIL ); - IAE exception = Assert.assertThrows( - IAE.class, + DruidException exception = Assert.assertThrows( + DruidException.class, () -> inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)) ); Assert.assertTrue( + "Expect residual error to be thrown", exception.getMessage().contains("residual") ); } @@ -321,11 +306,12 @@ public void testResidualFilterModeFailWithPartitionedTableNonPartitionColumn() t null, ResidualFilterMode.FAIL ); - IAE exception = Assert.assertThrows( - IAE.class, + DruidException exception = Assert.assertThrows( + DruidException.class, () -> inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)) ); Assert.assertTrue( + "Expect residual error to be thrown", exception.getMessage().contains("residual") ); } @@ -391,7 +377,7 @@ private void createAndLoadPartitionedTable(TableIdentifier tableIdentifier) thro OutputFile file = icebergTable.io().newOutputFile(filepath); // Create a partition key for the partition spec - org.apache.iceberg.PartitionKey partitionKey = new org.apache.iceberg.PartitionKey(partitionSpec, tableSchema); + PartitionKey partitionKey = new PartitionKey(partitionSpec, tableSchema); partitionKey.partition(record.copy(tableData)); DataWriter dataWriter = diff --git a/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/ResidualFilterModeTest.java b/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/ResidualFilterModeTest.java index eb765a8600bb..f7a9891f7acc 100644 --- a/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/ResidualFilterModeTest.java +++ b/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/ResidualFilterModeTest.java @@ -29,12 +29,10 @@ public class ResidualFilterModeTest public void testFromString() { Assert.assertEquals(ResidualFilterMode.IGNORE, ResidualFilterMode.fromString("ignore")); - Assert.assertEquals(ResidualFilterMode.WARN, ResidualFilterMode.fromString("warn")); Assert.assertEquals(ResidualFilterMode.FAIL, ResidualFilterMode.fromString("fail")); // Test case insensitivity Assert.assertEquals(ResidualFilterMode.IGNORE, ResidualFilterMode.fromString("IGNORE")); - Assert.assertEquals(ResidualFilterMode.WARN, ResidualFilterMode.fromString("Warn")); Assert.assertEquals(ResidualFilterMode.FAIL, ResidualFilterMode.fromString("FAIL")); } @@ -51,7 +49,6 @@ public void testFromStringInvalid() public void testGetValue() { Assert.assertEquals("ignore", ResidualFilterMode.IGNORE.getValue()); - Assert.assertEquals("warn", ResidualFilterMode.WARN.getValue()); Assert.assertEquals("fail", ResidualFilterMode.FAIL.getValue()); } @@ -62,12 +59,10 @@ public void testJsonSerialization() throws Exception // Test serialization Assert.assertEquals("\"ignore\"", mapper.writeValueAsString(ResidualFilterMode.IGNORE)); - Assert.assertEquals("\"warn\"", mapper.writeValueAsString(ResidualFilterMode.WARN)); Assert.assertEquals("\"fail\"", mapper.writeValueAsString(ResidualFilterMode.FAIL)); // Test deserialization Assert.assertEquals(ResidualFilterMode.IGNORE, mapper.readValue("\"ignore\"", ResidualFilterMode.class)); - Assert.assertEquals(ResidualFilterMode.WARN, mapper.readValue("\"warn\"", ResidualFilterMode.class)); Assert.assertEquals(ResidualFilterMode.FAIL, mapper.readValue("\"fail\"", ResidualFilterMode.class)); } } From 4dbbe0dd9df42a8496d04cd9ab48c4deaae4b39e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesse=20Tu=C4=9Flu?= Date: Wed, 28 Jan 2026 23:01:47 -0800 Subject: [PATCH 3/3] Final --- .../iceberg/input/IcebergInputSource.java | 1 - .../iceberg/input/IcebergInputSourceTest.java | 81 +++++++++---------- 2 files changed, 37 insertions(+), 45 deletions(-) diff --git a/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergInputSource.java b/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergInputSource.java index dc2b84d22971..ccbb10af14dc 100644 --- a/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergInputSource.java +++ b/extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergInputSource.java @@ -183,7 +183,6 @@ public DateTime getSnapshotTime() return snapshotTime; } - @Nullable @JsonProperty public ResidualFilterMode getResidualFilterMode() { diff --git a/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/IcebergInputSourceTest.java b/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/IcebergInputSourceTest.java index ed0e4d6de27d..b42b3eaa0301 100644 --- a/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/IcebergInputSourceTest.java +++ b/extensions-contrib/druid-iceberg-extensions/src/test/java/org/apache/druid/iceberg/input/IcebergInputSourceTest.java @@ -265,59 +265,52 @@ public void testResidualFilterModeFail() throws IOException @Test public void testResidualFilterModeFailWithPartitionedTable() throws IOException { + // Cleanup default table first + tearDown(); // Create a partitioned table and filter on the partition column - TableIdentifier partitionedTableId = TableIdentifier.of(Namespace.of(NAMESPACE), "partitionedTable"); - createAndLoadPartitionedTable(partitionedTableId); + tableIdentifier = TableIdentifier.of(Namespace.of(NAMESPACE), "partitionedTable"); + createAndLoadPartitionedTable(tableIdentifier); - try { - // Filter on partition column with FAIL mode should succeed (no residual) - IcebergInputSource inputSource = new IcebergInputSource( - "partitionedTable", - NAMESPACE, - new IcebergEqualsFilter("id", "123988"), - testCatalog, - new LocalInputSourceFactory(), - null, - ResidualFilterMode.FAIL - ); - Stream>> splits = inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)); - Assert.assertEquals(1, splits.count()); - } - finally { - dropTableFromCatalog(partitionedTableId); - } + IcebergInputSource inputSource = new IcebergInputSource( + "partitionedTable", + NAMESPACE, + new IcebergEqualsFilter("id", "123988"), + testCatalog, + new LocalInputSourceFactory(), + null, + ResidualFilterMode.FAIL + ); + Stream>> splits = inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)); + Assert.assertEquals(1, splits.count()); } @Test public void testResidualFilterModeFailWithPartitionedTableNonPartitionColumn() throws IOException { + // Cleanup default table first + tearDown(); // Create a partitioned table and filter on a non-partition column - TableIdentifier partitionedTableId = TableIdentifier.of(Namespace.of(NAMESPACE), "partitionedTable2"); - createAndLoadPartitionedTable(partitionedTableId); + tableIdentifier = TableIdentifier.of(Namespace.of(NAMESPACE), "partitionedTable2"); + createAndLoadPartitionedTable(tableIdentifier); - try { - // Filter on non-partition column with FAIL mode should throw exception - IcebergInputSource inputSource = new IcebergInputSource( - "partitionedTable2", - NAMESPACE, - new IcebergEqualsFilter("name", "Foo"), - testCatalog, - new LocalInputSourceFactory(), - null, - ResidualFilterMode.FAIL - ); - DruidException exception = Assert.assertThrows( - DruidException.class, - () -> inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)) - ); - Assert.assertTrue( - "Expect residual error to be thrown", - exception.getMessage().contains("residual") - ); - } - finally { - dropTableFromCatalog(partitionedTableId); - } + // Filter on non-partition column with FAIL mode should throw exception + IcebergInputSource inputSource = new IcebergInputSource( + "partitionedTable2", + NAMESPACE, + new IcebergEqualsFilter("name", "Foo"), + testCatalog, + new LocalInputSourceFactory(), + null, + ResidualFilterMode.FAIL + ); + DruidException exception = Assert.assertThrows( + DruidException.class, + () -> inputSource.createSplits(null, new MaxSizeSplitHintSpec(null, null)) + ); + Assert.assertTrue( + "Expect residual error to be thrown", + exception.getMessage().contains("residual") + ); } @After