In recent articles, such as my tutorial on how to use filtering queries with Microsoft Graph PowerShell, I often append my queries with the -ConsistencyLevel parameter and the Eventual value. While this is often used in the context of an advanced filtering query with Microsoft Graph, it can also be used when making standard queries, so it is important to understand the purpose of the parameter and the consequences of using it. Again, if you want to understand the difference between advanced and standard queries, check out the filtering queries post I have linked above.
In this article, I will explain how the Eventual ConsistencyLevel parameter works and when and why you should use it with Microsoft Graph PowerShell.
ConsistencyLevel Eventual explained
In databases (which is what Microsoft Graph aggregates across different Microsoft 365 services), consistency refers to the state of the data which is replicated across distributed database or systems. Consistency helps ensure data is accurate and up-to-date across these distributed systems and the consistency level refers to the set of rules which allows a person or system to access this distributed data in real-world scenarios, ensuring changes are fully up to date (or not) on all areas where the data is stored, when it is read.
In an eventual consistency model, all replicas in a distributed system can be read from, to return the last updated value of the requested object. Because any replica can be read from, some may return the correct value and some may return an old value, depending on the latency between replicas.
For example, referring to the diagram below. If a write operation is made on an object from a node in the UK South datacentre, replication to a nearby datacentre (such as UK West) may be instantaneous and a subsequent read may return the correct data. However, if that subsequent read happened on a data centre in Central US, due to replication lag, you may be returned incorrect data.
Eventual consistency allows this to happen as it increases the availability of the service, reduces the overall latency and provides a better end-user experience when performing complex read requests. However, if you are performing write requests within the same session, then there is a chance that due to this replication lag, you may be returned inconsistent data, this is why the Eventual consistency header is not added to every query by default.
The default experience when querying Microsoft Graph
Eventual consistency is not the default experience when making requests to Microsoft Graph, for the very reason that there is a chance that inconsistent data could be returned. Instead, you will always be returned the updated value when making write and read requests in the same session in a default experience.
Note:
When referring to the ‘default experience’ I am talking about when a request is made to the Rest directory Service and not the Advanced Queries Service. For more information on these two services, read my article: How to Use -Filter with Microsoft Graph PowerShell.
You can see the difference between the experiences when you make a write request to an object, then read the value of the changed property on the object from the same session immediately after, from both the Rest Directory Service and Advanced Queries Service.
Rest Directory Service (default)
Below you can see that when performing a write request, and then reading from the Rest Directory Service in the default experience, the correct and consistent value is returned.
Rest Directory Service (with eventual consistency)
When performing a write request, and then reading from the Rest Directory Service with eventual consistency, you can see the old value has been returned due to replication lag.
Advanced Queries Service
The same experience is had when performing a write request, then reading from the Advanced Queries Service. The old value is returned instead of the new value due to the replication lag.
It is important to carefully understand when you should and shouldn’t use eventual consistency. As a general rule of thumb, eventual consistency should only be used when sending a query to the Advanced Queries Service and should only be used in sessions where you are only making read requests. Alternatively, if you need to make an advanced query in the same session where you need to make a write (or change), then use the read query first to obtain your data, then do the write request after.
