sfmc.guide
Engagement Next
⌘K

ExecuteFilter

Executes a data-extension-based data filter and returns the matching rows as an unordered rowset. Runtime-proven on a live Marketing Cloud Engagement CloudPage — including what an empty filter returns and its case-insensitive matching.

Runtime verified Test scripts included

Syntax

ExecuteFilter(dataFilterExternalId)  →  rowset
1 argument — exactly

Parameters

Name Type Required Description
dataFilterExternalId string Yes External key of a data filter that is based on a data extension

Example

%%[
  VAR @rows
  SET @rows = ExecuteFilter("AMP_VERIFY_FILTER")
]%%
Matches: %%=v(RowCount(@rows))=%%

With a filter FirstName Equals "Alice" over a data extension holding two Alice rows and one Bob row, renders Matches: 2.

Iterate the returned rowset with Row and Field:

%%[
  VAR @rows, @i, @r
  SET @rows = ExecuteFilter("AMP_VERIFY_FILTER")
  FOR @i = 1 TO RowCount(@rows) DO
    SET @r = Row(@rows, @i)
]%%
%%=v(Field(@r, "Id"))=%%: %%=v(Field(@r, "FirstName"))=%%
%%[
  NEXT @i
]%%

Emits F1: Alice and F3: Alice — the Bob row is excluded.

Return value

rowset — the rows that satisfy the data filter, unordered. Pass it to RowCount, Row and Field. A filter that matches nothing returns an empty rowset (RowCount 0), not a null or an error — the page does not abort.

Behaviour

Only data-extension-based filters. The filter referenced by dataFilterExternalId must be built on a data extension; profile-attribute filters are not supported. Use this on CloudPages, landing pages, microsites, and MobileConnect SMS.

The filter value comparison is case-insensitive. A row whose FirstName was alice matched a filter searching for Alice, alongside the exact-case rows.

Returns an unordered rowset. Row order is not guaranteed; use ExecuteFilterOrderedRows when you need sorting or a row cap.

Show test script
%%[
  VAR @b
  SET @b = RequestParameter("b")

  IF @b == "zzz" THEN
    OutputLine(Concat("CTRL=[alive]"))
  ENDIF

  IF @b == "seed" THEN
    DeleteData("AMP_VERIFY_SCRATCH", "Id", "F1")
    DeleteData("AMP_VERIFY_SCRATCH", "Id", "F2")
    DeleteData("AMP_VERIFY_SCRATCH", "Id", "F3")
    InsertData("AMP_VERIFY_SCRATCH", "Id", "F1", "FirstName", "Alice", "Score", 10)
    InsertData("AMP_VERIFY_SCRATCH", "Id", "F2", "FirstName", "Bob", "Score", 20)
    InsertData("AMP_VERIFY_SCRATCH", "Id", "F3", "FirstName", "Alice", "Score", 30)
    OutputLine(Concat("seeded"))
  ENDIF

  IF @b == "run" THEN
    VAR @rs, @cnt, @i, @r
    SET @rs = ExecuteFilter("AMP_VERIFY_FILTER")
    SET @cnt = RowCount(@rs)
    OutputLine(Concat("rowCount=[", @cnt, "]"))
    FOR @i = 1 TO @cnt DO
      SET @r = Row(@rs, @i)
      OutputLine(Concat("  ", Field(@r, "Id"), " FirstName=[", Field(@r, "FirstName"), "] Score=[", Field(@r, "Score"), "]"))
    NEXT @i
  ENDIF
]%%

Availability

Platform Available
Marketing Cloud Engagement Yes
Marketing Cloud Next No

See also