Skip to content

graphql.mdx

Latest commit

 

History

History
498 lines (329 loc) · 18 KB

graphql.mdx

File metadata and controls

498 lines (329 loc) · 18 KB
Raw
title Graphql
description Graphql protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

GraphQL Protocol Support

GraphQL is a query language for APIs and a runtime for executing those queries.

It provides a complete and understandable description of the data in your API,

gives clients the power to ask for exactly what they need, and enables powerful

developer tools.

Overview

GraphQL provides:

  • Type-safe schema definition

  • Precise data fetching (no over/under-fetching)

  • Introspection and documentation

  • Real-time subscriptions

  • Batched queries with DataLoader

Use Cases

  1. Modern API Development

  • Mobile and web applications

  • Microservices federation

  • Real-time dashboards

  1. Data Aggregation

  • Multi-source data integration

  • Complex nested queries

  • Efficient data loading

  1. Developer Experience

  • Self-documenting API

  • Type safety and validation

  • GraphQL playground

See also: https://graphql.org/

See also: https://spec.graphql.org/

@example GraphQL Query

query GetCustomer($id: ID!) \{

customer(id: $id) \{

id

name

email

orders(limit: 10, status: "active") \{

id

total

items \{

product \{

name

price

\}

\}

\}

\}

\}

@example GraphQL Mutation

mutation CreateOrder($input: CreateOrderInput!) \{

createOrder(input: $input) \{

id

orderNumber

status

\}

\}
**Source:** `packages/spec/src/api/graphql.zod.ts`

TypeScript Usage

import { FederationEntity, FederationEntityKey, FederationExternalField, FederationGateway, FederationProvides, FederationRequires, GraphQLConfig, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryConfig, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLResolverConfig, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig, SubgraphConfig } from '@objectstack/spec/api';
import type { FederationEntity, FederationEntityKey, FederationExternalField, FederationGateway, FederationProvides, FederationRequires, GraphQLConfig, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryConfig, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLResolverConfig, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig, SubgraphConfig } from '@objectstack/spec/api';

// Validate data
const result = FederationEntity.parse(data);

FederationEntity

Properties

Property Type Required Description
typeName string ✅ GraphQL type name for this entity
keys { fields: string; resolvable: boolean }[] ✅ Entity key definitions
externalFields { field: string; ownerSubgraph?: string }[] optional Fields owned by other subgraphs
requires { field: string; fields: string }[] optional Required external fields for computed fields
provides { field: string; fields: string }[] optional Fields provided during resolution
owner boolean ✅ Whether this subgraph is the owner of this entity

FederationEntityKey

Properties

Property Type Required Description
fields string ✅ Selection set of fields composing the entity key
resolvable boolean ✅ Whether entities can be resolved from this subgraph

FederationExternalField

Properties

Property Type Required Description
field string ✅ Field name marked as external
ownerSubgraph string optional Subgraph that owns this field

FederationGateway

Properties

Property Type Required Description
enabled boolean ✅ Enable GraphQL Federation gateway mode
version Enum<'v1' | 'v2'> ✅ Federation specification version
subgraphs { name: string; url: string; schemaSource: Enum<'introspection' | 'file' | 'registry'>; schemaPath?: string; … }[] ✅ Subgraph configurations
serviceDiscovery { type: Enum<'static' | 'dns' | 'consul' | 'kubernetes'>; pollIntervalMs?: integer; namespace?: string } optional Service discovery configuration
queryPlanning { strategy: Enum<'parallel' | 'sequential' | 'adaptive'>; maxDepth?: integer; dryRun: boolean } optional Query planning configuration
composition { conflictResolution: Enum<'error' | 'first_wins' | 'last_wins'>; validate: boolean } optional Schema composition configuration
errorHandling { includeSubgraphName: boolean; partialErrors: Enum<'propagate' | 'nullify' | 'reject'> } optional Error handling configuration

FederationProvides

Properties

Property Type Required Description
field string ✅ Field that provides additional entity fields
fields string ✅ Selection set of provided fields (e.g., "name price")

FederationRequires

Properties

Property Type Required Description
field string ✅ Field with the requirement
fields string ✅ Selection set of required fields (e.g., "price weight")

GraphQLConfig

Properties

Property Type Required Description
enabled boolean optional Enable GraphQL API
path string optional GraphQL endpoint path
playground { enabled?: boolean; path?: string } optional GraphQL Playground configuration
schema { autoGenerateTypes?: boolean; types?: { name: string; object: string; description?: string; fields?: object; … }[]; queries?: { name: string; object: string; type: Enum<'get' | 'list' | 'search'>; description?: string; … }[]; mutations?: { name: string; object: string; type: Enum<'create' | 'update' | 'delete' | 'upsert' | 'custom'>; description?: string; … }[]; … } optional Schema generation configuration
dataLoaders { name: string; source: string; batchFunction: object; cache?: object; … }[] optional DataLoader configurations
security { depthLimit?: object; complexity?: object; rateLimit?: object; persistedQueries?: object } optional Security configuration
federation { enabled?: boolean; version?: Enum<'v1' | 'v2'>; subgraphs: { name: string; url: string; schemaSource?: Enum<'introspection' | 'file' | 'registry'>; schemaPath?: string; … }[]; serviceDiscovery?: object; … } optional GraphQL Federation gateway configuration

