Skip to content

Filters and Searching

Filters are the power behind Objects allowing you to search for and return specific pieces of data within your Object Collections.

Introduction to Filters #

Imagine you have a large box filled with various tools, and you’re looking for just one screwdriver. Filters are the instructions you give to quickly bring you that screwdriver instead of manually searching through every tool in the box. By setting filters, you specify the criteria your data must meet, such as a name, date, or number. For example, if you want to see all transactions from a particular client, you just set a filter for that client’s name under the transaction records. It’s an efficient way to access the exact data you need without unnecessary complexity.

The SPACEtag® Objects API provides you many filter operations, such as equal to, greater than and less than.

GET https://api.spacetagcloud.net/objects/v1/action?object=contacts.person&first_name=Hanna

In the above example, this will return all of the Objects from the contacts.person collection where the first_name equals “Hanna”. This is the most basic example of filter, since all URL query-string parameters in the request must be equals by default.

But what about if we wanted to return all of the Objects where the last_name field wasn’t equal to “Smith”, i.e. last_name <> “Smith” ? Well, using standard GET query-string params, it would be a bit complicated as you can’t just specify last_name<>Smith . So instead, in the Objects API we use an operator attached to the field (sometimes called a mnemonic) in the query-string. For example: last_name.ne=Smith .

So the following Objects API request would return Objects where the first_name equals “Hanna”, but the last_name does not equal “Smith”.

GET https://api.spacetagcloud.net/objects/v1/action?object=contacts.person&first_name=Hanna&last_name.ne=Smith

Filter Operators #

These are the filter operators available with Objects API:

Filter NameLogical OperatorField OperatorExample
Equal To=None or .eqlast_name=Smith
Not Equal To<>.nelast_name.ne=Smith
Greater Than>.gtmy_number.gt=100
Greater Than or Equal To>=.gtemy_number.gte=100
Less Than<.ltmy_number.lt=100
Less Than or Equal To=<.ltemy_number.lte=100
Is LikeLIKE <pattern>.likefirst_name.like=Alex%
Is Not LikeNOT LIKE <pattern>.notlikefirst_name.notlike=Alex%
Is NullNULL.nullfirst_name.null=1
Is Not NullNOT NULL.notnullfirst_name.notnull=1
Is Empty= ”.emptyfirst_name.empty=1
Is Not Empty<> ”.notemptyfirst_name.notempty=1

Understanding the LIKE Filter #

Think of the LIKE filter in SPACEtag® Objects as a way to find data that matches a specific pattern. It’s like using a search function in your favourite word processor or email program, where you can look for words or phrases that contain certain letters or patterns.

How LIKE Filters Work: #

When you use the LIKE filter, you can include special characters to specify the pattern:

  • The percent sign % acts like a wildcard that can represent any sequence of characters, long or short.
  • The underscore _ represents exactly one character.
Examples: #
  1. Finding Names Starting with ‘Jo’
    • Filter: first_name.like=Jo%
    • Meaning: This filter will find all entries where the name starts with ‘Jo’. So, it will match ‘John’, ‘Joanna’, ‘Jonathan’, etc.
  2. Finding Names with ‘an’ Anywhere
    • Filter: first_name.like=%an%
    • Meaning: This filter will find any name that has ‘an’ in it, regardless of where it appears. It matches ‘Susan’, ‘Danny’, ‘Brianna’, etc.

Using NOT LIKE: #

The NOT LIKE filter works just the opposite way. It helps you find data that does not match a specific pattern.

  • Example:
    • Filter: first_name.notlike=Al%
    • Meaning: This filter will exclude any names that start with ‘Al’, such as ‘Alan’, ‘Albert’, etc.

By using LIKE and NOT LIKE, you can make your data search as broad or as specific as you need. It’s a powerful tool that helps you manage and navigate your data more effectively.

LIKE Filters Are Inefficient #

Using the LIKE operator for pattern matching, especially with a leading wildcard (e.g., %name), can be inefficient on large datasets because it generally cannot utilise indexes effectively. Indexes help the database quickly locate data, but a wildcard at the beginning of a pattern forces a complete scan of all records, significantly slowing down searches as data volume grows.

For better performance, especially with large datasets, it’s advisable to structure queries to avoid leading wildcards if possible. This is important for the user experience for your apps, and where your account is metered on API execution time.

Understanding NULL Values and Empty Strings #

When working with data in Spacetag Objects, it’s important to understand the difference between NULL values and empty strings, as they represent different concepts:

  • NULL Value: A NULL value in a database represents the absence of a value. It means that the field is left blank during record creation, indicating that the value is unknown or not applicable. NULL is not the same as zero, nor is it the same as an empty string.
  • Empty String: An empty string is a string with no characters. Unlike NULL, it is a definite value, indicating that the field was explicitly set to “nothing.” It’s like saying the answer is specifically an empty response.

Using Filters for NULL and Empty Strings #

Spacetag Objects provides specific filters to help you query data more effectively based on these distinctions:

  • .null Filter: This filter allows you to find records where a specified field is NULL. For example, first_name.null will find all records where the name field has no value (i.e., it is unknown).
  • .notnull Filter: Opposite of the .null filter, this finds records where the field is not NULL. Using first_name.notnull will return all records where the name field has some value, whether it’s an empty string or a filled-out name.
  • .empty Filter: This filter helps you find records where a field is an empty string. For example, description.empty will show records where the description is explicitly set to an empty string.
  • .notempty Filter: This filter finds records where the field is not empty—it contains one or more characters. So, description.notempty will return records with a non-empty description.

Practical Application #

Using these filters allows you to precisely tailor your queries to ensure that your application behaves as expected, especially in scenarios where distinguishing between “unknown” (NULL) and “empty” (empty string) can impact functionality or business logic.

In SPACEtag® Objects most fields in a new Object are NULL until you set it with some data. There are some exceptions to this, where they may be empty strings or other values by default, but these are identified in the Object data structure documentation.