Sync Filters

ObjectBox Sync uses filters to enable partial syncing so that each user gets only the data they need.

Unless you want to replicate all data to all clients, you want to use sync filters. For each user, sync filters select the data that is synchronized to the user (client). This enables "user-specific sync".

Sync filters are generally available since ObjectBox 5, i.e. Sync Server version 2025-09-16 or later. Older ObjectBox clients must be updated to ObjectBox 5.0 or later when using sync filters.

Configuration

Sync filters are defined as part of the Sync Server configuration (via the JSON file only). For each type of your data model, you can configure a sync filter expression (aka "rule").

It's generally a good idea to keep this configuration file in a version control system (git) and with sync filters even more so.

Add filter expressions to the JSON configuration

The JSON configuration file is typically named sync-server-config.json. For general details and other configuration options, please check the configuration page.

All sync filters are defined inside a syncFilters JSON object. Filters are defined per data type (from your ObjectBox data model) with the type names as JSON keys. The value is a string and contains the filter expression.

The JSON configuration is best illustrated by an example:

{
  "syncFilters": {
    "Category": "name == 'public'",
    "Person": "age >= 18",
    "Customer": "email == $auth.email"
  }
}

This configuration contains three sync filters for the types Category, Person, and Customer. The filter expression for Category references the property name (part of the Category type) and selects only categories with the name "public" for synchronization. Similarly, the filter expression for Person selects only persons who are at least 18 years old.

The Customer filter filters on the email property and uses a variable called $auth.email as its operand. Typically, sync filters use variables as these allow for user-specific sync. Variables start with a $ character. In this case, it refers to an authentication variable, which represents the Sync user's email address.

Typically, sync filters use the equals condition (==). In this case, index the underlying property as this is the most efficient approach. See the performance section for details.

Filter expressions

Filter expressions provide a compact and flexible way to query and filter data in ObjectBox Sync. They use a simple syntax that is similar to many programming languages and SQL.

A filter expression consists of conditions that can be combined using logical operators. The basic structure of a condition has three parts:

propertyName operator value

Simple examples:

name == "John"
age > 25

Property names

The first part of a filter condition is the "property name", which refers to a property (aka member/field) in your data objects (aka type defined in your ObjectBox data model). For example, consider a Person type defined in your ObjectBox data model that has a name and age property. Now, when defining a filter expression for the Person type, you can refer to name and age as property names.

Operators

Filter expressions can use the following operators for all value types:

Operator	Description	Example
==	Equals	name == "Alice"
!=	Not equals	status != "inactive"
>	Greater than	age > 18
<	Less than	price < 100.0
>=	Greater than or equal	score >= 80
<=	Less than or equal	quantity <= 50
IN	Matches any value in a set	status IN $client.statuses

For string values, the following operators are additionally available:

Operator	Description	Example
==~	Case-insensitive equals	name ==~ "JOHN"
^=	Starts with	email ^= "admin"
*=	Contains	description *= "urgent"
$=	Ends with	filename $= ".pdf"
IN~	Case-insensitive IN	category IN~ $client.categories

The IN operator

The IN operator allows matching a property against multiple values provided by a variable. It supports string and integer (32 and 64 bit) properties. The actual values for the variable are provided (by the client or JWT) as a comma-separated string.

For example, assume a client wants to sync objects where the category property matches "books", "music", or "games". The filter expression would be:

category IN $client.categories

Like this, clients have to provide the variable categories as the comma-separated string "books,music,games" without whitespace.

For integer properties, the same approach applies:

priorityLevel IN $client.levels

Here, the client provides the variable levels with values like "1,3,5" (matching levels 1, 3, and 5).

Escaping commas and backslashes

If your string values contain commas or backslashes, you need to escape them:

• Use \, for a literal comma within a value

• Use \\ for a literal backslash within a value

For example, to match values "a,b" and "c\d", the client would provide:

"a\,b,c\\d"

This is parsed as two values: "a,b" and "c\d".

Case-insensitive IN with IN~

For string properties, you can use IN~ for case-insensitive matching. This works the same as IN, but the comparison ignores case differences.

category IN~ $client.categories

