Skip to content

Commit c544936

Browse files
learn-build-service-prod[bot]learn-build-service-prod[bot]
authored
Merge pull request #13873 from MicrosoftDocs/main
Auto Publish – main to live - 2026-04-12 11:00 UTC
2 parents d815aaa + fe31a63 commit c544936

8 files changed

Lines changed: 160 additions & 11 deletions

‎docs/graph/design-graph-schema.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
title: Design a Graph Schema for Graph in Microsoft Fabric
3+
description: Learn best practices for designing a graph schema in Microsoft Fabric, including how to choose node types, edge types, key columns, and properties.
4+
ms.date: 04/10/2026
5+
ms.topic: how-to
6+
ms.reviewer: wangwilliam
7+
ai-usage: ai-assisted
8+
---
9+
10+
# Design a graph schema in Microsoft Fabric
11+
12+
[!INCLUDE [feature-preview](./includes/feature-preview-note.md)]
13+
14+
A graph schema is the collection of node types, edge types, and their properties that define the structure of your graph. A well-designed graph schema makes your data easier to query, maintain, and extend. This article provides best practices for turning tabular data in a lakehouse into an effective [labeled property graph](graph-data-models.md) in Microsoft Fabric.
15+
16+
Use these guidelines before you start modeling in the graph model editor. For step-by-step instructions on creating nodes and edges, see the [graph tutorial](tutorial-introduction.md). Examples in this article use the [Adventure Works sample dataset](sample-datasets.md).
17+
18+
> [!IMPORTANT]
19+
> Graph currently doesn't support schema evolution. After you model your data, the structure of nodes, edges, and properties is fixed. Structural changes, such as adding properties, modifying labels, or changing relationship types, require you to create a new graph model and reload all data. This process takes time and consumes capacity, so plan your schema thoroughly before you start modeling.
20+
21+
## Prerequisites
22+
23+
- A [Fabric workspace](../fundamentals/create-workspaces.md) with a lakehouse that contains your source tables.
24+
- Familiarity with the [graph model editor](tutorial-introduction.md).
25+
- Optional: The [Adventure Works sample dataset](sample-datasets.md) to follow the examples in this article.
26+
27+
## Understand node types and edge types
28+
29+
Before you design a schema, understand these core concepts:
30+
31+
A **node type** defines a kind of entity in your graph, such as a customer, product, or order. It consists of:
32+
33+
- A **label**, which is the name that identifies this category of node. For example, `Customer`. You use the label in queries to refer to nodes of this type.
34+
- A **mapping table**, which is the lakehouse table that provides the source data for the node type. For example, the *adventureworks_customers* table.
35+
- A **key column** that uniquely identifies each node (labeled **ID** in the graph model editor). For example, `CustomerID_K`.
36+
- **Properties**, which are columns from the table that become attributes on each node. For example, `FirstName`, `LastName`, and `EmailAddress`.
37+
38+
A **node** is an individual instance of a node type - one row in the mapping table. For example, each row in *adventureworks_customers* becomes a `Customer` node.
39+
40+
An **edge type** defines a kind of relationship between two node types. It consists of:
41+
42+
- A **label**, which is the name that identifies this category of relationship. For example, `purchases`.
43+
- A **mapping table** that contains the relationship data between the source and target nodes. For example, the *adventureworks_orders* table.
44+
- A **source node type** and a **target node type** that the edge connects. For example, `Customer` as the source and `Order` as the target.
45+
46+
An **edge** is an individual instance of an edge type - one row in the mapping table that connects two specific nodes.
47+
48+
> [!NOTE]
49+
> In the graph model editor, the **Add node** and **Add edge** buttons create node types and edge types, not individual nodes or edges.
50+
51+
## Identify entities and relationships
52+
53+
Start by identifying the *entities* (things) and *relationships* (connections) in your data. Entities become node types. Connections between entities become edge types.
54+
55+
Ask these questions about your source tables:
56+
57+
- **What are the primary entities?** Rows that represent distinct real-world things are candidates for node types. For example, customers, products, orders, and employees.
58+
- **How do these entities relate to each other?** Columns that reference rows in another table (foreign keys) suggest edge types. For example, `CustomerID_FK` in an `orders` table points to the `customers` table, which suggests modeling a `purchases` edge.
59+
- **Are there embedded entities?** A column inside a table might represent a distinct entity worth extracting into its own node type. For an example, see [Choose node types](#choose-node-types). For a step-by-step walkthrough, see [Add multiple node and edge types from one mapping table](tutorial-model-node-edge-from-same-table.md).
60+
61+
## Choose node types
62+
63+
Create a node type for each entity that you need to query or traverse independently. Use these guidelines:
64+
65+
| Make the entity a **node type** when... | Keep it as a **property** when... |
66+
| --- | --- |
67+
| You need to traverse to or through it. | It's descriptive metadata you only read, not traverse. |
68+
| Multiple entities share a relationship with it. | It's unique to the entity it belongs to. |
69+
| You need to match or group by it directly in queries. | You only filter by it as a property of another entity. |
70+
71+
**Example:** In the Adventure Works dataset, `Country` starts as a column on the `employees` table. If you need to query "which employees live in the same country?" or "which countries have the most employees?", extract `Country` into its own node type. If you only need to display an employee's country as a label, leave it as a property.
72+
73+
## Choose key columns
74+
75+
Every node type requires a key column (or compound key) that uniquely identifies each node. Choose keys carefully:
76+
77+
- **Use existing unique identifiers** from your source tables. For example, `CustomerID_K` or `ProductID_K`.
78+
- **Avoid surrogate keys that lack business meaning** unless no natural key exists. For example, prefer `CustomerID` over an auto-incrementing row number.
79+
- **Use compound keys** when a single column doesn't guarantee uniqueness. For example, a `ProductVersion` node might need both `ProductID` and `VersionNumber` as its key.
80+
- **Match data types** between key columns and the foreign key columns used in edge mappings. Mismatched types cause edge creation failures.
81+
82+
> [!TIP]
83+
> Define [node key constraints](gql-graph-types.md#set-up-node-key-constraints) to enable the query engine to perform direct lookups on key properties. This optimization speeds up queries that look up specific nodes by key.
84+
85+
## Choose edge types
86+
87+
Edge types define the relationships between node types. Each edge type connects a source node type to a target node type through a mapping table.
88+
89+
Follow these guidelines:
90+
91+
- **Use descriptive labels** that read as verbs or verb phrases. For example, `purchases`, `sells`, `livesIn`, and `belongsTo`. A well-named edge makes queries easier to read.
92+
- **Consider direction carefully.** Edges in graph are directed. Choose the direction that best represents the real-world relationship. For example, `Customer` --*purchases*--> `Order` reads more naturally than `Order` --*purchasedBy*--> `Customer`.
93+
- **Give distinct names to edge types that connect different node type pairs.** If both "employee sells order" and "customer purchases order" connect to `Order`, name them `sells` and `purchases` rather than giving both the same label. For more information, see [edge creation limitations](limitations.md#edge-creation).
94+
- **Add properties to edge types** when the relationship itself has attributes. For example, a `quantity` on a `contains` edge or an `orderDate` on a `purchases` edge.
95+
96+
> [!IMPORTANT]
97+
> The mapping table for an edge must contain columns that match the key columns of both the source and target node types in values and data type. Tables that you use to create node types can also serve as edge mapping tables if they meet this requirement.
98+
99+
## Remove unnecessary properties
100+
101+
When you create a node type from a mapping table, every column in the table becomes a property by default. Remove properties that you don't need for queries or analysis.
102+
103+
Excessive properties increase storage, slow queries, and make the graph harder to maintain. For each node type, keep only properties that are:
104+
105+
- Required for the uniqueness of the node (key columns)
106+
- Used in `WHERE` filters or `RETURN` projections in your queries
107+
- Needed for downstream analysis or visualization
108+
109+
For more information on how property count affects query performance, see [Return only the properties you need](gql-query-performance.md#return-only-the-properties-you-need).
110+
111+
## Choose data types
112+
113+
Select the most specific data type for each property. The right types improve both storage efficiency and query performance:
114+
115+
- Use `INT` or `UINT64` for numeric identifiers and counts. Numeric comparisons are faster than string comparisons.
116+
- Use `ZONED DATETIME` for timestamps instead of string-formatted dates.
117+
- Use `BOOLEAN` for true/false flags instead of string values like `"yes"` or `"no"`.
118+
119+
For the full list of supported types, see [Current limitations — Data types](limitations.md#data-types).
120+
121+
## Common tabular-to-graph patterns
122+
123+
The following table summarizes how some common tabular data structures translate to graph elements:
124+
125+
| Tabular structure | Graph result | Example |
126+
| --- | --- | --- |
127+
| **One-to-many:** Parent table + child table with foreign key | Two node types connected by an edge type. | `Customer` --*purchases*--> `Order` |
128+
| **Many-to-many:** Junction table linking two tables | Edge type between two node types. | `Vendor` --*produces*--> `Product` |
129+
| **Embedded entity:** Column representing a shared entity | Extracted node type with edge. | `Employee` --*livesIn*--> `Country` |
130+
| **Hierarchy:** Chain of parent-child tables | Node types linked by edges at each level. | `Product` --*isOfType*--> `Subcategory` --*belongsTo*--> `Category` |
131+
132+
For a step-by-step walkthrough of the embedded entity pattern, see [Add multiple node and edge types from one mapping table](tutorial-model-node-edge-from-same-table.md).
133+
134+
## Related content
135+
136+
- [Tutorial: Introduction to graph](tutorial-introduction.md)
137+
- [GQL graph types](gql-graph-types.md)
138+
- [Optimize GQL query performance](gql-query-performance.md)
139+
- [Labeled property graphs](graph-data-models.md)
140+
- [Current limitations](limitations.md)

‎docs/graph/gql-query-performance.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Optimize GQL Query Performance for graph in Microsoft Fabric
33
description: Learn how to write efficient GQL queries for graph in Microsoft Fabric. Apply filtering, traversal, and key constraint strategies to improve query performance.
44
ms.topic: how-to
5-
ms.date: 03/12/2026
5+
ms.date: 04/10/2026
66
ms.reviewer: splantikow
77
---
88

@@ -12,7 +12,7 @@ ms.reviewer: splantikow
1212

1313
This article provides guidance for writing GQL (Graph Query Language) queries that perform predictably and efficiently when working with graph in Microsoft Fabric. The recommendations are based on current platform behavior and documented constraints.
1414

15-
For hard limits on graph size, result size, and query timeout, see [Current limitations](limitations.md).
15+
For hard limits on graph size, result size, and query timeout, see [Current limitations](limitations.md). Several recommendations in this article also relate to how you design your graph schema. For more information, see [Design a graph schema](design-graph-schema.md).
1616

1717
## Filter early in patterns
1818

‎docs/graph/graph-data-models.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Learn how the Labeled Property Graph (LPG) model in graph in Micros
44
#customer intent: As a data professional, I want to understand the labeled property graph model used by graph in Microsoft Fabric so that I can effectively model my connected data.
55
ai-usage: ai-assisted
66
ms.topic: concept-article
7-
ms.date: 03/31/2026
7+
ms.date: 04/10/2026
88
ms.reviewer: wangwilliam
99
---
1010

@@ -40,10 +40,14 @@ For most customers, LPG provides the best balance of performance, usability, and
4040
- **Simplicity and intuitiveness:** Nodes and edges map closely to how people think about networks. LPG is less complex than RDF. You don't need to define ontologies or manage global identifiers.
4141
- **Properties on edges:** Model weighted, temporal, or labeled relationships on edges. This feature supports advanced analytics like recommendations and fraud detection.
4242
- **Performance and storage efficiency:** LPG-based graph databases store data compactly and enable fast traversals, even for large, complex graphs.
43-
- **Flexible schema:** Evolve your graph model as your business needs change, without rigid constraints.
43+
- **Flexible schema:** Evolve your graph model as your business needs change, without rigid constraints. Note that schema changes currently require you to create a new graph model and reload your data. For more information, see [Design a graph schema](design-graph-schema.md).
4444
- **Integration with Fabric:** Graph works with OneLake and Power BI, enabling seamless analytics and visualization.
4545

46+
For details on how node types and edge types map to lakehouse tables in Fabric, see [Understand node types and edge types](design-graph-schema.md#understand-node-types-and-edge-types).
47+
4648
## Related content
4749

50+
- [Design a graph schema](design-graph-schema.md)
51+
- [Tutorial: Introduction to graph](tutorial-introduction.md)
4852
- [Try Microsoft Fabric for free](../fundamentals/fabric-trial.md)
4953
- [End-to-end tutorials in Microsoft Fabric](../fundamentals/end-to-end-tutorials.md)

‎docs/graph/how-graph-works.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: How graph in Microsoft Fabric works
33
description: Learn how data flows through graph in Microsoft Fabric, from data ingestion and storage in OneLake to graph modeling, querying, and returning results.
44
#customer intent: As a data analyst or engineer, I want to understand how graph in Microsoft Fabric processes and queries data so that I can evaluate whether it fits my analytical needs.
55
ms.topic: concept-article
6-
ms.date: 03/31/2026
6+
ms.date: 04/10/2026
77
ms.reviewer: wangwilliam
88
ai-usage: ai-assisted
99
---
@@ -40,7 +40,7 @@ In the graph modeling step, you define the graph schema by specifying:
4040
- **Edge types:** Relationships between entities, such as "purchases," "contains," or "produces."
4141
- **Table mappings:** How node and edge definitions map to the underlying source tables.
4242

43-
This step creates the [labeled property graph](graph-data-models.md) structure. Complete graph modeling before you query the graph.
43+
This step creates the [labeled property graph](graph-data-models.md) structure. Complete graph modeling before you query the graph. For guidance on making these modeling decisions, see [Design a graph schema](design-graph-schema.md).
4444

4545
> [!NOTE]
4646
> Graph currently doesn't support schema evolution. If you need to make structural changes—such as adding new properties, modifying labels, or changing relationship types—reingest the updated source data into a new model.

‎docs/graph/overview.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: What is graph in Microsoft Fabric?
33
description: Learn about the core purpose, architecture, and benefits of graph in Microsoft Fabric, including integration and feature highlights.
44
ms.topic: overview
5-
ms.date: 03/26/2026
5+
ms.date: 04/10/2026
66
ms.reviewer: wangwilliam
77
ms.custom: references_regions
88
ms.search.form: graph overview
@@ -45,7 +45,7 @@ By using graph, you can:
4545
- Create a labeled property graph over structured data in OneLake by defining its nodes and edges in terms of underlying tabular data. To learn how to load and refresh source data, see [Manage and refresh data](manage-data.md).
4646

4747
> [!IMPORTANT]
48-
> Graph currently doesn't support schema evolution. After you ingest and model your data, the structure of nodes, relationships, and properties is fixed. If you need to make structural changes - such as adding new properties, modifying labels, or changing relationship types - you must reingest the updated source data into a new model.
48+
> Graph currently doesn't support schema evolution. After you ingest and model your data, the structure of nodes, relationships, and properties is fixed. If you need to make structural changes - such as adding new properties, modifying labels, or changing relationship types - you must reingest the updated source data into a new model. For guidance on planning your schema, see [Design a graph schema](design-graph-schema.md).
4949
5050
- Query by using GQL (Graph Query Language), including pattern matching, path constructs, aggregations, and other features as they're released. The official International Standard for GQL is [ISO/IEC 39075 Information technology — Database languages — GQL](https://www.iso.org/standard/76120.html).
5151

‎docs/graph/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ items:
4343
href: security-overview.md
4444
- name: How-tos
4545
items:
46+
- name: Design a graph schema
47+
href: design-graph-schema.md
4648
- name: Share and manage permissions
4749
href: share-graph-manage-permissions.md
4850
- name: Manage data

‎docs/graph/tutorial-model-node-edge-from-same-table.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: "Tutorial: Create Node and Edge Types from One Mapping Table"
33
description: Learn how to create multiple node types and edge types from a single mapping table in your graph model in Microsoft Fabric.
44
ms.topic: tutorial
5-
ms.date: 03/24/2026
5+
ms.date: 04/10/2026
66
ms.reviewer: wangwilliam
77
ms.search.form: Tutorial - Add nodes and edges from one mapping table
88
ai-usage: ai-assisted
@@ -115,6 +115,9 @@ In this tutorial step, you derived two node types and one edge type from the sin
115115

116116
This pattern is useful whenever a relational table contains embedded entities that you want to represent as separate nodes in your graph. Look for columns that represent distinct real-world entities, such as countries, cities, or departments, as candidates for extraction into their own node types.
117117

118+
> [!TIP]
119+
> For more modeling patterns and decision guidance, see [Design a graph schema](design-graph-schema.md).
120+
118121
## Next step
119122

120123
> [!div class="nextstepaction"]

‎docs/graph/tutorial-model-nodes.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: "Tutorial: Add node types to your graph"
33
description: Learn how to add node types to your graph model in Microsoft Fabric by mapping source tables and configuring node properties.
44
ms.topic: tutorial
5-
ms.date: 03/24/2026
5+
ms.date: 04/10/2026
66
ms.reviewer: wangwilliam
77
ms.search.form: Tutorial - Add nodes to your graph
88
ai-usage: ai-assisted
@@ -44,7 +44,7 @@ To add node types to your graph, follow these steps:
4444
- **ID** of the mapping column: `CustomerID_K`
4545

4646
> [!TIP]
47-
> You can set compound keys (IDs consisting of multiple columns).
47+
> You can set compound keys (IDs consisting of multiple columns). After you select a mapping table, choose one ID from the **ID** dropdown, then use the dropdown again to add another.
4848
4949
1. Select **Confirm** to add the node type to your graph.
5050
1. Repeat the process for all remaining node types listed in the [Adventure Works node mappings](#adventure-works-node-mappings) table.

0 commit comments

Comments
 (0)