@@ -46,7 +46,7 @@ It's modeled after Python's `json.tool`, reading from stdin and writing to stdou
46
46
* [ Type coercions] ( #type-coercions )
47
47
* [ Meta fields] ( #meta-fields )
48
48
* [ \_ _ typename] ( #__typename )
49
- * [ \_ _ count ] ( #__count )
49
+ * [ \_ x_count ] ( #_x_count )
50
50
* [ The GraphQL schema] ( #the-graphql-schema )
51
51
* [ Execution model] ( #execution-model )
52
52
* [ Miscellaneous] ( #miscellaneous )
@@ -790,16 +790,23 @@ and others. Vertices of all subtypes of `Entity` will therefore be returned, and
790
790
column that outputs the ` __typename ` field will show their runtime type: ` Animal ` , ` Species ` ,
791
791
` Food ` , etc.
792
792
793
- ### \_ \_ count
793
+ ### \_ x \_ count
794
794
795
- The ` __count ` meta field is a non-standard meta field defined by the GraphQL compiler that makes it
795
+ The ` _x_count ` meta field is a non-standard meta field defined by the GraphQL compiler that makes it
796
796
possible to interact with the _ number_ of elements in a scope marked ` @fold ` . By applying directives
797
797
like ` @output ` and ` @filter ` to this meta field, queries can output the number of elements captured
798
798
in the ` @fold ` and filter down results to select only those with the desired fold sizes.
799
799
800
- #### Adding the ` __count ` meta field to your schema
800
+ We use the ` _x_ ` prefix to signify that this is an extension meta field introduced by the compiler,
801
+ and not part of the canonical set of GraphQL meta fields defined by the GraphQL specification.
802
+ We do not use the GraphQL standard double-underscore (` __ ` ) prefix for meta fields,
803
+ since all names with that prefix are
804
+ [ explicitly reserved and prohibited from being used] ( https://facebook.github.io/graphql/draft/#sec-Reserved-Names )
805
+ in directives, fields, or any other artifacts.
801
806
802
- Since the ` __count ` meta field is not currently part of the GraphQL standard, it has to be
807
+ #### Adding the ` _x_count ` meta field to your schema
808
+
809
+ Since the ` _x_count ` meta field is not currently part of the GraphQL standard, it has to be
803
810
explicitly added to all interfaces and types in your schema. There are two ways to do this.
804
811
805
812
The preferred way to do this is to use the ` EXTENDED_META_FIELD_DEFINITIONS ` constant as
@@ -834,7 +841,7 @@ insert_meta_fields_into_existing_schema(existing_schema)
834
841
Animal {
835
842
name @output(out_name: "name")
836
843
out_Animal_ParentOf @fold {
837
- __count @output(out_name: "number_of_children")
844
+ _x_count @output(out_name: "number_of_children")
838
845
name @output(out_name: "child_names")
839
846
}
840
847
}
@@ -849,7 +856,7 @@ the output type of the `number_of_children` selection is an integer.
849
856
Animal {
850
857
name @output(out_name: "name")
851
858
out_Animal_ParentOf @fold {
852
- __count @filter(op_name: ">=", value: ["$min_children"])
859
+ _x_count @filter(op_name: ">=", value: ["$min_children"])
853
860
@output(out_name: "number_of_children")
854
861
name @filter(op_name: "has_substring", value: ["$substr"])
855
862
@output(out_name: "child_names")
@@ -861,24 +868,24 @@ Here, we've modified the above query to add two more filtering constraints to th
861
868
- child ` Animal ` vertices must contain the value of ` $substr ` as a substring in their name, and
862
869
- ` Animal ` vertices must have at least ` $min_children ` children that satisfy the above filter.
863
870
864
- Importantly, any filtering on ` __count ` is applied * after* any other filters and type coercions
871
+ Importantly, any filtering on ` _x_count ` is applied * after* any other filters and type coercions
865
872
that are present in the ` @fold ` in question. This order of operations matters a lot: selecting
866
873
` Animal ` vertices with 3+ children, then filtering the children based on their names is not the same
867
874
as filtering the children first, and then selecting ` Animal ` vertices that have 3+ children that
868
875
matched the earlier filter.
869
876
870
877
#### Constraints and Rules
871
- - The ` __count ` field is only allowed to appear within a vertex field marked ` @fold ` .
872
- - Filtering on ` __count ` is always applied * after* any other filters and type coercions present
878
+ - The ` _x_count ` field is only allowed to appear within a vertex field marked ` @fold ` .
879
+ - Filtering on ` _x_count ` is always applied * after* any other filters and type coercions present
873
880
in that ` @fold ` .
874
- - Filtering or outputting the value of the ` __count ` field must always be done at the innermost
881
+ - Filtering or outputting the value of the ` _x_count ` field must always be done at the innermost
875
882
scope of the ` @fold ` . It is invalid to expand vertex fields within a ` @fold ` after filtering
876
- or outputting the value of the ` __count ` meta field.
883
+ or outputting the value of the ` _x_count ` meta field.
877
884
878
- #### How is filtering on ` __count ` different from ` @filter ` with ` has_edge_degree ` ?
885
+ #### How is filtering on ` _x_count ` different from ` @filter ` with ` has_edge_degree ` ?
879
886
880
887
The ` has_edge_degree ` filter allows filtering based on the number of edges of a particular type.
881
- There are situations in which filtering with ` has_edge_degree ` and filtering using ` = ` on ` __count `
888
+ There are situations in which filtering with ` has_edge_degree ` and filtering using ` = ` on ` _x_count `
882
889
produce equivalent queries. Here is one such pair of queries:
883
890
```
884
891
{
896
903
Species {
897
904
name @output(out_name: "name")
898
905
in_Animal_OfSpecies @fold {
899
- __count @filter(op_name: "=", value: ["$num_animals"])
906
+ _x_count @filter(op_name: "=", value: ["$num_animals"])
900
907
}
901
908
}
902
909
}
@@ -928,7 +935,7 @@ versus
928
935
name @output(out_name: "name")
929
936
in_Animal_OfSpecies @fold {
930
937
out_Animal_LivesIn {
931
- __count @filter(op_name: "=", value: ["$num_animals"])
938
+ _x_count @filter(op_name: "=", value: ["$num_animals"])
932
939
name @filter(op_name: "=", value: ["$location"])
933
940
}
934
941
}
@@ -939,7 +946,7 @@ In the first, for the purposes of the `has_edge_degree` filtering, the location
939
946
live is irrelevant: the ` has_edge_degree ` only makes sure that the ` Species ` vertex has the
940
947
correct number of edges of type ` in_Animal_OfSpecies ` , and that's it. In contrast, the second query
941
948
ensures that only ` Species ` vertices that have ` $num_animals ` animals that live in the selected
942
- location are returned -- the location matters since the ` @filter ` on the ` __count ` field applies
949
+ location are returned -- the location matters since the ` @filter ` on the ` _x_count ` field applies
943
950
to the number of elements in the ` @fold ` scope.
944
951
945
952
## The GraphQL schema
0 commit comments