diff --git a/data-explorer/kusto-tocs/management/toc.yml b/data-explorer/kusto-tocs/management/toc.yml index a52fdf12e4..d2454f3883 100644 --- a/data-explorer/kusto-tocs/management/toc.yml +++ b/data-explorer/kusto-tocs/management/toc.yml @@ -232,6 +232,12 @@ items: href: /kusto/management/graph/graph-persistent-overview?view=azure-data-explorer&preserve-view=true - name: Graph models overview href: /kusto/management/graph/graph-model-overview?view=azure-data-explorer&preserve-view=true + - name: Graph model policies + href: /kusto/management/graph/graph-model-policies?view=azure-data-explorer&preserve-view=true + - name: snapshot_indexing graph model policy + href: /kusto/management/graph/graph-model-policy-snapshot-indexing?view=azure-data-explorer&preserve-view=true + - name: graph_query graph model policy + href: /kusto/management/graph/graph-model-policy-graph-query?view=azure-data-explorer&preserve-view=true - name: .create-or-alter graph_model href: /kusto/management/graph/graph-model-create-or-alter?view=azure-data-explorer&preserve-view=true - name: .drop graph_model diff --git a/data-explorer/kusto/management/graph/graph-model-overview.md b/data-explorer/kusto/management/graph/graph-model-overview.md index 1c94fac27b..e93059222c 100644 --- a/data-explorer/kusto/management/graph/graph-model-overview.md +++ b/data-explorer/kusto/management/graph/graph-model-overview.md @@ -355,6 +355,7 @@ graph("EmployeeNetwork") * [.create-or-alter graph_model](graph-model-create-or-alter.md) * [.drop graph_model](graph-model-drop.md) * [.show graph_models](graph-model-show.md) +* [Graph model policies](graph-model-policies.md) * [Key considerations](graph-persistent-overview.md#key-considerations) * [Graph operators](../../query/graph-operators.md) * [Graph best practices](../../query/graph-best-practices.md) diff --git a/data-explorer/kusto/management/graph/graph-model-policies.md b/data-explorer/kusto/management/graph/graph-model-policies.md new file mode 100644 index 0000000000..0a037359a5 --- /dev/null +++ b/data-explorer/kusto/management/graph/graph-model-policies.md @@ -0,0 +1,71 @@ +--- +title: Graph model policies +description: Learn about graph model policies that control retention, caching, snapshot indexing, and default graph query behavior. +ms.reviewer: royo, danieldror +ms.topic: reference +ms.date: 07/08/2026 +--- + +# Graph model policies (preview) + +> [!INCLUDE [applies](../../includes/applies-to-version/applies.md)] [!INCLUDE [fabric](../../includes/applies-to-version/fabric.md)] [!INCLUDE [azure-data-explorer](../../includes/applies-to-version/azure-data-explorer.md)] + +> [!NOTE] +> This feature is currently in preview. Functionality and syntax are subject to change before General Availability. + +Graph model policies control how a graph model is stored, prepared, and used by default graph queries. + +Graph models support existing [retention](../retention-policy.md) and [caching](../cache-policy.md) policies. Graph models also support policies that are specific to graph snapshots and graph queries. + +## Supported policies + +|Policy|Description| +|--|--| +|`retention`|Controls data retention for graph model artifacts.| +|`caching`|Controls hot-cache behavior for graph model artifacts.| +|`snapshot_indexing`|Controls how graph snapshots are indexed.| +|`graph_query`|Controls graph query behavior for the graph model.| + +## Syntax + +`.show` `graph_model` *GraphModelName* `policy` *PolicyName* + +`.alter` `graph_model` *GraphModelName* `policy` *PolicyName* *PolicyObject* + +`.delete` `graph_model` *GraphModelName* `policy` *PolicyName* + +## Parameters + +|Name|Type|Required|Description| +|--|--|--|--| +|*GraphModelName*|String|✅|The graph model name.| +|*PolicyName*|String|✅|The policy name. Supported values include `retention`, `caching`, `snapshot_indexing`, and `graph_query`.| +|*PolicyObject*|String|✅ for `.alter`|A JSON policy object. The shape depends on the policy.| + +## Examples + +### Set the snapshot indexing policy + +````kusto +.alter graph_model MyGraph policy snapshot_indexing ``` +{ + "IndexingLevel": "Default" +} +``` +```` + +### Set the default graph query policy + +````kusto +.alter graph_model MyGraph policy graph_query ``` +{ + "DefaultSnapshotQueryBehavior": "LatestIndexedSnapshot" +} +``` +```` + +## Related content + +- [snapshot_indexing graph model policy](graph-model-policy-snapshot-indexing.md) +- [graph_query graph model policy](graph-model-policy-graph-query.md) +- [Graph models overview](graph-model-overview.md) diff --git a/data-explorer/kusto/management/graph/graph-model-policy-graph-query.md b/data-explorer/kusto/management/graph/graph-model-policy-graph-query.md new file mode 100644 index 0000000000..2239760d4c --- /dev/null +++ b/data-explorer/kusto/management/graph/graph-model-policy-graph-query.md @@ -0,0 +1,113 @@ +--- +title: graph_query graph model policy +description: Learn how to show, alter, and delete the graph_query policy for a graph model. +ms.reviewer: royo, danieldror +ms.topic: reference +ms.date: 07/08/2026 +--- + +# graph_query graph model policy (preview) + +> [!INCLUDE [applies](../../includes/applies-to-version/applies.md)] [!INCLUDE [fabric](../../includes/applies-to-version/fabric.md)] [!INCLUDE [azure-data-explorer](../../includes/applies-to-version/azure-data-explorer.md)] + +> [!NOTE] +> This feature is currently in preview. Functionality and syntax are subject to change before General Availability. + +The `graph_query` policy controls graph query behavior for a graph model. + +The policy controls which snapshot is selected when a query references a graph model without naming a snapshot. For example, the policy applies to queries that use `graph("MyGraph")`. It doesn't apply when a query names a specific snapshot. + +The default `DefaultSnapshotQueryBehavior` value is `LatestSnapshot`. + +If a query names a specific snapshot, that snapshot must be available for queries. If the named snapshot isn't available yet, the query fails. If a query doesn't name a snapshot, `LatestSnapshot` selects the latest available snapshot regardless of indexing state. `LatestIndexedSnapshot` selects the latest available snapshot that satisfies the model's `snapshot_indexing` policy. + +## Permissions + +To show the policy, you need [Database Monitor or Database Viewer permissions](../../access-control/role-based-access-control.md). + +To alter or delete the policy, you need Graph Admin permissions on the graph model. + +## Syntax + +`.show` `graph_model` *GraphModelName* `policy` `graph_query` + +`.show` `graph_model` `*` `policy` `graph_query` + +`.alter` `graph_model` *GraphModelName* `policy` `graph_query` *PolicyObject* + +`.delete` `graph_model` *GraphModelName* `policy` `graph_query` + +## Parameters + +|Name|Type|Required|Description| +|--|--|--|--| +|*GraphModelName*|String|✅|The graph model name.| +|*PolicyObject*|String|✅ for `.alter`|A JSON policy object.| +|`DefaultSnapshotQueryBehavior`|String|✅|The snapshot selection behavior for `graph("model")`. Supported values are `LatestSnapshot` and `LatestIndexedSnapshot`.| + +## Default snapshot query behavior + +|Value|Description| +|--|--| +|`LatestSnapshot`|Use the latest available snapshot, regardless of indexing state. This is the default value.| +|`LatestIndexedSnapshot`|Use the latest available snapshot that satisfies the model's `snapshot_indexing` policy. If no matching snapshot is available, the query fails with a clear error.| + +Deleting the policy restores the default behavior. + +## Returns + +This command returns a table with the following columns: + +|Column|Type|Description| +|--|--|--| +|PolicyName|String|The policy name.| +|EntityName|String|The graph model name.| +|Policy|String|The JSON representation of the policy.| +|ChildEntities|String|Reserved.| +|EntityType|String|The entity type.| + +## Examples + +### Show the policy for a graph model + +```kusto +.show graph_model MyGraph policy graph_query +``` + +### Show policies for all graph models + +```kusto +.show graph_model * policy graph_query +``` + +### Use the latest available snapshot + +````kusto +.alter graph_model MyGraph policy graph_query ``` +{ + "DefaultSnapshotQueryBehavior": "LatestSnapshot" +} +``` +```` + +### Use the latest snapshot that satisfies the indexing policy + +````kusto +.alter graph_model MyGraph policy graph_query ``` +{ + "DefaultSnapshotQueryBehavior": "LatestIndexedSnapshot" +} +``` +```` + +### Delete the policy + +```kusto +.delete graph_model MyGraph policy graph_query +``` + +## Related content + +- [Graph model policies](graph-model-policies.md) +- [snapshot_indexing graph model policy](graph-model-policy-snapshot-indexing.md) +- [Graph models overview](graph-model-overview.md) diff --git a/data-explorer/kusto/management/graph/graph-model-policy-snapshot-indexing.md b/data-explorer/kusto/management/graph/graph-model-policy-snapshot-indexing.md new file mode 100644 index 0000000000..68ae752126 --- /dev/null +++ b/data-explorer/kusto/management/graph/graph-model-policy-snapshot-indexing.md @@ -0,0 +1,124 @@ +--- +title: snapshot_indexing graph model policy +description: Learn how to show, alter, and delete the snapshot_indexing policy for a graph model. +ms.reviewer: royo, danieldror +ms.topic: reference +ms.date: 07/08/2026 +--- + +# snapshot_indexing graph model policy (preview) + +> [!INCLUDE [applies](../../includes/applies-to-version/applies.md)] [!INCLUDE [fabric](../../includes/applies-to-version/fabric.md)] [!INCLUDE [azure-data-explorer](../../includes/applies-to-version/azure-data-explorer.md)] + +> [!NOTE] +> This feature is currently in preview. Functionality and syntax are subject to change before General Availability. + +The `snapshot_indexing` policy controls how graph snapshots for a graph model are indexed. + +The policy affects snapshots created after the policy is set. It doesn't change existing snapshots. + +The default `IndexingLevel` value is `Default`. + +Indexing can improve query performance, but more complete indexing can increase the work needed to prepare a snapshot. Indexing runs in the background, so graph queries can continue to use available snapshots while indexing work is in progress. To control whether default graph queries wait for indexed snapshots, use the [`graph_query`](graph-model-policy-graph-query.md) policy. + +## Permissions + +To show the policy, you need [Database Monitor or Database Viewer permissions](../../access-control/role-based-access-control.md). + +To alter or delete the policy, you need Graph Admin permissions on the graph model. + +## Syntax + +`.show` `graph_model` *GraphModelName* `policy` `snapshot_indexing` + +`.show` `graph_model` `*` `policy` `snapshot_indexing` + +`.alter` `graph_model` *GraphModelName* `policy` `snapshot_indexing` *PolicyObject* + +`.delete` `graph_model` *GraphModelName* `policy` `snapshot_indexing` + +## Parameters + +|Name|Type|Required|Description| +|--|--|--|--| +|*GraphModelName*|String|✅|The graph model name.| +|*PolicyObject*|String|✅ for `.alter`|A JSON policy object.| +|`IndexingLevel`|String|✅|The requested indexing level. Supported values are `Disabled`, `Default`, and `Best`.| + +## Indexing levels + +|Indexing level|Description| +|--|--| +|`Disabled`|Don't index graph snapshots for the model.| +|`Default`|Let the system decide whether indexing is beneficial for each snapshot. This is the default value.| +|`Best`|Use the most complete indexing behavior for snapshots of the model. This can improve query performance, but might require more work while preparing snapshots.| + +Deleting the policy restores the default behavior. + +## Returns + +This command returns a table with the following columns: + +|Column|Type|Description| +|--|--|--| +|PolicyName|String|The policy name.| +|EntityName|String|The graph model name.| +|Policy|String|The JSON representation of the policy.| +|ChildEntities|String|Reserved.| +|EntityType|String|The entity type.| + +## Examples + +### Show the policy for a graph model + +```kusto +.show graph_model MyGraph policy snapshot_indexing +``` + +### Show policies for all graph models + +```kusto +.show graph_model * policy snapshot_indexing +``` + +### Use the default indexing behavior + +````kusto +.alter graph_model MyGraph policy snapshot_indexing ``` +{ + "IndexingLevel": "Default" +} +``` +```` + +### Use the most complete indexing behavior + +````kusto +.alter graph_model MyGraph policy snapshot_indexing ``` +{ + "IndexingLevel": "Best" +} +``` +```` + +### Disable snapshot indexing + +````kusto +.alter graph_model MyGraph policy snapshot_indexing ``` +{ + "IndexingLevel": "Disabled" +} +``` +```` + +### Delete the policy + +```kusto +.delete graph_model MyGraph policy snapshot_indexing +``` + +## Related content + +- [Graph model policies](graph-model-policies.md) +- [graph_query graph model policy](graph-model-policy-graph-query.md) +- [Graph snapshots overview](graph-snapshot-overview.md) diff --git a/data-explorer/kusto/management/policies.md b/data-explorer/kusto/management/policies.md index e9b66f2c95..9d6e03339e 100644 --- a/data-explorer/kusto/management/policies.md +++ b/data-explorer/kusto/management/policies.md @@ -20,6 +20,7 @@ The following table provides an overview of the policies for managing your envir |[Capacity policy](capacity-policy.md)|Controls the compute resources of data management operations.| |[Encoding policy](encoding-policy.md)|Defines how data is encoded, compressed, and indexed.| |[Extent tags retention policy](extent-tags-retention-policy.md)|Controls the mechanism that automatically removes extent tags from tables.| +|[Graph model policies](graph/graph-model-policies.md)|Control retention, caching, snapshot indexing, and default graph query behavior for graph models.| |[Ingestion batching policy](batching-policy.md)|Groups multiple data ingestion requests into batches for more efficient processing.| |[Ingestion time policy](ingestion-time-policy.md)|Adds a hidden datetime column to the table that records the time of ingestion.| |[ManagedIdentity policy](managed-identity-policy.md)|Controls which managed identities can be used for what purposes.| @@ -50,6 +51,7 @@ The following table provides an overview of the policies for managing your envir |[Capacity policy](capacity-policy.md)|Controls the compute resources of data management operations.| |[Encoding policy](encoding-policy.md)|Defines how data is encoded, compressed, and indexed.| |[Extent tags retention policy](extent-tags-retention-policy.md)|Controls the mechanism that automatically removes extent tags from tables.| +|[Graph model policies](graph/graph-model-policies.md)|Control retention, caching, snapshot indexing, and default graph query behavior for graph models.| |[Ingestion batching policy](batching-policy.md)|Groups multiple data ingestion requests into batches for more efficient processing.| |[Ingestion time policy](ingestion-time-policy.md)|Adds a hidden datetime column to the table that records the time of ingestion.| |[ManagedIdentity policy](managed-identity-policy.md)|Controls which managed identities can be used for what purposes.| diff --git a/data-explorer/kusto/management/toc.yml b/data-explorer/kusto/management/toc.yml index 3263f9214d..e9d947ec36 100644 --- a/data-explorer/kusto/management/toc.yml +++ b/data-explorer/kusto/management/toc.yml @@ -232,6 +232,12 @@ items: href: graph/graph-persistent-overview.md - name: Graph models overview href: graph/graph-model-overview.md + - name: Graph model policies + href: graph/graph-model-policies.md + - name: snapshot_indexing graph model policy + href: graph/graph-model-policy-snapshot-indexing.md + - name: graph_query graph model policy + href: graph/graph-model-policy-graph-query.md - name: .create-or-alter graph_model href: graph/graph-model-create-or-alter.md - name: .drop graph_model