mlflow.entities

The mlflow.entities module defines entities returned by the MLflow REST API.

class mlflow.entities.Dataset(name: str, digest: str, source_type: str, source: str, schema: Optional[str] = None, profile: Optional[str] = None)

Dataset object associated with an experiment.

property digest

String digest of the dataset.

classmethod from_proto(proto)

property name

String name of the dataset.

property profile

String profile of the dataset.

property schema

String schema of the dataset.

property source

String source of the dataset.

property source_type

String source_type of the dataset.

to_proto()

class mlflow.entities.DatasetInput(dataset: Dataset, tags: Optional[List[InputTag]] = None)

DatasetInput object associated with an experiment.

property dataset

Dataset.

classmethod from_proto(proto)

property tags

Array of input tags.

to_proto()

class mlflow.entities.Experiment(experiment_id, name, artifact_location, lifecycle_stage, tags=None, creation_time=None, last_update_time=None)

Experiment object.

DEFAULT_EXPERIMENT_NAME = 'Default'

property artifact_location

String corresponding to the root artifact URI for the experiment.

property creation_time

property experiment_id

String ID of the experiment.

classmethod from_proto(proto)

property last_update_time

property lifecycle_stage

Lifecycle stage of the experiment. Can either be ‘active’ or ‘deleted’.

property name

String name of the experiment.

property tags

Tags that have been set on the experiment.

to_proto()

class mlflow.entities.ExperimentTag(key, value)

Tag object associated with an experiment.

classmethod from_proto(proto)

property key

String name of the tag.

to_proto()

property value

String value of the tag.

class mlflow.entities.FileInfo(path, is_dir, file_size)

Metadata about a file or directory.

property file_size

Size of the file or directory. If the FileInfo is a directory, returns None.

classmethod from_proto(proto)

property is_dir

Whether the FileInfo corresponds to a directory.

property path

String path of the file or directory.

to_proto()

class mlflow.entities.InputTag(key: str, value: str)

Input tag object associated with a dataset.

classmethod from_proto(proto)

property key

String name of the input tag.

to_proto()

property value

String value of the input tag.

class mlflow.entities.LifecycleStage

ACTIVE = 'active'

DELETED = 'deleted'

classmethod is_valid(lifecycle_stage)

classmethod matches_view_type(view_type, lifecycle_stage)

classmethod view_type_to_stages(view_type=3)

class mlflow.entities.LiveSpan(otel_span: opentelemetry.trace.span.Span, request_id: str, span_type: str = 'UNKNOWN')

A “live” version of the Span class.

The live spans are those being created and updated during the application runtime. When users start a new span using the tracing APIs within their code, this live span object is returned to get and set the span attributes, status, events, and etc.

add_event(event: SpanEvent)

Add an event to the span.

Parameters

event – The event to add to the span. This should be a SpanEvent object.

from_dict(data: Dict[str, Any]) → Span

Create a Span object from the given dictionary.

set_attribute(key: str, value: Any)

Set a single attribute to the span.

set_attributes(attributes: Dict[str, Any])

Set the attributes to the span. The attributes must be a dictionary of key-value pairs. This method is additive, i.e. it will add new attributes to the existing ones. If an attribute with the same key already exists, it will be overwritten.

set_inputs(inputs: Any)

Set the input values to the span.

set_outputs(outputs: Any)

Set the output values to the span.

set_status(status: Union[SpanStatusCode, str])

Set the status of the span.

Parameters

status – The status of the span. This can be a SpanStatus object or a string representing of the status code defined in SpanStatusCode e.g. "OK", "ERROR".

class mlflow.entities.Metric(key, value, timestamp, step)

Metric object.

classmethod from_dictionary(metric_dict)

Create a Metric object from a dictionary.

Parameters

metric_dict (dict) – Dictionary containing metric information.

Returns

The Metric object created from the dictionary.

Return type

Metric

classmethod from_proto(proto)

property key

String key corresponding to the metric name.

property step

Integer metric step (x-coordinate).

property timestamp

Metric timestamp as an integer (milliseconds since the Unix epoch).

to_dictionary()

Convert the Metric object to a dictionary.

Returns

The Metric object represented as a dictionary.

Return type

dict

to_proto()

property value

Float value of the metric.

