Add SectionedFetchRequest like API

[Rspoon3]

Why this is needed

Today, sectioned list UIs usually require:

1. @FetchAll for flat rows
2. grouping in memory (Dictionary(grouping:))
3. a wrapper type for section headers/items

For common section dimensions like isPinned, you can also do this with two separate fetches
(e.g. pinned + unpinned) or a custom FetchKeyRequest that manually assembles sections.

Both approaches works, but it's repetitive for a very common UI pattern.

Core Data baseline

Core Data provides sectioning with @SectionedFetchRequest:

@SectionedFetchRequest<Date, Quake>(
  sectionIdentifier: \.time,
  sortDescriptors: [SortDescriptor(\.time, order: .reverse)]
)
private var sections

What this could look like in SQLiteData

Keep the familiar sortDescriptors API and use descriptor order to drive both section and item ordering.

Option A: New wrapper (@FetchSectioned)

@FetchSectioned(
  Item.all,
  sectionIdentifier: \.category,
  sortDescriptors: [SortDescriptor(\.category, order: .forwards), SortDescriptor(\.name, order: .forwards)]
)
var sections: [FetchSection<String, Item>]

Option B: Extend @FetchAll

@FetchAll(
  Item.all,
  sectionedBy: \.category,
  sortDescriptors: [SortDescriptor(\.category, order: .forwards), SortDescriptor(\.name, order: .forwards)]
)
var sections: [FetchSection<String, Item>]

Proposed section type

public struct FetchSection<SectionID: Hashable & Sendable, Item: Sendable>: Identifiable, Sendable {
  public let id: SectionID
  public var items: [Item]
}

Small example: pinned section first

@Table
struct Book {
  let id: UUID
  var title: String
  var isPinned: Bool
}

@FetchSectioned(
  Book.all,
  sectionIdentifier: \.isPinned,
  sortDescriptors: [SortDescriptor(\.isPinned, order: .reverse), SortDescriptor(\.title, order: .forwards)]
)
var sections: [FetchSection<Bool, Book>]

List {
  ForEach(sections) { section in
    Section(section.id ? "Pinned" : "All Books") {
      ForEach(section.items) { Book in
        Text(Book.title)
      }
    }
  }
}

Small example: earthquakes sectioned by date

@Table
struct Quake {
  let id: UUID
  var magnitude: Double
  var place: String
  var time: Date
}

@FetchSectioned(
  Quake.all,
  sectionIdentifier: \.time,
  sectionTransform: { Calendar.current.startOfDay(for: $0) },
  sortDescriptors: [SortDescriptor(\.time, order: .reverse)]
)
var sections: [FetchSection<Date, Quake>]

Section transforms

The optional sectionTransform closure converts a raw column value into a coarser grouping key before sections are formed. In the earthquake example above, each row has a precise time timestamp, but we want to group rows by day, not by individual timestamp. The transform Calendar.current.startOfDay(for:) buckets every timestamp into its calendar day so all quakes from the same day land in one section.

This is useful whenever the natural column value is too granular for sectioning — dates into days/months, prices into ranges, scores into letter grades, etc. Core Data's @SectionedFetchRequest does not offer this; it requires adding a computed property on the model instead.

Alternative: SQL-level bucketing via .TableColumns extensions. Instead of transforming in Swift, the same bucketing could be expressed as a computed column expression using the library's existing extension pattern. For example, the codebase already extends .TableColumns with reusable query expressions like isActive and isArchived:

extension Quake.TableColumns {
  var day: some QueryExpression<Date> {
    // SQL-level date truncation, e.g. DATE(time)
  }
}

This would let the database handle bucketing before rows reach Swift, and the computed column could be used directly as the sectionIdentifier:

@FetchSectioned(
  Quake.all,
  sectionIdentifier: \.day,
  sortDescriptors: [SortDescriptor(\.time, order: .reverse)]
)
var sections: [FetchSection<Date, Quake>]

Both approaches could coexist — sectionTransform for simple client-side cases where a Swift closure is convenient, and .TableColumns extensions for performance-sensitive or reusable bucketing that pushes the work to SQLite.

Behavior expectations

• Re-executes automatically when underlying rows change (same as current fetch wrappers).
• Supports dynamic load(...) with a new query/filter/sort.
• Provides stable section identities for SwiftUI diffing.

[Rspoon3]

Okay I got something working.

import Foundation

