# 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.5.1,<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 [Query metadata: Setup][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:
- `download_files()` – download files from the specified experiments.
- `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.
- (experimental) `fetch_metric_buckets()` – get summary values split by X-axis buckets.
For details, see the [API reference][api-reference].
> To use the corresponding methods for runs, import the Runs API:
>
> ```python
> import neptune_query.runs as nq_runs
> ```
>
> You can use these methods to target individual runs by ID instead of experiment runs by name.
### 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.
## Documentation
- [How to query metadata][query-metadata]
- [API reference][api-reference]
---
## License
This project is licensed under the Apache License Version 2.0. For details, see [Apache License Version 2.0][license].
[api-reference]: https://docs.neptune.ai/api_overview
[query-metadata]: https://docs.neptune.ai/query_metadata
[setup]: https://docs.neptune.ai/query_metadata#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/57/f3/508c95fbcc498acf461268bb6676bec594339a9b6ecd3ebc287e0acbf979/neptune_query-1.7.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.5.1,<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 [Query metadata: Setup][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- `download_files()` – download files from the specified experiments.\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- (experimental) `fetch_metric_buckets()` – get summary values split by X-axis buckets.\n\nFor details, see the [API reference][api-reference].\n\n> To use the corresponding methods for runs, import the Runs API:\n>\n> ```python\n> import neptune_query.runs as nq_runs\n> ```\n>\n> You can use these methods to target individual runs by ID instead of experiment runs by name.\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## Documentation\n\n- [How to query metadata][query-metadata]\n- [API reference][api-reference]\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[api-reference]: https://docs.neptune.ai/api_overview\n[query-metadata]: https://docs.neptune.ai/query_metadata\n[setup]: https://docs.neptune.ai/query_metadata#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 Query is a Python library for retrieving data from Neptune.",
"version": "1.7.0",
"project_urls": {
"Documentation": "https://docs.neptune.ai/",
"Homepage": "https://neptune.ai/",
"Repository": "https://github.com/neptune-ai/neptune-query",
"Tracker": "https://github.com/neptune-ai/neptune-query/issues"
},
"split_keywords": [
"mlops",
" ml experiment tracking",
" ml model registry",
" ml model store",
" ml metadata store"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "25003a3323089d7560a1a99afec66f74fbe3a2fc3eb5c57a243e0bdc5d5a2a36",
"md5": "3e07bb67f63edbf632589f479a0b8b1f",
"sha256": "f76024df6bcd3de072cc55161dcf0a1aa7a01db50c8ff4da2576aeb72aa7f782"
},
"downloads": -1,
"filename": "neptune_query-1.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3e07bb67f63edbf632589f479a0b8b1f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 100393,
"upload_time": "2025-10-09T14:18:54",
"upload_time_iso_8601": "2025-10-09T14:18:54.846654Z",
"url": "https://files.pythonhosted.org/packages/25/00/3a3323089d7560a1a99afec66f74fbe3a2fc3eb5c57a243e0bdc5d5a2a36/neptune_query-1.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "57f3508c95fbcc498acf461268bb6676bec594339a9b6ecd3ebc287e0acbf979",
"md5": "b35b21664fc3a66e18362ee62b6254bc",
"sha256": "e7770ac8bb289868a66589a56c49a62452eb52065632cde44208775dd6d9d5d0"
},
"downloads": -1,
"filename": "neptune_query-1.7.0.tar.gz",
"has_sig": false,
"md5_digest": "b35b21664fc3a66e18362ee62b6254bc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 61896,
"upload_time": "2025-10-09T14:18:56",
"upload_time_iso_8601": "2025-10-09T14:18:56.007548Z",
"url": "https://files.pythonhosted.org/packages/57/f3/508c95fbcc498acf461268bb6676bec594339a9b6ecd3ebc287e0acbf979/neptune_query-1.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-09 14:18:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "neptune-ai",
"github_project": "neptune-query",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "neptune-query"
}
JSON