class mlflow.entities.NoOpSpan

No-op implementation of the Span interface.

This instance should be returned from the mlflow.start_span context manager when span creation fails. This class should have exactly the same interface as the Span so that user’s setter calls do not raise runtime errors.

E.g.

with mlflow.start_span("span_name") as span:
    # Even if the span creation fails, the following calls should pass.
    span.set_inputs({"x": 1})
    # Do something

add_event(event: SpanEvent)

property context

end()

property end_time_ns

The end time of the span in nanosecond.

property name

The name of the span.

property parent_id

The span ID of the parent span.

property request_id

No-op span returns a special request ID to distinguish it from the real spans.

set_attribute(key: str, value: Any)

set_attributes(attributes: Dict[str, Any])

set_inputs(inputs: Dict[str, Any])

set_outputs(outputs: Dict[str, Any])

set_status(status: SpanStatus)

property span_id

The ID of the span. This is only unique within a trace.

property start_time_ns

The start time of the span in nanosecond.

property status

The status of the span.

class mlflow.entities.Param(key, value)

Parameter object.

classmethod from_proto(proto)

property key

String key corresponding to the parameter name.

to_proto()

property value

String value of the parameter.

class mlflow.entities.Run(run_info: RunInfo, run_data: RunData, run_inputs: Optional[RunInputs] = None)

Run object.

property data

The run data, including metrics, parameters, and tags.

Return type

mlflow.entities.RunData

classmethod from_proto(proto)

property info

The run metadata, such as the run id, start time, and status.

Return type

mlflow.entities.RunInfo

property inputs

The run inputs, including dataset inputs

Return type

mlflow.entities.RunInputs

to_dictionary() → Dict[Any, Any]

to_proto()

class mlflow.entities.RunData(metrics=None, params=None, tags=None)

Run data (metrics and parameters).

classmethod from_proto(proto)

property metrics

Dictionary of string key -> metric value for the current run. For each metric key, the metric value with the latest timestamp is returned. In case there are multiple values with the same latest timestamp, the maximum of these values is returned.

property params

Dictionary of param key (string) -> param value for the current run.

property tags

Dictionary of tag key (string) -> tag value for the current run.

to_dictionary()

to_proto()

class mlflow.entities.RunInfo(run_uuid, experiment_id, user_id, status, start_time, end_time, lifecycle_stage, artifact_uri=None, run_id=None, run_name=None)

Metadata about a run.

property artifact_uri

String root artifact URI of the run.

property end_time

End time of the run, in number of milliseconds since the UNIX epoch.

property experiment_id

String ID of the experiment for the current run.

classmethod from_proto(proto)

classmethod get_orderable_attributes()

classmethod get_searchable_attributes()

property lifecycle_stage

One of the values in LifecycleStage describing the lifecycle stage of the run.

property run_id

String containing run id.

property run_name

String containing run name.

property run_uuid

[Deprecated, use run_id instead] String containing run UUID.

property start_time

Start time of the run, in number of milliseconds since the UNIX epoch.

property status

One of the values in mlflow.entities.RunStatus describing the status of the run.

to_proto()

property user_id

String ID of the user who initiated this run.

class mlflow.entities.RunInputs(dataset_inputs: List[DatasetInput])

RunInputs object.

property dataset_inputs

Array of dataset inputs.

classmethod from_proto(proto)

to_dictionary() → Dict[Any, Any]

to_proto()

class mlflow.entities.RunStatus

Enum for status of an mlflow.entities.Run.

FAILED = 4

FINISHED = 3

KILLED = 5

RUNNING = 1

SCHEDULED = 2

static all_status()

static from_string(status_str)

static is_terminated(status)

static to_string(status)

class mlflow.entities.RunTag(key, value)

Tag object associated with a run.

classmethod from_proto(proto)

property key

String name of the tag.

to_proto()

property value

String value of the tag.

class mlflow.entities.SourceType

Enum for originating source of a mlflow.entities.Run.

JOB = 2

LOCAL = 4

NOTEBOOK = 1

PROJECT = 3

RECIPE = 6

SOURCETYPE_TO_STRING = {1: 'NOTEBOOK', 2: 'JOB', 3: 'PROJECT', 4: 'LOCAL', 5: 'UNKNOWN', 6: 'RECIPE'}

