# The trace Why an answer is what it is: every step a search, a page or a product lookup took, with what it decided. ## A search - `release` (string · required): The id of a release. A release is named by its content and never changes. - `snapshot` (string · required): The id of a catalog snapshot. A snapshot is named by its content and never changes. - `publishing` (string): A release was being published while this request was answered; either release's live settings, such as its synonyms or typo settings, may have applied. - `live` ([WentLive](#WentLive)): The index run this was answered from and how it took the release live: switched in, with settings, or built. - `derived` (array of strings): The release's files the live run derived from its catalog because the release leaves them out, such as `categories.json` with the facets or `ranking.json` with the sort options. They answered as if written; the run report gives the reason for each of their settings. - `request` ([object](/docs/reference/query-api#search.body) · required): The request as it was answered: with the time it arrived at, and the channel and locale it was answered in. Replayed as a search test or in the preview, against the same release and snapshot, it gives the same response. - `steps` ([array of objects](/docs/reference/trace#steps) · required): One entry per step, in the order the steps ran. - `timings` ([Timings](#Timings)): How long the Query API took for the request. A page's listing leaves it to the page's trace, which measures the whole page. ## The steps of a search One entry per step, in the order the steps ran. ### `normalize` The query as the engine's tokenizer reads it. - `query` (string · required) - `normalized` (string · required) ### `resolve` What the query named, and the text that is left. - `resolution` (object · required): The categories, brands and values a query named, and the text that is left. - `category` (string): The id of a category node, such as `wohnen/sofas`: the merchant's id of a `category` entity. - `filters` ([object](/docs/reference/query-api#Selector)): The detected filters, such as `{ "color": "grey", "width": { "lte": 220 } }`. - `text` (string · required) - `complete` (boolean · required): Nothing is left as text. - `left_out` ([array of objects](/docs/reference/query-api#AppliedFilter)): What a relaxed search left out of what the query named, each as the filter it would have been, with its labels, so a storefront can say what the results leave out. Empty unless the response is `relaxed`. - `detections` ([array of Detection](#Detection)): Each word or phrase that became the category or a filter, with the entry it matched. - `kept` (array of objects): Words that matched something and stay text all the same, each with the reason. Words that matched something and stay text. - `words` (string · required) - `reason` (string · required): Why they stay text, such as "they name the category Sofas and the brand Sofa Company alike". - `candidates` ([array of objects](/docs/reference/query-api#Selector)): What they could have meant. - `yielded` ([array of Detection](#Detection)): What the words named in a field the shopper chose themselves: their choice replaces it, so the words neither filter nor are searched, as "graues" after the shopper ticked blue on "graues Sofa". - `named` ([array of objects](/docs/reference/query-api#AppliedFilter)): What the query named as its chips read in the request's locale, held to or left out: the category and one filter per field, each with its labels, such as the category's title. ### `rules` Every candidate rule of one phase, in rule order, with the one state it ended in. - `phase` (string · required): - `understand`: Rules that resolve terms or remove words, before the query is resolved. - `redirect`: Rules that redirect; the highest one ends planning. - `shape`: Rules that filter, hide, pin, boost, bury, order sections and place banners. - `rules` (array of objects · required): What became of one candidate rule. - `rule` (string · required): A rule's id, unique per release, such as `home/out-of-stock-last`. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets. - `description` (string · required): The rule's line from `rules.json`, so the trace reads without the release. - `origin` (object): Where an imported rule or overlay came from. - `import` (string · required): What it was imported from, such as the previous search's export. - `ref` (string · required) - `state` (string · required): - `applied`: Every effect took place. - `partly_applied`: Some effects were moved or skipped; each says why. - `not_applied`: The rule matched, but a higher rule's redirect ended planning. - `not_matched`: The condition failed. - `inactive`: Disabled, or outside its schedule. - `matched` (string): The part of the condition that matched, as a sentence. - `failed` (string): The part of the condition that failed, as a sentence. - `reason` (string): Why the rule was inactive or not applied. - `effects` (array of objects): What became of one effect. - `effect` (string · required): One of `resolve`, `rewrite`, `redirect`, `filter`, `hide`, `pin`, `boost`, `bury`, `sections` or `place`. - `outcome` (string · required): One of `applied`, `moved` or `skipped`. - `section` (string): The section it acted in, by type: an effect that reaches the sections of several types is traced once for each. - `target` (string): What the effect was about, as a sentence, such as "brand is bosch", "product:SOFA-LUND-3" or, for a placement, the banner's title. - `slot` (string): Placements: where on the page the banner sits. - `top`: Above the results, on the first page. Banners of several rules stand in rule order, the highest first. - `grid`: Among the tiles, before the one at its position, on the page that holds that tile. - `bottom`: After the results, on the last page. Banners of several rules stand in rule order, the highest first. - `position` (integer): Pins and grid placements: the position asked for. - `placed` (integer): Pins: the slot the plan expects it to take. A higher pin that fails a filter frees its slot only in the engine, so where a hit landed is the `rank` step's. Grid placements: the position it took. - `strength` (string): One of `slight`, `medium` or `strong`. - `reason` (string): Why the effect was moved or skipped, such as "skipped: limit", or for a placement this page does not show, why not, such as "position 30 is on page 2". - `engine` (object): How the engine carried it out; for developers. The engine rule that executed a pin, boost or bury, and the weight it gave. - `rule` (string · required) - `weight` (number) ### `sort` The order the page lists its hits in, and where that choice came from. - `sort` (string · required): The sort option; `relevance` is built in. - `source` (string · required): Where the order of a page came from. - `shopper`: The shopper chose it; it wins over any default. - `text`: The request has words, which rank by relevance unless the shopper chose another order. - `category`: The nearest category node that sets a default sort, up the tree from the page's category. - `default`: The `default` layout of `categories.json`. - `built_in`: Nothing sets a default sort: relevance, which is built in. - `category` (string): The category whose node sets the sort, when `source` is `category`. - `reason` (string · required): Why, as a sentence, such as "The category wohnen/sofas sets price_desc as its default sort." ### `plan` The searches the engine is asked for, one per section, and the type the page lists. - `listed` (object · required): The type a page lists, whose section pages through the results, carries the facets and takes what the query named. - `type` (string · required): The code of an entity type, such as `product`, `category` or a merchant's own `store`. - `reason` (string · required): Why, as a sentence, such as "The category werkstatt/bremsenservice holds 7 service and no product entities." - `searches` (array of objects · required): One search of the plan, as the engine receives it; for developers. - `type` (string · required): The section it fills. - `index` (string · required): The engine index it searches. - `text` (string · required): The text it searches for. - `filter` (string): The engine filter, when the search is narrowed. - `sort` (array of strings): The engine sort, when the request chose one. - `page` (integer · required) - `per_page` (integer · required): Hits it returns; none for a search that only counts. - `facets` (array of strings): The engine fields whose values it counts. - `without` (string): The facet it counts under every filter but that facet's own, so that choosing a value keeps its siblings; its hits are not shown. ### `execute` The engine's answer, in one multi-search call. - `round_trip_ms` (number · required): From sending the call to reading its answer, in milliseconds. - `searches` (array of objects · required): What the engine answered for one search. - `index` (string · required) - `total` (integer · required): How many entities match in all, counted exactly however many they are. - `engine_ms` (integer · required): The engine's own time for the search, in milliseconds. It leaves out parsing the filter, so it is no budget. ### `relax` Nothing matched the resolved search, so it was searched again with less of what the query named. - `dropped` ([array of objects](/docs/reference/query-api#Selector) · required): What the next search leaves out: the category and the filters the query named, one field each. - `text` (string · required): The text it searches. ### `facets` How each facet was counted, and where a count can only be an upper bound. - `facets` (array of objects · required): How one facet of a section was counted. - `type` (string · required): The code of an entity type, such as `product`, `category` or a merchant's own `store`. - `field` (string · required): A field a selector, filter or facet reads: an attribute code, or one of the built-in fields `category`, `brand`, `price`, `on_sale`, `availability`, `delivery_days` and `rating`. - `search` (integer · required): The search of the plan that counted it, counted from 0. - `values` (integer · required): The values shown. - `limit` (integer): The most values the facet carries before `more`: the layout's `limit`, or the limit [`facet_values`](/docs/reference/limits#facet_values). None for a facet without a cap: one the request named, and every kind but a list or a swatch. - `more` (integer): How many values with results the cap left out. - `kept` (array of strings): Chosen values the results do not hold, shown with a count of 0 so they can be unchosen. - `upper_bound` (object): Why the counts are upper bounds, when they are. Why a facet's counts can be higher than the tiles a shopper would find. Every other count is exact. - `multi_select` (by: "multi_select"): Several values are chosen in these variant-level fields, and a tile may hold a variant for each: the counts add them up, at most as high as the tiles that have the value in some variant matching the other choices. - `fields` (array of strings · required) - `free_range` (by: "free_range"): A free range over this variant-level field narrows the results beside a choice in another variant-level field, and one variant may meet the range while another meets the choice. - `field` (string · required): A field a selector, filter or facet reads: an attribute code, or one of the built-in fields `category`, `brand`, `price`, `on_sale`, `availability`, `delivery_days` and `rating`. - `histogram` (object): The bins of a histogram, which only approximate the distribution. The same however the facet came to be counted, by the page or by a request that named it; a histogram the page left out is in `deferred` of the step instead. How a histogram's bars were drawn, which makes them an approximation of the distribution: the bins are a fixed ladder of preferred numbers, each 8 to 15 percent above the one before and the same whatever the catalog holds, so a bar says where products sit, not exactly how many. A tile with several prices counts in every bin one of them falls in, so the bars may add up to more than the tiles, and the chosen range may cut a bin in two. Each count itself follows the rules of any other facet's. - `bins` (integer · required): How many bins the response lists, those without tiles included. - `from` (number · required): Where the first bin starts: the ladder's number at or below the cheapest price. - `to` (number · required): Where the last bin ends, exclusive: the ladder's number above the dearest. - `deferred` (array of strings): The facets the page lists without counting them: those past the limit [`counted_facets`](/docs/reference/limits#counted_facets) that no choice and no request named, and the facets of a group that none of those reached. - `groups` (array of objects): The page's groups of facets and how each was counted. How a group of facets was counted: all of them or none, since a finder with a facet left out would draw an empty select, and a group is one control that a shopper opens or reads at once. - `group` (string · required): The code of a group of facets on a page, such as `tyre_size`. - `facets` (array of strings · required): Its facets as the page lists them, in the group's order. - `counted` (boolean · required): The page counted every facet of it, or none: it did not count the group. - `reason` (string · required): Why, as a sentence, such as "tyre_size stands at position 7 of the page, within the first 30 facets it counts". ### `rank` Why each hit of the page sits where it does: the pin that placed it, the boosts and buries that weighed it, and its business score. - `sections` (array of objects · required): The hits of one section and why each sits where it does. - `type` (string · required): The code of an entity type, such as `product`, `category` or a merchant's own `store`. - `hits` (array of objects · required): One hit and what placed it. - `entity` (string · required): An entity named with its type, `type:id`, such as `product:SOFA-LUND-3`. - `variant` (string): The merchant's id of an entity, unique per type, such as `SOFA-LUND-3`. It travels unchanged; OrbSearch never rewrites it. - `position` (integer · required): Its place on the page, counted from 1. - `pinned` (string): The rule whose pin put it here. - `sponsored` (object): The campaign of that pin, when it is a paid one. The campaign a paid placement belongs to: `{ "campaign": "Michelin spring" }`. - `campaign` (string · required): The merchant's name for it, which the campaign report counts by. - `weighed` ([array of objects](/docs/reference/management-api#Weight)): The boosts and buries that weighed it, each with the factor it gave. - `criteria` (array of objects): What the engine compared it by, in the order it compares, its business score among them. One criterion the engine compared hits by, with this hit's value. Hits are compared criterion by criterion in the order the engine ranks by, and the first criterion two hits differ in decides which comes first. - `words` (criterion: "words"): How many of the query's words it was found by, as typed, through a synonym or with a typo; more come first. - `matched` (integer · required) - `of` (integer · required) - `typos` (criterion: "typos"): How many typos it took to find those words; fewer come first. - `typos` (integer · required) - `sort` (criterion: "sort"): The sort the request chose, and the hit's value in it; a hit without a value comes last. - `sort` (string · required): The code of a sort option, such as `price_asc`. `relevance` is built in. - `by` (string · required): A field of an entity as search and result settings name it: a core field such as `title`, or an attribute as `attributes.`; sort options also read `signals.`. - `direction` (string · required): One of `asc` or `desc`. - `value` (any) - `business_score` (criterion: "business_score"): Its business score from 0 to 1; higher comes first. - `score` (number · required) - `proximity` (criterion: "proximity"): How close together the query's words stand in it, from 0 to 1; closer comes first. - `score` (number · required) - `fields` (criterion: "fields"): How early among the type's searched fields, and how early in a field, the words were found, from 0 to 1. - `score` (number · required) - `exactness` (criterion: "exactness"): Whether a field holds the query as a whole, starts with it, or neither, from 0 to 1. - `exact` (string · required): - `whole`: A field holds exactly the query. - `start`: A field starts with the query. - `no`: No field holds the query as it was written. - `score` (number · required) - `matched` (array of objects): The query's words it was found by, each with the fields it was found in and the synonym it was found through. A word of the query and how the hit was found by it. - `word` (string · required): The word as the engine reads the query. - `synonym` (string): The synonym it was found through, when the hit holds the synonym and not the word itself. - `entry` (string): The entry of `synonyms.json` that leads the word to its synonym, such as `de/groups/0`; with `synonym` only. - `typo` (string): The word of the hit it was found by with a typo, as its field writes it, such as `Bremsbelag` for `bremsbelg`. - `fields` (array of strings · required): The searched fields it was found in, in the type's order, such as `title`; `words` holds what the index adds, such as the titles of its categories. - `signals` ([array of SignalScore](#SignalScore)): The signals of its business score with their weights, the one that adds the most first. - `why` (array of objects): Why it sits here, from the facts above and the rest of the trace, in the order the reasons act. One reason a hit sits where it does, in a sentence and as data. - `sentence` (string · required): The reason in a sentence, such as "Pinned to position 1 by the rule “Sommer-Sale”." - `because` (object · required): - `pin` (kind: "pin"): A rule pinned it to its place, which comes before everything else; a paid pin names its campaign, and the sentence calls it a sponsored placement of that campaign. - `rule` (string · required): A rule's id, unique per release, such as `home/out-of-stock-last`. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets. - `description` (string · required) - `position` (integer · required) - `sponsored` (object): The campaign a paid placement belongs to: `{ "campaign": "Michelin spring" }`. - `campaign` (string · required): The merchant's name for it, which the campaign report counts by. - `weight` (kind: "weight"): A rule's boost or bury weighed it against the hits beside it. - `rule` (string · required): A rule's id, unique per release, such as `home/out-of-stock-last`. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets. - `description` (string · required) - `effect` (string · required): One of `resolve`, `rewrite`, `redirect`, `filter`, `hide`, `pin`, `boost`, `bury`, `sections` or `place`. - `factor` (number · required) - `named` (kind: "named"): Words of the query named something it is or has, which narrowed the results to it. - `words` (string · required) - `as` ([object](/docs/reference/query-api#Selector) · required): Picks entities (`where`). Attribute codes and the built-in fields `brand`, `price`, `on_sale`, `availability` and `delivery_days` are keys of the same object; `category` takes `is` or `within`. `{ "any": [{ "brand": "bosch" }, { "quality": "oe" }], "not": { "availability": "out_of_stock" } }` - `entry` (string · required): Where the meaning comes from, such as "the alias \"graues\" of the color group Grau". - `rule` (string): A rule's id, unique per release, such as `home/out-of-stock-last`. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets. - `pattern` (string) - `synonym` (string): The entry of `synonyms.json` that let the words name it, such as `de/groups/0`, when a synonym did. - `synonym` (kind: "synonym"): A word of the query found it only through a synonym, which the entry of `synonyms.json` holds. - `word` (string · required) - `synonym` (string · required) - `entry` (string): A synonym entry's place in `synonyms.json`: its language, its kind and its index there, such as `de/groups/0`, `de/one_way/2` or `de/never/0`. A delete moves the entries after it up, so a write names the draft version it read. - `text` (kind: "text"): How well it matches the query's text, and where. - `matched` (integer · required) - `of` (integer · required) - `typos` (integer · required) - `fields` (array of strings · required) - `sort` (kind: "sort"): The sort the request chose orders the page. - `sort` (string · required): The code of a sort option, such as `price_asc`. `relevance` is built in. - `by` (string · required): A field of an entity as search and result settings name it: a core field such as `title`, or an attribute as `attributes.`; sort options also read `signals.`. - `direction` (string · required): One of `asc` or `desc`. - `value` (any) - `business_score` (kind: "business_score"): Its business score orders it among the hits that match as well as it does; `signal` adds the most to it. - `score` (number · required) - `signal` ([SignalScore](#SignalScore)): One signal of a hit's business score. ### `assemble` The sections of the response, in order. - `sections` (array of objects · required): One section of the response. - `type` (string · required): The code of an entity type, such as `product`, `category` or a merchant's own `store`. - `total` (integer · required) - `upper_bound` (object): Why the total is an upper bound, when it is. Why a facet's counts can be higher than the tiles a shopper would find. Every other count is exact. - `multi_select` (by: "multi_select"): Several values are chosen in these variant-level fields, and a tile may hold a variant for each: the counts add them up, at most as high as the tiles that have the value in some variant matching the other choices. - `fields` (array of strings · required) - `free_range` (by: "free_range"): A free range over this variant-level field narrows the results beside a choice in another variant-level field, and one variant may meet the range while another meets the choice. - `field` (string · required): A field a selector, filter or facet reads: an attribute code, or one of the built-in fields `category`, `brand`, `price`, `on_sale`, `availability`, `delivery_days` and `rating`. - `hits` (integer · required): How many hits this page shows. ### `suggest` The suggestions of the autocomplete surface, in order, each with the entry of the catalog dictionary it came from. - `suggestions` (array of objects · required): One suggestion and where it comes from. - `text` (string · required) - `scope` (string): The id of a category node, such as `wohnen/sofas`: the merchant's id of a `category` entity. - `source` (string · required): The entry it completes, as a sentence, such as "the word \"Ecksofa\" of product titles, whose head is the category Sofas". - `products` (integer · required): The products that hold it, which rank it; for a scoped suggestion, those in its category. ## A page How a URL was resolved: each step of the order with what it found; the last one decided. - `channel` (string · required): The channel and locale the URL was resolved in. - `locale` (string · required): A BCP 47 language tag such as `de`, `de-CH` or `en`. A locale falls back along its tag: `de-CH` to `de`. - `path` (string · required): The path as it is matched: percent-decoded, in lowercase, without duplicate or trailing slashes. - `steps` (array of objects · required): - `step` (string · required): The order a URL is resolved in, then what decides about the page once it is known. - `legacy`: The legacy table, `redirects.json`: its exact entries, then its patterns. - `search`: The search page's path. - `catalog`: The paths of the catalog's categories and brands. - `normalize`: The path written differently from the page's own, such as in another case or with a trailing slash. - `parameters`: The URL's parameters read as filters, sort and page. - `product`: A product by its URL. - `robots`: Whether search engines may index the page, and its canonical. - `results`: What the results change: an empty page, a page past the last, a search that leads elsewhere. - `outcome` (string · required): What the step found, in a sentence. - `timings` ([Timings](#Timings)): How long the Query API took for the whole page, its listing's search or its product included. ## A product Why a product lookup answered what it did. - `release` (string · required): The id of a release. A release is named by its content and never changes. - `snapshot` (string · required): The id of a catalog snapshot. A snapshot is named by its content and never changes. - `publishing` (string): A release was being published while this request was answered; the product may be the new release's already. - `live` ([WentLive](#WentLive)): The index run this was answered from and how it took the release live. - `derived` (array of strings): The release's files the live run derived from its catalog because the release leaves them out, such as `types.json`, whose `details` say which details the product lists. - `request` (object · required): The request as it was answered, with the channel and locale it was answered in. A product lookup as it was answered. - `id` (string): The merchant's id of an entity, unique per type, such as `SOFA-LUND-3`. It travels unchanged; OrbSearch never rewrites it. - `url` (string) - `channel` (string · required): A channel's id, such as `de` or `ch`: a market or storefront. - `locale` (string · required): A BCP 47 language tag such as `de`, `de-CH` or `en`. A locale falls back along its tag: `de-CH` to `de`. - `index` (string · required): The engine index the product was read from, which the index run compiled for lookups. - `filter` (string · required): The engine filter that found it. - `round_trip_ms` (number · required): From sending the lookup to reading its answer, in milliseconds. **Guide:** [The trace](/docs/search#the-trace) ## `Detection` Words of the query that became the category or a filter. - `words` (string · required): The words as the query wrote them, such as `graues`. - `as` ([object](/docs/reference/query-api#Selector) · required): What they became, with exactly one field or `category`, as the filter chip writes it. - `entry` (string · required): Where the meaning comes from, as a sentence, such as "the alias \"graues\" of the color group Grau". - `rule` (string): The rule that decided what the words mean, when one did. - `pattern` (string): The pattern that read them, when one did: the id of the release's pattern, or the built-in pattern's name. - `synonym` (string): The entry of `synonyms.json` that let the words name it, such as `de/groups/0`: "couch" names the category Sofas through the group of "couch" and "sofa". ## `SignalScore` One signal of a hit's business score. - `signal` (string · required): The code of a signal, such as `sales_30d` or `rating`. - `value` (any): The signal as the catalog sends it, when it does. - `score` (number · required): Normalized to 0..1, the better the higher. - `weight` (number · required): Its weight in the type's business score. ## `Timings` How long the Query API took for a request, as the server measured it: from the request's arrival to its assembled answer, so writing the answer and the network path to the client come on top. Each time is held against the p95 budget of its kind: one request above it is a warning, and the budget is missed when more than 5 of 100 are. Only the server measures, so a trace assembled anywhere else, such as in a test, has none. - `total_ms` (number · required): The whole time in milliseconds, the engine round trips included. - `round_trip_ms` (number · required): The engine round trips together, in milliseconds: every call the request sent, a relaxed search's first one included. - `own_ms` (number · required): The Query API's own share in milliseconds: the whole time without the engine round trips. - `before_engine_ms` (number): The Query API's own time before its first engine call: reading the request, understanding the query and planning the searches. The rest of `own_ms` comes after the engine answered. A request that asks the engine nothing has none. - `total_budget_ms` (integer · required): The budget of the whole time for the request's kind: autocomplete's, or that of a search and a page. - `own_budget_ms` (integer · required): The budget of the Query API's own share. ## `WentLive` The index run a response was answered from, how it took its release live, and the offer changes its documents hold. With the release and the snapshot, they name what answered: a replay with the same three gives the same answer. - `run` (integer · required) - `course` ([object](/docs/reference/management-api#Course) · required): The way a release goes live and why, as data and as a sentence. - `offers` (integer): The offers revision: the latest batch of offer changes the run's indexes hold, applied on top of its snapshot by the run or written into its indexes since; left out when they hold none.