{"id":5340,"library":"neptune-query","title":"Neptune Query","description":"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.","status":"active","version":"1.14.1","language":"en","source_language":"en","source_url":"https://github.com/neptune-ai/neptune-query","tags":["mlops","data-science","experiment-tracking","neptune","metadata","query"],"install":[{"cmd":"pip install neptune-query","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python versions 3.10 to 3.12 (exclusive).","package":"python","optional":false}],"imports":[{"note":"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.","wrong":"import neptune_query.api as nq","symbol":"neptune_query","correct":"import neptune_query as nq"},{"note":"For functions specifically targeting individual Neptune runs by ID, import the `runs` submodule.","symbol":"neptune_query.runs","correct":"import neptune_query.runs as nq_runs"}],"quickstart":{"code":"import os\nimport neptune_query as nq\nimport pandas as pd\n\n# Set your Neptune API token and project name as environment variables.\n# Example: export NEPTUNE_API_TOKEN=\"YOUR_API_TOKEN\"\n# Example: export NEPTUNE_PROJECT=\"workspace-name/project-name\"\n\n# Ensure environment variables are set or pass them explicitly\nneptune_api_token = os.environ.get('NEPTUNE_API_TOKEN', 'YOUR_API_TOKEN_HERE')\nneptune_project = os.environ.get('NEPTUNE_PROJECT', 'your_workspace/your_project')\n\nif neptune_api_token == 'YOUR_API_TOKEN_HERE' or neptune_project == 'your_workspace/your_project':\n    print(\"Warning: Please set NEPTUNE_API_TOKEN and NEPTUNE_PROJECT environment variables or provide them explicitly.\")\n    # For demonstration, we'll skip further execution if credentials aren't set.\n    # In a real application, handle this appropriately (e.g., raise an error, prompt user).\n    exit()\n\n# Set the API token for the session (optional if NEPTUNE_API_TOKEN env var is set)\nnq.set_api_token(api_token=neptune_api_token)\n\n# List experiments in a project\nprint(f\"Listing experiments in project: {neptune_project}\")\nexperiment_names = nq.list_experiments(project=neptune_project)\nprint(f\"Found {len(experiment_names)} experiments: {experiment_names[:5]}...\")\n\n# Fetch a table of experiments with specific attributes\n# Fetch runs as rows and attributes as columns\ntable_df: pd.DataFrame = nq.fetch_experiments_table(\n    project=neptune_project,\n    columns=['sys/name', 'sys/creation_time', 'params/*', 'metrics/loss']\n)\n\nprint(\"\\nFetched experiments table (first 5 rows):\\n\")\nprint(table_df.head())\n\n# Fetch a specific metric series for an experiment\nif not table_df.empty:\n    first_experiment_name = table_df.iloc[0]['sys/name']\n    print(f\"\\nFetching 'metrics/loss' for experiment: {first_experiment_name}\")\n    metric_series_df = nq.fetch_metrics(\n        experiments=[first_experiment_name],\n        attributes=['metrics/loss']\n    )\n    print(\"\\nFetched metric series (first 5 rows):\\n\")\n    print(metric_series_df.head())","lang":"python","description":"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."},"warnings":[{"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).","message":"This 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"In 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.","severity":"breaking","affected_versions":">=1.10.0"},{"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.","message":"Authentication 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The 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.","severity":"deprecated","affected_versions":"All versions (migration from older clients)"},{"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.","message":"Some 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.","severity":"gotcha","affected_versions":">=1.8.0 (where these functions were introduced)"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}