Общие параметры

Следующие параметры могут применяться ко всем REST API.

При добавлении ?pretty=true к любому запросу, возвращаемый JSON будет отформатирован красиво (используйте только для отладки!). Другой вариант - установить ?format=yaml, что приведёт к возврату результата в (иногда) более читабельном формате yaml.

Статистика возвращается в формате, подходящем для людей (например, "exists_time": "1h" или "size": "1kb") и для компьютеров (например, "exists_time_in_millis": 3600000 или "size_in_bytes": 1024). Читаемые человеком значения могут быть отключены путем добавления ?human=false к строке запроса. Это имеет смысл, когда результаты статистики используются инструментом мониторинга, а не предназначены для просмотра человеком. Значение по умолчанию для флага human равно false.

Большинство параметров, которые принимают отформатированное значение даты — такие как gt и lt в range запросах, или from и to в daterange агрегациях — понимают математические операции с датами.

Выражение начинается с базовой даты, которая может быть либо now, либо строкой даты, заканчивающейся на ||. За базовой датой может следовать одно или несколько математических выражений:

Поддерживаемые единицы времени отличаются от тех, которые поддерживаются единицами времени для продолжительности. Поддерживаемые единицы:

Предполагая, что now равно 2001-01-01 12:00:00, некоторые примеры:

Все REST API принимают параметр filter_path, который может использоваться для уменьшения размера ответа, возвращаемого Elasticsearch. Этот параметр принимает разделенный запятыми список фильтров, выраженных с использованием точечной нотации:

GET /_search?q=kimchy&filter_path=took,hits.hits._id,hits.hits._score

Возвращает:

{
  "took" : 3,
  "hits" : {
    "hits" : [
      {
        "_id" : "0",
        "_score" : 1.6375021
      }
    ]
  }
}

Он также поддерживает подстановочный знак * для сопоставления любого поля или части имени поля:

GET /_cluster/state?filter_path=metadata.indices.*.stat*

Возвращает:

{
  "metadata" : {
    "indices" : {
      "my-index-000001": {"state": "open"}
    }
  }
}

А подстановочный знак ** может использоваться для включения полей без знания точного пути к полю. Например, мы можем вернуть состояние каждого шарда с помощью этого запроса:

GET /_cluster/state?filter_path=routing_table.indices.**.state

Возвращает:

{
  "routing_table": {
    "indices": {
      "my-index-000001": {
        "shards": {
          "0": [{"state": "STARTED"}, {"state": "UNASSIGNED"}]
        }
      }
    }
  }
}

Также можно исключить одно или несколько полей, добавив перед фильтром символ -:

GET /_count?filter_path=-_shards

Возвращает:

{
  "count" : 5
}

Для большего контроля включающие и исключающие фильтры могут быть объединены в одном выражении. В этом случае исключающие фильтры будут применены первыми, и результат будет снова отфильтрован с использованием включающих фильтров:

GET /_cluster/state?filter_path=metadata.indices.*.state,-metadata.indices.logstash-*

Возвращает:

{
  "metadata" : {
    "indices" : {
      "my-index-000001" : {"state" : "open"},
      "my-index-000002" : {"state" : "open"},
      "my-index-000003" : {"state" : "open"}
    }
  }
}

Обратите внимание, что Elasticsearch иногда возвращает непосредственно необработанное значение поля, например, поле _source. Если вы хотите фильтровать поля _source, вам следует рассмотреть возможность объединения уже существующего параметра _source (см. Get API для получения более подробной информации) с параметром filter_path следующим образом:

POST /library/book?refresh
{"title": "Book #1", "rating": 200.1}
POST /library/book?refresh
{"title": "Book #2", "rating": 1.7}
POST /library/book?refresh
{"title": "Book #3", "rating": 0.1}
GET /_search?filter_path=hits.hits._source&_source=title&sort=rating:desc

{
  "hits" : {
    "hits" : [ {
      "_source":{"title":"Book #1"}
    }, {
      "_source":{"title":"Book #2"}
    }, {
      "_source":{"title":"Book #3"}
    } ]
  }
}

Флаг flat_settings влияет на отображение списков настроек. Когда флаг flat_settings установлен в true, настройки возвращаются в плоском формате:

GET my-index-000001/_settings?flat_settings=true

Возвращает:

{
  "my-index-000001" : {
    "settings": {
      "index.number_of_replicas": "1",
      "index.number_of_shards": "1",
      "index.creation_date": "1474389951325",
      "index.uuid": "n6gzFZTgS664GUfx0Xrpjw",
      "index.version.created": ...,
      "index.routing.allocation.include._tier_preference" : "data_content",
      "index.provided_name" : "my-index-000001"
    }
  }
}

Когда флаг flat_settings установлен в false, настройки возвращаются в более читабельном структурированном формате:

GET my-index-000001/_settings?flat_settings=false

Возвращает:

