Skip to main content

Search term

GraphQL Query API Search Capabilities

Hii Retail provides GraphQL Query APIs with built-in free-text search. See more here.

This section describes advanced free-text search capabilities.

Query String Syntax​

A query string uses specific syntax with operators (AND, OR). The default operator is OR.

A query string can be a single word (bottle), a phrase in double quotes ("bright and bubbly"), or use operators.

Recommendation: Avoid heavy use of special syntax (wildcards, regex) unless necessary, as it can impact performance.

Invalid syntax in searchTerm returns an error; handle this in your search components.

.keyword Fields​

A field with .keyword suffix (e.g., name.keyword) matches the exact value, useful for structured content (e.g., email addresses).

  • name: "Fizzy Drink 1" matches if the phrase appears anywhere in name.
  • name.keyword: "Fizzy Drink 1" matches only if the field is exactly that value.
  • .keyword is required for wildcards.

Supported Query Elements​

Reserved Characters​

Escape reserved characters with a backslash. In JSON, use two backslashes. Reserved: + - = && || > < ! ( ) { } [ ] ^ " ~ * ? : \ /

Examples:

  • \(1\+1\)\=2 — searches for (1+1)=2
  • \\(1\\+1\\)\\=2 — same query in JSON

Boolean Operators​

Supported: + (must be present), - (must not be present), AND, OR, NOT.

Examples:

  • bottle can +soda -fizzy — soda must be present, fizzy must not, bottle and can are optional
  • ((bottle AND soda) OR (can AND soda) OR soda) AND NOT fizzy — same as above, using operators

Field Names​

  • businessUnitId.keyword:1-1 — exact match
  • status: ACTIVE — contains ACTIVE
  • name:(bottle OR flask) — contains bottle or flask
  • description: "heavy duty fabric" — contains the exact phrase
  • assortment\*:(IN_ASSORTMENT, C) — matches fields like assortmentType or assortmentTags
  • _exists_:description — field has any non-null value

Search Multiple Fields​

  • businessUnitId:AW001 AND status:ACTIVE — both fields must match

Wildcards (Use with Care)​

  • p?nk XX* — ? for single character, * for zero or more
  • field:* — matches any value (including empty)

Wildcards at the start of a word (e.g., *ing) are not supported for performance reasons.

Regular Expressions (Use with Care)​

See Elasticsearch regex syntax.

  • name:/joh?n(ath[oa]n)/ — regex pattern

Patterns like /.*n/ are not supported for performance reasons.

Fuzziness​

  • quikc~ brwn~ foks~3 — fuzzy queries with edit distance (default 2)
  • app*~1 — mixing fuzzy and wildcard is not supported

Proximity Searches​

  • "fox quick"~5 — words can be up to 5 words apart or in different order

Ranges​

Ranges for date, numeric, or string fields:

  • validFrom:[2022-01-01 TO 2022-12-31] — inclusive
  • netContent:[1 TO 5] — numbers 1 to 5
  • assortmentTags:{A TO D} — exclusive
  • netContent:[10 TO *] — from 10 upwards
  • referencePriceConversionFactor:>1 — greater than 1
  • referencePriceConversionFactor:<=0.9 — less than or equal to 0.9

Boosting​

Use ^ to boost relevance:

  • bottle^2 soda — prioritize bottle
  • "soda bottle"^2 — boost phrase
  • (soda can)^4 — boost group

Grouping​

  • (bottle OR can) AND soda - multiple terms or clauses can be grouped together with parentheses to form sub-queries
  • status:(ACTIVE OR DISCONTINUED) name:(bright and bubbly)^2 - groups can be used to target a particular field, or to boost the result of a sub-query