Federation Scalars

Apollo Federation scalar types used in pyck

Audience: Programmer

Federation scalars are special scalar types used by Apollo Federation for distributed GraphQL schema composition. These scalars are primarily used internally by the federation runtime and are not typically used directly in client queries.

Available Federation Scalars

join__FieldSet

A string representation of a selection set used to specify fields for federation key directives.

Type: String

Usage: Used in @key directives to define entity keys across services.

type InventoryItem @key(fields: "id") @key(fields: "sku") {
  id: ID!
  sku: String!
  name: String!
}

link__Import

Represents an import statement for federation directives and types.

Type: String

Usage: Used to import federation specifications and features.

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.3", import: ["@key", "@requires"])

Understanding Federation in pyck

pyck uses Apollo Federation to compose multiple GraphQL services into a single unified API:

Attachments Service: Handles file uploads and attachments
Inventory Service: Manages inventory items, movements, and repositories
MainData Service: Handles master data (customers, suppliers, data types)
Management Service: Manages companies, users, and access control
Picking Service: Handles picking orders and order fulfillment
Receiving Service: Manages inbound shipments and receiving
WorkflowService: Orchestrates Temporal workflows

Federation Directives

While not scalars, these directives work with federation scalars:

@key: Defines the primary key for an entity
@requires: Specifies fields needed from other services
@provides: Indicates fields provided by this service
@external: Marks fields defined in another service
@extends: Extends a type from another service

Example: Federated Entity

# In Inventory Service
type InventoryItem @key(fields: "id") {
  id: ID!
  sku: String!
  name: String!
  stock: Stock
}

# In Picking Service
extend type InventoryItem @key(fields: "id") {
  id: ID! @external
  pickingOrders: [PickingOrderItem!]!
}

Client Perspective

From a client's perspective, federation is transparent. You query the unified schema without needing to know about the underlying service boundaries:

query {
  inventoryItem(id: "item_123") {
    # From Inventory Service
    id
    sku
    name
    stock {
      available
      reserved
    }
    
    # From Picking Service (federated)
    pickingOrders {
      id
      quantity
      pickingOrder {
        referenceId
        status
      }
    }
  }
}

Best Practices

Let Federation Handle It: These scalars are managed by the federation runtime
Focus on the API: As a client developer, work with the composed schema
Understand Service Boundaries: Knowing which service owns which data can help with performance optimization