# Neptune Fetcher
Neptune Fetcher is a read-only API for querying metadata logged with the [Neptune Python client][neptune-client-scale]. The separation makes it safer and more efficient to fetch data from Neptune.
With the Fetcher 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.
> [!NOTE]
> _For the Python API corresponding to [Neptune 2.x][legacy-app], see [neptune-client][neptune-client]._
## Documentation
- [Fetching how-to guides][fetcher-guide]
- [Fetcher API reference][fetcher-api-ref]
- [Update your code from old Fetcher to Alpha][fetcher-migration]
## Installation
```bash
pip install -U neptune-fetcher
```
Set your Neptune API token and project name as environment variables:
```bash
export NEPTUNE_API_TOKEN="h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ=="
```
```bash
export NEPTUNE_PROJECT="workspace-name/project-name"
```
For help, see [Get started][setup] in the Neptune documentation.
> **Note:** To change the token or project, you can [set the context][set-context] directly in the code. This way, you can work with multiple projects at the same time.
## Usage
Import the `alpha` module:
```python
import neptune_fetcher.alpha as npt
```
To fetch experiment metadata from your project, use the [`fetch_experiments_table()`][fetch-exp-table] function.
- To filter experiments to return, use the `experiments` parameter.
- To specify attributes to include as columns, use the `attributes` parameter.
```python
npt.fetch_experiments_table(
experiments=["exp_ergwq", "exp_qgguv"],
attributes=["metrics/train_accuracy", "metrics/train_loss"],
)
```
```pycon
metrics/train_accuracy metrics/train_loss
last last
experiment
exp_ergwq 0.278149 0.336344
exp_qgguv 0.160260 0.790268
```
To fetch values at each step, use [`fetch_metrics()`][fetch-metrics]:
```python
npt.fetch_metrics(
experiments=r"exp.*",
attributes=r".*metric.*/val_.+",
)
```
```pycon
experiment step metrics/val_accuracy metrics/val_loss
0 exp_dczjz 0 0.432187 0.823375
1 exp_dczjz 1 0.649685 0.971732
2 exp_dczjz 2 0.760142 0.154741
3 exp_dczjz 3 0.719508 0.504652
4 exp_dczjz 4 0.180321 0.503800
5 exp_hgctc 0 0.012390 0.171790
6 exp_hgctc 1 0.392041 0.768675
7 exp_hgctc 2 None 0.847072
8 exp_hgctc 3 0.479945 0.323537
9 exp_hgctc 4 0.102646 0.055511
```
You can define detailed criteria for which experiments to search or which attributes to return.
For instructions, see the [how-to guides][fetcher-guide] in the Neptune documentation:
- [Listing project contents][project-explo]
- [Fetching metadata][fetch-data]
- [Constructing filters][construct-filters]
- [Working with runs][runs-api]
---
## Old Fetcher API
For documentation related to the previous version of the Fetcher API, see the `docs/old/` directory:
- [docs/old/usage.md](docs/old/usage.md)
- [docs/old/api_reference.md](docs/old/api_reference.md)
To update your code to the new version, see [Migrate to Fetcher Alpha][fetcher-migration] in the Neptune documentation.
---
## License
This project is licensed under the Apache License Version 2.0. For details, see [Apache License Version 2.0][license].
[fetcher-api-ref]: https://docs.neptune.ai/fetcher/attribute
[fetch-exp-table]: https://docs.neptune.ai/fetcher/fetch_experiments_table
[fetch-metrics]: https://docs.neptune.ai/fetcher/fetch_metrics
[construct-filters]: https://docs.neptune.ai/construct_fetching_filters
[fetch-data]: https://docs.neptune.ai/fetch_metadata
[fetcher-guide]: https://docs.neptune.ai/query_metadata
[fetcher-migration]: https://docs.neptune.ai/fetcher_migration
[project-explo]: https://docs.neptune.ai/list_project_contents
[runs-api]: https://docs.neptune.ai/fetcher_runs_api
[set-context]: https://docs.neptune.ai/set_fetching_context
[setup]: https://docs.neptune.ai/setup
[legacy-app]: https://app.neptune.ai/
[neptune-client]: https://github.com/neptune-ai/neptune-client
[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.9",
"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/c9/f1/3ff257560ecea1b9aea4995604de65e64715da6071dfa61d7752a10abb30/neptune_query-0.0.1a12.tar.gz",
"platform": null,
"description": "# Neptune Fetcher\n\nNeptune Fetcher is a read-only API for querying metadata logged with the [Neptune Python client][neptune-client-scale]. The separation makes it safer and more efficient to fetch data from Neptune.\n\nWith the Fetcher 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> [!NOTE]\n> _For the Python API corresponding to [Neptune 2.x][legacy-app], see [neptune-client][neptune-client]._\n\n## Documentation\n\n- [Fetching how-to guides][fetcher-guide]\n- [Fetcher API reference][fetcher-api-ref]\n- [Update your code from old Fetcher to Alpha][fetcher-migration]\n\n## Installation\n\n```bash\npip install -U neptune-fetcher\n```\n\nSet your Neptune API token and project name as environment variables:\n\n```bash\nexport NEPTUNE_API_TOKEN=\"h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ==\"\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:** To change the token or project, you can [set the context][set-context] directly in the code. This way, you can work with multiple projects at the same time.\n\n## Usage\n\nImport the `alpha` module:\n\n```python\nimport neptune_fetcher.alpha as npt\n```\n\nTo fetch experiment metadata from your project, use the [`fetch_experiments_table()`][fetch-exp-table] function.\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\nnpt.fetch_experiments_table(\n experiments=[\"exp_ergwq\", \"exp_qgguv\"],\n attributes=[\"metrics/train_accuracy\", \"metrics/train_loss\"],\n)\n```\n\n```pycon\n metrics/train_accuracy metrics/train_loss\n last last\nexperiment\nexp_ergwq 0.278149 0.336344\nexp_qgguv 0.160260 0.790268\n```\n\nTo fetch values at each step, use [`fetch_metrics()`][fetch-metrics]:\n\n```python\nnpt.fetch_metrics(\n experiments=r\"exp.*\",\n attributes=r\".*metric.*/val_.+\",\n)\n```\n\n```pycon\n experiment step metrics/val_accuracy metrics/val_loss\n0 exp_dczjz 0 0.432187 0.823375\n1 exp_dczjz 1 0.649685 0.971732\n2 exp_dczjz 2 0.760142 0.154741\n3 exp_dczjz 3 0.719508 0.504652\n4 exp_dczjz 4 0.180321 0.503800\n5 exp_hgctc 0 0.012390 0.171790\n6 exp_hgctc 1 0.392041 0.768675\n7 exp_hgctc 2 None 0.847072\n8 exp_hgctc 3 0.479945 0.323537\n9 exp_hgctc 4 0.102646 0.055511\n```\n\nYou can define detailed criteria for which experiments to search or which attributes to return.\n\nFor instructions, see the [how-to guides][fetcher-guide] in the Neptune documentation:\n\n- [Listing project contents][project-explo]\n- [Fetching metadata][fetch-data]\n- [Constructing filters][construct-filters]\n- [Working with runs][runs-api]\n\n---\n\n## Old Fetcher API\n\nFor documentation related to the previous version of the Fetcher API, see the `docs/old/` directory:\n\n- [docs/old/usage.md](docs/old/usage.md)\n- [docs/old/api_reference.md](docs/old/api_reference.md)\n\nTo update your code to the new version, see [Migrate to Fetcher Alpha][fetcher-migration] in the Neptune documentation.\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[fetcher-api-ref]: https://docs.neptune.ai/fetcher/attribute\n[fetch-exp-table]: https://docs.neptune.ai/fetcher/fetch_experiments_table\n[fetch-metrics]: https://docs.neptune.ai/fetcher/fetch_metrics\n\n[construct-filters]: https://docs.neptune.ai/construct_fetching_filters\n[fetch-data]: https://docs.neptune.ai/fetch_metadata\n[fetcher-guide]: https://docs.neptune.ai/query_metadata\n[fetcher-migration]: https://docs.neptune.ai/fetcher_migration\n[project-explo]: https://docs.neptune.ai/list_project_contents\n[runs-api]: https://docs.neptune.ai/fetcher_runs_api\n[set-context]: https://docs.neptune.ai/set_fetching_context\n[setup]: https://docs.neptune.ai/setup\n\n[legacy-app]: https://app.neptune.ai/\n[neptune-client]: https://github.com/neptune-ai/neptune-client\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": "0.0.1a12",
"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": "2477402c80ac99e6184c0c2b54363665621908d52edd4a51f2abea1a8ce80191",
"md5": "da0bbdd674186e57834c203ea0ff9507",
"sha256": "b48ea28cb347d35a0736d883374f95d3f069d4df442c4ee31d2d190593b16b4c"
},
"downloads": -1,
"filename": "neptune_query-0.0.1a12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "da0bbdd674186e57834c203ea0ff9507",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 79981,
"upload_time": "2025-07-11T13:40:23",
"upload_time_iso_8601": "2025-07-11T13:40:23.895671Z",
"url": "https://files.pythonhosted.org/packages/24/77/402c80ac99e6184c0c2b54363665621908d52edd4a51f2abea1a8ce80191/neptune_query-0.0.1a12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c9f13ff257560ecea1b9aea4995604de65e64715da6071dfa61d7752a10abb30",
"md5": "21aa9a8a29df74eecd1843d8ea1471ae",
"sha256": "2ba1dfa6db8e597e739be9e2be8a945d654cf4267aaf4c03c5ae6e17f149f7bb"
},
"downloads": -1,
"filename": "neptune_query-0.0.1a12.tar.gz",
"has_sig": false,
"md5_digest": "21aa9a8a29df74eecd1843d8ea1471ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 49229,
"upload_time": "2025-07-11T13:40:25",
"upload_time_iso_8601": "2025-07-11T13:40:25.315751Z",
"url": "https://files.pythonhosted.org/packages/c9/f1/3ff257560ecea1b9aea4995604de65e64715da6071dfa61d7752a10abb30/neptune_query-0.0.1a12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 13:40:25",
"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
