› ›

API поиска структуры

Находит структуру текста. Текст должен содержать данные, подходящие для импорта в Elastic Stack.

Запрос

POST _text_structure/find_structure

Предварительные условия

Если включены функции безопасности Elasticsearch, вам необходимо иметь monitor_text_structure или monitor права кластера для использования этого API. См. Права доступа к безопасности.

Описание

Этот API предоставляет отправную точку для импорта данных в Elasticsearch в формате, подходящем для последующего использования с другими функциями Elastic Stack.

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

Ответ API содержит:

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

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

Подробности вывода можно увидеть в примерах.

Если поиск структуры даёт неожиданные результаты для какого-либо текста, укажите параметр запроса explain. Это приводит к появлению explanation в ответе, что должно помочь определить причину выбора возвращённой структуры.

Параметры запроса

charset

(Необязательно, строка) Набор символов текста. Он должен быть набором символов, поддерживаемым JVM, используемой Elasticsearch. Например, UTF-8, UTF-16LE, windows-1252 или EUC-JP. Если этот параметр не указан, средство определения структуры выбирает подходящий набор символов.

column_names

(Необязательно, строка) Если вы установили format в delimited, вы можете указать имена столбцов в виде списка, разделенного запятыми. Если этот параметр не указан, средство определения структуры использует имена столбцов из строки заголовка текста. Если в тексте нет строки заголовка, столбцы будут именоваться «column1», «column2», «column3» и т.д.

delimiter

(Необязательно, строка) Если вы установили format в delimited, вы можете указать символ, используемый для разграничения значений в каждой строке. Поддерживается только один символ; разделитель не может иметь несколько символов. По умолчанию API рассматривает следующие возможности: запятая, табуляция, точка с запятой и вертикальная черта (|). В этом сценарии по умолчанию все строки должны иметь одинаковое количество полей для распознавания разделимого формата. Если вы укажете разделитель, до 10% строк могут иметь разное количество столбцов по сравнению с первой строкой.

explain

(Необязательно, логическое значение) Если этот параметр установлен в true, ответ включает поле с именем explanation, которое представляет собой массив строк, указывающих, как средство определения структуры создало свой результат. Значение по умолчанию — false.

format

(Необязательно, строка) Высокоуровневая структура текста. Допустимые значения: ndjson, xml, delimited и semi_structured_text. По умолчанию API выбирает формат. В этом сценарии по умолчанию все строки должны иметь одинаковое количество полей для распознавания разделимого формата. Если format установлено в delimited, а delimiter не установлено, API допускает до 5% строк, имеющих разное количество столбцов по сравнению с первой строкой.

grok_pattern

(Необязательно, строка) Если вы установили format в semi_structured_text, вы можете указать шаблон Grok, используемый для извлечения полей из каждого сообщения в тексте. Имя поля отметки времени в шаблоне Grok должно совпадать с именем, указанным в параметре timestamp_field. Если этот параметр не указан, имя поля отметки времени в шаблоне Grok должно совпадать с "timestamp". Если grok_pattern не указано, средство определения структуры создает шаблон Grok.

has_header_row

(Необязательно, логическое значение) Если вы установили format в delimited, вы можете использовать этот параметр для указания того, находятся ли имена столбцов в первой строке текста. Если этот параметр не указан, средство определения структуры делает предположение на основе сходства первой строки текста с другими строками.

line_merge_size_limit

(Необязательно, целое без знака) Максимальное количество символов в сообщении при объединении строк в сообщения во время анализа полуструктурированного текста. Значение по умолчанию — 10000. При очень длинных сообщениях может потребоваться увеличить это значение, но следует учитывать, что это может привести к очень длительному времени обработки, если способ группирования строк в сообщения определен неправильно.

lines_to_sample

(Необязательно, целое без знака) Количество строк, включаемых в структурный анализ, начиная с начала текста. Минимальное значение — 2; значение по умолчанию — 1000. Если значение этого параметра больше количества строк в тексте, анализ выполняется (при условии, что в тексте есть хотя бы две строки) для всех строк.

Количество строк и их вариативность влияют на скорость анализа. Например, если вы загружаете текст, где первые 1000 строк — это все варианты одного сообщения, анализ найдет больше общего, чем было бы при большем образце. Однако, если возможно, эффективнее загрузить образец текста с большим разнообразием в первых 1000 строках, чем запросить анализ 100000 строк для достижения некоторого разнообразия.

quote

