fix(sql_connect): Refactor to improve caching performance for large result sets

packages/firebase_data_connect/firebase_data_connect/example/dataconnect/.dataconnect/schema/main/input.gql

@@ -263,6 +263,10 @@ input Movie_Data {
   ✨ `_expr` server value variant of `title` (✨ Generated from Field `Movie`.`title` of type `String!`)
   """
   title_expr: String_Expr @fdc_forbiddenInVariables
+  """
+  ✨ Generated from Field `Movie`.`directedBies_on_movie` of type `[DirectedBy!]!`
+  """
+  directedBies_on_movie: [DirectedBy_Data!]
 }
 """
 ✨ Generated filter input type for table 'Movie'. This input allows filtering objects using various conditions. Use `_or`, `_and`, and `_not` to compose complex filters.
@@ -542,6 +546,10 @@ input Person_Data {
   ✨ `_expr` server value variant of `name` (✨ Generated from Field `Person`.`name` of type `String!`)
   """
   name_expr: String_Expr @fdc_forbiddenInVariables
+  """
+  ✨ Generated from Field `Person`.`directedBies_on_directedby` of type `[DirectedBy!]!`
+  """
+  directedBies_on_directedby: [DirectedBy_Data!]
 }
 """
 ✨ Generated filter input type for table 'Person'. This input allows filtering objects using various conditions. Use `_or`, `_and`, and `_not` to compose complex filters.

packages/firebase_data_connect/firebase_data_connect/example/integration_test/cache_e2e.dart

@@ -0,0 +1,85 @@
+// Copyright 2026, the Chromium project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:firebase_data_connect/firebase_data_connect.dart';
+import 'package:firebase_data_connect_example/generated/movies.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+import 'query_e2e.dart'; // For deleteAllMovies
+
+void runCacheTests() {
+  group(
+    '$FirebaseDataConnect cache',
+    () {
+      setUp(() async {
+        final dataConnect = MoviesConnector.instance.dataConnect;
+        // Temporarily disable cache during database cleanup to prevent populating it
+        dataConnect.cacheSettings = null;
+        dataConnect.useDataConnectEmulator('127.0.0.1', 9399);
+
+        await deleteAllMovies();
+
+        // Enable cache with memory storage and a large TTL for testing.
+        dataConnect.cacheSettings = CacheSettings(
+          storage: CacheStorage.memory,
+          maxAge: const Duration(minutes: 5),
+        );
+        // Re-apply emulator to force cache manager recreation with new settings
+        dataConnect.useDataConnectEmulator('127.0.0.1', 9399);
+      });
+
+      testWidgets('test cache flow: serverOnly, cacheOnly, preferCache',
+          (WidgetTester tester) async {
+        final moviesConnector = MoviesConnector.instance;
+
+        // 1. Initial query with preferCache should result in server hit because cache is empty.
+        final res1 = await moviesConnector.listMovies().ref().execute(
+              fetchPolicy: QueryFetchPolicy.preferCache,
+            );
+        expect(res1.source, DataSource.server);
+        expect(res1.data.movies, isEmpty);
+
+        // 2. Second query with preferCache should result in cache hit.
+        final res2 = await moviesConnector.listMovies().ref().execute(
+              fetchPolicy: QueryFetchPolicy.preferCache,
+            );
+        expect(res2.source, DataSource.cache);
+        expect(res2.data.movies, isEmpty);
+
+        // 3. Mutation to add a movie. This goes to server.
+        await moviesConnector
+            .createMovie(
+              genre: 'Sci-Fi',
+              title: 'Inception',
+              releaseYear: 2010,
+            )
+            .ref()
+            .execute();
+
+        // 4. Query with cacheOnly should still return empty list (cache hit, stale data).
+        final res3 = await moviesConnector.listMovies().ref().execute(
+              fetchPolicy: QueryFetchPolicy.cacheOnly,
+            );
+        expect(res3.source, DataSource.cache);
+        expect(res3.data.movies, isEmpty);
+
+        // 5. Query with serverOnly should return the new movie (server hit) and update cache.
+        final res4 = await moviesConnector.listMovies().ref().execute(
+              fetchPolicy: QueryFetchPolicy.serverOnly,
+            );
+        expect(res4.source, DataSource.server);
+        expect(res4.data.movies.length, 1);
+        expect(res4.data.movies[0].title, 'Inception');
+
+        // 6. Query with cacheOnly should now return the new movie (cache hit).
+        final res5 = await moviesConnector.listMovies().ref().execute(
+              fetchPolicy: QueryFetchPolicy.cacheOnly,
+            );
+        expect(res5.source, DataSource.cache);
+        expect(res5.data.movies.length, 1);
+        expect(res5.data.movies[0].title, 'Inception');
+      });
+    },
+  );
+}

packages/firebase_data_connect/firebase_data_connect/example/integration_test/e2e_test.dart

@@ -10,6 +10,7 @@ import 'package:firebase_data_connect_example/generated/movies.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:integration_test/integration_test.dart';
 
+import 'cache_e2e.dart';
 import 'generation_e2e.dart';
 import 'instance_e2e.dart';
 import 'listen_e2e.dart';
@@ -69,5 +70,6 @@ void main() {
     runGenerationTest();
     runListenTests();
     runWebSocketTests();
+    runCacheTests();
   });
 }

packages/firebase_data_connect/firebase_data_connect/example/lib/generated/.guides/usage.md

