Sorting and Ordering

Introduction

Sorting and Ordering in Seaography provides a mechanism to organize the results of GraphQL queries by specific entity columns. This feature is integrated into the framework's core query system, allowing users to define the order of returned data for both top-level entities and nested relational queries. By bridging SeaORM's database capabilities with async-graphql, Seaography automatically generates the necessary input types to support ordering in a type-safe manner. Sources: README.md:46, src/lib.rs:56

The system supports ascending (ASC) and descending (DESC) directions. This functionality is critical for features such as pagination, where consistent ordering ensures that nodes are correctly traversed across pages. Sources: README.md:126, CHANGELOG.md:405

Architectural Integration

Ordering is exposed through the orderBy argument in GraphQL queries. This argument accepts an input object where keys correspond to column names and values indicate the sort direction. Sources: README.md:126, examples/postgres/tests/query_tests.rs:434

Data Flow for Ordered Queries

The following diagram illustrates how an ordering request moves from a GraphQL client through the Seaography framework to the database.

Ordering logic is applied during the resolver phase, where Seaography translates the GraphQL input into SeaORM order_by calls. Sources: README.md:21-25, CHANGELOG.md:405

Key Components and Input Structures

The ordering system relies on generated input objects for each entity. These objects allow the user to specify one or more columns to sort by. Sources: README.md:56, src/lib.rs:242

Order Directions

The framework utilizes a standard enumeration for sort directions:

Sources: README.md:126, examples/postgres/tests/query_tests.rs:444

Relational Ordering

Ordering is not limited to the root query; it can be applied to nested relational fields. For example, when fetching a customer, the associated payment nodes can be ordered independently. Sources: README.md:175-180, examples/postgres/tests/query_tests.rs:442-446

Implementation in Queries

Ordering is typically used in conjunction with filters and pagination. In the generated schema, the orderBy field appears alongside filters and pagination arguments. Sources: README.md:174-177, examples/sqlite/tests/query_tests.rs:420-424

Example Query Structure

{
  film(
    orderBy: { title: ASC },
    pagination: { page: { limit: 10, page: 0 } }
  ) {
    nodes {
      title
      releaseYear
    }
  }
}

Sources: README.md:126-129, examples/mysql/tests/query_tests.rs:434-438

Technical Constraints and Requirements

• Column Availability: Any column defined in the SeaORM entity can be used for ordering. Sources: README.md:56, src/lib.rs:56
• Case Sensitivity: The framework supports both field-camel-case and field-snake-case for ordering fields, depending on the crate features enabled. Sources: README.md:60, Cargo.toml:44-55
• Multiple Fields: While most examples show a single field, the underlying SeaORM implementation allows for multiple ORDER BY clauses to be generated. Sources: CHANGELOG.md:405-407

Summary

Sorting and Ordering is a foundational feature of Seaography that enables structured data retrieval. By leveraging SeaORM's native ordering capabilities and mapping them to async-graphql input objects, the framework provides a seamless way to sort database records via a GraphQL API. This integration supports both simple top-level queries and complex nested relational fetches, ensuring that clients can control the presentation of data directly from the query. Sources: README.md:14-25, src/lib.rs:14-25