IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« analyzer copy_to »
Elastic Docs ›Elasticsearch Guide [8.17] ›Mapping ›Mapping parameters

coerce

edit
IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

coerce

edit

Data is not always clean. Depending on how it is produced a number might be rendered in the JSON body as a true JSON number, e.g. 5, but it might also be rendered as a string, e.g. "5". Alternatively, a number that should be an integer might instead be rendered as a floating point, e.g. 5.0, or even "5.0".

Coercion attempts to clean up dirty values to fit the data type of a field. For instance:

  • Strings will be coerced to numbers.
  • Floating points will be truncated for integer values.

For instance:

resp = client.indices.create(
    index="my-index-000001",
    mappings={
        "properties": {
            "number_one": {
                "type": "integer"
            },
            "number_two": {
                "type": "integer",
                "coerce": False
            }
        }
    },
)
print(resp)

resp1 = client.index(
    index="my-index-000001",
    id="1",
    document={
        "number_one": "10"
    },
)
print(resp1)

resp2 = client.index(
    index="my-index-000001",
    id="2",
    document={
        "number_two": "10"
    },
)
print(resp2)
response = client.indices.create(
  index: 'my-index-000001',
  body: {
    mappings: {
      properties: {
        number_one: {
          type: 'integer'
        },
        number_two: {
          type: 'integer',
          coerce: false
        }
      }
    }
  }
)
puts response

response = client.index(
  index: 'my-index-000001',
  id: 1,
  body: {
    number_one: '10'
  }
)
puts response

response = client.index(
  index: 'my-index-000001',
  id: 2,
  body: {
    number_two: '10'
  }
)
puts response
const response = await client.indices.create({
  index: "my-index-000001",
  mappings: {
    properties: {
      number_one: {
        type: "integer",
      },
      number_two: {
        type: "integer",
        coerce: false,
      },
    },
  },
});
console.log(response);

const response1 = await client.index({
  index: "my-index-000001",
  id: 1,
  document: {
    number_one: "10",
  },
});
console.log(response1);

const response2 = await client.index({
  index: "my-index-000001",
  id: 2,
  document: {
    number_two: "10",
  },
});
console.log(response2);
PUT my-index-000001
{
  "mappings": {
    "properties": {
      "number_one": {
        "type": "integer"
      },
      "number_two": {
        "type": "integer",
        "coerce": false
      }
    }
  }
}

PUT my-index-000001/_doc/1
{
  "number_one": "10" 
}

PUT my-index-000001/_doc/2
{
  "number_two": "10" 
}

The number_one field will contain the integer 10.

This document will be rejected because coercion is disabled.

The coerce setting value can be updated on existing fields using the update mapping API.

Index-level default

edit

The index.mapping.coerce setting can be set on the index level to disable coercion globally across all mapping types:

resp = client.indices.create(
    index="my-index-000001",
    settings={
        "index.mapping.coerce": False
    },
    mappings={
        "properties": {
            "number_one": {
                "type": "integer",
                "coerce": True
            },
            "number_two": {
                "type": "integer"
            }
        }
    },
)
print(resp)

resp1 = client.index(
    index="my-index-000001",
    id="1",
    document={
        "number_one": "10"
    },
)
print(resp1)

resp2 = client.index(
    index="my-index-000001",
    id="2",
    document={
        "number_two": "10"
    },
)
print(resp2)
response = client.indices.create(
  index: 'my-index-000001',
  body: {
    settings: {
      'index.mapping.coerce' => false
    },
    mappings: {
      properties: {
        number_one: {
          type: 'integer',
          coerce: true
        },
        number_two: {
          type: 'integer'
        }
      }
    }
  }
)
puts response

response = client.index(
  index: 'my-index-000001',
  id: 1,
  body: {
    number_one: '10'
  }
)
puts response

response = client.index(
  index: 'my-index-000001',
  id: 2,
  body: {
    number_two: '10'
  }
)
puts response
const response = await client.indices.create({
  index: "my-index-000001",
  settings: {
    "index.mapping.coerce": false,
  },
  mappings: {
    properties: {
      number_one: {
        type: "integer",
        coerce: true,
      },
      number_two: {
        type: "integer",
      },
    },
  },
});
console.log(response);

const response1 = await client.index({
  index: "my-index-000001",
  id: 1,
  document: {
    number_one: "10",
  },
});
console.log(response1);

const response2 = await client.index({
  index: "my-index-000001",
  id: 2,
  document: {
    number_two: "10",
  },
});
console.log(response2);
PUT my-index-000001
{
  "settings": {
    "index.mapping.coerce": false
  },
  "mappings": {
    "properties": {
      "number_one": {
        "type": "integer",
        "coerce": true
      },
      "number_two": {
        "type": "integer"
      }
    }
  }
}

PUT my-index-000001/_doc/1
{ "number_one": "10" } 

PUT my-index-000001/_doc/2
{ "number_two": "10" }

The number_one field overrides the index level setting to enable coercion.

This document will be rejected because the number_two field inherits the index-level coercion setting.
« analyzer copy_to »