How to query metadata via the Neptune API#
You can download the metadata of your runs and models in bulk, or extract data from individual objects.
This page outlines some common ways to access typical metadata. For the full list of ways to interact with metadata fields, see Field types reference.
Related
Downloading runs table as DataFrame#
To download the runs table of a project as a pandas DataFrame, initialize the project with init_project()
and use the fetch_runs_table()
method:
import neptune
project = neptune.init_project(
project="workspace-name/project-name", # (1)!
mode="read-only",
)
# Get dashboard with runs contributed by "jackie" and tagged "cycleLR"
runs_table_df = project.fetch_runs_table(owner="sophia", tag="cycleLR").to_pandas()
runs_table_df.head()
-
The full project name. For example,
"ml-team/classification"
.To copy it to your clipboard, navigate to the project settings in the top-right () and select Edit project details.
The returned runs_table_df
is a pandas DataFrame, where
- each row represents a run.
- each column represents a metadata field, such as metrics, text logs, and parameters.
To include only certain fields as columns in the table, use the columns
parameter:
>>> filtered_runs_df = project.fetch_runs_table(
... columns=["sys/running_time", "f1_score"]
... ).to_pandas()
Fetching table...
>>> print(filtered_runs_df)
sys/id sys/running_time f1_score
0 CLS-8 5.436 0.95
1 CLS-7 12.342 0.92
2 CLS-6 318.538 0.80
3 CLS-5 9.560 0.80
...
Below is a more complex example, with custom columns, sorting, and a limit on the number of returned entries.
>>> runs_table_df = project.fetch_runs_table(
... columns=["sys/modification_time", "sys/ping_time"],
... sort_by="sys/ping_time",
... limit=5,
... ).to_pandas()
Fetching table...
>>> print(runs_table_df)
sys/id sys/modification_time sys/ping_time
0 NLU-22 2024-01-12T16:52:14.083Z 2024-01-12T16:52:14.083Z
1 NLU-23 2024-01-03T08:49:06.008Z 2024-01-03T08:49:06.008Z
2 NLU-21 2023-12-22T10:34:09.065Z 2023-12-22T10:34:09.065Z
3 NLU-20 2023-12-22T10:28:56.065Z 2023-12-20T14:59:00.122Z
4 NLU-19 2023-12-20T14:56:54.21Z 2023-12-20T14:56:54.21Z
Ping time refers to the last interaction with the Neptune client library; that is, when something was last logged by the API.
Related
- API reference ≫
project
- System namespace:
ping_time
Using a custom progress bar#
To use a custom callback to visualize the download progress, simply define a class that inherits from ProgressBarCallback
and pass it to the progress_bar
argument (the type, not an instance).
from types import TracebackType
from typing import Any, Optional, Type
from neptune.typing import ProgressBarCallback
class ClickProgressBar(ProgressBarCallback):
def __init__(self, *, description: Optional[str] = None, **_: Any) -> None:
super().__init__()
from click import progressbar
...
self._progress_bar = progressbar(iterable=None, length=1, label=description)
...
def update(self, *, by: int, total: Optional[int] = None) -> None:
if total:
self._progress_bar.length = total
self._progress_bar.update(by)
...
def __enter__(self) -> "ClickProgressBar":
self._progress_bar.__enter__()
return self
...
def __exit__(
self,
exc_type: Optional[Type[BaseException]],
exc_val: Optional[BaseException],
exc_tb: Optional[TracebackType],
) -> None:
self._progress_bar.__exit__(exc_type, exc_val, exc_tb)
import neptune
project = neptune.init_project(project="ml-team/nlu", mode="read-only")
project.fetch_runs_table(progress_bar=ClickProgressBar)
Querying metadata from object#
To query metadata from a given run or other object, you fetch or download the metadata in a similar fashion as you logged it.
The methods correspond in the following way:
Logging method | Querying method | Field type to use on |
---|---|---|
= or assign() |
fetch() |
Any single value field except (File ) |
add() |
fetch() |
Tags (StringSet ) |
append() (prev. log() ) |
fetch_last() , fetch_values() |
FloatSeries , StringSeries |
append(File()) |
download_last() , download() |
FileSeries |
track_files() |
fetch_hash() , fetch_files_list() , download() |
Artifact |
upload() , upload_files() |
download() |
File , FileSet |
For the full list, see API reference ≫ Field types.
Initializing existing object#
Start by initializing Neptune with the ID of the object:
How do I find the ID?
The Neptune ID is a unique identifier for the run. In the table view, it's displayed in the leftmost column.
The ID is stored in the system namespace (sys/id
).
If the run is active, you can obtain its ID with run["sys/id"].fetch()
. For example:
Setting the mode to "read only" ensures that no data is added or changed.
Querying single value#
Use the fetch()
method to query any single-valued metadata of the object:
params = run["parameters"].fetch()
batch_size = run["parameters/batch_size"].fetch()
f1_score = run["f1_score"].fetch()
The same method works for fields in the system namespace:
username = run["sys/owner"].fetch() # string
last_updated = run["sys/modification_time"].fetch() # datetime
my_run_id = run["sys/id"].fetch() # run ID
Fetching artifact metadata#
See Download artifact metadata.
Querying tags#
You can access the tags of an object by using fetch()
on the sys/tags
field:
Querying values from series field#
For value series logged with the append()
(previously log()
) method, you can query either the last value or the full list of values.
# Accessing last value of FloatSeries
final_loss = run["train/loss"].fetch_last()
# Accessing last value of StringSeries
last_stderr_line = run["monitoring/6519428b/stderr"].fetch_last()
Retrieve all the values and their indexes as a pandas DataFrame with fetch_values()
:
loss_df = run["train/loss"].fetch_values()
# Don't include timestamp
loss_df = run["train/loss"].fetch_values(include_timestamp=False)
Similarly, from FileSeries fields, you can download the last file to the disk with download_last()
or download all files with download()
:
# Download last file in the FileSeries
run["train/epoch/histogram"].download_last()
# Download all files in the FileSeries
run["train/epoch/histogram"].download()
Downloading files#
Use download()
to query uploaded files:
# Download example_image to the current directory
run["data/example_image"].download()
# Download model to the specified directory
run["trained_model"].download(destination_path)
You can also download files from artifact fields:
# Download all files from the artifact, optionally specifying a download destination
run["datasets/train"].download(destination="./datasets")
For details, see Download artifact metadata.
Query nested namespaces or fields#
To query namespaces or fields that are nested under another namespace, you can access the object structure with get_structure()
.
Example
To get the monitoring sub-namespaces, which are generated automatically by Neptune for each process: