Rename __count meta field to _x_count and release v1.10.0. (kensho-technologies#176)

* Rename __count meta field to _x_count and release v1.10.0.

* Fix changelog link to PR.

* Update with link to GraphQL spec.

Author: obi1kenobi

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Current development version
 
+## v1.10.0
+
+- **BREAKING**: Rename the `__count` meta field to `_x_count`, to avoid GraphQL schema parsing issues with other GraphQL libraries. [#176](https://github.com/kensho-technologies/graphql-compiler/pull/176)
+
 ## v1.9.0
 
 - Add a `__count` meta field that supports outputting and filtering on the size of a `@fold` scope. [#158](https://github.com/kensho-technologies/graphql-compiler/pull/158)

README.md

@@ -46,7 +46,7 @@ It's modeled after Python's `json.tool`, reading from stdin and writing to stdou
   * [Type coercions](#type-coercions)
   * [Meta fields](#meta-fields)
      * [\__typename](#__typename)
-     * [\__count](#__count)
+     * [\_x_count](#_x_count)
   * [The GraphQL schema](#the-graphql-schema)
   * [Execution model](#execution-model)
   * [Miscellaneous](#miscellaneous)
@@ -790,16 +790,23 @@ and others. Vertices of all subtypes of `Entity` will therefore be returned, and
 column that outputs the `__typename` field will show their runtime type: `Animal`, `Species`,
 `Food`, etc.
 
-### \_\_count
+### \_x\_count
 
-The `__count` meta field is a non-standard meta field defined by the GraphQL compiler that makes it
+The `_x_count` meta field is a non-standard meta field defined by the GraphQL compiler that makes it
 possible to interact with the _number_ of elements in a scope marked `@fold`. By applying directives
 like `@output` and `@filter` to this meta field, queries can output the number of elements captured
 in the `@fold` and filter down results to select only those with the desired fold sizes.
 
-#### Adding the `__count` meta field to your schema
+We use the `_x_` prefix to signify that this is an extension meta field introduced by the compiler,
+and not part of the canonical set of GraphQL meta fields defined by the GraphQL specification.
+We do not use the GraphQL standard double-underscore (`__`) prefix for meta fields,
+since all names with that prefix are
+[explicitly reserved and prohibited from being used](https://facebook.github.io/graphql/draft/#sec-Reserved-Names)
+in directives, fields, or any other artifacts.
 
-Since the `__count` meta field is not currently part of the GraphQL standard, it has to be
+#### Adding the `_x_count` meta field to your schema
+
+Since the `_x_count` meta field is not currently part of the GraphQL standard, it has to be
 explicitly added to all interfaces and types in your schema. There are two ways to do this.
 
 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)
     Animal {
         name @output(out_name: "name")
         out_Animal_ParentOf @fold {
-            __count @output(out_name: "number_of_children")
+            _x_count @output(out_name: "number_of_children")
             name @output(out_name: "child_names")
         }
     }
@@ -849,7 +856,7 @@ the output type of the `number_of_children` selection is an integer.
     Animal {
         name @output(out_name: "name")
         out_Animal_ParentOf @fold {
-            __count @filter(op_name: ">=", value: ["$min_children"])
+            _x_count @filter(op_name: ">=", value: ["$min_children"])
                     @output(out_name: "number_of_children")
             name @filter(op_name: "has_substring", value: ["$substr"])
                  @output(out_name: "child_names")
@@ -861,24 +868,24 @@ Here, we've modified the above query to add two more filtering constraints to th
 - child `Animal` vertices must contain the value of `$substr` as a substring in their name, and
 - `Animal` vertices must have at least `$min_children` children that satisfy the above filter.
 
-Importantly, any filtering on `__count` is applied *after* any other filters and type coercions
+Importantly, any filtering on `_x_count` is applied *after* any other filters and type coercions
 that are present in the `@fold` in question. This order of operations matters a lot: selecting
 `Animal` vertices with 3+ children, then filtering the children based on their names is not the same
 as filtering the children first, and then selecting `Animal` vertices that have 3+ children that
 matched the earlier filter.
 
 #### Constraints and Rules
-- The `__count` field is only allowed to appear within a vertex field marked `@fold`.
-- Filtering on `__count` is always applied *after* any other filters and type coercions present
+- The `_x_count` field is only allowed to appear within a vertex field marked `@fold`.
+- Filtering on `_x_count` is always applied *after* any other filters and type coercions present
   in that `@fold`.
-- Filtering or outputting the value of the `__count` field must always be done at the innermost
+- Filtering or outputting the value of the `_x_count` field must always be done at the innermost
   scope of the `@fold`. It is invalid to expand vertex fields within a `@fold` after filtering
-  or outputting the value of the `__count` meta field.
+  or outputting the value of the `_x_count` meta field.
 
-#### How is filtering on `__count` different from `@filter` with `has_edge_degree`?
+#### How is filtering on `_x_count` different from `@filter` with `has_edge_degree`?
 
 The `has_edge_degree` filter allows filtering based on the number of edges of a particular type.
-There are situations in which filtering with `has_edge_degree` and filtering using `=` on `__count`
+There are situations in which filtering with `has_edge_degree` and filtering using `=` on `_x_count`
 produce equivalent queries. Here is one such pair of queries:
 ```
 {
@@ -896,7 +903,7 @@ and
     Species {
         name @output(out_name: "name")
         in_Animal_OfSpecies @fold {
-            __count @filter(op_name: "=", value: ["$num_animals"])
+            _x_count @filter(op_name: "=", value: ["$num_animals"])
         }
     }
 }
@@ -928,7 +935,7 @@ versus
         name @output(out_name: "name")
         in_Animal_OfSpecies @fold {
             out_Animal_LivesIn {
-                __count @filter(op_name: "=", value: ["$num_animals"])
+                _x_count @filter(op_name: "=", value: ["$num_animals"])
                 name @filter(op_name: "=", value: ["$location"])
             }
         }
@@ -939,7 +946,7 @@ In the first, for the purposes of the `has_edge_degree` filtering, the location
 live is irrelevant: the `has_edge_degree` only makes sure that the `Species` vertex has the
 correct number of edges of type `in_Animal_OfSpecies`, and that's it. In contrast, the second query
 ensures that only `Species` vertices that have `$num_animals` animals that live in the selected
-location are returned -- the location matters since the `@filter` on the `__count` field applies
+location are returned -- the location matters since the `@filter` on the `_x_count` field applies
 to the number of elements in the `@fold` scope.
 
 ## The GraphQL schema

graphql_compiler/__init__.py

@@ -20,7 +20,7 @@
 
 
 __package_name__ = 'graphql-compiler'
-__version__ = '1.9.0'
+__version__ = '1.10.0'
 
 
 def graphql_to_match(schema, graphql_query, parameters, type_equivalence_hints=None):

graphql_compiler/compiler/blocks.py

@@ -478,7 +478,7 @@ class GlobalOperationsStart(MarkerBlock):
 
     Global operations include, for example, various kinds of filters that affect more than one
     location in the query. Such filters are produced, e.g., as part of nested-optional processing,
-    or when filters are applied to the "__count" meta property.
+    or when filters are applied to the "_x_count" meta property.
     """
 
     __slots__ = ()

graphql_compiler/compiler/compiler_frontend.py

@@ -564,7 +564,7 @@ def _validate_fold_has_outputs_or_count_filter(fold_scope_location, fold_has_cou
     # This function makes sure that the @fold scope has an effect.
     # Folds either output data, or filter the data enclosing the fold based on the size of the fold.
     if fold_has_count_filter:
-        # This fold has a filter on the "__count" property, so it is legal and has an effect.
+        # This fold has a filter on the "_x_count" property, so it is legal and has an effect.
         return True
 
     # At least one output in the outputs list must point to the fold_scope_location,

graphql_compiler/compiler/context_helpers.py

@@ -48,7 +48,7 @@ def set_fold_scope_data(context, data):
 
 
 def has_fold_count_filter(context):
-    """Return True if the current context contains a filter on the __count field."""
+    """Return True if the current context contains a filter on the _x_count field."""
     return CONTEXT_FOLD_HAS_COUNT_FILTER in context
 
 
@@ -58,7 +58,7 @@ def unmark_fold_count_filter(context):
 
 
 def set_fold_count_filter(context):
-    """Set a mark indicating the presence of a filter on a fold __count field."""
+    """Set a mark indicating the presence of a filter on a fold _x_count field."""
     context[CONTEXT_FOLD_HAS_COUNT_FILTER] = True
 
 

graphql_compiler/compiler/expressions.py

@@ -505,7 +505,7 @@ def validate(self):
 
         if self.fold_scope_location.field == COUNT_META_FIELD_NAME:
             if not GraphQLInt.is_same_type(self.field_type):
-                raise TypeError(u'Expected the __count meta-field to be of GraphQLInt type, but '
+                raise TypeError(u'Expected the _x_count meta-field to be of GraphQLInt type, but '
                                 u'encountered type {} instead: {}'
                                 .format(self.field_type, self.fold_scope_location))
         else:

graphql_compiler/schema.py

@@ -280,7 +280,7 @@ def _parse_datetime_value(value):
 
 
 TYPENAME_META_FIELD_NAME = '__typename'  # This meta field is built-in.
-COUNT_META_FIELD_NAME = '__count'
+COUNT_META_FIELD_NAME = '_x_count'
 
 
 ALL_SUPPORTED_META_FIELDS = frozenset((
@@ -311,7 +311,7 @@ def insert_meta_fields_into_existing_schema(graphql_schema):
     Use this function at your own risk. Don't say you haven't been warned.
 
     Properties added include:
-        - "__count", which allows filtering folds based on the number of elements they capture.
+        - "_x_count", which allows filtering folds based on the number of elements they capture.
 
     Args:
         graphql_schema: GraphQLSchema object describing the schema that is going to be used with

graphql_compiler/tests/test_input_data.py

@@ -1890,7 +1890,7 @@ def output_count_in_fold_scope():
         Animal {
             name @output(out_name: "name")
             out_Animal_ParentOf @fold {
-                __count @output(out_name: "number_of_children")
+                _x_count @output(out_name: "number_of_children")
                 name @output(out_name: "child_names")
             }
         }
@@ -1914,7 +1914,7 @@ def filter_count_with_runtime_parameter_in_fold_scope():
         Animal {
             name @output(out_name: "name")
             out_Animal_ParentOf @fold {
-                __count @filter(op_name: ">=", value: ["$min_children"])
+                _x_count @filter(op_name: ">=", value: ["$min_children"])
                 name @output(out_name: "child_names")
             }
         }
@@ -1942,7 +1942,7 @@ def filter_count_with_tagged_parameter_in_fold_scope():
                 limbs @tag(tag_name: "limbs")
             }
             out_Animal_ParentOf @fold {
-                __count @filter(op_name: ">=", value: ["%limbs"])
+                _x_count @filter(op_name: ">=", value: ["%limbs"])
                 name @output(out_name: "child_names")
             }
         }
@@ -1965,7 +1965,7 @@ def filter_count_and_other_filters_in_fold_scope():
         Animal {
             name @output(out_name: "name")
             out_Animal_ParentOf @fold {
-                __count @filter(op_name: ">=", value: ["$min_children"])
+                _x_count @filter(op_name: ">=", value: ["$min_children"])
                         @output(out_name: "number_of_children")
                 alias @filter(op_name: "contains", value: ["$expected_alias"])
             }
@@ -1992,10 +1992,10 @@ def multiple_filters_on_count():
         Animal {
             name @output(out_name: "name")
             out_Animal_ParentOf @fold {
-                __count @filter(op_name: ">=", value: ["$min_children"])
+                _x_count @filter(op_name: ">=", value: ["$min_children"])
             }
             out_Entity_Related @fold {
-                __count @filter(op_name: ">=", value: ["$min_related"])
+                _x_count @filter(op_name: ">=", value: ["$min_related"])
             }
         }
     }'''
@@ -2020,7 +2020,7 @@ def filter_on_count_with_nested_filter():
             name @output(out_name: "name")
             in_Animal_OfSpecies @fold {
                 out_Animal_LivesIn {
-                    __count @filter(op_name: "=", value: ["$num_animals"])
+                    _x_count @filter(op_name: "=", value: ["$num_animals"])
                     name @filter(op_name: "=", value: ["$location"])
                 }
             }

graphql_compiler/tests/test_ir_generation_errors.py

@@ -317,7 +317,7 @@ def test_fold_directive_constraints(self):
             Animal {
                 name @output(out_name: "name")
                 out_Animal_ParentOf {
-                    __count @output(out_name: "child_count")
+                    _x_count @output(out_name: "child_count")
                 }
             }
         }'''
@@ -326,7 +326,7 @@ def test_fold_directive_constraints(self):
             Species {
                 name @output(out_name: "name")
                 in_Animal_OfSpecies @fold {
-                    __count @output(out_name: "fold_size")
+                    _x_count @output(out_name: "fold_size")
                     out_Animal_LivesIn {
                         name @filter(op_name: "=", value: ["$location"])
                     }
@@ -338,9 +338,9 @@ def test_fold_directive_constraints(self):
             Species {
                 name @output(out_name: "name")
                 in_Animal_OfSpecies @fold {
-                    __count @output(out_name: "fold_size")
+                    _x_count @output(out_name: "fold_size")
                     out_Animal_LivesIn {
-                        __count @filter(op_name: "=", value: ["$num_animals"])
+                        _x_count @filter(op_name: "=", value: ["$num_animals"])
                     }
                 }
             }
@@ -350,9 +350,9 @@ def test_fold_directive_constraints(self):
             Species {
                 name @output(out_name: "name")
                 in_Animal_OfSpecies @fold {
-                    __count @filter(op_name: "=", value: ["$num_animals"])
+                    _x_count @filter(op_name: "=", value: ["$num_animals"])
                     out_Animal_LivesIn {
-                        __count @output(out_name: "fold_size")
+                        _x_count @output(out_name: "fold_size")
                     }
                 }
             }
@@ -485,7 +485,7 @@ def test_tag_directive_constraints(self):
             Animal {
                 name @output(out_name: "name")
                 out_Animal_ParentOf {
-                    __count @tag(tag_name: "count")
+                    _x_count @tag(tag_name: "count")
                 }
             }
         }''')