Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 37 ยท Schema Design

Global Object Identification and the Node Interface

Learn the Node interface and the node(id) query: opaque global IDs, refetching any object by ID, how caches benefit, and what Relay-compatible schemas expect.

In most databases, an id is only unique inside its table: there is a book with id 7, an author with id 7 and a review with id 7. That is fine in a REST API, because the URL says which kind of thing you mean (/books/7). In a GraphQL schema, where one endpoint serves every type, it is a problem. Given only the string "7", nobody can tell which object it names. Client caches, refetch logic and generic tools all suffer from that.

Global Object Identification is a convention that fixes this. It has two parts: every important object has an id that is unique across the whole schema (a global ID), and the schema offers one generic query, node(id:), that can fetch any such object from its ID alone. It is part of the Relay specification, which is why you will hear it called "the Relay ID spec" or "the Node interface", but it is useful in any GraphQL API, with or without Relay.

Global Object Identification

Global ID Unique across all types.
Node interface Any object with an id implements it.
node(id) One query to refetch anything.

A convention, not part of the GraphQL core spec.

1 / 2

The Node interface and node(id)

The convention adds an interface, one field on Query, and an implementation on each type that wants to be refetchable:

GRAPHQL
interface Node {
  id: ID!
}

type Query {
  node(id: ID!): Node
  nodes(ids: [ID!]!): [Node]!
}

type Book implements Node {
  id: ID!
  title: String!
  author: Author!
}

type Author implements Node {
  id: ID!
  name: String!
  books: [Book!]!
}

Book and Author promise to have an id: ID! field by implementing Node. The node field returns the interface, so the concrete type is not known until runtime. A client must say what it wants per type with inline fragments, exactly as in Enums, Interfaces and Unions:

GRAPHQL
query Refetch($id: ID!) {
  node(id: $id) {
    __typename
    id
    ... on Book { title }
    ... on Author { name }
  }
}

nodes(ids:) is an optional batch version. Both fields are nullable on purpose: an unknown or deleted ID returns null rather than an error, and nodes keeps the list position so the client can match answers to requests.

The spec asks for the field to be named node and the argument id, because Relay and many tools look for exactly those names. If you are not using such tools you may rename them, but there is no real benefit.

Global IDs are opaque

How do you make an ID unique across types? The usual trick is to combine the type name and the local ID and encode the result, for example as Base64:

TEXT
Book:7   ->  Qm9vazo3
Author:7 ->  QXV0aG9yOjc=

The server can decode Qm9vazo3 back into Book and 7, decide which resolver to call, and fetch the right row. Two properties make this design work:

  • The ID is opaque to clients. They must treat it as a string they received and pass back, never parse it. That lets you change the encoding later (add a database shard number, switch to UUIDs, rename a type) without breaking anyone. The Base64 encoding is not a secret or a security measure; it only discourages people from parsing it.
  • The ID is stable. A cache key that changes between requests would defeat the purpose. Base the ID on the permanent database key.

Base64 is a convention, not a rule. Some teams use prefixed IDs such as book_7, or UUIDs that are already globally unique and need no wrapping. What matters is that the server can find the type from the ID, and that the type is not guessable by changing the ID's digits to mean a different type's record. Anything fetched through node(id:) must pass the same authorization checks as the normal query for that type: a global ID is an address, not a permission.

Stand-in: encoding IDs and resolving node

The stand-in below does the server side by hand: it encodes and decodes global IDs, keeps a registry that maps each type name to a function that loads an object, and resolves node and nodes. A resolver that returns an object also has to say which type it is (__typename), as real servers do through resolveType for interfaces.

Node.js Global IDs and a node resolver

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The local id 7 exists in two tables, but the two global IDs differ, so a cache or a refetch can never confuse a book with an author. A bad ID gives null, never a stack trace.

Why client caches love it

A normalized client cache (see Clients, Apollo and Code Generation) stores each object once under a key built from its type and ID, so that every query showing the same object updates when one of them returns fresh data. With global IDs the key is the ID itself, and it is unambiguous even when two types use the same database numbers.

The node query adds refetching. If a mutation fails halfway, or a push message says "object X changed", the client can reload just that object without knowing which root field normally returns it. Relay builds its useRefetchableFragment on exactly this: a component with a fragment on a Node type can reload itself by ID.

Stand-in: refetching a stale object by ID

This stand-in imitates a small normalized cache. Two "screens" show the same book through different queries. When the server data changes, one node(id) refetch updates the single cache entry, and both screens read the new value.

Node.js A normalized cache refetching through node(id)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Both screens changed after a single refetch because they read the same cache entry. That is the effect of identifying objects by one global, stable key.

Designing with Node in mind

  • Implement Node on every entity that has an identity and that clients may cache or refetch: User, Book, Order. Do not implement it on value objects that only exist inside another object (an Address inside an order may not need an ID of its own).
  • Keep id for the global ID. If clients also need the database key (to build a URL, say), add a separate field such as databaseId: Int! or slug. Do not expose raw database IDs as id and make the global one a second field: tools expect id to be global.
  • Make loaders cheap and batch-friendly. nodes(ids:) is an invitation to load many objects; group the IDs by type and use DataLoader.
  • Check permissions in the loader. node can reach anything, so it must apply the same rules as the type's normal queries.
  • Plan IDs early. Changing the ID scheme after clients cache IDs in local storage or URLs is painful.

Combine this convention with the connection pattern from Pagination: Offset, Cursor and Connections, which also comes from Relay, and the schema is understood by Relay and by most generic tooling. See Schema Design Best Practices for the broader advice.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why is a plain database id like 7 not enough as a GraphQL id across a whole schema?

    Global identification needs ids that are unique across all types, usually by combining the type name and the local id.
  2. 2. What does the node(id: ID!) field return?

    It returns the Node interface, so clients use inline fragments for type-specific fields. Unknown ids give null.
  3. 3. Clients are told to treat global IDs as opaque. What does that allow the server to do?

    If clients never parse IDs, the server may rework the format. Base64 is not security.
  4. 4. A global id decodes to Order:9001. What must the server still do in the node loader?

    An ID is an address, not a permission. Any route to the object must check access.
  5. 5. Where should a database primary key go if clients also need it?

    Tools expect id to be the global ID. Expose the local key under another name if you must.

Summary

  • Global Object Identification gives every important object an id unique across the schema and a generic node(id:) query (plus optional nodes(ids:)) that returns the Node interface.
  • Global IDs usually combine type and local id (often Base64-encoded) and are opaque: clients pass them back and never parse them.
  • Normalized caches key objects by global ID, and node enables refetching a single object without knowing its usual root field.
  • Implement Node on entities, not on value objects; keep id global and expose database keys separately.
  • Check authorization in the node loader, batch loads by type, and decide the ID scheme early.

Next, see how whole GraphQL servers are put together around databases and existing services in GraphQL Server Architectures.