@require_graphql_subschema to manage large schema

[Keweiqu]

As an opposite direction of composite schema, by creating subschemas, we can manage the schema size and have the ability to gradually reveal more parts of the schema to the model as it sees fit. This is inspired by the claude skill. Concrete example below:

1 Entrypoint SDL

Contains the directive and the root fields. Each field is annotated with the subschema(s) it requires. Types referenced here are defined in the subschemas.

# entrypoint.graphql
directive @require_graphql_subschema(names: [String!]!) on FIELD_DEFINITION
type Query {
  # Task queries
  task(id: ID!): Task
    @require_graphql_subschema(names: ["TASK"])
  tasks(first: Int, after: ID): [Task!]!
    @require_graphql_subschema(names: ["TASK"])
  # Calendar queries
  calendarMeeting(id: ID!): CalendarMeeting
    @require_graphql_subschema(names: ["CALENDAR"])
  meetings(start: Int!, end: Int!): [CalendarMeeting!]!
    @require_graphql_subschema(names: ["CALENDAR"])
}

2. Task subschema SDL
   Defines the Task domain types. No directive usage here—annotation is strictly at fields in the entrypoint or on field selections within objects (if you choose to gate nested fields too).

# task_subschema.graphql
type Task {
  id: ID!
  title: String!
  priority: TaskPriority!
  ownerId: ID
  # If you need nested gating on object fields, you can apply the directive here too.
  # comments: [TaskComment!]! @require_graphql_subschema(names: ["TASK"])
}
enum TaskPriority {
  HIGH
  MID
  LOW
}
type TaskComment {
  id: ID!
  text: String!
  createdAt: Int!
}

3. Calendar subschema SDL
   Defines calendar domain types. Again, no directive usage here unless you want to gate specific nested fields.

# calendar_subschema.graphql
type CalendarMeeting {
  id: ID!
  title: String!
  startTime: Int!
  endTime: Int!
  attendees: [Employee!]! @require_graphql_subschema(names: ["EMPLOYEE"])
  room: Room
}
type Room {
  id: ID!
  displayName: String!
}

[Keweiqu]

@michael-watson @michaelstaib

[michael-watson]

I've seen similar patterns like this in the past! My first thought/question is what is the end goal in managing the large schema? I'm assuming this is primarily to have smaller portions of the schema for LLMs to help anyone reason with a larger schema which I see falling into two buckets:

1. Schema updates
2. Generating operations (which could need schema updates)

For generating operations, I have seen a lot of success by looking only at the root query to determine the starting shape. Then reconstructing a representation of only the relevant bits. It seems like the pattern described here would be able to accomplish something similar where your LLM can have the full context of the root and fan out to other subgraphs as needed. The main challenge I see is someone having to have all of those files locally (or a setup to get those subschemas) to have an Agent follow this. One solution to this would be to extend the Introspection API or add a root Query field to return a specific subschema with an optional name args where if name is undefined, it returns the root schema. This would make it easy for someone with just the GraphQL API url to get started on the same workflow.

For schema updates, I think anything that breaks the schema into sub schemas is the right direction. I do think there is something missing from GraphQL specifically for LLMs to understand these things. I hope to share some stuff I built 🔜

[Keweiqu]

The motivation why we proposed this is to generating operations, you are indeed right we essentially extended the introspection API which allows the agent to create a GraphQL query that fetches a subschema based on subschema name.

[HieuNguyen202]

Hey @michael-watson , I'm Hugh Nguyen. I've been hacking on this idea with Kewei at Meta. You got an interesting point about returning the root schema (for LLM) when the name is undefined. Our implementation co-locate the GraphQL server and the Agent codes, so we have not had a needed for this. But, extending the introspection API to support subschema use cases for AI sound reasonable, especially if it can remove the need for the root schema being defined in the Agent (graphql client) making schema updates contained in the graphql server. This also has in interesting trade-off, which is all agents now will have the same root schema - Agents can't define which set of root fields should be initially loaded into the Agent's context window.

I do think there is something missing from GraphQL specifically for LLMs to understand these things.

We currently use very basic prompting to tech the LLM to load the subschemas as it encounter @require_graphql_subschema "directives", but it doesn't work 100% of the time. Would love to see what you will come up with.