Skip to content

Commit dd6c13f

Browse files
dimitris-athanasioudimitris-athanasiou
authored
[ML] Add description to DF analytics (#45774) (#46019)
1 parent 2671839 commit dd6c13f

File tree

11 files changed

+110
-9
lines changed

11 files changed

+110
-9
lines changed

‎client/rest-high-level/src/main/java/org/elasticsearch/client/ml/dataframe/DataFrameAnalyticsConfig.java

Lines changed: 25 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ public static Builder builder() {
4848
}
4949

5050
private static final ParseField ID = new ParseField("id");
51+
private static final ParseField DESCRIPTION = new ParseField("description");
5152
private static final ParseField SOURCE = new ParseField("source");
5253
private static final ParseField DEST = new ParseField("dest");
5354
private static final ParseField ANALYSIS = new ParseField("analysis");
@@ -60,6 +61,7 @@ public static Builder builder() {
6061

6162
static {
6263
PARSER.declareString(Builder::setId, ID);
64+
PARSER.declareString(Builder::setDescription, DESCRIPTION);
6365
PARSER.declareObject(Builder::setSource, (p, c) -> DataFrameAnalyticsSource.fromXContent(p), SOURCE);
6466
PARSER.declareObject(Builder::setDest, (p, c) -> DataFrameAnalyticsDest.fromXContent(p), DEST);
6567
PARSER.declareObject(Builder::setAnalysis, (p, c) -> parseAnalysis(p), ANALYSIS);
@@ -95,6 +97,7 @@ private static DataFrameAnalysis parseAnalysis(XContentParser parser) throws IOE
9597
}
9698

9799
private final String id;
100+
private final String description;
98101
private final DataFrameAnalyticsSource source;
99102
private final DataFrameAnalyticsDest dest;
100103
private final DataFrameAnalysis analysis;
@@ -103,10 +106,12 @@ private static DataFrameAnalysis parseAnalysis(XContentParser parser) throws IOE
103106
private final Instant createTime;
104107
private final Version version;
105108

106-
private DataFrameAnalyticsConfig(@Nullable String id, @Nullable DataFrameAnalyticsSource source, @Nullable DataFrameAnalyticsDest dest,
107-
@Nullable DataFrameAnalysis analysis, @Nullable FetchSourceContext analyzedFields,
108-
@Nullable ByteSizeValue modelMemoryLimit, @Nullable Instant createTime, @Nullable Version version) {
109+
private DataFrameAnalyticsConfig(@Nullable String id, @Nullable String description, @Nullable DataFrameAnalyticsSource source,
110+
@Nullable DataFrameAnalyticsDest dest, @Nullable DataFrameAnalysis analysis,
111+
@Nullable FetchSourceContext analyzedFields, @Nullable ByteSizeValue modelMemoryLimit,
112+
@Nullable Instant createTime, @Nullable Version version) {
109113
this.id = id;
114+
this.description = description;
110115
this.source = source;
111116
this.dest = dest;
112117
this.analysis = analysis;
@@ -120,6 +125,10 @@ public String getId() {
120125
return id;
121126
}
122127

128+
public String getDescription() {
129+
return description;
130+
}
131+
123132
public DataFrameAnalyticsSource getSource() {
124133
return source;
125134
}
@@ -154,6 +163,9 @@ public XContentBuilder toXContent(XContentBuilder builder, Params params) throws
154163
if (id != null) {
155164
builder.field(ID.getPreferredName(), id);
156165
}
166+
if (description != null) {
167+
builder.field(DESCRIPTION.getPreferredName(), description);
168+
}
157169
if (source != null) {
158170
builder.field(SOURCE.getPreferredName(), source);
159171
}
@@ -189,6 +201,7 @@ public boolean equals(Object o) {
189201

190202
DataFrameAnalyticsConfig other = (DataFrameAnalyticsConfig) o;
191203
return Objects.equals(id, other.id)
204+
&& Objects.equals(description, other.description)
192205
&& Objects.equals(source, other.source)
193206
&& Objects.equals(dest, other.dest)
194207
&& Objects.equals(analysis, other.analysis)
@@ -200,7 +213,7 @@ public boolean equals(Object o) {
200213

201214
@Override
202215
public int hashCode() {
203-
return Objects.hash(id, source, dest, analysis, analyzedFields, modelMemoryLimit, createTime, version);
216+
return Objects.hash(id, description, source, dest, analysis, analyzedFields, modelMemoryLimit, createTime, version);
204217
}
205218

206219
@Override
@@ -211,6 +224,7 @@ public String toString() {
211224
public static class Builder {
212225

213226
private String id;
227+
private String description;
214228
private DataFrameAnalyticsSource source;
215229
private DataFrameAnalyticsDest dest;
216230
private DataFrameAnalysis analysis;
@@ -226,6 +240,11 @@ public Builder setId(String id) {
226240
return this;
227241
}
228242

243+
public Builder setDescription(String description) {
244+
this.description = description;
245+
return this;
246+
}
247+
229248
public Builder setSource(DataFrameAnalyticsSource source) {
230249
this.source = Objects.requireNonNull(source);
231250
return this;
@@ -262,7 +281,8 @@ public Builder setVersion(Version version) {
262281
}
263282

264283
public DataFrameAnalyticsConfig build() {
265-
return new DataFrameAnalyticsConfig(id, source, dest, analysis, analyzedFields, modelMemoryLimit, createTime, version);
284+
return new DataFrameAnalyticsConfig(id, description, source, dest, analysis, analyzedFields, modelMemoryLimit, createTime,
285+
version);
266286
}
267287
}
268288
}

‎client/rest-high-level/src/test/java/org/elasticsearch/client/MachineLearningIT.java

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1257,6 +1257,7 @@ public void testPutDataFrameAnalyticsConfig() throws Exception {
12571257
.setIndex("put-test-dest-index")
12581258
.build())
12591259
.setAnalysis(OutlierDetection.createDefault())
1260+
.setDescription("some description")
12601261
.build();
12611262

12621263
createIndex("put-test-source-index", defaultMappingForTest());
@@ -1273,6 +1274,7 @@ public void testPutDataFrameAnalyticsConfig() throws Exception {
12731274
assertThat(createdConfig.getAnalysis(), equalTo(config.getAnalysis()));
12741275
assertThat(createdConfig.getAnalyzedFields(), equalTo(config.getAnalyzedFields()));
12751276
assertThat(createdConfig.getModelMemoryLimit(), equalTo(ByteSizeValue.parseBytesSizeValue("1gb", ""))); // default value
1277+
assertThat(createdConfig.getDescription(), equalTo("some description"));
12761278
}
12771279

12781280
public void testGetDataFrameAnalyticsConfig_SingleConfig() throws Exception {

‎client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2950,6 +2950,7 @@ public void testPutDataFrameAnalytics() throws Exception {
29502950
.setAnalysis(outlierDetection) // <4>
29512951
.setAnalyzedFields(analyzedFields) // <5>
29522952
.setModelMemoryLimit(new ByteSizeValue(5, ByteSizeUnit.MB)) // <6>
2953+
.setDescription("this is an example description") // <7>
29532954
.build();
29542955
// end::put-data-frame-analytics-config
29552956

‎client/rest-high-level/src/test/java/org/elasticsearch/client/ml/dataframe/DataFrameAnalyticsConfigTests.java

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,9 @@ public static DataFrameAnalyticsConfig randomDataFrameAnalyticsConfig() {
4949
.setSource(randomSourceConfig())
5050
.setDest(randomDestConfig())
5151
.setAnalysis(randomOutlierDetection());
52+
if (randomBoolean()) {
53+
builder.setDescription(randomAlphaOfLength(20));
54+
}
5255
if (randomBoolean()) {
5356
builder.setAnalyzedFields(new FetchSourceContext(true,
5457
generateRandomStringArray(10, 10, false, false),

‎docs/java-rest/high-level/ml/put-data-frame-analytics.asciidoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ include-tagged::{doc-tests-file}[{api}-config]
3636
<4> The analysis to be performed
3737
<5> The fields to be included in / excluded from the analysis
3838
<6> The memory limit for the model created as part of the analysis process
39+
<7> Optionally, a human-readable description
3940

4041
[id="{upid}-{api}-query-config"]
4142

‎docs/reference/ml/df-analytics/apis/dfanalyticsresources.asciidoc

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,9 @@ PUT _ml/data_frame/analytics/loganalytics
4242
// CONSOLE
4343
// TEST[setup:setup_logdata]
4444

45+
`description`::
46+
(Optional, string) A description of the job.
47+
4548
`dest`::
4649
(object) The destination configuration of the analysis. The `index` property
4750
(string) is the name of the index in which to store the results of the

‎docs/reference/ml/df-analytics/apis/put-dfanalytics.asciidoc

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,10 @@ and mappings.
6565
(Optional, object) You can specify both `includes` and/or `excludes` patterns. If
6666
`analyzed_fields` is not set, only the relevant fields will be included. For
6767
example, all the numeric fields for {oldetection}.
68-
68+
69+
`description`::
70+
(Optional, string) A description of the job.
71+
6972
`dest`::
7073
(Required, object) The destination configuration, consisting of `index` and
7174
optionally `results_field` (`ml` by default). See
@@ -94,6 +97,7 @@ type is `outlier_detection`:
9497
--------------------------------------------------
9598
PUT _ml/data_frame/analytics/loganalytics
9699
{
100+
"description": "Outlier detection on log data",
97101
"source": {
98102
"index": "logdata"
99103
},
@@ -115,6 +119,7 @@ The API returns the following result:
115119
----
116120
{
117121
"id" : "loganalytics",
122+
"description": "Outlier detection on log data",
118123
"source" : {
119124
"index" : [
120125
"logdata"

‎x-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/ml/dataframe/DataFrameAnalyticsConfig.java

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ public class DataFrameAnalyticsConfig implements ToXContentObject, Writeable {
4444
public static final ByteSizeValue PROCESS_MEMORY_OVERHEAD = new ByteSizeValue(20, ByteSizeUnit.MB);
4545

4646
public static final ParseField ID = new ParseField("id");
47+
public static final ParseField DESCRIPTION = new ParseField("description");
4748
public static final ParseField SOURCE = new ParseField("source");
4849
public static final ParseField DEST = new ParseField("dest");
4950
public static final ParseField ANALYSIS = new ParseField("analysis");
@@ -62,6 +63,7 @@ private static ObjectParser<Builder, Void> createParser(boolean ignoreUnknownFie
6263

6364
parser.declareString((c, s) -> {}, CONFIG_TYPE);
6465
parser.declareString(Builder::setId, ID);
66+
parser.declareString(Builder::setDescription, DESCRIPTION);
6567
parser.declareObject(Builder::setSource, DataFrameAnalyticsSource.createParser(ignoreUnknownFields), SOURCE);
6668
parser.declareObject(Builder::setDest, DataFrameAnalyticsDest.createParser(ignoreUnknownFields), DEST);
6769
parser.declareObject(Builder::setAnalysis, (p, c) -> parseAnalysis(p, ignoreUnknownFields), ANALYSIS);
@@ -100,6 +102,7 @@ private static DataFrameAnalysis parseAnalysis(XContentParser parser, boolean ig
100102
}
101103

102104
private final String id;
105+
private final String description;
103106
private final DataFrameAnalyticsSource source;
104107
private final DataFrameAnalyticsDest dest;
105108
private final DataFrameAnalysis analysis;
@@ -117,10 +120,11 @@ private static DataFrameAnalysis parseAnalysis(XContentParser parser, boolean ig
117120
private final Instant createTime;
118121
private final Version version;
119122

120-
public DataFrameAnalyticsConfig(String id, DataFrameAnalyticsSource source, DataFrameAnalyticsDest dest,
123+
public DataFrameAnalyticsConfig(String id, String description, DataFrameAnalyticsSource source, DataFrameAnalyticsDest dest,
121124
DataFrameAnalysis analysis, Map<String, String> headers, ByteSizeValue modelMemoryLimit,
122125
FetchSourceContext analyzedFields, Instant createTime, Version version) {
123126
this.id = ExceptionsHelper.requireNonNull(id, ID);
127+
this.description = description;
124128
this.source = ExceptionsHelper.requireNonNull(source, SOURCE);
125129
this.dest = ExceptionsHelper.requireNonNull(dest, DEST);
126130
this.analysis = ExceptionsHelper.requireNonNull(analysis, ANALYSIS);
@@ -133,6 +137,11 @@ public DataFrameAnalyticsConfig(String id, DataFrameAnalyticsSource source, Data
133137

134138
public DataFrameAnalyticsConfig(StreamInput in) throws IOException {
135139
this.id = in.readString();
140+
if (in.getVersion().onOrAfter(Version.V_7_4_0)) {
141+
description = in.readOptionalString();
142+
} else {
143+
description = null;
144+
}
136145
this.source = new DataFrameAnalyticsSource(in);
137146
this.dest = new DataFrameAnalyticsDest(in);
138147
this.analysis = in.readNamedWriteable(DataFrameAnalysis.class);
@@ -152,6 +161,10 @@ public String getId() {
152161
return id;
153162
}
154163

164+
public String getDescription() {
165+
return description;
166+
}
167+
155168
public DataFrameAnalyticsSource getSource() {
156169
return source;
157170
}
@@ -188,6 +201,9 @@ public Version getVersion() {
188201
public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException {
189202
builder.startObject();
190203
builder.field(ID.getPreferredName(), id);
204+
if (description != null) {
205+
builder.field(DESCRIPTION.getPreferredName(), description);
206+
}
191207
builder.field(SOURCE.getPreferredName(), source);
192208
builder.field(DEST.getPreferredName(), dest);
193209

@@ -218,6 +234,9 @@ public XContentBuilder toXContent(XContentBuilder builder, Params params) throws
218234
@Override
219235
public void writeTo(StreamOutput out) throws IOException {
220236
out.writeString(id);
237+
if (out.getVersion().onOrAfter(Version.V_7_4_0)) {
238+
out.writeOptionalString(description);
239+
}
221240
source.writeTo(out);
222241
dest.writeTo(out);
223242
out.writeNamedWriteable(analysis);
@@ -242,6 +261,7 @@ public boolean equals(Object o) {
242261

243262
DataFrameAnalyticsConfig other = (DataFrameAnalyticsConfig) o;
244263
return Objects.equals(id, other.id)
264+
&& Objects.equals(description, other.description)
245265
&& Objects.equals(source, other.source)
246266
&& Objects.equals(dest, other.dest)
247267
&& Objects.equals(analysis, other.analysis)
@@ -254,7 +274,7 @@ public boolean equals(Object o) {
254274

255275
@Override
256276
public int hashCode() {
257-
return Objects.hash(id, source, dest, analysis, headers, getModelMemoryLimit(), analyzedFields, createTime, version);
277+
return Objects.hash(id, description, source, dest, analysis, headers, getModelMemoryLimit(), analyzedFields, createTime, version);
258278
}
259279

260280
@Override
@@ -269,6 +289,7 @@ public static String documentId(String id) {
269289
public static class Builder {
270290

271291
private String id;
292+
private String description;
272293
private DataFrameAnalyticsSource source;
273294
private DataFrameAnalyticsDest dest;
274295
private DataFrameAnalysis analysis;
@@ -287,6 +308,7 @@ public Builder(DataFrameAnalyticsConfig config) {
287308

288309
public Builder(DataFrameAnalyticsConfig config, ByteSizeValue maxModelMemoryLimit) {
289310
this.id = config.id;
311+
this.description = config.description;
290312
this.source = new DataFrameAnalyticsSource(config.source);
291313
this.dest = new DataFrameAnalyticsDest(config.dest);
292314
this.analysis = config.analysis;
@@ -304,6 +326,11 @@ public String getId() {
304326
return id;
305327
}
306328

329+
public Builder setDescription(String description) {
330+
this.description = description;
331+
return this;
332+
}
333+
307334
public Builder setId(String id) {
308335
this.id = ExceptionsHelper.requireNonNull(id, ID);
309336
return this;
@@ -354,7 +381,8 @@ public Builder setVersion(Version version) {
354381
*/
355382
public DataFrameAnalyticsConfig build() {
356383
applyMaxModelMemoryLimit();
357-
return new DataFrameAnalyticsConfig(id, source, dest, analysis, headers, modelMemoryLimit, analyzedFields, createTime, version);
384+
return new DataFrameAnalyticsConfig(id, description, source, dest, analysis, headers, modelMemoryLimit, analyzedFields,
385+
createTime, version);
358386
}
359387

360388
/**
@@ -365,6 +393,7 @@ public DataFrameAnalyticsConfig build() {
365393
public DataFrameAnalyticsConfig buildForMemoryEstimation() {
366394
return new DataFrameAnalyticsConfig(
367395
id != null ? id : "dummy",
396+
description,
368397
source,
369398
dest != null ? dest : new DataFrameAnalyticsDest("dummy", null),
370399
analysis,

‎x-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/ml/job/results/ReservedFieldNames.java

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -286,6 +286,7 @@ public final class ReservedFieldNames {
286286
ChunkingConfig.TIME_SPAN_FIELD.getPreferredName(),
287287

288288
DataFrameAnalyticsConfig.ID.getPreferredName(),
289+
DataFrameAnalyticsConfig.DESCRIPTION.getPreferredName(),
289290
DataFrameAnalyticsConfig.SOURCE.getPreferredName(),
290291
DataFrameAnalyticsConfig.DEST.getPreferredName(),
291292
DataFrameAnalyticsConfig.ANALYSIS.getPreferredName(),

‎x-pack/plugin/core/src/test/java/org/elasticsearch/xpack/core/ml/dataframe/DataFrameAnalyticsConfigTests.java

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,9 @@ public static DataFrameAnalyticsConfig.Builder createRandomBuilder(String id, bo
113113
if (randomBoolean()) {
114114
builder.setModelMemoryLimit(new ByteSizeValue(randomIntBetween(1, 16), randomFrom(ByteSizeUnit.MB, ByteSizeUnit.GB)));
115115
}
116+
if (randomBoolean()) {
117+
builder.setDescription(randomAlphaOfLength(20));
118+
}
116119
if (withGeneratedFields) {
117120
if (randomBoolean()) {
118121
builder.setCreateTime(Instant.now());

‎x-pack/plugin/src/test/resources/rest-api-spec/test/ml/data_frame_analytics_crud.yml

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1182,3 +1182,36 @@ setup:
11821182
}}
11831183
- is_true: create_time
11841184
- is_true: version
1185+
1186+
---
1187+
"Test put with description":
1188+
1189+
- do:
1190+
ml.put_data_frame_analytics:
1191+
id: "with-description"
1192+
body: >
1193+
{
1194+
"description": "This is a described config",
1195+
"source": {
1196+
"index": "index-source"
1197+
},
1198+
"dest": {
1199+
"index": "index-dest"
1200+
},
1201+
"analysis": {
1202+
"regression": {
1203+
"dependent_variable": "foo"
1204+
}
1205+
}
1206+
}
1207+
- match: { id: "with-description" }
1208+
- match: { description: "This is a described config" }
1209+
- match: { source.index: ["index-source"] }
1210+
- match: { dest.index: "index-dest" }
1211+
- match: { analysis: {
1212+
"regression":{
1213+
"dependent_variable": "foo"
1214+
}
1215+
}}
1216+
- is_true: create_time
1217+
- is_true: version

0 commit comments

Comments
 (0)