Skip to content

Commit f75a24a

Browse files
lcawllcawl
committed
Add new requests and responses
1 parent 343d11b commit f75a24a

File tree

4 files changed

+385
-0
lines changed

4 files changed

+385
-0
lines changed

‎specification/text_structure/find_field_structure/FindFieldStructureRequest.ts‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
/*
2+
* Licensed to Elasticsearch B.V. under one or more contributor
3+
* license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright
5+
* ownership. Elasticsearch B.V. licenses this file to you under
6+
* the Apache License, Version 2.0 (the "License"); you may
7+
* not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
import { RequestBase } from '@_types/Base'
21+
import { GrokPattern } from '@_types/common'
22+
import { uint } from '@_types/Numeric'
23+
import { Duration } from '@_types/Time'
24+
/**
25+
* Find the structure of a text field.
26+
* Find the structure of a text field in an Elasticsearch index.
27+
* @rest_spec_name text_structure.find_field_structure
28+
* @availability stack stability=stable visibility=public
29+
* @cluster_privileges monitor_text_structure
30+
*/
31+
interface Request extends RequestBase {
32+
query_parameters: {
33+
/**
34+
* If `format` is set to `delimited`, you can specify the column names in a comma-separated list.
35+
* If this parameter is not specified, the structure finder uses the column names from the header row of the text.
36+
* If the text does not have a header row, columns are named "column1", "column2", "column3", for example.
37+
*/
38+
column_names?: string
39+
/**
40+
* If you have set `format` to `delimited`, you can specify the character used to delimit the values in each row.
41+
* Only a single character is supported; the delimiter cannot have multiple characters.
42+
* By default, the API considers the following possibilities: comma, tab, semi-colon, and pipe (`|`).
43+
* In this default scenario, all rows must have the same number of fields for the delimited format to be detected.
44+
* If you specify a delimiter, up to 10% of the rows can have a different number of columns than the first row.
45+
*/
46+
delimiter?: string
47+
/**
48+
* The number of documents to include in the structural analysis.
49+
* The minimum value is 2.
50+
* @server_default 1000
51+
*/
52+
documents_to_sample?: uint
53+
/**
54+
* The mode of compatibility with ECS compliant Grok patterns.
55+
* Use this parameter to specify whether to use ECS Grok patterns instead of legacy ones when the structure finder creates a Grok pattern.
56+
* This setting primarily has an impact when a whole message Grok pattern such as `%{CATALINALOG}` matches the input.
57+
* If the structure finder identifies a common structure but has no idea of the meaning then generic field names such as `path`, `ipaddress`, `field1`, and `field2` are used in the `grok_pattern` output.
58+
* The intention in that situation is that a user who knows the meanings will rename the fields before using them.
59+
* @server_default disabled
60+
*/
61+
ecs_compatibility?: EcsCompatibilityType
62+
/**
63+
* If true, the response includes a field named `explanation`, which is an array of strings that indicate how the structure finder produced its result.
64+
* @server_default false
65+
*/
66+
explain?: boolean
67+
/**
68+
* The field that should be analyzed.
69+
*/
70+
field: string
71+
/**
72+
* The high level structure of the text.
73+
* By default, the API chooses the format.
74+
* In this default scenario, all rows must have the same number of fields for a delimited format to be detected.
75+
* If the format is set to delimited and the delimiter is not set, however, the API tolerates up to 5% of rows that have a different number of columns than the first row.
76+
*/
77+
format?: FormatType
78+
/**
79+
* If the format is `semi_structured_text`, you can specify a Grok pattern that is used to extract fields from every message in the text.
80+
* The name of the timestamp field in the Grok pattern must match what is specified in the `timestamp_field` parameter.
81+
* If that parameter is not specified, the name of the timestamp field in the Grok pattern must match "timestamp".
82+
* If `grok_pattern` is not specified, the structure finder creates a Grok pattern.
83+
*/
84+
grok_pattern?: GrokPattern
85+
/**
86+
* The name of the index that contains the analyzed field.
87+
*/
88+
index: string
89+
/**
90+
* If the format is `delimited`, you can specify the character used to quote the values in each row if they contain newlines or the delimiter character.
91+
* Only a single character is supported.
92+
* If this parameter is not specified, the default value is a double quote (`"`).
93+
* If your delimited text format does not use quoting, a workaround is to set this argument to a character that does not appear anywhere in the sample.
94+
*/
95+
quote?: string
96+
/**
97+
* If the format is `delimited`, you can specify whether values between delimiters should have whitespace trimmed from them.
98+
* If this parameter is not specified and the delimiter is pipe (`|`), the default value is true.
99+
* Otherwise, the default value is false.
100+
*/
101+
should_trim_fields?: boolean
102+
/**
103+
* The maximum amount of time that the structure analysis can take.
104+
* If the analysis is still running when the timeout expires, it will be stopped.
105+
* @server_default 25s
106+
*/
107+
timeout?: Duration
108+
/**
109+
* The name of the field that contains the primary timestamp of each record in the text.
110+
* In particular, if the text was ingested into an index, this is the field that would be used to populate the `@timestamp` field.
111+
*
112+
* If the format is `semi_structured_text`, this field must match the name of the appropriate extraction in the `grok_pattern`.
113+
* Therefore, for semi-structured text, it is best not to specify this parameter unless `grok_pattern` is also specified.
114+
*
115+
* For structured text, if you specify this parameter, the field must exist within the text.
116+
*
117+
* If this parameter is not specified, the structure finder makes a decision about which field (if any) is the primary timestamp field.
118+
* For structured text, it is not compulsory to have a timestamp in the text.
119+
*/
120+
timestamp_field?: string
121+
/**
122+
* The Java time format of the timestamp field in the text.
123+
* Only a subset of Java time format letter groups are supported:
124+
*
125+
* * `a`
126+
* * `d`
127+
* * `dd`
128+
* * `EEE`
129+
* * `EEEE`
130+
* * `H`
131+
* * `HH`
132+
* * `h`
133+
* * `M`
134+
* * `MM`
135+
* * `MMM`
136+
* * `MMMM`
137+
* * `mm`
138+
* * `ss`
139+
* * `XX`
140+
* * `XXX`
141+
* * `yy`
142+
* * `yyyy`
143+
* * `zzz`
144+
*
145+
* Additionally `S` letter groups (fractional seconds) of length one to nine are supported providing they occur after `ss` and are separated from the `ss` by a period (`.`), comma (`,`), or colon (`:`).
146+
* Spacing and punctuation is also permitted with the exception a question mark (`?`), newline, and carriage return, together with literal text enclosed in single quotes.
147+
* For example, `MM/dd HH.mm.ss,SSSSSS 'in' yyyy` is a valid override format.
148+
*
149+
* One valuable use case for this parameter is when the format is semi-structured text, there are multiple timestamp formats in the text, and you know which format corresponds to the primary timestamp, but you do not want to specify the full `grok_pattern`.
150+
* Another is when the timestamp format is one that the structure finder does not consider by default.
151+
*
152+
* If this parameter is not specified, the structure finder chooses the best format from a built-in set.
153+
*
154+
* If the special value `null` is specified, the structure finder will not look for a primary timestamp in the text.
155+
* When the format is semi-structured text, this will result in the structure finder treating the text as single-line messages.
156+
*/
157+
timestamp_format?: string
158+
}
159+
}
160+
161+
export enum EcsCompatibilityType {
162+
disabled,
163+
v1
164+
}
165+
166+
export enum FormatType {
167+
delimited,
168+
ndjson,
169+
semi_structured_text,
170+
xml
171+
}