@@ -8,9 +8,9 @@ MoviesConnector.instance.addDateAndTimestamp(addDateAndTimestampVariables).execu
 MoviesConnector.instance.seedMovies().execute();
 MoviesConnector.instance.createMovie(createMovieVariables).execute();
 MoviesConnector.instance.deleteMovie(deleteMovieVariables).execute();
+MoviesConnector.instance.deleteAllMovieData().execute();
 MoviesConnector.instance.thing(thingVariables).execute();
 MoviesConnector.instance.seedData().execute();
-MoviesConnector.instance.ListMovies().execute();
 
 ```
 

packages/firebase_data_connect/firebase_data_connect/example/lib/generated/README.md

@@ -650,6 +650,40 @@ ref.execute();
 ```
 
 
+### deleteAllMovieData
+#### Required Arguments
+```dart
+// No required arguments
+MoviesConnector.instance.deleteAllMovieData().execute();
+```
+
+
+
+#### Return Type
+`execute()` returns a `OperationResult<deleteAllMovieDataData, void>`
+```dart
+/// Result of an Operation Request (query/mutation).
+class OperationResult<Data, Variables> {
+  OperationResult(this.dataConnect, this.data, this.ref);
+  Data data;
+  OperationRef<Data, Variables> ref;
+  FirebaseDataConnect dataConnect;
+}
+
+final result = await MoviesConnector.instance.deleteAllMovieData();
+deleteAllMovieDataData data = result.data;
+final ref = result.ref;
+```
+
+#### Getting the Ref
+Each builder returns an `execute` function, which is a helper function that creates a `Ref` object, and executes the underlying operation.
+An example of how to use the `Ref` object is shown below:
+```dart
+final ref = MoviesConnector.instance.deleteAllMovieData().ref();
+ref.execute();
+```
+
+
 ### thing
 #### Required Arguments
 ```dart

packages/firebase_data_connect/firebase_data_connect/example/lib/generated/delete_all_movie_data.dart

@@ -20,19 +20,14 @@ class DeleteAllMovieDataVariablesBuilder {
 
 @immutable
 class DeleteAllMovieDataData {
-  final int directedByDeleteMany;
-  final int movieDeleteMany;
-  final int personDeleteMany;
+  final int directedBy_deleteMany;
+  final int movie_deleteMany;
+  final int person_deleteMany;
   DeleteAllMovieDataData.fromJson(dynamic json)
-      : directedByDeleteMany = nativeFromJson<int>(
-          json['directedBy_deleteMany'],
-        ),
-        movieDeleteMany = nativeFromJson<int>(
-          json['movie_deleteMany'],
-        ),
-        personDeleteMany = nativeFromJson<int>(
-          json['person_deleteMany'],
-        );
+      : directedBy_deleteMany =
+            nativeFromJson<int>(json['directedBy_deleteMany']),
+        movie_deleteMany = nativeFromJson<int>(json['movie_deleteMany']),
+        person_deleteMany = nativeFromJson<int>(json['person_deleteMany']);
   @override
   bool operator ==(Object other) {
     if (identical(this, other)) {
@@ -43,29 +38,29 @@ class DeleteAllMovieDataData {
     }
 
     final DeleteAllMovieDataData otherTyped = other as DeleteAllMovieDataData;
-    return directedByDeleteMany == otherTyped.directedByDeleteMany &&
-        movieDeleteMany == otherTyped.movieDeleteMany &&
-        personDeleteMany == otherTyped.personDeleteMany;
+    return directedBy_deleteMany == otherTyped.directedBy_deleteMany &&
+        movie_deleteMany == otherTyped.movie_deleteMany &&
+        person_deleteMany == otherTyped.person_deleteMany;
   }
 
   @override
   int get hashCode => Object.hashAll([
-        directedByDeleteMany.hashCode,
-        movieDeleteMany.hashCode,
-        personDeleteMany.hashCode,
+        directedBy_deleteMany.hashCode,
+        movie_deleteMany.hashCode,
+        person_deleteMany.hashCode
       ]);
 
   Map<String, dynamic> toJson() {
     Map<String, dynamic> json = {};
-    json['directedBy_deleteMany'] = nativeToJson<int>(directedByDeleteMany);
-    json['movie_deleteMany'] = nativeToJson<int>(movieDeleteMany);
-    json['person_deleteMany'] = nativeToJson<int>(personDeleteMany);
+    json['directedBy_deleteMany'] = nativeToJson<int>(directedBy_deleteMany);
+    json['movie_deleteMany'] = nativeToJson<int>(movie_deleteMany);
+    json['person_deleteMany'] = nativeToJson<int>(person_deleteMany);
     return json;
   }
 
-  const DeleteAllMovieDataData({
-    required this.directedByDeleteMany,
-    required this.movieDeleteMany,
-    required this.personDeleteMany,
+  DeleteAllMovieDataData({
+    required this.directedBy_deleteMany,
+    required this.movie_deleteMany,
+    required this.person_deleteMany,
   });
 }

packages/firebase_data_connect/firebase_data_connect/lib/firebase_data_connect.dart

@@ -28,7 +28,13 @@ export 'src/common/common_library.dart'
         CallerSDKType;
 export 'src/core/empty_serializer.dart' show emptySerializer;
 export 'src/core/ref.dart'
-    show MutationRef, OperationRef, OperationResult, QueryRef, QueryResult;
+    show
+        MutationRef,
+        OperationRef,
+        OperationResult,
+        QueryRef,
+        QueryResult,
+        DataSource;
 export 'src/firebase_data_connect.dart';
 export 'src/optional.dart'
     show