GraphQLDataLoaderConfig

Properties

Property Type Required Description
name string ✅ DataLoader name
source string ✅ Source object or datasource
batchFunction { type: Enum<'findByIds' | 'query' | 'script' | 'custom'>; keyField?: string; query?: string; script?: string; … } ✅ Batch function configuration
cache { enabled: boolean; keyFn?: string } optional DataLoader caching
options { batch: boolean; cache: boolean; maxCacheSize?: integer } optional DataLoader options

GraphQLDirectiveConfig

Properties

Property Type Required Description
name string ✅ Directive name (camelCase)
description string optional Directive description
locations Enum<'QUERY' | 'MUTATION' | 'SUBSCRIPTION' | 'FIELD' | 'FRAGMENT_DEFINITION' | 'FRAGMENT_SPREAD' | 'INLINE_FRAGMENT' | 'VARIABLE_DEFINITION' | 'SCHEMA' | 'SCALAR' | 'OBJECT' | 'FIELD_DEFINITION' | 'ARGUMENT_DEFINITION' | 'INTERFACE' | 'UNION' | 'ENUM' | 'ENUM_VALUE' | 'INPUT_OBJECT' | 'INPUT_FIELD_DEFINITION'>[] ✅ Directive locations
args Record<string, { type: string; description?: string; defaultValue?: any }> optional Directive arguments
repeatable boolean ✅ Can be applied multiple times
implementation { type: Enum<'auth' | 'validation' | 'transform' | 'cache' | 'deprecation' | 'custom'>; handler?: string } optional Directive implementation

GraphQLDirectiveLocation

Allowed Values

  • QUERY
  • MUTATION
  • SUBSCRIPTION
  • FIELD
  • FRAGMENT_DEFINITION
  • FRAGMENT_SPREAD
  • INLINE_FRAGMENT
  • VARIABLE_DEFINITION
  • SCHEMA
  • SCALAR
  • OBJECT
  • FIELD_DEFINITION
  • ARGUMENT_DEFINITION
  • INTERFACE
  • UNION
  • ENUM
  • ENUM_VALUE
  • INPUT_OBJECT
  • INPUT_FIELD_DEFINITION

GraphQLMutationConfig

Properties

Property Type Required Description
name string ✅ Mutation field name (camelCase recommended)
object string ✅ Source ObjectQL object name
type Enum<'create' | 'update' | 'delete' | 'upsert' | 'custom'> ✅ Mutation type
description string optional Mutation description
input { typeName?: string; fields?: object; validation?: object } optional Input configuration
output { type: Enum<'object' | 'payload' | 'boolean' | 'custom'>; includeEnvelope: boolean; customType?: string } optional Output configuration
transaction { enabled: boolean; isolationLevel?: Enum<'read_uncommitted' | 'read_committed' | 'repeatable_read' | 'serializable'> } optional Transaction configuration
authRequired boolean ✅ Require authentication
permissions string[] optional Required permissions
hooks { before?: string[]; after?: string[] } optional Lifecycle hooks

GraphQLPersistedQuery

Properties

Property Type Required Description
enabled boolean ✅ Enable persisted queries
mode Enum<'optional' | 'required'> ✅ Persisted query mode (optional: allow both, required: only persisted)
store { type: Enum<'memory' | 'redis' | 'database' | 'file'>; connection?: string; ttl?: integer } optional Query store configuration
apq { enabled: boolean; hashAlgorithm: Enum<'sha256' | 'sha1' | 'md5'>; cache?: object } optional Automatic Persisted Queries configuration
allowlist { enabled: boolean; queries?: { id: string; operation?: string; query?: string }[]; source?: string } optional Query allow list configuration
security { maxQuerySize?: integer; rejectIntrospection: boolean } optional Security configuration

GraphQLQueryComplexity

Properties

Property Type Required Description
enabled boolean ✅ Enable query complexity limiting
maxComplexity integer ✅ Maximum query complexity
defaultFieldComplexity integer ✅ Default complexity per field
fieldComplexity Record<string, integer | { base: integer; multiplier?: string; calculator?: string }> optional Per-field complexity configuration
listMultiplier number ✅ Multiplier for list fields
onComplexityExceeded Enum<'reject' | 'log' | 'warn'> ✅ Action when complexity exceeded
errorMessage string optional Custom error message for complexity violations

GraphQLQueryConfig

Properties

