文本结构
- class elasticsearch.client.TextStructureClient
To use this client, access
client.text_structurefrom anElasticsearchclient. For example:from elasticsearch import Elasticsearch # Create the client instance client = Elasticsearch(...) # Use the text_structure client client.text_structure.<method>(...)
- find_field_structure(*, field, index, column_names=None, delimiter=None, documents_to_sample=None, ecs_compatibility=None, error_trace=None, explain=None, filter_path=None, format=None, grok_pattern=None, human=None, pretty=None, quote=None, should_trim_fields=None, timeout=None, timestamp_field=None, timestamp_format=None)
查找文本字段的结构。 查找Elasticsearch索引中文本字段的结构。
此API为从已摄入Elasticsearch的日志消息中提取更多信息提供了起点。 例如，如果您将数据摄入到一个仅包含
@timestamp和message字段的简单索引中，可以使用此API查看message字段中存在哪些常见结构。API响应包含：
- 示例消息。
- 统计数据，显示文本中检测到的所有字段的最常见值以及数字字段的基本数值统计。
- 关于文本结构的信息，这在编写摄入配置以索引该文本或类似格式文本时非常有用。
- 适用于Elasticsearch索引的映射，可用于摄入文本。
所有这些信息都可以由结构查找器在无指导的情况下计算得出。 但是，您可以选择通过指定一个或多个查询参数来覆盖关于文本结构的部分决策。
如果结构查找器产生意外结果，请指定
explain查询参数，响应中将出现解释。 这有助于确定为何选择返回的结构。https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-text_structure
- Parameters:
field (str) – 需要分析的字段。
index (str) – 包含被分析字段的索引名称。
column_names (str | None) – 如果`format`设置为`delimited`，可以以逗号分隔列表形式指定列名。 如果未指定此参数，结构查找器将使用文本标题行中的列名。如果 文本没有标题行，则列将被命名为”column1”、”column2”、 “column3”等。
delimiter (str | None) – 如果已将`format`设置为`delimited`，可以指定 用于分隔每行值的字符。仅支持单个字符； 分隔符不能有多个字符。默认情况下， API会考虑以下可能性：逗号、制表符、分号和 竖线(|)。在此默认情况下，所有行必须具有相同数量 的字段才能检测到分隔格式。如果指定了分隔符， 最多10%的行可以与第一行具有不同的列数。
documents_to_sample (int | None) – 包含在结构分析中的文档数量。最小值为2。
ecs_compatibility (str | Literal['disabled', 'v1'] | None) – 与ECS兼容Grok模式的兼容模式。 使用此参数指定当结构查找器创建Grok模式时是否使用ECS Grok模式而非 旧版模式。此设置主要在整体消息Grok模式（如`%{CATALINALOG}`） 匹配输入时产生影响。如果结构查找器识别出常见结构 但不知道其含义，则在`grok_pattern`输出中使用通用字段名， 如`path`、ipaddress、field1`和`field2。 这种情况下的意图是，了解含义的用户将在使用前重命名字段。
explain (bool | None) – 如果为`true`，响应将包含名为`explanation`的字段， 这是一个字符串数组，指示结构查找器如何产生其结果。
format (str | Literal['delimited', 'ndjson', 'semi_structured_text', 'xml'] | None) – 文本的高级结构。默认情况下，API选择 格式。在此默认情况下，所有行必须具有相同数量 的字段才能检测到分隔格式。如果格式设置为 delimited且未设置分隔符，API将容忍最多 5%的行与第一行具有不同的列数。
grok_pattern (str | None) – 如果格式为`semi_structured_text`，可以指定 用于从文本中每条消息提取字段的Grok模式。 Grok模式中时间戳字段的名称必须与`timestamp_field`参数中指定的 名称匹配。如果未指定该参数，Grok模式中时间戳字段的名称 必须匹配”timestamp”。如果未指定`grok_pattern`， 结构查找器将创建Grok模式。
quote (str | None) – 如果格式为`delimited`，可以指定用于 引用每行值的字符（如果它们包含换行符或分隔符 字符）。仅支持单个字符。如果未指定此参数， 默认值为双引号(”)。如果您的分隔文本 格式不使用引用，解决方法是将此参数设置为 样本中未出现的字符。
should_trim_fields (bool | None) – 如果格式为`delimited`，可以指定 分隔符之间的值是否应去除空白。如果未指定此参数 且分隔符为竖线(|)，默认值为true。否则， 默认值为`false`。
timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 结构分析可以花费的最大时间量。 如果分析在超时到期时仍在运行，将被停止。
timestamp_field (str | None) – 包含文本中每条记录主时间戳的字段名称。 特别是，如果文本被摄入到索引中，这是将用于填充 @timestamp`字段的字段。如果格式为`semi_structured_text， 此字段必须与`grok_pattern`中适当提取的名称匹配。因此， 对于半结构化文本，最好不要指定此参数，除非同时指定了`grok_pattern`。 对于结构化文本，如果指定此参数，字段必须存在于文本中。 如果未指定此参数，结构查找器将决定哪个字段（如果有）是主 时间戳字段。对于结构化文本，文本中不一定需要有时间戳。
timestamp_format (str | None) – 文本中时间戳字段的Java时间格式。 仅支持Java时间格式字母组的子集：* a * d * dd * EEE * EEEE * H * HH * h * M * MM * MMM * MMMM * mm * ss * XX * XXX * yy * yyyy * zzz 此外，支持长度为一到九的`S`字母组 （分数秒），前提是它们出现在`ss`之后，并通过句点(.)、 逗号(,)或冒号(:)与`ss`分隔。也允许使用空格和标点符号， 但问号(?)、换行符和回车符除外，以及用单引号括起的字面文本。 例如，MM/dd HH.mm.ss,SSSSSS ‘in’ yyyy`是一个有效的覆盖格式。 此参数的一个有价值的用例是当格式为半结构化文本时，文本中有多个时间戳 格式，并且您知道哪种格式对应于主时间戳，但您不想指定完整的`grok_pattern。 另一个是当时间戳格式是结构查找器默认不考虑的格式时。 如果未指定此参数，结构查找器将从内置集合中选择最佳格式。 如果指定特殊值`null`，结构查找器将不会在文本中查找主时间戳。当 格式为半结构化文本时，这将导致结构查找器将文本视为单行消息。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- find_message_structure(*, messages=None, column_names=None, delimiter=None, ecs_compatibility=None, error_trace=None, explain=None, filter_path=None, format=None, grok_pattern=None, human=None, pretty=None, quote=None, should_trim_fields=None, timeout=None, timestamp_field=None, timestamp_format=None, body=None)
查找文本消息的结构。 查找一组文本消息的结构。 这些消息必须包含适合摄入Elasticsearch的数据。
此API为将数据以适合后续与其他Elastic Stack功能配合使用的格式摄入Elasticsearch提供了一个起点。 如果您的输入文本已被其他处理过程分割为独立消息，请使用此API而非查找文本结构API。
API响应包含：
- 示例消息。
- 统计信息，显示文本中检测到的所有字段的最常见值以及数字字段的基本数值统计。
- 关于文本结构的信息，这在编写摄入配置以索引该文本或类似格式文本时非常有用。 适用于Elasticsearch索引的映射，您可以使用这些映射来摄入文本。
所有这些信息都可以由结构查找器在无指导的情况下计算得出。 但是，您可以选择性地通过指定一个或多个查询参数来覆盖关于文本结构的某些决策。
如果结构查找器产生意外结果，请指定
explain查询参数，响应中将包含解释。 这有助于确定为何选择返回的结构。- Parameters:
column_names (str | None) – 如果格式为`delimited`，可以以逗号分隔的列表指定列名。 如果未指定此参数，结构查找器将使用文本标题行中的列名。 如果文本没有标题行，列将被命名为”column1”、”column2”、”column3”等。
delimiter (str | None) – 如果格式为`delimited`，可以指定用于分隔每行值的字符。 仅支持单个字符；分隔符不能包含多个字符。默认情况下，API会考虑以下可能性： 逗号、制表符、分号和竖线(|)。在此默认场景中，所有行必须具有相同数量的字段才能检测到分隔格式。 如果指定了分隔符，最多10%的行可以与第一行具有不同的列数。
ecs_compatibility (str | Literal['disabled', 'v1'] | None) – 与ECS兼容Grok模式的兼容模式。 使用此参数指定当结构查找器创建Grok模式时是否使用ECS Grok模式而非旧版模式。 当整个消息Grok模式（如`%{CATALINALOG}`）匹配输入时，此设置主要产生影响。 如果结构查找器识别出常见结构但不知道其含义，则在`grok_pattern`输出中使用通用字段名， 如`path`、ipaddress、field1`和`field2，目的是让了解其含义的用户在使用前重命名这些字段。
explain (bool | None) – 如果此参数设置为true，响应将包含名为`explanation`的字段， 该字段是一个字符串数组，指示结构查找器如何产生其结果。
format (str | Literal['delimited', 'ndjson', 'semi_structured_text', 'xml'] | None) – 文本的高级结构。默认情况下，API选择格式。在此默认场景中， 所有行必须具有相同数量的字段才能检测到分隔格式。 如果格式为`delimited`且未设置分隔符，API最多容忍5%的行与第一行具有不同的列数。
grok_pattern (str | None) – 如果格式为`semi_structured_text`，可以指定一个Grok模式， 用于从文本中的每条消息提取字段。Grok模式中时间戳字段的名称必须与`timestamp_field` 参数中指定的名称匹配。如果未指定该参数，Grok模式中时间戳字段的名称必须匹配”timestamp”。 如果未指定`grok_pattern`，结构查找器将创建一个Grok模式。
quote (str | None) – 如果格式为`delimited`，可以指定用于引用每行值的字符（如果这些值包含换行符或分隔符）。 仅支持单个字符。如果未指定此参数，默认值为双引号(”)。 如果您的分隔文本格式不使用引用，解决方法是将此参数设置为样本中不出现的字符。
should_trim_fields (bool | None) – 如果格式为`delimited`，可以指定是否应修剪分隔符之间值的空白。 如果未指定此参数且分隔符为竖线(|)，默认值为true。否则，默认值为`false`。
timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 结构分析可以花费的最大时间。 如果分析在超时到期时仍在运行，将被停止。
timestamp_field (str | None) – 包含文本中每条记录主时间戳的字段名称。 特别是，如果文本被摄入索引，此字段将用于填充`@timestamp`字段。 如果格式为`semi_structured_text`，此字段必须与`grok_pattern`中相应提取的名称匹配。 因此，对于半结构化文本，最好不指定此参数，除非同时指定了`grok_pattern`。 对于结构化文本，如果指定此参数，该字段必须存在于文本中。 如果未指定此参数，结构查找器将决定哪个字段（如果有）是主时间戳字段。 对于结构化文本，文本中不必包含时间戳。
timestamp_format (str | None) – 文本中时间戳字段的Java时间格式。 仅支持Java时间格式字母组的子集：* a * d * dd * EEE * EEEE * H * HH * h * M * MM * MMM * MMMM * mm * ss * XX * XXX * yy * yyyy * zzz 此外，支持长度为一到九的`S`字母组（小数秒）， 前提是它们出现在`ss`之后，并通过句点(.)、逗号(,)或冒号(:)与`ss`分隔。 也允许使用空格和标点符号，但问号(?)、换行符和回车符除外，以及用单引号括起的字面文本。 例如，MM/dd HH.mm.ss,SSSSSS ‘in’ yyyy`是一个有效的覆盖格式。 此参数的一个有价值的用例是当格式为半结构化文本时，文本中有多个时间戳格式， 并且您知道哪种格式对应于主时间戳，但您不想指定完整的`grok_pattern。 另一个用例是时间戳格式是结构查找器默认不考虑的格式。 如果未指定此参数，结构查找器将从内置集合中选择最佳格式。 如果指定特殊值`null`，结构查找器将不会在文本中查找主时间戳。 当格式为半结构化文本时，这将导致结构查找器将文本视为单行消息。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- find_structure(*, text_files=None, body=None, charset=None, column_names=None, delimiter=None, ecs_compatibility=None, explain=None, format=None, grok_pattern=None, has_header_row=None, line_merge_size_limit=None, lines_to_sample=None, quote=None, should_trim_fields=None, timeout=None, timestamp_field=None, timestamp_format=None)
查找文本文件的结构。 该文本文件必须包含适合摄入Elasticsearch的数据。
此API为将数据以适合后续与其他Elastic Stack功能配合使用的格式摄入Elasticsearch提供了一个起点。 与其他Elasticsearch端点不同，发布到此端点的数据不需要是UTF-8编码和JSON格式。 但必须是文本；目前不支持二进制文本格式。 大小限制为Elasticsearch HTTP接收缓冲区大小，默认为100 MB。
API的响应包含：
- 文本开头的几条消息。
- 揭示文本中检测到的所有字段最常见值的统计信息，以及数字字段的基本数值统计。
- 关于文本结构的信息，这在编写摄入配置以索引它或类似格式的文本时非常有用。
- Elasticsearch索引的适当映射，可用于摄入文本。
所有这些信息都可以由结构查找器在无指导的情况下计算得出。 但是，您可以选择通过指定一个或多个查询参数来覆盖关于文本结构的一些决策。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-text-structure-find-structure
- Parameters:
charset (str | None) – 文本的字符集。必须是Elasticsearch使用的JVM支持的字符集。 例如，UTF-8、UTF-16LE、windows-1252`或`EUC-JP。如果未指定此参数， 结构查找器将选择合适的字符集。
column_names (str | None) – 如果将格式设置为`delimited`，可以以逗号分隔的列表指定列名。 如果未指定此参数，结构查找器将使用文本标题行中的列名。 如果文本没有标题行，则列将被命名为”column1”、”column2”、”column3”等。
delimiter (str | None) – 如果将`format`设置为`delimited`，可以指定用于分隔每行值的字符。 仅支持单个字符；分隔符不能有多个字符。默认情况下， API会考虑以下可能性：逗号、制表符、分号和竖线(|)。在此默认情况下， 所有行必须具有相同数量的字段才能检测到分隔格式。如果指定了分隔符， 最多10%的行可以与第一行具有不同的列数。
ecs_compatibility (str | None) – 与ECS兼容的Grok模式的兼容模式。 使用此参数指定在结构查找器创建Grok模式时是否使用ECS Grok模式而不是旧模式。 有效值为`disabled`和`v1`。此设置主要在诸如`%{CATALINALOG}`之类的整个消息Grok模式匹配输入时产生影响。 如果结构查找器识别出常见结构但不知道其含义，则在`grok_pattern`输出中使用通用字段名， 如`path`、ipaddress、field1`和`field2，目的是让知道含义的用户在使用前重命名这些字段。
explain (bool | None) – 如果此参数设置为`true`，响应将包含一个名为explanation的字段， 它是一个字符串数组，指示结构查找器如何产生其结果。如果结构查找器对某些文本产生意外结果， 使用此查询参数帮助您确定为什么选择了返回的结构。
format (str | None) – 文本的高级结构。有效值为`ndjson`、xml、delimited`和`semi_structured_text。 默认情况下，API选择格式。在此默认情况下，所有行必须具有相同数量的字段才能检测到分隔格式。 但是，如果格式设置为`delimited`且未设置分隔符，API容忍最多5%的行与第一行具有不同的列数。
grok_pattern (str | None) – 如果将`format`设置为`semi_structured_text`，可以指定一个Grok模式， 用于从文本中的每条消息提取字段。Grok模式中时间戳字段的名称必须与`timestamp_field`参数中指定的匹配。 如果未指定该参数，Grok模式中时间戳字段的名称必须匹配”timestamp”。 如果未指定`grok_pattern`，结构查找器将创建一个Grok模式。
has_header_row (bool | None) – 如果将`format`设置为`delimited`，可以使用此参数指示列名是否在文本的第一行中。 如果未指定此参数，结构查找器将根据文本第一行与其他行的相似性进行猜测。
line_merge_size_limit (int | None) – 在分析半结构化文本时，合并行形成消息时消息的最大字符数。 如果有极长的消息，可能需要增加此值，但请注意，如果误检测了将行分组为消息的方式， 这可能导致非常长的处理时间。
lines_to_sample (int | None) – 包含在结构分析中的行数，从文本开头开始。最小为2。 如果此参数的值大于文本中的行数，分析将继续进行（只要文本中至少有两行）所有行。 注意：行数和行的变化会影响分析速度。例如，如果上传的文本前1000行都是同一消息的变体， 分析将找到比更大样本更多的共性。但如果可能，上传前1000行有更多变化的样本文本比请求分析100000行以实现某些变化更高效。
quote (str | None) – 如果将`format`设置为`delimited`，可以指定用于引用每行值的字符，如果它们包含换行符或分隔符字符。 仅支持单个字符。如果未指定此参数，默认值为双引号(”)。如果分隔文本格式不使用引用， 解决方法是将此参数设置为样本中不出现的字符。
should_trim_fields (bool | None) – 如果将`format`设置为`delimited`，可以指定分隔符之间的值是否应去除空白。 如果未指定此参数且分隔符为竖线(|)，默认值为`true`。否则，默认值为`false`。
timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 结构分析可以花费的最大时间。如果分析在超时到期时仍在运行，则将被停止。
timestamp_field (str | None) – 包含文本中每条记录主要时间戳的字段名称。特别是，如果文本被摄入索引， 此字段将用于填充`@timestamp`字段。如果`format`为`semi_structured_text`， 此字段必须与`grok_pattern`中适当提取的名称匹配。因此，对于半结构化文本， 除非同时指定了`grok_pattern`，最好不要指定此参数。对于结构化文本，如果指定此参数， 字段必须存在于文本中。如果未指定此参数，结构查找器将决定哪个字段（如果有）是主要时间戳字段。 对于结构化文本，文本中不必有时间戳。
timestamp_format (str | None) – 文本中时间戳字段的Java时间格式。 仅支持Java时间格式字母组的子集：* a * d * dd * EEE * EEEE * H * HH * h * M * MM * MMM * MMMM * mm * ss * XX * XXX * yy * yyyy * zzz 此外，支持长度为一到九的`S`字母组（小数秒）， 前提是它们出现在`ss`之后，并通过`.`、,`或:与`ss`分隔。也允许间距和标点符号， 除了?`、换行和回车，以及用单引号括起的字面文本。例如，MM/dd HH.mm.ss,SSSSSS ‘in’ yyyy`是一个有效的覆盖格式。 此参数的一个有价值的用例是当格式为半结构化文本，文本中有多个时间戳格式， 并且您知道哪个格式对应于主要时间戳，但您不想指定完整的`grok_pattern。 另一个是当时间戳格式是结构查找器默认不考虑的格式。如果未指定此参数， 结构查找器将从内置集合中选择最佳格式。如果指定特殊值`null`， 结构查找器将不会在文本中查找主要时间戳。当格式为半结构化文本时， 这将导致结构查找器将文本视为单行消息。
- Return type:
- test_grok_pattern(*, grok_pattern=None, text=None, ecs_compatibility=None, error_trace=None, filter_path=None, human=None, pretty=None, body=None)
测试 Grok 模式。 在一行或多行文本上测试 Grok 模式。 API 会返回文本行是否匹配该模式，以及匹配子字符串的偏移量和长度。