[[ip]]
=== IP field type
++++
<titleabbrev>IP</titleabbrev>
++++

An `ip` field can index/store either {wikipedia}/IPv4[IPv4] or
{wikipedia}/IPv6[IPv6] addresses.

[source,console]
--------------------------------------------------
PUT my-index-000001
{
  "mappings": {
    "properties": {
      "ip_addr": {
        "type": "ip"
      }
    }
  }
}

PUT my-index-000001/_doc/1
{
  "ip_addr": "192.168.1.1"
}

GET my-index-000001/_search
{
  "query": {
    "term": {
      "ip_addr": "192.168.0.0/16"
    }
  }
}
--------------------------------------------------
// TESTSETUP

NOTE: You can also store ip ranges in a single field using an <<range,ip_range data type>>.

[[ip-params]]
==== Parameters for `ip` fields

The following parameters are accepted by `ip` fields:

[horizontal]

<<mapping-boost,`boost`>>::

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

<<doc-values,`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,`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.

<<mapping-index,`index`>>::

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

<<null-value,`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
    <<mapping-ignored-field,`_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-mapping-fields,runtime equivalent>>, and should emit strings
    containing IPv4 or IPv6 formatted addresses.

<<mapping-store,`store`>>::

    Whether the field value should be stored and retrievable separately from
    the <<mapping-source-field,`_source`>> field. Accepts `true` or `false`
    (default).

[[query-ip-fields]]
==== Querying `ip` fields

The most common way to query ip addresses is to use the
{wikipedia}/Classless_Inter-Domain_Routing#CIDR_notation[CIDR]
notation: `[ip_address]/[prefix_length]`. For instance:

[source,console]
--------------------------------------------------
GET my-index-000001/_search
{
  "query": {
    "term": {
      "ip_addr": "192.168.0.0/16"
    }
  }
}
--------------------------------------------------

or

[source,console]
--------------------------------------------------
GET my-index-000001/_search
{
  "query": {
    "term": {
      "ip_addr": "2001:db8::/48"
    }
  }
}
--------------------------------------------------

Also beware that colons are special characters to the
<<query-dsl-query-string-query,`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:

[source,console]
--------------------------------------------------
GET my-index-000001/_search
{
  "query": {
    "query_string" : {
      "query": "ip_addr:\"2001:db8::/48\""
    }
  }
}
--------------------------------------------------
