Filter Based on Nested Objects Fields

Introduction

You can filter your query results by specifying conditions of nested fields of an object.

For example:

query {
  articles(where: { author: { name: { _eq: "Sam Jones" } } }) {
    id
    title
  }
}

Applicable Fields for Nested Field Comparisons

Nested field comparisons can be made in the GraphQL API if:

• The field's type is an Object Type
• The field is a Relationship

Filtering by Object Type Fields

To filter results based on a field within an object type, apply a condition to the nested field.

Example:

In this query, profile is an Object Type field, and we filter users based on the condition that their profile.age is greater than 30.

Filtering by Relationship Fields

You can filter results based on conditions applied to the fields of the target model in a relationship. The relationship can be either an object or array type.

Example: Filter by Array relationship fields.

In this query, books is an Array relationship, and we filter authors who have written a book titled "GraphQL Basics".

Example: Filter by Object relationship fields.

In this query, author is an object relationship field, and we filter books where the author.name is "Alice Johnson".

Data Connector Capability

For relationship filtering to be processed efficiently, the data connector must support the relation_comparisons relationships capability. This allows the query engine to push down relationship comparisons directly to the data connector, ensuring that filtering based on relationships is handled at the data source level, improving performance and reducing unnecessary data transfer.

However, if the relation_comparisons capability is absent, the query engine will handle the relationship comparisons at its own layer. In this case, the query engine fetches the relevant mapping field values of the relationship and constructs the necessary comparison expressions. While this ensures that the query can still execute, it may result in reduced efficiency and slower responses, as more data needs to be transferred to the query engine for evaluation. See Performance of Relationship Comparisons for more details.

Compatibility Date

To utilize relationship comparisons without the relation_comparisons capability, you must update the compatibility date. For detailed instructions, please refer to the Compatibility Config.

Remote Relationships

A relationship between two entities from different data connectors is known as a remote relationship. This type of relationship allows you to integrate and query data across multiple sources seamlessly. Filtering with a predicate from a model in a remote data source using remote relationships enhances query flexibility, enabling precise data retrieval directly on the server. This eliminates the need for client-side filtering, which not only simplifies your code but also reduces network data transfer, leading to improved application performance.

For example:

query UsersCompletedOrders {
  users(where: { orders: { status: { _eq: "complete" } } }) {
    id
    name
    orders {
      id
      status
    }
  }
}

This query retrieves a list of users along with their completed orders. Here, users and orders stored in separate data sources.

Limitations

• Only remote relationships where the targets are models are supported in comparisons, with support for remote relationships targeting commands coming soon.

• Remote relationships defined across subgraphs are currently not supported.

• Fields involved in relationship mapping must be backed by data connector columns that have support for the equal comparison operator.

Understanding Predicate Resolution

The predicate of a remote relationship is resolved independently of the data connector's relation_comparisons capability. When a remote relationship is used in a comparison, the engine retrieves the relevant data from the remote model and constructs the necessary comparison expressions to filter the results, similar to how local relationships are resolved without the relation_comparisons capability.

Consequently, the performance of remote predicates can vary significantly based on the efficiency of the underlying data sources and the complexity of the relationships being queried. For more details, see Performance of Relationship Comparisons.