Finishing with experiments endpoints (searchexperiments not complete)

Author: pebeto

src/MLFlowClient.jl

@@ -1,15 +1,3 @@
-"""
-    MLFlowClient
-
-[MLFlowClient](https://github.com/JuliaAI.jl) is a [Julia](https://julialang.org/) package for working with [MLFlow](https://mlflow.org/) using the REST [API v2.0](https://www.mlflow.org/docs/latest/rest-api.html).
-
-`MLFlowClient` allows you to create and manage `MLFlow` experiments, runs, and log metrics and artifacts. If you are not familiar with `MLFlow` and its concepts, please refer to [MLFlow documentation](https://mlflow.org/docs/latest/index.html).
-
-# Limitations
-
-- no authentication support.
-- when storing artifacts, the assumption is that MLFlow and this library run on the same server. Artifacts are stored using plain filesystem operations. Therefore, `/mlruns` or the specified `artifact_location` must be accessible to both the MLFlow server (read), and this library (write).
-"""
 module MLFlowClient
 
 using Dates
@@ -21,18 +9,55 @@ using ShowCases
 using FilePathsBase: AbstractPath
 
 include("types/tag.jl")
+export Tag
+
 include("types/enums.jl")
+export
+    ViewType,
+    RunStatus,
+    ModelVersionStatus
+
 include("types/dataset.jl")
+export
+    Dataset,
+    DatasetInput
+
 include("types/artifact.jl")
+export FileInfo
+
 include("types/model_version.jl")
+export ModelVersion
+
 include("types/registered_model.jl")
+export
+    RegisteredModel,
+    RegisteredModelAlias
+
 include("types/experiment.jl")
+export Experiment
+
 include("types/run.jl")
+export
+    Run,
+    Param,
+    Metric,
+    RunData,
+    RunInfo,
+    RunInputs
+
 include("types/mlflow.jl")
+export MLFlow
 
 include("utils.jl")
 include("api.jl")
 
 include("services/experiment.jl")
-
+export
+    getexperiment,
+    createexperiment,
+    deleteexperiment,
+    updateexperiment,
+    restoreexperiment,
+    searchexperiments,
+    getexperimentbyname
 end

src/api.jl

@@ -1,11 +1,38 @@
+"""
+    uri(mlf::MLFlow, endpoint::String; parameters=missing)
+
+Retrieves an URI based on `mlf`, `endpoint`, and, optionally, `parameters`.
+
+# Examples
+```@example
+MLFlowClient.uri(mlf, "experiments/get", Dict(:experiment_id=>10))
+```
+"""
+uri(mlf::MLFlow, endpoint::String;
+    parameters::Dict{Symbol, <:Any}=Dict{Symbol, IntOrString}()) =
+    URI("$(mlf.apiroot)/$(mlf.apiversion)/mlflow/$(endpoint)";
+        query=parameters)
+
+"""
+    headers(mlf::MLFlow,custom_headers::AbstractDict)
+
+Retrieves HTTP headers based on `mlf` and merges with user-provided `custom_headers`
+
+# Examples
+```@example
+headers(mlf,Dict("Content-Type"=>"application/json"))
+```
+"""
+headers(mlf::MLFlow, custom_headers::AbstractDict) = merge(mlf.headers, custom_headers)
+
 """
     mlfget(mlf, endpoint; kwargs...)
 
 Performs a HTTP GET to a specified endpoint. kwargs are turned into GET params.
 """
 function mlfget(mlf, endpoint; kwargs...)
-    apiuri = uri(mlf, endpoint, kwargs)
-    apiheaders = headers(mlf, Dict("Content-Type" => "application/json"))
+    apiuri = uri(mlf, endpoint; parameters=kwargs |> Dict)
+    apiheaders = headers(mlf, ("Content-Type" => "application/json") |> Dict)
 
     try
         response = HTTP.get(apiuri, apiheaders)
@@ -21,7 +48,7 @@ end
 Performs a HTTP POST to the specified endpoint. kwargs are converted to JSON and become the POST body.
 """
 function mlfpost(mlf, endpoint; kwargs...)
-    apiuri = uri(mlf, endpoint)
+    apiuri = uri(mlf, endpoint;)
     apiheaders = headers(mlf, Dict("Content-Type" => "application/json"))
     body = JSON.json(kwargs)
 
@@ -31,4 +58,4 @@ function mlfpost(mlf, endpoint; kwargs...)
     catch e
         throw(e)
     end
-end
+end

src/services/experiment.jl

@@ -1,57 +1,50 @@
 """
-    createexperiment(instance::MLFlow; name=missing, artifact_location=missing,
-        tags=[])
+    createexperiment(instance::MLFlow; name::String="",
+        artifact_location::String="",
+        tags::Union{Dict{<:Any}, Array{<:Any}}=[])
 
 Create an experiment with a name. Returns the newly created experiment.
 Validates that another experiment with the same name does not already exist and
 fails if another experiment with the same name already exists.
 
 # Arguments
 - `instance`: [`MLFlow`](@ref) configuration.
