Filtering And Sorting

Some of our endpoints support specifying filter or sorting criteria within the request. These options can reduce the result set size or return data in a more suitable order.

​

Filtering

Zixflow supports two distinct formats for filtering: shorthand and verbose.

• Shorthand Format: Ideal for quick equality checks.
• Verbose Format: Allows for more complex conditions and logical operators.

​

Shorthand Filters

Shorthand filters are straightforward and concise. Here’s an example:

Example: People named “John Doe” with the email “john@doe.com”

POST /api/v1/collection-records/{collectionId}/query
Content-Type: application/json

{
  "filter": {
    "name": "John Doe",
    "emails": "john@doe.com"
  }
}

​

Verbose Filters

Verbose filters enable more complex queries, such as combining multiple conditions or querying specific properties of an attribute. All shorthand filters can also be expressed in verbose syntax.

Example: Using verbose syntax for the same filter

POST /api/v1/collection-records/{collectionId}/query
Content-Type: application/json

{
  "filter": {
    "$and": [
      {
        "name": {
            "$eq": "John Doe"
        }
      },
      {
        "emails": {
            "$eq": "john@doe.com"
        }
      }
    ]
  }
}

Here:

• A logical operator ($and) is used to combine conditions.
• Specific properties on the attributes (name and emails) are queried.

Each attribute type has specific properties available, so the set of possible filters varies by attribute type.

​

Comparison Operators

There are fourteen comparison operators in total. Below are some examples:

​

$eq - Equality

Checks for equality and is supported by every attribute type. If using shorthand syntax, $eq is usually implied but can also be specified explicitly.

Deals with an exact name

{
  "name": {
    "$eq": "John Doe"
  }
}

​

$not_empty

Filters results based on whether there is any value defined.

Companies which have at least one domain

{
  "name": {
    "$not_empty": true
  }
}

​

$in

Checks if the record or entry has a value that is part of a set.

Records where record_id is one of many values

{
  "filter": {
    "name": {
      "$in": ["John Doe", "John Doe 2"]
    }
  }
}

​

String Comparisons

For string-like properties or attributes, the following operators are available:

​

$contains

Matches parts of a string, case-sensitively.

Name contains John

{
  "name": {
    "$contains": "John"
  }
}

​

$not_contains

Do not matches parts of a string, case-sensitively.

Name does not contains John

{
  "name": {
    "$not_contains": "John"
  }
}

​

$starts_with & $ends_with

Matches the beginning or the end of a string, respectively.

People with phone numbers starting +1

{
  "phoneNumbers": {
    "$starts_with": "+1"
  }
}

Phone number starts with +1 and ends with 0909

{
  "phoneNumbers": {
    "$starts_with": "+1",
    "$ends_with": "0909"
  }
}

​

Numeric or Date Comparisons

For sortable properties like numbers or dates, use the following operators:

• $lt: Less than
• $lte: Less than or equal
• $gte: Greater than or equal
• $gt: Greater than

People with 4 or more rating

{
  "rating": {
    "$gte": 4
  }
}

people created in 2024

{
  "createdAt": {
    "$gte": "2024-01-01",
    "$lte": "2024-12-31"
  }
}

​

Logical Operators

Combine multiple conditions using $and, $or, and $not.

​

$and Operator

Specifies that all conditions must match. If using shorthand syntax with multiple attributes, $and is implied.

People with name John Doe and email is john@doe.com

{
  "$and": [{ "name": "John Doe" }, { "emails": "john@doe.com" }]
}

​

$or Operator

Specifies that at least one condition must match.

List all peoples with name John Doe or Alice Doe

{
  "$or": [{ "name": "John Doe" }, { "name": "Alice Doe" }]
}

​

$not Operator

Matches all documents that do not meet the condition.

People not with name John

{
  "name": { "$not": "John" }
}

​

Sorting

Sorting allows us to retrieve results in a specific order based on attribute values. Each sort operation must define a direction.

Sorting can be performed by an attribute apiKeyName. For instance, we can sort People first by their name and then by their email address:

{
  "sort": [
    { "direction": "asc", "attribute": "name" },
    { "direction": "desc", "attribute": "emails" }
  ]
}