diff --git a/docs/source/_redirects b/docs/source/_redirects index be76c0317..9a56f6c99 100644 --- a/docs/source/_redirects +++ b/docs/source/_redirects @@ -1,3 +1,4 @@ +/gateway/ /docs/federation/router/ /other-servers/ /docs/federation/supported-subgraphs/ /federation-spec/ /docs/federation/subgraph-spec/ diff --git a/docs/source/api/apollo-subgraph.mdx b/docs/source/api/apollo-subgraph.mdx index 043310f3f..1865d4b37 100644 --- a/docs/source/api/apollo-subgraph.mdx +++ b/docs/source/api/apollo-subgraph.mdx @@ -92,7 +92,7 @@ const server = new ApolloServer({ The name of a special **reference resolver** function you can define for every [entity](../entities/) in a subgraph schema's resolver map. -The `__resolveReference` function enables your gateway's query planner to resolve a particular entity by whatever unique identifier your other subgraphs use to reference it. For details, see [Defining an entity](../entities/#defining-an-entity). +The `__resolveReference` function enables your router's query planner to resolve a particular entity by whatever unique identifier your other subgraphs use to reference it. For details, see [Defining an entity](../entities/#defining-an-entity). The function takes the parameters listed below. diff --git a/docs/source/config.json b/docs/source/config.json index be74493ca..04f08f7b8 100644 --- a/docs/source/config.json +++ b/docs/source/config.json @@ -25,10 +25,10 @@ "3️⃣ Local composition": "/quickstart/local-composition", "4️⃣ Working with subgraphs": "/quickstart/local-subgraphs" }, - "Implementing a Supergraph": { + "Building Your Supergraph": { "Subgraphs in Apollo Server": "/subgraphs", "Other subgraph libraries": "/supported-subgraphs", - "Graph router/gateway": "/gateway" + "The graph router/gateway": "/router" }, "Federated Schemas": { "Overview": "/federated-types/overview", diff --git a/docs/source/entities-advanced.mdx b/docs/source/entities-advanced.mdx index 08c38a382..fd8dfdc8f 100644 --- a/docs/source/entities-advanced.mdx +++ b/docs/source/entities-advanced.mdx @@ -116,7 +116,7 @@ The steps for this migration depend on how you perform schema composition: 3. Deploy the updated Billing subgraph to your environment. - * At this point, the Billing subgraph can successfully resolve `Bill` objects, but the gateway doesn't _know_ this yet because its supergraph schema hasn't been updated. + * At this point, the Billing subgraph can successfully resolve `Bill` objects, but the router doesn't _know_ this yet because its supergraph schema hasn't been updated. 4. In the Payments subgraph, remove the `Bill` entity and its associated resolvers (**do not deploy this change yet**): @@ -140,11 +140,11 @@ The steps for this migration depend on how you perform schema composition: 5. Compose an updated supergraph schema with your usual configuration using `rover supergraph compose`. * This updated supergraph schema indicates that the Billing subgraph resolves `Bill` entities, and the Payments subgraph _doesn't_. -6. Assuming CI completes successfully, deploy an updated version of your _gateway_ with the new supergraph schema. - * When this deployment completes, the gateway begins resolving `Bill` fields in the Billing subgraph _instead of_ the Payments subgraph. +6. Assuming CI completes successfully, deploy an updated version of your _router_ with the new supergraph schema. + * When this deployment completes, the router begins resolving `Bill` fields in the Billing subgraph _instead of_ the Payments subgraph. 7. Deploy an updated version of your Payments subgraph without the `Bill` entity. - * At this point it's safe to remove this definition, because the gateway is never resolving `Bill` with the Payments subgraph. + * At this point it's safe to remove this definition, because the router is never resolving `Bill` with the Payments subgraph. We're done! `Bill` is now resolved in a new subgraph, and it was resolvable during each step of the migration process. @@ -214,11 +214,11 @@ extend schema 5. Deploy the updated Billing subgraph to your environment. - * This change is currently invisible to your gateway, which is not yet aware that the Billing subgraph defines the `Bill` entity. + * This change is currently invisible to your router, which is not yet aware that the Billing subgraph defines the `Bill` entity. 6. Publish the updated Billing subgraph schema to Apollo. - * When the gateway fetches its new supergraph schema, it detects that it should resolve the `Bill` entity in the Billing subgraph _instead of_ in the Payments subgraph. + * When the router fetches its new supergraph schema, it detects that it should resolve the `Bill` entity in the Billing subgraph _instead of_ in the Payments subgraph. 7. In the Payments subgraph, _remove_ the `Bill` entity and its associated resolvers: @@ -241,7 +241,7 @@ extend schema 8. Publish the updated Payments subgraph schema to Apollo. - * When the gateway fetches its new supergraph schema, it continues resolving the `Bill` entity in the Billing subgraph. The `@override` directive has no effect if a field is defined in only one subgraph. + * When the router fetches its new supergraph schema, it continues resolving the `Bill` entity in the Billing subgraph. The `@override` directive has no effect if a field is defined in only one subgraph. 9. Deploy the updated Payments subgraph to your environment. @@ -418,7 +418,7 @@ We can perform this migration with the following steps (additional commentary on -5. Compose a new supergraph schema. Deploy a new version of your gateway that uses the updated schema. +5. Compose a new supergraph schema. Deploy a new version of your router that uses the updated schema. 6. Deploy the updated Products subgraph to your environment. @@ -437,9 +437,9 @@ type Product @key(fields: "id") { } ``` -As shown, you use the `@requires` directive to indicate which fields (and subfields) from _other_ subgraphs are required. You also need to _define_ the required fields and apply the `@external` directive to them. This directive tells the gateway, "This subgraph knows that these fields exist, but it _can't_ resolve them itself." +As shown, you use the `@requires` directive to indicate which fields (and subfields) from _other_ subgraphs are required. You also need to _define_ the required fields and apply the `@external` directive to them. This directive tells the router, "This subgraph knows that these fields exist, but it _can't_ resolve them itself." -In the above example, if a query requests a product's `shippingEstimate`, the gateway does the following, in order: +In the above example, if a query requests a product's `shippingEstimate`, the router does the following, in order: 1. It queries the Products subgraph for the product's `size` and `weight`. 2. It queries the Shipping subgraph for the product's `shippingEstimate`. The `size` and `weight` are included in the `Product` object passed to the resolver for `shippingEstimate`: @@ -472,7 +472,7 @@ In this modification of the previous example, `size` and `weight` are now subfie By default, exactly one subgraph is responsible for resolving each field in your supergraph schema (with some exceptions, like entity `@key` fields). But sometimes, _multiple_ subgraphs are able to resolve a particular entity field, because all of those subgraphs have access to a particular data store. For example, an Inventory subgraph and a Products subgraph might both have access to the database that stores all product-related data. -You can enable multiple subgraphs to resolve a particular entity field. **This is a completely optional optimization.** When the gateway plans a query's execution, it looks at which fields are available from each subgraph. It can then attempt to optimize performance by executing the query across the fewest subgraphs needed to access all required fields. +You can enable multiple subgraphs to resolve a particular entity field. **This is a completely optional optimization.** When the router plans a query's execution, it looks at which fields are available from each subgraph. It can then attempt to optimize performance by executing the query across the fewest subgraphs needed to access all required fields. You achieve this with one of the following directives: @@ -565,8 +565,8 @@ type Product @key(fields: "id") { Here we're using two directives in combination: `@provides` and `@external`. -* The `@provides` directive tells the gateway, "This subgraph can resolve the `name` of any `Product` object returned by `InStockCount.product`." -* The `@external` directive tells the gateway, "This subgraph _can't_ resolve the `name` of a `Product` object, _except_ wherever indicated by `@provides`." +* The `@provides` directive tells the router, "This subgraph can resolve the `name` of any `Product` object returned by `InStockCount.product`." +* The `@external` directive tells the router, "This subgraph _can't_ resolve the `name` of a `Product` object, _except_ wherever indicated by `@provides`." #### Rules for using `@provides` diff --git a/docs/source/entities.mdx b/docs/source/entities.mdx index edd4783b2..a9a85ed6e 100644 --- a/docs/source/entities.mdx +++ b/docs/source/entities.mdx @@ -55,7 +55,7 @@ type Product @key(fields: "id") { The `@key` directive defines the entity's **primary key**, which consists of one or more of the type's `fields`. In this example, the `Product` entity's primary key is its `id` field. -**Every instance of an entity must be uniquely identifiable by its `@key` fields.** This is what enables your gateway to associate field data from _different_ subgraphs with the _same_ entity instance. +**Every instance of an entity must be uniquely identifiable by its `@key` fields.** This is what enables your router to associate field data from _different_ subgraphs with the _same_ entity instance. > **An entity's `@key` _cannot_ include:** > @@ -66,7 +66,7 @@ The `@key` directive defines the entity's **primary key**, which consists of one ### 2. Define a reference resolver -The `@key` directive effectively tells the gateway, "This subgraph can resolve an instance of this entity if you provide its primary key." In order for this to be true, the subgraph needs to define a **reference resolver** for the entity. +The `@key` directive effectively tells the router, "This subgraph can resolve an instance of this entity if you provide its primary key." In order for this to be true, the subgraph needs to define a **reference resolver** for the entity. > ⚠️ **This section describes how to create reference resolvers in Apollo Server.** If you're using another [subgraph-compatible library](./supported-subgraphs/), see its documentation for creating reference resolvers. @@ -89,7 +89,7 @@ Let's break this example down: * You declare an entity's reference resolver in your resolver map, as a member of the entity's corresponding object. * A reference resolver's name is always `__resolveReference`. * A reference resolver's first parameter is a **representation** of the entity being resolved. - * An entity representation is an object that contains the entity's `@key` fields, plus its `__typename` field. These values are provided by the gateway. + * An entity representation is an object that contains the entity's `@key` fields, plus its `__typename` field. These values are provided by the router. * A reference resolver is responsible for returning all of the entity fields that this subgraph defines. * In this example, the hypothetical `fetchProductByID` function fetches a particular `Product`'s field data based on its `id`. @@ -120,7 +120,7 @@ type Product @key(fields: "id") { -When a subgraph contributes entity fields, no _other_ subgraph knows about those fields—only the gateway does thanks to the composed supergraph schema. +When a subgraph contributes entity fields, no _other_ subgraph knows about those fields—only the router does thanks to the composed supergraph schema. By default, each subgraph must contribute _different_ fields, with the important exception of `@key` fields. Otherwise, a composition error occurs. To override this default, see [Resolving another subgraph's field](./entities-advanced/#resolving-another-subgraphs-field). @@ -202,7 +202,7 @@ type Query { > Notice that the Reviews subgraph [references the `Product` entity without contributing fields](#referencing-an-entity-without-contributing-fields). -The Reviews subgraph defines one entry point into our schema: `Query.latestReviews`. This means that the following query is valid against our gateway: +The Reviews subgraph defines one entry point into our schema: `Query.latestReviews`. This means that the following query is valid against our router: ```graphql {6} query GetReviewsWithProducts { @@ -218,20 +218,20 @@ query GetReviewsWithProducts { Here we have a problem: this query needs to start its execution in the Reviews subgraph (because that's where `latestReviews` is defined), but that subgraph _doesn't_ know that `Product` entities have a `price` field! Remember, the Reviews subgraph only knows about the `id` field of `Product`. -Because of this, the gateway needs to fetch `price` from the Products subgraph instead. To handle this two-step process, the gateway generates a **query plan**. +Because of this, the router needs to fetch `price` from the Products subgraph instead. To handle this two-step process, the router generates a **query plan**. ### The query plan -> Query plans are automatically generated and carried out by the gateway. You don't need to write any code related to them. +> Query plans are automatically generated and carried out by the router. You don't need to write any code related to them. -A query plan is a blueprint for dividing a single incoming operation into one or more operations that are each resolvable by a single subgraph. The gateway generates a query plan for each unique operation that it receives from clients. +A query plan is a blueprint for dividing a single incoming operation into one or more operations that are each resolvable by a single subgraph. Your router generates a query plan for each unique operation that it receives from clients. -With our example query above, the gateway knows the following: +With our example query above, the router knows the following: * It _must_ start by querying the Reviews subgraph, because that's where `Query.latestReviews` is defined. * It _must_ then query the Products subgraph to fetch the `price` of each `Product` returned by the Reviews subgraph. -Using this information, the gateway's query plan starts with this query to the Reviews subgraph: +Using this information, the router's query plan starts with this query to the Reviews subgraph: ```graphql {5} query { @@ -245,11 +245,11 @@ query { } ``` -Notice that this query omits the `Product.price` field but _adds_ the `Product.__typename` field! This is because the gateway needs **representations** of each returned `Product` entity for its _second_ query. +Notice that this query omits the `Product.price` field but _adds_ the `Product.__typename` field! This is because the router needs **representations** of each returned `Product` entity for its _second_ query. > As described in [Define a reference resolver](#2-define-a-reference-resolver), an entity representation is an object that contains the entity's `@key` fields (`id` in this case), plus its `__typename` field. -This first query returns a list of `Review` objects, each containing a `Product` representation. With these representations, the gateway can execute its second query, this time on the Products subgraph: +This first query returns a list of `Review` objects, each containing a `Product` representation. With these representations, the router can execute its second query, this time on the Products subgraph: ```graphql query { @@ -261,9 +261,9 @@ query { } ``` -This query uses a special entry point that's automatically added to every subgraph schema: `Query._entities`. This entry point is what provides the gateway with random access to any entity's fields. +This query uses a special entry point that's automatically added to every subgraph schema: `Query._entities`. This entry point is what provides the router with direct access to any entity's fields. -Each item in the `representations` list argument above is one of the `Product` representations that the gateway obtained from its _first_ query. Here's an example list: +Each item in the `representations` list argument above is one of the `Product` representations that the router obtained from its _first_ query. Here's an example list: ```json [ @@ -279,7 +279,7 @@ Each item in the `representations` list argument above is one of the `Product` r ] ``` -These representations are passed individually to the `Product` [reference resolver](#2-define-a-reference-resolver) in the Products subgraph. When the reference resolver finishes returning values for each representation, the gateway receives its response: +These representations are passed individually to the `Product` [reference resolver](#2-define-a-reference-resolver) in the Products subgraph. When the reference resolver finishes returning values for each representation, the router receives its response: ```json [ @@ -293,7 +293,7 @@ These representations are passed individually to the `Product` [reference resolv ] ``` -Nice! The gateway can merge this `price` data with the `Product` objects returned by its first query. After doing so, the gateway returns a single, combined result to the client. +Nice! The router can merge this `price` data with the `Product` objects returned by its first query. After doing so, the router returns a single, combined result to the client. > [Learn more about query plans.](./query-plans/) diff --git a/docs/source/federated-types/composition.mdx b/docs/source/federated-types/composition.mdx index faf093d05..6bfcb13f5 100644 --- a/docs/source/federated-types/composition.mdx +++ b/docs/source/federated-types/composition.mdx @@ -35,7 +35,7 @@ To learn how to install Rover and use this command, see the [quickstart](../quic ### Automatically with managed federation -With [managed federation](../managed-federation/overview/), Apollo performs composition automatically whenever one of your subgraphs updates its registered schema. This enables your running graph router to dynamically fetch an updated supergraph schema from Apollo as soon as it's available: +With [managed federation](../managed-federation/overview/), Apollo performs composition automatically whenever one of your subgraphs updates its published schema. This enables your running graph router to dynamically fetch an updated supergraph schema from Apollo as soon as it's available: ```mermaid graph LR; @@ -67,13 +67,13 @@ For example, take a look at these two subgraph schemas: ```graphql {2} title="Subgraph A" -type Event { +type Event @shareable { timestamp: String! } ``` ```graphql {2} title="Subgraph B" -type Event { +type Event @shareable { timestamp: Int! } ``` diff --git a/docs/source/federated-types/federated-directives.mdx b/docs/source/federated-types/federated-directives.mdx index 664aea457..856d2bd04 100644 --- a/docs/source/federated-types/federated-directives.mdx +++ b/docs/source/federated-types/federated-directives.mdx @@ -224,7 +224,7 @@ See also [Value types in Apollo Federation](./sharing-types/) and [Resolving ano directive @inaccessible on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION ``` -Indicates that a definition in the subgraph schema should be _omitted_ from the gateway's [API schema](./overview/#api-schema), _even if that definition is also present in other subgraphs_. This means that the field is not exposed to clients at all. +Indicates that a definition in the subgraph schema should be _omitted_ from the router's [API schema](./overview/#api-schema), _even if that definition is also present in other subgraphs_. This means that the field is not exposed to clients at all. Common use cases for `@inaccessible` include: @@ -497,7 +497,7 @@ Examples: directive @tag(name: String!) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION ``` -Applies arbitrary string metadata to a schema location. Custom tooling can use this metadata during any step of the schema delivery flow, including composition, static analysis, and documentation. Apollo Studio's enterprise [contracts feature](/studio/contracts/) uses `@tag` to define inclusion and exclusion filters. +Applies arbitrary string metadata to a schema location. Custom tooling can use this metadata during any step of the schema delivery flow, including composition, static analysis, and documentation. Apollo Studio's enterprise [contracts feature](/studio/contracts/) uses `@tag` with its inclusion and exclusion filters. > ⚠️ Unlike with most directives, composition _preserves_ uses of this directive in the generated supergraph schema. To preserve uses of _other_ directives, see [`@composeDirective`](#composedirective). > diff --git a/docs/source/federated-types/overview.mdx b/docs/source/federated-types/overview.mdx index 14ae189cd..11028856f 100644 --- a/docs/source/federated-types/overview.mdx +++ b/docs/source/federated-types/overview.mdx @@ -21,10 +21,10 @@ graph TB; * **Subgraph schemas.** Each **subgraph** has a distinct schema that indicates _which_ types and fields of your composed **supergraph** it can resolve. * These are the only schemas that your teams define manually. -* **Supergraph schema.** This schema combines all of the types and fields from your subgraph schemas, _plus_ some federation-specific information that tells your gateway which subgraphs can resolve which fields. +* **Supergraph schema.** This schema combines all of the types and fields from your subgraph schemas, _plus_ some federation-specific information that tells your router which subgraphs can resolve which fields. * This schema is the result of performing [composition](./composition/) on your collection of subgraph schemas. * **API schema.** This schema is similar to the supergraph schema, but it _omits_ federation-specific types, fields, and directives that are considered "machinery" and are not part of your public API. - * This is the schema that your gateway exposes to clients, who don't need to know internal implementation details about your graph. + * This is the schema that your router exposes to clients, who don't need to know internal implementation details about your graph. Let's look at an example! @@ -101,9 +101,9 @@ As these schemas show, multiple subgraphs can contribute unique fields to a sing The supergraph schema is the output of [schema composition](./composition/). It serves the following purposes: -* It provides your gateway with the name and endpoint URL for each of your subgraphs. +* It provides your router with the name and endpoint URL for each of your subgraphs. * It includes all types and fields defined by all of your subgraphs. -* It tells your gateway which of your subgraphs can resolve which GraphQL fields. +* It tells your router which of your subgraphs can resolve which GraphQL fields. Here's the supergraph schema composed with [the subgraph schemas above](#subgraph-schemas): @@ -188,11 +188,11 @@ type User -As you can see, the supergraph schema includes a lot of Federation-specific additions! These additions are used only by the gateway, and you'll never need to add them manually. +As you can see, the supergraph schema includes a lot of Federation-specific additions! These additions are used only by the router, and you'll never need to add them manually. ## API schema -The gateway uses its [supergraph schema](#supergraph-schema) to produce an **API schema**, which it exposes to clients as your actual GraphQL API. This schema cleanly and logically represents the combination of your [subgraph schemas](#subgraph-schemas): +The router uses its [supergraph schema](#supergraph-schema) to produce an **API schema**, which it exposes to clients as your actual GraphQL API. This schema cleanly and logically represents the combination of your [subgraph schemas](#subgraph-schemas): ```graphql type Product { diff --git a/docs/source/federated-types/sharing-types.mdx b/docs/source/federated-types/sharing-types.mdx index b1876051f..98df328aa 100644 --- a/docs/source/federated-types/sharing-types.mdx +++ b/docs/source/federated-types/sharing-types.mdx @@ -47,7 +47,7 @@ type Position { -Attempting to compose these two subgraph schemas together will [break composition](./composition/#breaking-composition). The gateway doesn't know _which subgraph_ is responsible for resolving `Position.x` and `Position.y`. To enable multiple subgraphs to resolve these fields, you must first mark that field as [`@shareable`](#using-shareable). +Attempting to compose these two subgraph schemas together will [break composition](./composition/#breaking-composition). The router doesn't know _which subgraph_ is responsible for resolving `Position.x` and `Position.y`. To enable multiple subgraphs to resolve these fields, you must first mark that field as [`@shareable`](#using-shareable). > As an alternative, if you want Subgraphs A and B to resolve _different_ fields of `Position`, you can designate the `Position` type as an [entity](../entities). @@ -92,7 +92,7 @@ Both subgraphs A _and_ B can now resolve the `x` and `y` fields for the `Positio #### ⚠️ Important considerations for `@shareable` -* If a type or field is marked `@shareable` in _any_ subgraph, it must be marked `@shareable` or [`@external`](./federated-directives/#external) in _every_ subgraph that defines it. Otherwise, composition fails. +* If a type or field is marked `@shareable` in _any_ subgraph, it must be marked either `@shareable` or [`@external`](./federated-directives/#external) in _every_ subgraph that defines it. Otherwise, composition fails. * If multiple subgraphs can resolve a field, **make sure each subgraph's resolver for that field behaves identically.** Otherwise, queries might return inconsistent results depending on which subgraph resolves the field. ## Differing shared fields @@ -100,7 +100,7 @@ Both subgraphs A _and_ B can now resolve the `x` and `y` fields for the `Positio Shared fields can differ between subgraphs in specific ways: * The return type of a shared field can vary in nullability (`String` / `String!`). * A shared field's return type _can't_ vary in its core type (`Int` vs. `String`) or in whether it returns a list (`Int` vs. `[Int]`). -* A field can be omitted from a subgraph, _IF_ that field is always [resolvable](../federated-types/composition/#rules-of-composition). +* A field can be omitted from a subgraph, _if_ that field is always [resolvable](../federated-types/composition/#rules-of-composition). For example, take a look at the shared `Food` type below: @@ -194,7 +194,7 @@ This definition works for querying Subgraph A, because Subgraph A's definition i Arguments for a shared field can differ between subgraphs in certain ways: * If an argument is _required_ in at least one subgraph, it can be _optional_ in other subgraphs. **It cannot be omitted.** -* If an argument is _optional in every subgraph where it's defined_, it _can_ be omitted in other subgraphs. _However:_ +* If an argument is _optional in every subgraph where it's defined_, it is _technically valid_ to omit it in other subgraphs. _However:_ * ⚠️ **If a field argument is omitted from any subgraph, that argument is omitted from the supergraph schema entirely!** This means that clients _can't_ provide the argument for that field.

✅

@@ -374,7 +374,7 @@ To incrementally add the field to _all_ of our subgraphs _without_ breaking comp ### Using `@inaccessible` -If you apply the `@inaccessible` directive to a field, composition _omits_ that field from your gateway's API schema. This helps you incrementally add a field to multiple subgraphs without breaking composition. +If you apply the `@inaccessible` directive to a field, composition _omits_ that field from your router's API schema. This helps you incrementally add a field to multiple subgraphs without breaking composition. To use `@inaccessible` in a subgraph, first make sure you include it in the `import` array of your Federation 2 opt-in declaration: @@ -500,7 +500,7 @@ This can be useful when different subgraphs are responsible for different subset > You can also use the `enum` type across multiple subgraphs. For details, see [Merging types from multiple subgraphs](composition#enums). -Subgraphs can share `input` type definitions, but composition merges them differently. When `input` types are composed across multiple subgraphs, only their _mutual_ fields are carried over into the supergraph schema: +Subgraphs can share `input` type definitions, but composition merges them differently. When `input` types are composed across multiple subgraphs, only their _mutual_ fields are preserved the supergraph schema: diff --git a/docs/source/index.mdx b/docs/source/index.mdx index cff3e3aea..8cc3b6b9b 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -126,7 +126,7 @@ graph BT; ``` * The router is one of the following: - * An instance of [the Apollo Router](https://www.apollographql.com/docs/router/): a high-performance, precompiled Rust executable + * [The Apollo Router](https://www.apollographql.com/docs/router/) (recommended): a high-performance, precompiled Rust executable * An instance of Apollo Server using special extensions from the [`@apollo/gateway`](./api/apollo-gateway) library * Subgraphs can run Apollo Server using special extensions from the [`@apollo/subgraph`](./api/apollo-subgraph) library, _or_ they can run any other [subgraph-compatible GraphQL server](./supported-subgraphs/). Different subgraphs in the same supergraph can even use different server libraries. diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index c0b75f513..8e8e786d3 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -24,7 +24,7 @@ Whenever possible, you should update your subgraph configuration in a way that i Additionally, **call `rover subgraph publish` for a subgraph only after all replicas of that subgraph are deployed**. This ensures that resolvers are in place for all operations that are executable against your graph, and operations can't attempt to access fields that do not yet exist. -In the rare case where a configuration change is _not_ backward compatible with your gateway's query planner, you should update your registered subgraph schemas _before_ you deploy your updated code. +In the rare case where a configuration change is _not_ backward compatible with your router's query planner, you should update your registered subgraph schemas _before_ you deploy your updated code. You should also perform configuration updates that affect query planning prior to (and separately from) other changes. This helps avoid a scenario where the query planner generates queries that fail validation in downstream services or violate your resolvers. @@ -33,7 +33,7 @@ Examples of this include: - Modifying `@key`, `@requires`, or `@provides` directives - Removing a type implementation from an interface -In general, always exercise caution when pushing configuration changes that affect your gateway's query planner, and consider how those changes will affect your other subgraphs. +In general, always exercise caution when pushing configuration changes that affect your router's query planner, and consider how those changes will affect your other subgraphs. ### Example scenario @@ -101,7 +101,7 @@ query { } ``` -Currently, the gateway expands all interfaces into implementing types. +Currently, the router expands all interfaces into implementing types. ## Removing a subgraph @@ -113,13 +113,13 @@ To "de-register" a subgraph with Apollo, call `rover subgraph delete`: rover subgraph delete my-supergraph@my-variant --name accounts ``` -The next time it starts up or polls, your gateway obtains an updated configuration that reflects the removed subgraph. +The next time it starts up or polls, your router obtains an updated configuration that reflects the removed subgraph. ## Using variants to control rollout -With managed federation, you can control which version of your graph a fleet of gateways are using. In the majority of cases, rolling over all of your gateway instances to a new schema version is safe, assuming you've used [schema checks](./federated-schema-checks/) to confirm that your changes are backward compatible. +With managed federation, you can control which version of your graph a fleet of routers are using. In the majority of cases, rolling over all of your router instances to a new schema version is safe, assuming you've used [schema checks](./federated-schema-checks/) to confirm that your changes are backward compatible. -However, changes at the gateway level might involve a variety of different updates, such as [migrating entities](../entities-advanced/#migrating-entities-and-fields) from one subgraph to another. If your infrastructure requires a more advanced deployment process, you can use [graph variants](https://www.apollographql.com/docs/studio/schema/registry/#registering-a-schema-to-a-variant) to manage different fleets of gateways running with different configurations. +However, changes at the router level might involve a variety of different updates, such as [migrating entities](../entities-advanced/#migrating-entities-and-fields) from one subgraph to another. If your infrastructure requires a more advanced deployment process, you can use [graph variants](/studio/schema/registry/#registering-a-schema-to-a-variant) to manage different fleets of gateways running with different configurations. ### Example @@ -131,14 +131,14 @@ To configure a canary deployment, you might maintain two production graph varian rover subgraph check my-supergraph@prod-canary --name launches --schema ./launches/schema.graphql ``` 2. Deploy your changes to the `launches` subgraph in your production environment, _without_ running `rover subgraph publish`. - * _This ensures that your production gateway's configuration is not updated yet._ + * _This ensures that your production router's configuration is not updated yet._ 3. Update your `prod-canary` variant's registered schema, by running: ``` rover subgraph publish my-supergraph@prod-canary --name launches --schema ./launches/schema.graphql ``` - * _If composition fails due to intermediate changes to the canary graph, the canary gateway's configuration will not be updated._ + * _If composition fails due to intermediate changes to the canary graph, the canary router's configuration will not be updated._ 4. Wait for health checks to pass against the canary and confirm that operation metrics appear as expected. -5. After the canary is stable, roll out the changes to your production gateways: +5. After the canary is stable, roll out the changes to your production routers: ``` rover subgraph publish my-supergraph@prod --name=launches --schema ./launches/schema.graphql ``` @@ -206,13 +206,13 @@ With this atomic strategy, the query planner resolves all outstanding requests t ## Reliability and security -Your gateway fetches its configuration by polling Apollo Uplink, an Apollo-hosted endpoint specifically for serving supergraph configs. In the event that your updated config is inaccessible due to an outage in Uplink, your gateway continues to serve its most recently fetched configuration. +Your router fetches its configuration by polling Apollo Uplink, an Apollo-hosted endpoint specifically for serving supergraph configs. In the event that your updated config is inaccessible due to an outage in Uplink, your router continues to serve its most recently fetched configuration. -If you restart a gateway instance or spin up a _new_ instance during an Uplink outage, that instance can't fetch its configuration until Apollo resolves the outage. +If you restart a router instance or spin up a _new_ instance during an Uplink outage, that instance can't fetch its configuration until Apollo resolves the outage. ## The `subgraph publish` lifecycle -Whenever you call `rover subgraph publish` for a particular subgraph, it both updates that subgraph's registered schema and updates the gateway's managed configuration. +Whenever you call `rover subgraph publish` for a particular subgraph, it both updates that subgraph's registered schema and updates the router's managed configuration. Because your graph is dynamically changing and multiple subgraphs might be updated simultaneously, it's possible for changes to cause composition errors, even if `rover subgraph check` was successful. For this reason, updating a subgraph re-triggers composition in the cloud, ensuring that all subgraphs still compose to form a complete supergraph before updating the configuration. The workflow behind the scenes can be summed up as follows: @@ -222,9 +222,9 @@ Because your graph is dynamically changing and multiple subgraphs might be updat 4. If composition fails, the command exits and emits errors. 5. If composition succeeds, Apollo Uplink begins serving the updated supergraph schema. -On the other side of the equation sits the gateway. The gateway regularly polls Apollo Uplink for changes to its configuration. The lifecycle of dynamic configuration updates is as follows: +On the other side of the equation sits the router. The router regularly polls Apollo Uplink for changes to its configuration. The lifecycle of dynamic configuration updates is as follows: -1. The gateway polls for updates to its configuration. -2. On update, the gateway downloads the updated configuration, including the new supergraph schema. -3. The gateway uses the new supergraph schema to update its query planning logic. -4. The gateway continues to resolve in-flight requests with the previous configuration, while using the updated configuration for all new requests. +1. The router polls for updates to its configuration. +2. On update, the router downloads the updated configuration, including the new supergraph schema. +3. The router uses the new supergraph schema to update its query planning logic. +4. The router continues to resolve in-flight requests with the previous configuration, while using the updated configuration for all new requests. diff --git a/docs/source/metrics.md b/docs/source/metrics.md index 0d1f8b335..2f82f6ff7 100644 --- a/docs/source/metrics.md +++ b/docs/source/metrics.md @@ -3,20 +3,20 @@ title: Federated trace data description: How federated tracing works --- -One of the many benefits of using GraphQL as an API layer is that it enables fine-grained [tracing](https://www.apollographql.com/docs/platform/performance/#traces) of every API call. The Apollo platform supports consuming and aggregating these traces to provide detailed insights into your GraphQL layer's performance and usage. +One of the many benefits of using GraphQL as an API layer is that it enables fine-grained [tracing](/studio/metrics/usage-reporting) of every API call. The Apollo platform supports consuming and aggregating these traces to provide detailed insights into your GraphQL layer's performance and usage. -Apollo Federation supports sending **federated traces** from the Apollo gateway, which are constructed from timing and error information provided by your subgraphs. These federated traces capture the subgraph-level details in the shape of the query plan, which is sent to Apollo's [metrics ingress](https://www.apollographql.com/docs/studio/setup-analytics/#sending-metrics-to-the-reporting-endpoint) by default, and aggregated into query-level stats and field-level stats. The overall flow of a federated trace is as follows: +Apollo Federation supports sending **federated traces** from your graph router, which are constructed from timing and error information provided by your subgraphs. These federated traces capture the subgraph-level details in the shape of the query plan, which is sent to Apollo's [metrics ingress](/studio/metrics/usage-reporting) by default, and aggregated into query-level stats and field-level stats. The overall flow of a federated trace is as follows: -1. The gateway receives an operation from a client. -2. The gateway constructs a query plan for the operation, delegating sub-queries to subgraphs. -3. For each [fetch](https://www.apollographql.com/docs/federation/subgraph-spec/#fetch-service-capabilities) to a subgraph, a response is received. -4. The [`extensions`](https://www.apollographql.com/docs/resources/graphql-glossary/#extensions) of each response includes a trace from the sub-query. -5. The gateway collects the set of sub-query traces from subgraphs and arranges them in the shape of the query plan. -6. The federated trace is sent to the Apollo [metrics ingress](https://www.apollographql.com/docs/studio/setup-analytics/#sending-metrics-to-the-reporting-endpoint) for processing. +1. The router receives an operation from a client. +2. The router constructs a query plan for the operation, delegating sub-queries to subgraphs. +3. For each [fetch](./subgraph-spec/#fetch-service-capabilities) to a subgraph, a response is received. +4. The [`extensions`](/resources/graphql-glossary/#extensions) of each response includes a trace from the sub-query. +5. The router collects the set of sub-query traces from subgraphs and arranges them in the shape of the query plan. +6. The federated trace is sent to the Apollo [metrics ingress](/studio/metrics/usage-reporting/) for processing. -In summary, subgraphs report timing and error information to the gateway, and the gateway is responsible for reporting those metrics to Apollo. +In summary, subgraphs report timing and error information to the router, and the router is responsible for reporting those metrics to Apollo. -## Turning it on +## Enabling federated tracing with `@apollo/gateway` Ensure that all dependencies on `apollo-server` are at version `2.7.0` or higher. Provide an API key to your gateway via the `APOLLO_KEY` environment variable for the gateway to report metrics to the default ingress. To ensure that subgraphs do not report metrics as well, either do not provide them with an `APOLLO_KEY` or install the [`ApolloServerPluginUsageReportingDisabled` plugin](https://www.apollographql.com/docs/apollo-server/api/plugin/usage-reporting/) in your `ApolloServer`. @@ -26,13 +26,17 @@ These options will cause the Apollo gateway to collect tracing information from ## How tracing data is exposed from a subgraph -> NOTE: this section details how the gateway communicates with subgraphs around encoded tracing information and is not necessary to understand in order to enable federated tracing. +> **Note:** This section explains how your router communicates with subgraphs around encoded tracing information. It is not necessary to understand in order to enable federated tracing. -The Apollo gateway looks to the `extensions` field of all subgraph responses for the presence of an `ftv1` field. This field contains a representation of the tracing information for the sub-query that was executed against the subgraph, sent as the Base64 encoding of the [protobuf representation](https://github.com/apollographql/apollo-server/blob/main/packages/apollo-reporting-protobuf/src/reports.proto) of the trace. In order to request this information of subgraph, the gateway will send the header pair `'apollo-federation-include-trace': 'ftv1'` on fetches if configured to collect metrics, as per above. By default, a federated Apollo Server subgraph will recognize this header pair and attach tracing information in extensions of the response. +Your router inspects the `extensions` field of all subgraph responses for the presence of an `ftv1` field. This field contains a representation of the tracing information for the sub-query that was executed against the subgraph, sent as the Base64 encoding of the [protobuf representation](https://github.com/apollographql/apollo-server/blob/main/packages/apollo-reporting-protobuf/src/reports.proto) of the trace. + +To request this information of a subgraph, the router sends the header pair `'apollo-federation-include-trace': 'ftv1'` on fetches if configured to collect metrics, as per above. By default, a federated Apollo Server subgraph recognizes this header pair and attaches tracing information in extensions of the response. ## How traces are constructed and aggregated -The Apollo gateway constructs traces in the shape of the [query plan](https://www.apollographql.com/docs/federation/implementing/#inspecting-query-plans), embedding an individual `Trace` for each fetch that is performed in the query plan. This indicates the sub-query traces as well as which order they were fetched from the underlying subgraphs. The field-level statistics that the Apollo Platform aggregates from these traces are collected over the fields over which the operation was executed **in the federated subgraphs**. In other words, field stats are collected based on the operations the query planner makes rather than the operations that the clients make. On the other hand, operation-level statistics are aggregated over the operations executed **by the client**, which means that even if query-planning changes, statistics will still be corresponded to the same client-delivered operation. +Your router constructs traces in the shape of the [query plan](./query-plans/), embedding an individual `Trace` for each fetch that is performed in the query plan. This indicates the sub-query traces, as well as which order they were fetched from the underlying subgraphs. + +The field-level statistics that Apollo aggregates from these traces are collected for the fields over which the operation was executed **in the subgraphs**. In other words, field stats are collected based on the operations the query planner makes, instead of the operations that the clients make. On the other hand, operation-level statistics are aggregated over the operations executed **by the client**, which means that even if query-planning changes, statistics still correspond to the same client-delivered operation. ## How errors work @@ -40,4 +44,4 @@ The Apollo Platform provides functionality to modify error details for the clien When modifying errors for the client, you might want to use this option to hide implementation details, like database errors, from your users. When modifying errors for reporting, you might want to obfuscate or redact personal information, like user IDs or emails. -Since federated metrics collection works by collecting latency and error information from a set of distributed subgraphs, **these options are respected from those subgraphs** as well as from the gateway level. Subgraphs will embed errors in their `ftv1` extension after the `rewriteError` method (passed to the inline trace plugin in the subgraph, not the usage reporting plugin in the gateway!) is applied, and the gateway will only report the errors that are sent via that extension, ignoring the format that downstream errors are reported to end users. This functionality enables subgraph implementers to determine how error information should be displayed to both users and in metrics without needing the gateway to contain any logic that might be subgraph-specific. +Since federated metrics collection works by collecting latency and error information from a set of distributed subgraphs, **these options are respected from those subgraphs** as well as from the router. Subgraphs embed errors in their `ftv1` extension after the `rewriteError` method (passed to the inline trace plugin in the subgraph, not the usage reporting plugin in the gateway!) is applied, and the gateway only reports the errors that are sent via that extension, ignoring the format that downstream errors are reported to end users. This functionality enables subgraph implementers to determine how error information should be displayed to both users and in metrics without needing the gateway to contain any logic that might be subgraph-specific. diff --git a/docs/source/query-plans.mdx b/docs/source/query-plans.mdx index 55ff4e923..12372f7d5 100644 --- a/docs/source/query-plans.mdx +++ b/docs/source/query-plans.mdx @@ -1,11 +1,11 @@ --- title: Query plans -description: How your gateway plans operations across subgraphs +description: How your router plans operations across subgraphs --- > ⚠️ You definitely don't need to understand the details of query plans to get started with Apollo Federation! This information is provided primarily for advanced debugging purposes. -Whenever your gateway receives an incoming GraphQL operation, it needs to figure out how to use your subgraphs to populate data for each of that operation's fields. To do this, the gateway generates a **query plan**: +Whenever your router receives an incoming GraphQL operation, it needs to figure out how to use your subgraphs to populate data for each of that operation's fields. To do this, the router generates a **query plan**: ```mermaid flowchart TB; @@ -20,7 +20,7 @@ A query plan is a blueprint for dividing a single incoming operation into _one o ## Example graph -Let's say our federated graph includes these subgraphs: +Let's say our federated supergraph includes these subgraphs: @@ -52,7 +52,7 @@ type Review { -Based on these subgraphs, clients can execute the following query against our gateway: +Based on these subgraphs, clients can execute the following query against our router: ```graphql query GetHotels { @@ -66,9 +66,9 @@ query GetHotels { } ``` -This query includes fields from both the Hotels subgraph and the Reviews subgraph. Therefore, the gateway needs to send at least one query to each subgraph to populate all requested fields. +This query includes fields from both the Hotels subgraph and the Reviews subgraph. Therefore, the router needs to send at least one query to each subgraph to populate all requested fields. -Take a look at the gateway's query plan for this query: +Take a look at the router's query plan for this query: @@ -142,7 +142,7 @@ Each of these is described in further detail below. ### `Fetch` node -A `Fetch` node tells the gateway to execute a particular GraphQL operation on a particular subgraph. Every query plan includes at least one `Fetch` node. +A `Fetch` node tells the router to execute a particular GraphQL operation on a particular subgraph. Every query plan includes at least one `Fetch` node. ```graphql # Executes the query shown on the "books" subgraph @@ -188,7 +188,7 @@ QueryPlan { ### `Parallel` node -A `Parallel` node tells the gateway that all of the node's immediate children can be executed in parallel. This node appears in query plans whenever the gateway can execute completely independent operations on different subgraphs. +A `Parallel` node tells the router that all of the node's immediate children can be executed in parallel. This node appears in query plans whenever the router can execute completely independent operations on different subgraphs. ```graphql Parallel { @@ -217,7 +217,7 @@ query GetBooksAndMovies { } ``` -In this case, the data returned by each subgraph does _not_ depend on the data returned by any _other_ subgraph. Therefore, the gateway can query both subgraphs in parallel. +In this case, the data returned by each subgraph does _not_ depend on the data returned by any _other_ subgraph. Therefore, the router can query both subgraphs in parallel. The query plan for the operation looks like this: @@ -250,7 +250,7 @@ QueryPlan { ### `Sequence` node -A `Sequence` node tells the gateway that the node's immediate children _must_ be executed _serially_ in the order listed. +A `Sequence` node tells the router that the node's immediate children _must_ be executed _serially_ in the order listed. ```graphql Sequence { @@ -327,7 +327,7 @@ As shown, this query plan defines a `Sequence` that executes a `Fetch` on the Ho ### `Flatten` node -A `Flatten` node always appears inside a `Sequence` node, and it always _contains_ a `Fetch` node. It tells the gateway to merge the data returned by its `Fetch` node with data that was _previously_ `Fetch`ed during the current `Sequence`: +A `Flatten` node always appears inside a `Sequence` node, and it always _contains_ a `Fetch` node. It tells the router to merge the data returned by its `Fetch` node with data that was _previously_ `Fetch`ed during the current `Sequence`: ```graphql Flatten(path: "hotels.@") { @@ -337,7 +337,7 @@ Flatten(path: "hotels.@") { } ``` -The `Flatten` node's `path` argument tells the gateway _at what position_ to merge the newly returned data with the existing data. An `@` element in a `path` indicates that the immediately preceding path element returns a list. +The `Flatten` node's `path` argument tells the router _at what position_ to merge the newly returned data with the existing data. An `@` element in a `path` indicates that the immediately preceding path element returns a list. In the snippet above, the data returned by the `Flatten`'s `Fetch` is added to the `Sequence`'s existing data within the objects contained in the `hotels` list field. @@ -357,19 +357,19 @@ query GetHotels { } ``` -The query plan for this operation first instructs the gateway to execute this query on the Hotels subgraph: +The query plan for this operation first instructs the router to execute this query on the Hotels subgraph: ```graphql { hotels { id address - __typename # The gateway requests this to resolve references (see below) + __typename # The router requests this to resolve references (see below) } } ``` -At this point, we still need review-related information for each hotel. The query plan next instructs the gateway to query the Reviews subgraph for a list of `Hotel` objects that each have this structure: +At this point, we still need review-related information for each hotel. The query plan next instructs the router to query the Reviews subgraph for a list of `Hotel` objects that each have this structure: ```graphql { @@ -379,7 +379,7 @@ At this point, we still need review-related information for each hotel. The quer } ``` -Now, the gateway needs to know _how to merge_ these `Hotel` objects with the data it already fetched from the Hotels subgraph. The `Flatten` node's `path` argument tells it exactly that: +Now, the router needs to know _how to merge_ these `Hotel` objects with the data it already fetched from the Hotels subgraph. The `Flatten` node's `path` argument tells it exactly that: ```graphql Flatten(path: "hotels.@") { @@ -389,7 +389,7 @@ Flatten(path: "hotels.@") { In other words, "Take the `Hotel` objects returned by the Reviews subgraph and merge them with the `Hotel` objects in the top-level `hotels` field returned by the _first_ query." -When the gateway completes this merge, the resulting data exactly matches the structure of the client's original query: +When the router completes this merge, the resulting data exactly matches the structure of the client's original query: ```graphql { @@ -432,9 +432,9 @@ Flatten(path: "hotels.@") { Instead of containing a GraphQL operation, this `Fetch` node contains two **GraphQL fragments**, separated by `=>`. * The first fragment is a **representation** of the entity being resolved (in this case, `Hotel`). [Learn more about entity representations](./entities/#2-define-a-reference-resolver). -* The second fragment contains the entity fields and subfields that the gateway needs the subgraph to resolve (in this case, `Hotel.reviews` and `Review.rating`). +* The second fragment contains the entity fields and subfields that the router needs the subgraph to resolve (in this case, `Hotel.reviews` and `Review.rating`). -When the gateway sees this special `Fetch` syntax, it knows to query a subgraph's [`Query._entities` field](./subgraphs/#query_entities). This field is what enables a subgraph to provide direct access to any available fields of an entity. +When the router sees this special `Fetch` syntax, it knows to query a subgraph's [`Query._entities` field](./subgraphs/#query_entities). This field is what enables a subgraph to provide direct access to any available fields of an entity. Now that you've learned about each query plan node, take another look at the example query plan in [Example graph](#example-graph) to see how these nodes work together in a complete query plan. @@ -442,11 +442,11 @@ Now that you've learned about each query plan node, take another look at the exa You can view the query plan for a particular operation in any of the following ways: -* [In the Apollo Studio Explorer](https://www.apollographql.com/docs/studio/explorer/additional-features/#query-plans-for-federated-graphs) +* [In the Apollo Studio Explorer](/studio/explorer/additional-features/#query-plans-for-federated-graphs) * Note that you must [register your federated graph](./managed-federation/setup/) with Apollo Studio to view query plans in the Explorer. -* As direct output from your gateway (see below) +* As direct output from the `@apollo/gateway` library (see below) -### Outputting query plans from the gateway +### Outputting query plans with `@apollo/gateway` Your gateway can output the query plan for each incoming operation as it's calculated. To do so, add the following to the file where you initalize your `ApolloGateway` instance: diff --git a/docs/source/gateway.mdx b/docs/source/router.mdx similarity index 100% rename from docs/source/gateway.mdx rename to docs/source/router.mdx