Microsoft Sentinel
Cloud and workloadsCustom Graphs Overview
In brief
The guidance now states that interactive-session graphs are temporary, on-demand graph jobs materialize graphs for 30 days before deletion, and custom graph activity is billed under the Microsoft Sentinel graph meter. It also updates terminology, examples, and links.
What Defender admins need to know
Administrators should account for the documented 30-day retention period and graph-related charges when planning investigations and scheduled jobs. No action is required.
Summaries are generated from the documentation change itself.
Documentation change
View on Microsoft LearnThe comparison below shows only the changed extract. Use the full-page view for complete context.
#customer intent: As a security researcher, I want to create custom graphs in my tenant so that I can continuously monitor and detect systemic threats.
Common scenarios
These scenarios representshow a sample of what’s possible with custom graphs. You can model any entities, relationships, and data from the Sentinel data lake, enablinglake. Build graphs tailored to your specific security workflows and investigative needs.
| Scenario | Key questions that graph can help answer |
|---|
Use the Jupyter notebooks in Microsoft Visual Studio Code to interactively create and analyze custom graphs with your data in the Microsoft Sentinel data lake. The notebooks are provided by the Microsoft Sentinel Visual Studio Code extension that allows you to interact with the Microsoft Sentinel data lake using Python for Spark (PySpark). For more information on the Microsoft Sentinel Visual Studio Code extension, see Install Visual Studio Code and the Microsoft Sentinel extension.
You can author custom graphs using either AI‑assisted graph authoring or by writing your own code usingcode. Use the Microsoft Sentinel graph provider reference to define the nodes and edges in your graph model (nodes and edges),model, transform your data from the Sentinel data lake, and usequery your graphs with Graph Query Language (GQL) to query and analyze your graphs.. For more information, see AI-assisted custom graph authoring in Microsoft Sentinel, Microsoft Sentinel graph provider reference and Graph Query Language (GQL) reference for Sentinel custom graph.
OnceAfter you author the graph code in a notebook, your can run the notebook in an interactive session or schedulepublish a graph job. Graphs created during thean interactive notebook session are ephemeraltemporary and are available only in the context of the notebookthat session. To materialize your graph and share with your team, schedule aAn on-demand graph job to rebuild your graph frequently. Once materialized,materializes the graph is accessible from:for 30 days and then deletes it. A scheduled graph job rebuilds the graph on the refresh schedule you configure. You can access a materialized graph from the graph experience under Microsoft Sentinel in Microsoftthe Defender portal under Sentinel,portal, Visual Studio Code Notebooks,notebooks, and Graphgraph query APIs.
Creating and querying custom graphs is billed under the Microsoft Sentinel graph meter. For more information, see Graph charges.
The following table summarizes the steps to build custom graphs in Microsoft Sentinel:
| Step | Description |
|---|---|
| 1. Create and investigate a graph in an interactive notebook session | - Jupyter notebooks in Microsoft Sentinel provide an interactive environment for exploring and analyzing data in the Microsoft Sentinel - The Microsoft Sentinel extension includes sentinel_graph Python library.- Use - sentinel_graph library |
| 2. Schedule a graph job to materialize your graph | - Materialize your graph in your tenant for continued access and collaboration. - Use Sentinel jobs to tailor how often you want to refresh a materialized graph with Lake data. - Query and visualize materialized graphs in graph experience in Microsoft Sentinel. |
| 3. Run advanced graph algorithms | - Use Jupyter notebooks for accessing built-in support for GraphFrames analytics and graph traversal functions. - Use purpose-built Sentinel graph algorithms for common security use cases. |
Visualizing graphs in Microsoft Sentinel
Microsoft Sentinel provides multiple options for visualizing graphs, including the graphs experience Microsoft Sentinel, Jupyter notebooks in the Sentinel Visual Studio Code extension. The graph experience lets you run Graph Query Language (GQL) queries, view the graph schema,schema (the defined node and edge types), visualize the graph, view graph results in tabular format, and interactively traverse the graph to the next hop with a simple click.
:::image type="content" source="./media/custom-graphs-overview/graph-exploration-phishing-query.png" alt-text="Screenshot of the Sentinel graph in Microsoft Sentinel showing a graph visualization." lightbox="./media/custom-graphs-overview/graph-exploration-phishing-query.png":::
@@ -4,12 +4,12 @@ description: Learn how custom graphs in Microsoft Sentinel help you model connec ms.author: edbaynash author: EdB-MSFT ms.reviewer: sourinpaul-ms.date: 06/12/2026+ms.date: 08/07/2026 ms.topic: how-to ms.service: microsoft-sentinel ms.subservice: sentinel-platform ai-usage: ai-assisted-ms.custom: msecd-doc-authoring-1014+ms.custom: msecd-doc-authoring-1015 #customer intent: As a security researcher, I want to create custom graphs in my tenant so that I can continuously monitor and detect systemic threats. @@ -21,7 +21,7 @@ Custom graphs let you build tailored security graphs tuned to your unique securi ## Common scenarios -These scenarios represent a sample of what’s possible with custom graphs. You can model any entities, relationships, and data from the Sentinel data lake, enabling graphs tailored to your specific security workflows and investigative needs.+These scenarios show a sample of what’s possible with custom graphs. You can model any entities, relationships, and data from the Sentinel data lake. Build graphs tailored to your security workflows and investigative needs. | Scenario |Key questions that graph can help answer | |----------|---------------|@@ -35,15 +35,17 @@ These scenarios represent a sample of what’s possible with custom graphs. You Use the Jupyter notebooks in Microsoft Visual Studio Code to interactively create and analyze custom graphs with your data in the Microsoft Sentinel data lake. The notebooks are provided by the Microsoft Sentinel Visual Studio Code extension that allows you to interact with the Microsoft Sentinel data lake using Python for Spark (PySpark). For more information on the Microsoft Sentinel Visual Studio Code extension, see [Install Visual Studio Code and the Microsoft Sentinel extension](./notebooks.md#install-visual-studio-code-and-the-microsoft-sentinel-extension). -You can author custom graphs using either AI‑assisted graph authoring or by writing your own code using the Microsoft Sentinel graph provider reference to define your graph model (nodes and edges), transform your data from the Sentinel data lake, and use Graph Query Language (GQL) to query and analyze your graphs. For more information, see [AI-assisted custom graph authoring in Microsoft Sentinel](./create-graphs-with-ai.md), [Microsoft Sentinel graph provider reference](./sentinel-graph-provider-reference.md) and [Graph Query Language (GQL) reference for Sentinel custom graph](./gql-reference-for-sentinel-custom-graph.md).+You can author custom graphs using either AI‑assisted graph authoring or by writing your own code. Use the Microsoft Sentinel graph provider reference to define the nodes and edges in your graph model, transform your data from the Sentinel data lake, and query your graphs with Graph Query Language (GQL). For more information, see [AI-assisted custom graph authoring in Microsoft Sentinel](./create-graphs-with-ai.md), [Microsoft Sentinel graph provider reference](./sentinel-graph-provider-reference.md) and [Graph Query Language (GQL) reference for Sentinel custom graph](./gql-reference-for-sentinel-custom-graph.md). -Once you author the graph code in notebook, your can run the notebook in an interactive session or schedule a graph job. Graphs created during the interactive notebook session are ephemeral and are available only in the context of the notebook session. To materialize your graph and share with your team, schedule a graph job to rebuild your graph frequently. Once materialized, the graph is accessible from: the graph experience in Microsoft Defender portal under Sentinel, Visual Studio Code Notebooks, and Graph query APIs.+After you author the graph code in a notebook, run the notebook in an interactive session or publish a graph job. Graphs created during an interactive notebook session are temporary and available only in that session. An on-demand graph job materializes the graph for 30 days and then deletes it. A scheduled graph job rebuilds the graph on the refresh schedule you configure. You can access a materialized graph from the graph experience under Microsoft Sentinel in the Defender portal, Visual Studio Code notebooks, and graph query APIs.++Creating and querying custom graphs is billed under the Microsoft Sentinel graph meter. For more information, see [Graph charges](../billing.md#graph-charges). The following table summarizes the steps to build custom graphs in Microsoft Sentinel: | Step | Description | |------|-------------|-| **1. Create and investigate a graph in interactive notebook session** | - Jupyter notebooks in Sentinel provide an interactive environment for exploring and analyzing data in Sentinel Lake.<br>- The Microsoft Sentinel extension includes a graph builder Python library.<br>- Use the Jupyter notebook in Sentinel to define nodes and edges with Lake data, and create graphs.<br>- The graph builder library allows you to query a graph using Graph Query Language (GQL) in the Jupyter graph notebook. |+| **1. Create and investigate a graph in an interactive notebook session** | - Jupyter notebooks in Microsoft Sentinel provide an interactive environment for exploring and analyzing data in the Microsoft Sentinel data lake.<br>- The Microsoft Sentinel extension includes the `sentinel_graph` Python library.<br>- Use a Jupyter notebook to define nodes and edges with data from the Microsoft Sentinel data lake and create graphs.<br>- Use the `sentinel_graph` library to query a graph with Graph Query Language (GQL). | | **2. Schedule a graph job to materialize your graph** |- Materialize your graph in your tenant for continued access and collaboration.<br>- Use Sentinel jobs to tailor how often you want to refresh a materialized graph with Lake data.<br>- Query and visualize materialized graphs in graph experience in Microsoft Sentinel.| | **3. Run advanced graph algorithms** |- Use Jupyter notebooks for accessing built-in support for GraphFrames analytics and graph traversal functions.<br>- Use purpose-built Sentinel graph algorithms for common security use cases.| @@ -51,7 +53,7 @@ For detailed instructions on how to build custom graphs in Microsoft Sentinel, s ## Visualizing graphs in Microsoft Sentinel -Microsoft Sentinel provides multiple options for visualizing graphs, including the graphs experience Microsoft Sentinel, Jupyter notebooks in the Sentinel Visual Studio Code extension. The graph experience lets you run Graph Query Language (GQL) queries, view the graph schema, visualize the graph, view graph results in tabular format, and interactively traverse the graph to the next hop with a simple click. +Microsoft Sentinel provides multiple options for visualizing graphs, including the graphs experience Microsoft Sentinel, Jupyter notebooks in the Sentinel Visual Studio Code extension. The graph experience lets you run Graph Query Language (GQL) queries, view the graph schema (the defined node and edge types), visualize the graph, view graph results in tabular format, and interactively traverse the graph to the next hop with a simple click. :::image type="content" source="./media/custom-graphs-overview/graph-exploration-phishing-query.png" alt-text="Screenshot of the Sentinel graph in Microsoft Sentinel showing a graph visualization." lightbox="./media/custom-graphs-overview/graph-exploration-phishing-query.png":::