Search query rules¶

Shape the results of specific searches on a product search engine. A query rule names the searches it acts on and, for those searches only, pins products to the top, hides products, or boosts products by a field value. Rules live on the engine, so they apply to every search config using it, and they have no draft: a saved rule is live at once.

A search is compared with a rule's queries after normalisation, lower case, trimmed, single spaces, so "Running Shoes" and "running shoes" are the same query. A trailing * matches every search starting with the text before it (run*), and * alone matches every search. Each query can belong to only one rule of an engine.

Products are addressed by their URL, the same URL productData_get shows. Pinned products appear in the order you list them.

Tips & tricks¶

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

For searches on "running shoes", pin <PRODUCT URL> and <PRODUCT URL> to the top on my product search engine.

Create a query rule on my product search engine that boosts the brand Nike by 3 for the searches "trainers" and "sneakers".

search_listQueryRules¶

List the query rules of a product search engine. Each rule shows its queries, the products pinned to the top (elevates, in display order), the products hidden (excludes) and its boosts. A pinned or hidden product that has since left the catalog keeps its productId with url and title empty, so you can still see and remove it.

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

[
  {
    "id": 0,
    "queries": [
      "running shoes",
      "runners"
    ],
    "elevates": [
      {
        "productId": "<string>",
        "url": "https://shop.example/p/123",
        "title": "<string>"
      }
    ],
    "excludes": [],
    "boosts": [
      {
        "field": "brand",
        "value": "Nike",
        "formattedValue": "Nike",
        "boost": 2
      }
    ],
    "createdAt": "<string>"
  }
]

search_getQueryRule¶

Get one query rule of a product search engine: its queries, pinned products in order, hidden products and boosts.

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

search_addQueryRule¶

Add a query rule to a product search engine. The rule acts on every search matching one of its queries. A query can belong to only one rule of the engine; the tool refuses a query another rule already has and names it.

Each boost has these fields, the same as an engine boost:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_addQueryRule",
    "arguments": {
      "websiteUuid": "<string>",
      "engineId": 0,
      "queries": ["running shoes", "runners"],
      "elevates": ["https://shop.example/p/123", "https://shop.example/p/456"],
      "excludes": ["https://shop.example/p/789"],
      "boosts": [
        {
          "field": "brand",
          "value": "Nike",
          "boost": 2
        }
      ]
    }
  }
}

search_updateQueryRule¶

Update a query rule of a product search engine. Every list is optional, and a list you provide replaces that part of the rule in full: omitted lists are left unchanged, an empty list clears that part. Read the rule with search_getQueryRule first when you are adding or removing a single entry.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_updateQueryRule",
    "arguments": {
      "websiteUuid": "<string>",
      "engineId": 0,
      "ruleId": 0,
      "excludes": ["https://shop.example/p/789"]
    }
  }
}

search_deleteQueryRule¶

Delete a query rule of a product search engine. The searches it covered fall back to the engine's normal results at once. Read it with search_getQueryRule first if you may want to recreate it.

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

{
  "id": 0,
  "queries": [
    "running shoes",
    "runners"
  ]
}