UNKNOWN = 5

static from_string(status_str)

static to_string(status)

class mlflow.entities.Span(otel_span: opentelemetry.sdk.trace.ReadableSpan)

A span object. A span represents a unit of work or operation and is the building block of Traces.

This Span class represents immutable span data that is already finished and persisted. The “live” span that is being created and updated during the application runtime is represented by the LiveSpan subclass.

property attributes

Get all attributes of the span.

Returns

A dictionary of all attributes of the span.

property end_time_ns

The end time of the span in nanosecond.

property events

Get all events of the span.

Returns

A list of all events of the span.

classmethod from_dict(data: Dict[str, Any]) → Span

Create a Span object from the given dictionary.

get_attribute(key: str) → Optional[Any]

Get a single attribute value from the span.

Parameters

key – The key of the attribute to get.

Returns

The value of the attribute if it exists, otherwise None.

property inputs

The input values of the span.

property name

The name of the span.

property outputs

The output values of the span.

property parent_id

The span ID of the parent span.

property request_id

The request ID of the span, a unique identifier for the trace it belongs to. Request ID is equivalent to the trace ID in OpenTelemetry, but generated differently by the tracing backend.

property span_id

The ID of the span. This is only unique within a trace.

property span_type

The type of the span.

property start_time_ns

The start time of the span in nanosecond.

property status

The status of the span.

to_dict()

class mlflow.entities.SpanEvent(name: str, timestamp: int = <factory>, attributes: Dict[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]] = <factory>)

An event that records a specific occurrences or moments in time during a span, such as an exception being thrown. Compatible with OpenTelemetry.

Parameters

• name – Name of the event.

• timestamp – The exact time the event occurred, measured in microseconds. If not provided, the current time will be used.

• attributes – A collection of key-value pairs representing detailed attributes of the event, such as the exception stack trace. Attributes value must be one of [str, int, float, bool, bytes] or a sequence of these types.

attributes: Dict[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]

classmethod from_exception(exception: Exception)

Create a span event from an exception.

json()

name: str

timestamp: int

class mlflow.entities.SpanStatus(status_code: SpanStatusCode, description: str = '')

Status of the span or the trace.

Parameters

• status_code – The status code of the span or the trace. This must be one of the values of the mlflow.entities.SpanStatusCode enum or a string representation of it like “OK”, “ERROR”.

• description – Description of the status. This should be only set when the status is ERROR, otherwise it will be ignored.

description: str = ''

status_code: SpanStatusCode

class mlflow.entities.SpanStatusCode(value)

Enum for status code of a span

ERROR = 'ERROR'

OK = 'OK'

UNSET = 'UNSET'

class mlflow.entities.SpanType

Predefined set of span types.

AGENT = 'AGENT'

CHAIN = 'CHAIN'

CHAT_MODEL = 'CHAT_MODEL'

EMBEDDING = 'EMBEDDING'

LLM = 'LLM'

PARSER = 'PARSER'

RERANKER = 'RERANKER'

RETRIEVER = 'RETRIEVER'

TOOL = 'TOOL'

UNKNOWN = 'UNKNOWN'

class mlflow.entities.Trace(info: TraceInfo, data: TraceData)

A trace object.

Parameters

• info – A lightweight object that contains the metadata of a trace.

• data – A container object that holds the spans data of a trace.

data: TraceData

classmethod from_dict(trace_dict: Dict[str, Any]) → Trace

classmethod from_json(trace_json: str) → Trace

info: TraceInfo

static pandas_dataframe_columns() → List[str]

to_dict() → Dict[str, Any]

to_json(pretty=False) → str

to_pandas_dataframe_row() → Dict[str, Any]

class mlflow.entities.TraceData(spans: List[mlflow.entities.span.Span] = <factory>, request: Optional[str] = None, response: Optional[str] = None)

A container object that holds the spans data of a trace.

Parameters

• spans – List of spans that are part of the trace.

• request – Input data for the entire trace. Equivalent to the input of the root span but added for ease of access. Stored as a JSON string.

• response – Output data for the entire trace. Equivalent to the output of the root span. Stored as a JSON string.

classmethod from_dict(d)

request: Optional[str] = None

response: Optional[str] = None

spans: List[Span]

to_dict() → Dict[str, Any]

