English for SurrealDB Developers

SurrealDB blends document, graph, and relational modeling into a single engine queried with SurrealQL, which means a team’s vocabulary has to stretch across ideas from three different database worlds at once. Getting “record link” and “graph edge” confused, or treating “schemafull” and “schemaless” tables as interchangeable, leads to modeling mistakes that are hard to unwind later. This guide covers the English used when discussing SurrealDB with a team.

Key Vocabulary

Record ID — SurrealDB’s unique identifier format combining a table name and an identifier (like user:tobie), used directly in queries and as a first-class value rather than an opaque string. “Store the record ID itself as the reference, not just the raw identifier — SurrealDB can traverse it directly without an extra lookup table.”

Record link (vs. graph edge) — a field on one record that points directly to another record’s ID, distinct from a graph edge, which is its own record connecting two others with its own properties. “A record link is fine if you just need a pointer to the author, but if the relationship itself needs metadata — like when the review happened — model it as a graph edge instead.”

Graph edge (RELATE) — a first-class record created with the RELATE statement that connects two other records and can carry its own fields, enabling graph traversal queries. “Use RELATE to create a wrote edge between the user and the post — that lets us query ‘who wrote what’ as a graph traversal instead of a join.”

Schemafull vs. schemaless table — a table can enforce a defined field structure (schemafull) or accept arbitrary fields per record (schemaless), chosen per table rather than for the whole database. “Make the orders table schemafull since its shape is stable and validation matters, but leave event_log schemaless since its fields vary by event type.”

SurrealQL traversal (graph query) — SurrealQL’s syntax for walking relationships (->wrote->post), letting a query express multi-hop graph paths inline rather than through multiple joins. “Instead of three separate joins, this SurrealQL traversal walks user to post to comment in one statement — it reads like the relationship it’s describing.”

Common Phrases

• “Should this be a simple record link, or does the relationship itself need properties, which means it should be a graph edge?”
• “Is this table schemafull for validation, or schemaless because the shape genuinely varies?”
• “Can we express this as a graph traversal instead of multiple round trips?”
• “What’s the record ID format here — are we relying on it being human-readable?”
• “Does this query need RELATE, or is a plain record link enough for this use case?”

Example Sentences

Reviewing a pull request: “This models ‘liked’ as a boolean field on the post — if you need to know who liked it and when, that should be a graph edge with a RELATE, not a flag.”

Explaining a design decision: “We made the core domain tables schemafull for safety, but kept the audit log schemaless since new event types show up faster than we could migrate a schema.”

Describing an incident: “The slow query wasn’t a missing index — it was three separate lookups that should have been a single SurrealQL graph traversal from user to order to item.”

Professional Tips

• Say “record link” versus “graph edge” precisely — the distinction determines whether a relationship can carry its own data, and getting it wrong means a costly remodel later.
• When reviewing schema choices, ask “schemafull or schemaless, and why?” — it forces an explicit tradeoff instead of a default nobody chose deliberately.
• Use “RELATE” as a verb when describing edge creation — it matches the SurrealQL keyword and avoids ambiguity with generic “connect these records.”
• Describe multi-hop queries as “traversals” rather than “joins” — it signals you’re thinking in SurrealDB’s graph model, not translating from SQL habits.

Practice Exercise

1. Explain in two sentences when a relationship should be a graph edge instead of a simple record link.
2. Write a one-sentence code review comment recommending a table be made schemafull.
3. Describe, in your own words, what a SurrealQL graph traversal does compared to a SQL join.