查询计划

了解查询计划 以帮助你调试 Apollo Federation 的高级用法。

当你的 路由器 接收到一个进入的 GraphQL 操作 时，它需要确定如何使用你的 子图 来填充数据为每个操作的 字段。要做到这一点，路由器生成一个 查询计划：

一个 查询计划 是将单个进入的操作分解为多个可由单个 子图 解决的操作的蓝图。其中一些操作依赖于其他操作的结果，因此查询计划还定义了它们执行所需的任何排序。

示例图

假设我们的联邦 超级图 包含以下这些 子图:

type Hotel @key(fields: "id") {
  id: ID!
  address: String!
}

type Query {
  hotels: [Hotel!]!
}

type Hotel @key(fields: "id") {
  id: ID! @external
  reviews: [Review!]!
}

type Review {
  id: ID!
  rating: Int!
  description: String!
}

基于这些子图，客户可以对我们的路由器执行以下查询：

1
query GetHotels {
2
  hotels { # Resolved by Hotels subgraph
3
    id
4
    address
5
    reviews { # Resolved by Reviews subgraph
6
      rating
7
    }
8
  }
9
}

此查询包括来自酒店子图和评论子图的字段。因此，路由器需要向每个子图发送至少一个查询，以填充所有请求的字段。

查看此查询的路由器查询计划：

1
# Top-level definition
2
QueryPlan {
3
  # Indicates child nodes must be executed serially in order
4
  Sequence {
5
    # Execute the contained operation on the `hotels` subgraph
6
    Fetch(service: "hotels") {
7
      {
8
        hotels {
9
          id
10
          address
11
          __typename
12
        }
13
      }
14
    },
15
    # Merge the data from this contained Fetch with earlier data
16
    # from this Sequence, at the position indicated by `path`
17
    # (The @ path element indicates the previous element returns a list)
18
    Flatten(path: "hotels.@") {
19
      # Execute this operation on the `reviews` subgraph
20
      Fetch(service: "reviews") {
21
        # Use these fields as the representation of a Hotel entity
22
        {
23
          ... on Hotel {
24
            __typename
25
            id
26
          }
27
        } => # Populate these additional fields for the corresponding Hotel
28
        {
29
          ... on Hotel {
30
            reviews {
31
              rating
32
            }
33
          }
34
        }
35
      },
36
    },
37
  },
38
}

这种语法可能看起来很复杂。🤔 让我们来拆解它。

查询计划的构架

一个查询计划被定义为一组节点的层次结构，当序列化成JSON或GraphQL文档时看起来像。

每个查询计划的最高层是这样的QueryPlan节点：

1
QueryPlan {
2
  ...
3
}

在QueryPlan节点内定义的每个节点是以下之一：

以下对每个选项做了更详细的描述。

Fetch节点

一个Fetch节点告诉路由器在特定的子图上执行特定的GraphQL操作。每个查询计划至少包含一个Fetch节点。

1
# Executes the query shown on the "books" subgraph
2
Fetch(service: "books") {
3
  {
4
    books {
5
      title
6
      author
7
    }
8
  }
9
},

节点的主体是要执行的操作，其service参数指明要对哪个子图执行操作。

在我们的示例图中，以下查询只从Hotels子图中获取数据：

1
query GetHotels {
2
  hotels {
3
    id
4
    address
5
  }
6
}

因为这个操作不需要在多个子图之间协调操作，所以整个查询计划中只包含一个Fetch节点：

1
QueryPlan {
2
  Fetch(service: "hotels") {
3
    {
4
      hotels {
5
        id
6
        address
7
      }
8
    }
9
  },
10
}

当Fetch节点在跨子图解析实体引用时，它会使用特殊的语法。有关详情，请参阅使用Flatten解析引用。

Parallel 节点

一个Parallel节点告诉路由器该节点的所有直接子节点可以并行执行。此节点出现在查询计划中，当路由器可以在不同的子图上执行完全独立的操作时。

1
Parallel {
2
  Fetch(...) {
3
    ...
4
  },
5
  Fetch(...) {
6
    ...
7
  },
8
  ...
9
}

例如，假设我们的联邦图有一个Books子图和一个Movies 子图。假设客户端执行以下查询来获取书籍和电影的两个单独列表：