Property Type Required Description
name string ✅ Query field name (camelCase recommended)
object string ✅ Source ObjectQL object name
type Enum<'get' | 'list' | 'search'> ✅ Query type
description string optional Query description
args Record<string, { type: string; description?: string; defaultValue?: any }> optional Query arguments
filtering { enabled?: boolean; fields?: string[]; operators?: Enum<'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'contains' | 'startsWith' | 'endsWith' | 'isNull' | 'isNotNull'>[] } optional Filtering capabilities
sorting { enabled?: boolean; fields?: string[]; defaultSort?: object } optional Sorting capabilities
pagination { enabled?: boolean; type?: Enum<'offset' | 'cursor' | 'relay'>; defaultLimit?: integer; maxLimit?: integer; … } optional Pagination configuration
fields { required?: string[]; selectable?: string[] } optional Field selection configuration
authRequired boolean optional Require authentication
permissions string[] optional Required permissions
cache { enabled?: boolean; ttl?: integer; key?: string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } } optional Query caching

GraphQLQueryDepthLimit

Properties

Property Type Required Description
enabled boolean ✅ Enable query depth limiting
maxDepth integer ✅ Maximum query depth
ignoreFields string[] optional Fields excluded from depth calculation
onDepthExceeded Enum<'reject' | 'log' | 'warn'> ✅ Action when depth exceeded
errorMessage string optional Custom error message for depth violations

GraphQLRateLimit

Properties

Property Type Required Description
enabled boolean ✅ Enable rate limiting
strategy Enum<'token_bucket' | 'fixed_window' | 'sliding_window' | 'cost_based'> ✅ Rate limiting strategy
global { maxRequests: integer; windowMs: integer } optional Global rate limits
perUser { maxRequests: integer; windowMs: integer } optional Per-user rate limits
costBased { enabled: boolean; maxCost: integer; windowMs: integer; useComplexityAsCost: boolean } optional Cost-based rate limiting
operations Record<string, { maxRequests: integer; windowMs: integer }> optional Per-operation rate limits
onLimitExceeded Enum<'reject' | 'queue' | 'log'> ✅ Action when rate limit exceeded
errorMessage string optional Custom error message for rate limit violations
includeHeaders boolean ✅ Include rate limit headers in response

GraphQLResolverConfig

Properties

Property Type Required Description
path string ✅ Resolver path (Type.field)
type Enum<'datasource' | 'computed' | 'script' | 'proxy'> ✅ Resolver implementation type
implementation { datasource?: string; query?: string; expression?: string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object }; dependencies?: string[]; … } optional Implementation configuration
cache { enabled?: boolean; ttl?: integer; keyArgs?: string[] } optional Resolver caching

GraphQLScalarType

Allowed Values

  • ID
  • String
  • Int
  • Float
  • Boolean
  • DateTime
  • Date
  • Time
  • JSON
  • JSONObject
  • Upload
  • URL
  • Email
  • PhoneNumber
  • Currency
  • Decimal
  • BigInt
  • Long
  • UUID
  • Base64
  • Void

GraphQLSubscriptionConfig

Properties

Property Type Required Description
name string ✅ Subscription field name (camelCase recommended)
object string ✅ Source ObjectQL object name
events Enum<'created' | 'updated' | 'deleted' | 'custom'>[] ✅ Events to subscribe to (not yet implemented — no subscription transport exists; see #3197)
description string optional Subscription description
filter { enabled: boolean; fields?: string[] } optional Subscription filtering
payload { includeEntity: boolean; includePreviousValues: boolean; includeMeta: boolean } optional Payload configuration
authRequired boolean ✅ Require authentication
permissions string[] optional Required permissions
rateLimit { enabled: boolean; maxSubscriptionsPerUser: integer; throttleMs?: integer } optional Subscription rate limiting

GraphQLTypeConfig

Properties

Property Type Required Description
name string ✅ GraphQL type name (PascalCase recommended)
object string ✅ Source ObjectQL object name
description string optional Type description
fields { include?: string[]; exclude?: string[]; mappings?: Record<string, { graphqlName?: string; graphqlType?: string; description?: string; deprecationReason?: string; … }> } optional Field configuration
interfaces string[] optional GraphQL interface names
isInterface boolean ✅ Define as GraphQL interface
directives { name: string; args?: Record<string, any> }[] optional GraphQL directives

SubgraphConfig

Properties

Property Type Required Description
name string ✅ Unique subgraph identifier
url string ✅ Subgraph endpoint URL
schemaSource Enum<'introspection' | 'file' | 'registry'> ✅ How to obtain the subgraph schema
schemaPath string optional Path to schema file (SDL format)
entities { typeName: string; keys: { fields: string; resolvable: boolean }[]; externalFields?: { field: string; ownerSubgraph?: string }[]; requires?: { field: string; fields: string }[]; … }[] optional Entity definitions for this subgraph
healthCheck { enabled: boolean; path: string; intervalMs: integer } optional Subgraph health check configuration
forwardHeaders string[] optional HTTP headers to forward to this subgraph