With this filter, if the client provides "books,music" (case does not matter), it will match objects where category is "Books", "BOOKS", "books", "Music", etc.

Note: IN~ is only available for string properties. For integer types, use the regular IN operator.

Performance: prefer the case-sensitive IN operator over IN~ as the case-sensitive variant can use indexes.

IN-like filters for literals

The IN operator only works with variables, so you cannot use it with fixed literals. However, you can use the OR operator (see Logical operators) to create a similar effect with a set of fixed literals:

category == 'books' OR category == 'music' OR category == 'games'

Values (operands)

The third and last part of a filter condition is the value or operand. It defines the value to which the property is compared. If it's a match, i.e., the condition is considered "true", then the object is included in the sync.

Operands can either be literals (fixed values) or variables (dynamic values). Supported literal types are strings, integers, and floating-point values. The literal type must match the property type, e.g., the name property can only have string values. If there's a mismatch, a configuration error will occur when the Sync Server parses the sync filters.

Literal values

Strings can be enclosed in either double quotes (") or single quotes ('):

name == "John Doe"
title == 'Software Engineer'

Escape sequences are supported using backslash (\):

message == "He said \"Hello\""
path == 'C:\\Users\\John'

Literal numbers can be integers and floating-point values:

age == 25
price >= 19.99

Variable Operands

Typically, sync filter operands are "variables", which are resolved when a client logs in using client-specific values. Thus, variables enable user-specific data sync. They are discussed in detail in the Variables section below.

Variables

In filter conditions, variables are referenced using a dollar sign ($) followed by the variable name:

email == $auth.email

If the variable name includes special characters, you use the braces syntax, e.g. ${variable}:

myProperty == ${auth.https://example.com/custom-claim}

Note that variable names do not support escape sequences, e.g. the backslash has no special meaning.

Stick to "reasonable" variable names. If possible, use only letters, numbers, and underscores, e.g. avoid special characters and spaces. One exce While the Sync Server may not enforce rules yet, this may become required in the future.

Variable types

While variables are provided as strings, they are parsed internally into a specific type, e.g. string, integer, floating-point or s set of a values of a specific type. Thus, if you use one variable multiple times, ensure that the variable type is consistent. For example, a variable used to match against a string property, cannot also be used to match against an integer property. This rarely makes sense, but if you need to do this, use multiple variables; one for each type.

Default Values

Variables can have default values that are used when the variable is not provided by the client or JWT. The syntax uses ?? followed by the default value inside the braces syntax:

${variable ?? defaultValue}

Examples:

team == ${client.team ?? "green"}
priority >= ${client.minPriority ?? 0}

In the first example, if the client does not provide a team variable, objects with team == "green" are synced. In the second example, if minPriority is not provided, all objects with priority >= 0 are synced.

Default values follow the same syntax as literal values:

• Strings must be quoted: ${client.name ?? "anonymous"} or ${client.name ?? 'anonymous'}

• Numbers are unquoted: ${client.level ?? 42} or ${client.price ?? 19.99}

An empty string ("" or '') is a valid default value. For example, ${client.tag ?? ""} uses an empty string if tag is not provided.

When a variable is used multiple times in an expression, each usage can have its own default value:

minAge <= ${client.age ?? 0} AND maxAge >= ${client.age ?? 999}

If a variable has no default value and is not provided by the client or JWT, the login will fail with an error. Use default values for optional variables to avoid this.

Auth variables

"Auth" variables are defined by ObjectBox Sync Server authenticators when a client logs in. At this point, only the JWT authenticator provides variables. It is used when Sync clients provide JWTs to authenticate; see JWT authentication for details. Once the JWT has been validated, the Sync Server sets the JWT's claims as sync variables using the "auth." prefix. For example, JWTs typically have an "email" claim, which is then exposed as a variable named "auth.email". In sync filters, you can refer to this as $auth.email.

Custom claims

JWTs are basically encoded and signed JSON objects. While some JWT properties are (more or less) standardized like the "aud" and "iss" claims, JWT allows you to add additional properties to the JSON. These "custom claims" can be very useful for sync filters as they offer a standard way to provide client-specific data securely to the Sync Server.

Let's say you want to group users into teams. Check with your JWT provider how to add custom claims to your JWTs. Also, at the JWT provider side, assign users to teams. Then, you can use a filter expression like team == $auth.team to enable group-based sync.

Nested custom claims

Your JWT provider may only support custom claims that are nested JSON objects. You can access these values via the dot notation.

For example, let's assume your decoded JWT looks like this:

{
  "email": "[email protected]",
  "user_properties": {
    "team": {
      "v": "blue"
    }
  },
  "other_properties": "..."
}

Then, you can access the team value via $auth.user_properties.team.v, e.g. a complete sync filter expression could look like this: team == $auth.user_properties.team.v.

Client variables

ObjectBox Sync Clients can also define variables for sync filters. Before logging in, the client API allows to add variables using key/value pairs (strings). For API details, see Sync Client. These are sent to the Sync Server with the login request and can be used in sync filter expressions using the client. prefix.

For example, assume we want to group data into teams and allow clients can freely choose a team. Let's say a client adds a filter variable "team" with value "red" before logging in. A filter expression team == $client.team would then match only objects where the team property is "red" for this client.

Property type conversion

While you provide the filter variable values as a string, you can use it also for non-string properties. For example, if a filter condition refery to an int property "year" and the client provided value is "2025" (string), it's automatically parsed to the int value 2025. The following (property) typesare supported:

• Strings (no conversion needed)

• Integers, e.g. "42" (all integer property types from 8 to 64 bits are supported)

• Dates (timestamp in milliseconds/nanoseconds since the epoch)

• Floating point numbers, e.g. "3.14159"

• Boolean ("true" vs. all other strings)

When (not) to use client variables

Client variables are by definition provided by clients; the server has no way to verify the values. They are fine for preferences-like data, which clients can freely choose from.

Avoid client variables for security- or business-critical matters, especially if values can be looked up or are guessable. Given a certain effort, if this information is "leaked" or guessed, a malicious client could use these values to access data it should not have access to. This can be mitigated by using none-guessable values like long enough random values, e.g. UUIDv4, which only the client can know.

Combining Filter Conditions

Logical Operators

In filter expressions, you can use the logical operators to combine conditions.

AND combines two conditions where both must be true. AND has higher precedence than OR (AND is evaluated first).

age >= 18 AND status == "active"

OR combines two conditions where at least one must be true. OR has lower precedence than AND.

category == "urgent" OR priority > 5

Precedence and Grouping

Without parentheses, AND has higher precedence than OR.

Thus, the following two expressions are equivalent, e.g. requires the "premium" status or a combination of minimum age and score:

status == "premium" OR age >= 21 AND score >= 100 

status == "premium" OR (age >= 21 AND score >= 100) 

Use parentheses to control the order of evaluation; e.g. to (always) require a minimum score and either premium status or a minimum age:

(status == "premium" OR age >= 21) AND score >= 100 

Complex Examples

Multiple conditions with different operators:

name ^= "John" AND age > 25 AND (status == "active" OR status == "pending")

String matching with case-insensitive comparison:

email $= "@company.com" AND department ==~ "ENGINEERING"

Numeric ranges and string patterns:

(price >= 10.0 AND price <= 100.0) AND description *= "sale"

Performance

Sync filters are used to create queries, e.g. when clients connect for the first time for a "full sync". Thus, what makes a query performant also applies to sync filters.

Especially for equality conditions (==), it is highly recommended to use indexes for the properties used in the filter expressions (unless you only have a few objects of a type, e.g. less than a hundred). This is done in the standard ObjectBox way, i.e. using the index annotation (@Index for most languages) on the property in the data model.

Caveats

Sync filters have some caveats to be aware of (future versions may or may not address them):

• Do not change values of properties used in Sync filters. If you rely on this, delete the object with the old value instead and insert a new object with the new value. For example, consider a property team that is used in a sync filter expression. One client changes the team from "blue" to "green". The server now correctly syncs the change to "team green" clients. However, it is not yet deleted from "team blue" clients that have synced before. Thus, use the delete and insert approach instead: the server will correctly remove the object from "team blue" clients.