Query vs. Mutation in API for GraphQL – Understanding the difference
GraphQL has changed the way developers interact with data using APIs by offering a more flexible and efficient alternative to REST. Before getting started, Create an API for GraphQL in Fabric and add data to use GraphQL in Fabric.
At the heart of GraphQL are two core operations: queries and mutations. While they may look similar on the surface, they serve very different purposes.
What is a Query?
A query is used to fetch data from a data source using API for GraphQL. Think of it like reading information from a database. Queries are read-only operations, meaning they do not modify any data on the server.
Example:
query {
user(id: "1")
{
name
email
}
}This query asks for the name and email of the user with ID 1. The server responds with nothing more, nothing less.
Key characteristics:
- Safe: doesn’t change server state.
- Cacheable: can be stored and reused.
- Idempotent: running it, multiple times has the same effect.
What is a Mutation?
A mutation is used to modify data on the data source. This includes creating, updating, or deleting records. Mutations are write operations and can change the state of the system.
Example:
mutation {
updateUser(id: "1", input: {name: "Jane Doe"})
{
id
name
}
}This mutation updates the name of the user with ID 1 to “Jane Doe” and returns the updated user data.
Key characteristics:
- Modifies state: changes data on the server.
- Not cacheable: each call may produce different results.
- Non-idempotent: running it multiple times may have different effects.
When to use what
- Use queries when you want to retrieve data without making any changes.
- Use mutations when you need to create, update, or delete data.
| Feature | Query | Mutation |
| Purpose | Read data | Modify data |
| Server Impact | No change | Changes server state |
| Idempotency | Yes | Not guaranteed |
| Example scenario | Get user profiles | Update a user profile |
Understanding the difference between queries and mutations is essential for building efficient and predictable GraphQL APIs. Queries are your go-to for fetching data, while mutations are your tool for making changes. Keeping these roles clear helps maintain clean, maintainable, and performant applications.
Supported data sources
Currently, the following supported data sources can be exposed through the Fabric API for GraphQL:
- Microsoft Fabric Data Warehouse
- Microsoft Fabric SQL database
- Microsoft Fabric Lakehouse via SQL Analytics Endpoint
- Microsoft Fabric Mirrored Databases via SQL Analytics Endpoint, including:
- Mirrored databases from Azure SQL Database
- Mirrored databases from Azure SQL Managed Instance
- Mirrored databases from Azure Cosmos DB
- Mirrored databases from Microsoft Fabric SQL Database
- Mirrored databases from Azure Databricks
- Mirrored databases from Snowflake
- Open mirrored databases
- Azure SQL database
- Datamart
Enable and disable queries and mutations
The enable/disable feature for queries and mutations allows dynamic control over API access, enabling you to activate or deactivate specific operations without modifying code or deploying changes.
- Disable – Blocks any requests from running the query or mutation. If someone tries to execute it, an error message will be returned. When a query or mutation is disabled, the schema reloads, making the query or mutation appear grayed out in the schema explorer.
- Enable – Allow a previously disabled query or mutation to be executed again. The item becomes executable after the schema reload operation, which occurs upon selecting the Enable option.
Please note that queries or mutations auto generated from stored procedures can only be deleted. Once deleted, they can be re-added using Get Data or the Update Schema options.
In summary, leveraging API for GraphQL through Fabric offers a compelling approach to modern API development. By combining the efficiency and adaptability of GraphQL with Fabric’s robust tools, developers can create scalable, precise, and user-focused integrations.
