# 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.4.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:
- `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/b6/e0/c0361cd5031e591faf8376727ab9eb82417983c7aba4d2e8b2bfe6721c17/neptune_query-1.5.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.4.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- `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.5.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": "1aa14c621a4d0acc0e5ed09c5665352a75d161865a4cae21a053b3596405705d",
"md5": "9595dc741311c50f0cb1f37726bdd808",
"sha256": "ea7cf97ea8d1ae080a2d985b3b6530d4c7d4846346e164a84f6a62e22c044f94"
},
"downloads": -1,
"filename": "neptune_query-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9595dc741311c50f0cb1f37726bdd808",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 100916,
"upload_time": "2025-09-16T14:37:07",
"upload_time_iso_8601": "2025-09-16T14:37:07.085461Z",
"url": "https://files.pythonhosted.org/packages/1a/a1/4c621a4d0acc0e5ed09c5665352a75d161865a4cae21a053b3596405705d/neptune_query-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b6e0c0361cd5031e591faf8376727ab9eb82417983c7aba4d2e8b2bfe6721c17",
"md5": "b48e318568e505a503b5da5cff6829f5",
"sha256": "5c1fa76241208569ba1b2e4cbe11e61166167e06421644366afdb6e8b92b0125"
},
"downloads": -1,
"filename": "neptune_query-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "b48e318568e505a503b5da5cff6829f5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 62292,
"upload_time": "2025-09-16T14:37:08",
"upload_time_iso_8601": "2025-09-16T14:37:08.287295Z",
"url": "https://files.pythonhosted.org/packages/b6/e0/c0361cd5031e591faf8376727ab9eb82417983c7aba4d2e8b2bfe6721c17/neptune_query-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-16 14:37:08",
"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
