Filtering System

Relevant source files

The following files were used as context for generating this wiki page:

• src/builder_context/filter_types_map.rs
• src/inputs/active_enum_filter_input.rs
• src/lib.rs
• CHANGELOG.md
• README.md
• examples/sqlite/tests/query_tests.rs

The Filtering System in Seaography is a dynamic component that bridges GraphQL input queries with SeaORM database filters. It allows users to perform complex data retrieval by applying various operators (such as equality, comparison, and pattern matching) directly to entity columns and related entities.

This system is designed to be highly extensible, supporting basic scalar types, complex enumerations, and even database-specific features like Postgres arrays. It maps SeaORM column types to specific GraphQL filter input objects, enabling type-safe filtering within the GraphQL schema.

Sources: README.md:20-22, src/lib.rs:58-60, src/builder_context/filter_types_map.rs:113-118

Core Architecture and Components

The filtering architecture relies on a mapping layer that converts SeaORM metadata into GraphQL input types. This is primarily handled by the FilterTypesMapHelper, which defines how each database column type translates to a corresponding filter input object.

Filtering Flow

The following diagram illustrates the flow from a GraphQL request containing filters to the generation of a SeaORM Condition.

The system uses the ObjectAccessor from async-graphql to inspect the filter arguments provided in a query and iteratively builds a SeaORM Condition object.

Sources: src/builder_context/filter_types_map.rs:326-335, src/inputs/active_enum_filter_input.rs:83-87

Filter Types and Mappings

Seaography maps standard SeaORM column types to specialized filter input structures. These mappings ensure that operators relevant to the data type (e.g., contains for strings but not for booleans) are available in the GraphQL schema.

Default Type Mappings

SeaORM Column Type	Filter Type	Filter Input Object Name
String, Text	String	StringFilterInput
Integer, BigInt, SmallInt	Integer	IntegerFilterInput
Float, Double	Float	FloatFilterInput
Boolean	Boolean	BooleanFilterInput
Char, Decimal, DateTime	Text	TextFilterInput
Enum	Enumeration	[EnumName]EnumFilterInput
Array	Array	[Type]ArrayFilterInput

Sources: src/builder_context/filter_types_map.rs:125-167, src/inputs/active_enum_filter_input.rs:20-25

Filter Operations

Each filter type supports a subset of operations. The FilterOperation enum defines the available logic:

• Equality/Comparison: eq, ne, gt, gte, lt, lte.
• Set Logic: is_in, is_not_in.
• Null Checks: is_null, is_not_null.
• String Matching: contains, starts_with, ends_with, like, ilike (case-insensitive).
• Range: between, not_between.
• Arrays: array_contains, array_contained, array_overlap.

Sources: src/builder_context/filter_types_map.rs:46-77, src/builder_context/filter_types_map.rs:647-670, CHANGELOG.md:162-163

Enumeration Filtering

Enumerations are handled via the ActiveEnumFilterInputBuilder. This builder generates a specific filter input for each ActiveEnum defined in the SeaORM entities.

The system extracts the variants of the enumeration to ensure that the GraphQL input values match the database-level enum values.

Sources: src/inputs/active_enum_filter_input.rs:30-65, src/inputs/active_enum_filter_input.rs:95-108

Advanced Filtering Features

Filtering by Related Entities

Version 2.0.0 introduced the ability to filter entities based on the properties of their relations using the having argument. This allows for complex joins and nested conditions.

Example Query:

{
  country(having: { city: { city: { eq: "London" } } }) {
    nodes {
      country
    }
  }
}

Sources: CHANGELOG.md:10-25, examples/sqlite/tests/query_tests.rs:777-785

Logical Operators (OR/AND)

Filters can be combined using logical operators. The system supports wrapping multiple filter conditions in an or array to create disjunctive queries.

Sources: examples/sqlite/tests/query_tests.rs:818-825

Custom Filter Overwrites

The FilterTypesMapConfig allows developers to overwrite the default filter behavior for specific columns. This includes mapping a column to a custom GraphQL type or providing a manual FnFilterCondition to handle complex logic not supported by the default system.

Sources: src/builder_context/filter_types_map.rs:12-20

Configuration Options

The behavior of the filtering system can be adjusted through the BuilderContext and specific configuration flags.

Option	Type	Description
combine_is_null_is_not_null	bool	If true, is_null: false replaces the is_not_null operator.
use_ilike	bool	Enables the use of the ilike operator for case-insensitive matching.
overwrites	BTreeMap	Custom mappings for specific entity columns to filter types.

Sources: src/builder_context/filter_types_map.rs:567-585, CHANGELOG.md:144-148

Summary

The Seaography Filtering System provides a robust mechanism for exposing database-level filtering capabilities through a GraphQL API. By automatically mapping SeaORM types to GraphQL inputs and providing hooks for customization, it enables both rapid development and the flexibility required for complex business requirements. Key strengths include its support for relations via having, specialized array operations, and type-safe enumeration handling.

Sources: README.md:46-56, src/lib.rs:85-95