Filtering is available as an optional parameter on numerous LUSID API endpoints.
- Filtering entity fields
- Filtering entity identifiers
- Filtering custom entity fields
- Filtering properties
- Filtering SHKs
- Filtering nested fields
- Error reporting
- Searching fields
The filtering functionality allows you to specify a string defining the subset of results that are returned by the API call. Filters are specified using the LUSID filter syntax:
Filtering in LUSID is:
- Does not return null values or values that are not set (except when filtering using not exists)
Supported operators are as follows:
|Operator||Description||Examples of valid expressions|
Returns a record if the value exactly matches the specified value.
displayname eq 'MyPortfolio'
isDerived eq True
Returns a record if the value doesn't match the specified value.
displayname neq 'MyPortfolio'
isDerived neq True
Returns a record if the value is greater than the specified value.
created gt 2019-01-01
created gt 2019-01-15T10:00:00
unit gt 10
greater than or equal to
Returns a record if the value is greater than or equal to the specified value.
created gte 2019-01-15
created gte 2017-02-15T18:00:00
unit gte 10
Returns a record if the value is less than the specified value.
created lt 2017-02-01
created lt 2017-02-15T18:00:00
unit lt 10
Returns a record if the value starts with the specified value.
displayName startswith ‘Mypo’
Returns a record if the value matches any of the specified values.
displayName in 'MyPortfolio', 'MyOtherPortfolio'
Returns a record if the value is not in any of the specified values.
displayName not in 'My Portfolio', 'MyOtherPortfolio'
Returns a record if the value is set.
Returns a record if the value is not set.
properties.Portfolio/scope/code not exists
Logical AND operator that connects two or more filter statements and returns a record if all resolve to true.
isDerived eq True and created lt 2017-03-15
Logical OR operator that connects two or more filter statements and returns a record if one resolves to true.
isDerived eq True or displayName eq 'MyPortfolio'
Note you can combine the and and or operators; and is evaluated before or following standard Boolean operator precedence. If you want to change the precedence, use parentheses. (So the order of evaluation is: parentheses,
displayName eq 'MyPortfolio' or (isDerived eq True and created lt 2017-03-15)
The filter string can be preceded by a not operator that negates the results.
not displayName in 'MyPortfolio', 'MyOtherPortfolio'
The operators you can use depend on the data type of the field you want to filter on:
|Data type of field||Example field||Supported operators|
|eq, neq, startswith, in, not|
|eq, neq, gt, gte, lt, lte|
|Not supported||Not supported|
|in, not in, eq, neq|
|properties/identifiers||Depending on type of value|
Array / List
|Not supported||Not supported|
Values are case-insensitive and wildcard characters are not supported.
Some LUSID entities such as instruments support filtering on identifiers. Instrument identifiers can be filtered by providing the identifier key for the identifiers collection, for example:
This filter returns all records where the identifier type Currency is set to CCY_USD.
If you create your own custom entities, you can filter on data field values using the fields collection, for example:
This filter returns all the custom entities of a particular type located in the EC4 postal code area.
Some LUSID API endpoints support decorating properties onto entities. The syntax to filter properties can be either:
The property key is a three-part identifier used to uniquely identify properties. The structure is <domain>/<scope>/<code>. The key is case sensitive. For example:
For multi-value properties, the filter syntax reflects the fact you may want to match
all of a property's values. For example:
properties[mydomain/myscope/mycode] any (~ startswith 're')matches both
["red", "green", "blue"]and
["red", "reed", "read"]
properties[mydomain/myscope/mycode] all (~ startswith 're')matches just
["red", "reed", "read"]
Note: For multi-value properties, using the
eq operator in the standard way (for example
properties[mydomain/myscope/mycode] eq 'red') acts as a shortcut for
properties[mydomain/myscope/mycode] any (~ eq 'red').
You can filter on sub-holding keys (special transaction properties registered with a portfolio for the purpose of segmenting holdings into groups) using the
SubHoldingKeys collection, for example:
SubHoldingKeys[Transaction/Demo/Strategy] eq 'Income'
The LUSID API supports nested filtering. Fields not present at the root level can be accessed using the '.' syntax. Consider the following response schema for the ListPortfolio API endpoint below:
For example, to filter on a portfolio's scope:
Note the following:
- Multi-value properties and derived properties are currently not filterable in LUSID
- Filtering on DateTimeCutLabel is not supported
- Filtering on data types such as Arrays and Lists (denoted by [...]) is not supported
- Filtering is still case sensitive for instrument identifiers, instrument properties and portfolio properties on List* API endpoints.
The LUSID API returns user-friendly messages that can be used to determine the cause of any errors. The table below summarises the error messages, including descriptions and potential resolutions:
|Error Name||Code||Error Description||Potential Resolution|
|DataFilterApplicationFailure||181||There was a problem with the syntax of the provided filter. The problematic token was: 'equal'|
Check the syntax supplied in the string is correct one. Look at the examples above.
In this case the operator 'equal' is not supported, the correct operator is eq.
|DataFilterApplicationFailure||181||One or more failures occurred. Cannot apply 'operator' to a 'instrument' and a 'string'||Operator used in the filter syntax is not supported. Please use the operators as described in the operator section above.|
|DataFilterApplicationFailure||181||One or more failures occurred. The field 'fieldName' referred to in the supplied filter is not valid or is not available for filtering||Field being used in the filtering is not currently supported. Check if the fieldName used is the correct one.|
|FilterExecutionTimeout||415||Timed out when attempting to filter records.||LUSID allows a maximum time of 30 seconds for any filter query to run. Try improving the filter query by adding additional parameters or please send us an email on email@example.com to discuss your use case.|
|PropertyNotDefined||121||Property not defined||Make sure that the key used for property filtering is the right one and uses the property filtering syntax as described above. Please note that the property key is case sensitive.|
The search parameter is supported only on Search* API endpoints and can be used to make wildcard searches across all fields for a given resource. It applies across the whole record and utilizes features such as ElasticSearch tokenisation. Results returned from search can be filtered further to return only the relevant records.
For example, the following matches any records where the text string starts with Global:
This will match any records where Global is mentioned as a word token in the string. Tokens for Search API endpoints are delimited by looking at the space and dash literals in a given string: