Search engines¶

Tune what a search returns and in what order. A product search engine holds the search steps (field weights, typo tolerance, stock and hidden-product handling), boosts, elevates, excludes and personalization behind a website's search configs. Content search engines run the link content queries (categories, site pages, blog posts, brands) shown alongside product results.

Two things set engines apart from the rest of the Search tools:

• No draft. A search config has a draft and a live state; its engine has neither. An edit to an engine is live for every config using it as soon as it is saved. Boosts can take up to five minutes to reach every search, the lifetime of their cache.
• Shared. Every search config references exactly one product engine, and most websites have a single engine serving all of theirs. search_listProductEngines shows which configs each engine serves, so check that before you edit. To try a different tuning without touching live search, create a second engine, point a config at it with search_setConfigProductEngine, and publish that draft from My Hello Retail.

Tips & tricks¶

Pick the card that matches what you're doing. Each prompt is ready to paste into your assistant.

List the product search engines for my website and which search configs use each one.

Show the boosts on my product search engine, then boost the brand Nike by 2 and bury the brand Adidas by -2.

When someone searches for "running shoes", pin <PRODUCT URL> to the top of the results on my product search engine.

Create a product search engine called "Title first" with title weighted 5 and brand 1, point my mobile search config at it, and tell me where to publish the draft.

search_listProductEngines¶

List the product search engines of a website. A product search engine holds the tuning that decides which products a search returns and in which order: search steps, boosts, elevates, excludes and personalization. usedByConfigKeys names the search configs each engine serves, which is the blast radius of an edit. Most websites have a single engine shared by all their search configs.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_listProductEngines",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

[
  {
    "id": 0,
    "name": "<string>",
    "createdAt": "<string>",
    "modifiedAt": "<string>",
    "stepCount": 1,
    "usedByConfigKeys": [
      "<string>"
    ]
  }
]

search_getProductEngine¶

Get the full settings of one product search engine. Search steps run in order and the search stops at the first step that finds results, so later steps are fallbacks; typically each step relaxes the matching of the one before it. Within a step, fields maps a field name to its relative weight on match relevance, and availableStepFields lists the names a step can weight. The step fields are described under search_updateProductEngine.

exactProductNumberSearch prepends an implicit exact product-number step. filterByGroupingKey collapses product variants sharing a grouping key into one result. facetLimit is the maximum number of filter values returned per field, read-only here.

Boosts, elevates, excludes and personalization are read with their own tools: search_getProductEngineBoosts, search_getProductEngineElevates, search_getProductEngineExcludes and search_getPersonalization.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_getProductEngine",
    "arguments": {
      "websiteUuid": "<string>",
      "engineId": 0
    }
  }
}

{
  "id": 0,
  "name": "<string>",
  "exactProductNumberSearch": false,
  "filterByGroupingKey": false,
  "useAdditionalSearchTerms": false,
  "facetLimit": 100,
  "searchSteps": [
    {
      "fields": {
        "title": 3,
        "keywords": 2,
        "brand": 1
      },
      "minimumShouldMatch": "1",
      "fuzzy": true,
      "fuzzNumbers": true,
      "exactMatch": false,
      "splitSearchString": false,
      "showOutOfStock": false,
      "showHiddenProducts": false,
      "productScoreBoost": 0.0
    }
  ],
  "availableStepFields": [
    "productNumber",
    "title",
    "keywords",
    "description",
    "brand",
    "hierarchies"
  ]
}

search_updateProductEngine¶

Update the settings of a product search engine. All parameters are optional and updates are partial: omitted fields are left unchanged. searchSteps is a full replacement when provided, so read the current steps with search_getProductEngine first and pass every field of every step explicitly.

Each step has these fields, and all of them are required:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_updateProductEngine",
    "arguments": {
      "websiteUuid": "<string>",
      "engineId": 0,
      "filterByGroupingKey": true,
      "searchSteps": [
        {
          "fields": {
            "title": 5,
            "keywords": 2,
            "brand": 1
          },
          "minimumShouldMatch": "100%",
          "fuzzy": false,
          "fuzzNumbers": true,
          "exactMatch": false,
          "splitSearchString": false,
          "showOutOfStock": false,
          "showHiddenProducts": false,
          "productScoreBoost": 0.5
        }
      ]
    }
  }
}

