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

🔍 Extended Query Filtering

The Master and Complete Item query APIs now support a new optional filter argument: expression. This enhancement allows to apply advanced, KQL-based filtering on top of the standard faceting and filtering flow. It provides full control for building complex filter expressions—especially when working with additional properties.

Why this matters

Extended Query Filtering enables precise, multi-attribute filtering in a single request—resulting in accurate facets. For example, imagine a customer is looking for a jacket in color Blue and size M or S. These conditions are sent in the filter argument using a KQL expression. The backend returns only items whose additional properties match Color = Blue and Size = M or S.

The facetingParams argument (and the facets returned in the response) allow you to build the dynamic filters often found in e-commerce browsing, while the filter expression applies the selected filters so that only matching items are returned.

📌 What’s New?

facetingParams

Defines which standard properties (e.g. itemCategoryId, brand) and additional properties (e.g. Color, Size or Style) should be used to calculate top facet values displayed in the UI.

expression

A Kibana Query Language (KQL) string applied to the actual dataset before faceting options have been calculated. Use this to narrow search results based on user-selected filter conditions, including complex AND/OR logic.

🧠 How It Works

facetingParams → Builds the Facets

This determines which properties will appear as available filter options.

expression → Applies the Final Filter Logic

This applies the user’s actual selections to the results by executing a KQL expression, e.g.:

expression: "additionalProperties:{ id: Color and value: Blue } and additionalProperties: {id: Size and (value: S or value: M)}"

`facetingParams` Structure

facetingParams {
  propertyValuesCount: Int = 10
  properties: [FacetingProperty!]
}

propertyValuesCount

Default: 10
Determines how many top values are returned for each facet.
Values are ranked by number of items (descending).

properties

Each entry defines a facet source:

Field	Description
`isAdditionalProperty`	`true` → property comes from additional properties.
`propertyName`	If `isAdditionalProperty = true`: use the ID of the additional property. If `false`: use the standard property name.

To return facet data, the query must request facets:

facets {
  propertyName
  values {
    value
    count
  }
}

Usage Examples

Example 1 — Basic Faceting (no expression)

query {
  completeItems(
    searchTerm: "*"
    first: 10
    businessUnitId: "{{businessUnitId}}"
    facetingParams:  {
       propertyValuesCount: 5
       properties: [ 
        { propertyName: "brand" isAdditionalProperty: false },
        { propertyName: "Color" isAdditionalProperty: true }
      ]
    }
  ) {
    totalCount
    pageInfo {
      endCursor
      hasNextPage
    }
    facets {
      propertyName
      values {
        value
        count
      }
    }
    nodes {
      id
      name
      type
      businessUnitIds
      additionalProperties {
        ...
      }
      priceSpecifications {
       ...
      }
      itemIdentifiers {
        ...
      }
    }
  }
}

Result:

User sees available filters for brand and color, based on the top 5 values.

Example 2 — Using expression to filter results by additional properties

query {
  completeItems(
    searchTerm: "*"
    first: 10
    businessUnitId: "{{businessUnitId}}"
    facetingParams:  {
       propertyValuesCount: 9
       properties: [ 
        { propertyName: "brand" isAdditionalProperty: false },
        { propertyName: "Color" isAdditionalProperty: true }
      ]
    }
    filter: {
      expression: "additionalProperties:{ id: Color and value: Blue } and additionalProperties: {id: Size and (value: S or value: M)}"
    }
  ) {
    totalCount
    pageInfo {
      endCursor
      hasNextPage
    }
    facets {
      propertyName
      values {
        value
        count
      }
    }
    nodes {
      id
      name
      type
      businessUnitIds
      additionalProperties {
        ...
      }
      priceSpecifications {
       ...
      }
      itemIdentifiers {
        ...
      }
    }
  }
}

What happens:

First, the filter is applied to the dataset; then unique values for properties (facets) are calculated.
Then, the query filters items to only those where:
- Color = Blue
- Size = S or M

Example 3 — Combining Standard and Additional Filters

query {
  completeItems(
    searchTerm: "*"
    first: 10
    businessUnitId: "{{businessUnitId}}"
    facetingParams:  {
       propertyValuesCount: 3
       properties: [ 
        { propertyName: "brand" isAdditionalProperty: false},
        { propertyName: "Color" isAdditionalProperty: true },
        { propertyName: "Size" isAdditionalProperty: true },
      ]
    }
    filter: {
      expression: "brand: PnP AND additionalProperties:{ id: Color and value: Green } and additionalProperties: {id: Size and (value: 36 or value: 37)}"
    }
  ) {
    totalCount
    pageInfo {
      endCursor
      hasNextPage
    }
    facets {
      propertyName
      values {
        value
        count
      }
    }
    nodes {
      id
      ...
      priceSpecifications {
        ...
      }
      itemIdentifiers {
        ...
      }
    }
  }
}

This allows highly granular filtering behavior beyond traditional facet-based selections.

🧩 Summary

facetingParams defines which fields will become facets and how many values are shown.
expression applies complex KQL filters to the result set.
Always request facets in the query if you want them returned.

GraphQL Query API Search Capabilities

Query String Syntax​

.keyword Fields​

Supported Query Elements​

Reserved Characters​

Boolean Operators​

Field Names​

Search Multiple Fields​

Wildcards (Use with Care)​

Regular Expressions (Use with Care)​

Fuzziness​

Proximity Searches​

Ranges​

Boosting​

Grouping​

🔍 Extended Query Filtering​

Why this matters​

📌 What’s New?​

🧠 How It Works​

facetingParams Structure​

Making Facets visible in responses​

🧩 Summary​