feat: step-based parameterized catalog entries in GQL

Author: Spelkington

examples/advanced/KedroSpaceflightsGQL/Data/_01_Raw/Catalog.Raw.cs

@@ -70,7 +70,7 @@ public partial class Catalog
     );
 
   /// <summary>
-  /// Raw shuttle data queried from the GQL server.
+  /// Raw shuttle data queried from the GQL server (all shuttles, unfiltered).
   /// </summary>
   public IItem<IEnumerable<IGetShuttles_Shuttles>> Shuttles =>
     CreateItem(
@@ -96,4 +96,42 @@ public partial class Catalog
           allowEmptyData: true
         )
     );
+
+  // ── Parameterized GQL entries — consumed by the Analytics flow ──────────
+
+  /// <summary>
+  /// The company ID of the highest-rated company. Written by FindTopRatedCompany;
+  /// used as the parameter source for <see cref="TopRatedCompanyShuttles"/>.
+  /// </summary>
+  public IItem<string> TopRatedCompanyId =>
+    CreateItem(() => ItemFactory.Single.Memory<string>("TopRatedCompanyId"));
+
+  /// <summary>
+  /// Shuttles operated by the top-rated company — a parameterized GQL catalog entry.
+  /// At load time, the adapter reads <see cref="TopRatedCompanyId"/> and fires a
+  /// filtered <c>GetShuttlesByCompanyId</c> query. Only that company's shuttles are
+  /// transferred; the full shuttle dataset is never pulled.
+  /// </summary>
+  /// <remarks>
+  /// The dependency analyzer discovers that this item's adapter depends on
+  /// <see cref="TopRatedCompanyId"/>. Any step consuming <see cref="TopRatedCompanyShuttles"/>
+  /// is automatically scheduled after the step that produces
+  /// <see cref="TopRatedCompanyId"/>, with no explicit ordering required in the flow
+  /// definition.
+  /// </remarks>
+  public IItem<IEnumerable<IGetShuttlesByCompanyId_Shuttles>> TopRatedCompanyShuttles =>
+    CreateItem(
+      () =>
+        GqlItemFactory.Enumerable.Query<
+          string,
+          IGetShuttlesByCompanyIdResult,
+          IGetShuttlesByCompanyId_Shuttles
+        >(
+          label: "GQLTopRatedCompanyShuttles",
+          parameterSource: TopRatedCompanyId,
+          queryFunc: (companyId, ct) => _client.GetShuttlesByCompanyId.ExecuteAsync(companyId, ct),
+          selectData: r => r.Shuttles,
+          allowEmptyData: true
+        )
+    );
 }

examples/advanced/KedroSpaceflightsGQL/Data/_08_Reporting/Catalog.Reporting.cs

@@ -22,6 +22,20 @@ public partial class Catalog
         )
     );
 
+  /// <summary>
+  /// Fleet summary for the top-rated company, produced by the Analytics flow.
+  /// Demonstrates that the consuming step receives plain materialized data and has
+  /// no awareness of the parameterized GQL query that fetched it.
+  /// </summary>
+  public IItem<TopRatedCompanyReport> TopRatedCompanyReport =>
+    CreateItem(
+      () =>
+        ItemFactory.Single.Json<TopRatedCompanyReport>(
+          label: "TopRatedCompanyReport",
+          filePath: $"{_basePath}/_08_Reporting/Datasets/top_rated_company_report.json"
+        )
+    );
+
   /// <summary>
   /// Shuttle passenger capacity bar chart (in-memory GenericChart).
   /// Intermediate chart object stored in memory for downstream export to PNG.

examples/advanced/KedroSpaceflightsGQL/Data/_08_Reporting/Schemas/TopRatedCompanyReport.cs

@@ -0,0 +1,31 @@
+using Flowthru.Core.Abstractions;
+
+namespace KedroSpaceflightsGQL.Data._08_Reporting.Schemas;
+
+/// <summary>
+/// Summary report for the top-rated company's shuttle fleet.
+/// Produced by the Analytics flow to demonstrate parameterized GQL catalog items.
+/// </summary>
+[FlowthruSchema]
+public partial record TopRatedCompanyReport
+{
+  /// <summary>
+  /// Identifier of the top-rated company.
+  /// </summary>
+  public required string CompanyId { get; init; }
+
+  /// <summary>
+  /// Number of shuttles operated by this company.
+  /// </summary>
+  public required int ShuttleCount { get; init; }
+
+  /// <summary>
+  /// Average trip price across the company's fleet.
+  /// </summary>
+  public required decimal AveragePrice { get; init; }
+
+  /// <summary>
+  /// Total passenger capacity across the company's entire fleet.
+  /// </summary>
+  public required int TotalPassengerCapacity { get; init; }
+}

examples/advanced/KedroSpaceflightsGQL/Flows/Analytics/AnalyticsFlow.cs

