Skip to main content
Version: v1.0.0

Handle artifacts

This guide explains how to add artifacts to an MLOps entity, such as a workspace, dataset, experiment, or deployment, as well as how to retrieve, update, delete, or convert artifacts to a string or dictionary.

Prerequisites​

Before you begin,

Add an artifact​

Use the add() method to upload an artifact to an entity.

artifact = entity.artifacts.add(
   data="/path/to/docx_artifact.docx",
   mime_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document",
)
note

If you link a H2O Driverless AI (DAI) experiment to a workspace directly from a DAI instance, all its artifacts are added to the experiment automatically.

View artifacts​

List artifacts​

Use the list() method to view all artifacts linked to an entity.

Input:

artifacts = entity.artifacts.list()
artifacts

Output:

   | name               | mime_type                 | uid
---+--------------------+---------------------------+--------------------------------------
 0 | docx_artifact.docx | application/vnd.openxmlfo | 92e4ea49-fdcd-436b-9293-dcd0e8fdae18
note

  • The output of list() method is displayed in a neatly formatted view. By default, only the first 50 rows are displayed to keep the output concise and manageable.

  • Calling len(artifacts) returns the total number of rows it contains, not just the number currently displayed.

  • To customize the number of rows displayed, you can call the show() method with the n argument. This allows more rows to be shown when needed. For example:

    artifacts.show(n=100)

    This will display up to 100 artifacts.

  • The artifacts can be iterated over, as it is designed to behave like an iterator.

Filter artifacts​

Use the list() method with key-value arguments to filter the artifacts.

Input:

entity.artifacts.list(name="docx_artifact.docx")

This returns a list of matching artifacts as a table.

Output:

   | name               | mime_type                 | uid
---+--------------------+---------------------------+--------------------------------------
 0 | docx_artifact.docx | application/vnd.openxmlfo | 92e4ea49-fdcd-436b-9293-dcd0e8fdae18

Retrieve an artifact​

Use the get() method to retrieve a specific artifact by its unique ID.

Input:

artifact = entity.artifacts.get(uid="92e4ea49-fdcd-436b-9293-dcd0e8fdae18")
artifact
note

You can retrieve a specific artifact from the list returned by list() using indexing.
For example, artifact = entity.artifacts.list(key=value)[index]. The key and value arguments are optional.

Output:

<class 'h2o_mlops._artifacts.MLOpsArtifact(
   uid='92e4ea49-fdcd-436b-9293-dcd0e8fdae18',
   parent_entity_uid='777b3d15-36ba-4a96-b687-47e3d6687d4d',
   name='docx_artifact.docx',
   state='AVAILABLE',
   mime_type='application/vnd.openxmlformats-officedocument.wordprocessingml.document',
   size=0,
   md5_digest='1B2M2Y8AsgTpgAmY7PhCfg==',
   created_time=datetime.datetime(2025, 6, 11, 17, 31, 12, 850635, tzinfo=tzutc()),
   uploaded_time=datetime.datetime(2025, 6, 11, 17, 31, 16, 26743, tzinfo=tzutc()),
   last_modified_time=datetime.datetime(2025, 6, 11, 17, 31, 16, 27248, tzinfo=tzutc()),
)'>

Artifact properties​

An artifact has the following main properties:

  • uid: Unique ID of the artifact
  • parent_entity_uid: ID of the parent workspace, dataset, etc.
  • name: Name of the artifact
  • state: Artifact state
  • mime_type: File type of the artifact
  • size: File size in bytes
  • md5_digest: MD5 hash of the artifact
  • created_time: Timestamp when the artifact was created
  • uploaded_time: Timestamp when the artifact was uploaded
  • last_modified_time: Last time the artifact was updated
  • model_info: Model-specific metadata, if applicable

Download an artifact​

To download an artifact:

Input:

artifact.download()

Output:

'docx_artifact.docx'

