Automatic Global Object Identification #1232

enisdenjo · 2025-06-12T11:58:29Z

Automatic implementation of the GraphQL Global Object Identification Specification by adding a Node interface and node(id: ID!): Node field to the Query type.

The Node interface will have a nodeId (not id!) field used as the global identifier. It is intentionally not id to avoid collisions with existing id fields in subgraphs.

"""
An object with a globally unique `ID`.
"""
interface Node {
  """
  A globally unique identifier. Can be used in various places throughout the system to identify this single value.
  """
  nodeId: ID!
}

extend type Query {
  """
  Fetches an object given its globally unique `ID`.
  """
  node(
    """
    The globally unique `ID`.
    """
    nodeId: ID!
  ): Node
}

Features

Not a subgraph
No changes necessary to any of the subgraphs
No extra network requests

See global-object-identification E2E tests which adds Global Object Identification to the the usual Apollo Federation inventory+products+users+reviews example.

Why `nodeId`?

interface Node {
- id: ID!
+ nodeId: ID!
}

We use the nodeId as the Global Object Identifier avoid possible collisions with id fields that are common to exist in subgraphs.

Hive Gateway

CLI

// gateway.config.ts

import { defineConfig } from '@graphql-hive/gateway';

export const gatewayConfig = defineConfig({
  globalObjectIdentification: true,
});

Programmatic Usage

// index.ts

import { createGatewayRuntime } from '@graphql-hive/gateway-runtime'

export const gateway = createGatewayRuntime({
  globalObjectIdentification: true,
})

Configuring

Instead of passing true to the globalObjectIdentification option that enables and sets the defaults, you can instead pass a configuration object and adjust the behaviour.

interface ResolvedGlobalId {
  /** The concrete type of the globally identifiable node. */
  type: string;
  /** The actual ID of the concrete type in the relevant source. */
  id: string;
}

interface GlobalObjectIdentificationOptions {
  /**
   * The field name of the global ID on the Node interface.
   *
   * The `Node` interface defaults to `nodeId`, not `id`! It is intentionally not
   * `id` to avoid collisions with existing `id` fields in subgraphs.
   *
   * @default nodeId
   */
  nodeIdField?: string;
  /**
   * Takes a type name and an ID specific to that type name, and returns a
   * "global ID" that is unique among all types.
   *
   * Note that the global ID can contain a JSON stringified object which
   * contains multiple key fields needed to identify the object.
   *
   * @default import('graphql-relay').toGlobalId
   */
  toGlobalId?(type: string, id: string | number): string;
  /**
   * Takes the "global ID" created by toGlobalID, and returns the type name and ID
   * used to create it.
   *
   * @default import('graphql-relay').fromGlobalId
   */
  fromGlobalId?(globalId: string): ResolvedGlobalId;
}

TODOs

Plural nodes(ids: [ID!]!) for batching
Change nodeId field name in Node interface
Don't collide with existing Node interfaces
~~What to do? Remove from subgraphs? Merge?~~ Error? ✅
Example how to use in Relay and Apollo Client
Respect subgraph type ownership
Interface support (interface Actor implements Node { ... })
Unions should work, test to make sure

Ref GW-268

theguild-bot · 2025-06-12T12:01:09Z

🚀 Snapshot Release (`alpha`)

The latest changes of this PR are available as alpha on npm (based on the declared changesets):

Package	Version	Info
`@graphql-tools/federation`	`3.3.0-alpha-528b9ad3ecc81ee9fc6444ab0046799f44e1cd10`	npm ↗︎ unpkg ↗︎
`@graphql-mesh/fusion-runtime`	`0.12.0-alpha-528b9ad3ecc81ee9fc6444ab0046799f44e1cd10`	npm ↗︎ unpkg ↗︎
`@graphql-hive/gateway`	`1.15.3-alpha-528b9ad3ecc81ee9fc6444ab0046799f44e1cd10`	npm ↗︎ unpkg ↗︎
`@graphql-hive/nestjs`	`1.0.17-alpha-528b9ad3ecc81ee9fc6444ab0046799f44e1cd10`	npm ↗︎ unpkg ↗︎
`@graphql-hive/plugin-aws-sigv4`	`1.0.14-alpha-528b9ad3ecc81ee9fc6444ab0046799f44e1cd10`	npm ↗︎ unpkg ↗︎
`@graphql-mesh/plugin-opentelemetry`	`1.3.61-alpha-528b9ad3ecc81ee9fc6444ab0046799f44e1cd10`	npm ↗︎ unpkg ↗︎
`@graphql-mesh/plugin-prometheus`	`1.3.49-alpha-528b9ad3ecc81ee9fc6444ab0046799f44e1cd10`	npm ↗︎ unpkg ↗︎
`@graphql-hive/gateway-runtime`	`1.10.0-alpha-528b9ad3ecc81ee9fc6444ab0046799f44e1cd10`	npm ↗︎ unpkg ↗︎

theguild-bot · 2025-06-12T12:03:57Z