1
query GetBooksAndMovies {
2
  books {
3
    id
4
    title
5
  }
6
  movies {
7
    id
8
    title
9
  }
10
}

在这种情况下，每个子图返回的数据不依赖于其他子图返回的数据。因此，路由器可以并行查询这两个子图。

操作的查询计划看起来是这样：

1
QueryPlan {
2
  Parallel {
3
    Fetch(service: "books") {
4
      {
5
        books {
6
          id
7
          title
8
        }
9
      }
10
    },
11
    Fetch(service: "movies") {
12
      {
13
        movies {
14
          id
15
          title
16
        }
17
      }
18
    },
19
  },
20
}

Sequence 节点

一个Sequence节点告诉路由器节点的前驱子节点必须按列表顺序依次执行。

1
Sequence {
2
  Fetch(...) {
3
    ...
4
  },
5
  Flatten(...) {
6
    Fetch(...) {
7
      ...
8
    }
9
  },
10
  ...
11
}

该节点出现在查询计划中，当一个子图的响应依赖于另一个子图首先返回的数据时。这种情况最常见于查询请求跨多个子图定义的实体的字段时。

以一个例子来说，我们可以回到我们GetHotels查询，它来自我们的示例图：

1
query GetHotels {
2
  hotels { # Resolved by Hotels subgraph
3
    id
4
    address
5
    reviews { # Resolved by Reviews subgraph
6
      rating
7
    }
8
  }
9
}

在我们的示例图中，Hotel类型是一个实体。Hotel.id和Hotel.address由Hotels子图解析，但Hotel.reviews由Reviews子图解析。我们的Hotels子图需要首先解析，因为否则Reviews子图不知道为哪些酒店返回评论。

操作的查询计划看起来是这样：

1
QueryPlan {
2
  Sequence {
3
    Fetch(service: "hotels") {
4
      {
5
        hotels {
6
          id
7
          address
8
          __typename
9
        }
10
      }
11
    },
12
    Flatten(path: "hotels.@") {
13
      Fetch(service: "reviews") {
14
        {
15
          ... on Hotel {
16
            __typename
17
            id
18
          }
19
        } =>
20
        {
21
          ... on Hotel {
22
            reviews {
23
              rating
24
            }
25
          }
26
        }
27
      },
28
    },
29
  },
30
}

如图所示，此查询计划定义了一个Sequence，在执行Reviews子图的Fetch操作之前，首先在Hotels子图上执行。（我们将在下文中介绍Flatten节点和第二个Fetch操作的特殊语法。）

Flatten 节点

一个Flatten节点始终出现在一个Sequence节点内部，并且它始终包含一个Fetch节点。它告诉路由器将其Fetch节点返回的数据与之前在当前Sequence期间Fetch获取的数据合并：

1
Flatten(path: "hotels.@") {
2
  Fetch(service: "reviews") {
3
    ...
4
  }
5
}

Flatten节点的path参数告诉路由器在哪里将新返回的数据与现有数据合并。@元素在path中表示前面的路径元素返回一个列表。

在上面的示例中，Flatten's Fetch返回的数据被添加到Sequence's 存在于hotels列表字段中的existing data。

扩展示例

再次回到我们的GetHotels查询的示例图：

1
query GetHotels {
2
  hotels { # Resolved by Hotels subgraph
3
    id
4
    address
5
    reviews { # Resolved by Reviews subgraph
6
      rating
7
    }
8
  }
9
}

此操作的查询计划首先指示路由器在Hotels子图上执行此查询：

1
{
2
  hotels {
3
    id
4
    address
5
    __typename # The router requests this to resolve references (see below)
6
  }
7
}

到目前为止，我们还需要每个酒店的评论相关信息。查询计划接下来指示路由器查询Reviews子图，列出具有以下结构的Hotel对象：

1
{
2
  reviews {
3
    rating
4
  }
5
}

现在，路由器需要知道如何将这些Hotel对象与它已经从Hotels子图中获取的数据合并。Flatten节点的path参数刚好告诉它这一点：

1
Flatten(path: "hotels.@") {
2
  ...
3
}

换句话说，“将Reviews子图返回的Hotel对象与顶层hotels字段返回的第一个查询中的Hotel对象合并。”

当路由器完成此合并时，结果数据与客户端原始查询的结构完全一致：

1
{
2
  hotels {
3
    id
4
    address
5
    reviews {
6
      rating
7
    }
8
  }
9
}

