title: Relay Compiler Vocabulary
description: Key terms and concepts used by the Relay GraphQL compiler and framework.
version: 1.0.0
modified: '2026-05-02'
terms:
  - term: Relay
    definition: >-
      An open-source JavaScript framework developed by Meta for building data-driven
      React applications using GraphQL. The framework emphasizes co-location of data
      requirements with components and ahead-of-time compilation.

  - term: Relay Compiler
    definition: >-
      The ahead-of-time build tool that scans JavaScript/TypeScript source files for
      GraphQL fragment definitions, validates them against the schema, optimizes queries,
      and generates runtime artifacts and type definitions.

  - term: Fragment
    definition: >-
      A named, reusable piece of a GraphQL query co-located with the React component
      that needs the data. Relay compiles fragments into optimized query artifacts.

  - term: Fragment Spread
    definition: >-
      The syntax (...FragmentName) used to include a fragment within a query or parent
      fragment, allowing composition of data requirements.

  - term: Data Masking
    definition: >-
      Relay's isolation mechanism where a component can only access data from its own
      fragment, not data requested by parent or sibling fragments.

  - term: Normalization
    definition: >-
      Relay's process of storing GraphQL response data in a normalized in-memory store
      where each object is stored once and referenced by ID.

  - term: Store
    definition: >-
      Relay's normalized in-memory cache that holds all fetched GraphQL data,
      automatically updating components when their subscribed data changes.

  - term: Preloaded Query
    definition: >-
      A query initiated before a component renders (via loadQuery()) to avoid
      network request waterfalls when navigating between views.

  - term: Connection
    definition: >-
      The GraphQL Cursor Connections specification pattern used for paginated lists,
      with edges, nodes, cursors, and pageInfo fields. Annotated with @connection.

  - term: '@argumentDefinitions'
    definition: >-
      A Relay directive that declares typed arguments a fragment accepts, enabling
      fragments to be configured by their parent.

  - term: '@arguments'
    definition: >-
      A Relay directive used at a fragment spread to pass values to the fragment's
      declared @argumentDefinitions.

  - term: '@refetchable'
    definition: >-
      A Relay directive that auto-generates a refetch query for a fragment,
      enabling the usePaginationFragment or useRefetchableFragment hooks.

  - term: '@connection'
    definition: >-
      A Relay directive that marks a connection field for use with pagination hooks,
      providing cursor-based forward and backward pagination.

  - term: '@required'
    definition: >-
      A Relay directive that specifies how null values on a field should be handled
      at runtime (THROW, LOG, or NONE).

  - term: Compiler Artifact
    definition: >-
      Files generated by the Relay compiler from GraphQL fragments and queries,
      including optimized query strings and TypeScript/Flow type definitions.

  - term: Type Generation
    definition: >-
      The Relay compiler's automatic generation of TypeScript or Flow types from
      GraphQL fragment definitions, providing full type safety for component props.

  - term: useFragment
    definition: >-
      A React hook that reads data from a Relay fragment in the normalized store
      and subscribes the component to updates when that data changes.

  - term: usePaginationFragment
    definition: >-
      A React hook for fragments annotated with @connection and @refetchable that
      provides loadNext/loadPrevious functions for cursor-based pagination.

  - term: useMutation
    definition: >-
      A React hook that executes a GraphQL mutation and optionally applies an
      optimistic update to the local store before the server responds.