5.1Methods of Cost Analysis

There are different Methods of Cost Analysis:

• When conducted before executing the query, it is called Static Query Analysis.
• When conducted during query execution, it is referred to as Dynamic Query Analysis.
• When conducted after query execution, it is Query Response Analysis.

Different methods of Cost Analysis offer different semantics of precisely what their results mean, and thus do not always produce the same count and cost values. For example, Static Query Analysis could say that ten Users might be returned, where Query Response Analysis would show that only three Users were actually returned. Alternatively, Static Query Analysis could say that an Address with a Street and City might be returned, where Dynamic Query Analysis would show that the entire Address was returned as null and the Street and City resolvers were never executed.

The three types of Cost Analysis have inherent tradeoffs, and the relative strength of their advantages depends on the environment in which GraphQL is used. Therefore, different methods will be appropriate at different times, and sometimes it can be appropriate to run multiple methods of cost analysis. One environment could run Static Cost Analysis to protect against unsafe queries and Dynamic Query Analysis to charge an API Consumer via monetization. Another environment might prefer Query Response Analysis to get a tight bound on the real cost without adding any load to the backend server. Many combinations are possible.

5.2Inputs to Cost Analysis

All three Methods of Cost Analysis include an input of the GraphQL schema. For all of these methods, the unenhanced schema would not be sufficient to calculate the cost. Therefore, the input schema includes both the schema constructs which are part of the GraphQL specification, and additional information in the form of directives on that schema which provide:

• Numerical Weights on various schema constructs. These are used to calculate weighted sums for the result Costs.
• List Size configuration to aid in bounding the sizes of returned lists.

The Static Query Analysis method also uses an input of the transaction’s GraphQL query, while the Query Response Analysis uses as inputs both the GraphQL query and the GraphQL response. Dynamic Query Analysis can be embedded into the GraphQL execution engine with access to its state during execution.

5.3Results of Cost Analysis

Each of the three Methods of Cost Analysis yields two kinds of results: Counts and Costs. These two kinds of results from Cost Analysis MAY be provided as outputs of the whole Cost Analysis, or MAY be maintained only as internal data used as part of Cost Analysis. Furthermore, they may be skipped if it does not change the overall results of Cost Analysis, and may be stored in any form or calculated in any order. The purpose of describing them here is to explain a straightforward algorithm that is easy to understand and verify, without eliminating any opportunities for optimization.

For example, some users of Cost Analysis might use the Counts as output to achieve rate-limiting based on a subset of the counts, where other users of Cost Analysis might leave the Counts as an internal step towards calculating the Costs.

Example № 4{
   "Query" : 1,
   "User" : 3
}

Example № 5{
   "UserInput" : 1
}

Example № 6{
   "Query.user" : 3,
   "User.name" : 3,
   "User.friends" : 1
}

Example № 7{
   "UserInput.name" : 1,
   "ProduceInput.category" : 2,
   "Filter.age" : 1
}

Example № 8{
   "Query.users.limit" : 1,
   "@skip.if" : 2
}

Example № 9{
   "@defer" : 1,
   "@include" : 2
}

Example № 10type Query {
  topProducts(filter: Filter @cost(weight: "15.0")): [String] @cost(weight: "5.0") @listSize(assumedSize: 10)
}

Example № 11type Query {
  mostPopularProduct(approx: Approximate @cost(weight: "-3.0")): Product @cost(weight: "5.0")
}

Example № 12input Filter {
  approx: Approximate @cost(weight: "-12.0")
}
type Query {
  topProducts(filter: Filter @cost(weight: "15.0")): [String] @cost(weight: "5.0") @listSize(assumedSize: 10)
}

Example № 13directive @approx (tolerance: Float! @cost(weight: "-1.0")) on FIELD

6.1Introspection of Cost Analysis Results

The results of cost analysis can be added into the introspection. As with any introspection, some servers might disable it for security or enable it to support powerful tooling. Each system MAY extend introspection with cost analysis results, and if they do then they MUST extend introspection in these ways to be compatible.

__cost : __Cost!

type __Cost {
   requestCosts : __CostMetrics
   responseCosts : __CostMetrics
}

type __CostMetrics {
   fieldCounts(regexName: String) : [__CostCountType!]!
   typeCounts(regexName: String) : [__CostCountType!]!
   inputTypeCounts(regexName: String) : [__CostCountType!]!
   inputFieldCounts(regexName: String) : [__CostCountType!]!
   argumentCounts(regexName: String) : [__CostCountType!]!
   directiveCounts(regexName: String) : [__CostCountType!]!

   fieldCost : Float!
   typeCost : Float!

   fieldCostByLocation(regexPath: String) : [__CostByLocation!]!
   typeCostByLocation(regexPath: String) : [__CostByLocation!]!
}