‎specification/text_structure/find_field_structure/FindFieldStructureResponse.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
/*
2+
* Licensed to Elasticsearch B.V. under one or more contributor
3+
* license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright
5+
* ownership. Elasticsearch B.V. licenses this file to you under
6+
* the Apache License, Version 2.0 (the "License"); you may
7+
* not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
export class Response {
20+
body: {}
21+
}

‎specification/text_structure/find_message_structure/FindMessageStructureRequest.ts‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
/*
2+
* Licensed to Elasticsearch B.V. under one or more contributor
3+
* license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright
5+
* ownership. Elasticsearch B.V. licenses this file to you under
6+
* the Apache License, Version 2.0 (the "License"); you may
7+
* not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
import { RequestBase } from '@_types/Base'
21+
import { Field, GrokPattern } from '@_types/common'
22+
import { Duration } from '@_types/Time'
23+
/**
24+
* Find the structure of text messages.
25+
* Find the structure of a list of text messages.
26+
* The messages must contain data that is suitable to be ingested into Elasticsearch.
27+
*
28+
* This API provides a starting point for ingesting data into Elasticsearch in a format that is suitable for subsequent use with other Elastic Stack functionality.
29+
* Use this API rather than the find text structure API if your input text has already been split up into separate messages by some other process.
30+
* The response from the API contains:
31+
*
32+
* * Sample messages.
33+
* * Statistics that reveal the most common values for all fields detected within the text and basic numeric statistics for numeric fields.
34+
* * Information about the structure of the text, which is useful when you write ingest configurations to index it or similarly formatted text.
35+
* Appropriate mappings for an Elasticsearch index, which you could use to ingest the text.
36+
*
37+
* All this information can be calculated by the structure finder with no guidance.
38+
* However, you can optionally override some of the decisions about the text structure by specifying one or more query parameters.
39+
* @rest_spec_name text_structure.find_message_structure
40+
* @availability stack stability=stable visibility=public
41+
* @cluster_privileges monitor_text_structure
42+
*/
43+
interface Request extends RequestBase {
44+
query_parameters: {
45+
/** If the format is `delimited`, you can specify the column names in a comma-separated list.
46+
* If this parameter is not specified, the structure finder uses the column names from the header row of the text.
47+
* If the text does not have a header role, columns are named "column1", "column2", "column3", for example.
48+
*/
49+
column_names?: string
50+
/**
51+
* If you the format is `delimited`, you can specify the character used to delimit the values in each row.
52+
* Only a single character is supported; the delimiter cannot have multiple characters.
53+
* By default, the API considers the following possibilities: comma, tab, semi-colon, and pipe (`|`).
54+
* In this default scenario, all rows must have the same number of fields for the delimited format to be detected.
55+
* If you specify a delimiter, up to 10% of the rows can have a different number of columns than the first row.
56+
*/
57+
delimiter?: string
58+
/**
59+
* The mode of compatibility with ECS compliant Grok patterns.
60+
* Use this parameter to specify whether to use ECS Grok patterns instead of legacy ones when the structure finder creates a Grok pattern.
61+
* This setting primarily has an impact when a whole message Grok pattern such as `%{CATALINALOG}` matches the input.
62+
* If the structure finder identifies a common structure but has no idea of meaning then generic field names such as `path`, `ipaddress`, `field1`, and `field2` are used in the `grok_pattern` output, with the intention that a user who knows the meanings rename these fields before using it.
63+
* @server_default disabled
64+
*/
65+
ecs_compatibility?: EcsCompatibilityType
66+
/**
67+
* If this parameter is set to true, the response includes a field named `explanation`, which is an array of strings that indicate how the structure finder produced its result.
68+
* @server_default false
69+
*/
70+
explain?: boolean
71+
/** The high level structure of the text.
72+
* By default, the API chooses the format.
73+
* In this default scenario, all rows must have the same number of fields for a delimited format to be detected.
74+
* If the format is `delimited` and the delimiter is not set, however, the API tolerates up to 5% of rows that have a different number of columns than the first row.
75+
*/
76+
format?: FormatType
77+
/**
78+
* If the format is `semi_structured_text`, you can specify a Grok pattern that is used to extract fields from every message in the text.
79+
* The name of the timestamp field in the Grok pattern must match what is specified in the `timestamp_field` parameter.
80+
* If that parameter is not specified, the name of the timestamp field in the Grok pattern must match "timestamp".
81+
* If `grok_pattern` is not specified, the structure finder creates a Grok pattern.
82+
*/
83+
grok_pattern?: GrokPattern
84+
/**
85+
* If the format is `delimited`, you can specify the character used to quote the values in each row if they contain newlines or the delimiter character.
86+
* Only a single character is supported.
87+
* If this parameter is not specified, the default value is a double quote (`"`).
88+
* If your delimited text format does not use quoting, a workaround is to set this argument to a character that does not appear anywhere in the sample.
89+
*/
90+
quote?: string
91+
/**
92+
* If the format is `delimited`, you can specify whether values between delimiters should have whitespace trimmed from them.
93+
* If this parameter is not specified and the delimiter is pipe (`|`), the default value is true.
94+
* Otherwise, the default value is false.
95+
*/
96+
should_trim_fields?: boolean
97+
/**
98+
* The maximum amount of time that the structure analysis can take.
99+
* If the analysis is still running when the timeout expires, it will be stopped.
100+
* @server_default 25s
101+
*/
102+
timeout?: Duration
103+
/**
104+
* The name of the field that contains the primary timestamp of each record in the text.
105+
* In particular, if the text was ingested into an index, this is the field that would be used to populate the `@timestamp` field.
106+
*
107+
* If the format is `semi_structured_text`, this field must match the name of the appropriate extraction in the `grok_pattern`.
108+
* Therefore, for semi-structured text, it is best not to specify this parameter unless `grok_pattern` is also specified.
109+
*
110+
* For structured text, if you specify this parameter, the field must exist within the text.
111+
*
112+
* If this parameter is not specified, the structure finder makes a decision about which field (if any) is the primary timestamp field.
113+
* For structured text, it is not compulsory to have a timestamp in the text.
114+
*/
115+
timestamp_field?: Field
116+
/**
117+
* The Java time format of the timestamp field in the text.
118+
* Only a subset of Java time format letter groups are supported:
119+
*
120+
* * `a`
121+
* * `d`
122+
* * `dd`
123+
* * `EEE`
124+
* * `EEEE`
125+
* * `H`
126+
* * `HH`
127+
* * `h`
128+
* * `M`
129+
* * `MM`
130+
* * `MMM`
131+
* * `MMMM`
132+
* * `mm`
133+
* * `ss`
134+
* * `XX`
135+
* * `XXX`
136+
* * `yy`
137+
* * `yyyy`
138+
* * `zzz`
139+
*
140+
* Additionally `S` letter groups (fractional seconds) of length one to nine are supported providing they occur after `ss` and are separated from the `ss` by a period (`.`), comma (`,`), or colon (`:`).
141+
* Spacing and punctuation is also permitted with the exception a question mark (`?`), newline, and carriage return, together with literal text enclosed in single quotes.
142+
* For example, `MM/dd HH.mm.ss,SSSSSS 'in' yyyy` is a valid override format.
143+
*
144+
* One valuable use case for this parameter is when the format is semi-structured text, there are multiple timestamp formats in the text, and you know which format corresponds to the primary timestamp, but you do not want to specify the full `grok_pattern`.
145+
* Another is when the timestamp format is one that the structure finder does not consider by default.
146+
*
147+
* If this parameter is not specified, the structure finder chooses the best format from a built-in set.
148+
*
149+
* If the special value `null` is specified, the structure finder will not look for a primary timestamp in the text.
150+
* When the format is semi-structured text, this will result in the structure finder treating the text as single-line messages.
151+
*/
152+
timestamp_format?: string
153+
}
154+
body: {
155+
/**
156+
* The list of messages you want to analyze.
157+
*/
158+
messages: Array<string>
159+
}
160+
}
161+
162+
export enum EcsCompatibilityType {
163+
disabled,
164+
v1
165+
}
166+
167+
export enum FormatType {
168+
delimited,
169+
ndjson,
170+
semi_structured_text,
171+
xml
172+
}

‎specification/text_structure/find_message_structure/FindMessageStructureResponse.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
/*
2+
* Licensed to Elasticsearch B.V. under one or more contributor
3+
* license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright
5+
* ownership. Elasticsearch B.V. licenses this file to you under
6+
* the Apache License, Version 2.0 (the "License"); you may
7+
* not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
export class Response {
20+
body: {}
21+
}

0 commit comments

Comments
 (0)