-- `name::String`: Experiment name. This field is required.
-- `artifact_location::String`: Location where all artifacts for the experiment
+- `name`: Experiment name. This field is required.
+- `artifact_location`: Location where all artifacts for the experiment
 are stored. If not provided, the remote server will select an appropriate
 default.
 - `tags`: A collection of tags to set on the experiment.
 
 # Returns
-An object of type [`Experiment`](@ref).
+The ID of the newly created experiment.
 """
-function createexperiment(instance::MLFlow; name::String=missing,
-    artifact_location::String=missing, tags::Array{Dict{Any, Any}}=[])
-    if ismissing(name)
-        name = string(UUIDs.uuid4())
+function createexperiment(instance::MLFlow; name::String="",
+    artifact_location::String="",
+    tags::Union{Dict{<:Any}, Array{<:Any}}=[])::String
+    if name |> isempty
+        name = UUIDs.uuid4() |> string
     end
 
+    tags = tags |> parsetags
+
     try
         result = mlfpost(instance, "experiments/create"; name=name,
             artifact_location=artifact_location, tags=tags)
-        return getexperiment(instance, result["experiment_id"])
+        return result["experiment_id"]
     catch e
         if isa(e, HTTP.ExceptionRequest.StatusError) && e.status == 400
-            error_code = JSON.parse(String(e.response.body))["error_code"]
+            error_code = (e.response.body |> String |> JSON.parse)["error_code"]
             if error_code == MLFLOW_ERROR_CODES.RESOURCE_ALREADY_EXISTS
                 error("Experiment with name \"$name\" already exists")
             end
         end
         throw(e)
     end
 end
-createexperiment(instance::MLFlow; name::String=missing,
-    artifact_location::String=missing, tags::Array{Pair{Any, Any}}=[]) =
-    createexperiment(instance, name=name, artifact_location=artifact_location,
-        tags=tags |> transform_pair_array_to_dict_array)
-createexperiment(instance::MLFlow; name::String=missing,
-    artifact_location::String=missing, tags::Dict{Any, Any}=[]) =
-    createexperiment(instance, name=name, artifact_location=artifact_location,
-        tags=tags |> transform_dict_to_dict_array)
-createexperiment(instance::MLFlow; name::String=missing,
-    artifact_location::String=missing, tags::Array{Tag}=[]) =
-    createexperiment(instance, name=name, artifact_location=artifact_location,
-        tags=tags |> transform_tag_array_to_dict_array)
 
 """
     getexperiment(instance::MLFlow, experiment_id::String)
+    getexperiment(instance::MLFlow, experiment_id::Integer)
 
 Get metadata for an experiment. This method works on deleted experiments.
 
@@ -66,7 +59,7 @@ function getexperiment(instance::MLFlow, experiment_id::String)
     try
         arguments = (:experiment_id => experiment_id,)
         result = mlfget(instance, "experiments/get"; arguments...)
-        return Experiment(result["experiment"])
+        return result["experiment"] |> Experiment
     catch e
         if isa(e, HTTP.ExceptionRequest.StatusError) && e.status == 404
             return missing
@@ -75,4 +68,174 @@ function getexperiment(instance::MLFlow, experiment_id::String)
     end
 end
 getexperiment(instance::MLFlow, experiment_id::Integer) =
