English for Gel (EdgeDB) Developers

Gel (the database formerly named EdgeDB) presents itself as graph-relational rather than purely relational, and its query language reads much closer to natural object traversal than SQL, so explaining it to a SQL-native team requires vocabulary that bridges both worlds clearly.

Key Vocabulary

Graph-relational — a data model combining the strong typing and constraints of a relational database with the natural, nested object traversal of a graph database, avoiding the joins-everywhere feel of pure SQL. “We’re not writing five joins to get this nested data — Gel is graph-relational, so traversing related objects is expressed directly in the query, closer to how we think about the data.”

EdgeQL — Gel’s native query language, designed to express nested, object-shaped queries naturally, in contrast to SQL’s flatter, table-and-join-oriented syntax. “This query looks nothing like the SQL we’re used to because it’s EdgeQL — it’s built to express nested object shapes directly, without us manually assembling joins.”

Schema-as-code — the practice of defining a database schema in a dedicated schema language and applying it through migrations, treating the schema definition itself as a versioned, reviewable artifact. “We’re not editing tables through a GUI here — the schema is defined as code, reviewed in pull requests just like application logic, and applied through migrations.”

Link — Gel’s schema construct for representing a relationship between object types, roughly analogous to a foreign key but modeled explicitly as a named, first-class relationship rather than an implicit column reference. “This isn’t a bare foreign key column — it’s a named link in the schema, which is why we can traverse it directly in a query without writing an explicit join.”

Computed property — a schema-defined field whose value is derived from an expression over other data, evaluated at query time rather than stored and manually kept in sync. “We don’t need to remember to update this field on every write — it’s a computed property, so its value is always derived fresh at query time.”

Common Phrases

• “Can we express this directly in EdgeQL, or does this really need to be modeled as a raw SQL join?”
• “Is this relationship modeled as a proper link in the schema, or is it just an implicit foreign key column?”
• “Should this be a computed property instead of a field we have to remember to update manually?”
• “Is the schema change actually going through a migration and review, or was this applied directly?”

Example Sentences

Explaining the model to a SQL-native engineer: “Instead of writing three joins to pull an author, their posts, and each post’s tags, this EdgeQL query expresses that whole nested shape directly.”

Discussing a schema design: “Let’s model this relationship as an explicit link rather than a bare identifier column — it makes the schema self-documenting and lets us traverse it naturally in queries.”

Reviewing a migration: “This field should probably be a computed property instead of something the application updates manually — that removes an entire class of sync bugs.”

Professional Tips

• Introduce graph-relational early when pitching Gel to a SQL-only team — leading with “it’s still strongly typed and relational” reduces resistance before showing the more graph-like query syntax.
• Contrast EdgeQL with SQL directly in code review discussions, showing the equivalent joins it replaces — this builds trust faster than asserting it’s “better” without evidence.
• Push for schema-as-code discipline from day one — treating schema changes as reviewable, versioned artifacts avoids the drift that plagues GUI-managed relational databases.
• Recommend computed property over manually maintained derived fields whenever the source data is already in the schema — it eliminates an entire category of stale-data bugs.

Practice Exercise

1. Explain to a SQL-native developer how EdgeQL avoids writing multiple explicit joins for nested data.
2. Describe the difference between a bare foreign key column and an explicit schema link.
3. Write a sentence recommending a computed property instead of a manually maintained derived field.

Navigating Nuances: Beyond Literal Translation

As you delve deeper into working with Gel (formerly EdgeDB), it’s crucial to recognize that technical communication isn’t just about translating words from one language to another. It’s about conveying meaning, intent, and context effectively – especially when collaborating with a team where English might not be everyone’s first language. Often, the most significant challenges come not from misunderstandable vocabulary itself, but from subtle differences in phrasing and the way information is presented. Consider a code review comment: “This query could benefit from utilizing indexes for improved performance.” A native speaker would understand this immediately, but someone less familiar with English technical jargon might interpret it as a criticism of their coding skills. The key here is to focus on clear intent – in this case, suggesting an optimization. Similarly, a Slack message like, “Let’s refactor this module for better maintainability,” needs careful consideration. It’s not simply stating a desire; it’s proposing a strategic change with potential long-term benefits.

Another common hurdle is describing complex queries to non-technical team members. Imagine you’re explaining an EdgeQL query that traverses multiple relationships within the database. Simply saying “this query gets all users and their orders” isn’t enough. You need to articulate why this information is being requested, how it will be used, and the potential impact on system performance – phrases like “to generate a sales report” or “for analytical purposes”. Precision in your language demonstrates understanding and allows others to grasp the underlying logic. Furthermore, actively seeking clarification (“Could you elaborate on why we’re using this specific relationship?”) shows respect for differing levels of knowledge and fosters a collaborative environment. Don’t assume everyone understands the terminology – proactively explaining concepts is a cornerstone of effective communication.

A crucial skill is also adapting your language to your audience. When presenting to stakeholders, use more accessible terms and avoid overly technical jargon. Conversely, when discussing EdgeQL syntax with fellow developers, you can leverage specialized vocabulary confidently. Focusing on active voice (“The query retrieves data…”) is generally clearer than passive voice (“Data is retrieved by the query…”). And always prioritize clarity over conciseness – a slightly longer explanation that’s easily understood is far more valuable than a brief, ambiguous statement.

Here’s an example of how to describe a simple EdgeQL query in a PR description:

SELECT
  u.id AS user_id,
  u.name AS username,
  o.order_date AS order_date,
  o.total_amount AS total_amount
FROM
  user u
JOIN
  order o ON u.id = o.user_id
WHERE
  o.status = 'completed'
LIMIT 10;

This example clearly outlines the data being retrieved and the filtering criteria, facilitating a better understanding of the query’s purpose for anyone reviewing the PR.