1# Licensed to Elasticsearch B.V. under one or more contributor 2# license agreements. See the NOTICE file distributed with 3# this work for additional information regarding copyright 4# ownership. Elasticsearch B.V. licenses this file to you under 5# the Apache License, Version 2.0 (the "License"); you may 6# not use this file except in compliance with the License. 7# You may obtain a copy of the License at 8# 9# http://www.apache.org/licenses/LICENSE-2.0 10# 11# Unless required by applicable law or agreed to in writing, 12# software distributed under the License is distributed on an 13# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 14# KIND, either express or implied. See the License for the 15# specific language governing permissions and limitations 16# under the License. 17 18from .utils import SKIP_IN_PATH, NamespacedClient, _bulk_body, _make_path, query_params 19 20 21class MlClient(NamespacedClient): 22 @query_params("allow_no_jobs", "allow_no_match", "force", "timeout") 23 def close_job(self, job_id, body=None, params=None, headers=None): 24 """ 25 Closes one or more anomaly detection jobs. A job can be opened and closed 26 multiple times throughout its lifecycle. 27 28 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-close-job.html>`_ 29 30 :arg job_id: The name of the job to close 31 :arg body: The URL params optionally sent in the body 32 :arg allow_no_jobs: Whether to ignore if a wildcard expression 33 matches no jobs. (This includes `_all` string or when no jobs have been 34 specified) 35 :arg allow_no_match: Whether to ignore if a wildcard expression 36 matches no jobs. (This includes `_all` string or when no jobs have been 37 specified) 38 :arg force: True if the job should be forcefully closed 39 :arg timeout: Controls the time to wait until a job has closed. 40 Default to 30 minutes 41 """ 42 if job_id in SKIP_IN_PATH: 43 raise ValueError("Empty value passed for a required argument 'job_id'.") 44 45 return self.transport.perform_request( 46 "POST", 47 _make_path("_ml", "anomaly_detectors", job_id, "_close"), 48 params=params, 49 headers=headers, 50 body=body, 51 ) 52 53 @query_params() 54 def delete_calendar(self, calendar_id, params=None, headers=None): 55 """ 56 Deletes a calendar. 57 58 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-delete-calendar.html>`_ 59 60 :arg calendar_id: The ID of the calendar to delete 61 """ 62 if calendar_id in SKIP_IN_PATH: 63 raise ValueError( 64 "Empty value passed for a required argument 'calendar_id'." 65 ) 66 67 return self.transport.perform_request( 68 "DELETE", 69 _make_path("_ml", "calendars", calendar_id), 70 params=params, 71 headers=headers, 72 ) 73 74 @query_params() 75 def delete_calendar_event(self, calendar_id, event_id, params=None, headers=None): 76 """ 77 Deletes scheduled events from a calendar. 78 79 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-delete-calendar-event.html>`_ 80 81 :arg calendar_id: The ID of the calendar to modify 82 :arg event_id: The ID of the event to remove from the calendar 83 """ 84 for param in (calendar_id, event_id): 85 if param in SKIP_IN_PATH: 86 raise ValueError("Empty value passed for a required argument.") 87 88 return self.transport.perform_request( 89 "DELETE", 90 _make_path("_ml", "calendars", calendar_id, "events", event_id), 91 params=params, 92 headers=headers, 93 ) 94 95 @query_params() 96 def delete_calendar_job(self, calendar_id, job_id, params=None, headers=None): 97 """ 98 Deletes anomaly detection jobs from a calendar. 99 100 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-delete-calendar-job.html>`_ 101 102 :arg calendar_id: The ID of the calendar to modify 103 :arg job_id: The ID of the job to remove from the calendar 104 """ 105 for param in (calendar_id, job_id): 106 if param in SKIP_IN_PATH: 107 raise ValueError("Empty value passed for a required argument.") 108 109 return self.transport.perform_request( 110 "DELETE", 111 _make_path("_ml", "calendars", calendar_id, "jobs", job_id), 112 params=params, 113 headers=headers, 114 ) 115 116 @query_params("force") 117 def delete_datafeed(self, datafeed_id, params=None, headers=None): 118 """ 119 Deletes an existing datafeed. 120 121 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-delete-datafeed.html>`_ 122 123 :arg datafeed_id: The ID of the datafeed to delete 124 :arg force: True if the datafeed should be forcefully deleted 125 """ 126 if datafeed_id in SKIP_IN_PATH: 127 raise ValueError( 128 "Empty value passed for a required argument 'datafeed_id'." 129 ) 130 131 return self.transport.perform_request( 132 "DELETE", 133 _make_path("_ml", "datafeeds", datafeed_id), 134 params=params, 135 headers=headers, 136 ) 137 138 @query_params("requests_per_second", "timeout") 139 def delete_expired_data(self, body=None, job_id=None, params=None, headers=None): 140 """ 141 Deletes expired and unused machine learning data. 142 143 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-delete-expired-data.html>`_ 144 145 :arg body: deleting expired data parameters 146 :arg job_id: The ID of the job(s) to perform expired data 147 hygiene for 148 :arg requests_per_second: The desired requests per second for 149 the deletion processes. 150 :arg timeout: How long can the underlying delete processes run 151 until they are canceled 152 """ 153 return self.transport.perform_request( 154 "DELETE", 155 _make_path("_ml", "_delete_expired_data", job_id), 156 params=params, 157 headers=headers, 158 body=body, 159 ) 160 161 @query_params() 162 def delete_filter(self, filter_id, params=None, headers=None): 163 """ 164 Deletes a filter. 165 166 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-delete-filter.html>`_ 167 168 :arg filter_id: The ID of the filter to delete 169 """ 170 if filter_id in SKIP_IN_PATH: 171 raise ValueError("Empty value passed for a required argument 'filter_id'.") 172 173 return self.transport.perform_request( 174 "DELETE", 175 _make_path("_ml", "filters", filter_id), 176 params=params, 177 headers=headers, 178 ) 179 180 @query_params("allow_no_forecasts", "timeout") 181 def delete_forecast(self, job_id, forecast_id=None, params=None, headers=None): 182 """ 183 Deletes forecasts from a machine learning job. 184 185 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-delete-forecast.html>`_ 186 187 :arg job_id: The ID of the job from which to delete forecasts 188 :arg forecast_id: The ID of the forecast to delete, can be comma 189 delimited list. Leaving blank implies `_all` 190 :arg allow_no_forecasts: Whether to ignore if `_all` matches no 191 forecasts 192 :arg timeout: Controls the time to wait until the forecast(s) 193 are deleted. Default to 30 seconds 194 """ 195 if job_id in SKIP_IN_PATH: 196 raise ValueError("Empty value passed for a required argument 'job_id'.") 197 198 return self.transport.perform_request( 199 "DELETE", 200 _make_path("_ml", "anomaly_detectors", job_id, "_forecast", forecast_id), 201 params=params, 202 headers=headers, 203 ) 204 205 @query_params("force", "wait_for_completion") 206 def delete_job(self, job_id, params=None, headers=None): 207 """ 208 Deletes an existing anomaly detection job. 209 210 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-delete-job.html>`_ 211 212 :arg job_id: The ID of the job to delete 213 :arg force: True if the job should be forcefully deleted 214 :arg wait_for_completion: Should this request wait until the 215 operation has completed before returning Default: True 216 """ 217 if job_id in SKIP_IN_PATH: 218 raise ValueError("Empty value passed for a required argument 'job_id'.") 219 220 return self.transport.perform_request( 221 "DELETE", 222 _make_path("_ml", "anomaly_detectors", job_id), 223 params=params, 224 headers=headers, 225 ) 226 227 @query_params() 228 def delete_model_snapshot(self, job_id, snapshot_id, params=None, headers=None): 229 """ 230 Deletes an existing model snapshot. 231 232 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-delete-snapshot.html>`_ 233 234 :arg job_id: The ID of the job to fetch 235 :arg snapshot_id: The ID of the snapshot to delete 236 """ 237 for param in (job_id, snapshot_id): 238 if param in SKIP_IN_PATH: 239 raise ValueError("Empty value passed for a required argument.") 240 241 return self.transport.perform_request( 242 "DELETE", 243 _make_path( 244 "_ml", "anomaly_detectors", job_id, "model_snapshots", snapshot_id 245 ), 246 params=params, 247 headers=headers, 248 ) 249 250 @query_params("advance_time", "calc_interim", "end", "skip_time", "start") 251 def flush_job(self, job_id, body=None, params=None, headers=None): 252 """ 253 Forces any buffered data to be processed by the job. 254 255 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-flush-job.html>`_ 256 257 :arg job_id: The name of the job to flush 258 :arg body: Flush parameters 259 :arg advance_time: Advances time to the given value generating 260 results and updating the model for the advanced interval 261 :arg calc_interim: Calculates interim results for the most 262 recent bucket or all buckets within the latency period 263 :arg end: When used in conjunction with calc_interim, specifies 264 the range of buckets on which to calculate interim results 265 :arg skip_time: Skips time to the given value without generating 266 results or updating the model for the skipped interval 267 :arg start: When used in conjunction with calc_interim, 268 specifies the range of buckets on which to calculate interim results 269 """ 270 if job_id in SKIP_IN_PATH: 271 raise ValueError("Empty value passed for a required argument 'job_id'.") 272 273 return self.transport.perform_request( 274 "POST", 275 _make_path("_ml", "anomaly_detectors", job_id, "_flush"), 276 params=params, 277 headers=headers, 278 body=body, 279 ) 280 281 @query_params("duration", "expires_in", "max_model_memory") 282 def forecast(self, job_id, params=None, headers=None): 283 """ 284 Predicts the future behavior of a time series by using its historical behavior. 285 286 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-forecast.html>`_ 287 288 :arg job_id: The ID of the job to forecast for 289 :arg duration: The duration of the forecast 290 :arg expires_in: The time interval after which the forecast 291 expires. Expired forecasts will be deleted at the first opportunity. 292 :arg max_model_memory: The max memory able to be used by the 293 forecast. Default is 20mb. 294 """ 295 if job_id in SKIP_IN_PATH: 296 raise ValueError("Empty value passed for a required argument 'job_id'.") 297 298 return self.transport.perform_request( 299 "POST", 300 _make_path("_ml", "anomaly_detectors", job_id, "_forecast"), 301 params=params, 302 headers=headers, 303 ) 304 305 @query_params( 306 "anomaly_score", 307 "desc", 308 "end", 309 "exclude_interim", 310 "expand", 311 "from_", 312 "size", 313 "sort", 314 "start", 315 ) 316 def get_buckets(self, job_id, body=None, timestamp=None, params=None, headers=None): 317 """ 318 Retrieves anomaly detection job results for one or more buckets. 319 320 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-get-bucket.html>`_ 321 322 :arg job_id: ID of the job to get bucket results from 323 :arg body: Bucket selection details if not provided in URI 324 :arg timestamp: The timestamp of the desired single bucket 325 result 326 :arg anomaly_score: Filter for the most anomalous buckets 327 :arg desc: Set the sort direction 328 :arg end: End time filter for buckets 329 :arg exclude_interim: Exclude interim results 330 :arg expand: Include anomaly records 331 :arg from_: skips a number of buckets 332 :arg size: specifies a max number of buckets to get 333 :arg sort: Sort buckets by a particular field 334 :arg start: Start time filter for buckets 335 """ 336 if "from_" in params: 337 params["from"] = params.pop("from_") 338 339 if job_id in SKIP_IN_PATH: 340 raise ValueError("Empty value passed for a required argument 'job_id'.") 341 342 return self.transport.perform_request( 343 "POST", 344 _make_path( 345 "_ml", "anomaly_detectors", job_id, "results", "buckets", timestamp 346 ), 347 params=params, 348 headers=headers, 349 body=body, 350 ) 351 352 @query_params("end", "from_", "job_id", "size", "start") 353 def get_calendar_events(self, calendar_id, params=None, headers=None): 354 """ 355 Retrieves information about the scheduled events in calendars. 356 357 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-get-calendar-event.html>`_ 358 359 :arg calendar_id: The ID of the calendar containing the events 360 :arg end: Get events before this time 361 :arg from_: Skips a number of events 362 :arg job_id: Get events for the job. When this option is used 363 calendar_id must be '_all' 364 :arg size: Specifies a max number of events to get 365 :arg start: Get events after this time 366 """ 367 if "from_" in params: 368 params["from"] = params.pop("from_") 369 370 if calendar_id in SKIP_IN_PATH: 371 raise ValueError( 372 "Empty value passed for a required argument 'calendar_id'." 373 ) 374 375 return self.transport.perform_request( 376 "GET", 377 _make_path("_ml", "calendars", calendar_id, "events"), 378 params=params, 379 headers=headers, 380 ) 381 382 @query_params("from_", "size") 383 def get_calendars(self, body=None, calendar_id=None, params=None, headers=None): 384 """ 385 Retrieves configuration information for calendars. 386 387 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-get-calendar.html>`_ 388 389 :arg body: The from and size parameters optionally sent in the 390 body 391 :arg calendar_id: The ID of the calendar to fetch 392 :arg from_: skips a number of calendars 393 :arg size: specifies a max number of calendars to get 394 """ 395 if "from_" in params: 396 params["from"] = params.pop("from_") 397 398 return self.transport.perform_request( 399 "POST", 400 _make_path("_ml", "calendars", calendar_id), 401 params=params, 402 headers=headers, 403 body=body, 404 ) 405 406 @query_params("from_", "partition_field_value", "size") 407 def get_categories( 408 self, job_id, body=None, category_id=None, params=None, headers=None 409 ): 410 """ 411 Retrieves anomaly detection job results for one or more categories. 412 413 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-get-category.html>`_ 414 415 :arg job_id: The name of the job 416 :arg body: Category selection details if not provided in URI 417 :arg category_id: The identifier of the category definition of 418 interest 419 :arg from_: skips a number of categories 420 :arg partition_field_value: Specifies the partition to retrieve 421 categories for. This is optional, and should never be used for jobs 422 where per-partition categorization is disabled. 423 :arg size: specifies a max number of categories to get 424 """ 425 if "from_" in params: 426 params["from"] = params.pop("from_") 427 428 if job_id in SKIP_IN_PATH: 429 raise ValueError("Empty value passed for a required argument 'job_id'.") 430 431 return self.transport.perform_request( 432 "POST", 433 _make_path( 434 "_ml", "anomaly_detectors", job_id, "results", "categories", category_id 435 ), 436 params=params, 437 headers=headers, 438 body=body, 439 ) 440 441 @query_params("allow_no_datafeeds", "allow_no_match") 442 def get_datafeed_stats(self, datafeed_id=None, params=None, headers=None): 443 """ 444 Retrieves usage information for datafeeds. 445 446 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-get-datafeed-stats.html>`_ 447 448 :arg datafeed_id: The ID of the datafeeds stats to fetch 449 :arg allow_no_datafeeds: Whether to ignore if a wildcard 450 expression matches no datafeeds. (This includes `_all` string or when no 451 datafeeds have been specified) 452 :arg allow_no_match: Whether to ignore if a wildcard expression 453 matches no datafeeds. (This includes `_all` string or when no datafeeds 454 have been specified) 455 """ 456 return self.transport.perform_request( 457 "GET", 458 _make_path("_ml", "datafeeds", datafeed_id, "_stats"), 459 params=params, 460 headers=headers, 461 ) 462 463 @query_params("allow_no_datafeeds", "allow_no_match", "exclude_generated") 464 def get_datafeeds(self, datafeed_id=None, params=None, headers=None): 465 """ 466 Retrieves configuration information for datafeeds. 467 468 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-get-datafeed.html>`_ 469 470 :arg datafeed_id: The ID of the datafeeds to fetch 471 :arg allow_no_datafeeds: Whether to ignore if a wildcard 472 expression matches no datafeeds. (This includes `_all` string or when no 473 datafeeds have been specified) 474 :arg allow_no_match: Whether to ignore if a wildcard expression 475 matches no datafeeds. (This includes `_all` string or when no datafeeds 476 have been specified) 477 :arg exclude_generated: Omits fields that are illegal to set on 478 datafeed PUT 479 """ 480 return self.transport.perform_request( 481 "GET", 482 _make_path("_ml", "datafeeds", datafeed_id), 483 params=params, 484 headers=headers, 485 ) 486 487 @query_params("from_", "size") 488 def get_filters(self, filter_id=None, params=None, headers=None): 489 """ 490 Retrieves filters. 491 492 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-get-filter.html>`_ 493 494 :arg filter_id: The ID of the filter to fetch 495 :arg from_: skips a number of filters 496 :arg size: specifies a max number of filters to get 497 """ 498 if "from_" in params: 499 params["from"] = params.pop("from_") 500 501 return self.transport.perform_request( 502 "GET", 503 _make_path("_ml", "filters", filter_id), 504 params=params, 505 headers=headers, 506 ) 507 508 @query_params( 509 "desc", 510 "end", 511 "exclude_interim", 512 "from_", 513 "influencer_score", 514 "size", 515 "sort", 516 "start", 517 ) 518 def get_influencers(self, job_id, body=None, params=None, headers=None): 519 """ 520 Retrieves anomaly detection job results for one or more influencers. 521 522 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-get-influencer.html>`_ 523 524 :arg job_id: Identifier for the anomaly detection job 525 :arg body: Influencer selection criteria 526 :arg desc: whether the results should be sorted in decending 527 order 528 :arg end: end timestamp for the requested influencers 529 :arg exclude_interim: Exclude interim results 530 :arg from_: skips a number of influencers 531 :arg influencer_score: influencer score threshold for the 532 requested influencers 533 :arg size: specifies a max number of influencers to get 534 :arg sort: sort field for the requested influencers 535 :arg start: start timestamp for the requested influencers 536 """ 537 if "from_" in params: 538 params["from"] = params.pop("from_") 539 540 if job_id in SKIP_IN_PATH: 541 raise ValueError("Empty value passed for a required argument 'job_id'.") 542 543 return self.transport.perform_request( 544 "POST", 545 _make_path("_ml", "anomaly_detectors", job_id, "results", "influencers"), 546 params=params, 547 headers=headers, 548 body=body, 549 ) 550 551 @query_params("allow_no_jobs", "allow_no_match") 552 def get_job_stats(self, job_id=None, params=None, headers=None): 553 """ 554 Retrieves usage information for anomaly detection jobs. 555 556 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-get-job-stats.html>`_ 557 558 :arg job_id: The ID of the jobs stats to fetch 559 :arg allow_no_jobs: Whether to ignore if a wildcard expression 560 matches no jobs. (This includes `_all` string or when no jobs have been 561 specified) 562 :arg allow_no_match: Whether to ignore if a wildcard expression 563 matches no jobs. (This includes `_all` string or when no jobs have been 564 specified) 565 """ 566 return self.transport.perform_request( 567 "GET", 568 _make_path("_ml", "anomaly_detectors", job_id, "_stats"), 569 params=params, 570 headers=headers, 571 ) 572 573 @query_params("allow_no_jobs", "allow_no_match", "exclude_generated") 574 def get_jobs(self, job_id=None, params=None, headers=None): 575 """ 576 Retrieves configuration information for anomaly detection jobs. 577 578 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-get-job.html>`_ 579 580 :arg job_id: The ID of the jobs to fetch 581 :arg allow_no_jobs: Whether to ignore if a wildcard expression 582 matches no jobs. (This includes `_all` string or when no jobs have been 583 specified) 584 :arg allow_no_match: Whether to ignore if a wildcard expression 585 matches no jobs. (This includes `_all` string or when no jobs have been 586 specified) 587 :arg exclude_generated: Omits fields that are illegal to set on 588 job PUT 589 """ 590 return self.transport.perform_request( 591 "GET", 592 _make_path("_ml", "anomaly_detectors", job_id), 593 params=params, 594 headers=headers, 595 ) 596 597 @query_params("desc", "end", "from_", "size", "sort", "start") 598 def get_model_snapshots( 599 self, job_id, body=None, snapshot_id=None, params=None, headers=None 600 ): 601 """ 602 Retrieves information about model snapshots. 603 604 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-get-snapshot.html>`_ 605 606 :arg job_id: The ID of the job to fetch 607 :arg body: Model snapshot selection criteria 608 :arg snapshot_id: The ID of the snapshot to fetch 609 :arg desc: True if the results should be sorted in descending 610 order 611 :arg end: The filter 'end' query parameter 612 :arg from_: Skips a number of documents 613 :arg size: The default number of documents returned in queries 614 as a string. 615 :arg sort: Name of the field to sort on 616 :arg start: The filter 'start' query parameter 617 """ 618 if "from_" in params: 619 params["from"] = params.pop("from_") 620 621 if job_id in SKIP_IN_PATH: 622 raise ValueError("Empty value passed for a required argument 'job_id'.") 623 624 return self.transport.perform_request( 625 "POST", 626 _make_path( 627 "_ml", "anomaly_detectors", job_id, "model_snapshots", snapshot_id 628 ), 629 params=params, 630 headers=headers, 631 body=body, 632 ) 633 634 @query_params( 635 "allow_no_jobs", 636 "allow_no_match", 637 "bucket_span", 638 "end", 639 "exclude_interim", 640 "overall_score", 641 "start", 642 "top_n", 643 ) 644 def get_overall_buckets(self, job_id, body=None, params=None, headers=None): 645 """ 646 Retrieves overall bucket results that summarize the bucket results of multiple 647 anomaly detection jobs. 648 649 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-get-overall-buckets.html>`_ 650 651 :arg job_id: The job IDs for which to calculate overall bucket 652 results 653 :arg body: Overall bucket selection details if not provided in 654 URI 655 :arg allow_no_jobs: Whether to ignore if a wildcard expression 656 matches no jobs. (This includes `_all` string or when no jobs have been 657 specified) 658 :arg allow_no_match: Whether to ignore if a wildcard expression 659 matches no jobs. (This includes `_all` string or when no jobs have been 660 specified) 661 :arg bucket_span: The span of the overall buckets. Defaults to 662 the longest job bucket_span 663 :arg end: Returns overall buckets with timestamps earlier than 664 this time 665 :arg exclude_interim: If true overall buckets that include 666 interim buckets will be excluded 667 :arg overall_score: Returns overall buckets with overall scores 668 higher than this value 669 :arg start: Returns overall buckets with timestamps after this 670 time 671 :arg top_n: The number of top job bucket scores to be used in 672 the overall_score calculation 673 """ 674 if job_id in SKIP_IN_PATH: 675 raise ValueError("Empty value passed for a required argument 'job_id'.") 676 677 return self.transport.perform_request( 678 "POST", 679 _make_path( 680 "_ml", "anomaly_detectors", job_id, "results", "overall_buckets" 681 ), 682 params=params, 683 headers=headers, 684 body=body, 685 ) 686 687 @query_params( 688 "desc", 689 "end", 690 "exclude_interim", 691 "from_", 692 "record_score", 693 "size", 694 "sort", 695 "start", 696 ) 697 def get_records(self, job_id, body=None, params=None, headers=None): 698 """ 699 Retrieves anomaly records for an anomaly detection job. 700 701 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-get-record.html>`_ 702 703 :arg job_id: The ID of the job 704 :arg body: Record selection criteria 705 :arg desc: Set the sort direction 706 :arg end: End time filter for records 707 :arg exclude_interim: Exclude interim results 708 :arg from_: skips a number of records 709 :arg record_score: Returns records with anomaly scores greater 710 or equal than this value 711 :arg size: specifies a max number of records to get 712 :arg sort: Sort records by a particular field 713 :arg start: Start time filter for records 714 """ 715 if "from_" in params: 716 params["from"] = params.pop("from_") 717 718 if job_id in SKIP_IN_PATH: 719 raise ValueError("Empty value passed for a required argument 'job_id'.") 720 721 return self.transport.perform_request( 722 "POST", 723 _make_path("_ml", "anomaly_detectors", job_id, "results", "records"), 724 params=params, 725 headers=headers, 726 body=body, 727 ) 728 729 @query_params() 730 def info(self, params=None, headers=None): 731 """ 732 Returns defaults and limits used by machine learning. 733 734 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/get-ml-info.html>`_ 735 """ 736 return self.transport.perform_request( 737 "GET", "/_ml/info", params=params, headers=headers 738 ) 739 740 @query_params() 741 def open_job(self, job_id, params=None, headers=None): 742 """ 743 Opens one or more anomaly detection jobs. 744 745 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-open-job.html>`_ 746 747 :arg job_id: The ID of the job to open 748 """ 749 if job_id in SKIP_IN_PATH: 750 raise ValueError("Empty value passed for a required argument 'job_id'.") 751 752 return self.transport.perform_request( 753 "POST", 754 _make_path("_ml", "anomaly_detectors", job_id, "_open"), 755 params=params, 756 headers=headers, 757 ) 758 759 @query_params() 760 def post_calendar_events(self, calendar_id, body, params=None, headers=None): 761 """ 762 Posts scheduled events in a calendar. 763 764 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-post-calendar-event.html>`_ 765 766 :arg calendar_id: The ID of the calendar to modify 767 :arg body: A list of events 768 """ 769 for param in (calendar_id, body): 770 if param in SKIP_IN_PATH: 771 raise ValueError("Empty value passed for a required argument.") 772 773 return self.transport.perform_request( 774 "POST", 775 _make_path("_ml", "calendars", calendar_id, "events"), 776 params=params, 777 headers=headers, 778 body=body, 779 ) 780 781 @query_params("reset_end", "reset_start") 782 def post_data(self, job_id, body, params=None, headers=None): 783 """ 784 Sends data to an anomaly detection job for analysis. 785 786 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-post-data.html>`_ 787 788 :arg job_id: The name of the job receiving the data 789 :arg body: The data to process 790 :arg reset_end: Optional parameter to specify the end of the 791 bucket resetting range 792 :arg reset_start: Optional parameter to specify the start of the 793 bucket resetting range 794 """ 795 for param in (job_id, body): 796 if param in SKIP_IN_PATH: 797 raise ValueError("Empty value passed for a required argument.") 798 799 body = _bulk_body(self.transport.serializer, body) 800 return self.transport.perform_request( 801 "POST", 802 _make_path("_ml", "anomaly_detectors", job_id, "_data"), 803 params=params, 804 headers=headers, 805 body=body, 806 ) 807 808 @query_params() 809 def preview_datafeed(self, body=None, datafeed_id=None, params=None, headers=None): 810 """ 811 Previews a datafeed. 812 813 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-preview-datafeed.html>`_ 814 815 :arg body: The datafeed config and job config with which to 816 execute the preview 817 :arg datafeed_id: The ID of the datafeed to preview 818 """ 819 return self.transport.perform_request( 820 "POST", 821 _make_path("_ml", "datafeeds", datafeed_id, "_preview"), 822 params=params, 823 headers=headers, 824 body=body, 825 ) 826 827 @query_params() 828 def put_calendar(self, calendar_id, body=None, params=None, headers=None): 829 """ 830 Instantiates a calendar. 831 832 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-put-calendar.html>`_ 833 834 :arg calendar_id: The ID of the calendar to create 835 :arg body: The calendar details 836 """ 837 if calendar_id in SKIP_IN_PATH: 838 raise ValueError( 839 "Empty value passed for a required argument 'calendar_id'." 840 ) 841 842 return self.transport.perform_request( 843 "PUT", 844 _make_path("_ml", "calendars", calendar_id), 845 params=params, 846 headers=headers, 847 body=body, 848 ) 849 850 @query_params() 851 def put_calendar_job(self, calendar_id, job_id, params=None, headers=None): 852 """ 853 Adds an anomaly detection job to a calendar. 854 855 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-put-calendar-job.html>`_ 856 857 :arg calendar_id: The ID of the calendar to modify 858 :arg job_id: The ID of the job to add to the calendar 859 """ 860 for param in (calendar_id, job_id): 861 if param in SKIP_IN_PATH: 862 raise ValueError("Empty value passed for a required argument.") 863 864 return self.transport.perform_request( 865 "PUT", 866 _make_path("_ml", "calendars", calendar_id, "jobs", job_id), 867 params=params, 868 headers=headers, 869 ) 870 871 @query_params( 872 "allow_no_indices", "expand_wildcards", "ignore_throttled", "ignore_unavailable" 873 ) 874 def put_datafeed(self, datafeed_id, body, params=None, headers=None): 875 """ 876 Instantiates a datafeed. 877 878 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-put-datafeed.html>`_ 879 880 :arg datafeed_id: The ID of the datafeed to create 881 :arg body: The datafeed config 882 :arg allow_no_indices: Ignore if the source indices expressions 883 resolves to no concrete indices (default: true) 884 :arg expand_wildcards: Whether source index expressions should 885 get expanded to open or closed indices (default: open) Valid choices: 886 open, closed, hidden, none, all 887 :arg ignore_throttled: Ignore indices that are marked as 888 throttled (default: true) 889 :arg ignore_unavailable: Ignore unavailable indexes (default: 890 false) 891 """ 892 for param in (datafeed_id, body): 893 if param in SKIP_IN_PATH: 894 raise ValueError("Empty value passed for a required argument.") 895 896 return self.transport.perform_request( 897 "PUT", 898 _make_path("_ml", "datafeeds", datafeed_id), 899 params=params, 900 headers=headers, 901 body=body, 902 ) 903 904 @query_params() 905 def put_filter(self, filter_id, body, params=None, headers=None): 906 """ 907 Instantiates a filter. 908 909 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-put-filter.html>`_ 910 911 :arg filter_id: The ID of the filter to create 912 :arg body: The filter details 913 """ 914 for param in (filter_id, body): 915 if param in SKIP_IN_PATH: 916 raise ValueError("Empty value passed for a required argument.") 917 918 return self.transport.perform_request( 919 "PUT", 920 _make_path("_ml", "filters", filter_id), 921 params=params, 922 headers=headers, 923 body=body, 924 ) 925 926 @query_params( 927 "allow_no_indices", "expand_wildcards", "ignore_throttled", "ignore_unavailable" 928 ) 929 def put_job(self, job_id, body, params=None, headers=None): 930 """ 931 Instantiates an anomaly detection job. 932 933 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-put-job.html>`_ 934 935 :arg job_id: The ID of the job to create 936 :arg body: The job 937 :arg allow_no_indices: Ignore if the source indices expressions 938 resolves to no concrete indices (default: true). Only set if 939 datafeed_config is provided. 940 :arg expand_wildcards: Whether source index expressions should 941 get expanded to open or closed indices (default: open). Only set if 942 datafeed_config is provided. Valid choices: open, closed, hidden, none, 943 all 944 :arg ignore_throttled: Ignore indices that are marked as 945 throttled (default: true). Only set if datafeed_config is provided. 946 :arg ignore_unavailable: Ignore unavailable indexes (default: 947 false). Only set if datafeed_config is provided. 948 """ 949 for param in (job_id, body): 950 if param in SKIP_IN_PATH: 951 raise ValueError("Empty value passed for a required argument.") 952 953 return self.transport.perform_request( 954 "PUT", 955 _make_path("_ml", "anomaly_detectors", job_id), 956 params=params, 957 headers=headers, 958 body=body, 959 ) 960 961 @query_params("delete_intervening_results") 962 def revert_model_snapshot( 963 self, job_id, snapshot_id, body=None, params=None, headers=None 964 ): 965 """ 966 Reverts to a specific snapshot. 967 968 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-revert-snapshot.html>`_ 969 970 :arg job_id: The ID of the job to fetch 971 :arg snapshot_id: The ID of the snapshot to revert to 972 :arg body: Reversion options 973 :arg delete_intervening_results: Should we reset the results 974 back to the time of the snapshot? 975 """ 976 for param in (job_id, snapshot_id): 977 if param in SKIP_IN_PATH: 978 raise ValueError("Empty value passed for a required argument.") 979 980 return self.transport.perform_request( 981 "POST", 982 _make_path( 983 "_ml", 984 "anomaly_detectors", 985 job_id, 986 "model_snapshots", 987 snapshot_id, 988 "_revert", 989 ), 990 params=params, 991 headers=headers, 992 body=body, 993 ) 994 995 @query_params("enabled", "timeout") 996 def set_upgrade_mode(self, params=None, headers=None): 997 """ 998 Sets a cluster wide upgrade_mode setting that prepares machine learning indices 999 for an upgrade. 1000 1001 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-set-upgrade-mode.html>`_ 1002 1003 :arg enabled: Whether to enable upgrade_mode ML setting or not. 1004 Defaults to false. 1005 :arg timeout: Controls the time to wait before action times out. 1006 Defaults to 30 seconds 1007 """ 1008 return self.transport.perform_request( 1009 "POST", "/_ml/set_upgrade_mode", params=params, headers=headers 1010 ) 1011 1012 @query_params("end", "start", "timeout") 1013 def start_datafeed(self, datafeed_id, body=None, params=None, headers=None): 1014 """ 1015 Starts one or more datafeeds. 1016 1017 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-start-datafeed.html>`_ 1018 1019 :arg datafeed_id: The ID of the datafeed to start 1020 :arg body: The start datafeed parameters 1021 :arg end: The end time when the datafeed should stop. When not 1022 set, the datafeed continues in real time 1023 :arg start: The start time from where the datafeed should begin 1024 :arg timeout: Controls the time to wait until a datafeed has 1025 started. Default to 20 seconds 1026 """ 1027 if datafeed_id in SKIP_IN_PATH: 1028 raise ValueError( 1029 "Empty value passed for a required argument 'datafeed_id'." 1030 ) 1031 1032 return self.transport.perform_request( 1033 "POST", 1034 _make_path("_ml", "datafeeds", datafeed_id, "_start"), 1035 params=params, 1036 headers=headers, 1037 body=body, 1038 ) 1039 1040 @query_params("allow_no_datafeeds", "allow_no_match", "force", "timeout") 1041 def stop_datafeed(self, datafeed_id, body=None, params=None, headers=None): 1042 """ 1043 Stops one or more datafeeds. 1044 1045 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-stop-datafeed.html>`_ 1046 1047 :arg datafeed_id: The ID of the datafeed to stop 1048 :arg body: The URL params optionally sent in the body 1049 :arg allow_no_datafeeds: Whether to ignore if a wildcard 1050 expression matches no datafeeds. (This includes `_all` string or when no 1051 datafeeds have been specified) 1052 :arg allow_no_match: Whether to ignore if a wildcard expression 1053 matches no datafeeds. (This includes `_all` string or when no datafeeds 1054 have been specified) 1055 :arg force: True if the datafeed should be forcefully stopped. 1056 :arg timeout: Controls the time to wait until a datafeed has 1057 stopped. Default to 20 seconds 1058 """ 1059 if datafeed_id in SKIP_IN_PATH: 1060 raise ValueError( 1061 "Empty value passed for a required argument 'datafeed_id'." 1062 ) 1063 1064 return self.transport.perform_request( 1065 "POST", 1066 _make_path("_ml", "datafeeds", datafeed_id, "_stop"), 1067 params=params, 1068 headers=headers, 1069 body=body, 1070 ) 1071 1072 @query_params( 1073 "allow_no_indices", "expand_wildcards", "ignore_throttled", "ignore_unavailable" 1074 ) 1075 def update_datafeed(self, datafeed_id, body, params=None, headers=None): 1076 """ 1077 Updates certain properties of a datafeed. 1078 1079 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-update-datafeed.html>`_ 1080 1081 :arg datafeed_id: The ID of the datafeed to update 1082 :arg body: The datafeed update settings 1083 :arg allow_no_indices: Ignore if the source indices expressions 1084 resolves to no concrete indices (default: true) 1085 :arg expand_wildcards: Whether source index expressions should 1086 get expanded to open or closed indices (default: open) Valid choices: 1087 open, closed, hidden, none, all 1088 :arg ignore_throttled: Ignore indices that are marked as 1089 throttled (default: true) 1090 :arg ignore_unavailable: Ignore unavailable indexes (default: 1091 false) 1092 """ 1093 for param in (datafeed_id, body): 1094 if param in SKIP_IN_PATH: 1095 raise ValueError("Empty value passed for a required argument.") 1096 1097 return self.transport.perform_request( 1098 "POST", 1099 _make_path("_ml", "datafeeds", datafeed_id, "_update"), 1100 params=params, 1101 headers=headers, 1102 body=body, 1103 ) 1104 1105 @query_params() 1106 def update_filter(self, filter_id, body, params=None, headers=None): 1107 """ 1108 Updates the description of a filter, adds items, or removes items. 1109 1110 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-update-filter.html>`_ 1111 1112 :arg filter_id: The ID of the filter to update 1113 :arg body: The filter update 1114 """ 1115 for param in (filter_id, body): 1116 if param in SKIP_IN_PATH: 1117 raise ValueError("Empty value passed for a required argument.") 1118 1119 return self.transport.perform_request( 1120 "POST", 1121 _make_path("_ml", "filters", filter_id, "_update"), 1122 params=params, 1123 headers=headers, 1124 body=body, 1125 ) 1126 1127 @query_params() 1128 def update_job(self, job_id, body, params=None, headers=None): 1129 """ 1130 Updates certain properties of an anomaly detection job. 1131 1132 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-update-job.html>`_ 1133 1134 :arg job_id: The ID of the job to create 1135 :arg body: The job update settings 1136 """ 1137 for param in (job_id, body): 1138 if param in SKIP_IN_PATH: 1139 raise ValueError("Empty value passed for a required argument.") 1140 1141 return self.transport.perform_request( 1142 "POST", 1143 _make_path("_ml", "anomaly_detectors", job_id, "_update"), 1144 params=params, 1145 headers=headers, 1146 body=body, 1147 ) 1148 1149 @query_params() 1150 def update_model_snapshot( 1151 self, job_id, snapshot_id, body, params=None, headers=None 1152 ): 1153 """ 1154 Updates certain properties of a snapshot. 1155 1156 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-update-snapshot.html>`_ 1157 1158 :arg job_id: The ID of the job to fetch 1159 :arg snapshot_id: The ID of the snapshot to update 1160 :arg body: The model snapshot properties to update 1161 """ 1162 for param in (job_id, snapshot_id, body): 1163 if param in SKIP_IN_PATH: 1164 raise ValueError("Empty value passed for a required argument.") 1165 1166 return self.transport.perform_request( 1167 "POST", 1168 _make_path( 1169 "_ml", 1170 "anomaly_detectors", 1171 job_id, 1172 "model_snapshots", 1173 snapshot_id, 1174 "_update", 1175 ), 1176 params=params, 1177 headers=headers, 1178 body=body, 1179 ) 1180 1181 @query_params() 1182 def validate(self, body, params=None, headers=None): 1183 """ 1184 Validates an anomaly detection job. 1185 1186 `<https://www.elastic.co/guide/en/machine-learning/current/ml-jobs.html>`_ 1187 1188 :arg body: The job config 1189 """ 1190 if body in SKIP_IN_PATH: 1191 raise ValueError("Empty value passed for a required argument 'body'.") 1192 1193 return self.transport.perform_request( 1194 "POST", 1195 "/_ml/anomaly_detectors/_validate", 1196 params=params, 1197 headers=headers, 1198 body=body, 1199 ) 1200 1201 @query_params() 1202 def validate_detector(self, body, params=None, headers=None): 1203 """ 1204 Validates an anomaly detection detector. 1205 1206 `<https://www.elastic.co/guide/en/machine-learning/current/ml-jobs.html>`_ 1207 1208 :arg body: The detector 1209 """ 1210 if body in SKIP_IN_PATH: 1211 raise ValueError("Empty value passed for a required argument 'body'.") 1212 1213 return self.transport.perform_request( 1214 "POST", 1215 "/_ml/anomaly_detectors/_validate/detector", 1216 params=params, 1217 headers=headers, 1218 body=body, 1219 ) 1220 1221 @query_params("force", "timeout") 1222 def delete_data_frame_analytics(self, id, params=None, headers=None): 1223 """ 1224 Deletes an existing data frame analytics job. 1225 1226 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/delete-dfanalytics.html>`_ 1227 1228 :arg id: The ID of the data frame analytics to delete 1229 :arg force: True if the job should be forcefully deleted 1230 :arg timeout: Controls the time to wait until a job is deleted. 1231 Defaults to 1 minute 1232 """ 1233 if id in SKIP_IN_PATH: 1234 raise ValueError("Empty value passed for a required argument 'id'.") 1235 1236 return self.transport.perform_request( 1237 "DELETE", 1238 _make_path("_ml", "data_frame", "analytics", id), 1239 params=params, 1240 headers=headers, 1241 ) 1242 1243 @query_params() 1244 def evaluate_data_frame(self, body, params=None, headers=None): 1245 """ 1246 Evaluates the data frame analytics for an annotated index. 1247 1248 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/evaluate-dfanalytics.html>`_ 1249 1250 :arg body: The evaluation definition 1251 """ 1252 if body in SKIP_IN_PATH: 1253 raise ValueError("Empty value passed for a required argument 'body'.") 1254 1255 return self.transport.perform_request( 1256 "POST", 1257 "/_ml/data_frame/_evaluate", 1258 params=params, 1259 headers=headers, 1260 body=body, 1261 ) 1262 1263 @query_params("allow_no_match", "exclude_generated", "from_", "size") 1264 def get_data_frame_analytics(self, id=None, params=None, headers=None): 1265 """ 1266 Retrieves configuration information for data frame analytics jobs. 1267 1268 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/get-dfanalytics.html>`_ 1269 1270 :arg id: The ID of the data frame analytics to fetch 1271 :arg allow_no_match: Whether to ignore if a wildcard expression 1272 matches no data frame analytics. (This includes `_all` string or when no 1273 data frame analytics have been specified) Default: True 1274 :arg exclude_generated: Omits fields that are illegal to set on 1275 data frame analytics PUT 1276 :arg from_: skips a number of analytics 1277 :arg size: specifies a max number of analytics to get Default: 1278 100 1279 """ 1280 if "from_" in params: 1281 params["from"] = params.pop("from_") 1282 1283 return self.transport.perform_request( 1284 "GET", 1285 _make_path("_ml", "data_frame", "analytics", id), 1286 params=params, 1287 headers=headers, 1288 ) 1289 1290 @query_params("allow_no_match", "from_", "size", "verbose") 1291 def get_data_frame_analytics_stats(self, id=None, params=None, headers=None): 1292 """ 1293 Retrieves usage information for data frame analytics jobs. 1294 1295 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/get-dfanalytics-stats.html>`_ 1296 1297 :arg id: The ID of the data frame analytics stats to fetch 1298 :arg allow_no_match: Whether to ignore if a wildcard expression 1299 matches no data frame analytics. (This includes `_all` string or when no 1300 data frame analytics have been specified) Default: True 1301 :arg from_: skips a number of analytics 1302 :arg size: specifies a max number of analytics to get Default: 1303 100 1304 :arg verbose: whether the stats response should be verbose 1305 """ 1306 if "from_" in params: 1307 params["from"] = params.pop("from_") 1308 1309 return self.transport.perform_request( 1310 "GET", 1311 _make_path("_ml", "data_frame", "analytics", id, "_stats"), 1312 params=params, 1313 headers=headers, 1314 ) 1315 1316 @query_params() 1317 def put_data_frame_analytics(self, id, body, params=None, headers=None): 1318 """ 1319 Instantiates a data frame analytics job. 1320 1321 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/put-dfanalytics.html>`_ 1322 1323 :arg id: The ID of the data frame analytics to create 1324 :arg body: The data frame analytics configuration 1325 """ 1326 for param in (id, body): 1327 if param in SKIP_IN_PATH: 1328 raise ValueError("Empty value passed for a required argument.") 1329 1330 return self.transport.perform_request( 1331 "PUT", 1332 _make_path("_ml", "data_frame", "analytics", id), 1333 params=params, 1334 headers=headers, 1335 body=body, 1336 ) 1337 1338 @query_params("timeout") 1339 def start_data_frame_analytics(self, id, body=None, params=None, headers=None): 1340 """ 1341 Starts a data frame analytics job. 1342 1343 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/start-dfanalytics.html>`_ 1344 1345 :arg id: The ID of the data frame analytics to start 1346 :arg body: The start data frame analytics parameters 1347 :arg timeout: Controls the time to wait until the task has 1348 started. Defaults to 20 seconds 1349 """ 1350 if id in SKIP_IN_PATH: 1351 raise ValueError("Empty value passed for a required argument 'id'.") 1352 1353 return self.transport.perform_request( 1354 "POST", 1355 _make_path("_ml", "data_frame", "analytics", id, "_start"), 1356 params=params, 1357 headers=headers, 1358 body=body, 1359 ) 1360 1361 @query_params("allow_no_match", "force", "timeout") 1362 def stop_data_frame_analytics(self, id, body=None, params=None, headers=None): 1363 """ 1364 Stops one or more data frame analytics jobs. 1365 1366 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/stop-dfanalytics.html>`_ 1367 1368 :arg id: The ID of the data frame analytics to stop 1369 :arg body: The stop data frame analytics parameters 1370 :arg allow_no_match: Whether to ignore if a wildcard expression 1371 matches no data frame analytics. (This includes `_all` string or when no 1372 data frame analytics have been specified) 1373 :arg force: True if the data frame analytics should be 1374 forcefully stopped 1375 :arg timeout: Controls the time to wait until the task has 1376 stopped. Defaults to 20 seconds 1377 """ 1378 if id in SKIP_IN_PATH: 1379 raise ValueError("Empty value passed for a required argument 'id'.") 1380 1381 return self.transport.perform_request( 1382 "POST", 1383 _make_path("_ml", "data_frame", "analytics", id, "_stop"), 1384 params=params, 1385 headers=headers, 1386 body=body, 1387 ) 1388 1389 @query_params() 1390 def delete_trained_model(self, model_id, params=None, headers=None): 1391 """ 1392 Deletes an existing trained inference model that is currently not referenced by 1393 an ingest pipeline. 1394 1395 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/delete-trained-models.html>`_ 1396 1397 :arg model_id: The ID of the trained model to delete 1398 """ 1399 if model_id in SKIP_IN_PATH: 1400 raise ValueError("Empty value passed for a required argument 'model_id'.") 1401 1402 return self.transport.perform_request( 1403 "DELETE", 1404 _make_path("_ml", "trained_models", model_id), 1405 params=params, 1406 headers=headers, 1407 ) 1408 1409 @query_params() 1410 def explain_data_frame_analytics( 1411 self, body=None, id=None, params=None, headers=None 1412 ): 1413 """ 1414 Explains a data frame analytics config. 1415 1416 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/explain-dfanalytics.html>`_ 1417 1418 :arg body: The data frame analytics config to explain 1419 :arg id: The ID of the data frame analytics to explain 1420 """ 1421 return self.transport.perform_request( 1422 "POST", 1423 _make_path("_ml", "data_frame", "analytics", id, "_explain"), 1424 params=params, 1425 headers=headers, 1426 body=body, 1427 ) 1428 1429 @query_params( 1430 "allow_no_match", 1431 "decompress_definition", 1432 "exclude_generated", 1433 "from_", 1434 "include", 1435 "include_model_definition", 1436 "size", 1437 "tags", 1438 ) 1439 def get_trained_models(self, model_id=None, params=None, headers=None): 1440 """ 1441 Retrieves configuration information for a trained inference model. 1442 1443 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/get-trained-models.html>`_ 1444 1445 :arg model_id: The ID of the trained models to fetch 1446 :arg allow_no_match: Whether to ignore if a wildcard expression 1447 matches no trained models. (This includes `_all` string or when no 1448 trained models have been specified) Default: True 1449 :arg decompress_definition: Should the model definition be 1450 decompressed into valid JSON or returned in a custom compressed format. 1451 Defaults to true. Default: True 1452 :arg exclude_generated: Omits fields that are illegal to set on 1453 model PUT 1454 :arg from_: skips a number of trained models 1455 :arg include: A comma-separate list of fields to optionally 1456 include. Valid options are 'definition' and 'total_feature_importance'. 1457 Default is none. 1458 :arg include_model_definition: Should the full model definition 1459 be included in the results. These definitions can be large. So be 1460 cautious when including them. Defaults to false. 1461 :arg size: specifies a max number of trained models to get 1462 Default: 100 1463 :arg tags: A comma-separated list of tags that the model must 1464 have. 1465 """ 1466 if "from_" in params: 1467 params["from"] = params.pop("from_") 1468 1469 return self.transport.perform_request( 1470 "GET", 1471 _make_path("_ml", "trained_models", model_id), 1472 params=params, 1473 headers=headers, 1474 ) 1475 1476 @query_params("allow_no_match", "from_", "size") 1477 def get_trained_models_stats(self, model_id=None, params=None, headers=None): 1478 """ 1479 Retrieves usage information for trained inference models. 1480 1481 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/get-trained-models-stats.html>`_ 1482 1483 :arg model_id: The ID of the trained models stats to fetch 1484 :arg allow_no_match: Whether to ignore if a wildcard expression 1485 matches no trained models. (This includes `_all` string or when no 1486 trained models have been specified) Default: True 1487 :arg from_: skips a number of trained models 1488 :arg size: specifies a max number of trained models to get 1489 Default: 100 1490 """ 1491 if "from_" in params: 1492 params["from"] = params.pop("from_") 1493 1494 return self.transport.perform_request( 1495 "GET", 1496 _make_path("_ml", "trained_models", model_id, "_stats"), 1497 params=params, 1498 headers=headers, 1499 ) 1500 1501 @query_params() 1502 def put_trained_model(self, model_id, body, params=None, headers=None): 1503 """ 1504 Creates an inference trained model. 1505 1506 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/put-trained-models.html>`_ 1507 1508 :arg model_id: The ID of the trained models to store 1509 :arg body: The trained model configuration 1510 """ 1511 for param in (model_id, body): 1512 if param in SKIP_IN_PATH: 1513 raise ValueError("Empty value passed for a required argument.") 1514 1515 return self.transport.perform_request( 1516 "PUT", 1517 _make_path("_ml", "trained_models", model_id), 1518 params=params, 1519 headers=headers, 1520 body=body, 1521 ) 1522 1523 @query_params() 1524 def estimate_model_memory(self, body, params=None, headers=None): 1525 """ 1526 Estimates the model memory 1527 1528 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-apis.html>`_ 1529 1530 :arg body: The analysis config, plus cardinality estimates for 1531 fields it references 1532 """ 1533 if body in SKIP_IN_PATH: 1534 raise ValueError("Empty value passed for a required argument 'body'.") 1535 1536 return self.transport.perform_request( 1537 "POST", 1538 "/_ml/anomaly_detectors/_estimate_model_memory", 1539 params=params, 1540 headers=headers, 1541 body=body, 1542 ) 1543 1544 @query_params() 1545 def update_data_frame_analytics(self, id, body, params=None, headers=None): 1546 """ 1547 Updates certain properties of a data frame analytics job. 1548 1549 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/update-dfanalytics.html>`_ 1550 1551 :arg id: The ID of the data frame analytics to update 1552 :arg body: The data frame analytics settings to update 1553 """ 1554 for param in (id, body): 1555 if param in SKIP_IN_PATH: 1556 raise ValueError("Empty value passed for a required argument.") 1557 1558 return self.transport.perform_request( 1559 "POST", 1560 _make_path("_ml", "data_frame", "analytics", id, "_update"), 1561 params=params, 1562 headers=headers, 1563 body=body, 1564 ) 1565 1566 @query_params("timeout", "wait_for_completion") 1567 def upgrade_job_snapshot(self, job_id, snapshot_id, params=None, headers=None): 1568 """ 1569 Upgrades a given job snapshot to the current major version. 1570 1571 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-upgrade-job-model-snapshot.html>`_ 1572 1573 :arg job_id: The ID of the job 1574 :arg snapshot_id: The ID of the snapshot 1575 :arg timeout: How long should the API wait for the job to be 1576 opened and the old snapshot to be loaded. 1577 :arg wait_for_completion: Should the request wait until the task 1578 is complete before responding to the caller. Default is false. 1579 """ 1580 for param in (job_id, snapshot_id): 1581 if param in SKIP_IN_PATH: 1582 raise ValueError("Empty value passed for a required argument.") 1583 1584 return self.transport.perform_request( 1585 "POST", 1586 _make_path( 1587 "_ml", 1588 "anomaly_detectors", 1589 job_id, 1590 "model_snapshots", 1591 snapshot_id, 1592 "_upgrade", 1593 ), 1594 params=params, 1595 headers=headers, 1596 ) 1597 1598 @query_params() 1599 def delete_trained_model_alias( 1600 self, model_id, model_alias, params=None, headers=None 1601 ): 1602 """ 1603 Deletes a model alias that refers to the trained model 1604 1605 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/delete-trained-models-aliases.html>`_ 1606 1607 :arg model_id: The trained model where the model alias is 1608 assigned 1609 :arg model_alias: The trained model alias to delete 1610 """ 1611 for param in (model_id, model_alias): 1612 if param in SKIP_IN_PATH: 1613 raise ValueError("Empty value passed for a required argument.") 1614 1615 return self.transport.perform_request( 1616 "DELETE", 1617 _make_path("_ml", "trained_models", model_id, "model_aliases", model_alias), 1618 params=params, 1619 headers=headers, 1620 ) 1621 1622 @query_params() 1623 def preview_data_frame_analytics( 1624 self, body=None, id=None, params=None, headers=None 1625 ): 1626 """ 1627 Previews that will be analyzed given a data frame analytics config. 1628 1629 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/preview-dfanalytics.html>`_ 1630 1631 :arg body: The data frame analytics config to preview 1632 :arg id: The ID of the data frame analytics to preview 1633 """ 1634 return self.transport.perform_request( 1635 "POST", 1636 _make_path("_ml", "data_frame", "analytics", id, "_preview"), 1637 params=params, 1638 headers=headers, 1639 body=body, 1640 ) 1641 1642 @query_params("reassign") 1643 def put_trained_model_alias(self, model_id, model_alias, params=None, headers=None): 1644 """ 1645 Creates a new model alias (or reassigns an existing one) to refer to the 1646 trained model 1647 1648 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/put-trained-models-aliases.html>`_ 1649 1650 :arg model_id: The trained model where the model alias should be 1651 assigned 1652 :arg model_alias: The trained model alias to update 1653 :arg reassign: If the model_alias already exists and points to a 1654 separate model_id, this parameter must be true. Defaults to false. 1655 """ 1656 for param in (model_id, model_alias): 1657 if param in SKIP_IN_PATH: 1658 raise ValueError("Empty value passed for a required argument.") 1659 1660 return self.transport.perform_request( 1661 "PUT", 1662 _make_path("_ml", "trained_models", model_id, "model_aliases", model_alias), 1663 params=params, 1664 headers=headers, 1665 ) 1666 1667 @query_params( 1668 "charset", 1669 "column_names", 1670 "delimiter", 1671 "explain", 1672 "format", 1673 "grok_pattern", 1674 "has_header_row", 1675 "line_merge_size_limit", 1676 "lines_to_sample", 1677 "quote", 1678 "should_trim_fields", 1679 "timeout", 1680 "timestamp_field", 1681 "timestamp_format", 1682 ) 1683 def find_file_structure(self, body, params=None, headers=None): 1684 """ 1685 Finds the structure of a text file. The text file must contain data that is 1686 suitable to be ingested into Elasticsearch. 1687 1688 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/find-structure.html>`_ 1689 1690 .. warning:: 1691 1692 This API is **experimental** so may include breaking changes 1693 or be removed in a future version 1694 1695 :arg body: The contents of the file to be analyzed 1696 :arg charset: Optional parameter to specify the character set of 1697 the file 1698 :arg column_names: Optional parameter containing a comma 1699 separated list of the column names for a delimited file 1700 :arg delimiter: Optional parameter to specify the delimiter 1701 character for a delimited file - must be a single character 1702 :arg explain: Whether to include a commentary on how the 1703 structure was derived 1704 :arg format: Optional parameter to specify the high level file 1705 format Valid choices: ndjson, xml, delimited, semi_structured_text 1706 :arg grok_pattern: Optional parameter to specify the Grok 1707 pattern that should be used to extract fields from messages in a semi- 1708 structured text file 1709 :arg has_header_row: Optional parameter to specify whether a 1710 delimited file includes the column names in its first row 1711 :arg line_merge_size_limit: Maximum number of characters 1712 permitted in a single message when lines are merged to create messages. 1713 Default: 10000 1714 :arg lines_to_sample: How many lines of the file should be 1715 included in the analysis Default: 1000 1716 :arg quote: Optional parameter to specify the quote character 1717 for a delimited file - must be a single character 1718 :arg should_trim_fields: Optional parameter to specify whether 1719 the values between delimiters in a delimited file should have whitespace 1720 trimmed from them 1721 :arg timeout: Timeout after which the analysis will be aborted 1722 Default: 25s 1723 :arg timestamp_field: Optional parameter to specify the 1724 timestamp field in the file 1725 :arg timestamp_format: Optional parameter to specify the 1726 timestamp format in the file - may be either a Joda or Java time format 1727 """ 1728 if body in SKIP_IN_PATH: 1729 raise ValueError("Empty value passed for a required argument 'body'.") 1730 1731 body = _bulk_body(self.transport.serializer, body) 1732 return self.transport.perform_request( 1733 "POST", 1734 "/_ml/find_file_structure", 1735 params=params, 1736 headers=headers, 1737 body=body, 1738 ) 1739 1740 @query_params("wait_for_completion") 1741 def reset_job(self, job_id, params=None, headers=None): 1742 """ 1743 Resets an existing anomaly detection job. 1744 1745 `<https://www.elastic.co/guide/en/elasticsearch/reference/7.15/ml-reset-job.html>`_ 1746 1747 :arg job_id: The ID of the job to reset 1748 :arg wait_for_completion: Should this request wait until the 1749 operation has completed before returning Default: True 1750 """ 1751 if job_id in SKIP_IN_PATH: 1752 raise ValueError("Empty value passed for a required argument 'job_id'.") 1753 1754 return self.transport.perform_request( 1755 "POST", 1756 _make_path("_ml", "anomaly_detectors", job_id, "_reset"), 1757 params=params, 1758 headers=headers, 1759 ) 1760