{"id":1977,"library":"dagster-graphql","title":"Dagster GraphQL","description":"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.","status":"active","version":"1.12.22","language":"en","source_language":"en","source_url":"https://github.com/dagster-io/dagster/tree/master/python_modules/dagster-graphql","tags":["data orchestration","graphql","dagster","api client"],"install":[{"cmd":"pip install dagster-graphql","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"dagster-graphql is part of the Dagster ecosystem and currently includes the entire 'dagster' package as a dependency, which can lead to a large dependency tree.","package":"dagster"},{"reason":"Utilized internally for GraphQL query dispatch over HTTP. Bumped to be inclusive of v4 for broader transitive dependency compatibility.","package":"gql"}],"imports":[{"note":"This is the primary client for programmatic interaction with the Dagster GraphQL API.","symbol":"DagsterGraphQLClient","correct":"from dagster_graphql import DagsterGraphQLClient"}],"quickstart":{"code":"import os\nfrom dagster_graphql import DagsterGraphQLClient\n\n# Configure client for local Dagster instance or Dagster Cloud\n# For local: DagsterGraphQLClient(\"localhost\", port_number=3000)\n# For Dagster Cloud:\n# url = os.environ.get(\"DAGSTER_CLOUD_URL\", \"YOUR_ORG.dagster.cloud/prod\")\n# token = os.environ.get(\"DAGSTER_CLOUD_API_TOKEN\", \"YOUR_TOKEN\")\n\n# Example for a local Dagster instance (run 'dagster dev' first)\nclient = DagsterGraphQLClient(\"localhost\", port_number=3000)\n\ntry:\n    # Example: Get a list of recent runs\n    runs_query = \"\"\"\n    query LatestRuns {\n        runsOrError {\n            __typename\n            ... on Runs {\n                results {\n                    id\n                    status\n                    pipelineName\n                }\n            }\n            ... on PythonError {\n                message\n            }\n        }\n    }\n    \"\"\"\n    result = client._execute(runs_query) # _execute is used for raw GraphQL queries\n\n    if result and result.get(\"runsOrError\", {}).get(\"__typename\") == \"Runs\":\n        print(\"Recent Dagster Runs:\")\n        for run in result[\"runsOrError\"][\"results\"]:\n            print(f\"  ID: {run['id']}, Status: {run['status']}, Job: {run['pipelineName']}\")\n    elif result and result.get(\"runsOrError\", {}).get(\"__typename\") == \"PythonError\":\n        print(f\"Error fetching runs: {result['runsOrError']['message']}\")\n    else:\n        print(f\"Unexpected result: {result}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python environment to 3.10 or newer (up to 3.14).","message":"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.","severity":"breaking","affected_versions":">=1.12.0"},{"fix":"Review your code for usage of `client.reload_repository_location` and consult Dagster documentation for alternatives as version 2.0 approaches.","message":"The `reload_repository_location` API method in `DagsterGraphQLClient` is slated for removal in Dagster version 2.0.","severity":"deprecated","affected_versions":"All 1.x versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement pagination logic using the `cursor` field when querying `logsForRun` or `eventConnection` resolvers to ensure complete data retrieval.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}