@@ -0,0 +1,81 @@
+using Flowthru.Core.Flows;
+using KedroSpaceflightsGQL.Data;
+using KedroSpaceflightsGQL.Flows.Analytics.Steps;
+
+namespace KedroSpaceflightsGQL.Flows.Analytics;
+
+/// <summary>
+/// Analytics pipeline demonstrating parameterized GQL catalog items.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <strong>The problem this addresses:</strong> The GQL shuttle endpoint contains the full
+/// fleet across all companies. Pulling it unfiltered and then post-filtering in a step wastes
+/// network bandwidth and server resources — particularly when only a small subset is needed.
+/// </para>
+/// <para>
+/// <strong>The pattern:</strong>
+/// <list type="number">
+/// <item>
+///   <c>FindTopRatedCompany</c> is a pure transform: it reads all company records and selects
+///   the highest-rated company's ID, writing it to the in-memory <c>TopRatedCompanyId</c>
+///   catalog item.
+/// </item>
+/// <item>
+///   <c>TopRatedCompanyShuttles</c> is a <em>parameterized</em> GQL catalog entry. Its adapter
+///   is declared with <c>parameterSource: catalog.TopRatedCompanyId</c>. When the engine loads
+///   this item, the adapter reads <c>TopRatedCompanyId</c> first and passes its value to
+///   <c>GetShuttlesByCompanyId</c> — so only the relevant shuttles are fetched.
+/// </item>
+/// <item>
+///   <c>AnalyzeTopCompanyFleet</c> is a pure transform: it receives a plain
+///   <c>IEnumerable</c> and produces a report. It has no knowledge of parameterization.
+/// </item>
+/// </list>
+/// </para>
+/// <para>
+/// <strong>DAG ordering:</strong> The dependency analyzer inspects
+/// <c>TopRatedCompanyShuttles</c>'s adapter and discovers that it depends on
+/// <c>TopRatedCompanyId</c>. It automatically adds <c>FindTopRatedCompany</c> as a
+/// transitive dependency of <c>AnalyzeTopCompanyFleet</c> — no explicit ordering is declared
+/// in this flow definition.
+/// </para>
+/// </remarks>
+public static class AnalyticsFlow
+{
+  /// <summary>
+  /// Creates the analytics pipeline.
+  /// </summary>
+  public static Flow Create(Catalog catalog)
+  {
+    return FlowBuilder.CreateFlow(pipeline =>
+    {
+      pipeline.AddStep(
+        label: "FindTopRatedCompany",
+        description: """
+          Identifies the company with the highest rating across all GQL companies.
+          GqlDatabaseSeeded is consumed as an explicit DAG gate ensuring Ingest has
+          completed before this step executes.
+        """,
+        transform: FindTopRatedCompanyStep.Create(),
+        input: (catalog.GqlDatabaseSeeded, catalog.Companies),
+        output: catalog.TopRatedCompanyId
+      );
+
+      pipeline.AddStep(
+        label: "AnalyzeTopCompanyFleet",
+        description: """
+          Computes a fleet summary for the top-rated company. The input catalog item
+          (TopRatedCompanyShuttles) is parameterized: its adapter reads TopRatedCompanyId at load
+          time and fires a filtered GQL query — only that company's shuttles are transferred.
+          This step is a pure transform with no awareness of the filtering mechanism.
+          DAG ordering (runs after FindTopRatedCompany) is enforced automatically via the
+          adapter's ItemDependencies declaration.
+        """,
+        transform: AnalyzeTopCompanyShuttlesStep.Create(),
+        input: catalog.TopRatedCompanyShuttles,
+        output: catalog.TopRatedCompanyReport
+      );
+    });
+  }
+}

examples/advanced/KedroSpaceflightsGQL/Flows/Analytics/Steps/AnalyzeTopCompanyShuttlesStep.cs

@@ -0,0 +1,44 @@
+using Flowthru.Core.Steps;
+using KedroSpaceflightsGQL.Data._08_Reporting.Schemas;
+using KedroSpaceflightsGQL.Infra.GqlClient;
+
+namespace KedroSpaceflightsGQL.Flows.Analytics.Steps;
+
+/// <summary>
+/// Computes a fleet summary for the top-rated company from its filtered shuttle data.
+/// </summary>
+/// <remarks>
+/// This step is a pure transform. It receives a plain <c>IEnumerable</c> of shuttle records
+/// and produces a report. It has no awareness that the shuttle data was fetched via a
+/// parameterized GQL query — the catalog layer handled all of that. The DAG ordering
+/// (this step runs after <c>FindTopRatedCompany</c>) is enforced automatically by the
+/// dependency analyzer inspecting <c>TopRatedCompanyShuttles</c>'s adapter dependencies.
+/// </remarks>
+[FlowthruStep]
+public static class AnalyzeTopCompanyShuttlesStep
+{
+  /// <summary>
+  /// Creates the transform that summarizes a company's shuttle fleet.
+  /// </summary>
+  public static Func<
+    IEnumerable<IGetShuttlesByCompanyId_Shuttles>,
+    TopRatedCompanyReport
+  > Create() =>
+    shuttles =>
+    {
+      var list = shuttles.ToList();
+
+      var companyId = list.FirstOrDefault()?.CompanyId ?? "unknown";
+      var shuttleCount = list.Count;
+      var averagePrice = shuttleCount > 0 ? list.Average(s => s.Price) : 0m;
+      var totalCapacity = list.Sum(s => s.PassengerCapacity);
+
+      return new TopRatedCompanyReport
+      {
+        CompanyId = companyId,
+        ShuttleCount = shuttleCount,
+        AveragePrice = averagePrice,
+        TotalPassengerCapacity = totalCapacity,
+      };
+    };
+}

