Relationships

In a relational database you express links with foreign keys and join tables. In GraphQL you express the same links far more directly: a relationship is simply a field whose type is another type. There is no special syntax — the type system you already know is all you need. What changes from one relationship to the next is only the shape of the field: a single value, a list, or a list on both sides.

One-to-one and one-to-many

The simplest link returns a single object. A Post belongs to exactly one Author, so the field’s type is just Author:

type Post {
  id: ID!
  title: String!
  author: Author!
}

The reverse direction is one-to-many: one author has many posts. The field type becomes a list, [Post!]!:

type Author {
  id: ID!
  name: String!
  posts: [Post!]!
}

That is the entire pattern. A “to-one” side returns a type; a “to-many” side returns a list of that type. The same two types can expose the relationship from both ends, letting a client walk in either direction.

Many-to-many

When both sides can have many of the other, you have a many-to-many relationship — say a Post carries several Tags, and each Tag is attached to many posts. In SDL this is just a list field on each type:

type Post {
  id: ID!
  title: String!
  tags: [Tag!]!
}

type Tag {
  id: ID!
  label: String!
  posts: [Post!]!
}

There is no visible “join table” in the schema — that bookkeeping lives in your data layer. The client only sees two types, each with a list field pointing at the other.

flowchart LR
  Author["type Author"]
  Post["type Post"]
  Tag["type Tag"]
  Author -->|"posts: [Post!]! (one-to-many)"| Post
  Post -->|"author: Author!"| Author
  Post -->|"tags: [Tag!]! (many-to-many)"| Tag
  Tag -->|"posts: [Post!]!"| Post

One-to-many between Author and Post; many-to-many between Post and Tag.

Resolving the other side

Declaring the field is half the job; the other half is the resolver that fetches the related data when a client actually selects that field. A resolver for a relationship field receives the parent object and uses its id to look up what is connected. Because GraphQL only runs a resolver when its field is requested, a client that asks for name but not posts never pays the cost of loading posts at all.

Crossing relationships, run for real

The schema below wires up a one-to-many (Author → posts) and a many-to-many (Post ↔ Tag), with resolvers that look up the other side by id. The query crosses three relationships in one request. Press Run.

JavaScript

(async () => {
  const { graphql, buildSchema } = await import('https://esm.sh/graphql@16');

  const schema = buildSchema(`
    type Author {
      id: ID!
      name: String!
      posts: [Post!]!
    }

    type Tag {
      id: ID!
      label: String!
      posts: [Post!]!
    }

    type Post {
      id: ID!
      title: String!
      author: Author!
      tags: [Tag!]!
    }

    type Query {
      author(id: ID!): Author
    }
  `);

  // Plain tables, the way a data layer would store them.
  const authors = { a1: { id: 'a1', name: 'Ada Lin' } };
  const tags = {
    t1: { id: 't1', label: 'design' },
    t2: { id: 't2', label: 'graphql' },
  };
  const posts = [
    { id: 'p1', title: 'Designing a graph', authorId: 'a1', tagIds: ['t1', 't2'] },
    { id: 'p2', title: 'Walking relationships', authorId: 'a1', tagIds: ['t2'] },
  ];

  // Build a Post object whose relationship fields resolve the other side.
  const buildPost = (p) => ({
    id: p.id,
    title: p.title,
    author: () => buildAuthor(authors[p.authorId]),
    tags: () => p.tagIds.map((id) => buildTag(tags[id])),
  });

  const buildTag = (t) => ({
    id: t.id,
    label: t.label,
    posts: () => posts.filter((p) => p.tagIds.includes(t.id)).map(buildPost),
  });

  const buildAuthor = (a) => ({
    id: a.id,
    name: a.name,
    // One-to-many: find every post whose authorId matches.
    posts: () => posts.filter((p) => p.authorId === a.id).map(buildPost),
  });

  const root = {
    author: ({ id }) => (authors[id] ? buildAuthor(authors[id]) : null),
  };

  const query = `
    {
      author(id: "a1") {
        name
        posts {
          title
          tags { label }
        }
      }
    }
  `;

  const result = await graphql({ schema, source: query, rootValue: root });
  console.log(JSON.stringify(result, null, 2));
})();

Trace the output: from one author we resolved the one-to-many posts, and inside each post we resolved the many-to-many tags. Each relationship field had its own resolver that looked up the connected records by id. Notice we never wrote a SQL JOIN — the graph is the join, expressed as nested field selections.