# Tips for Filtering Data in Typesense

In this article, we'll talk about how to filter data in Typesense using various filtering options:

Basic Filtering
Available Operators
- Non-exact Operator for String Types
- Array Operators
Prefix Filtering
Boolean Operations
- Operator Precedence
Filtering Array Types
Escaping special characters
Filtering Geopoints
Filtering Nested Object Fields
Filtering Joined Collections

# Basic Filtering

Typesense allows you to filter your search results based on the values of specific fields. You can use the filter_by parameter to specify a custom filter string.

{
  "q": "*",
  "filter_by": "country:=USA"
  // ...
}

Note that the base format for a filter is field: <operator> <value>. Every filter field must have a : after it.

✅ Correct: price:>=100
❌ Incorrect: price>=100

# Available Operators

Operator	Description	Available types	Example
`=`	Equal to	`string`, `int32`, `int64`, `float`, `bool`	`country:=USA`
`:`	Partially equal to	`string`	`country:New`
`>`	Greater than	`int32`, `int64`, `float`	`price:>100`
`<`	Less than	`int32`, `int64`, `float`	`price:<100`
`!=`	Not equal to	`string`, `int32`, `int64`, `float`, `bool`	`status:!=inactive`
`<=`	Less than or equal to	`int32`, `int64`, `float`	`price:<=100`
`>=`	Greater than or equal to	`int32`, `int64`, `float`	`price:>=100`
`[]`	Is one of	`string`, `int32`, `int64`, `float`, `bool`	`country:[USA, UK, Canada]`
`!=[]`	Is not any of	`string`, `int32`, `int64`, `float`, `bool`	`country:!=[USA, UK, Canada]`
`[..]`	Range	`int32`, `int64`, `float`	`price:[100..200]`

# Non-exact Operator for String Types

The non-exact operator (:) allows for word-level partial matching on string fields. It's useful when you want to find results that contain a specific word:

location:New

This filter will match any country name containing "New", such as:

✅ New Zealand
✅ New Caledonia
✅ Papua New Guinea

But it will NOT match a location like:

❌ Newfoundland

Since New is not a standalone word in the string Newfoundland. If you need this type of matching, see Prefix Filtering below.

Performance Tip

The non-exact operator (:) doesn't take token position into account, so it is usually faster than the exact := operator.

# Array Operators

Array operators allow you to filter numeric fields (int32, int64, or float) based on specific conditions:

price:[<20, >100]

Will result in items with a price of:

Under 20 OR
Over 100

Commas act as OR operators, allowing flexible condition combinations.

# The Range Operator

The range operator can be used with multiple array elements, creating a logical OR between ranges or values:

price:[100...200, 15...50, 800]

This matches items with prices:

Between 100 and 200
Between 15 and 50
Exactly 800

# Prefix Filtering

This feature is only available as of Typesense Server v27.0

You can use an asterisk (*) to denote a prefix in a string field filter. This allows you to filter for fields that begin with the provided prefix:

name:Jo*

This filter will return results for people whose names include a word starting with Jo, such as:

Jonathan Jacobs
John McKinley
Michael Johansson

When you use the prefix in conjunction with the exact-match operator :=, the results will only include entries where the prefix matches the beginning of the name:

name:=Jo*

This will match:

✅ Jonathan Jacobs
✅ John McKinley

But not:

❌ Michael Johansson

# Boolean Operations

You can combine multiple filters using logical operators.

Operator	Description	Example
`&&`	Logical AND	`country:=USA && city:=New York`
`\|\|`	Logical OR	`country:=USA \|\| country:=Canada`

When using logical operators, you can use parentheses to group your filters.

For example, to filter for products that are either made in the USA or Canada, and are located in New York, you can use the following filter:

(country:=USA || country:=Canada) && city:=New York

This will return products that are either made in the USA or Canada, and are located in New York. When using logical operators, you can use parentheses to group your filters. For example, to filter for products that are either made in the USA or Canada, and are located in New York, you can use the following filter:

(country:=USA || country:=Canada) && city:=New York

# Operator Precedence

In boolean operations, the AND operator (&&) has higher precedence than the OR operator (||). This means that AND operations are performed before OR operations, unless parentheses are used to specify a different order.

For example:

country:=USA || country:=Canada && city:=New York

Would be interpreted as:

country:=USA || (country:=Canada && city:=New York)

To change the order of operations, use parentheses:

(country:=USA || country:=Canada) && city:=New York

# Filtering Array Types

Any of the array types can be used for filtering, matching any of their values.

For example, if there's a field called department_prices that's a int32[] and there's a document with department_prices: [32, 60, 80], then the filter of:

department_prices:<80

Would in turn return this document.

Subsequently, you can also use array operators:

deparment_prices:[20...80]

# Escaping special characters

If you want to filter for a value that includes special characters, such as a comma (,), you can use backticks around your filter value:

country:=`United States, Minor Outlying Islands`

# Filtering Geopoints

You can filter on geopoint fields by searching either within a specific radius, or by specifying a bounding box.

For example, to filter for results within a 10 kilometer radius of a specific location, you can use the following filter:

location:(48.90615915923891, 2.3435897727061175, 10 km),

TIP

You can use the same filter for miles by changing the distance unit to mi.

Or, to filter for results within a bounding box, you can use the following filter:

location:(48.8662, 2.3255, 48.8581, 2.3209, 48.8561, 2.3448, 48.8641, 2.3469)

For information on filtering geopoint fields to search within a specific area, please refer to our documentation on Geosearch.

# Filtering Nested Object Fields

You can also filter on nested object fields by using the dot (.) notation to refer to nested fields.

For example, if you have a customer nested object inside your collection schema that looks like this:

{
  "customer": {
    "name": "John Doe",
    "city": "Alpha",
    "dob": 964924500
  }
}

You can filter by the customer's name like:

customer.name:=John Doe

# Filtering Joined Collections

When filtering for joined collection, you use the $CollectionName(<filter>) syntax.

For example, if you have a products collection with a category field and a categories collection with a name field, you can filter for products that are in the Electronics category like this:

$categories(name:=Electronics)

Inside of the joined collection, you can use any filter string that you would use directly for that collection, including &&, || and ! boolean operators. For example, to filter on products in the Electronics category AND the Mobile category, but NOT in the Disposable category, and under $100, you can use the following filter:

$categories(name:=Electronics && name:=Mobile && name:!=Disposable) && price:<100

Filtering on joined fields is supported at any level of nesting. For a detailed explanation and examples, please refer to our documentation on nested joins.

WARNING

Joins must be configured in the schema prior to using them in a filter.

See JOINs for more details.

← Tips for Locale-Specific Search Running in Production →