# Neptune Query API
The `neptune_query` package is a read-only API for fetching metadata tracked with the [Neptune logging client][neptune-client-scale].
With the Query API, you can:
- List experiments, runs, and attributes of a project.
- Fetch experiment or run metadata as a data frame.
- Define filters to fetch experiments, runs, and attributes that meet certain criteria.
## Installation
```bash
pip install "neptune-query>=1.0.0,<2.0.0"
```
Set your Neptune API token and project name as environment variables:
```bash
export NEPTUNE_API_TOKEN="ApiTokenFromYourNeptuneProfile"
```
```bash
export NEPTUNE_PROJECT="workspace-name/project-name"
```
For help, see [Get started][setup] in the Neptune documentation.
> **Note:** You can also pass the project path to the `project` argument of any querying function.
## Usage
```python
import neptune_query as nq
```
Available functions:
- `fetch_experiments_table()` – runs as rows and attributes as columns.
- `fetch_metrics()` – series of float or int values, with steps as rows.
- `fetch_series()` – for series of strings 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()` – set the Neptune API token to use for the session.
### Example 1: Fetch metric values
To fetch values at each step, use `fetch_metrics()`.
- To filter experiments to return, use the `experiments` parameter.
- To specify attributes to include as columns, use the `attributes` parameter.
```python
nq.fetch_metrics(
experiments=["exp_dczjz"],
attributes=r"metrics/val_.+_estimated$",
)
```
```pycon
metrics/val_accuracy_estimated metrics/val_loss_estimated
experiment step
exp_dczjz 1.0 0.432187 0.823375
2.0 0.649685 0.971732
3.0 0.760142 0.154741
4.0 0.719508 0.504652
```
### Example 2: Fetch metadata as one row per run
To fetch experiment metadata from your project, use the `fetch_experiments_table()` function:
```python
nq.fetch_experiments_table(
experiments=r"^exp_",
attributes=["metrics/train_accuracy", "metrics/train_loss", "learning_rate"],
)
```
```pycon
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.
---
## License
This project is licensed under the Apache License Version 2.0. For details, see [Apache License Version 2.0][license].
[setup]: https://docs.neptune.ai/setup
[neptune-client-scale]: https://github.com/neptune-ai/neptune-client-scale
[license]: http://www.apache.org/licenses/LICENSE-2.0
Raw data
{
"_id": null,
"home_page": null,
"name": "neptune-query",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "MLOps, ML Experiment Tracking, ML Model Registry, ML Model Store, ML Metadata Store",
"author": "neptune.ai",
"author_email": "contact@neptune.ai",
"download_url": "https://files.pythonhosted.org/packages/8c/c0/9f074ecd3d565228c2149cc41a5b2f0d403ac82065c2a80bbd251149a8d3/neptune_query-1.0.0.tar.gz",
"platform": null,
"description": "# Neptune Query API\n\nThe `neptune_query` package is a read-only API for fetching metadata tracked with the [Neptune logging client][neptune-client-scale].\n\nWith the Query API, you can:\n\n- List experiments, runs, and attributes of a project.\n- Fetch experiment or run metadata as a data frame.\n- Define filters to fetch experiments, runs, and attributes that meet certain criteria.\n\n## Installation\n\n```bash\npip install \"neptune-query>=1.0.0,<2.0.0\"\n```\n\nSet your Neptune API token and project name as environment variables:\n\n```bash\nexport NEPTUNE_API_TOKEN=\"ApiTokenFromYourNeptuneProfile\"\n```\n\n```bash\nexport NEPTUNE_PROJECT=\"workspace-name/project-name\"\n```\n\nFor help, see [Get started][setup] in the Neptune documentation.\n\n> **Note:** You can also pass the project path to the `project` argument of any querying function.\n\n## Usage\n\n```python\nimport neptune_query as nq\n```\n\nAvailable functions:\n\n- `fetch_experiments_table()` – runs as rows and attributes as columns.\n- `fetch_metrics()` – series of float or int values, with steps as rows.\n- `fetch_series()` – for series of strings or histograms.\n- `list_attributes()` – all logged attributes of the target project's experiment runs.\n- `list_experiments()` – names of experiments in the target project.\n- `set_api_token()` – set the Neptune API token to use for the session.\n\n### Example 1: Fetch metric values\n\nTo fetch values at each step, use `fetch_metrics()`.\n\n- To filter experiments to return, use the `experiments` parameter.\n- To specify attributes to include as columns, use the `attributes` parameter.\n\n```python\nnq.fetch_metrics(\n experiments=[\"exp_dczjz\"],\n attributes=r\"metrics/val_.+_estimated$\",\n)\n```\n\n```pycon\n metrics/val_accuracy_estimated metrics/val_loss_estimated\nexperiment step\nexp_dczjz 1.0 0.432187 0.823375\n 2.0 0.649685 0.971732\n 3.0 0.760142 0.154741\n 4.0 0.719508 0.504652\n```\n\n### Example 2: Fetch metadata as one row per run\n\nTo fetch experiment metadata from your project, use the `fetch_experiments_table()` function:\n\n```python\nnq.fetch_experiments_table(\n experiments=r\"^exp_\",\n attributes=[\"metrics/train_accuracy\", \"metrics/train_loss\", \"learning_rate\"],\n)\n```\n\n```pycon\n metrics/train_accuracy metrics/train_loss learning_rate\nexperiment\nexp_ergwq 0.278149 0.336344 0.01\nexp_qgguv 0.160260 0.790268 0.02\nexp_hstrj 0.365521 0.459901 0.01\n```\n\n> For series attributes, the value of the last logged step is returned.\n\n---\n\n## License\n\nThis project is licensed under the Apache License Version 2.0. For details, see [Apache License Version 2.0][license].\n\n\n[setup]: https://docs.neptune.ai/setup\n\n[neptune-client-scale]: https://github.com/neptune-ai/neptune-client-scale\n\n[license]: http://www.apache.org/licenses/LICENSE-2.0\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Neptune Fetcher",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://docs.neptune.ai/",
"Homepage": "https://neptune.ai/",
"Repository": "https://github.com/neptune-ai/neptune-fetcher",
"Tracker": "https://github.com/neptune-ai/neptune-fetcher/issues"
},
"split_keywords": [
"mlops",
" ml experiment tracking",
" ml model registry",
" ml model store",
" ml metadata store"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "89a67a154c8dafc48bc873a35af6b1933d02ce7a6f54aa8a1bb25923bd0720cd",
"md5": "d47373fcba19a637c459ae8b8822a2ac",
"sha256": "d4e4a7520df3564bd4bd5bd23b735fecf4721cb7c68951914ac11c8f2ed6c6e2"
},
"downloads": -1,
"filename": "neptune_query-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d47373fcba19a637c459ae8b8822a2ac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 80928,
"upload_time": "2025-07-17T13:30:21",
"upload_time_iso_8601": "2025-07-17T13:30:21.746569Z",
"url": "https://files.pythonhosted.org/packages/89/a6/7a154c8dafc48bc873a35af6b1933d02ce7a6f54aa8a1bb25923bd0720cd/neptune_query-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8cc09f074ecd3d565228c2149cc41a5b2f0d403ac82065c2a80bbd251149a8d3",
"md5": "1dbea29534673233115c9c2e15c8477b",
"sha256": "7c30711e5af7cef9794fa3df3467b9885e6a5c53b24d25958f457f5c47c88dff"
},
"downloads": -1,
"filename": "neptune_query-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "1dbea29534673233115c9c2e15c8477b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 49554,
"upload_time": "2025-07-17T13:30:22",
"upload_time_iso_8601": "2025-07-17T13:30:22.732003Z",
"url": "https://files.pythonhosted.org/packages/8c/c0/9f074ecd3d565228c2149cc41a5b2f0d403ac82065c2a80bbd251149a8d3/neptune_query-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 13:30:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "neptune-ai",
"github_project": "neptune-fetcher",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "neptune-query"
}
JSON