type __CostByLocation {
   path: String!
   cost: Float!
}

type __CostCountType {
   name: String!
   value:  Int!
}

Example № 14query exampleQuery ($VarDef1: Int @custom(first: 1)) {
  a1(arg1: 1, arg2: {f1: 3, f2: 4}) {
    x @dir1(f3: 3, f4: 4)
    ...b @dir2
    ... on A @dir3 {
      c
    }
  }
  a2 {
    ...b
    ... on A {
      nest {
        y
      }
    }
    ... on A {
      nest {
        z
      }
    }
  }
  alias1:a2 {
    ...b
  }

  a3(arg1: [{d1: 3, d2: "f"}, 2, "foo", false], arg2: $VarDef1) {
    g
  }

  a3(arg1: [{d1: 3, d2: "f"}, 2, "foo", false], arg2: $VarDef1) {
    g
  }

}
fragment b on A @dir4 {
  h
}

Example № 15
query A {
  a {
    y: x { i j }
    x: y
    z: x { j k }
    ...B
 }
}

fragment B {
  z
}

query B {
  a {
    a
    b
    ...A
 }
}

fragment A {
  c
}

6.2introspectionOnly

Implementations may support an HTTP Header named introspectionOnly. If this header is passed, then that HTTP transaction MUST only execute the introspection parts of the query, including __schema, __type, __cost, and any other extensions to introspection.

This header gives the client tooling the ability:

• to pass this header and a query which will be analyzed and yield the results of cost analysis, without actually executing the non-meta part of the query.
• to not pass this header, thus defaulting to executing all parts of the query including the meta and non-meta parts.

6.3NoSchemaIntrospectionCustomRule

Since __cost is an extension of introspection, any custom rule that turns off all introspection such as the graphql-js v15.2.0 feature, must also forbid use of __cost.

Implementations may make finer-grained setting to only forbid parts of introspection, however a generic toggle or validation rule must apply to all parts of introspection equally.

6.4Introspection of Cost Directives

This document specifies adding cost directives to a GraphQL schema. It would be useful for client tooling to automatically introspect these directives from a GraphQL server, allowing the server to advertise how expensive various GraphQL constructs are in that GraphQL schema. It would help if GraphQL introspection results had an option to include directives in the GraphQL schema, as is being discussed as a possible change to the GraphQL specification.

7.1weight

The weight argument defines what value to add to the overall cost for every appearance, or possible appearance, of a type, field, argument, etc. Being of type non-null String, the weight argument has to be set for every use of the @cost directive. In other words, it is the sole purpose of the cost directive to set a weight. While weight is required on @cost, it is not required to include the @cost directive on any schema construct.

While the type of weight is a String!, the value of the String may be a serialized Float. The reason that the definition is String is to allow extensibility of using a formula which computes a Float. All implementations must accept a literal serialized Float.

When a @cost directive is not provided, Cost Analysis relies on default weights:

• For scalar and enum types the weight defaults to "0.0".
• Fields returning scalar and enum types, arguments of scalar and enum types, as well as input fields of scalar and enum types all default to "0.0".
• Weights for all composite input and output types default to "1.0".

These default weights reflect the fact that scalar and enum values are often contained in their composite parents, like a “name” being contained in a “user” object, so while they require an additional GraphQL resolver function to be called, it usually does not result in an additional call outside of the GraphQL execution engine.

Weights can be negative. The overall calculated weight of a field or directive can never be negative, and if found to be negative must be rounded up to zero, but negative weights on arguments can be useful when combined with positive weights on the field that uses those arguments. See Negative Weights.

7.2Locations

The @cost directive can be used in a variety of locations, namely on all elements relevant for calculating different kinds of cost.

Deliberately, the @cost directive cannot be used on abstract types, neither interfaces nor unions. For such types, Cost Analysis should consider as weight the maximum weight of any of the member types. This constraint is required to ensure that Static Cost Analysis on a query produces cost values that are upper bounds of the values produced by either Dynamic Query Analysis or Query Response Analysis, which run after a concrete type was determined during execution.

For the same reason, the cost directive cannot be used on fields of an interface.

Additonally, the @cost directive cannot be used on an input object, although it can be used on the fields within an input object. The rationale is that the input object itself adds to the size of the query which can be calculated exactly without any directives, whereas the fields in the input type might correspond to additonal work needed in the resolver function for an object’s field, and should affect the weight of that other field.

8.1assumedSize

The assumedSize argument can be used to statically define the maximum length of a list returned by a field.

For example, in the following schema document, the assumedSize argument states that the list of strings returned by field Query.topProducts will always be 10:

Example № 16type Query {
  topProducts: [String] @listSize(assumedSize: 10)
}

For static analysis to produce accurate counts and cost, the GraphQL server must ensure that the list returned by a field with an assumedSize directive does in fact return lists of (at most) the defined size.

