Mapping and fields

What the mapping is

The mapping lists every field search knows about. Each field has a type and five flags that say what it is used for: searched, filtered, shown as a facet, sorted by or returned with results. Searchable fields also have text analysis options.

Fields & mapping lists every field with its type and flags

A document may carry fields the mapping does not list. Zaproo stores them, but search ignores them until you map them. See unmapped fields.

In the cabinet, open an index and then Fields & mapping. Edits go into a draft. The Changes panel lists every change and whether it is additive or breaking before you click Save mapping. If the draft would break a profile, rule or facet, the panel shows which ones use each field, and Save mapping stays off until you change them. See Fields in use.

GET returns language, fields and unmapped. PUT takes language and fields and replaces the whole mapping, so send every field you want to keep. A field left out is removed. The answer holds the saved mapping, the updated index and a diff with kind (none, additive or breaking) and one entry per change.

{
  "language": "english",
  "fields": {
    "id": { "type": "keyword", "filterable": true, "sortable": true },
    "title": { "type": "text", "searchable": true, "sortable": true },
    "brand": { "type": "keyword", "searchable": true, "filterable": true, "facetable": true },
    "price": { "type": "float", "filterable": true, "facetable": true, "sortable": true },
    "categories": { "type": "hierarchy", "filterable": true, "facetable": true },
    "attributes.color": { "type": "keyword", "filterable": true, "facetable": true }
  }
}

A flag left out takes its default: returnable is on, the other four are off. Over MCP, get_mapping and update_mapping do the same.

Field types

A field holds one value or an array of values of its type. null is allowed.

A document whose value does not fit the field's type is rejected when you upload it. A hierarchy field may hold several paths, one per category the product is in. Only text, keyword and hierarchy fields can be searchable.

Flags

The cabinet lists them under Used for when you edit a field, with the same labels.

Text analysis

A searchable field has four more options. The cabinet shows them under Text analysis in the field editor once Searchable is on. In the API they go in the field's analysis object. An option left out takes its default.

Every analysis option changes how stored text is split into words, so changing one on an existing field is breaking and needs a reindex.

Field names

• A name starts with a letter and holds letters, digits and _, up to 64 characters: brand, price_eur.
• Put product attributes under attributes: the mapping field attributes.color reads color from the document's attributes object. Only one level is allowed.
• attributes itself is reserved and cannot be mapped.
• Every mapping has an id field of type keyword. You cannot remove it or change its type.
• A mapping holds at most 500 fields.

Other nested objects in a document are stored but never mapped.

Inferred mapping

An index created without fields maps its fields from the first upload. Each field gets a type and flags from its values:

Common product fields keep fixed flags when their values fit: title, shortDescription, description, url, imageUrl, price, currency, brand, categories (as hierarchy), sku and inStock.

Inference runs once. Fields that later uploads bring are not mapped automatically. They appear under unmapped fields.

Unmapped fields

GET mapping lists in unmapped every field your documents carry that the mapping lacks, with a sample value, the suggested definition inference would give it (null when its values mix types) and firstSeenAt. Up to 1000 field names are recorded per index.

In the cabinet they appear under Not mapped yet. Add puts the field into the draft with the suggested definition. Edit it if needed, then save.

Documents already uploaded hold values for these fields, and a mapping update does not index stored values. Adding an unmapped field is therefore breaking: save it, then reindex so search covers every document.

Additive and breaking changes

A save compares the new mapping with the live version.

• Additive changes apply at once, and the index stays READY.
• Breaking changes are saved, but the live version keeps the previous mapping. The index moves to NEEDS_REINDEX until a reindex builds a version with the new mapping.

Search, filters and profiles keep working on the live version while the index waits for a reindex. While a version is being built, a breaking save answers 409 VERSION_BUILDING. Additive saves still work.

Fields in use

A mapping change may not break the search configuration that uses it. Remove a field from the profiles, rules and facets that use it first, then remove it from the mapping. The same holds for a type change or a flag turned off: a profile that filters on price with a range needs price to stay numeric and filterable.

A save is refused with 409 MAPPING_BREAKS_CONFIG when it would make any of these invalid:

• a search profile: its query fields, facets, sort options, filters, filter fields or returned fields
• a ranking rule: its condition filters, boost and filter actions, or field weights
• the index facets
• the autocomplete value fields
• the data source field mapping

details lists every use, so you know what to change:

{
  "error": {
    "code": "MAPPING_BREAKS_CONFIG",
    "message": "This mapping change would break search configuration that uses \"brand\". Remove or change those uses in the profiles, rules, facets, autocomplete or data source listed in details first.",
    "details": [
      { "kind": "facets", "id": null, "name": "Index facets", "path": "facets.0.field", "field": "brand", "message": "\"brand\" is not a mapped field" }
    ]
  }
}

kind is profile, rule, facets, suggest or feed. id is the profile or rule id, and null for the others. path points into that configuration. A use that was already invalid before the change does not block it.

Returns what the guard checks: profiles, rules (each { id, rule }), facets, suggestFields and feedFields. The cabinet uses it to show the same issues before you save.

Integrations

A shop platform plugin can seed the mapping for you. While the plugin's Manage the index mapping setting is on, the plugin adds each new shop attribute as a field. Once a field is saved, Zaproo owns it: a later sync from the plugin adds only fields the mapping lacks, and never changes or removes a saved field or the index language. In Fields & mapping you can change any field and add new ones, but you can't remove a field. A PUT .../mapping from anyone but the plugin's key that removes a field answers 409 MAPPING_MANAGED_BY_INTEGRATION; exclude the attribute in the plugin, or turn the setting off there, to remove it. A breaking change still marks the index Reindex needed, and the plugin rebuilds the index on its next sync. See Integrations.

Errors

Related

• Indices and languages
• Documents and tasks
• Reindex and versions
• Search profiles