Most people never need this. The point-and-click filter builder can answer almost any question, see finding records with Filters. CQL is an optional shortcut for power users who would rather type a filter than click it. Nothing here unlocks new abilities, it is the same filters, written as text.
CQL (the CoolFocus Query Language) is a plain way to write down a filter. When you are in a filter, you can switch between the visual builder and CQL using the mode toggle, they are two views of the same thing. Type CQL and the builder updates, build visually and you can read the CQL. CoolFocus checks your CQL as you type and underlines anything it does not understand.
It reads close to English. A filter for donors named Alice is simply:
firstName = 'Alice'
These match the examples in the visual-builder articles:
amount > 250
email is not empty
lastGiftDate more than 90 days ago
createdDate this month
firstName = 'John' AND lastName = 'Smith'
Use AND when every part must be true, OR when any part will do, and parentheses to group them:
(amount > 100 AND createdDate this year) OR source = 'online'
The same "do they have any, how many, what is the total" questions from Filtering by Related Records look like this:
contributions() has at least one contribution
none visits() has no visits
contributions(amount > 250) has a gift over $250
contributions().count() > 5 more than five gifts
contributions().sum(amount) > 1000 total giving over $1,000
Text: =, !=, contains, does not contain, starts with, ends with, is empty, is not empty
Numbers: =, !=, >, >=, <, <=, is empty, is not empty
Dates, exact: on '2024-01-15', after '2024-01-01', before '2025-12-31'
Dates, relative: exactly 30 days ago, more than 90 days ago, less than 7 days ago
Dates, calendar: this month, last month, this quarter, last quarter, this year, last year, plus year is 2024 and month is 'January'
Yes/No: is true, is false
Related records: name() (has any), none name() (has none), and totals .count(), .sum(field), .min(field), .max(field)
A few rules of thumb: put text and dates in single quotes ('Alice', '2024-01-01'), leave numbers bare (250), and field names are the ones you see in the filter builder's field list.
Use these fields on the Clients list:
pointsBalance >= 100
pointsEarnedLast90Days >= 10
CoolFocus tells you what it did not understand, an unknown field name, a missing value, or an unclosed parenthesis. Fix the underlined part, or switch back to the visual builder and build that piece by clicking. You can always save the result as a segment.