8.2slicingArguments

The slicingArguments argument can be used to define which of the field’s arguments with numeric type are slicing arguments, so that their value determines the size of the list returned by that field. It may specify a list of multiple slicing arguments.

For example, in the following schema document, the slicingArguments argument states that the max argument of field Query.users is a slicing argument:

Example № 17type Query {
  users (max: Int!): [String] @listSize(slicingArguments: ["max"])
}

When analyzing a query that includes that field, the static analysis can use the value of the max argument to determine how long the list of users is going to be (at most).

For any argument with a default value in the schema but no value given in the query, static analysis should treat it as if that value was given in the query.

When multiple slicing arguments are defined and a query contains more than one, static analysis should consider their largest value to ensure producing upper bounds.

8.3sizedFields

The sizedFields argument can be used to define that the value of the assumedSize argument or of a slicing argument does not affect the size of a list returned by a field itself, but that of a list returned by one of its sub-fields.

This option is relevant primarily for schemas that implement the GraphQL Cursor Connections Specification. In it, fields with slicing arguments first and last return a single Connection with a field edges that itself returns the sliced list (in which each element is contained in an Edge).

For example, in the following schema document, the field Query.films has two slicing arguments first and last. The field returns a single FilmConnection, which itself provides access to multiple FilmEdges via its FilmConnection.edges field. The sizedFields option states the the size of the list returned by FilmConnection.edges is determined by the value of one of the slicing arguments of the parent field:

Example № 18type FilmEdge {
  cursor: ID
  node: Film # Definition of this type left out in this example
}

type FilmConnection {
  edges: [FilmEdge]
  # See https://relay.dev/graphql/connections.htm#sec-Connection-Types.Fields.PageInfo
  pageInfo: PageInfo
}

type Query {
  films(first: Int, after: ID, last: Int, before: ID): FilmConnection @listSize(
      slicingArguments: ["first", "last"],
      sizedFields: ["edges"]
    )
}

8.4requireOneSlicingArgument

The requireOneSlicingArgument argument can be used to inform the static analysis that it should expect that exactly one of the defined slicing arguments is present in a query. If that is not the case (i.e., if none or multiple slicing arguments are present), the static analysis may throw an error.

Requiring a single slicing argument is useful once more for schemas that implement the GraphQL Cursor Connections Specification. They define two slicing arguments, first and last, for paginated fields. GraphQL does not support stating that exactly one or the other is required. In consequence, GraphQL API providers like GitHub implement custom validation rules to make sure exactly one slicing argument is used in a query. The requireOneSlicingArgument argument allows to configure this behavior.

If no slicingArguments are defined, then the value of requireOneSlicingArgument is ignored.

Per default, requireOneSlicingArgument is enabled, and has to be explicitly disabled if not desired for a field.

8.5Locations

The listSize directive can be used solely on field definitions.

9.1Cost Directive

An SDL document that implements this spec should contain a directive definition for the cost directive. Specifically:

• The cost directive should define a single argument named weight of type non-null String.
• The cost should be non-repeatable.
• The cost directive should define the locations ARGUMENT_DEFINITION, ENUM, FIELD_DEFINITION, INPUT_FIELD_DEFINITION, OBJECT, and SCALAR.

The correct usage of the cost directive is partly covered by GraphQL’s specified validation rules. Specifically:

• The cost directive can only be used in the locations defined in its definition (covered by the “Directives Are In Valid Locations” validation rule), and can be used only once per location (covered by the “Directives Are Unique Per Location” validation rule).
• When used, the cost directive must set a value for its defined weight argument (covered by the “Required Arguments” validation rule) and must only use that argument (covered by the “Argument Names” validation rule) and its value must be of the correct type (covered by the “Values of Correct Type” validation rule).

In addition, further rules for using the cost directive should be validated.

9.2List Size Directive

An SDL document that implements this spec should contain a directive definition for the listSize directive. Specifically:

• The listSize directive should define the following arguments:
  • An argument named assumedSize with type Int.
  • An argument named slicingArguments with type list of String.
  • An argument named sizedFields with type list of String.
  • An argument named requireOneSlicingArgument with type Boolean and a default value of true.
• The listSize should be non-repeatable.
• The listSize directive should define the single location FIELD_DEFINITION.

The correct usage of the listSize directive is partly covered by GraphQL’s specified validation rules. Specifically:

• The listSize directive can only be used in the locations defined in its definition (covered by the “Directives Are In Valid Locations” validation rule), and can be used only once per location (covered by the “Directives Are Unique Per Location” validation rule).
• When used, the listSize directive may set values for any of its defined arguments (covered by the “Argument Names” validation rule) and their values must be of the correct type (covered by the “Values of Correct Type” validation rule).

In addition, further rules for using the listSize directive should be validated.