The import report

Every index run reports what it took in from the catalog and what it left out, each with its reason. So no row goes missing unseen, and a broken one never takes the rest of the catalog with it.

curl -s -H "Authorization: Bearer $key" $api/index-runs \
  | jq -c '.data[0] | {state} + (.report | {rows, entities, rejected})'

{"state":"succeeded","rows":40,"entities":39,"rejected":1}

The home store's run read 40 rows, made 39 entities live and left one row out.

Reference: GET /api/v1/index-runs · GET /api/v1/index-runs/{index_run} · RunReport

Rows left outCopy Anchor Link

A row with a broken field is left out whole, with its variants. The report groups the rows by what is wrong, and lists the first ten of each:

curl -s -H "Authorization: Bearer $key" $api/index-runs \
  | jq -c '.data[0].report.rejections[] | {code, count}, (.examples[] | {row, id, pointer, message})'

{"code":"invalid_field","count":1}
{"row":27,"id":"TEPPICH-SILO","pointer":"/variants/1/price","message":"Invalid type: string \"249,00 €\", expected a JSON number."}

Row 27 is the rug TEPPICH-SILO (Teppich: rug), whose second variant writes its price as text. The pointer names the field, and row is numbered as the file counts it. In an export, each example also names its column.

A value that does not fit its attribute is dropped instead, and its entity kept. Those are counted apart, under values.rejected. Before an export goes live, its import lists the same problems (Importing and mapping).

Reference: rejections · RejectionGroup · values.rejected

Settings it derivedCopy Anchor Link

The run derives each file the release leaves out from the catalog, and gives every setting its reason:

curl -s -H "Authorization: Bearer $key" $api/index-runs \
  | jq -c '.data[0].report.defaults.reasons[] | {setting, file, reason}'

{"setting":"product.no_typos.model_number","file":"types.json","reason":{"by":"few","values":0}}
{"setting":"product.no_typos.gtin","file":"types.json","reason":{"by":"few","values":0}}

The home store's release writes all of these files, but its types.json leaves open which identifiers a search must match exactly. So the run decided: the catalog holds no model numbers or GTINs, too few to tell whether each names one product, so typos still find them.

A catalog sent with an empty release derives far more, such as why "Farbe" (color) became a color filter (Your own catalog).

Reference: defaults · Derived

Values attributes.json does not listCopy Anchor Link

A value the catalog spells that attributes.json does not list becomes a value of its own, as the catalog spells it. The report names each one:

curl -s -H "Authorization: Bearer $key" $api/index-runs \
  | jq -c '.data[0].report.values | {new, ungrouped}, (.derived[] | {attribute, label, groups})'

{"new":4,"ungrouped":1}
{"attribute":"color","label":"Klarglas","groups":["clear"]}
{"attribute":"color","label":"Rauchglas","groups":null}
{"attribute":"features","label":"abnehmbarer Bezug","groups":null}
{"attribute":"material","label":"Polypropylen","groups":null}

"Klarglas" (clear glass) is a color the built-in colors know, so it shows under clear. "Rauchglas" (smoked glass) holds no color word, so it stays without a group. The other two, "abnehmbarer Bezug" (removable cover) and "Polypropylen" (polypropylene), need none. List a value in attributes.json to give it the label and group you want (Types and attributes).

Reference: values · DerivedValue

Index run statesCopy Anchor Link

A run builds fresh indexes beside the live ones and swaps them in, so shoppers never see half a catalog:

• queued: it waits for the indexer.
• running: it builds the indexes, and progress says how far it got.
• succeeded: it is live, and searches read its snapshot and release.
• failed: error says why, and nothing it built went live.
• superseded: a newer run took its place before it went live.

Reference: state · error · progress

NextCopy Anchor Link

• Importing and mapping: see the problems before an export goes live, and correct how it is read.
• Formats we read: the files an index run reads, and OrbSearch JSON Lines.
• Releases: publish, roll back, and the runs they queue.