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.

Cyclic foreign-key dependencies

A schema where two or more tables reference each other in a cycle (e.g. A has a FK to B, and B has a FK back to A) has no valid topological order, so DatabaseSequenceFilter rejects it with CyclicTablesDependencyException by default. Enable FEATURE_SKIP_CYCLE_CHECK to opt out of that check; the cycle is then treated as a single unit for ordering purposes, so a table outside the cycle is still correctly sorted relative to it (a table with its own FK to a cyclic table still sorts after the whole cycle, not just after whichever cyclic member happened to be placed first) — only the relative order of the tables making up the cycle itself is left unresolved, falling back to their original input order. It becomes the caller’s responsibility to make the cycle insertable — for example by leaving the cyclic FK column(s) null on the first pass and updating them afterwards, or by relying on database-side deferred constraint checking.

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);