Choosing the Right Elasticsearch Field Types

Field types determine how Elasticsearch indexes WooCommerce data and what operations are available at query time. A product name needs full-text analysis, while a SKU must support exact matching. A price should be numeric, and product attributes may require nested documents when each attribute combination must remain associated with the correct variation.

Start with the operation, not the source value

The same WooCommerce value can be represented differently depending on how the store searches and filters it. Before defining a mapping, list the required operations:

Full-text search: Use text for product names, descriptions, and other prose.
Exact matching: Use keyword for SKUs, brand slugs, order statuses, and identifiers.
Filtering and aggregations: Use keyword, numeric types, boolean, or date.
Sorting: Use a numeric, date, or keyword field with doc values enabled.
Location searches: Use geo_point for store or warehouse coordinates.

Mapping a field as text does not make it suitable for every operation. An analyzed text field is optimized for matching terms, not for exact filters, sorting, or useful aggregations.

Use text and keyword together when both behaviors are needed

Product titles and category names commonly need both full-text search and exact operations. A multi-field mapping stores the same source value in different indexed forms:

{
  "properties": {
    "name": {
      "type": "text",
      "fields": {
        "keyword": {
          "type": "keyword",
          "ignore_above": 256
        }
      }
    }
  }
}

The name field can be queried with match, while name.keyword can be used for sorting or aggregating. For example, a product search can analyze “wireless headphones,” while a duplicate check can use an exact term query against a SKU or normalized product identifier.

Do not automatically add a keyword subfield to every long description. Descriptions rarely need exact-value aggregations, and indexing unnecessary subfields increases index size and mapping complexity. For long text, use text alone unless a specific exact-match requirement exists.

Choose keyword for identifiers and controlled values

keyword is appropriate for values that should be treated as a single token. Typical WooCommerce examples include:

SKU and variation SKU
Product, category, and brand slugs
Currency codes such as USD or GBP
Stock status and product status
Shipping classes and tax classes
External IDs from ERP, PIM, or marketplace systems

Use a term query for an exact keyword value. If identifiers may contain inconsistent capitalization or whitespace, normalize them at index time:

{
  "sku": {
    "type": "keyword",
    "normalizer": "lowercase_normalizer"
  }
}

A normalizer can apply character-level normalization without tokenizing the value. Keep the original display value in _source if the storefront must preserve the merchant’s formatting.

Map prices, quantities, and dimensions as numeric fields

WooCommerce prices, stock quantities, weights, and dimensions should not be indexed as strings when the application needs range filters, sorting, or calculations. Use a numeric type that matches the expected range and precision:

integer or long for whole-number quantities and external IDs.
float or double for values where floating-point behavior is acceptable.
scaled_float for currency or fixed decimal precision.

For currency, scaled_float can avoid many floating-point surprises by storing a scaled integer internally:

{
  "price": {
    "type": "scaled_float",
    "scaling_factor": 100
  },
  "stock_quantity": {
    "type": "integer"
  }
}

With a scaling factor of 100, a price of 19.99 is indexed to two decimal places. The synchronization process must still validate the currency and rounding rules before sending data to Elasticsearch. If a catalog supports multiple currencies, index the currency code separately and decide whether prices belong in separate fields, per-currency objects, or a currency-specific index.

Use boolean and date for operational filters

Flags such as featured, virtual, downloadable, and backorders_allowed should use boolean. Avoid indexing values such as yes, no, 1, and 0 inconsistently across products.

Use date for publication dates, modification timestamps, sale periods, and order events. Prefer an unambiguous ISO 8601 representation from the WooCommerce integration:

{
  "date_modified": {
    "type": "date",
    "format": "strict_date_optional_time||epoch_millis"
  },
  "on_sale": {
    "type": "boolean"
  }
}

A sale start or end date can then be queried with range conditions. If a field is optional, the integration should omit it or send a valid null value consistently rather than mixing formatted strings and arbitrary text.

Understand object and nested fields for product data

Elasticsearch maps JSON objects as object by default. This works for a simple product structure such as:

{
  "brand": {
    "slug": "acme",
    "name": "Acme"
  }
}

However, arrays of objects require special care. Consider a variable product with these variation records:

{
  "variations": [
    {"color": "red", "size": "small", "price": 20},
    {"color": "blue", "size": "large", "price": 25}
  ]
}

If variations is mapped as a regular object, Elasticsearch flattens the values into independent multi-value fields. A query for color=red and size=large could incorrectly match the product even though that combination does not exist in one variation.

Use nested when conditions must apply to the same array element:

{
  "variations": {
    "type": "nested",
    "properties": {
      "color": {"type": "keyword"},
      "size": {"type": "keyword"},
      "price": {"type": "scaled_float", "scaling_factor": 100}
    }
  }
}

Queries against nested fields must use a nested query with the correct path. Nested mappings provide accurate relationship handling, but they add query and indexing overhead. Do not use them for every array automatically; use them when cross-field association matters to storefront behavior.

Use flattened for unpredictable metadata

WooCommerce extensions often add arbitrary product metadata. Mapping every possible metadata key as a dedicated field can create mapping growth and eventually trigger field-limit problems. The flattened type is useful when metadata needs basic key-value searching but does not require separate numeric behavior, complex analysis, or nested relationships.

{
  "metadata": {
    "type": "flattened"
  }
}

Use explicit mappings instead when a metadata value needs numeric ranges, date queries, autocomplete, or aggregations with carefully controlled semantics. A common agency pattern is to keep a small set of business-critical attributes as explicit fields and place low-value, extension-specific metadata in a controlled flattened field.

Consider specialized types only for clear use cases

Some catalogs benefit from specialized field types:

geo_point supports distance queries and sorting for stores, pickup locations, and warehouses.
ip is appropriate for customer or administrative IP addresses when they are indexed for filtering or analysis.
completion supports search-as-you-type suggestions, but requires a suggestion-oriented input structure.
wildcard can help with certain expensive wildcard and regular-expression searches, especially on machine-generated identifiers, but should not replace normal product search fields.

These types solve specific problems and can increase storage or query costs. Test the expected query patterns with realistic catalog data before introducing them into a shared index template.

Plan mappings around index lifecycle

Field types cannot generally be changed in place after data has been indexed. Changing a WooCommerce field from text to keyword, or from object to nested, normally requires a new index, a revised mapping, and a reindex operation. Agencies should use versioned index names and aliases so a migration can be prepared without taking search offline.

Define the mapping in version control.
Create a new versioned index with the revised settings and mappings.
Reindex or rebuild products from the authoritative WooCommerce source.
Run representative searches, filters, sorting, and aggregations.
Move the read alias to the new index after validation.

Keep mapping changes coordinated with the WooCommerce synchronization code. A field type is part of the search API contract: changing the serialized value, analyzer, or nesting model can affect queries, facets, and frontend behavior even when the PHP product model appears unchanged.

Practical mapping checklist

Use text for prose that needs analyzed search.
Use keyword for exact identifiers, slugs, statuses, and facets.
Use multi-fields when one value needs both full-text and exact operations.
Use numeric types for prices, quantities, dimensions, and ranges.
Use boolean for true/false flags and date for timestamps.
Use nested when filters must remain tied to one variation or array object.
Use flattened cautiously for unpredictable metadata.
Disable or restrict dynamic field creation for untrusted or highly variable metadata.
Test mappings against the actual filters, sort orders, facets, and variation logic used by the store.

Table of contents :