Filters

dbUnit can filter which tables, columns, and rows participate in an operation or comparison — this page consolidates all three.

Table Filters

Table filters (org.dbunit.dataset.filter) decide which tables from a larger dataset are exposed, and in what order, via FilteredDataSet. Every strategy implements ITableFilter (itself extending the simpler ITableFilterSimple, just accept(String tableName)).

IncludeTableFilter / ExcludeTableFilter

IncludeTableFilter exposes only tables matching a name pattern, without changing table order; ExcludeTableFilter does the opposite, hiding matching tables. Both support wildcards:

ITableFilter filter = new IncludeTableFilter(new String[] {"ACCOUNT*"});
IDataSet filteredDataSet = new FilteredDataSet(filter, dataSet);

SequenceTableFilter

Imposes an explicit table order — see Decorators.

DatabaseSequenceFilter

DatabaseSequenceFilter automatically determines table order using foreign/exported keys information. This strategy is vendor independent and should work with any JDBC driver that implements the DatabaseMetaData.getExportedKeys() method.

Support simple multi-level dependency like this:

   A
  / \
 B   C
    / \
   D   E

IDatabaseConnection conn = new DatabaseConnection(jdbcConn);

ITableFilter filter = new DatabaseSequenceFilter(conn);
IDataSet dataset = new FilteredDataSet(filter, conn.createDataSet());

FlatXmlDataSet.write(dataset, new File(fileName));

org.dbunit.database.search.TablesDependencyHelper is the static convenience API backing this filter’s traversal — getDependentTables(), getDependsOnTables(), and their transitive getAllDependentTables() variants, plus getDataset()/getAllDataset() to go straight from a set of root tables to a dependency-ordered IDataSet. Reach for it directly when you need the table list or a ready-made dataset rather than a filter to wrap around an existing one.

PrimaryKeyFilter

PrimaryKeyFilter (org.dbunit.database) restricts related tables' rows to those reachable, via foreign key, from a starting set of primary key values — e.g. "only the orders belonging to these 3 customers, and only those customers' addresses." It does not support composite/multi-column primary keys.

Column Filters

IColumnFilter / DefaultColumnFilter

IColumnFilter decides, per table and column, whether a column is included. The FAQ example below excludes primary-key and timestamp columns commonly generated by the code under test rather than supplied by the test:

DefaultColumnFilter columnFilter = new DefaultColumnFilter();
columnFilter.excludeColumn("PK*");
columnFilter.excludeColumn("*TIME");

FilteredTableMetaData metaData =
        new FilteredTableMetaData(originalTable.getTableMetaData(), columnFilter);
ITable filteredTable = new CompositeTable(metaData, originalTable);

DefaultColumnFilter supports wildcards and offers includedColumnsTable()/ excludedColumnsTable() convenience methods to build a filtered ITable in one call:

ITable filteredTable = DefaultColumnFilter.excludedColumnsTable(originalTable,
        new String[] {"PK*", "*TIME"});

See Ignoring Some Columns in Comparison for this same mechanism used specifically to align an actual table’s columns with a narrower expected table.

GeneratedColumnFilter

GeneratedColumnFilter (3.0.0+) is an IColumnFilter that excludes database-generated columns (Column.getGeneratedColumn()), for databases that expose that metadata. Apply it via TableDecoratorDataSet:

dataset = new TableDecoratorDataSet(dataset,
        table -> new ColumnFilterTable(table, new GeneratedColumnFilter()));

Row Filters

IRowFilter queries column values via an IRowValueProvider and returns true to accept the row or false to filter it out. Wrap an ITable in RowFilterTable to apply it:

IRowFilter rowFilter = rowValueProvider -> {
    Object columnValue = rowValueProvider.getColumnValue("COLUMN1");
    return "customerAbroad".equalsIgnoreCase((String) columnValue);
};
ITable filteredTable = new RowFilterTable(iTable, rowFilter);