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.

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

The first upload to a new index maps every field it can recognise (see inferred mapping). Check the result before you build search profiles.

Change fields in the cabinet

Open the index, then Fields & mapping. The table lists every field with its type and a badge for each setting that is on.

Fields & mapping lists every field with its type and settings

After a breaking save, the page shows Reindex needed. Click Reindex now in the Reindex panel at the top of the page to build the index with the new mapping. See Reindex and versions.

The table groups every attributes.* field under one collapsible attributes row, which starts collapsed when there are more than eight of them. Filter fields above the table narrows it to the fields whose full name contains what you type.

Find fields by setting or type

Under Filter fields, two rows of chips narrow the table further. Each chip shows how many fields it matches.

• Settings: Searchable, Filterable, Facetable, Sortable and Returnable. Pick several to see the fields that have all of them, for example every field that is both filterable and sortable.
• Type: one chip for each field type the mapping uses. Pick several to see the fields of any of those types.

Click a chip again to turn it off. The chips and the text box work together, so price with Sortable on shows the sortable fields whose name contains "price". Reset filters clears the text and every chip. While a filter is on, the attributes group opens so that matching attributes are not hidden.

Only organization owners and admins can change the mapping. Members see the table without the edit controls.

Change the mapping with the API

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. PATCH takes only fields and changes just the fields it names: a definition adds or replaces that field, null removes it, and every other field and the language stay as they are. Send each named field's whole definition, because a flag left out takes its default. Both answers hold 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, update_mapping and update_fields 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 click Edit on 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.
• Names that start with zs_alt. belong to language groups. You cannot add or remove them.
• 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 on Fields & mapping, each with a sample value. Add puts the field into the draft with the suggested definition. Click Edit on it if needed, then Save mapping.

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 in the Changes panel before you save, with a link to each profile, rule or page that uses the field.

Integrations

A shop platform plugin can seed the mapping for you. While the plugin's Add new attributes to the Zaproo 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 or PATCH .../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.

Language group fields

An index in a language group holds the text the other members lend it. Each copy is a mapping field named zs_alt.<source language>.<field>, for example zs_alt.english.title. The group adds and removes these fields when you save it. The cabinet lists them in a section of their own.

A borrowed field is always text and analyzed in the language it came from. It is always searchable, and filterable, facetable and sortable stay off. It starts not returnable. Turning Returnable on is additive, and then a profile's returned fields can include it. You may change Split numbers, Codes and Word pairs, which are breaking changes as on any other field. A search profile only searches a borrowed field once it lists it under Fields and weights.

A PUT or PATCH .../mapping that adds a zs_alt. field answers 400 MAPPING_FIELD_RESERVED. One that leaves out or removes a field the group lends answers 409 MAPPING_MANAGED_BY_LANGUAGE_GROUP. Change the group's shared fields instead. Removing a borrowed field through the group is additive: the next sync strips its text from the documents.

Errors

Related

• Indices and languages
• Documents and tasks
• Reindex and versions
• Search profiles
• Data source
• Quickstart