(Необязательно, строка) Если вы установили format в delimited, вы можете указать символ, используемый для выделения значений в каждой строке, если они содержат новые строки или разделитель. Поддерживается только один символ. Если этот параметр не указан, значение по умолчанию — двойная кавычка ("). Если ваш разделимый формат текста не использует кавычки, обходным путём является установка этого аргумента на символ, который не встречается нигде в образце.

should_trim_fields

(Необязательно, логическое значение) Если вы установили format в delimited, вы можете указать, следует ли обрезать пробелы из значений между разделителями. Если этот параметр не указан и разделитель — вертикальная черта (|), значение по умолчанию — true. В противном случае значение по умолчанию — false.

timeout

(Необязательно, единицы измерения времени) Устанавливает максимальное время, которое может занять структурный анализ. Если анализ все ещё выполняется при истечении таймаута, он будет прерван. Значение по умолчанию — 25 секунд.

timestamp_field

(Необязательно, строка) Имя поля, содержащего основную отметку времени каждого запися в тексте. В частности, если текст был импортирован в индекс, это поле будет использоваться для заполнения поля @timestamp.

Если format равно semi_structured_text, это поле должно совпадать с именем соответствующего извлечения в grok_pattern. Поэтому для полуструктурированного текста лучше не указывать этот параметр, если также не указан grok_pattern.

Для структурированного текста, если вы укажете этот параметр, поле должно существовать в тексте.

Если этот параметр не указан, средство определения структуры принимает решение о том, какое поле (если таковое есть) является основным полем отметки времени. Для структурированного текста наличие отметки времени в тексте не обязательно.

timestamp_format

(Необязательно, строка) Формат времени Java поля отметки времени в тексте.

Поддерживается только подмножество буквенных групп формата времени Java:

a
d
dd
EEE
EEEE
H
HH
h
M
MM
MMM
MMMM
mm
ss
XX
XXX
yy
yyyy
zzz

Кроме того, поддерживаются буквенные группы (дробительные секунды) длиной от одного до девяти, если они встречаются после ss и разделены от ss знаком ., , или :. Также допускаются пробелы и знаки препинания, за исключением ?, новой строки и возврата каретки, а также текстовой строки, заключённой в одинарные кавычки. Например, MM/dd HH.mm.ss,SSSSSS 'in' yyyy — это допустимый формат переопределения.

Одним из ценных случаев применения этого параметра является ситуация, когда формат — полуструктурированный текст, в тексте есть несколько форматов отметки времени, и вы знаете, какой формат соответствует основной отметке времени, но не хотите указывать полный grok_pattern. Другой случай — когда формат отметки времени не учитывается средством определения структуры по умолчанию.

Если этот параметр не указан, средство определения структуры выбирает лучший формат из встроенного набора.

В следующей таблице приведены соответствующие значения timeformat для некоторых примеров отметок времени:

Формат времени	Представление
yyyy-MM-dd HH:mm:ssZ	2019-04-20 13:15:22+0000
EEE, d MMM yyyy HH:mm:ss Z	Sat, 20 Apr 2019 13:15:22 +0000
dd.MM.yy HH:mm:ss.SSS	20.04.19 13:15:22.285

См. документацию по формату даты/времени Java для получения дополнительной информации о синтаксисе формата даты и времени.

Тело запроса

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

Примеры

Импорт JSON, разделенного символами новой строки

Предположим, у вас есть текст JSON, разделенный символами новой строки, содержащий информацию о книгах. Вы можете отправить содержимое на find_structure конечную точку:

POST _text_structure/find_structure
{"name": "Leviathan Wakes", "author": "James S.A. Corey", "release_date": "2011-06-02", "page_count": 561}
{"name": "Hyperion", "author": "Dan Simmons", "release_date": "1989-05-26", "page_count": 482}
{"name": "Dune", "author": "Frank Herbert", "release_date": "1965-06-01", "page_count": 604}
{"name": "Dune Messiah", "author": "Frank Herbert", "release_date": "1969-10-15", "page_count": 331}
{"name": "Children of Dune", "author": "Frank Herbert", "release_date": "1976-04-21", "page_count": 408}
{"name": "God Emperor of Dune", "author": "Frank Herbert", "release_date": "1981-05-28", "page_count": 454}
{"name": "Consider Phlebas", "author": "Iain M. Banks", "release_date": "1987-04-23", "page_count": 471}
{"name": "Pandora's Star", "author": "Peter F. Hamilton", "release_date": "2004-03-02", "page_count": 768}
{"name": "Revelation Space", "author": "Alastair Reynolds", "release_date": "2000-03-15", "page_count": 585}
{"name": "A Fire Upon the Deep", "author": "Vernor Vinge", "release_date": "1992-06-01", "page_count": 613}
{"name": "Ender's Game", "author": "Orson Scott Card", "release_date": "1985-06-01", "page_count": 324}
{"name": "1984", "author": "George Orwell", "release_date": "1985-06-01", "page_count": 328}
{"name": "Fahrenheit 451", "author": "Ray Bradbury", "release_date": "1953-10-15", "page_count": 227}
{"name": "Brave New World", "author": "Aldous Huxley", "release_date": "1932-06-01", "page_count": 268}
{"name": "Foundation", "author": "Isaac Asimov", "release_date": "1951-06-01", "page_count": 224}
{"name": "The Giver", "author": "Lois Lowry", "release_date": "1993-04-26", "page_count": 208}
{"name": "Slaughterhouse-Five", "author": "Kurt Vonnegut", "release_date": "1969-06-01", "page_count": 275}
{"name": "The Hitchhiker's Guide to the Galaxy", "author": "Douglas Adams", "release_date": "1979-10-12", "page_count": 180}
{"name": "Snow Crash", "author": "Neal Stephenson", "release_date": "1992-06-01", "page_count": 470}
{"name": "Neuromancer", "author": "William Gibson", "release_date": "1984-07-01", "page_count": 271}
{"name": "The Handmaid's Tale", "author": "Margaret Atwood", "release_date": "1985-06-01", "page_count": 311}
{"name": "Starship Troopers", "author": "Robert A. Heinlein", "release_date": "1959-12-01", "page_count": 335}
{"name": "The Left Hand of Darkness", "author": "Ursula K. Le Guin", "release_date": "1969-06-01", "page_count": 304}
{"name": "The Moon is a Harsh Mistress", "author": "Robert A. Heinlein", "release_date": "1966-04-01", "page_count": 288}

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

{
  "num_lines_analyzed" : 24, 
  "num_messages_analyzed" : 24, 
  "sample_start" : "{\"name\": \"Leviathan Wakes\", \"author\": \"James S.A. Corey\", \"release_date\": \"2011-06-02\", \"page_count\": 561}\n{\"name\": \"Hyperion\", \"author\": \"Dan Simmons\", \"release_date\": \"1989-05-26\", \"page_count\": 482}\n", 
  "charset" : "UTF-8", 
  "has_byte_order_marker" : false, 
  "format" : "ndjson", 
  "timestamp_field" : "release_date", 
  "joda_timestamp_formats" : [ 
    "ISO8601"
  ],
  "java_timestamp_formats" : [ 
    "ISO8601"
  ],
  "need_client_timezone" : true, 
  "mappings" : { 
    "properties" : {
      "@timestamp" : {
        "type" : "date"
      },
      "author" : {
        "type" : "keyword"
      },
      "name" : {
        "type" : "keyword"
      },
      "page_count" : {
        "type" : "long"
      },
      "release_date" : {
        "type" : "date",
        "format" : "iso8601"
      }
    }
  },
  "ingest_pipeline" : {
    "description" : "Ingest pipeline created by text structure finder",
    "processors" : [
      {
        "date" : {
          "field" : "release_date",
          "timezone" : "{{ event.timezone }}",
          "formats" : [
            "ISO8601"
          ]
        }
      }
    ]
  },
  "field_stats" : { 
    "author" : {
      "count" : 24,
      "cardinality" : 20,
      "top_hits" : [
        {
          "value" : "Frank Herbert",
          "count" : 4
        },
        {
          "value" : "Robert A. Heinlein",
          "count" : 2
        },
        {
          "value" : "Alastair Reynolds",
          "count" : 1
        },
        {
          "value" : "Aldous Huxley",
          "count" : 1
        },
        {
          "value" : "Dan Simmons",
          "count" : 1
        },
        {
          "value" : "Douglas Adams",
          "count" : 1
        },
        {
          "value" : "George Orwell",
          "count" : 1
        },
        {
          "value" : "Iain M. Banks",
          "count" : 1
        },
        {
          "value" : "Isaac Asimov",
          "count" : 1
        },
        {
          "value" : "James S.A. Corey",
          "count" : 1
        }
      ]
    },
    "name" : {
      "count" : 24,
      "cardinality" : 24,
      "top_hits" : [
        {
          "value" : "1984",
          "count" : 1
        },
        {
          "value" : "A Fire Upon the Deep",
          "count" : 1
        },
        {
          "value" : "Brave New World",
          "count" : 1
        },
        {
          "value" : "Children of Dune",
          "count" : 1
        },
        {
          "value" : "Consider Phlebas",
          "count" : 1
        },
        {
          "value" : "Dune",
          "count" : 1
        },
        {
          "value" : "Dune Messiah",
          "count" : 1
        },
        {
          "value" : "Ender's Game",
          "count" : 1
        },
        {
          "value" : "Fahrenheit 451",
          "count" : 1
        },
        {
          "value" : "Foundation",
          "count" : 1
        }
      ]
    },
    "page_count" : {
      "count" : 24,
      "cardinality" : 24,
      "min_value" : 180,
      "max_value" : 768,
      "mean_value" : 387.0833333333333,
      "median_value" : 329.5,
      "top_hits" : [
        {
          "value" : 180,
          "count" : 1
        },
        {
          "value" : 208,
          "count" : 1
        },
        {
          "value" : 224,
          "count" : 1
        },
        {
          "value" : 227,
          "count" : 1
        },
        {
          "value" : 268,
          "count" : 1
        },
        {
          "value" : 271,
          "count" : 1
        },
        {
          "value" : 275,
          "count" : 1
        },
        {
          "value" : 288,
          "count" : 1
        },
        {
          "value" : 304,
          "count" : 1
        },
        {
          "value" : 311,
          "count" : 1
        }
      ]
    },
    "release_date" : {
      "count" : 24,
      "cardinality" : 20,
      "earliest" : "1932-06-01",
      "latest" : "2011-06-02",
      "top_hits" : [
        {
          "value" : "1985-06-01",
          "count" : 3
        },
        {
          "value" : "1969-06-01",
          "count" : 2
        },
        {
          "value" : "1992-06-01",
          "count" : 2
        },
        {
          "value" : "1932-06-01",
          "count" : 1
        },
        {
          "value" : "1951-06-01",
          "count" : 1
        },
        {
          "value" : "1953-10-15",
          "count" : 1
        },
        {
          "value" : "1959-12-01",
          "count" : 1
        },
        {
          "value" : "1965-06-01",
          "count" : 1
        },
        {
          "value" : "1966-04-01",
          "count" : 1
        },
        {
          "value" : "1969-10-15",
          "count" : 1
        }
      ]
    }
  }
}

	`num_lines_analyzed` указывает, сколько строк текста было проанализировано.
	`num_messages_analyzed` указывает, сколько различных сообщений содержали эти строки. Для NDJSON это значение совпадает со значением `num_lines_analyzed`. Для других форматов текста сообщения могут занимать несколько строк.
	`sample_start` воспроизводит первые два сообщения в тексте дословно. Это может помочь в диагностике ошибок разбора или случайных загрузок неправильного текста.
	`charset` указывает кодировку символов, используемую для разбора текста.
	Для кодировок UTF-символов `has_byte_order_marker` указывает, начинается ли текст с маркера порядка байтов.
	`format` является одним из `ndjson`, `xml`, `delimited` или `semi_structured_text`.
	`timestamp_field` называет поле, которое, по всей видимости, является основным временным меткой каждого документа.
	`joda_timestamp_formats` используются для указания Logstash, как анализировать временные метки.
	`java_timestamp_formats` — это форматы времени Java, распознаваемые в полях времени. Эти форматы используются в схемах Elasticsearch и конвейерах обработки.
	Если формат временной метки обнаружен без указания часового пояса, `need_client_timezone` будет `true`. Поэтому серверу, который анализирует текст, клиент должен указать правильный часовой пояс.
	`mappings` содержит некоторые подходящие схемы для индекса, в который можно вставить данные. В этом случае полю `release_date` присвоен тип `keyword`, так как оно не считается достаточно специфичным для преобразования в тип `date`.
	`field_stats` содержит наиболее распространенные значения каждого поля, а также основные числовые статистики для числового поля `page_count`. Эта информация может дать подсказки о том, что данные необходимо очистить или преобразовать перед использованием другими функциями Elastic Stack.

Определение структуры примера данных NYC желтых такси

Следующий пример показывает, как можно определить структуру некоторых данных о поездках желтых такси Нью-Йорка. Первая команда curl загружает данные, первые 20000 строк которых затем передаются в конечную точку find_structure. Параметр запроса lines_to_sample конечной точки устанавливается в 20000, чтобы соответствовать значению, указанному в команде head.

curl -s "s3.amazonaws.com/nyc-tlc/trip+data/yellow_tripdata_2018-06.csv" | head -20000 | curl -s -H "Content-Type: application/json" -XPOST "localhost:9200/_text_structure/find_structure?pretty&lines_to_sample=20000" -T -

Заголовок Content-Type: application/json должен быть установлен, даже если в данном случае данные не являются JSON. (В качестве альтернативы Content-Type можно установить на любое другое поддерживаемое Elasticsearch значение, но оно должно быть установлено.)

Если запрос не обнаруживает ошибок, вы получаете следующий результат:

{
  "num_lines_analyzed" : 20000,
  "num_messages_analyzed" : 19998, 
  "sample_start" : "VendorID,tpep_pickup_datetime,tpep_dropoff_datetime,passenger_count,trip_distance,RatecodeID,store_and_fwd_flag,PULocationID,DOLocationID,payment_type,fare_amount,extra,mta_tax,tip_amount,tolls_amount,improvement_surcharge,total_amount\n\n1,2018-06-01 00:15:40,2018-06-01 00:16:46,1,.00,1,N,145,145,2,3,0.5,0.5,0,0,0.3,4.3\n",
  "charset" : "UTF-8",
  "has_byte_order_marker" : false,
  "format" : "delimited", 
  "multiline_start_pattern" : "^.*?,\"?\\d{4}-\\d{2}-\\d{2}[T ]\\d{2}:\\d{2}",
  "exclude_lines_pattern" : "^\"?VendorID\"?,\"?tpep_pickup_datetime\"?,\"?tpep_dropoff_datetime\"?,\"?passenger_count\"?,\"?trip_distance\"?,\"?RatecodeID\"?,\"?store_and_fwd_flag\"?,\"?PULocationID\"?,\"?DOLocationID\"?,\"?payment_type\"?,\"?fare_amount\"?,\"?extra\"?,\"?mta_tax\"?,\"?tip_amount\"?,\"?tolls_amount\"?,\"?improvement_surcharge\"?,\"?total_amount\"?",
  "column_names" : [ 
    "VendorID",
    "tpep_pickup_datetime",
    "tpep_dropoff_datetime",
    "passenger_count",
    "trip_distance",
    "RatecodeID",
    "store_and_fwd_flag",
    "PULocationID",
    "DOLocationID",
    "payment_type",
    "fare_amount",
    "extra",
    "mta_tax",
    "tip_amount",
    "tolls_amount",
    "improvement_surcharge",
    "total_amount"
  ],
  "has_header_row" : true, 
  "delimiter" : ",", 
  "quote" : "\"", 
  "timestamp_field" : "tpep_pickup_datetime", 
  "joda_timestamp_formats" : [ 
    "YYYY-MM-dd HH:mm:ss"
  ],
  "java_timestamp_formats" : [ 
    "yyyy-MM-dd HH:mm:ss"
  ],
  "need_client_timezone" : true, 
  "mappings" : {
    "properties" : {
      "@timestamp" : {
        "type" : "date"
      },
      "DOLocationID" : {
        "type" : "long"
      },
      "PULocationID" : {
        "type" : "long"
      },
      "RatecodeID" : {
        "type" : "long"
      },
      "VendorID" : {
        "type" : "long"
      },
      "extra" : {
        "type" : "double"
      },
      "fare_amount" : {
        "type" : "double"
      },
      "improvement_surcharge" : {
        "type" : "double"
      },
      "mta_tax" : {
        "type" : "double"
      },
      "passenger_count" : {
        "type" : "long"
      },
      "payment_type" : {
        "type" : "long"
      },
      "store_and_fwd_flag" : {
        "type" : "keyword"
      },
      "tip_amount" : {
        "type" : "double"
      },
      "tolls_amount" : {
        "type" : "double"
      },
      "total_amount" : {
        "type" : "double"
      },
      "tpep_dropoff_datetime" : {
        "type" : "date",
        "format" : "yyyy-MM-dd HH:mm:ss"
      },
      "tpep_pickup_datetime" : {
        "type" : "date",
        "format" : "yyyy-MM-dd HH:mm:ss"
      },
      "trip_distance" : {
        "type" : "double"
      }
    }
  },
  "ingest_pipeline" : {
    "description" : "Ingest pipeline created by text structure finder",
    "processors" : [
      {
        "csv" : {
          "field" : "message",
          "target_fields" : [
            "VendorID",
            "tpep_pickup_datetime",
            "tpep_dropoff_datetime",
            "passenger_count",
            "trip_distance",
            "RatecodeID",
            "store_and_fwd_flag",
            "PULocationID",
            "DOLocationID",
            "payment_type",
            "fare_amount",
            "extra",
            "mta_tax",
            "tip_amount",
            "tolls_amount",
            "improvement_surcharge",
            "total_amount"
          ]
        }
      },
      {
        "date" : {
          "field" : "tpep_pickup_datetime",
          "timezone" : "{{ event.timezone }}",
          "formats" : [
            "yyyy-MM-dd HH:mm:ss"
          ]
        }
      },
      {
        "convert" : {
          "field" : "DOLocationID",
          "type" : "long"
        }
      },
      {
        "convert" : {
          "field" : "PULocationID",
          "type" : "long"
        }
      },
      {
        "convert" : {
          "field" : "RatecodeID",
          "type" : "long"
        }
      },
      {
        "convert" : {
          "field" : "VendorID",
          "type" : "long"
        }
      },
      {
        "convert" : {
          "field" : "extra",
          "type" : "double"
        }
      },
      {
        "convert" : {
          "field" : "fare_amount",
          "type" : "double"
        }
      },
      {
        "convert" : {
          "field" : "improvement_surcharge",
          "type" : "double"
        }
      },
      {
        "convert" : {
          "field" : "mta_tax",
          "type" : "double"
        }
      },
      {
        "convert" : {
          "field" : "passenger_count",
          "type" : "long"
        }
      },
      {
        "convert" : {
          "field" : "payment_type",
          "type" : "long"
        }
      },
      {
        "convert" : {
          "field" : "tip_amount",
          "type" : "double"
        }
      },
      {
        "convert" : {
          "field" : "tolls_amount",
          "type" : "double"
        }
      },
      {
        "convert" : {
          "field" : "total_amount",
          "type" : "double"
        }
      },
      {
        "convert" : {
          "field" : "trip_distance",
          "type" : "double"
        }
      },
      {
        "remove" : {
          "field" : "message"
        }
      }
    ]
  },
  "field_stats" : {
    "DOLocationID" : {
      "count" : 19998,
      "cardinality" : 240,
      "min_value" : 1,
      "max_value" : 265,
      "mean_value" : 150.26532653265312,
      "median_value" : 148,
      "top_hits" : [
        {
          "value" : 79,
          "count" : 760
        },
        {
          "value" : 48,
          "count" : 683
        },
        {
          "value" : 68,
          "count" : 529
        },
        {
          "value" : 170,
          "count" : 506
        },
        {
          "value" : 107,
          "count" : 468
        },
        {
          "value" : 249,
          "count" : 457
        },
        {
          "value" : 230,
          "count" : 441
        },
        {
          "value" : 186,
          "count" : 432
        },
        {
          "value" : 141,
          "count" : 409
        },
        {
          "value" : 263,
          "count" : 386
        }
      ]
    },
    "PULocationID" : {
      "count" : 19998,
      "cardinality" : 154,
      "min_value" : 1,
      "max_value" : 265,
      "mean_value" : 153.4042404240424,
      "median_value" : 148,
      "top_hits" : [
        {
          "value" : 79,
          "count" : 1067
        },
        {
          "value" : 230,
          "count" : 949
        },
        {
          "value" : 148,
          "count" : 940
        },
        {
          "value" : 132,
          "count" : 897
        },
        {
          "value" : 48,
          "count" : 853
        },
        {
          "value" : 161,
          "count" : 820
        },
        {
          "value" : 234,
          "count" : 750
        },
        {
          "value" : 249,
          "count" : 722
        },
        {
          "value" : 164,
          "count" : 663
        },
        {
          "value" : 114,
          "count" : 646
        }
      ]
    },
    "RatecodeID" : {
      "count" : 19998,
      "cardinality" : 5,
      "min_value" : 1,
      "max_value" : 5,
      "mean_value" : 1.0656565656565653,
      "median_value" : 1,
      "top_hits" : [
        {
          "value" : 1,
          "count" : 19311
        },
        {
          "value" : 2,
          "count" : 468
        },
        {
          "value" : 5,
          "count" : 195
        },
        {
          "value" : 4,
          "count" : 17
        },
        {
          "value" : 3,
          "count" : 7
        }
      ]
    },
    "VendorID" : {
      "count" : 19998,
      "cardinality" : 2,
      "min_value" : 1,
      "max_value" : 2,
      "mean_value" : 1.59005900590059,
      "median_value" : 2,
      "top_hits" : [
        {
          "value" : 2,
          "count" : 11800
        },
        {
          "value" : 1,
          "count" : 8198
        }
      ]
    },
    "extra" : {
      "count" : 19998,
      "cardinality" : 3,
      "min_value" : -0.5,
      "max_value" : 0.5,
      "mean_value" : 0.4815981598159816,
      "median_value" : 0.5,
      "top_hits" : [
        {
          "value" : 0.5,
          "count" : 19281
        },
        {
          "value" : 0,
          "count" : 698
        },
        {
          "value" : -0.5,
          "count" : 19
        }
      ]
    },
    "fare_amount" : {
      "count" : 19998,
      "cardinality" : 208,
      "min_value" : -100,
      "max_value" : 300,
      "mean_value" : 13.937719771977209,
      "median_value" : 9.5,
      "top_hits" : [
        {
          "value" : 6,
          "count" : 1004
        },
        {
          "value" : 6.5,
          "count" : 935
        },
        {
          "value" : 5.5,
          "count" : 909
        },
        {
          "value" : 7,
          "count" : 903
        },
        {
          "value" : 5,
          "count" : 889
        },
        {
          "value" : 7.5,
          "count" : 854
        },
        {
          "value" : 4.5,
          "count" : 802
        },
        {
          "value" : 8.5,
          "count" : 790
        },
        {
          "value" : 8,
          "count" : 789
        },
        {
          "value" : 9,
          "count" : 711
        }
      ]
    },
    "improvement_surcharge" : {
      "count" : 19998,
      "cardinality" : 3,
      "min_value" : -0.3,
      "max_value" : 0.3,
      "mean_value" : 0.29915991599159913,
      "median_value" : 0.3,
      "top_hits" : [
        {
          "value" : 0.3,
          "count" : 19964
        },
        {
          "value" : -0.3,
          "count" : 22
        },
        {
          "value" : 0,
          "count" : 12
        }
      ]
    },
    "mta_tax" : {
      "count" : 19998,
      "cardinality" : 3,
      "min_value" : -0.5,
      "max_value" : 0.5,
      "mean_value" : 0.4962246224622462,
      "median_value" : 0.5,
      "top_hits" : [
        {
          "value" : 0.5,
          "count" : 19868
        },
        {
          "value" : 0,
          "count" : 109
        },
        {
          "value" : -0.5,
          "count" : 21
        }
      ]
    },
    "passenger_count" : {
      "count" : 19998,
      "cardinality" : 7,
      "min_value" : 0,
      "max_value" : 6,
      "mean_value" : 1.6201620162016201,
      "median_value" : 1,
      "top_hits" : [
        {
          "value" : 1,
          "count" : 14219
        },
        {
          "value" : 2,
          "count" : 2886
        },
        {
          "value" : 5,
          "count" : 1047
        },
        {
          "value" : 3,
          "count" : 804
        },
        {
          "value" : 6,
          "count" : 523
        },
        {
          "value" : 4,
          "count" : 406
        },
        {
          "value" : 0,
          "count" : 113
        }
      ]
    },
    "payment_type" : {
      "count" : 19998,
      "cardinality" : 4,
      "min_value" : 1,
      "max_value" : 4,
      "mean_value" : 1.315631563156316,
      "median_value" : 1,
      "top_hits" : [
        {
          "value" : 1,
          "count" : 13936
        },
        {
          "value" : 2,
          "count" : 5857
        },
        {
          "value" : 3,
          "count" : 160
        },
        {
          "value" : 4,
          "count" : 45
        }
      ]
    },
    "store_and_fwd_flag" : {
      "count" : 19998,
      "cardinality" : 2,
      "top_hits" : [
        {
          "value" : "N",
          "count" : 19910
        },
        {
          "value" : "Y",
          "count" : 88
        }
      ]
    },
    "tip_amount" : {
      "count" : 19998,
      "cardinality" : 717,
      "min_value" : 0,
      "max_value" : 128,
      "mean_value" : 2.010959095909593,
      "median_value" : 1.45,
      "top_hits" : [
        {
          "value" : 0,
          "count" : 6917
        },
        {
          "value" : 1,
          "count" : 1178
        },
        {
          "value" : 2,
          "count" : 624
        },
        {
          "value" : 3,
          "count" : 248
        },
        {
          "value" : 1.56,
          "count" : 206
        },
        {
          "value" : 1.46,
          "count" : 205
        },
        {
          "value" : 1.76,
          "count" : 196
        },
        {
          "value" : 1.45,
          "count" : 195
        },
        {
          "value" : 1.36,
          "count" : 191
        },
        {
          "value" : 1.5,
          "count" : 187
        }
      ]
    },
    "tolls_amount" : {
      "count" : 19998,
      "cardinality" : 26,
      "min_value" : 0,
      "max_value" : 35,
      "mean_value" : 0.2729697969796978,
      "median_value" : 0,
      "top_hits" : [
        {
          "value" : 0,
          "count" : 19107
        },
        {
          "value" : 5.76,
          "count" : 791
        },
        {
          "value" : 10.5,
          "count" : 36
        },
        {
          "value" : 2.64,
          "count" : 21
        },
        {
          "value" : 11.52,
          "count" : 8
        },
        {
          "value" : 5.54,
          "count" : 4
        },
        {
          "value" : 8.5,
          "count" : 4
        },
        {
          "value" : 17.28,
          "count" : 4
        },
        {
          "value" : 2,
          "count" : 2
        },
        {
          "value" : 2.16,
          "count" : 2
        }
      ]
    },
    "total_amount" : {
      "count" : 19998,
      "cardinality" : 1267,
      "min_value" : -100.3,
      "max_value" : 389.12,
      "mean_value" : 17.499898989898995,
      "median_value" : 12.35,
      "top_hits" : [
        {
          "value" : 7.3,
          "count" : 478
        },
        {
          "value" : 8.3,
          "count" : 443
        },
        {
          "value" : 8.8,
          "count" : 420
        },
        {
          "value" : 6.8,
          "count" : 406
        },
        {
          "value" : 7.8,
          "count" : 405
        },
        {
          "value" : 6.3,
          "count" : 371
        },
        {
          "value" : 9.8,
          "count" : 368
        },
        {
          "value" : 5.8,
          "count" : 362
        },
        {
          "value" : 9.3,
          "count" : 332
        },
        {
          "value" : 10.3,
          "count" : 332
        }
      ]
    },
    "tpep_dropoff_datetime" : {
      "count" : 19998,
      "cardinality" : 9066,
      "earliest" : "2018-05-31 06:18:15",
      "latest" : "2018-06-02 02:25:44",
      "top_hits" : [
        {
          "value" : "2018-06-01 01:12:12",
          "count" : 10
        },
        {
          "value" : "2018-06-01 00:32:15",
          "count" : 9
        },
        {
          "value" : "2018-06-01 00:44:27",
          "count" : 9
        },
        {
          "value" : "2018-06-01 00:46:42",
          "count" : 9
        },
        {
          "value" : "2018-06-01 01:03:22",
          "count" : 9
        },
        {
          "value" : "2018-06-01 01:05:13",
          "count" : 9
        },
        {
          "value" : "2018-06-01 00:11:20",
          "count" : 8
        },
        {
          "value" : "2018-06-01 00:16:03",
          "count" : 8
        },
        {
          "value" : "2018-06-01 00:19:47",
          "count" : 8
        },
        {
          "value" : "2018-06-01 00:25:17",
          "count" : 8
        }
      ]
    },
    "tpep_pickup_datetime" : {
      "count" : 19998,
      "cardinality" : 8760,
      "earliest" : "2018-05-31 06:08:31",
      "latest" : "2018-06-02 01:21:21",
      "top_hits" : [
        {
          "value" : "2018-06-01 00:01:23",
          "count" : 12
        },
        {
          "value" : "2018-06-01 00:04:31",
          "count" : 10
        },
        {
          "value" : "2018-06-01 00:05:38",
          "count" : 10
        },
        {
          "value" : "2018-06-01 00:09:50",
          "count" : 10
        },
        {
          "value" : "2018-06-01 00:12:01",
          "count" : 10
        },
        {
          "value" : "2018-06-01 00:14:17",
          "count" : 10
        },
        {
          "value" : "2018-06-01 00:00:34",
          "count" : 9
        },
        {
          "value" : "2018-06-01 00:00:40",
          "count" : 9
        },
        {
          "value" : "2018-06-01 00:02:53",
          "count" : 9
        },
        {
          "value" : "2018-06-01 00:05:40",
          "count" : 9
        }
      ]
    },
    "trip_distance" : {
      "count" : 19998,
      "cardinality" : 1687,
      "min_value" : 0,
      "max_value" : 64.63,
      "mean_value" : 3.6521062106210715,
      "median_value" : 2.16,
      "top_hits" : [
        {
          "value" : 0.9,
          "count" : 335
        },
        {
          "value" : 0.8,
          "count" : 320
        },
        {
          "value" : 1.1,
          "count" : 316
        },
        {
          "value" : 0.7,
          "count" : 304
        },
        {
          "value" : 1.2,
          "count" : 303
        },
        {
          "value" : 1,
          "count" : 296
        },
        {
          "value" : 1.3,
          "count" : 280
        },
        {
          "value" : 1.5,
          "count" : 268
        },
        {
          "value" : 1.6,
          "count" : 268
        },
        {
          "value" : 0.6,
          "count" : 256
        }
      ]
    }
  }
}

	`num_messages_analyzed` на 2 меньше, чем `num_lines_analyzed`, потому что только записи данных считаются сообщениями. Первая строка содержит имена столбцов, а во втором образце строка пустая.
	В отличие от первого примера, в этом случае `format` был идентифицирован как `delimited`.
	Поскольку `format` — это `delimited`, поле `column_names` в выводе перечисляет имена столбцов в порядке их появления в образце.
	`has_header_row` указывает, что в этом образце имена столбцов находились в первой строке образца. (Если бы это не так, было бы неплохо указать их в параметре запроса `column_names`).
	Разделителем `delimiter` для этого образца является запятая, так как это текст в формате CSV.
	Символ `quote` — это двойная кавычка по умолчанию. (Поисковик структуры не пытается вывести любой другой символ кавычек, поэтому, если у вас есть разделительный текст, который заключен в кавычки с каким-то другим символом, вы должны указать его, используя параметр запроса `quote`).
	`timestamp_field` был выбран как `tpep_pickup_datetime`. `tpep_dropoff_datetime` подошло бы также, но `tpep_pickup_datetime` было выбрано, потому что оно стоит первым в порядке столбцов. Если вы предпочитаете `tpep_dropoff_datetime`, заставьте его быть выбранным, используя параметр запроса `timestamp_field`.
	`joda_timestamp_formats` используются для указания Logstash, как анализировать временные метки.
	`java_timestamp_formats` — это форматы времени Java, распознаваемые в полях времени. Эти форматы используются в схемах Elasticsearch и конвейерах обработки.
	Формат временной метки в этом образце не указывает часовой пояс, поэтому для точного преобразования их во временные метки UTC для хранения в Elasticsearch необходимо указать часовой пояс, к которому они относятся. `need_client_timezone` будет `false` для форматов временных меток, которые включают часовой пояс.

Настройка параметра таймаута

Если вы пытаетесь проанализировать большой объем данных, анализ займет много времени. Если вы хотите ограничить объем обработки, выполняемой кластером Elasticsearch для запроса, используйте параметр запроса timeout. Анализ будет прерван, и будет возвращена ошибка, когда таймаут истечет. Например, вы можете заменить 20000 строк в предыдущем примере на 200000 и установить таймаут анализа в 1 секунду:

curl -s "s3.amazonaws.com/nyc-tlc/trip+data/yellow_tripdata_2018-06.csv" | head -200000 | curl -s -H "Content-Type: application/json" -XPOST "localhost:9200/_text_structure/find_structure?pretty&lines_to_sample=200000&timeout=1s" -T -

Если вы не используете невероятно быстрый компьютер, вы получите ошибку таймаута:

{
  "error" : {
    "root_cause" : [
      {
        "type" : "timeout_exception",
        "reason" : "Aborting structure analysis during [delimited record parsing] as it has taken longer than the timeout of [1s]"
      }
    ],
    "type" : "timeout_exception",
    "reason" : "Aborting structure analysis during [delimited record parsing] as it has taken longer than the timeout of [1s]"
  },
  "status" : 500
}

Если вы сами попробуете пример выше, вы заметите, что общее время выполнения команд curl значительно превышает 1 секунду. Это связано с тем, что для загрузки 200000 строк CSV из интернета требуется некоторое время, а таймаут измеряется с момента начала обработки данных этой конечной точкой.

Анализ файлов журнала Elasticsearch

Вот пример анализа файла журнала Elasticsearch:

curl -s -H "Content-Type: application/json" -XPOST "localhost:9200/_text_structure/find_structure?pretty" -T "$ES_HOME/logs/elasticsearch.log"

Если запрос не обнаруживает ошибок, результат будет примерно таким:

{
  "num_lines_analyzed" : 53,
  "num_messages_analyzed" : 53,
  "sample_start" : "[2018-09-27T14:39:28,518][INFO ][o.e.e.NodeEnvironment    ] [node-0] using [1] data paths, mounts [[/ (/dev/disk1)]], net usable_space [165.4gb], net total_space [464.7gb], types [hfs]\n[2018-09-27T14:39:28,521][INFO ][o.e.e.NodeEnvironment    ] [node-0] heap size [494.9mb], compressed ordinary object pointers [true]\n",
  "charset" : "UTF-8",
  "has_byte_order_marker" : false,
  "format" : "semi_structured_text", 
  "multiline_start_pattern" : "^\\[\\b\\d{4}-\\d{2}-\\d{2}[T ]\\d{2}:\\d{2}", 
  "grok_pattern" : "\\[%{TIMESTAMP_ISO8601:timestamp}\\]\\[%{LOGLEVEL:loglevel}.*", 
  "timestamp_field" : "timestamp",
  "joda_timestamp_formats" : [
    "ISO8601"
  ],
  "java_timestamp_formats" : [
    "ISO8601"
  ],
  "need_client_timezone" : true,
  "mappings" : {
    "properties" : {
      "@timestamp" : {
        "type" : "date"
      },
      "loglevel" : {
        "type" : "keyword"
      },
      "message" : {
        "type" : "text"
      }
    }
  },
  "ingest_pipeline" : {
    "description" : "Ingest pipeline created by text structure finder",
    "processors" : [
      {
        "grok" : {
          "field" : "message",
          "patterns" : [
            "\\[%{TIMESTAMP_ISO8601:timestamp}\\]\\[%{LOGLEVEL:loglevel}.*"
          ]
        }
      },
      {
        "date" : {
          "field" : "timestamp",
          "timezone" : "{{ event.timezone }}",
          "formats" : [
            "ISO8601"
          ]
        }
      },
      {
        "remove" : {
          "field" : "timestamp"
        }
      }
    ]
  },
  "field_stats" : {
    "loglevel" : {
      "count" : 53,
      "cardinality" : 3,
      "top_hits" : [
        {
          "value" : "INFO",
          "count" : 51
        },
        {
          "value" : "DEBUG",
          "count" : 1
        },
        {
          "value" : "WARN",
          "count" : 1
        }
      ]
    },
    "timestamp" : {
      "count" : 53,
      "cardinality" : 28,
      "earliest" : "2018-09-27T14:39:28,518",
      "latest" : "2018-09-27T14:39:37,012",
      "top_hits" : [
        {
          "value" : "2018-09-27T14:39:29,859",
          "count" : 10
        },
        {
          "value" : "2018-09-27T14:39:29,860",
          "count" : 9
        },
        {
          "value" : "2018-09-27T14:39:29,858",
          "count" : 6
        },
        {
          "value" : "2018-09-27T14:39:28,523",
          "count" : 3
        },
        {
          "value" : "2018-09-27T14:39:34,234",
          "count" : 2
        },
        {
          "value" : "2018-09-27T14:39:28,518",
          "count" : 1
        },
        {
          "value" : "2018-09-27T14:39:28,521",
          "count" : 1
        },
        {
          "value" : "2018-09-27T14:39:28,522",
          "count" : 1
        },
        {
          "value" : "2018-09-27T14:39:29,861",
          "count" : 1
        },
        {
          "value" : "2018-09-27T14:39:32,786",
          "count" : 1
        }
      ]
    }
  }
}

	На этот раз `format` был идентифицирован как `semi_structured_text`.
	`multiline_start_pattern` установлен на основе того, что временная метка появляется в первой строке каждого многострочного сообщения журнала.
	Была создана очень простая схема `grok_pattern`, которая извлекает временную метку и распознаваемые поля, которые появляются в каждом проанализированном сообщении. В этом случае единственное поле, распознанное помимо временной метки, было уровень журнала.

Указание `grok_pattern` в качестве параметра запроса

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

В случае файла журнала Elasticsearch более полная схема Grok — это \[%{TIMESTAMP_ISO8601:timestamp}\]\[%{LOGLEVEL:loglevel} *\]\[%{JAVACLASS:class} *\] \[%{HOSTNAME:node}\] %{JAVALOGMESSAGE:message}. Вы можете повторно проанализировать тот же текст, отправив эту схему grok_pattern в качестве параметра запроса (соответствующим образом закодировав её в URL):

curl -s -H "Content-Type: application/json" -XPOST "localhost:9200/_text_structure/find_structure?pretty&format=semi_structured_text&grok_pattern=%5C%5B%25%7BTIMESTAMP_ISO8601:timestamp%7D%5C%5D%5C%5B%25%7BLOGLEVEL:loglevel%7D%20*%5C%5D%5C%5B%25%7BJAVACLASS:class%7D%20*%5C%5D%20%5C%5B%25%7BHOSTNAME:node%7D%5C%5D%20%25%7BJAVALOGMESSAGE:message%7D" -T "$ES_HOME/logs/elasticsearch.log"