{
  "my-index-000001" : {
    "settings" : {
      "index" : {
        "number_of_replicas": "1",
        "number_of_shards": "1",
        "creation_date": "1474389951325",
        "uuid": "n6gzFZTgS664GUfx0Xrpjw",
        "version": {
          "created": ...
        },
        "routing": {
          "allocation": {
            "include": {
              "_tier_preference": "data_content"
            }
          }
        },
        "provided_name" : "my-index-000001"
      }
    }
  }
}

По умолчанию flat_settings установлен в false.

Параметры REST (при использовании HTTP, отображаются в параметрах URL HTTP) следуют соглашению об использовании нижнего подчеркивания в качестве разделителя слов.

Все параметры REST API (как параметры запроса, так и тело JSON) поддерживают предоставление логического значения "false" в виде false и логического значения "true" в виде true. Все другие значения приведут к ошибке.

Все REST API поддерживают предоставление числовых параметров как string в дополнение к поддержке собственных числовых типов JSON.

Всякий раз, когда необходимо указать продолжительность, например, для параметра timeout, продолжительность должна указывать единицу измерения, например, 2d для 2 дней. Поддерживаемые единицы:

Всякий раз, когда необходимо указать размер данных в байтах, например, при установке параметра размера буфера, значение должно указывать единицу измерения, например, 10kb для 10 килобайт. Обратите внимание, что эти единицы используют степени числа 1024, поэтому 1kb означает 1024 байта. Поддерживаемые единицы:

Безразмерные величины означают, что у них нет "единицы измерения", такой как "байты", "Герцы", "метры" или "длинная тонна".

Если одна из этих величин велика, мы будем выводить ее как 10m для 10 000 000 или 7k для 7 000. Мы все еще будем выводить 87, когда имеем в виду 87. Это поддерживаемые множители:

В тех случаях, когда необходимо указать расстояния, например, параметр distance в запросе географического расстояния, по умолчанию используется единица измерения метры, если не указано иное. Расстояния можно указывать в других единицах, таких как "1km" или "2mi" (2 мили).

Полный список единиц приведен ниже:

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

При запросе к полям text или keyword, fuzziness интерпретируется как расстояние Левенштейна — количество односимвольных изменений, которые необходимо внести в одну строку, чтобы сделать её такой же, как другая строка.

Параметр fuzziness можно указать следующим образом:

По умолчанию, когда запрос возвращает ошибку, Elasticsearch не включает трассировку стека ошибки. Вы можете включить это поведение, установив параметр URL error_trace в значение true. Например, по умолчанию, когда вы отправляете неверный параметр size в API _search:

POST /my-index-000001/_search?size=surprise_me

Ответ выглядит следующим образом:

{
  "error" : {
    "root_cause" : [
      {
        "type" : "illegal_argument_exception",
        "reason" : "Failed to parse int parameter [size] with value [surprise_me]"
      }
    ],
    "type" : "illegal_argument_exception",
    "reason" : "Failed to parse int parameter [size] with value [surprise_me]",
    "caused_by" : {
      "type" : "number_format_exception",
      "reason" : "For input string: \"surprise_me\""
    }
  },
  "status" : 400
}

Но если вы установите error_trace=true:

POST /my-index-000001/_search?size=surprise_me&error_trace=true

Ответ выглядит следующим образом:

{
  "error": {
    "root_cause": [
      {
        "type": "illegal_argument_exception",
        "reason": "Failed to parse int parameter [size] with value [surprise_me]",
        "stack_trace": "Failed to parse int parameter [size] with value [surprise_me]]; nested: IllegalArgumentException..."
      }
    ],
    "type": "illegal_argument_exception",
    "reason": "Failed to parse int parameter [size] with value [surprise_me]",
    "stack_trace": "java.lang.IllegalArgumentException: Failed to parse int parameter [size] with value [surprise_me]\n    at org.elasticsearch.rest.RestRequest.paramAsInt(RestRequest.java:175)...",
    "caused_by": {
      "type": "number_format_exception",
      "reason": "For input string: \"surprise_me\"",
      "stack_trace": "java.lang.NumberFormatException: For input string: \"surprise_me\"\n    at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)..."
    }
  },
  "status": 400
}

Для библиотек, которые не принимают тело запроса для запросов, отличных от POST, вы можете передать тело запроса в качестве параметра строки запроса source. При использовании этого метода также следует передать параметр source_content_type со значением типа носителя, которое указывает формат источника, например, application/json.

Тип содержимого, отправляемого в теле запроса, должен быть указан с помощью заголовка Content-Type. Значение этого заголовка должно соответствовать одному из поддерживаемых API форматов. Большинство API поддерживают JSON, YAML, CBOR и SMILE. API массового и многократного поиска поддерживают NDJSON, JSON и SMILE; другие типы приведут к ответу с ошибкой.

При использовании параметра строки запроса source, тип содержимого должен быть указан с помощью параметра строки запроса source_content_type.

Elasticsearch поддерживает только UTF-8 кодированный JSON. Elasticsearch игнорирует любые другие заголовки кодирования, отправленные с запросом. Ответы также закодированы в UTF-8.