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.

  • Return whether any suggestions have been dismissed.

    Declaration

    Swift

    func anyDismissedSuggestions() throws -> Bool

  • Removes all content from the database.

    Declaration

    Swift

    func clear() throws

  • Clear dismissed suggestions

    Declaration

    Swift

    func clearDismissedSuggestions() throws

  • Dismiss a suggestion by its dismissal key.

    Dismissed suggestions cannot be fetched again.

    Prefer [SuggestStore::dismiss_by_suggestion] if you have a crate::Suggestion. This method is intended for cases where a suggestion originates outside this component.

    Declaration

    Swift

    func dismissByKey(key: String) throws

  • Dismiss a suggestion.

    Dismissed suggestions cannot be fetched again.

    Declaration

    Swift

    func dismissBySuggestion(suggestion: Suggestion) throws

  • Deprecated, use [SuggestStore::dismiss_by_suggestion] or [SuggestStore::dismiss_by_key] instead.

    Dismiss a suggestion

    Dismissed suggestions will not be returned again

    Declaration

    Swift

    func dismissSuggestion(suggestionUrl: String) throws

  • Fetches a geoname’s names stored in the database.

    See fetch_geoname_alternates in geoname.rs for documentation.

    Declaration

    Swift

    func fetchGeonameAlternates(geoname: Geoname) throws -> GeonameAlternates

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

    See fetch_geonames in geoname.rs for documentation.

    Declaration

    Swift

    func fetchGeonames(query: String, matchNamePrefix: Bool, 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?)

  • Return whether a suggestion has been dismissed given its dismissal key.

    [SuggestStore::query] will never return dismissed suggestions, so normally you never need to know whether a suggestion has been dismissed. This method is intended for cases where a dismissal key originates outside this component.

    Declaration

    Swift

    func isDismissedByKey(key: String) throws -> Bool

  • Return whether a suggestion has been dismissed.

    [SuggestStore::query] will never return dismissed suggestions, so normally you never need to know whether a Suggestion has been dismissed, but this method can be used to do so.

    Declaration

    Swift

    func isDismissedBySuggestion(suggestion: Suggestion) throws -> Bool

  • 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