使用 Flatten 解析引用

与序列节点类似，Flatten 节点在任何子图响应依赖于必须由另一个子图先返回的数据时出现。这几乎总是涉及解决定义在多个子图中的实体字段。

在这些情况下，Flatten 节点的 Fetch 需要在检索实体的字段之前解决对实体的引用。在这种情况下，Fetch 节点使用特殊语法：

1
Flatten(path: "hotels.@") {
2
  Fetch(service: "reviews") {
3
    {
4
      ... on Hotel {
5
        _typename
6
        id
7
      }
8
    } =>
9
    {
10
      ... on Hotel {
11
        reviews {
12
          rating
13
        }
14
      }
15
    }
16
  },
17
}

与包含 GraphQL 操作不同，这个 Fetch 节点包含两个 GraphQL 片段，由 => 分隔。

• 第一个 片段是正在解决的实体（在这种情况下，Hotel）的表示。了解更多关于实体表示的信息。
• 第二个片段包含路由器需要子图解决（在这种情况下，Hotel.reviews 和 Review.rating）的实体字段和子字段。

当路由器看到这个特殊的 Fetch 语法时，它知道要查询子图的 Query._entities 字段。此字段使得子图能够直接访问实体的任何可用字段。

现在你已经了解了每个查询计划节点，请再次查看 示例图中的示例查询计划，以了解这些节点如何在一个完整的查询计划中一起工作。

延迟节点

一个 Defer 节点对应于查询计划中同一嵌套层级的多个 @defer。

此节点包含一个 主块和一系列 延迟块。主块表示不延迟的查询部分。每个延迟块对应于查询的一个延迟部分。

阅读更多关于如何在 @defer 的路由器支持文章。

1
QueryPlan {
2
  Defer {
3
    Primary {
4
      Fetch(...) {}
5
    }, [
6
      Deferred(...) {
7
        Flatten(...) {
8
          Fetch(...) {}
9
        }
10
      }
11
    ]
12
  }
13
}

条件节点

一个 Skip 或 Include 节点将查询计划分为 if-else 分支。当操作包含 @skip 或 @include 指令时，会使用条件节点，以便查询计划可以根据提供的运行时 变量选择不同的节点。

1
QueryPlan {
2
  Sequence {
3
    Fetch(...) {}
4
    Include(...) {
5
      Flatten(...) {
6
        Fetch(...) { }
7
      }
8
    }
9
  }
10
}

1
QueryPlan {
2
  Sequence {
3
    Fetch(...) {}
4
    Skip(...) {
5
      Flatten(...) {
6
        Fetch(...) { }
7
      }
8
    }
9
  }
10
}

查看查询计划

您可以通过以下任何方式查看特定操作的查询计划：

• 在GraphOS Studio资源管理器中
  • 注意，必须将您的联邦图在GraphOS中注册，以在资源管理器中查看查询计划。
• 作为来自@apollo/gateway库的直接输出（见下文）

以标题输出查询计划

自从Apollo Router Corev0.16.0+ 和 @apollo/gatewayv2.5.4+起，您可以在GraphQL响应extensions中返回以下头信息来包含查询计划：

• 包括Apollo-Query-Plan-Experimental头信息会将查询计划放在响应扩展中返回
• 另外，包括带有一个支持的选项的Apollo-Query-Plan-Experimental-Format头，将改变输出的格式：
  • 值prettified会返回人性化的查询计划字符串
  • 值internal会返回查询计划的JSON表示形式

使用@apollo/gateway输出查询计划

您的网关可以在计算过程中输出每个传入的操作的查询计划。要这样做，请将以下内容添加到初始化您的ApolloGateway实例的文件中：

1. 从@apollo/query-planner库导入serializeQueryPlan函数：

   JavaScript

   1
   const {serializeQueryPlan} = require('@apollo/query-planner');

   复制

2. 将experimental_didResolveQueryPlan选项添加到您传递给ApolloGateway构造函数的对象中：

   JavaScript

   1
   const gateway = new ApolloGateway({
   2
     experimental_didResolveQueryPlan: function(options) {
   3
       if (options.requestContext.operationName !== 'IntrospectionQuery') {
   4
         console.log(serializeQueryPlan(options.queryPlan));
   5
       }
   6
     }
   7
   });

   复制