Define Advanced Keys

Depending on your entities' fields and usage, you may need to use more advanced @keys. For example, you may need to define a compound @key if multiple fields are required to uniquely identify an entity. If different subgraphs interact with different fields of an entity, you may need to define multiple—and sometimes differing—@keys for the entity.

Compound @keys

A single @key can consist of multiple fields, the combination of which uniquely identifies an entity. This is called a compound or composite key. In the following example, the combination of both username and domain fields is required to uniquely identify the User entity:

1
type User @key(fields: "username domain") {
2
  username: String!
3
  domain: String!
4
}

Nested fields in compound @keys

Nested fields are often used in compound keys. In the following example, the User entity's @key consists of both a user's id and the id of that user's associated Organization:

1
type User @key(fields: "id organization { id }") {
2
  id: ID!
3
  organization: Organization!
4
}
5

6
type Organization {
7
  id: ID!
8
}

Multiple @keys

When different subgraphs interact with different fields of an entity, you may need to define multiple @keys for the entity. For example, a Reviews subgraph might refer to products by their ID, whereas an Inventory subgraph might use SKUs.

In the following example, the Product entity can be uniquely identified by either its id or its sku:

1
type Product @key(fields: "id") @key(fields: "sku") {
2
  id: ID!
3
  sku: String!
4
  name: String!
5
  price: Int
6
}

1
type Product @key(fields: "id") @key(fields: "id sku") {
2
  # ...
3
}

Referencing entities with multiple keys

A subgraph that references an entity without contributing any fields can use any @key fields in its stub definition. For example, if the Products subgraph defines the Product entity like this:

1
type Product @key(fields: "id") @key(fields: "sku") {
2
  id: ID!
3
  sku: String!
4
  name: String!
5
  price: Int
6
}

Then, a Reviews subgraph can use either id or sku in the stub definition:

1
# Either:
2
type Product @key(fields: "id", resolvable: false) {
3
  id: ID!
4
}
5

6
# Or:
7
type Product @key(fields: "sku", resolvable: false) {
8
  sku: String!
9
}

When resolving a reference for an entity with multiple keys, you can determine how to resolve it based on which key is present. For example, if you're using @apollo/subgraph, it could look like this:

1
// Products subgraph
2
const resolvers = {
3
  Product: {
4
    __resolveReference(productRepresentation) {
5
      if(productRepresentation.sku){
6
        return fetchProductBySku(productRepresentation.sku);
7
      } else {
8
        return fetchProductByID(productRepresentation.id);
9
      }
10
    }
11
  },
12
  // ...other resolvers...
13
}

Differing @keys across subgraphs

Although an entity commonly uses the exact same @key field(s) across subgraphs, you can alternatively use different @keys with different fields. For example, you can define a Product entity shared between subgraphs, one with sku and upc as its @keys, and the other with only upc as the @key field:

1
type Product @key(fields: "sku") @key(fields: "upc") {
2
  sku: ID!
3
  upc: String!
4
  name: String!
5
  price: Int
6
}

1
type Product @key(fields: "upc") {
2
  upc: String!
3
  inStock: Boolean!
4
}

To merge entities between subgraphs, the entity must have at least one shared field between subgraphs. For example, operations can't merge the Product entity defined in the following subgraphs because they don't share any fields specified in the @key selection set:

❌

type Product @key(fields: "sku") {
  sku: ID!
  name: String!
  price: Int
}

type Product @key(fields: "upc") {
  upc: String!
  inStock: Boolean!
}

Operations with differing @keys

Differing keys across subgraphs affect which of the entity's fields can be resolved from each subgraph. Requests can resolve fields if there is a traversable path from the root query to the fields.

Take these subgraph schemas as an example:

type Product @key(fields: "sku") {
  sku: ID!
  upc: String!
  name: String!
  price: Int
}

type Query {
  product(sku: ID!): Product
  products: [Product!]!
}

type Product @key(fields: "upc") {
  upc: String!
  inStock: Boolean!
}

The queries defined in the Products subgraph can always resolve all product fields because the product entity can be joined via the upc field present in both schemas.

On the other hand, queries added to the Inventory subgraph can't resolve fields from the Products subgraph:

type Product @key(fields: "sku") {
  sku: ID!
  upc: String!
  name: String!
  price: Int
}

type Product @key(fields: "upc") {
  upc: String!
  inStock: Boolean!
}

type Query {
  productsInStock: [Product!]!
}

The productsInStock query can't resolve fields from the Products subgraph since the Products subgraph's Product type definition doesn't include upc as a key field, and sku isn't present in the Inventory subgraph.

If the Products subgraph includes @key(fields: "upc"), all queries from the Inventory subgraph can resolve all product fields:

1
type Product @key(fields: "sku") @key(fields: "upc") {
2
  sku: ID!
3
  upc: String!
4
  name: String!
5
  price: Int
6
}

1
type Product @key(fields: "upc") {
2
  upc: String!
3
  inStock: Boolean!
4
}
5

6
type Query {
7
  productsInStock: [Product!]!
8
}

Next steps

If you haven't already, learn how to contribute entity fields to the supergraph and reference them from subgraphs that don't contribute any fields.