abhishekrb19 commented on code in PR #18953:
URL: https://github.com/apache/druid/pull/18953#discussion_r2734619570
##########
extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergCatalog.java:
##########
@@ -100,12 +127,47 @@ public List<String> extractSnapshotDataFiles(
tableScan = tableScan.caseSensitive(isCaseSensitive());
CloseableIterable<FileScanTask> 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;
+ }
Review Comment:
Is this catch block needed? It can just fall through to the generic block
below.
##########
extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergCatalog.java:
##########
@@ -70,12 +74,35 @@ public List<String> 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<String> 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<String> dataFilePaths = new ArrayList<>();
+ ResidualFilterMode effectiveMode = residualFilterMode != null ?
residualFilterMode : ResidualFilterMode.IGNORE;
Review Comment:
This initialization when the value is null can be done in the
`IcebergInputSource` constructor and then we can just pass a non-null mode
everywhere.
##########
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. |
Review Comment:
I feel having a separate mode for `warn` is unnecessary. Can we just fold a
warning log in both the `ignore` and `fail` modes?
##########
extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergCatalog.java:
##########
@@ -100,12 +127,47 @@ public List<String> extractSnapshotDataFiles(
tableScan = tableScan.caseSensitive(isCaseSensitive());
CloseableIterable<FileScanTask> 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);
+ }
+ }
Review Comment:
IMO it’d be better to always log a warning when a residual filter is
detected (regardless of mode), not sure anyone would want just `warn`.
What do you think about simplifying this to two just two modes: `ignore`
(default) and `fail`? (we cadn still keep it as an enum for extensibility)
##########
extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergCatalog.java:
##########
@@ -100,12 +127,47 @@ public List<String> extractSnapshotDataFiles(
tableScan = tableScan.caseSensitive(isCaseSensitive());
CloseableIterable<FileScanTask> 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(
Review Comment:
nit: throw `DruidException`
##########
extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergCatalog.java:
##########
@@ -100,12 +127,47 @@ public List<String> extractSnapshotDataFiles(
tableScan = tableScan.caseSensitive(isCaseSensitive());
CloseableIterable<FileScanTask> 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())) {
Review Comment:
Is the residual expression from task guaranteed to be null for filters on
partition columns? (i.e., confirming there would be no false negatives)
##########
extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/IcebergCatalog.java:
##########
@@ -70,12 +74,35 @@ public List<String> extractSnapshotDataFiles(
IcebergFilter icebergFilter,
DateTime snapshotTime
)
+ {
+ return extractSnapshotDataFiles(tableNamespace, tableName, icebergFilter,
snapshotTime, null);
+ }
Review Comment:
Appears to be unused, can be removed?
##########
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"
+ );
Review Comment:
`DruidException` for better UX
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