class mlflow.entities.TraceInfo(request_id: str, experiment_id: str, timestamp_ms: int, execution_time_ms: Optional[int], status: mlflow.entities.trace_status.TraceStatus, request_metadata: Dict[str, str] = <factory>, tags: Dict[str, str] = <factory>)

Metadata about a trace.

Parameters

• request_id – id of the trace.

• experiment_id – id of the experiment.

• timestamp_ms – start time of the trace, in milliseconds.

• execution_time_ms – duration of the trace, in milliseconds.

• status – status of the trace.

• request_metadata – Key-value pairs associated with the trace. Request metadata are designed for immutable values like run ID associated with the trace.

• tags – Tags associated with the trace. Tags are designed for mutable values like trace name, that can be updated by the users after the trace is created, unlike request_metadata.

execution_time_ms: Optional[int]

experiment_id: str

classmethod from_dict(trace_info_dict)

Convert trace info dictionary to TraceInfo object.

classmethod from_proto(proto)

request_id: str

request_metadata: Dict[str, str]

status: mlflow.entities.trace_status.TraceStatus

tags: Dict[str, str]

timestamp_ms: int

to_dict()

Convert trace info to a dictionary for persistence. Update status field to the string value for serialization.

to_proto()

class mlflow.entities.ViewType

Enum to filter requested experiment types.

ACTIVE_ONLY = 1

ALL = 3

DELETED_ONLY = 2

classmethod from_proto(proto_view_type)

classmethod from_string(view_str)

classmethod to_proto(view_type)

classmethod to_string(view_type)

class mlflow.entities.model_registry.ModelVersion(name, version, creation_timestamp, last_updated_timestamp=None, description=None, user_id=None, current_stage=None, source=None, run_id=None, status='READY', status_message=None, tags=None, run_link=None, aliases=None)

MLflow entity for Model Version.

property aliases

List of aliases (string) for the current model version.

property creation_timestamp

Integer. Model version creation timestamp (milliseconds since the Unix epoch).

property current_stage

String. Current stage of this model version.

property description

String. Description

classmethod from_proto(proto)

property last_updated_timestamp

Integer. Timestamp of last update for this model version (milliseconds since the Unix epoch).

property name

String. Unique name within Model Registry.

property run_id

String. MLflow run ID that generated this model.

property run_link

String. MLflow run link referring to the exact run that generated this model version.

property source

String. Source path for the model.

property status

String. Current Model Registry status for this model.

property status_message

String. Descriptive message for error status conditions.

property tags

Dictionary of tag key (string) -> tag value for the current model version.

to_proto()

property user_id

String. User ID that created this model version.

property version

class mlflow.entities.model_registry.ModelVersionTag(key, value)

Tag object associated with a model version.

classmethod from_proto(proto)

property key

String name of the tag.

to_proto()

property value

String value of the tag.

class mlflow.entities.model_registry.RegisteredModel(name, creation_timestamp=None, last_updated_timestamp=None, description=None, latest_versions=None, tags=None, aliases=None)

MLflow entity for Registered Model.

property aliases

Dictionary of aliases (string) -> version for the current registered model.

property creation_timestamp

Integer. Model version creation timestamp (milliseconds since the Unix epoch).

property description

String. Description

classmethod from_proto(proto)

property last_updated_timestamp

Integer. Timestamp of last update for this model version (milliseconds since the Unix epoch).

property latest_versions

List of the latest mlflow.entities.model_registry.ModelVersion instances for each stage.

property name

String. Registered model name.

property tags

Dictionary of tag key (string) -> tag value for the current registered model.

to_proto()

class mlflow.entities.model_registry.RegisteredModelAlias(alias, version)

Alias object associated with a registered model.

property alias

String name of the alias.

classmethod from_proto(proto)

to_proto()

property version

String model version number that the alias points to.

class mlflow.entities.model_registry.RegisteredModelTag(key, value)

Tag object associated with a registered model.

classmethod from_proto(proto)

property key

String name of the tag.

to_proto()

property value

String value of the tag.

class mlflow.store.entities.PagedList(items: List[T], token)

Wrapper class around the base Python List type. Contains an additional token string attribute that can be passed to the pagination API that returned this list to fetch additional elements, if any are available

to_list()