Dagster GraphQL

1.12.22 · active · verified Thu Apr 09

dagster-graphql is the Python client library for interacting with Dagster's GraphQL API. It provides programmatic access to query metadata about Dagster runs, jobs, ops, assets, and to launch or terminate job executions. This library is a core component of the Dagster ecosystem, enabling automation, custom UIs, and integrations. It is currently at version 1.12.22 and maintains an active release cadence with frequent updates and bug fixes.

Warnings

breaking Python 3.9 support has been dropped. The minimum supported Python version for `dagster-graphql` (and Dagster core) is now 3.10. Users on Python 3.9 must upgrade their Python environment.
Fix: Upgrade Python environment to 3.10 or newer (up to 3.14).
deprecated The `reload_repository_location` API method in `DagsterGraphQLClient` is slated for removal in Dagster version 2.0.
Fix: Review your code for usage of `client.reload_repository_location` and consult Dagster documentation for alternatives as version 2.0 approaches.
gotcha The `dagster-graphql` package currently includes the entire `dagster` package and its sub-dependencies, which can lead to a large number of transitive dependencies. This might cause dependency clashes in complex environments or when integrating into lightweight applications.
Fix: Be mindful of your dependency tree. If clashes occur, consider isolating environments (e.g., using virtual environments) or manually crafting GraphQL requests if the `DagsterGraphQLClient`'s convenience is outweighed by dependency issues. The core GraphQL API can be interacted with directly using any HTTP client.
gotcha The Dagster GraphQL API is still evolving, and certain parts (especially those primarily for internal use by the Dagster webserver) are subject to breaking changes.
Fix: Always refer to the official Dagster release notes and GraphQL API documentation before upgrading to anticipate and address potential breaking changes, especially if relying on less commonly used API endpoints.
gotcha When querying logs for a run or events, the GraphQL API applies a default limit of 1000 items. To retrieve all logs, you must use the `cursor` field in the response to paginate through subsequent results.
Fix: Implement pagination logic using the `cursor` field when querying `logsForRun` or `eventConnection` resolvers to ensure complete data retrieval.
gotcha To reliably fetch job configuration schemas, use the `runConfigSchemaOrError` query rather than trying to extract `runConfigYaml` from `runsOrError`. Old runs or pruned data may result in `runConfigYaml` being empty or omitted, making it unreliable for reconstructing job configurations.
Fix: For fetching a job's default or current configuration schema, query `runConfigSchemaOrError` directly against the job definition. For past run configurations, be aware of data retention policies.

Install

pip install dagster-graphql Install latest version

Imports

DagsterGraphQLClient
```
from dagster_graphql import DagsterGraphQLClient
```
This is the primary client for programmatic interaction with the Dagster GraphQL API.

Quickstart

This quickstart demonstrates how to initialize the `DagsterGraphQLClient` and execute a raw GraphQL query to fetch recent Dagster runs. For Dagster Cloud, you would configure the client with your deployment URL and a user token. Ensure a Dagster instance (e.g., via `dagster dev`) is running and accessible at the specified host and port for the local example.

import os
from dagster_graphql import DagsterGraphQLClient

# Configure client for local Dagster instance or Dagster Cloud
# For local: DagsterGraphQLClient("localhost", port_number=3000)
# For Dagster Cloud:
# url = os.environ.get("DAGSTER_CLOUD_URL", "YOUR_ORG.dagster.cloud/prod")
# token = os.environ.get("DAGSTER_CLOUD_API_TOKEN", "YOUR_TOKEN")

# Example for a local Dagster instance (run 'dagster dev' first)
client = DagsterGraphQLClient("localhost", port_number=3000)

try:
    # Example: Get a list of recent runs
    runs_query = """
    query LatestRuns {
        runsOrError {
            __typename
            ... on Runs {
                results {
                    id
                    status
                    pipelineName
                }
            }
            ... on PythonError {
                message
            }
        }
    }
    """
    result = client._execute(runs_query) # _execute is used for raw GraphQL queries

    if result and result.get("runsOrError", {}).get("__typename") == "Runs":
        print("Recent Dagster Runs:")
        for run in result["runsOrError"]["results"]:
            print(f"  ID: {run['id']}, Status: {run['status']}, Job: {run['pipelineName']}")
    elif result and result.get("runsOrError", {}).get("__typename") == "PythonError":
        print(f"Error fetching runs: {result['runsOrError']['message']}")
    else:
        print(f"Unexpected result: {result}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →