English for Hasura GraphQL Engine

Hasura’s whole pitch is generating a GraphQL API directly from your database schema, which means most bugs teams hit aren’t in hand-written resolver code — they’re in permissions, relationships, or tracking configuration. Naming these Hasura-specific concepts precisely is what makes debugging sessions productive instead of confusing.

Key Vocabulary

Tracked table — a database table that Hasura has been explicitly configured to expose through its auto-generated GraphQL API; an untracked table simply doesn’t appear in the schema at all. “The new column showed up in the database but not in the API — turns out the table itself was never tracked in Hasura after the migration ran.”

Permission rule — a row- and column-level access policy defined per role (like user or admin) that determines which rows a query can return and which fields can be selected, inserted, or updated. “The bug wasn’t in our frontend code — the user role’s permission rule was missing a filter, so it was returning other users’ rows in addition to the current user’s own.”

Relationship (object / array) — a defined link between two tracked tables (often derived from a foreign key) that lets a GraphQL query nest related data, an object relationship for a single related row and an array relationship for many. “We added an array relationship from authors to books so a single query can fetch an author along with every book they’ve written, instead of making a separate request per book.”

Remote schema — an external GraphQL API that Hasura stitches into its own schema, letting clients query Hasura’s database-backed types and a third-party or custom service’s types in one request. “The recommendation logic lives in a separate microservice, so we added it as a remote schema — clients can query products and recommendations together without knowing two services are involved.”

Hasura action — a way to extend Hasura’s auto-generated API with custom business logic, defined as a GraphQL mutation or query that Hasura forwards to a webhook you control, when the logic can’t be expressed as a plain database operation. “Sending a welcome email isn’t something Hasura can generate automatically, so we defined it as an action that calls our own webhook after the underlying insert happens.”

Common Phrases

• “Is this table actually tracked in Hasura, or does it just exist in the database without being exposed?”
• “Is the missing data a permission-rule problem, or is the relationship itself not configured?”
• “Should this be an object relationship or an array relationship, given the cardinality here?”
• “Is this logic something Hasura can auto-generate, or do we need a custom action with a webhook?”
• “Is this type coming from our tracked tables, or is it actually served through a remote schema?”

Example Sentences

Debugging a permissions issue: “Users were seeing other people’s draft posts — the permission rule for the user role was filtering on published = true for reads but had no filter at all on the row-level select for drafts.”

Explaining a schema design decision: “We added the array relationship from orders to order_items so the frontend can fetch a full order in one query, instead of the client making N follow-up requests per item.”

Describing an architecture choice in a review: “We’re stitching in the payments service as a remote schema rather than replicating its data into our own tables, since payment state needs to stay authoritative in that service.”

Professional Tips

• Say tracked explicitly when a table’s data isn’t showing up in the API — it’s usually the first thing to check and often the actual root cause.
• Name the specific permission rule and role involved when discussing an access bug — “permissions are wrong” is far less actionable than “the user role’s select permission is missing a filter.”
• Distinguish object and array relationships precisely in schema reviews — picking the wrong cardinality early causes confusing null-versus-list bugs downstream.
• Use action deliberately when proposing custom logic — it signals you’ve already ruled out expressing the behavior as a plain database operation, which is Hasura’s default and preferred path.

Practice Exercise

1. Explain what it means for a table to be “tracked” in Hasura.
2. Describe the difference between an object relationship and an array relationship.
3. Write a sentence explaining when you’d reach for a Hasura action instead of relying on auto-generated CRUD.

In Practice: Navigating Nuance – Refining Communication Around Hasura Schemas

Let’s be honest, when you’re building with Hasura and GraphQL, the technical jargon can feel incredibly precise. It is precise, of course, but that precision can sometimes create a barrier to effective communication, especially for developers whose first language isn’t English. Beyond simply knowing the definitions of “schema,” “permissions,” and “relationships,” it’s about understanding how those terms are typically used in professional settings – particularly when discussing changes or seeking clarification. A simple request like, “Can you check the schema?” might not cut it. Instead, consider framing your query more deliberately to guide the reviewer’s attention. For instance, saying “Could you review the product schema, specifically focusing on the relationships between products and categories, to ensure we’ve correctly implemented the foreign key constraints?” immediately provides context and directs their effort.

This applies equally to Slack conversations and Pull Request descriptions. Imagine receiving a comment during a code review: “Schema looks good.” That’s incredibly vague! A more productive response would be, “The schema seems generally sound, but I’m concerned about the lack of explicit NOT NULL constraints on the product_id field in the orders table. We should consider adding these to improve data integrity.” See how that phrasing adds a layer of critical assessment and proposes a specific action? Similarly, when writing a PR description for changes related to Hasura’s remote schemas – perhaps updating a database connection or modifying permissions – don’t just say “Updated schema.” Instead, detail what was updated: “Modified the users schema to incorporate the new GDPR compliance requirements regarding data retention, including adding a last_accessed timestamp field and adjusting the associated permissions for read access to this field.”

The key is to move beyond simply stating facts and start articulating intent and reasoning. This isn’t about being overly verbose; it’s about ensuring everyone understands why certain decisions were made regarding your Hasura setup. It also helps in documenting the system, creating clear instructions for others to understand how things work.

Here’s a simple example of how you might use hasura-cli to inspect a schema and then discuss the output with a team member:

hasura-cli introspect --schema <your_database_url>

This command will generate a JSON representation of your Hasura schema. You could then share that file, or even just a snippet of its contents (e.g., showing the relationships between tables), to facilitate discussion about potential improvements or changes. The output can be used as a starting point for conversation and collaborative problem-solving.