Operation signatures

When you're viewing your graph's

Though each operation in the above example is named MyQuery, GraphOS treats them as different operations because they request different fields.

To help GraphOS identify functionally identical operations, your router generates an operation signature for each operation it reports to Studio. This signature is a normalized representation for an operation with deterministic field order, whitespace, and values for in-line argument values.

Why do we need an operation signature?

Consider the following operations:

1
query GetPostDetails($postId: String!) {
2
  post(id: $postId) {
3
    author
4
    content
5
  }
6
}
7

8
query GetPostDetails($postId: String!) {
9
  post(id: $postId) {
10
    content # Different field order
11
    author
12
  }
13
}
14

15
query GetPostDetails($postId: String!) {
16
  post(id: $postId) {
17
    writer: author # Field alias
18
    content
19
  }
20
}

Despite some cosmetic differences (including comments), all these operations execute identically on a particular GraphQL server. Therefore, Studio should group them when displaying performance metrics.

Apollo libraries use a

Signature algorithm

Feel free to

The signature algorithm performs the following modifications on an operation to generate its signature:

1. Transform in-line argument values

If an operation includes any in-line argument values, the algorithm transforms those values according to their type:

• Boolean and enum values are preserved.
• Int and Float values are replaced with 0.
• String, list, and object values are replaced with their "empty" counterpart ("", [], or {}).

2. Remove extraneous characters

The algorithm removes most unnecessary characters in the operation definition, including comments and redundant whitespace.

If the operation document includes multiple operations, then operations besides the executed operation are removed.

If the operation document includes fragments that aren't used by the executed operation, then those fragments are removed (other fragments are preserved).

3. Reorder definitions

Any preserved fragment definitions appear first, sorted alphanumerically by fragment name. The definition of the executed operation appears after all fragment definitions.

Fields

For a given object or fragment's fields, field selections are sorted in the following order:

1. Individually listed fields
2. Named fragment spreads
3. In-line fragments

Within each of these, sorting is alphanumeric by field name or fragment name.

Field aliases

All field aliases are removed. If an operation includes three instances of the same field with different aliases, then that field is listed in the signature three times with its non-aliased name.

Directives and arguments

If multiple directives are applied to the same location in the operation document, those directives are sorted alphanumerically.

If a single field accepts multiple arguments, those arguments are sorted alphanumerically by name.

Example signature

Consider this operation:

1
# Operation definition needs to appear after all fragment definitions
2
query GetUser {
3
  user(id: "hello") {
4
    # Replace string argument value with empty string
5
    ...NameParts # Spread fragment needs to appear after individual fields
6
    timezone # Needs to appear alphanumerically after `name`
7
    aliased: name # Need to remove alias
8
  }
9
}
10

11
# Excessive characters (including this comment!) need to be removed
12

13
fragment NameParts on User {
14
  firstname
15
  lastname
16
}

The signature algorithm generates the following signature for this operation:

1
fragment NameParts on User {
2
  firstname
3
  lastname
4
}
5
query GetUser {
6
  user(id: "") {
7
    name
8
    timezone
9
    ...NameParts
10
  }
11
}

Signatures and sensitive data

The signature algorithm's primary purpose is to group operations that differ only cosmetically in terms of whitespace, field order, aliases, etc. As an additional effect, the algorithm does

However, you should not rely on this! Ideally, your sensitive data should never reach GraphOS Studio in the first place. Whenever possible,

Logging signatures at runtime

To view operation signature hashes in your own logging tools, you can create an

1
const logOperationSignaturePlugin = {
2
  async requestDidStart() {
3
    return {
4
      async didResolveOperation(ctx) {
5
        console.log({
6
          queryHash: ctx.queryHash,
7
          operationName: ctx.operationName,
8
        });
9
      },
10
    };
11
  },
12
};
13

14
const server = new ApolloServer({
15
  schema,
16
  plugins: [logOperationSignaturePlugin],
17
});

1
const logOperationSignaturePlugin = {
2
  async requestDidStart() {
3
    return {
4
      async didResolveOperation(ctx) {
5
        console.log({
6
          queryHash: ctx.queryHash,
7
          operationName: ctx.operationName,
8
        });
9
      },
10
    };
11
  },
12
};
13

14
const server = new ApolloServer({
15
  schema,
16
  plugins: [logOperationSignaturePlugin],
17
});