Filter Conditions
Filter conditions decide which investments a screen returns. They are the most important and most complex part of a request, so they have their own section. This page explains how filter conditions are built and how to choose between the types. The pages in this section cover each type in detail.
Anatomy of a Filter Condition
A filter condition applies to one data point. It names the data point and gives a value, a list of values, or a comparison.
{
"<dataPoint>": "<value, list of values, or comparison>"
}
The following examples show the three forms.
{ "basicReference.baseCurrency": "USD" }
{ "basicReference.baseCurrency": ["USD", "CAD", "GBP"] }
{ "basicReference.inceptionDate": { "gt": "2020-01-01", "lt": "2024-01-01" } }
Filter conditions can be combined into larger conditions with and, or and not, and the combinations can be nested.
Where Filter Conditions Apply
Filter conditions are used in two parts of a request, and the syntax is the same in both.
| Property | Use |
|---|---|
scope | Sets the starting universe. For managed investments, it is defined with the basicReference.countryAvailableForSale data point. See Screen Investments. |
query | Narrows the scoped universe. |
Types of Filter Conditions
| Type | What It Does | Page |
|---|---|---|
| Equality | Matches an exact value, or any value in a list. | Equality and Text Filters |
| Text | Searches text by substring or by approximate match. | Equality and Text Filters |
| Comparison | Compares numbers and dates with gt, gte, lt and lte. | Comparison Filters |
| Compound | Combines conditions with and, or and not. | Compound Filters |
Choose the Right Filter
The data type of a data point determines which filters you can use. Check the metadata for the data point, as described in Explore Data Points.
| Data Type | Filters You Can Use |
|---|---|
boolean | Equals. |
date | Equals, in, and range comparisons. |
number | Equals, in, and range comparisons. |
string | Equals and in. Some data points also support fuzzy search. |
The operators property of each data point lists the operators it supports. Use only those operators on that data point.
Value Formats
| Value | Format | Example |
|---|---|---|
| Text | A JSON string. | "USD" |
| Number | A JSON number, with no quotation marks. | 4, 25.555 |
| Boolean | true or false, with no quotation marks. | true |
| Date | A string in yyyy-MM-dd format. | "2024-03-31" |
| List | A JSON array of values of the same type. | ["USD", "CAD"] |
Combine Filters
Use a compound filter whenever a query needs more than one condition. It makes the logic explicit, so that the query means the same thing to everyone who reads it.
"query": {
"and": [
{ "basicReference.baseCurrency": ["USD", "CAD"] },
{ "basicReference.inceptionDate": { "gt": "2010-01-01" } }
]
}
Quick Reference
| To Do This | Use This Syntax |
|---|---|
| Match one value | { "<dataPoint>": "<value>" } |
| Match any value in a list | { "<dataPoint>": ["<value1>", "<value2>"] } |
| Search text for a substring | { "<dataPoint>": { "contains": "<text>" } } |
| Search text approximately | { "<dataPoint>": { "value": "<text>", "fuzzy": true } } |
| Compare numbers or dates | { "<dataPoint>": { "gt": <value>, "lt": <value> } } |
| Require all conditions | { "and": [ <condition>, <condition> ] } |
| Require at least one condition | { "or": [ <condition>, <condition> ] } |
| Exclude conditions | { "not": [ <condition>, <condition> ] } |