Search index isolate without text indexing for predicate-only queries. (#8823)

Author: isoos

CHANGELOG.md

@@ -5,6 +5,7 @@ AppEngine version, listed here to ease deployment and troubleshooting.
  * Bump runtimeVersion to `2025.06.20`.
  * Upgraded stable Flutter analysis SDK to `3.32.4`.
  * Note: started to export `/api/packages/<package>/[likes|options|publisher|score]` endpoints.
+ * Note: search instance uses separate isolate for predicate-only queries.
 
 ## `20250619t085100-all`
  * Bump runtimeVersion to `2025.06.03`.

app/bin/tools/isolate_search_benchmark.dart

@@ -0,0 +1,71 @@
+// Copyright (c) 2025, the Dart 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 'dart:math';
+
+import 'package:_pub_shared/search/search_form.dart';
+import 'package:collection/collection.dart';
+import 'package:pub_dev/search/search_service.dart';
+import 'package:pub_dev/service/entrypoint/_isolate.dart';
+import 'package:pub_dev/service/entrypoint/search_index.dart';
+
+// NOTE: please add more queries to this list, especially if there is a performance bottleneck.
+final queries = [
+  'sdk:dart',
+  'sdk:flutter platform:android',
+  'is:flutter-favorite',
+  'chart',
+  'json',
+  'camera',
+  'android camera',
+  'sql database',
+];
+
+Future<void> main(List<String> args) async {
+  print('Loading...');
+  final primaryRunner = await startSearchIsolate(snapshot: args.first);
+  final reducedRunner = await startSearchIsolate(
+    snapshot: args.first,
+    removeTextContent: true,
+  );
+  print('Loaded.');
+
+  for (var i = 0; i < 5; i++) {
+    await _benchmark(primaryRunner, primaryRunner);
+    await _benchmark(primaryRunner, reducedRunner);
+    print('--');
+  }
+
+  await primaryRunner.close();
+  await reducedRunner.close();
+}
+
+Future<void> _benchmark(IsolateRunner primary, IsolateRunner reduced) async {
+  final index = IsolateSearchIndex(primary, reduced);
+  final durations = <String, List<int>>{};
+  for (var i = 0; i < 100; i++) {
+    final random = Random(i);
+    final items = queries
+        .map((q) => ServiceSearchQuery.parse(
+              query: q,
+              tagsPredicate: TagsPredicate.regularSearch(),
+            ))
+        .toList();
+    items.shuffle(random);
+    await Future.wait(items.map((q) async {
+      final sw = Stopwatch()..start();
+      await index.search(q);
+      final d = sw.elapsed.inMicroseconds;
+      durations.putIfAbsent('all', () => []).add(d);
+      final key = q.parsedQuery.hasFreeText ? 'primary' : 'reduced';
+      durations.putIfAbsent(key, () => []).add(d);
+    }));
+  }
+  for (final e in durations.entries) {
+    e.value.sort();
+    print('${e.key.padLeft(10)}: '
+        '${e.value.average.round().toString().padLeft(10)} avg '
+        '${e.value[e.value.length * 90 ~/ 100].toString().padLeft(10)} p90');
+  }
+}

app/lib/search/search_service.dart

@@ -137,6 +137,29 @@ class PackageDocument {
   Map<String, dynamic> toJson() => _$PackageDocumentToJson(this);
 
   late final packageNameLowerCased = package.toLowerCase();
+
+  /// Removes the text-heavy content from the current object,
+  /// making it lightweight for no-text indexing.
+  PackageDocument removeTextContent() => PackageDocument(
+        package: package,
+        version: version,
+        created: created,
+        updated: updated,
+        sourceUpdated: sourceUpdated,
+        timestamp: timestamp,
+        apiDocPages: null,
+        dependencies: dependencies,
+        description: null,
+        downloadCount: downloadCount,
+        downloadScore: downloadScore,
+        grantedPoints: grantedPoints,
+        likeCount: likeCount,
+        likeScore: likeScore,
+        maxPoints: maxPoints,
+        readme: null,
+        tags: tags,
+        trendScore: trendScore,
+      );
 }
 
 /// A reference to an API doc page
@@ -299,9 +322,6 @@ class ServiceSearchQuery {
       !_isFlutterFavorite &&
       (textMatchExtent ?? TextMatchExtent.api).shouldMatchApi();
 
-  bool get considerHighlightedHit => _hasOnlyFreeText && _hasNoOwnershipScope;
-  bool get includeHighlightedHit => considerHighlightedHit && offset == 0;
-
   /// Returns the validity status of the query.
   QueryValidity evaluateValidity() {
     // Block search on unreasonably long search queries (when the free-form

app/lib/search/updater.dart

@@ -30,15 +30,19 @@ IndexUpdater get indexUpdater => ss.lookup(#_indexUpdater) as IndexUpdater;
 
 /// Loads a local search snapshot file and builds an in-memory package index from it.
 Future<InMemoryPackageIndex> loadInMemoryPackageIndexFromFile(
-    String path) async {
+  String path, {
+  bool removeTextContent = false,
+}) async {
   final file = File(path);
   final content =
       json.decode(utf8.decode(gzip.decode(await file.readAsBytes())))
           as Map<String, Object?>;
   final snapshot = SearchSnapshot.fromJson(content);
   return InMemoryPackageIndex(
-      documents:
-          snapshot.documents!.values.where((d) => !isSdkPackage(d.package)));
+    documents: snapshot.documents!.values
+        .where((d) => !isSdkPackage(d.package))
+        .map((d) => removeTextContent ? d.removeTextContent() : d),
+  );
 }
 
 /// Saves the provided [documents] into a local search snapshot file.
@@ -60,8 +64,8 @@ class IndexUpdater {
 
   /// Loads the package index snapshot, or if it fails, creates a minimal
   /// package index with only package names and minimal information.
-  Future<void> init() async {
-    final isReady = await _initSnapshot();
+  Future<void> init({bool removeTextContent = false}) async {
+    final isReady = await _initSnapshot(removeTextContent);
     if (!isReady) {
       _logger.info('Loading minimum package index...');
       final documents = await searchBackend.loadMinimumPackageIndex().toList();
@@ -85,14 +89,17 @@ class IndexUpdater {
   }
 
   /// Returns whether the snapshot was initialized and loaded properly.
-  Future<bool> _initSnapshot() async {
+  Future<bool> _initSnapshot(bool removeTextContent) async {
     try {
       _logger.info('Loading snapshot...');
       final documents = await searchBackend.fetchSnapshotDocuments();
       if (documents == null) {
         return false;
       }
-      updatePackageIndex(InMemoryPackageIndex(documents: documents));
+      updatePackageIndex(InMemoryPackageIndex(
+        documents:
+            documents.map((d) => removeTextContent ? d.removeTextContent() : d),
+      ));
       // Arbitrary sanity check that the snapshot is not entirely bogus.
       // Index merge will enable search.
       if (documents.length > 10) {

app/lib/service/entrypoint/search.dart

@@ -38,13 +38,14 @@ class SearchCommand extends Command {
 
     envConfig.checkServiceEnvironment(name);
     await withServices(() async {
-      final packageIsolate = await startQueryIsolate(
+      final primaryIsolate = await startSearchIsolate(logger: _logger);
+      registerScopeExitCallback(primaryIsolate.close);
+
+      final reducedIsolate = await startSearchIsolate(
         logger: _logger,
-        kind: 'package',
-        spawnUri:
-            Uri.parse('package:pub_dev/service/entrypoint/search_index.dart'),
+        removeTextContent: true,
       );
-      registerScopeExitCallback(packageIsolate.close);
+      registerScopeExitCallback(reducedIsolate.close);
 
       final sdkIsolate = await startQueryIsolate(
         logger: _logger,
@@ -56,8 +57,9 @@ class SearchCommand extends Command {
 
       registerSearchIndex(
         SearchResultCombiner(
-          primaryIndex:
-              LatencyAwareSearchIndex(IsolateSearchIndex(packageIsolate)),
+          primaryIndex: LatencyAwareSearchIndex(
+            IsolateSearchIndex(primaryIsolate, reducedIsolate),
+          ),
           sdkIndex: SdkIsolateIndex(sdkIsolate),
         ),
       );
@@ -70,7 +72,10 @@ class SearchCommand extends Command {
           await Future.delayed(delay);
 
           // create a new index and handover with a 2-minute maximum wait
-          await packageIsolate.renew(count: 1, wait: Duration(minutes: 2));
+          await Future.wait([
+            primaryIsolate.renew(count: 1, wait: Duration(minutes: 2)),
+            reducedIsolate.renew(count: 1, wait: Duration(minutes: 2)),
+          ]);
 
           // schedule the renewal again
           scheduleRenew();

app/lib/service/entrypoint/search_index.dart

@@ -22,6 +22,11 @@ import 'package:pub_dev/shared/utils.dart';
 final _logger = Logger('search_index');
 
 final _argParser = ArgParser()
+  ..addFlag(
+    'remove-text-content',
+    defaultsTo: false,
+    help: 'When set, the text content of the index will be removed.',
+  )
   ..addOption(
     'snapshot',
     help:
@@ -34,6 +39,7 @@ Future<void> main(List<String> args, var message) async {
 
   final argv = _argParser.parse(args);
   final snapshot = argv['snapshot'] as String?;
+  final removeTextContent = (argv['remove-text-content'] as bool?) ?? false;
 
   final ServicesWrapperFn servicesWrapperFn;
   if (envConfig.isRunningInAppengine) {
@@ -46,9 +52,10 @@ Future<void> main(List<String> args, var message) async {
   await fork(() async {
     await servicesWrapperFn(() async {
       if (snapshot == null) {
-        await indexUpdater.init();
+        await indexUpdater.init(removeTextContent: removeTextContent);
       } else {
-        updatePackageIndex(await loadInMemoryPackageIndexFromFile(snapshot));
+        updatePackageIndex(await loadInMemoryPackageIndexFromFile(snapshot,
+            removeTextContent: removeTextContent));
       }
 
       await runIsolateFunctions(
@@ -75,12 +82,30 @@ Future<void> main(List<String> args, var message) async {
   timer.cancel();
 }
 
+/// Starts a new search isolate with optional overrides.
+Future<IsolateRunner> startSearchIsolate({
+  Logger? logger,
+  bool removeTextContent = false,
+  String? snapshot,
+}) async {
+  return await startQueryIsolate(
+    logger: logger ?? _logger,
+    kind: removeTextContent ? 'reduced' : 'primary',
+    spawnUri: Uri.parse('package:pub_dev/service/entrypoint/search_index.dart'),
+    spawnArgs: [
+      if (snapshot != null) ...['--snapshot', snapshot],
+      if (removeTextContent) '--remove-text-content',
+    ],
+  );
+}
+
 /// Implementation of [SearchIndex] that uses [RequestMessage]s to send requests
 /// across isolate boundaries. The instance should be registered inside the
 /// `frontend` isolate, and it calls the `index` isolate as a delegate.
 class IsolateSearchIndex implements SearchIndex {
-  final IsolateRunner _runner;
-  IsolateSearchIndex(this._runner);
+  final IsolateRunner _primary;
+  final IsolateRunner _reduced;
+  IsolateSearchIndex(this._primary, this._reduced);
   var _isReady = false;
 
   @override
@@ -96,7 +121,7 @@ class IsolateSearchIndex implements SearchIndex {
   @override
   FutureOr<IndexInfo> indexInfo() async {
     try {
-      final info = await _runner.sendRequest(
+      final info = await _primary.sendRequest(
         'info',
         timeout: Duration(seconds: 5),
       );
@@ -114,7 +139,8 @@ class IsolateSearchIndex implements SearchIndex {
   @override
   FutureOr<PackageSearchResult> search(ServiceSearchQuery query) async {
     try {
-      final rs = await _runner.sendRequest(
+      final runner = query.parsedQuery.hasFreeText ? _primary : _reduced;
+      final rs = await runner.sendRequest(
         Uri(queryParameters: query.toUriQueryParameters()).toString(),
         timeout: Duration(minutes: 1),
       );