Repo sync for protected branch

data-explorer/kusto/access-control/role-based-access-control.md

@@ -73,11 +73,13 @@ The **Manage** column offers ways to add or remove role principals.
 | External Table    | Admin               | Full permission in the scope of a particular external table.                                                                                                         | Database User or Database Viewer   | [management commands](../management/manage-external-table-security-roles.md)                                                                  |
 | Materialized view | Admin               | Full permission to alter the view, delete the view, and grant admin permissions to another principal.                                                                | Database User or Table Admin       | [management commands](../management/manage-materialized-view-security-roles.md)                                                               |
 | Function          | Admin               | Full permission to alter the function, delete the function, and grant admin permissions to another principal.                                                        | Database User or Table Admin       | [management commands](../management/manage-function-security-roles.md)                                                                        |
+| Graph             | GraphAdmin          | Full permission in the scope of a particular graph model.                                                                                                            | Database User                      |                                                                                                                                               |
 ::: moniker-end
 
 ::: moniker range="microsoft-fabric"
-| Scope             | Role               | Permissions                                                                                                                                                          | How the role is obtained                                                                                                                                                                                                                                                                                                                           |
-| ----------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+
+| Scope | Role | Permissions | How the role is obtained |
+| ---- | ---- | ----------- | ------------------------- |
 | Eventhouse        | AllDatabasesAdmin  | Full permission to all databases in the Eventhouse. May show and alter certain Eventhouse-level policies. Includes all permissions.                                  | - Inherited as workspace **admin**, workspace **member**, or workspace **contributor**. <br> <br> Can't be assigned with management commands.                                                                                                                                                                                                             |
 | Database          | Admin              | Full permission in the scope of a particular database. Includes all lower level permissions.                                                                         | - Inherited as workspace **admin**, workspace **member**, or workspace **contributor** <br> - [Item shared](/fabric/get-started/share-items#item-permission-model) with editing permissions. <br> - Assigned with [management commands](../management/manage-database-security-roles.md)                            |
 | Database          | User               | Read all data and metadata of the database. Create tables and functions, and become the admin for those tables and functions.                                        | - Assigned with [management commands](../management/manage-database-security-roles.md)                                                                                                                                                                                                                                                               |
@@ -90,6 +92,7 @@ The **Manage** column offers ways to add or remove role principals.
 | External Table    | Admin              | Full permission in the scope of a particular external table.                                                                                                         | - Assigned with [management commands](../management/manage-external-table-security-roles.md). Dependent on having **Database User** or **Database Viewer** on the parent database.                                                                                                                                                                                                                                                          |
 | Materialized view | Admin              | Full permission to alter the view, delete the view, and grant admin permissions to another principal.                                                                | - Inherited as workspace **admin**, workspace **member**, or workspace **contributor** <br> - Parent item (KQL Database) [shared](/fabric/get-started/share-items#item-permission-model) with editing permissions. <br> - Assigned with [management commands](../management/manage-database-security-roles.md). Dependent on having **Database User** or **Table Admin** on the parent items. |
 | Function          | Admin              | Full permission to alter the function, delete the function, and grant admin permissions to another principal.                                                        | - Inherited as workspace **admin**, workspace **member**, or workspace **contributor** <br> - Parent item (KQL Database) [shared](/fabric/get-started/share-items#item-permission-model) with editing permissions. <br> - Assigned with [management commands](../management/manage-database-security-roles.md). Dependent on having **Database User** or **Table Admin** on the parent items.      |
+| Graph             | GraphAdmin          | Full permission in the scope of a particular graph model.                                                                               |    - Inherited as workspace **admin**, workspace **member**, or workspace **contributor** <br> - Parent item (KQL Database) [shared](/fabric/get-started/share-items#item-permission-model) with editing permissions. <br> - Assigned with [management commands](../management/manage-database-security-roles.md). Dependent on having **Database User** or **Table Admin** on the parent items.                                      |                                                                                                                                               |
 ::: moniker-end
 
 ## Related content

data-explorer/kusto/management/capacity-policy.md

@@ -27,6 +27,7 @@ The capacity policy is made of the following components:
 * [PurgeStorageArtifactsCleanupCapacity](#purge-storage-artifacts-cleanup-capacity)
 * [PeriodicStorageArtifactsCleanupCapacity](#periodic-storage-artifacts-cleanup-capacity)
 * [QueryAccelerationCapacity](#query-acceleration-capacity)
+* [GraphSnapshotsCapacity](#graph-snapshots-capacity)
 
 To view the capacity of your cluster, use the [.show capacity](show-capacity-command.md) command.
 
@@ -193,6 +194,18 @@ The [.show capacity](show-capacity-command.md) command returns the cluster's que
 
 `Minimum(ClusterMaximumConcurrentOperations` `,` *Number of nodes in cluster* `*` `Maximum(1,` *Core count per node* `*`  `CoreUtilizationCoefficient))`
 
+### Graph Snapshots capacity
+
+| Property | Type | Description |
+|--|--|--|
+| `ClusterMaximumConcurrentOperations` | `long` | The maximum number of concurrent snapshot creation operations on cluster. |
+
+**Formula**
+
+The [.show capacity](show-capacity-command.md) command returns the cluster's periodic storage artifacts cleanup capacity based on the following formula:
+
+`ClusterMaximumConcurrentOperations`
+
 ## Defaults
 
 The default capacity policy has the following JSON representation:
@@ -241,6 +254,9 @@ The default capacity policy has the following JSON representation:
   "QueryAccelerationCapacity": {
     "ClusterMaximumConcurrentOperations": 100,
     "CoreUtilizationCoefficient": 0.5
+  },
+  "GraphSnapshotsCapacity": {
+    "ClusterMaximumConcurrentOperations": 5
   }
 }
 ```

data-explorer/kusto/management/graph/graph-model-create-or-alter.md

@@ -1,6 +1,6 @@
 ---
 title: .create-or-alter graph_model command
-description: Learn how to create or alter a graph model using the .create-or-alter graph_model command with syntax, parameters, and examples.
+description: Learn how to create or alter a graph model using the create-or-alter graph_model command with syntax, parameters, and examples.
 ms.reviewer: herauch
 ms.topic: reference
 ms.date: 05/24/2025
@@ -17,7 +17,7 @@ Creates a new graph model or alters an existing one using the provided model def
 
 ## Permissions
 
-To run this command, the user needs [Database Admin permissions](../../access-control/role-based-access-control.md).
+To run this command, the user needs [Database User permissions](../../access-control/role-based-access-control.md).
 
 ## Syntax
 
@@ -106,13 +106,13 @@ This command returns a table with the following columns:
 
 |Name|CreationTime|ID|SnapshotsCount|Model|AuthorizedPrincipals|RetentionPolicy|
 |---|---|---|---|---|---|---|
-|SocialNetwork|2025-05-23 14:42:37.5128901|aaaaaaaa-0b0b-1c1c-2d2d-333333333333|0|model from above|[</br>  {</br>    "Type": "AAD User",</br>    "DisplayName": "Alex Johnson (upn: [email protected])",</br>    "ObjectId": "aaaaaaaa-bbbb-cccc-1111-22222222222",</br>    "FQN": "aaduser=aaaaaaaa-bbbb-cccc-1111-22222222222;aaaabbbb-0000-cccc-1111-dddd2222eeee",</br>    "Notes": "",</br>    "RoleAssignmentIdentifier": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"</br>  }</br>]|{</br>  "SoftDeletePeriod": "3650.00:00:00"</br>}|
+|SocialNetwork|2025-05-23 14:42:37.5128901|aaaaaaaa-0b0b-1c1c-2d2d-333333333333|0|model from above|[</br>  {</br>    "Type": "Microsoft Entra ID User",</br>    "DisplayName": "Alex Johnson (upn: [email protected])",</br>    "ObjectId": "aaaaaaaa-bbbb-cccc-1111-22222222222",</br>    "FQN": "aaduser=aaaaaaaa-bbbb-cccc-1111-22222222222;aaaabbbb-0000-cccc-1111-dddd2222eeee",</br>    "Notes": "",</br>    "RoleAssignmentIdentifier": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"</br>  }</br>]|{</br>  "SoftDeletePeriod": "3650.00:00:00"</br>}|
 
 ## Notes
 
 * If a graph model with the specified name doesn't exist, a new one is created when using `.create-or-alter graph_model`. If one already exists, it's updated with the new definition.
 * Each time a graph model is altered, a new version is created, allowing you to track changes over time and revert to previous versions if needed.
-* To generate a graph snapshot from the model, use the [.make graph_snapshot](graph-snapshot-make.md) command.
+* To generate a graph snapshot from the model, use the [`.make graph_snapshot`](graph-snapshot-make.md) command.
 
 ## Related content
 

data-explorer/kusto/management/graph/graph-model-drop.md

@@ -17,7 +17,7 @@ Deletes an existing graph model and all its versions from the database, includin
 
 ## Permissions
 
-To run this command, you need [Database admin permissions](../../access-control/role-based-access-control.md).
+To run this command, you need [Database admin permissions](../../access-control/role-based-access-control.md) or [Graph admin permissions](../../access-control/role-based-access-control.md).
 
 ## Syntax
 

data-explorer/kusto/management/graph/graph-model-overview.md

@@ -47,18 +47,56 @@ A graph model consists of two main components:
 
 ### Schema (optional)
 
-The schema defines the structure of the nodes and edges in the graph:
+The schema defines the structure and properties of nodes and edges in the graph model. While optional, the schema serves several important purposes:
 
-- **Nodes**: Defines the types of nodes in the graph and their properties
-- **Edges**: Defines the types of relationships between nodes and their properties
+- **Type safety**: Schema properties define the expected data types for node and edge properties, ensuring type consistency during graph queries
+- **Property validation**: All properties defined in the schema become valid properties for nodes/edges with the corresponding labels, regardless of whether these properties appear in the step query columns
+- **Query compatibility**: Schema properties can be safely referenced in graph-match queries without type collisions with step query columns
+
+#### Schema structure
+
+- **Nodes**: Defines node label types and their typed properties (e.g., `"Person": {"Name": "string", "Age": "long"}`)
+- **Edges**: Defines edge label types and their typed properties (e.g., `"WORKS_AT": {"StartDate": "datetime", "Position": "string"}`)
 
 ### Definition
 
-The Definition specifies how to build the graph from tabular data:
+The Definition specifies how to build the graph from tabular data through a series of sequential operations. This section is the core of the graph model, as it transforms your relational data into a graph structure.
+
+#### Key characteristics of the Definition:
+
+* **Sequential execution**: Steps are executed in the exact order they appear in the Definition array. This order is critical because:
+  - Nodes must typically be created before edges that reference them
+  - Later steps can build upon or modify the results of earlier steps
+  - The sequence affects performance and memory usage during graph construction
+
+* **Incremental construction**: Each step adds to the graph being built, allowing you to:
+  - Combine data from multiple tables or sources
+  - Apply different logic for different types of nodes or edges
+  - Build complex graph structures incrementally
+
+#### Step types:
+
+* **AddNodes**: Steps that define how to create nodes from tabular data
+  - Can be used multiple times to add different types of nodes
+  - Each step can pull from different data sources or apply different filters
+  - Node properties are derived from the columns in the query result
 
-* **Steps**: A sequence of operations to add nodes and edges to the graph
-  * **AddNodes**: Steps that define how to create nodes from tabular data
-  * **AddEdges**: Steps that define how to create edges from tabular data
+* **AddEdges**: Steps that define how to create edges from tabular data
+  - Can reference nodes that don't yet exist (the system will create placeholder nodes and update them when AddNodes steps are processed later)
+  - Can create relationships between nodes from the same or different AddNodes steps
+  - Edge properties are derived from the columns in the query result
+  - While it's possible to add edges before nodes, it's recommended to add nodes first for better readability and understanding
+
+#### Execution flow example:
+
+```
+Step 1 (AddNodes): Create Person nodes from Employees table
+Step 2 (AddNodes): Create Company nodes from Organizations table  
+Step 3 (AddEdges): Create WORKS_AT edges between Person and Company nodes
+Step 4 (AddEdges): Create KNOWS edges between Person nodes
+```
+
+This sequential approach ensures that when Step 3 creates WORKS_AT edges, both the Person nodes (from Step 1) and Company nodes (from Step 2) already exist in the graph.
 
 ## Labels in Graph models
 
@@ -278,8 +316,16 @@ To refresh a graph:
 
 ### What if different steps create duplicate edges or nodes?
 
-- **Edges**: Duplicates remain as duplicates by default (edges don't have unique identifiers)
-- **Nodes**: "Duplicates" are merged - the system assumes they represent the same entity. If there are conflicting property values, the last value processed takes precedence
+The Definition steps execute sequentially, and duplicate handling differs between nodes and edges:
+
+- **Edges**: Duplicates remain as duplicates by default since edges don't have unique identifiers. If multiple steps create identical source-target relationships, each one becomes a separate edge in the graph. This behavior is intentional as multiple relationships between the same nodes can represent different interactions or events over time.
+
+- **Nodes**: "Duplicates" are automatically merged based on the NodeIdColumn value - the system assumes they represent the same entity. When multiple steps create nodes with the same identifier:
+  - All properties from different steps are combined into a single node
+  - If there are conflicting property values for the same property name, the value from the step that executed last takes precedence
+  - Properties that exist in one step but not another are preserved
+
+This merge behavior allows you to build nodes incrementally across steps, such as adding basic information in one step and enriching with additional properties in subsequent steps.
 
 ### How do graph models handle schema changes?
 

data-explorer/kusto/management/graph/graph-snapshot-drop.md

@@ -17,7 +17,7 @@ Deletes a specific graph snapshot from a graph model.
 
 ## Permissions
 
-To run this command, the user needs [Database Admin permissions](../../access-control/role-based-access-control.md).
+To run this command, the user needs [Database Admin permissions](../../access-control/role-based-access-control.md) or [Graph admin permissions](../../access-control/role-based-access-control.md).
 
 ## Syntax
 

data-explorer/kusto/management/graph/graph-snapshot-make.md

@@ -17,7 +17,7 @@ Creates a new graph snapshot from a specified graph model. A graph snapshot is a
 
 ## Permissions
 
-To run this command, the user needs [Database admin permissions](../../access-control/role-based-access-control.md).
+To run this command, the user needs [Database admin permissions](../../access-control/role-based-access-control.md) or [Graph admin permissions](../../access-control/role-based-access-control.md).
 
 ## Syntax
 

data-explorer/kusto/management/graph/graph-snapshot-show.md

@@ -17,7 +17,7 @@ Shows detailed information about a specific graph snapshot.
 
 ## Permissions
 
-To run this command, the user needs [Database admin permissions](../../access-control/role-based-access-control.md).
+To run this command, the user needs [Database viewer permissions](../../access-control/role-based-access-control.md).
 
 ## Syntax
 

data-explorer/kusto/management/graph/graph-snapshots-drop.md

@@ -1,6 +1,6 @@
 ---
 title: .drop graph_snapshots command
-description: Learn how to delete all graph snapshots for a specific graph model using the .drop graph_snapshots command.
+description: Learn how to delete all graph snapshots for a specific graph model using the drop graph_snapshots command.
 ms.reviewer: herauch
 ms.topic: reference
 ms.date: 05/24/2025
@@ -17,7 +17,7 @@ Deletes all graph snapshots associated with a specific graph model.
 
 ## Permissions
 
-To run this command, you need [Database admin permissions](../../access-control/role-based-access-control.md).
+To run this command, you need [Database admin permissions](../../access-control/role-based-access-control.md) or [Graph admin permissions](../../access-control/role-based-access-control.md).
 
 ## Syntax
 
@@ -45,9 +45,9 @@ The command completes successfully without returning any output.
 
 ## Important notes
 
-- The `.drop graph_snapshots` command permanently deletes all snapshots associated with a graph model. This operation cannot be undone.
+- The `.drop graph_snapshots` command permanently deletes all snapshots associated with a graph model. This operation can't be undone.
 - Dropping snapshots doesn't affect the graph model itself.
-- To drop a specific snapshot instead of all snapshots, use the [.drop graph_snapshot](graph-snapshot-drop.md) command.
+- To drop a specific snapshot instead of all snapshots, use the [`.drop graph_snapshot`](graph-snapshot-drop.md) command.
 
 ## Next steps
 

data-explorer/kusto/management/graph/graph-snapshots-show.md

@@ -17,7 +17,7 @@ Lists all graph snapshots for a specific graph model or for all graph models.
 
 ## Permissions
 
-To run this command, the user needs [Database admin permissions](../../access-control/role-based-access-control.md).
+To run this command, the user needs [Database viewer permissions](../../access-control/role-based-access-control.md).
 
 ## Syntax