SuggestStoreProtocol

public protocol SuggestStoreProtocol : AnyObject

The store is the entry point to the Suggest component. It incrementally downloads suggestions from the Remote Settings service, stores them in a local database, and returns them in response to user queries.

Your application should create a single store, and manage it as a singleton. The store is thread-safe, and supports concurrent queries and ingests. We expect that your application will call [SuggestStore::query()] to show suggestions as the user types into the address bar, and periodically call [SuggestStore::ingest()] in the background to update the database with new suggestions from Remote Settings.

For responsiveness, we recommend always calling query() on a worker thread. When the user types new input into the address bar, call [SuggestStore::interrupt()] on the main thread to cancel the query for the old input, and unblock the worker thread for the new query.

The store keeps track of the state needed to support incremental ingestion, but doesn’t schedule the ingestion work itself, or decide how many suggestions to ingest at once. This is for two reasons:

  1. The primitives for scheduling background work vary between platforms, and aren’t available to the lower-level Rust layer. You might use an idle timer on Desktop, WorkManager on Android, or BGTaskScheduler on iOS.
  2. Ingestion constraints can change, depending on the platform and the needs of your application. A mobile device on a metered connection might want to request a small subset of the Suggest data and download the rest later, while a desktop on a fast link might download the entire dataset on the first launch.

  • Removes all content from the database.

    Declaration

    Swift

    func clear() throws

  • Clear dismissed suggestions

    Declaration

    Swift

    func clearDismissedSuggestions() throws

  • Dismiss a suggestion

    Dismissed suggestions will not be returned again

    In the case of AMP suggestions this should be the raw URL.

    Declaration

    Swift

    func dismissSuggestion(suggestionUrl: String) throws

  • Fetches geonames stored in the database. A geoname represents a geographic place.

    query is a string that will be matched directly against geoname names. It is not a query string in the usual Suggest sense. match_name_prefix determines whether prefix matching is performed on names excluding abbreviations and airport codes. When true, names that start with query will match. When false, names that equal query will match.

    geoname_type restricts returned geonames to a [GeonameType].

    filter restricts returned geonames to certain cities or regions. Cities can be restricted to regions by including the regions in filter, and regions can be restricted to those containing certain cities by including the cities in filter. This is especially useful since city and region names are not unique. filter is disjunctive: If any item in filter matches a geoname, the geoname will be filtered in.

    The query can match a single geoname in more than one way. For example, it can match both a full name and an abbreviation. The returned vec of [GeonameMatch] values will include all matches for a geoname, one match per match_type per geoname. In other words, a matched geoname can map to more than one GeonameMatch.

    Declaration

    Swift

    func fetchGeonames(query: String, matchNamePrefix: Bool, geonameType: GeonameType?, filter: [Geoname]?) throws -> [GeonameMatch]

  • Returns global Suggest configuration data.

    Declaration

    Swift

    func fetchGlobalConfig() throws -> SuggestGlobalConfig

  • Returns per-provider Suggest configuration data.

    Declaration

    Swift

    func fetchProviderConfig(provider: SuggestionProvider) throws -> SuggestProviderConfig?

  • Ingests new suggestions from Remote Settings.

    Declaration

    Swift

    func ingest(constraints: SuggestIngestionConstraints) throws -> SuggestIngestionMetrics

  • Interrupts any ongoing queries.

    This should be called when the user types new input into the address bar, to ensure that they see fresh suggestions as they type. This method does not interrupt any ongoing ingests.

    Declaration

    Swift

    func interrupt(kind: InterruptKind?)

  • Queries the database for suggestions.

    Declaration

    Swift

    func query(query: SuggestionQuery) throws -> [Suggestion]

  • Queries the database for suggestions.

    Declaration

    Swift

    func queryWithMetrics(query: SuggestionQuery) throws -> QueryWithMetricsResult