Add Result container

.code-samples.meilisearch.yaml

@@ -3,6 +3,8 @@
 # the documentation on build
 # You can read more on https://github.com/meilisearch/documentation/tree/master/.vuepress/code-samples
 ---
+search_parameter_guide_show_ranking_score_1: |-
+  await client.index('movies').search('dragon', SearchQuery(showRankingScore: true));
 facet_search_2: |-
   await client.index('books').updateFaceting(Faceting(sortFacetValuesBy: {'genres': 'count'}));
 getting_started_faceting: |-

CONTRIBUTING.md

@@ -40,7 +40,7 @@ First of all, thank you for contributing to Meilisearch! The goal of this docume
 
 Install the official [Dart SDK](https://dart.dev/get-dart) or the [Flutter SDK](https://flutter.dev/docs/get-started/install) (which includes Dart SDK) using guides on the official website.
 
-Both of them include `pub`. But if you want to run the linter you need to install the Flutter SDK.
+Both of them include `pub`.
 
 ### Setup <!-- omit in TOC -->
 
@@ -54,13 +54,13 @@ docker-compose run --rm package bash -c "dart pub get && dart run test --concurr
 To install dependencies:
 
 ```bash
-pub get
+dart pub get
 ```
 
-Or if you are using Flutter SDK:
+This package relies on [build_runner](https://pub.dev/packages/build_runner) to generate serialization information for some models, to re-generate files after making any changes, run:
 
 ```bash
-flutter pub get
+dart run build_runner build
 ```
 
 ### Tests and Linter <!-- omit in TOC -->
@@ -71,9 +71,9 @@ Each PR should pass the tests and the linter to be accepted.
 # Tests
 curl -L https://install.meilisearch.com | sh # download Meilisearch
 ./meilisearch --master-key=masterKey --no-analytics # run Meilisearch
-pub run test --concurrency=4
+dart test
 # Linter
-flutter analyze
+dart analyze
 ```
 
 ## Git Guidelines

lib/src/client.dart

@@ -125,6 +125,35 @@
     return Task.fromMap(response.data!);
   }
 
+  /// Get the status of all experimental features that can be toggled at runtime
+  @RequiredMeiliServerVersion('1.3.0')
+  Future<ExperimentalFeatures> getExperimentalFeatures() async {
+    final response = await http.getMethod<Map<String, Object?>>(
+      '/experimental-features',
+    );
+    return ExperimentalFeatures.fromJson(response.data!);
+  }
+
+  /// Set the status of experimental features that can be toggled at runtime
+  @RequiredMeiliServerVersion('1.3.0')
+  Future<ExperimentalFeatures> updateExperimentalFeatures(
+    UpdateExperimentalFeatures input,
+  ) async {
+    final inputJson = input.toJson();
+    if (inputJson.isEmpty) {
+      throw ArgumentError.value(
+        input,
+        'input',
+        'input must contain at least one entry',
+      );
+    }
+    final response = await http.patchMethod<Map<String, Object?>>(
+      '/experimental-features',
+      data: input.toJson(),
+    );
+    return ExperimentalFeatures.fromJson(response.data!);
+  }
+
   /// Return health of the Meilisearch server.
   /// Throws an error if containing details if Meilisearch can't process your request.
   Future<Map<String, dynamic>> health() async {

lib/src/query_parameters/index_search_query.dart

@@ -29,6 +29,9 @@
     super.highlightPostTag,
     super.matchingStrategy,
     super.attributesToSearchOn,
+    super.showRankingScore,
+    super.vector,
+    super.showRankingScoreDetails,
   });
 
   @override
@@ -62,6 +65,9 @@
     String? highlightPostTag,
     MatchingStrategy? matchingStrategy,
     List<String>? attributesToSearchOn,
+    bool? showRankingScore,
+    List<dynamic /* double | List<double> */ >? vector,
+    bool? showRankingScoreDetails,
   }) =>
       IndexSearchQuery(
         query: query ?? this.query,
@@ -85,5 +91,9 @@
         highlightPostTag: highlightPostTag ?? this.highlightPostTag,
         matchingStrategy: matchingStrategy ?? this.matchingStrategy,
         attributesToSearchOn: attributesToSearchOn ?? this.attributesToSearchOn,
+        showRankingScore: showRankingScore ?? this.showRankingScore,
+        vector: vector ?? this.vector,
+        showRankingScoreDetails:
+            showRankingScoreDetails ?? this.showRankingScoreDetails,
       );
 }

lib/src/query_parameters/search_query.dart

@@ -1,4 +1,5 @@
 import 'package:meilisearch/meilisearch.dart';
+import 'package:meilisearch/src/annotations.dart';
 import 'queryable.dart';
 
 class SearchQuery extends Queryable {
@@ -20,6 +21,12 @@
   final String? highlightPostTag;
   final MatchingStrategy? matchingStrategy;
   final List<String>? attributesToSearchOn;
+  @RequiredMeiliServerVersion('1.3.0')
+  final bool? showRankingScore;
+  @RequiredMeiliServerVersion('1.3.0')
+  final bool? showRankingScoreDetails;
+  @RequiredMeiliServerVersion('1.3.0')
+  final List<dynamic /* double | List<double> */ >? vector;
 
   const SearchQuery({
     this.offset,
@@ -40,6 +47,9 @@
     this.highlightPostTag,
     this.matchingStrategy,
     this.attributesToSearchOn,
+    this.showRankingScore,
+    this.showRankingScoreDetails,
+    this.vector,
   });
 
   @override
@@ -62,6 +72,9 @@
       'highlightPostTag': highlightPostTag,
       'matchingStrategy': matchingStrategy?.name,
       'attributesToSearchOn': attributesToSearchOn,
+      'showRankingScore': showRankingScore,
+      'showRankingScoreDetails': showRankingScoreDetails,
+      'vector': vector,
     };
   }
 
@@ -84,6 +97,9 @@
     String? highlightPostTag,
     MatchingStrategy? matchingStrategy,
     List<String>? attributesToSearchOn,
+    bool? showRankingScore,
+    List<dynamic>? vector,
+    bool? showRankingScoreDetails,
   }) =>
       SearchQuery(
         offset: offset ?? this.offset,
@@ -105,5 +121,9 @@
         highlightPostTag: highlightPostTag ?? this.highlightPostTag,
         matchingStrategy: matchingStrategy ?? this.matchingStrategy,
         attributesToSearchOn: attributesToSearchOn ?? this.attributesToSearchOn,
+        showRankingScore: showRankingScore ?? this.showRankingScore,
+        vector: vector ?? this.vector,
+        showRankingScoreDetails:
+            showRankingScoreDetails ?? this.showRankingScoreDetails,
       );
 }

lib/src/results/_exports.dart

@@ -12,3 +12,6 @@ export 'matching_strategy_enum.dart';
 export 'index_stats.dart';
 export 'all_stats.dart';
 export 'facet_stat.dart';
+export 'document_container.dart';
+export 'ranking_rules/_exports.dart';
+export 'experimental_features.dart';

lib/src/results/document_container.dart

@@ -0,0 +1,163 @@
+import 'package:meilisearch/src/annotations.dart';
+
+import 'match_position.dart';
+import 'ranking_rules/base.dart';
+import 'searchable.dart';
+
+/// A class that wraps around documents returned from meilisearch to provide useful information.
+final class MeiliDocumentContainer<T extends Object> {
+  const MeiliDocumentContainer._({
+    required this.rankingScoreDetails,
+    required this.src,
+    required this.parsed,
+    required this.formatted,
+    required this.vectors,
+    required this.semanticScore,
+    required this.rankingScore,
+    required this.matchesPosition,
+  });
+
+  final Map<String, dynamic> src;
+  final T parsed;
+  final Map<String, dynamic>? formatted;
+  @RequiredMeiliServerVersion('1.3.0')
+  final List<dynamic /* double | List<double> */ >? vectors;
+  @RequiredMeiliServerVersion('1.3.0')
+  final double? semanticScore;
+  @RequiredMeiliServerVersion('1.3.0')
+  final double? rankingScore;
+  @RequiredMeiliServerVersion('1.3.0')
+  final MeiliRankingScoreDetails? rankingScoreDetails;
+
+  /// Contains the location of each occurrence of queried terms across all fields
+  final Map<String, List<MatchPosition>>? matchesPosition;
+
+  dynamic operator [](String key) => src[key];
+  dynamic getFormatted(String key) => formatted?[key];
+
+  dynamic getFormattedOrSrc(String key) => getFormatted(key) ?? this[key];
+
+  static MeiliDocumentContainer<Map<String, dynamic>> fromJson(
+    Map<String, dynamic> src,
+  ) {
+    final rankingScoreDetails =
+        src['_rankingScoreDetails'] as Map<String, dynamic>?;
+    return MeiliDocumentContainer<Map<String, dynamic>>._(
+      src: src,
+      parsed: src,
+      formatted: src['_formatted'] as Map<String, dynamic>?,
+      vectors: src['_vectors'] as List?,
+      semanticScore: src['_semanticScore'] as double?,
+      rankingScore: src['_rankingScore'] as double?,
+      matchesPosition: _readMatchesPosition(src),
+      rankingScoreDetails: rankingScoreDetails == null
+          ? null
+          : MeiliRankingScoreDetails.fromJson(rankingScoreDetails),
+    );
+  }
+
+  MeiliDocumentContainer<TOther> map<TOther extends Object>(
+    MeilisearchDocumentMapper<T, TOther> mapper,
+  ) {
+    return MeiliDocumentContainer._(
+        src: src,
+        parsed: mapper(parsed),
+        formatted: formatted,
+        vectors: vectors,
+        semanticScore: semanticScore,
+        rankingScore: rankingScore,
+        rankingScoreDetails: rankingScoreDetails,
+        matchesPosition: matchesPosition);
+  }
+
+  @override
+  String toString() => src.toString();
+}
+
+class MeiliRankingScoreDetails {
+  const MeiliRankingScoreDetails._({
+    required this.src,
+    required this.words,
+    required this.typo,
+    required this.proximity,
+    required this.attribute,
+    required this.exactness,
+    required this.customRules,
+  });
+  final Map<String, dynamic> src;
+  final MeiliRankingScoreDetailsWordsRule? words;
+  final MeiliRankingScoreDetailsTypoRule? typo;
+  final MeiliRankingScoreDetailsProximityRule? proximity;
+  final MeiliRankingScoreDetailsAttributeRule? attribute;
+  final MeiliRankingScoreDetailsExactnessRule? exactness;
+  final Map<String, MeiliRankingScoreDetailsCustomRule> customRules;
+
+  factory MeiliRankingScoreDetails.fromJson(Map<String, dynamic> src) {
+    final reservedKeys = {
+      'attribute',
+      'words',
+      'exactness',
+      'proximity',
+      'typo',
+    };
+
+    T? ruleGuarded<T>(
+      String key,
+      T Function(Map<String, dynamic> src) mapper,
+    ) {
+      final v = src[key];
+      if (v == null) {
+        return null;
+      }
+      return mapper(v as Map<String, dynamic>);
+    }
+
+    return MeiliRankingScoreDetails._(
+      src: src,
+      attribute: ruleGuarded(
+        'attribute',
+        MeiliRankingScoreDetailsAttributeRule.fromJson,
+      ),
+      words: ruleGuarded(
+        'words',
+        MeiliRankingScoreDetailsWordsRule.fromJson,
+      ),
+      exactness: ruleGuarded(
+        'exactness',
+        MeiliRankingScoreDetailsExactnessRule.fromJson,
+      ),
+      proximity: ruleGuarded(
+        'proximity',
+        MeiliRankingScoreDetailsProximityRule.fromJson,
+      ),
+      typo: ruleGuarded(
+        'typo',
+        MeiliRankingScoreDetailsTypoRule.fromJson,
+      ),
+      customRules: {
+        for (var custom in src.entries
+            .where((element) => !reservedKeys.contains(element.key)))
+          custom.key: MeiliRankingScoreDetailsCustomRule.fromJson(
+            custom.value as Map<String, dynamic>,
+          )
+      },
+    );
+  }
+}
+
+Map<String, List<MatchPosition>>? _readMatchesPosition(
+  Map<String, Object?> map,
+) {
+  final src = map['_matchesPosition'];
+
+  if (src == null) return null;
+
+  return (src as Map<String, Object?>).map(
+    (key, value) => MapEntry(
+      key,
+      (value as List<Object?>)
+          .map((e) => MatchPosition.fromMap(e as Map<String, Object?>))
+          .toList(),
+    ),
+  );
+}

lib/src/results/experimental_features.dart

@@ -0,0 +1,42 @@
+import 'package:json_annotation/json_annotation.dart';
+
+part 'experimental_features.g.dart';
+
+@JsonSerializable(
+  createFactory: true,
+  createToJson: false,
+)
+class ExperimentalFeatures {
+  @JsonKey(name: 'vectorStore')
+  final bool vectorStore;
+  @JsonKey(name: 'scoreDetails')
+  final bool scoreDetails;
+
+  const ExperimentalFeatures({
+    required this.vectorStore,
+    required this.scoreDetails,
+  });
+
+  factory ExperimentalFeatures.fromJson(Map<String, dynamic> src) {
+    return _$ExperimentalFeaturesFromJson(src);
+  }
+}
+
+@JsonSerializable(
+  includeIfNull: false,
+  createToJson: true,
+  createFactory: false,
+)
+class UpdateExperimentalFeatures {
+  @JsonKey(name: 'vectorStore')
+  final bool? vectorStore;
+  @JsonKey(name: 'scoreDetails')
+  final bool? scoreDetails;
+
+  const UpdateExperimentalFeatures({
+    this.vectorStore,
+    this.scoreDetails,
+  });
+
+  Map<String, dynamic> toJson() => _$UpdateExperimentalFeaturesToJson(this);
+}