/// A section of items grouped by a shared identifier.
struct FetchSection<SectionID: Hashable & Sendable, Item: Sendable>: Identifiable, Sendable {
    let id: SectionID
    var items: [Item] = []
}

import GRDB
import SQLiteData
import StructuredQueriesCore
import SwiftUI

// MARK: - SelectStatement + sectioned

extension SelectStatement where Joins == (), QueryValue == () {
    /// Groups pre-sorted rows into sections by a key path.
    ///
    /// The query must include `.order` with the section field first
    /// so that rows with the same value are contiguous.
    ///
    /// ```swift
    /// @Fetch(
    ///     Book.order { $0.genre.asc() }
    ///         .sectioned(by: \.genre)
    /// ) var sections: [FetchSection<String, Book>] = []
    /// ```
    nonisolated func sectioned<SectionID: Hashable & Sendable>(
        by keyPath: KeyPath<From.QueryOutput, SectionID>
    ) -> SectionedRequest<SectionID, From.QueryOutput> where From.QueryOutput: Sendable {
        SectionedRequest(self, sectionedBy: { $0[keyPath: keyPath] })
    }
}

// MARK: - SectionedRequest

/// A fetch request that streams rows from SQLite via a cursor and groups
/// them into sections in a single O(n) pass. No intermediate array
/// allocation, no client-side sorting — SQLite handles ORDER BY.
struct SectionedRequest<SectionID: Hashable & Sendable, Record: Sendable>: FetchKeyRequest {
    private let _fetchCursor: @Sendable (Database) throws -> QueryCursor<Record>
    private let sectionedBy: @Sendable (Record) -> SectionID

    init<S: SelectStatement>(
        _ statement: S,
        sectionedBy: @escaping @Sendable (Record) -> SectionID
    ) where S.From.QueryOutput == Record, S.Joins == (), S.QueryValue == () {
        self._fetchCursor = { db in try statement.fetchCursor(db) }
        self.sectionedBy = sectionedBy
    }

    func fetch(_ db: Database) throws -> [FetchSection<SectionID, Record>] {
        let cursor = try _fetchCursor(db)
        var sections: [FetchSection<SectionID, Record>] = []
        var currentID: SectionID?
        while let row = try cursor.next() {
            let id = sectionedBy(row)
            if id == currentID {
                sections[sections.count - 1].items.append(row)
            } else {
                sections.append(FetchSection(id: id, items: [row]))
                currentID = id
            }
        }
        return sections
    }

    // MARK: - Hashable

    static func == (lhs: Self, rhs: Self) -> Bool { true }

    func hash(into hasher: inout Hasher) {}
}

ExampleFiles.zip

[Rspoon3]

By adding an extension on QueryCursor I was able to get joins working as well.

// MARK: - QueryCursor + sectioned

extension QueryCursor {
    /// Groups pre-sorted cursor rows into sections in a single O(n) pass.
    func sectioned<SectionID: Hashable & Sendable>(
        by sectionedBy: (Element) -> SectionID
    ) throws -> [FetchSection<SectionID, Element>] where Element: Sendable {
        var sections: [FetchSection<SectionID, Element>] = []
        var currentID: SectionID?
        while let row = try next() {
            let id = sectionedBy(row)
            if id == currentID {
                sections[sections.count - 1].items.append(row)
            } else {
                sections.append(FetchSection(id: id, items: [row]))
                currentID = id
            }
        }
        return sections
    }
}

@Selection
nonisolated struct BookWithAuthor: Identifiable {
    var id: Book.ID
    var title: String
    var authorName: String
}

struct SectionedByAuthorRequest: FetchKeyRequest {
    func fetch(_ db: Database) throws -> [FetchSection<String, BookWithAuthor>] {
        try Book
            .join(Author.all) { $0.authorID.eq($1.id) }
            .order { _, authors in authors.name.asc() }
            .order { books, _ in books.title.asc() }
            .select { books, authors in
                BookWithAuthor.Columns(
                    id: books.id,
                    title: books.title,
                    authorName: authors.name
                )
            }
            .fetchCursor(db)
            .sectioned(by: \.authorName)
    }
}

struct SectionedByAuthorView: View {
    @Fetch(SectionedByAuthorRequest(), animation: .default)
    var sections: [FetchSection<String, BookWithAuthor>] = []

    // MARK: - Body

    var body: some View {
        List {
            ForEach(sections) { section in
                Section(section.id) {
                    ForEach(section.items) { row in
                        Text(row.title)
                    }
                }
            }
        }
        .navigationTitle("By Author")
    }
}