Query metadata
To query the logged metadata programmatically, use the Neptune Query API. You can:
- Fetch experiment metadata as a data frame.
- Define filters to query experiments, runs, and attributes that meet certain criteria.
- List experiments, runs, and attributes of a project.
The extended regular expression syntax is supported for matching names and other string values.
Setup
To install the Neptune Query API client:
pip install "neptune-query>=1.0.0,<2.0.0"
Set your Neptune API token and project name as environment variables:
- Linux
- macOS
- Windows
- Jupyter Notebook
- Google Colab
In your .profile
or other shell initialization file, use the export
commands:
export NEPTUNE_API_TOKEN="h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ=="
export NEPTUNE_PROJECT="workspace-name/project-name"
In your .profile
or other shell initialization file, use the export
commands:
export NEPTUNE_API_TOKEN="h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ=="
export NEPTUNE_PROJECT="workspace-name/project-name"
-
Open a terminal app, such as PowerShell or Command Prompt.
-
Paste the
setx
commands and press :setx NEPTUNE_API_TOKEN "h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ=="
setx NEPTUNE_PROJECT "workspace-name/project-name"
-
To activate the change, restart the terminal app.
Optionally, add the variable in Settings → Edit the system environment variables.
In notebooks for your personal use, set credentials with magic commands:
%env NEPTUNE_API_TOKEN=h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ==
%env NEPTUNE_PROJECT=workspace-name/project-name
In shared notebooks, it's more secure to use the os and getpass libraries:
import os
from getpass import getpass
os.environ["NEPTUNE_API_TOKEN"] = getpass("Enter your Neptune API token: ")
os.environ["NEPTUNE_PROJECT"] = "workspace-name/project-name"
Note that these don't persist when the notebook kernel is terminated. You must declare the variables again if you restart the notebook.
In Colab notebooks for your personal use, set credentials with magic commands:
%env NEPTUNE_API_TOKEN=h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ==
%env NEPTUNE_PROJECT=workspace-name/project-name
In shared Colab notebooks, it's more secure to use the os and getpass libraries:
import os
from getpass import getpass
os.environ["NEPTUNE_API_TOKEN"] = getpass("Enter your Neptune API token: ")
os.environ["NEPTUNE_PROJECT"] = "workspace-name/project-name"
Note that these don't persist when the notebook kernel is terminated. You must declare the variables again if you restart the notebook.
For help, see Get started.
You can also pass the project path to the project
argument of any querying function.
Usage
import neptune_query as nq
Available functions:
fetch_experiments_table()
– with runs as rows and attributes as columns.fetch_metrics()
– series of numerical values, one step per row.fetch_series()
– for series of strings, files, or histograms.list_attributes()
– all logged attributes of the target project's experiment runs.list_experiments()
– names of experiments in the target project.set_api_token()
– the Neptune API token to use for the session.
You can also target individual runs by ID instead of experiment runs by name. To use the corresponding methods for runs, import the runs
module:
import neptune_query.runs as nq_runs
nq_runs.fetch_metrics(...)
Example 1: Fetch metric values per step
To fetch numerical values at each step, use fetch_metrics()
:
- To specify or filter experiments to return, use the
experiments
parameter. - To specify attributes to include as columns, use the
attributes
parameter. - To limit the returned values, use the available parameters.
nq.fetch_metrics(
experiments=["exp_dczjz"],
attributes=r"metrics/val_.+_estimated$",
tail_limit=5,
)
metrics/val_accuracy_estimated metrics/val_loss_estimated
experiment step
exp_dczjz 1000.0 0.72187 0.14989
1001.0 0.72683 0.14781
1002.0 0.76981 0.14233
1003.0 0.76995 0.13552
1004.0 0.78161 0.12020
Example 2: Fetch metadata as one run per row
To fetch experiment metadata from your project, use fetch_experiments_table()
. The output mimics the runs table of the web app.
- To specify or filter experiments to return, use the
experiments
parameter. - To specify attributes to include as columns, use the
attributes
parameter.
nq.fetch_experiments_table(
experiments=r"^exp_",
attributes=["metrics/train_accuracy", "metrics/train_loss", "learning_rate"],
)
metrics/train_accuracy metrics/train_loss learning_rate
experiment
exp_ergwq 0.278149 0.336344 0.01
exp_qgguv 0.160260 0.790268 0.02
exp_hstrj 0.365521 0.459901 0.01
For series attributes, the value of the last logged step is returned.
Example 3: Define filters
List my experiments that have a "dataset_version" attribute and "val/loss" less than 0.1:
from neptune_query.filters import Filter
owned_by_me = Filter.eq("sys/owner", "sigurd")
dataset_check = Filter.exists("dataset_version")
loss_filter = Filter.lt("val/loss", 0.1)
interesting = owned_by_me & dataset_check & loss_filter
nq.list_experiments(experiments=interesting)
['exp_ergwq', 'exp_qgguv', 'exp_hstrj']
Then fetch configs from the experiments, including also the interesting metric:
nq.fetch_experiments_table(
experiments=interesting,
attributes=r"config/ | val/loss",
)
config/optimizer config/batch_size config/learning_rate val/loss
experiment
exp_ergwq Adam 32 0.001 0.0901
exp_qgguv Adadelta 32 0.002 0.0876
exp_hstrj Adadelta 64 0.001 0.0891
For details, see Filter
.