-    getexperiment(instance, experiment_id)
+    getexperiment(instance, string(experiment_id))
+
+"""
+    getexperimentbyname(instance::MLFlow, experiment_name::String)
+
+Get metadata for an experiment.
+
+This endpoint will return deleted experiments, but prefers the active
+experiment if an active and deleted experiment share the same name. If multiple
+deleted experiments share the same name, the API will return one of them.
+
+# Arguments
+- `instance`: [`MLFlow`](@ref) configuration.
+- `experiment_name`: Name of the associated experiment.
+
+# Returns
+An object of type [`Experiment`](@ref).
+"""
+function getexperimentbyname(instance::MLFlow, experiment_name::String)
+    try
+        arguments = (:experiment_name => experiment_name,)
+        result = mlfget(instance, "experiments/get-by-name"; arguments...)
+        return result["experiment"] |> Experiment
+    catch e
+        if isa(e, HTTP.ExceptionRequest.StatusError) && e.status == 404
+            return missing
+        end
+        throw(e)
+    end
+end
+
+"""
+    deleteexperiment(mlf::MLFlow, experiment_id::String)
+    deleteexperiment(mlf::MLFlow, experiment_id::Integer)
+    deleteexperiment(mlf::MLFlow, experiment::Experiment)
+
+Mark an experiment and associated metadata, runs, metrics, params, and tags for
+deletion. If the experiment uses FileStore, artifacts associated with
+experiment are also deleted.
+
+# Arguments
+- `mlf`: [`MLFlow`](@ref) configuration.
+- `experiment_id`: ID of the associated experiment.
+
+# Returns
+
+`true` if successful. Otherwise, raises exception.
+"""
+function deleteexperiment(mlf::MLFlow, experiment_id::String)
+    endpoint = "experiments/delete"
+    try
+        mlfpost(mlf, endpoint; experiment_id=experiment_id)
+        return true
+    catch e
+        if isa(e, HTTP.ExceptionRequest.StatusError) && e.status == 404
+            # experiment already deleted
+            return true
+        end
+        throw(e)
+    end
+end
+deleteexperiment(mlf::MLFlow, experiment_id::Integer) =
+    deleteexperiment(mlf, string(experiment_id))
+deleteexperiment(mlf::MLFlow, experiment::Experiment) =
+    deleteexperiment(mlf, experiment.experiment_id)
+
+"""
+    restoreexperiment(mlf::MLFlow, experiment_id::String)
+    restoreexperiment(mlf::MLFlow, experiment_id::Integer)
+    restoreexperiment(mlf::MLFlow, experiment::Experiment)
+
+Restore an experiment marked for deletion. This also restores associated
+metadata, runs, metrics, params, and tags. If experiment uses FileStore,
+underlying artifacts associated with experiment are also restored.
+
+# Arguments
+- `mlf`: [`MLFlow`](@ref) configuration.
+- `experiment_id`: ID of the associated experiment.
+
+# Returns
+
+`true` if successful. Otherwise, raises exception.
+"""
+function restoreexperiment(mlf::MLFlow, experiment_id::String)
+    endpoint = "experiments/restore"
+    try
+        mlfpost(mlf, endpoint; experiment_id=experiment_id)
+        return true
+    catch e
+        if isa(e, HTTP.ExceptionRequest.StatusError) && e.status == 404
+            error_code = JSON.parse(String(e.response.body))["error_code"]
+            if error_code == MLFLOW_ERROR_CODES.RESOURCE_DOES_NOT_EXIST
+                error("Experiment with id \"$experiment_id\" does not exist")
+            end
+        end
+        throw(e)
+    end
+end
+restoreexperiment(mlf::MLFlow, experiment_id::Integer) =
+    deleteexperiment(mlf, string(experiment_id))
+restoreexperiment(mlf::MLFlow, experiment::Experiment) =
+    deleteexperiment(mlf, experiment.experiment_id)
+
+"""
+    updateexperiment(mlf::MLFlow, experiment_id::String, new_name::String)
+    updateexperiment(mlf::MLFlow, experiment_id::Integer, new_name::String)
+    updateexperiment(mlf::MLFlow, experiment::Experiment, new_name::String)
+
+Update experiment metadata.
+
+# Arguments
+- `mlf`: [`MLFlow`](@ref) configuration.
+- `experiment_id`: ID of the associated experiment.
+- `new_name`: If provided, the experiment’s name is changed to the new name.
+The new name must be unique.
+
+# Returns
+`true` if successful. Otherwise, raises exception.
+"""
+function updateexperiment(mlf::MLFlow, experiment_id::String, new_name::String)
+    endpoint = "experiments/update"
+    try
+        mlfpost(mlf, endpoint; experiment_id=experiment_id, new_name=new_name)
+        return true
+    catch e
+        throw(e)
+    end
+end
+updateexperiment(mlf::MLFlow, experiment_id::Integer, new_name::String) =
+    updateexperiment(mlf, string(experiment_id), new_name)
+updateexperiment(mlf::MLFlow, experiment::Experiment, new_name::String) =
+    updateexperiment(mlf, experiment.experiment_id, new_name::String)
+
+"""
+    searchexperiments(mlf::MLFlow; max_results::Integer=20000,
+        page_token::String="", filter::String="", order_by::Array{String}=[],
+        view_type::ViewType=ACTIVE_ONLY)
+
+# Arguments
+- `mlf`: [`MLFlow`](@ref) configuration.
+- `max_results`: Maximum number of experiments desired.
+- `page_token`: Token indicating the page of experiments to fetch.
+- `filter`: A filter expression over experiment attributes and tags that allows
+returning a subset of experiments. See [MLFlow documentation](https://mlflow.org/docs/latest/rest-api.html#search-experiments).
+- `order_by`: List of columns for ordering search results, which can include
+experiment name and id with an optional “DESC” or “ASC” annotation, where “ASC”
+is the default.
+- `view_type`: Qualifier for type of experiments to be returned. If
+unspecified, return only active experiments.
+
+# Returns
+- vector of [`MLFlowExperiment`](@ref) experiments that were found in the MLFlow instance
+"""
+function searchexperiments(mlf::MLFlow; max_results::Integer=20000,
+    page_token::String="", filter::String="", order_by::Array{String}=String[],
+    view_type::ViewType=ACTIVE_ONLY)
+    endpoint = "experiments/search"
+    parameters = (; max_results, page_token, filter,
+        :view_type => view_type |> Integer)
+
+    if order_by |> !isempty
+        parameters = (; order_by, parameters...)
+    end
+
+    try
+        result = mlfget(mlf, endpoint; parameters...)
+        return result["experiments"] |> (x -> [Experiment(y) for y in x])
+    catch e
+        throw(e)
+    end
+end