---
title: SubGraph plugin
description: Build public and internal API variants from one set of types and fields.
---
Use one set of type definitions to build several API variants. Tag types and fields with named
sub-graphs, then pass `subGraph` to `builder.toSchema()` to select a variant. This is separate from
Apollo Federation: a sub-graph here is a filtered view of your own schema.
## Install
```package-install
npm install --save @pothos/plugin-sub-graph
```
## Build public and internal schemas
Declare the sub-graph names in `SubGraphs`. In this example, types and fields belong to both variants
by default, while `internalNotes` is available only in the internal API:
playground-examples/plugin-sub-graph/schema.ts#definitions
The `subGraph` option selects which types and fields appear in the built schema:
playground-examples/plugin-sub-graph/schema.ts#selection
playground-examples/plugin-sub-graph/variant-internal/schema.ts#selection
playground-examples/plugin-sub-graph/variant-combined/schema.ts#selection
playground-examples/plugin-sub-graph/variant-shared/schema.ts#selection
`{ product { name } }` works in either variant. `{ product { internalNotes } }` fails GraphQL
validation against the Public variant. Calling `toSchema()` without a sub-graph retains the full schema.
## Combine variants
An array includes types and fields belonging to any listed sub-graph:
```typescript
const combinedSchema = builder.toSchema({ subGraph: ['Internal', 'Public'] });
```
The `all` form includes only membership shared by every listed sub-graph:
```typescript
const sharedSchema = builder.toSchema({ subGraph: { all: ['Internal', 'Public'] } });
```
For the example above, the combined schema includes `internalNotes`; the shared schema omits it.
## Membership options
Set `subGraphs` on a type or field to override its defaults. A type without this option uses
`subGraphs.defaultForTypes` from the builder.
A field's membership is determined in this order:
1. Its own `subGraphs` option.
2. Its parent type's `defaultSubGraphsForFields` option.
3. Its parent type's membership, when `subGraphs.fieldsInheritFromTypes` is `true`.
4. The builder's `subGraphs.defaultForFields` option.
5. An empty array.
`fieldsInheritFromTypes` defaults to `false`. An explicit empty array overrides the fallback, so
`defaultSubGraphsForFields: []` on a type makes its fields opt in individually.
## Inputs and missing types
Nullable arguments and input fields can also have `subGraphs`. Required arguments and input fields
cannot be removed from a retained field or input object: resolvers may depend on them being present.
The plugin rejects a schema that tries to remove one.
An output field is omitted when its return type is excluded. Other references can make a filtered
schema invalid, such as a retained union containing an excluded member or a required argument using
an excluded input type. Include those dependencies in the variant or exclude the referring field or
type as well. Build and validate each variant you intend to serve.
## Include unreachable types
Types that remain unreachable after filtering are normally omitted. The
`subGraphs.explicitlyIncludeType` callback retains matching types that already belong to the selected
sub-graph, even when no field reaches them.
For federation entities, `hasResolvableKey` can retain an otherwise unreachable external reference.
Use this as a separate builder setup with both plugins:
```typescript
import SchemaBuilder from '@pothos/core';
import FederationPlugin, { hasResolvableKey } from '@pothos/plugin-federation';
import SubGraphPlugin from '@pothos/plugin-sub-graph';
const builder = new SchemaBuilder<{
SubGraphs: 'Public' | 'Internal';
}>({
plugins: [SubGraphPlugin, FederationPlugin],
subGraphs: {
defaultForTypes: ['Public', 'Internal'],
fieldsInheritFromTypes: true,
explicitlyIncludeType: (type) => hasResolvableKey(type),
},
});
```