Article-Number Search (ProductNumber)

In addition to the regular full-text product search, Makaira runs a dedicated article-number search for every search request. Its purpose is simple: when a customer types an exact article number, EAN, or SKU, they should land directly on that one product — not on a fuzzy near-match.

This page describes how the article-number search works, how it interacts with the regular product search, and how to configure your data so that customers find exactly the right product.

How it works

For every search query, Makaira runs two queries in parallel:

1. Regular product search — full-text search across the configured search fields (title, short description, search keys, …).
2. ProductNumber search — an exact-style match against the ean field and its ean.alphanumeric sub-field, restricted to active products and limited to one result.

The decision which result wins is straightforward:

In other words: a unique match in the ean field always wins over the regular search. Anything else falls through to the regular search.

What is matched

The ProductNumber search runs a multi_match against:

• ean — analysed like a regular text field, so it is token-aware. P-134147 is tokenised into P and 134147, which means a customer typing 134147 still hits P-134147.
• ean.alphanumeric — a single keyword token with all non-alphanumeric characters stripped (P-134147 → P134147). This catches customers who type the number with or without separators.

There is no fuzziness in the ProductNumber search. The match is strict — typos do not match.

What ends up in the ean field

The ean field is the only field consulted by the ProductNumber search. It is a free-form string and is intended for EAN, SKU, or article number (whichever your customers use to identify a product).

If your customers may type the number in different formats — for example with and without a prefix — put all accepted variants comma-separated in one ean field so that all variants are tokenised and indexed:

{
  "id": "12345",
  "ean": "P-134147, 134147"
}

With the example above, both P-134147 and 134147 will return product 12345 directly.

Should I add ean to the regular search fields?

Most setups do not need the ean field in the list of regular search fields. The ProductNumber search already covers the exact-article-number use case, and adding ean to the regular search has two side effects you usually do not want:

• Fuzzy matches. When the regular search has the error-tolerant search enabled, 134148 matches 134147 (Levenshtein distance 1). For article numbers that is almost always wrong — consecutive SKUs differ by one digit.
• Diluted relevance. Article numbers showing up alongside title/description matches can push unrelated products onto the result list.

If you need fuzzy article-number matching for some reason, add ean (and any custom field that holds the number, e.g. oxean) under Search → Search configuration → Fields. If you do not, leave the field out and rely on ProductNumber.

📘

Both behaviours can coexist

ProductNumber search runs unconditionally and is independent of the search-fields configuration. Removing ean from the search fields does not disable article-number search — it only stops fuzzy matches against the EAN.

Troubleshooting

A search for an article number returns the wrong product.

• Check ean in the data inspector. The number must be in the ean field — if it is only in oxean or another custom field, the ProductNumber search will not find it. Fold the custom field into ean (comma-separated) at import time.
• Check whether ean (or a synonymous field like oxean) is configured as a regular search field with fuzzy enabled. If yes, adjacent article numbers can match each other through Levenshtein distance. Remove the field from the regular search configuration to get exact-only behaviour.

A search for an article number returns the regular product list instead of the single product.

• The ProductNumber result count is not exactly 1. Either no document has the number in ean (check the data inspector) or multiple documents do (the ProductNumber search is restricted to active products, but if two active products share the same ean token, ProductNumber falls through to the regular search).

Synonyms and antonyms have no effect on the ProductNumber search.

• ProductNumber search runs as its own request and does not use the synonym/antonym configuration. Use the ean field itself to model accepted variants.

See also

• Field Reference — ean — where the ean field is defined.
• Search configuration — manage the regular search fields and fuzzy search.