Problem

When using the Entity Search API with a filter like contains(attributes.Address.City, "Jersey City"), no results are returned. However, when the search string has no spaces (e.g., contains(attributes.Address.City, "JerseyCity")), results are returned correctly. Additionally, using the equals filter instead of contains returns results as expected.

API Used:

/entities?filter=(contains(attributes.Address.City, "Jersey City"))&select=uri&max=5

Solution

The issue occurs because the contains filter is not designed to handle spaces within the search string. Let’s break down the behavior of the equals and contains filters to understand the solution:

1. Understanding the Filters:

• equals: This filter checks for an exact match between the attribute value and the search string. It is case-insensitive and will match the exact value (including spaces).

  Example:

  equals(attributes.Address.City, "Jersey City")
  

• contains: The contains filter matches substrings within the attribute value. However, it doesn't handle spaces in the search string properly, because it treats the space as part of the word. The filter is designed to match individual words or partial values.

  • For example, contains(attributes.Address.City, "Jersey City") will not work correctly because "Jersey City" contains a space, and the filter is expecting each word as a separate value.
  • contains works best when used for values like "JerseyCity", where there are no spaces.

  Supported Wildcards for contains:

  • *: Matches any character sequence, including an empty string.
  • ?: Matches any single character (case-insensitive).

  Example:

  contains(attributes.Address.City, "Jersey*")
  

  This would match any value starting with "Jersey" (e.g., "JerseyCity", "Jerseyville").

2. Solution:

To solve the issue, you can use the equals filter if you need an exact match, including spaces. If you must use the contains filter, ensure that the search string does not contain spaces, or consider using a wildcard search.

Updated Example using equals filter:

/entities?filter=(equals(attributes.Address.City, "Jersey City"))&select=uri&max=5

Example using contains with wildcard:

/entities?filter=(contains(attributes.Address.City, "Jersey*"))&select=uri&max=5

3. When to Use Each Filter:

• equals: Use this filter when you need to match the exact value of an attribute, including spaces.
• contains: Use this filter when you're looking for partial matches, but avoid using spaces in the search string. You can use wildcards to expand the search to more flexible criteria.

4. Conclusion:

The issue arises because the contains filter is not designed to handle spaces in the search string. If you need an exact match, use the equals filter. If you need partial matching, ensure that the search string does not contain spaces, or use a wildcard search.

Additional Resources:

For more details on filtering entities using the Entity Search API, refer to the following documentation:

• Filtering Entities- Reltio Documentation