The download() method supports the following optional parameters:

  • directory: Target folder (default: current working directory)
  • file_name: Output filename (default: artifact’s name)
  • overwrite: Whether to overwrite the file if it exists (default: False)
  • buffer: Store the file in memory using io.BytesIO instead of writing to disk
note

  • If you don't specify any options, the artifact downloads to the current working directory using its name.

  • If the artifact name does not include a file extension, you must pass the file_name argument with the appropriate extension. You can use the artifact's MIME type (mime_type) to determine the correct file extension.

    Common MIME types and corresponding file extensions:

    MIME typeFile extension
    application/vnd.openxmlformats-officedocument.wordprocessingml.document.docx
    application/json.json
    text/plain.txt
    application/zip.zip
    application/pdf.pdf
    image/png.png

Convert artifacts​

Artifacts can be converted to string or dictionary format, depending on their type:

  • A JSON artifact can be converted to a string or a dictionary.
  • A text artifact can only be converted to a string.
  • Other artifact types cannot be converted.

Convert JSON artifacts​

To convert JSON artifacts to a string and a dictionary, follow these steps:

  1. Add the JSON file to the specified entity as an artifact.

    json_artifact = entity.artifacts.add(
       data="/path/to/json_artifact.json",
       mime_type="application/json",
    )

  2. Convert the JSON artifact to a string:

    Input:

    json_artifact.to_string()

    Output:

    '{\n    "key": "value"\n}\n'

  3. Convert a JSON artifact to a dictionary:

    Input:

    json_artifact.to_dict()

    Output:

    {'key': 'value'}

Convert text artifacts​

To convert text artifacts to a string, follow these steps:

  1. Add the text file to the specified entity as an artifact.

    text_artifact = entity.artifacts.add(
       data="/path/to/txt_artifact.txt",
       mime_type="text/plain",
    )

  2. Convert the text artifact to a string:

    Input:

    text_artifact.to_string()

    Output:

    "It's a text file.\n"

Update an artifact​

You can update only the name and parent_entity fields of an artifact.

Make sure to retrieve the artifact before updating it. See Retrieve an artifact.

Input:

artifact.update(name="my-docx-artifact")
artifact

Output:

<class 'h2o_mlops._artifacts.MLOpsArtifact(
   uid='92e4ea49-fdcd-436b-9293-dcd0e8fdae18',
   parent_entity_uid='777b3d15-36ba-4a96-b687-47e3d6687d4d',
   name='my-docx-artifact',
   state='AVAILABLE',
   mime_type='application/vnd.openxmlformats-officedocument.wordprocessingml.document',
   size=0,
   md5_digest='1B2M2Y8AsgTpgAmY7PhCfg==',
   created_time=datetime.datetime(2025, 6, 11, 17, 31, 12, 850635, tzinfo=tzutc()),
   uploaded_time=datetime.datetime(2025, 6, 11, 17, 31, 16, 26743, tzinfo=tzutc()),
   last_modified_time=datetime.datetime(2025, 6, 11, 17, 31, 36, 773648, tzinfo=tzutc()),
)'>

Delete an artifact​

This section describes how to delete an artifact.

Use the delete() method to remove the artifact from the entity:

Input:

artifact.delete()
entity.artifacts.list()

In this example, artifact.delete() deletes the docx_artifact.docx artifact assigned to the artifact variable earlier in the Add an artifact section and retrieved in the Retrieve an artifact section.

The list() output confirms that the artifact has been successfully removed.

Output:

   | name               | mime_type        | uid
---+--------------------+------------------+--------------------------------------
 0 | txt_artifact.txt   | text/plain       | 04eaf9e2-f6cf-4140-9686-b31290f7fd17
 1 | json_artifact.json | application/json | 5d442fc2-d0ae-42eb-8050-42255fa8c10a

After deletion, the docx_artifact.docx artifact no longer appears in the list of artifacts for the entity.

Feedback