examples/advanced/KedroSpaceflightsGQL/Flows/Analytics/Steps/FindTopRatedCompanyStep.cs

@@ -0,0 +1,39 @@
+using Flowthru.Core.Steps;
+using KedroSpaceflightsGQL.Infra.GqlClient;
+
+namespace KedroSpaceflightsGQL.Flows.Analytics.Steps;
+
+/// <summary>
+/// Identifies the company with the highest rating across all companies.
+/// Produces the company ID string that parameterizes the downstream shuttle query.
+/// </summary>
+/// <remarks>
+/// This step is a pure transform: it has no awareness that its output will be consumed
+/// by a parameterized catalog entry. The catalog layer handles that wiring entirely.
+/// </remarks>
+[FlowthruStep]
+public static class FindTopRatedCompanyStep
+{
+  /// <summary>
+  /// Creates the transform that selects the highest-rated company's ID.
+  /// </summary>
+  /// <remarks>
+  /// The <c>bool</c> first input is the <c>GqlDatabaseSeeded</c> gate; it is consumed
+  /// only to express the DAG dependency on Ingest and is otherwise unused.
+  /// </remarks>
+  public static Func<(bool, IEnumerable<IGetCompanies_Companies>), string> Create() =>
+    input =>
+    {
+      var (_, companies) = input;
+      var top = companies.MaxBy(c => c.CompanyRating);
+
+      if (top is null)
+      {
+        throw new InvalidOperationException(
+          "Cannot determine top-rated company: the companies collection is empty."
+        );
+      }
+
+      return top.Id;
+    };
+}

examples/advanced/KedroSpaceflightsGQL/Infra/GqlClient/Operations.graphql

@@ -21,6 +21,20 @@ query GetShuttles {
   }
 }
 
+query GetShuttlesByCompanyId($companyId: String!) {
+  shuttles(companyId: $companyId) {
+    id
+    shuttleType
+    companyId
+    engines
+    passengerCapacity
+    crew
+    price
+    dCheckComplete
+    moonClearanceComplete
+  }
+}
+
 query GetReviews {
   reviews {
     shuttleId

examples/advanced/KedroSpaceflightsGQL/Infra/GqlClient/schema.graphql

@@ -50,7 +50,7 @@ input AddReviewInput {
 
 type Query {
   companies: [CompanyRecord!]!
-  shuttles: [ShuttleRecord!]!
+  shuttles(companyId: String): [ShuttleRecord!]!
   reviews: [ReviewRecord!]!
 }
 

examples/advanced/KedroSpaceflightsGQL/Infra/GqlServer/SpaceflightsGqlServer.cs

@@ -12,8 +12,10 @@ public class Query
   public IReadOnlyList<CompanyRecord> GetCompanies([Service] SpaceflightsRepository repo) =>
     repo.GetCompanies();
 
-  public IReadOnlyList<ShuttleRecord> GetShuttles([Service] SpaceflightsRepository repo) =>
-    repo.GetShuttles();
+  public IReadOnlyList<ShuttleRecord> GetShuttles(
+    [Service] SpaceflightsRepository repo,
+    string? companyId = null
+  ) => companyId is not null ? repo.GetShuttlesByCompanyId(companyId) : repo.GetShuttles();
 
   public IReadOnlyList<ReviewRecord> GetReviews([Service] SpaceflightsRepository repo) =>
     repo.GetReviews();

examples/advanced/KedroSpaceflightsGQL/Infra/GqlServer/SpaceflightsRepository.cs

@@ -36,6 +36,14 @@ public IReadOnlyList<ShuttleRecord> GetShuttles()
     }
   }
 
+  public IReadOnlyList<ShuttleRecord> GetShuttlesByCompanyId(string companyId)
+  {
+    lock (_lock)
+    {
+      return _shuttles.Where(s => s.CompanyId == companyId).ToList();
+    }
+  }
+
   public IReadOnlyList<ReviewRecord> GetReviews()
   {
     lock (_lock)