Commit 74a12c78 authored by Paul Gascou-Vaillancourt's avatar Paul Gascou-Vaillancourt Committed by Marcia Ramos

Clarify documentation about feature-flagged GraphQL entities

parent 18826bf0
......@@ -421,14 +421,16 @@ is still validated.
Again, make sure that those overrides are as short-lived as possible by tracking their removal in
the appropriate issue.
#### Feature flags in queries
#### Feature-flagged queries
Sometimes it may be helpful to have an entity in the GraphQL query behind a feature flag.
One example is working on a feature where the backend has already been merged but the frontend
has not. In this case, you may consider putting the GraphQL entity behind a feature flag to allow smaller
merge requests to be created and merged.
In cases where the backend is complete and the frontend is being implemented behind a feature flag,
a couple options are available to leverage the feature flag in the GraphQL queries.
To do this we can use the `@include` directive to exclude an entity if the `if` statement passes.
##### The `@include` directive
The `@include` (or its opposite, `@skip`) can be used to control whether an entity should be
included in the query. If the `@include` directive evaluates to `false`, the entity's resolver is
not hit and the entity is excluded from the response. For example:
```graphql
query getAuthorData($authorNameEnabled: Boolean = false) {
......@@ -456,6 +458,34 @@ export default {
};
```
Note that, even if the directive evalutes to `false`, the guarded entity is sent to the backend and
matched against the GraphQL schema. So this approach requires that the feature-flagged entity
exists in the schema, even if the feature flag is disabled. When the feature flag is turned off, it
is recommended that the resolver returns `null` at the very least.
##### Different versions of a query
There's another approach that involves duplicating the standard query, and it should be avoided. The copy includes the new entities
while the original remains unchanged. It is up to the production code to trigger the right query
based on the feature flag's status. For example:
```javascript
export default {
apollo: {
user: {
query() {
return this.glFeatures.authorNameEnabled ? NEW_QUERY : ORIGINAL_QUERY,
}
}
},
};
```
This approach is not recommended as it results in bigger merge requests and requires maintaining
two similar queries for as long as the feature flag exists. This can be used in cases where the new
GraphQL entities are not yet part of the schema, or if they are feature-flagged at the schema level
(`new_entitiy: :feature_flag`).
### Manually triggering queries
Queries on a component's `apollo` property are made automatically when the component is created.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment