Извлечение выбранных полей из поиска

По умолчанию каждый результат поиска включает поле документа _source, которое представляет собой весь JSON-объект, предоставленный при индексировании документа. Рекомендуются два метода извлечения выбранных полей из запроса поиска:

Вы можете использовать оба этих метода, хотя параметр fields предпочтительнее, потому что он учитывает как данные документа, так и отображения индекса. В некоторых случаях вам может потребоваться использовать другие методы извлечения данных.

Для извлечения определённых полей в ответе поиска используйте параметр fields. Поскольку он использует отображения индекса, параметр fields предоставляет несколько преимуществ по сравнению с прямым обращением к полю _source. В частности, параметр fields:

Также учитываются другие параметры отображения, включая ignore_above, ignore_malformed и null_value.

Параметр fields возвращает значения в соответствии с тем, как Elasticsearch их индексирует. Для стандартных полей это означает, что параметр fields ищет значения в _source, затем анализирует и форматирует их с использованием отображений.

Следующий запрос поиска использует параметр fields для извлечения значений для поля user.id, всех полей, начинающихся с http.response., и поля @timestamp.

Используя нотацию объектов, вы можете передать аргумент format для настройки формата возвращаемых значений дат или геопространственных данных.

POST my-index-000001/_search
{
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  },
  "fields": [
    "user.id",
    "http.response.*",         
    {
      "field": "@timestamp",
      "format": "epoch_millis" 
    }
  ],
  "_source": false
}

Ответ fields всегда возвращает массив значений для каждого поля, даже если в поле _source содержится единственное значение. Это связано с тем, что в Elasticsearch нет отдельного типа массива, и любое поле может содержать несколько значений. Параметр fields также не гарантирует, что значения массива будут возвращены в определённом порядке. Дополнительную информацию см. в документации по отображению массивов.

Ответ включает значения как плоский список в разделе fields для каждого результата поиска. Поскольку параметр fields не извлекает целые объекты, возвращаются только листовые поля.

{
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "my-index-000001",
        "_id" : "0",
        "_score" : 1.0,
        "_type" : "_doc",
        "fields" : {
          "user.id" : [
            "kimchy"
          ],
          "@timestamp" : [
            "4098435132000"
          ],
          "http.response.bytes": [
            1070000
          ],
          "http.response.status_code": [
            200
          ]
        }
      }
    ]
  }
}

PUT my-index-000001
{
  "mappings": {
    "properties": {
      "group" : { "type" : "keyword" },
      "user": {
        "type": "nested",
        "properties": {
          "first" : { "type" : "keyword" },
          "last" : { "type" : "keyword" }
        }
      }
    }
  }
}

PUT my-index-000001/_doc/1?refresh=true
{
  "group" : "fans",
  "user" : [
    {
      "first" : "John",
      "last" :  "Smith"
    },
    {
      "first" : "Alice",
      "last" :  "White"
    }
  ]
}

POST my-index-000001/_search
{
  "fields": ["*"],
  "_source": false
}

{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.0,
    "hits": [{
      "_index": "my-index-000001",
      "_id": "1",
      "_score": 1.0,
      "_type": "_doc",
      "fields": {
        "group" : ["fans"],
        "user": [{
            "first": ["John"],
            "last": ["Smith"]
          },
          {
            "first": ["Alice"],
            "last": ["White"]
          }
        ]
      }
    }]
  }
}

POST my-index-000001/_search
{
  "fields": ["user.first"],
  "_source": false
}

{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.0,
    "hits": [{
      "_index": "my-index-000001",
      "_id": "1",
      "_score": 1.0,
      "_type": "_doc",
      "fields": {
        "user": [{
            "first": ["John"]
          },
          {
            "first": ["Alice"]
          }
        ]
      }
    }]
  }
}

PUT my-index-000001
{
  "mappings": {
    "enabled": false 
  }
}

PUT my-index-000001/_doc/1?refresh=true
{
  "user_id": "kimchy",
  "session_data": {
     "object": {
       "some_field": "some_value"
     }
   }
}

POST my-index-000001/_search
{
  "fields": [
    "user_id",
    {
      "field": "session_data.object.*",
      "include_unmapped" : true 
    }
  ],
  "_source": false
}

{
  "took" : 2,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "my-index-000001",
        "_id" : "1",
        "_score" : 1.0,
        "_type" : "_doc",
        "fields" : {
          "session_data.object.some_field": [
            "some_value"
          ]
        }
      }
    ]
  }
}

PUT my-index-000001
{
  "mappings": {
    "properties": {
      "my-small" : { "type" : "keyword", "ignore_above": 2 }, 
      "my-large" : { "type" : "keyword" }
    }
  }
}

PUT my-index-000001/_doc/1?refresh=true
{
  "my-small": ["ok", "bad"], 
  "my-large": "ok content"
}

POST my-index-000001/_search
{
  "fields": ["my-*"],
  "_source": false
}

{
  "took" : 2,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "my-index-000001",
        "_type" : "_doc",
        "_id" : "1",
        "_score" : 1.0,
        "_ignored" : [ "my-small"],
        "fields" : {
          "my-large": [
            "ok content"
          ],
          "my-small": [
            "ok"
          ]
        },
        "ignored_field_values" : {
          "my-small": [
            "bad"
          ]
        }
      }
    ]
  }
}

Вы можете использовать параметр _source для выбора, какие поля источника будут возвращены. Это называется фильтрацией источника.

В следующем запросе API поиска параметр тела запроса _source установлен на false. Источник документа не включён в ответ.

GET /_search
{
  "_source": false,
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}

Чтобы вернуть только подмножество полей источника, укажите шаблон подстановки (*) в параметре _source. В следующем запросе API поиска возвращается источник только для поля obj и его свойств.

GET /_search
{
  "_source": "obj.*",
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}

Вы также можете указать массив шаблонов подстановок в поле _source. В следующем запросе API поиска возвращается источник только для полей obj1 и obj2 и их свойств.

GET /_search
{
  "_source": [ "obj1.*", "obj2.*" ],
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}

Для более тонкого управления вы можете указать объект, содержащий массивы шаблонов includes и excludes в параметре _source.

Если свойство includes указано, возвращаются только поля источника, соответствующие одному из его шаблонов. Вы можете исключить поля из этого подмножества, используя свойство excludes.

Если свойство includes не указано, возвращается весь исходный документ, за исключением полей, соответствующих шаблону в свойстве excludes.

Следующий запрос API поиска возвращает исходные данные только для полей obj1 и obj2 и их свойств, исключая любые дочерние поля description.

GET /_search
{
  "_source": {
    "includes": [ "obj1.*", "obj2.*" ],
    "excludes": [ "*.description" ]
  },
  "query": {
    "term": {
      "user.id": "kimchy"
    }
  }
}

Исходные данные документа _source хранятся как одно поле в Lucene. Эта структура означает, что весь объект _source должен быть загружен и проанализирован, даже если вы запрашиваете только часть из него. Чтобы избежать этого ограничения, вы можете попробовать другие варианты загрузки полей:

Elasticsearch всегда пытается загрузить значения из _source. Это поведение имеет те же последствия для фильтрации источника, где Elasticsearch нужно загрузить и проанализировать весь _source, чтобы получить только одно поле.

Вы можете использовать параметр docvalue_fields, чтобы вернуть значения doc values для одного или нескольких полей в ответе поиска.

Значения doc values хранят те же значения, что и _source, но в структуре на диске, основанной на столбцах, которая оптимизирована для сортировки и агрегаций. Поскольку каждое поле хранится отдельно, Elasticsearch читает только запрошенные значения полей и может избежать загрузки всего документа _source.

По умолчанию doc values хранятся для поддерживаемых полей. Однако doc values не поддерживаются для полей типа text или text_annotated.

Следующий запрос поиска использует параметр docvalue_fields для получения значений doc values для поля user.id, всех полей, начинающихся с http.response., и поля @timestamp:

GET my-index-000001/_search
{
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  },
  "docvalue_fields": [
    "user.id",
    "http.response.*", 
    {
      "field": "date",
      "format": "epoch_millis" 
    }
  ]
}

Также можно сохранить значения отдельных полей, используя опцию отображения store. Вы можете использовать параметр stored_fields для включения этих сохранённых значений в ответ поиска.

Позволяет выборочно загружать определенные сохраненные поля для каждого документа, представленного результатом поиска.

GET /_search
{
  "stored_fields" : ["user", "postDate"],
  "query" : {
    "term" : { "user" : "kimchy" }
  }
}

* может быть использован для загрузки всех сохранённых полей из документа.

Пустой массив приведет к возвращению только _id и _type для каждого результата, например:

GET /_search
{
  "stored_fields" : [],
  "query" : {
    "term" : { "user" : "kimchy" }
  }
}

Если запрошенные поля не сохранены (store отображение установлено в false), они будут проигнорированы.

Значения сохранённых полей, извлечённые из самого документа, всегда возвращаются в виде массива. Напротив, метаданные, такие как _routing, никогда не возвращаются в виде массива.

Также только листовые поля могут быть возвращены с помощью параметра stored_fields. Если указано поле объекта, оно будет проигнорировано.

Для отключения сохранённых полей (и метаданных) полностью используйте: _none_:

GET /_search
{
  "stored_fields": "_none_",
  "query" : {
    "term" : { "user" : "kimchy" }
  }
}

Вы можете использовать параметр script_fields для получения результата выполнения скрипта (на основе различных полей) для каждого результата. Например:

GET /_search
{
  "query": {
    "match_all": {}
  },
  "script_fields": {
    "test1": {
      "script": {
        "lang": "painless",
        "source": "doc['price'].value * 2"
      }
    },
    "test2": {
      "script": {
        "lang": "painless",
        "source": "doc['price'].value * params.factor",
        "params": {
          "factor": 2.0
        }
      }
    }
  }
}

Скриптовые поля могут работать с полями, которые не хранятся (price в данном случае) и позволяют возвращать настраиваемые значения (значение, вычисленное скриптом).

Скриптовые поля также могут получить доступ к фактическому документу _source и извлечь определенные элементы для возврата, используя params['_source']. Вот пример:

GET /_search
{
  "query": {
    "match_all": {}
  },
  "script_fields": {
    "test1": {
      "script": "params['_source']['message']"
    }
  }
}

Обратите внимание на ключевое слово _source для навигации по json-подобной модели.

Важно понимать разницу между doc['my_field'].value и params['_source']['my_field']. Первый, используя ключевое слово doc, приведет к загрузке терминов для этого поля в память (кеширование), что приведет к более быстрому выполнению, но большему потреблению памяти. Также обозначение doc[...] позволяет только простые знаковые поля (вы не можете вернуть json-объект из него) и имеет смысл только для неанализируемых или однословных полей. Однако использование doc по-прежнему является рекомендуемым способом доступа к значениям из документа, если это возможно, потому что _source должен быть загружен и проанализирован каждый раз, когда он используется. Использование _source очень медленно.