IP field type

IP field type

An ip field can index/store either IPv4 or IPv6 addresses.

  1. PUT my-index-000001
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "ip_addr": {
  6.         "type": "ip"
  7.       }
  8.     }
  9.   }
  10. }
  12. PUT my-index-000001/_doc/1
  13. {
  14.   "ip_addr": "192.168.1.1"
  15. }
  17. GET my-index-000001/_search
  18. {
  19.   "query": {
  20.     "term": {
  21.       "ip_addr": "192.168.0.0/16"
  22.     }
  23.   }
  24. }

You can also store ip ranges in a single field using an ip_range data type.

Parameters for ip fields

The following parameters are accepted by ip fields:

boost

Mapping field-level query time boosting. Accepts a floating point number, defaults to 1.0.

doc_values

Should the field be stored on disk in a column-stride fashion, so that it can later be used for sorting, aggregations, or scripting? Accepts true (default) or false.

ignore_malformed

If true, malformed IP addresses are ignored. If false (default), malformed IP addresses throw an exception and reject the whole document. Note that this cannot be set if the script parameter is used.

index

Should the field be searchable? Accepts true (default) and false.

null_value

Accepts an IPv4 or IPv6 value which is substituted for any explicit null values. Defaults to null, which means the field is treated as missing. Note that this cannot be set if the script parameter is used.

on_script_error

Defines what to do if the script defined by the script parameter throws an error at indexing time. Accepts reject (default), which will cause the entire document to be rejected, and ignore, which will register the field in the document’s _ignored metadata field and continue indexing. This parameter can only be set if the script field is also set.

script

If this parameter is set, then the field will index values generated by this script, rather than reading the values directly from the source. If a value is set for this field on the input document, then the document will be rejected with an error. Scripts are in the same format as their runtime equivalent, and should emit strings containing IPv4 or IPv6 formatted addresses.

store

Whether the field value should be stored and retrievable separately from the _source field. Accepts true or false (default).

time_series_dimension

[preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. (Optional, Boolean)

For internal use by Elastic only.

Marks the field as a time series dimension. Defaults to false.

The index.mapping.dimension_fields.limit index setting limits the number of dimensions in an index.

Dimension fields have the following constraints:

  • The doc_values and index mapping parameters must be true.
  • Field values cannot be an array or multi-value.

Querying ip fields

The most common way to query ip addresses is to use the CIDR notation: [ip_address]/[prefix_length]. For instance:

  1. GET my-index-000001/_search
  2. {
  3.   "query": {
  4.     "term": {
  5.       "ip_addr": "192.168.0.0/16"
  6.     }
  7.   }
  8. }

or

  1. GET my-index-000001/_search
  2. {
  3.   "query": {
  4.     "term": {
  5.       "ip_addr": "2001:db8::/48"
  6.     }
  7.   }
  8. }

Also beware that colons are special characters to the query_string query, so ipv6 addresses will need to be escaped. The easiest way to do so is to put quotes around the searched value:

  1. GET my-index-000001/_search
  2. {
  3.   "query": {
  4.     "query_string" : {
  5.       "query": "ip_addr:\"2001:db8::/48\""
  6.     }
  7.   }
  8. }