Registry / ai-ml / neptune-query

neptune-query

JSON →
library1.14.1pypypi✓ verified 27d ago

Neptune Query is a Python library (current version 1.14.1) for retrieving logged metadata from the Neptune MLOps platform. It provides a read-only API to programmatically fetch experiments, runs, and their associated attributes, often as Pandas DataFrames. The library is actively maintained with frequent minor and patch releases, offering a stable interface for data retrieval and analysis.

pip install neptune-query
INSTALL
IMPORT
SIG · NEPTUNE-QUERY
N
neptune-query
ai-mlpythonv1.14.1
Install
11.2s avg
Import
2274ms
Disk
203MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v1.14.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 2.472s · 201.4MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 11.2s · import 2.076s · 194MB
203MB installed
● package 203MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

neptune_query
✓ import neptune_query as nq
✗ import neptune_query.api as nq
The primary functions are exposed directly under the top-level `neptune_query` module, commonly aliased as `nq`. There is no `neptune_query.api` module for core functionality.
neptune_query.runs
✓ import neptune_query.runs as nq_runs
For functions specifically targeting individual Neptune runs by ID, import the `runs` submodule.

This quickstart demonstrates how to authenticate with Neptune.ai, list experiments within a specified project, fetch experiment metadata as a DataFrame using `fetch_experiments_table`, and retrieve a specific metric series using `fetch_metrics`. It highlights the use of environment variables for credentials and explicit `project` arguments. Make sure to replace placeholder values or set your `NEPTUNE_API_TOKEN` and `NEPTUNE_PROJECT` environment variables before running.

