summaryrefslogtreecommitdiff
path: root/doc/development/fe_guide/graphql.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/development/fe_guide/graphql.md')
-rw-r--r--doc/development/fe_guide/graphql.md44
1 files changed, 37 insertions, 7 deletions
diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md
index 3b49601f027..0229aa0123a 100644
--- a/doc/development/fe_guide/graphql.md
+++ b/doc/development/fe_guide/graphql.md
@@ -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 evaluates 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_entity: :feature_flag`).
+
### Manually triggering queries
Queries on a component's `apollo` property are made automatically when the component is created.
@@ -1310,7 +1340,7 @@ describe('when query times out', () => {
expect(getAlert().exists()).toBe(false);
expect(getGraph().exists()).toBe(true);
- /* fails again, alert retuns but data persists */
+ /* fails again, alert returns but data persists */
await advanceApolloTimers();
expect(getAlert().exists()).toBe(true);
expect(getGraph().exists()).toBe(true);