search_createProductEngine¶

Create an additional product search engine with default settings, for example to try an alternative tuning without touching the engine live configs use. The new engine serves no search config until one is pointed at it with search_setConfigProductEngine.

Most websites need only their one existing engine, so prefer tuning that one unless a separate engine is genuinely wanted.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_createProductEngine",
    "arguments": {
      "websiteUuid": "<string>",
      "name": "Title first"
    }
  }
}

search_getProductEngineBoosts¶

Get the boosts of a product search engine. A boost raises (positive) or lowers (negative) the relevance of every product whose field has value, such as brand Nike by 2. The boost is an integer from -10 to 10, the same scale as the dashboard. formattedValue is the value as the dashboard shows it; hierarchy values render kids$shoes as Kids > Shoes.

availableFields lists the fields a boost can target: the standard fields plus any extraData fields indexed for search (manage indexing with dataFields_getProductFields and dataFields_updateProductFieldsIndexing). Use productData_getFieldValues to see the values a field actually has. Query-specific boosts (query rules) are configured in My Hello Retail and are not returned here.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_getProductEngineBoosts",
    "arguments": {
      "websiteUuid": "<string>",
      "engineId": 0
    }
  }
}

{
  "engineId": 0,
  "engineName": "<string>",
  "boosts": [
    {
      "field": "brand",
      "value": "Nike",
      "formattedValue": "Nike",
      "boost": 2
    }
  ],
  "availableFields": [
    "<string>"
  ]
}

search_updateProductEngineBoosts¶

Replace the boosts of a product search engine. This is a full replacement: the provided list becomes the complete set of engine-level boosts. Pass an empty list to remove all boosts, and use search_getProductEngineBoosts first to read the current entries when only adding or changing one. Query-specific boosts (query rules) are separate and untouched by this tool.

The same field can be boosted on several values (brand Nike and brand Adidas), but each field and value pair can appear only once.

Each entry has these fields:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_updateProductEngineBoosts",
    "arguments": {
      "websiteUuid": "<string>",
      "engineId": 0,
      "boosts": [
        {
          "field": "brand",
          "value": "Nike",
          "boost": 2
        },
        {
          "field": "hierarchies",
          "value": "kids$shoes",
          "boost": -2
        }
      ]
    }
  }
}

search_getProductEngineElevates¶

Get the elevates of a product search engine. An elevate pins a specific product to the top of the results whenever the visitor's search matches query; the product is identified by its url.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_getProductEngineElevates",
    "arguments": {
      "websiteUuid": "<string>",
      "engineId": 0
    }
  }
}

{
  "engineId": 0,
  "engineName": "<string>",
  "elevates": [
    {
      "query": "running shoes",
      "url": "https://shop.example/p/123"
    }
  ]
}

search_updateProductEngineElevates¶

Replace the elevates of a product search engine: the products pinned to the top of the results for matching queries. This is a full replacement: the provided list becomes the complete set of elevates. Pass an empty list to remove all elevates, and use search_getProductEngineElevates first when only adding or changing one.

Each entry has these fields, and each query and url pair can appear only once:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_updateProductEngineElevates",
    "arguments": {
      "websiteUuid": "<string>",
      "engineId": 0,
      "elevates": [
        {
          "query": "running shoes",
          "url": "https://shop.example/p/123"
        }
      ]
    }
  }
}

search_getProductEngineExcludes¶

Get the excludes of a product search engine. An exclude hides a specific product from the results whenever the visitor's search matches query; the product is identified by its url.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_getProductEngineExcludes",
    "arguments": {
      "websiteUuid": "<string>",
      "engineId": 0
    }
  }
}

{
  "engineId": 0,
  "engineName": "<string>",
  "excludes": [
    {
      "query": "running shoes",
      "url": "https://shop.example/p/456"
    }
  ]
}

search_updateProductEngineExcludes¶

Replace the excludes of a product search engine: the products hidden from the results for matching queries. This is a full replacement: the provided list becomes the complete set of excludes. Pass an empty list to remove all excludes, and use search_getProductEngineExcludes first when only adding or changing one.