import os import neptune_query as nq import pandas as pd # Set your Neptune API token and project name as environment variables. # Example: export NEPTUNE_API_TOKEN="YOUR_API_TOKEN" # Example: export NEPTUNE_PROJECT="workspace-name/project-name" # Ensure environment variables are set or pass them explicitly neptune_api_token = os.environ.get('NEPTUNE_API_TOKEN', 'YOUR_API_TOKEN_HERE') neptune_project = os.environ.get('NEPTUNE_PROJECT', 'your_workspace/your_project') if neptune_api_token == 'YOUR_API_TOKEN_HERE' or neptune_project == 'your_workspace/your_project': print("Warning: Please set NEPTUNE_API_TOKEN and NEPTUNE_PROJECT environment variables or provide them explicitly.") # For demonstration, we'll skip further execution if credentials aren't set. # In a real application, handle this appropriately (e.g., raise an error, prompt user). exit() # Set the API token for the session (optional if NEPTUNE_API_TOKEN env var is set) nq.set_api_token(api_token=neptune_api_token) # List experiments in a project print(f"Listing experiments in project: {neptune_project}") experiment_names = nq.list_experiments(project=neptune_project) print(f"Found {len(experiment_names)} experiments: {experiment_names[:5]}...") # Fetch a table of experiments with specific attributes # Fetch runs as rows and attributes as columns table_df: pd.DataFrame = nq.fetch_experiments_table( project=neptune_project, columns=['sys/name', 'sys/creation_time', 'params/*', 'metrics/loss'] ) print("\nFetched experiments table (first 5 rows):\n") print(table_df.head()) # Fetch a specific metric series for an experiment if not table_df.empty: first_experiment_name = table_df.iloc[0]['sys/name'] print(f"\nFetching 'metrics/loss' for experiment: {first_experiment_name}") metric_series_df = nq.fetch_metrics( experiments=[first_experiment_name], attributes=['metrics/loss'] ) print("\nFetched metric series (first 5 rows):\n") print(metric_series_df.head())
Debug
Known issues
gotchaThis library (`neptune-query`) is for interacting with the neptune.ai MLOps platform, not Amazon Neptune (AWS's graph database service). There is common confusion due to the name overlap. Ensure you are using the correct library for your intended platform.
fix
Verify your project is hosted on neptune.ai if you intend to use this library. If you are working with Amazon Neptune, refer to AWS SDKs (e.g., `boto3`) and relevant graph database query languages (Gremlin, openCypher, SPARQL).
affects: All versions
breakingIn version 1.10.0, the external dependency on `neptune-api` was dropped. A copy of `neptune-api` (version 0.26.0) was bundled directly within `neptune-query`. This simplifies `neptune-query`'s dependency management but could break environments where users explicitly managed `neptune-api` versions in conjunction with `neptune-query` or expected a specific external `neptune-api` version to be used.
fix
Remove `neptune-api` from your project's direct dependencies if it was only used for `neptune-query`. If you used `neptune-api` directly for other purposes, ensure its bundled version (0.26.0) is compatible with your use case or adapt your code accordingly.
affects: >=1.10.0
gotchaAuthentication relies on either `NEPTUNE_API_TOKEN` and `NEPTUNE_PROJECT` environment variables or passing these values directly to functions like `set_api_token` or the `project` argument. Forgetting to set these can lead to authentication errors or operations failing silently. Ensure correct permissions for the API token.
fix
Always explicitly set `NEPTUNE_API_TOKEN` and `NEPTUNE_PROJECT` environment variables, or pass `api_token` and `project` arguments to relevant `neptune_query` functions. Double-check your API token's scope and project permissions if experiencing access issues.
affects: All versions
deprecatedThe Neptune Fetcher API (`neptune-fetcher`) is deprecated in favor of `neptune-query`. If you are migrating from older Neptune clients, you should transition to using `neptune-query` for all data retrieval tasks.
fix
Refactor your data retrieval code to use `neptune-query` functions. The `neptune-query` API is designed to be similar to `neptune_fetcher.alpha` but with improved stability and features. Consult the official `neptune.ai` documentation for migration guides.
affects: All versions (migration from older clients)
gotchaSome functions, such as `fetch_experiments_table_global()` and `fetch_runs_table_global()`, are explicitly marked as 'experimental'. Their API signatures or behavior might change in future releases, and they may not be as optimized or stable as core functions.
fix
Be aware that experimental functions might undergo changes. For production systems requiring high stability, prefer non-experimental functions. Regularly check the changelog for updates on experimental features.
affects: >=1.8.0 (where these functions were introduced)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'neptune'
The core Neptune client library, which `neptune-query` depends on, is not installed or accessible in your Python environment.
fix
Install the Neptune client library using pip: `pip install neptune`
NeptuneApiTokenNotProvided
The `neptune-query` library cannot find the API token required to authenticate with the Neptune MLOps platform. This token can be set via an environment variable (`NEPTUNE_API_TOKEN`) or passed directly during initialization.
fix
Set your Neptune API token as an environment variable (e.g., `export NEPTUNE_API_TOKEN='YOUR_API_TOKEN'`) or pass it directly when initializing the connection (e.g., `neptune.init(api_token='YOUR_API_TOKEN')`).
NeptuneConnectionLostException
The `neptune-query` client lost its connection to the Neptune MLOps server, which can be due to network issues, server downtime, or firewall restrictions.
fix
Check your internet connection, firewall settings, and the Neptune status page for any outages. If self-hosting, ensure your server is running and accessible.
AttributeError: 'str' object has no attribute 'source_instructions'
This error typically occurs when attempting to execute a Gremlin query by passing a raw string where the underlying Gremlin client expects a pre-compiled traversal object or a different query submission method.
fix
Construct your Gremlin queries using the `gremlin_python` traversal API (e.g., `g.V().has(...)`) instead of a simple string, or ensure your client is configured to accept string queries if that functionality is available.
Upgrade
Version history
1.14.1latest on PyPI · released Apr 7, 2026
Audit
Dependencies
pythonrequiredRequires Python versions 3.10 to 3.12 (exclusive).
Agent activity
21 hits · last 30 days
node
20
Resources
neptune-query — pip install neptune-query · libregistry