Query

@objc
open class Query : AbstractQuery

Describes all parameters of a search query.

There are two ways to access parameters:

  1. Using the high-level, typed properties for individual parameters (recommended).
  2. Using the low-level, untyped accessors parameter(withName:) and setParameter(withName:to:) or (better) the subscript operator. Use this approach if the parameter you wish to set is not supported by this class.

Warning

All parameters are optional. When a parameter is nil, the API applies a default value.
  • The instant-search query string, all words of the query are interpreted as prefixes (for example “John Mc” will match “John Mccamey” and “Johnathan Mccamey”). If no query parameter is set, retrieves all objects.

    Declaration

    Swift

    @objc
    public var query: String? { get set }
  • Values applicable to the queryType parameter.

    See more

    Declaration

    Swift

    public enum QueryType : String
  • Selects how the query words are interpreted:

    • prefixAll: all query words are interpreted as prefixes
    • prefixLast: only the last word is interpreted as a prefix (default behavior)
    • prefixNone: no query word is interpreted as a prefix. This option is not recommended.

    Declaration

    Swift

    public var queryType: QueryType? { get set }
  • Values applicable to the typoTolerance parameter.

    See more

    Declaration

    Swift

    public enum TypoTolerance : String
  • This setting has four different options:

    • true: activate the typo-tolerance.
    • false: disable the typo-tolerance.
    • min: keep only results with the lowest number of typo. For example if one result match without typos, then all results with typos will be hidden.
    • strict: if there is a match without typo, then all results with 2 typos or more will be removed. This option is useful if you want to avoid as much as possible false positive.

    Declaration

    Swift

    public var typoTolerance: TypoTolerance? { get set }
  • The minimum number of characters in a query word to accept one typo in this word.

    Declaration

    Swift

    public var minWordSizefor1Typo: UInt? { get set }
  • The minimum number of characters in a query word to accept two typos in this word.

    Declaration

    Swift

    public var minWordSizefor2Typos: UInt? { get set }
  • If set to false, disable typo-tolerance on numeric tokens (=numbers) in the query word. For example the query 304 will match with 30450, but not with 40450 that would have been the case with typo-tolerance enabled. Can be very useful on serial numbers and zip codes searches.

    Declaration

    Swift

    public var allowTyposOnNumericTokens: Bool? { get set }
  • Applicable values for the ignorePlurals parameter.

    See more

    Declaration

    Swift

    public enum IgnorePlurals : Equatable
  • Consider singular and plurals forms alike to be a match without typo. For example, car and cars, or foot and feet, will be considered equivalent. This parameter can be:

    You may enable this option for all languages at once (.all) or for a specific subset (.selected).

    Declaration

    Swift

    public var ignorePlurals: IgnorePlurals? { get set }
  • List of attributes you want to use for textual search (must be a subset of the searchableAttributes index setting). Attributes are separated with a comma (for example name,address ), you can also use a JSON string array encoding (for example encodeURIComponent(‘[name,address]’) ). By default, all attributes specified in searchableAttributes settings are used to search.

    Declaration

    Swift

    @objc
    public var restrictSearchableAttributes: [String]? { get set }
  • List of contexts for which rules are enabled. Contextual rules matching any of these contexts are eligible, as well as generic rules. When empty, only generic rules are eligible.

    Declaration

    Swift

    @objc
    public var ruleContexts: [String]? { get set }
  • If set to false, rules processing is disabled: no rule will match the query. Defaults to true.

    Declaration

    Swift

    public var enableRules: Bool? { get set }
  • Enable the advanced query syntax.

    Declaration

    Swift

    public var advancedSyntax: Bool? { get set }
  • If set to false, this query will not be taken into account for the Analytics.

    Declaration

    Swift

    public var analytics: Bool? { get set }
  • If set, tag your query with the specified identifiers. Tags can then be used in the Analytics to analyze a subset of searches only.

    Declaration

    Swift

    @objc
    public var analyticsTags: [String]? { get set }
  • If set to false, this query will not use synonyms defined in configuration.

    Declaration

    Swift

    public var synonyms: Bool? { get set }
  • If set to false, words matched via synonyms expansion will not be replaced by the matched synonym in the highlighted result.

    Declaration

    Swift

    public var replaceSynonymsInHighlight: Bool? { get set }
  • Specify a list of words that should be considered as optional when found in the query. This list will be appended to the one defined in your index settings.

    Declaration

    Swift

    @objc
    public var optionalWords: [String]? { get set }
  • Configure the precision of the proximity ranking criterion. By default, the minimum (and best) proximity value distance between 2 matching words is 1. Setting it to 2 (or 3) would allow 1 (or 2) words to be found between the matching words without degrading the proximity ranking value.

    Considering the query “javascript framework”, if you set minProximity=2 the records “JavaScript framework” and “JavaScript charting framework” will get the same proximity score, even if the second one contains a word between the 2 matching words.

    Declaration

    Swift

    public var minProximity: UInt? { get set }
  • Applicable values for the removeWordsIfNoResults parameter.

    See more

    Declaration

    Swift

    public enum RemoveWordsIfNoResults : String
  • Configure the way query words are removed when the query doesn’t retrieve any results. This option can be used to avoid having an empty result page. There are four different options:

    • lastWords: when a query does not return any result, the last word will be added as optionalWords (the process is repeated with the n-1 word, n-2 word, … until there is results). This option is particularly useful on e-commerce websites
    • firstWords: when a query does not return any result, the first word will be added as optionalWords (the process is repeated with the second word, third word, … until there is results). This option is useful on address search
    • allOptional: When a query does not return any result, a second trial will be made with all words as optional (which is equivalent to transforming the AND operand between query terms in a OR operand)
    • none: No specific processing is done when a query does not return any result.

    Declaration

    Swift

    public var removeWordsIfNoResults: RemoveWordsIfNoResults? { get set }
  • List of attributes on which you want to disable typo tolerance (must be a subset of the searchableAttributes index setting).

    Declaration

    Swift

    @objc
    public var disableTypoToleranceOnAttributes: [String]? { get set }
  • Applicable values for the removeStopWords parameter.

    See more

    Declaration

    Swift

    public enum RemoveStopWords : Equatable
  • Remove stop words from query before executing it. It can be a boolean: enable or disable all 41 supported languages or a comma separated string with the list of languages you have in your record (using language iso code). In most use-cases, we don’t recommend enabling this option.

    Stop words removal is applied on query words that are not interpreted as a prefix. The behavior depends of the queryType parameter:

    • queryType=prefixLast means the last query word is a prefix and it won’t be considered for stop words removal
    • queryType=prefixNone means no query word are prefix, stop words removal will be applied on all query words
    • queryType=prefixAll means all query terms are prefix, stop words won’t be removed

    This parameter is useful when you have a query in natural language like “what is a record?”. In this case, before executing the query, we will remove “what”, “is” and “a” in order to just search for “record”. This removal will remove false positive because of stop words, especially when combined with optional words. For most use cases, it is better to do not use this feature as people search by keywords on search engines.

    Declaration

    Swift

    public var removeStopWords: RemoveStopWords? { get set }
  • List of attributes on which you want to disable computation of the exact ranking criterion The list must be a subset of the searchableAttributes index setting.

    Declaration

    Swift

    @objc
    public var disableExactOnAttributes: [String]? { get set }
  • Applicable values for the exactOnSingleWordQuery parameter.

    See more

    Declaration

    Swift

    public enum ExactOnSingleWordQuery : String
  • This parameter control how the exact ranking criterion is computed when the query contains one word.

    Declaration

    Swift

    public var exactOnSingleWordQuery: ExactOnSingleWordQuery? { get set }
  • Applicable values for the alternativesAsExact parameter.

    See more

    Declaration

    Swift

    public enum AlternativesAsExact : String
  • Specify the list of approximation that should be considered as an exact match in the ranking formula.

    • ignorePlurals: alternative word added by the ignore plurals feature
    • singleWordSynonym: single word synonym (For example “NY” = “NYC”)
    • multiWordsSynonym: synonym over multiple words (For example “NY” = “New York”)

    The default value is ignorePlurals,singleWordSynonym.

    Declaration

    Swift

    public var alternativesAsExact: [AlternativesAsExact]? { get set }
  • Pagination parameter used to select the page to retrieve. Page is zero-based and defaults to 0. Thus, to retrieve the 10th page you need to set page=9

    Declaration

    Swift

    public var page: UInt? { get set }
  • Pagination parameter used to select the number of hits per page. Defaults to 20.

    Declaration

    Swift

    public var hitsPerPage: UInt? { get set }
  • Offset of the first hit to return (zero-based).

    Note

    In most cases, page/hitsPerPage is the recommended method for pagination.

    Declaration

    Swift

    public var offset: UInt? { get set }
  • Maximum number of hits to return. (1000 is the maximum)

    +Note: In most cases, page/hitsPerPage is the recommended method for pagination.

    Declaration

    Swift

    public var length: UInt? { get set }
  • List of object attributes you want to retrieve (let you minimize the answer size). You can also use * to retrieve all values when an attributesToRetrieve setting is specified for your index. By default all attributes are retrieved.

    Declaration

    Swift

    @objc
    public var attributesToRetrieve: [String]? { get set }
  • List of attributes you want to highlight according to the query. If an attribute has no match for the query, the raw value is returned. By default all indexed text attributes are highlighted. You can use * if you want to highlight all textual attributes. Numerical attributes are not highlighted. A matchLevel is returned for each highlighted attribute and can contain:

    • full: if all the query terms were found in the attribute
    • partial: if only some of the query terms were found
    • none: if none of the query terms were found

    Declaration

    Swift

    @objc
    public var attributesToHighlight: [String]? { get set }
  • List of attributes to snippet alongside the number of words to return (syntax is attributeName:nbWords). By default no snippet is computed.

    Declaration

    Swift

    @objc
    public var attributesToSnippet: [String]? { get set }
  • If set to true, the result hits will contain ranking information in _rankingInfo attribute.

    Declaration

    Swift

    public var getRankingInfo: Bool? { get set }
  • Specify the string that is inserted before the highlighted parts in the query result (defaults to <em>).

    Declaration

    Swift

    @objc
    public var highlightPreTag: String? { get set }
  • Specify the string that is inserted after the highlighted parts in the query result (defaults to </em>)

    Declaration

    Swift

    @objc
    public var highlightPostTag: String? { get set }
  • String used as an ellipsis indicator when a snippet is truncated (defaults to empty).

    Declaration

    Swift

    @objc
    public var snippetEllipsisText: String? { get set }
  • Restrict arrays in highlight and snippet results to items that matched the query. (defaults to false). When false, all array items are highlighted/snippeted. When true, only array items that matched at least partially are highlighted/snippeted.

    Declaration

    Swift

    public var restrictHighlightAndSnippetArrays: Bool? { get set }
  • Filter on numeric attributes.

    Declaration

    Swift

    @objc
    public var numericFilters: [Any]? { get set }
  • Filter the query by a set of tags.

    Declaration

    Swift

    @objc
    public var tagFilters: [Any]? { get set }
  • Enable the distinct feature (disabled by default) if the attributeForDistinct index setting is set. This feature is similar to the SQL “distinct” keyword: when enabled in a query with the distinct=1 parameter, all hits containing a duplicate value for the attributeForDistinct attribute are removed from results. For example, if the chosen attribute is _showname and several hits have the same value for _showname, then only the best one is kept and others are removed.

    Declaration

    Swift

    public var distinct: UInt? { get set }
  • List of object attributes that you want to use for faceting. Only attributes that have been added in attributesForFaceting index setting can be used in this parameter. You can also use * to perform faceting on all attributes specified in attributesForFaceting. If the number of results is important, the count can be approximate, the attribute exhaustiveFacetsCount in the response is true when the count is exact.

    Declaration

    Swift

    @objc
    public var facets: [String]? { get set }
  • Filter the query by a list of facets.

    Declaration

    Swift

    @objc
    public var facetFilters: [Any]? { get set }
  • Limit the number of facet values returned for each facet. For example: maxValuesPerFacet=10 will retrieve max 10 values per facet.

    Declaration

    Swift

    public var maxValuesPerFacet: UInt? { get set }
  • Force faceting to be applied after de-duplication.

    Warning

    There are strong requirements and caveats to this feature (including a performance impact), so please refer to the online documentation before enabling it.

    Declaration

    Swift

    public var facetingAfterDistinct: Bool? { get set }
  • Filter the query with numeric, facet or/and tag filters. The syntax is a SQL like syntax, you can use the OR and AND keywords. The syntax for the underlying numeric, facet and tag filters is the same than in the other filters:

    available=1 AND (category:Book OR NOT category:Ebook) AND _publicationdate: 1441745506 TO 1441755506
    AND inStock > 0 AND author:"John Doe"
    

    The list of keywords is:

    • OR: create a disjunctive filter between two filters.
    • AND: create a conjunctive filter between two filters.
    • TO: used to specify a range for a numeric filter.
    • NOT: used to negate a filter. The syntax with the - isn’t allowed.

    Declaration

    Swift

    @objc
    public var filters: String? { get set }
  • Search for entries around a given latitude/longitude. You can specify the maximum distance in meters with the aroundRadius parameter but we recommend to let it unset and let our automatic radius computation adapt it depending of the density of the are. At indexing, you should specify the geo-location of an object with the _geoloc attribute (in the form "_geoloc":{"lat":48.853409, "lng":2.348800} or "_geoloc":[{"lat":48.853409, "lng":2.348800},{"lat":48.547456, "lng":2.972075}] if you have several geo-locations in your record).

    Declaration

    Swift

    @objc
    public var aroundLatLng: LatLng? { get set }
  • Same than aroundLatLng but using IP geolocation instead of manually specified latitude/longitude.

    Declaration

    Swift

    public var aroundLatLngViaIP: Bool? { get set }
  • Applicable values for the aroundRadius parameter.

    See more

    Declaration

    Swift

    public enum AroundRadius : Equatable
  • Control the radius associated with a aroundLatLng or aroundLatLngViaIP query. If not set, the radius is computed automatically using the density of the area. You can retrieve the computed radius in the automaticRadius attribute of the answer. You can also specify a minimum value for the automatic radius by using the minimumAroundRadius query parameter. You can specify .all if you want to compute the geo distance without filtering in a geo area (this option will be faster than specifying a big integer).

    Declaration

    Swift

    public var aroundRadius: AroundRadius? { get set }
  • Control the precision of a aroundLatLng query. In meter. For example if you set aroundPrecision=100, two objects that are in the range 0-99m will be considered as identical in the ranking for the .variable geo ranking parameter (same for 100-199, 200-299, … ranges).

    Declaration

    Swift

    public var aroundPrecision: UInt? { get set }
  • Define the minimum radius used for aroundLatLng or aroundLatLngViaIP when aroundRadius is not set. The radius is computed automatically using the density of the area. You can retrieve the computed radius in the automaticRadius attribute of the answer.

    Declaration

    Swift

    public var minimumAroundRadius: UInt? { get set }
  • Search for entries inside a given area defined by the two extreme points of a rectangle. You can use several bounding boxes (OR) by passing more than 1 value.

    Declaration

    Swift

    @objc
    public var insideBoundingBox: [GeoRect]? { get set }
  • Search entries inside a given area defined by a union of polygons. Each polygon must be defined by a minimum of 3 points.

    Declaration

    Swift

    @objc
    public var insidePolygon: [[LatLng]]? { get set }
  • Values applicable to the sortFacetValuesBy parameter.

    See more

    Declaration

    Swift

    public enum SortFacetValuesBy : String
  • Controls how the facet values are sorted within each faceted attribute.

    Declaration

    Swift

    public var sortFacetValuesBy: SortFacetValuesBy? { get set }
  • Choose which fields the response will contain. Applies to search and browse queries.

    By default, all fields are returned. If this parameter is specified, only the fields explicitly listed will be returned, unless * is used, in which case all fields are returned. Specifying an empty list or unknown field names is an error.

    This parameter is mainly intended to limit the response size. For example, for complex queries, echoing of request parameters in the response’s params field can be undesirable.

    Some fields cannot be filtered out:

    • warning message
    • cursor in browse queries
    • fields triggered explicitly via getRankingInfo

    Declaration

    Swift

    @objc
    public var responseFields: [String]? { get set }
  • Maximum number of facet hits to return during a search for facet values.

    Note

    Does not apply to regular search queries.

    Note

    For performance reasons, the maximum allowed number of returned values is 100. Any value outside the range [1, 100] will be rejected.

    Declaration

    Swift

    public var maxFacetHits: UInt? { get set }
  • Whether to include the query in processing time percentile computation.

    When true, the API records the processing time of the search query and includes it when computing the 90% and 99% percentiles, available in your Algolia dashboard. When false, the search query is excluded from percentile computation.

    Declaration

    Swift

    public var percentileComputation: Bool? { get set }
  • Construct a query with the specified full text query.

    Declaration

    Swift

    @objc
    public convenience init(query: String?)
  • Clone an existing query.

    Declaration

    Swift

    @objc
    public convenience init(copy: Query)
  • Support for NSCopying.

    Note

    Primarily intended for Objective-C use. Swift coders should use init(copy:).

    Declaration

    Swift

    @objc
    open override func copy(with zone: NSZone?) -> Any
  • Parse a query from a URL query string.

    Declaration

    Swift

    @objc
    public static func parse(_ queryString: String) -> Query