Each entry has these fields, and each query and url pair can appear only once:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_updateProductEngineExcludes",
    "arguments": {
      "websiteUuid": "<string>",
      "engineId": 0,
      "excludes": [
        {
          "query": "running shoes",
          "url": "https://shop.example/p/456"
        }
      ]
    }
  }
}

search_getPersonalization¶

Get the personalization settings of a product search engine. Personalization boosts the products matching the individual visitor's affinities: each personalized field (product.brand, say) carries a boostValue from 0 to 10 weighting how strongly the visitor's affinity for that field's values influences ranking. allowedFields are the fields the website's subscription permits; availableFields is the full list. The hierarchy levels are presented as one product.hierarchy entry.

Requires Search personalization on the website's subscription in addition to Search.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_getPersonalization",
    "arguments": {
      "websiteUuid": "<string>",
      "engineId": 0
    }
  }
}

{
  "engineId": 0,
  "allowedFields": [
    "product.brand",
    "product.hierarchy"
  ],
  "availableFields": [
    "product.pi.budgetZone",
    "product.pi.productCluster",
    "product.brand",
    "product.hierarchy",
    "product.extraData.color"
  ],
  "personalizedFields": [
    {
      "field": "product.brand",
      "boostValue": 2
    }
  ]
}

search_updatePersonalization¶

Replace the personalization settings of a product search engine. This is a full replacement: the provided list becomes the complete set of personalized fields. Pass an empty list to disable personalization, and use search_getPersonalization first when only adding or changing one.

Requires Search personalization on the website's subscription in addition to Search.

Each entry has these fields, and each field can appear only once:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_updatePersonalization",
    "arguments": {
      "websiteUuid": "<string>",
      "engineId": 0,
      "personalizedFields": [
        {
          "field": "product.brand",
          "boostValue": 2
        },
        {
          "field": "product.hierarchy",
          "boostValue": 1
        }
      ]
    }
  }
}

search_listContentEngines¶

List the content search engines of a website. A content search engine executes the link content (content search) queries of the website's search configs, matching categories, site pages, blog posts or brands alongside product results. Each engine handles one contentType: CATEGORY, SITE_PAGE, BLOG_POST or BRAND.

Which engine a search config uses is set per config with search_updateLinkContent, which also creates a default engine per content type on demand, so there is no create tool here. This tool and search_getContentEngine and search_updateContentEngine manage the engines' own tuning.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_listContentEngines",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

[
  {
    "id": 0,
    "name": "<string>",
    "contentType": "CATEGORY",
    "createdAt": "<string>",
    "modifiedAt": "<string>"
  }
]

search_getContentEngine¶

Get the full settings of one content search engine. Search steps run in order and the search stops at the first step that finds results, so later steps are fallbacks. Within a step, fields maps a field name to its relative weight on match relevance, and availableStepFields lists the names a step can weight. The step fields are described under search_updateContentEngine.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_getContentEngine",
    "arguments": {
      "websiteUuid": "<string>",
      "engineId": 0
    }
  }
}

{
  "id": 0,
  "name": "<string>",
  "contentType": "CATEGORY",
  "searchSteps": [
    {
      "fields": {
        "title": 3,
        "keywords": 1
      },
      "minimumShouldMatch": "1",
      "fuzzy": true,
      "fuzzNumbers": true,
      "exactMatch": false,
      "splitSearchString": false
    }
  ],
  "availableStepFields": [
    "title",
    "keywords",
    "description",
    "hierarchy"
  ]
}

search_updateContentEngine¶

Update the settings of a content search engine. All parameters are optional and updates are partial: omitted fields are left unchanged. searchSteps is a full replacement when provided, so read the current steps with search_getContentEngine first and pass every field of every step explicitly.

Each step has these fields, and all of them are required. They behave as on a product engine, without the product-only stock, hidden-product and popularity settings:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_updateContentEngine",
    "arguments": {
      "websiteUuid": "<string>",
      "engineId": 0,
      "name": "Categories, title first",
      "searchSteps": [
        {
          "fields": {
            "title": 4,
            "hierarchy": 1
          },
          "minimumShouldMatch": "1",
          "fuzzy": true,
          "fuzzNumbers": false,
          "exactMatch": false,
          "splitSearchString": false
        }
      ]
    }
  }
}