Commenting on Metadata
Introduction
Hasura provides a commenting feature that allows your data teams to start conversations directly on the supergraph metadata. This feature enhances collaboration by closing the feedback loop and helps teams communicate more effectively about about their supergraph design and implementation.
This feature is available for all users on Base and Advanced plans.
How to comment
You can add comments on various objects from your metadata.
- Navigate to any model page in your project via the
Explorertab. - Hover over the field or section you want to comment on.
- Click on the comment icon that appears.
Commenting areas
Explorer Tab
The Explorer Tab is the primary interface where users interact with the supergraph metadata, making it a crucial place for collaboration. Comments here enable data producers and consumers to discuss design decisions, clarify data models, and suggest improvements to enhance PromptQL's ability to talk accurately with your data.
- Supergraph Page - Comment on the overall schema design, structure, and implementation details of the supergraph.
- Subgraph Page - Provide feedback on individual subgraphs, ensuring alignment with the larger supergraph design.
- Models → General
- Description - Clarify the model's purpose and usage to improve documentation.
- Signature - Discuss function signatures, return types, and argument structures.
- Models → Fields & Relationships
- Output Fields - Ask questions or provide insights on field usage and expected data.
- Arguments - Discuss argument types, required vs. optional parameters, and potential defaults.
- Relationships - Ensure relationships between models are well-defined and documented.
- Models → Permissions
- Role - Comment on role-based access control settings.
- Read / Create / Update / Delete - Discuss permission settings for different CRUD operations.
This feature is especially useful for teams working on building comprehensive supergraphs, as it ensures everyone stays aligned on data structure and permissions.
Insights Tab
The Insights Tab provides performance metrics, traces, and reports about API usage. Commenting here helps teams analyze and discuss API behavior, identify bottlenecks, and track improvements over time.
- Performance – Leave feedback on latency, throughput, and error rates.
- Platform Report – Discuss API usage patterns and suggest improvements.
- Traces – Analyze request traces and collaborate on optimizing execution paths.
This feature is valuable for DevOps, backend engineers, and API consumers looking to enhance API efficiency.
Builds Tab
The Builds Tab allows teams to track and validate schema changes across supergraph, subgraph, and connector builds. Commenting in this area helps teams coordinate schema evolution and avoid breaking changes.
- Supergraph Builds – Discuss schema changes at the supergraph level and their impact on consumers.
- Subgraph Builds – Leave comments about specific subgraph updates and dependencies.
- Connector Builds – Provide feedback on connector integrations and compatibility.
- Schema Diff – Highlight breaking changes or inconsistencies between schema versions.
By facilitating discussions on builds, teams can ensure smooth API evolution and prevent unexpected failures.
Notifications
In-app notifications show new comments made on your project.
The notification hub can be found in the top right corner of the console. On clicking the comments button, you will see all the comments where you are tagged in one place. You can click on a particular comment (deep linking) and go to the original thread on the console. You can also delete notifications from that menu.
You can learn how to invite collaborators here.
Limitations
The feature is in early access and has known limitations, which are in our backlog. Let us know if you would like to prioritize any specific functionality.
- Tagging users on comments
- Resolving comments
- Email notifications
- Ability to auto notify subgraph admin and developers.
- History Tab for comments.