Merge pull request #248840 from SturgeonMi/SturgeonMi-patch-mltable

Update mltable save api

Author: prmerger-automator[bot]

articles/machine-learning/how-to-mltable.md

@@ -203,20 +203,29 @@ You can optionally choose to load the MLTable object into Pandas, using:
 ```
 
 #### Save the data loading steps
-Next, save all your data loading steps into an MLTable file. If you save your data loading steps, you can reproduce your Pandas data frame at a later point in time, and you don't need to redefine the data loading steps in your code.
+Next, save all your data loading steps into an MLTable file. Saving your data loading steps in an MLTable file allows you to reproduce your Pandas data frame at a later point in time, without need to redefine the code each time.
 
+You can choose to save the MLTable yaml file to a cloud storage, or you can also save it to local paths.
 ```python
-# serialize the data loading steps into an MLTable file
-tbl.save("./nyc_taxi")
+# save the data loading steps in an MLTable file to a cloud storage
+# NOTE: the tbl object was defined in the previous snippet.
+tbl.save(save_path_dirc= "azureml://subscriptions/<subid>/resourcegroups/<rgname>/workspaces/<wsname>/datastores/<name>/paths/titanic", collocated=True, show_progress=True, allow_copy_errors=False, overwrite=True)
 ```
 
-You can optionally view the contents of the MLTable file, to understand how the data loading steps are serialized into a file:
-
 ```python
-with open("./nyc_taxi/MLTable", "r") as f:
-    print(f.read())
+# save the data loading steps in an MLTable file to local
+# NOTE: the tbl object was defined in the previous snippet.
+tbl.save("./titanic")
 ```
 
+> [!IMPORTANT]
+> - If collocated == True, then we will copy the data to the same folder with MLTable yaml file if they are not currently collocated, and we will use relative paths in MLTable yaml.
+> - If collocated == False, we will not move the data and we will use absolute paths for cloud data and use relative paths for local data.
+> - We don’t support this parameter combination: data is in local, collocated == False, `save_path_dirc` is a cloud directory. Please upload your local data to cloud and use the cloud data paths for MLTable instead.
+> - Parameters `show_progress` (default as True), `allow_copy_errors` (default as False), `overwrite`(default as True) are optional.
+>
+
+
 ### Reproduce data loading steps
 Now that the data loading steps have been serialized into a file, you can reproduce them at any point in time, with the load() method. This way, you don't need to redefine your data loading steps in code, and you can more easily share the file.