Olap 582 namespaced queries pr2

[rossroberts-toast]

Part 2 of the stacked PR series implementing query namespacing
(#1130). This PR introduces the building blocks without any
consumers yet — the root Query type is converted to use them in
PR 3.

What this PR adds:

• schema.namespace_type "Foo": schema definition API for
  declaring a GraphQL object type that groups root query fields
  under a shared intermediate path (e.g. Query.olap.widgets
  instead of Query.widgets).
• :namespace_ref resolver: auto-wired on any no-argument field
  whose return type is a namespace type. Returns {} as a
  non-null passthrough so each child field's own resolver can
  run. Users never reference it directly.
• :constant_value resolver: a standalone primitive that
  returns a configured value for fields that carry no data of
  their own. Available for user schemas; not coupled to
  namespacing.

Behavior:

A field on any type (Query, a namespace type, or a regular
indexed type) whose return type is a namespace type and which
has no args or explicit resolver is auto-wired to
:namespace_ref. Namespace types are excluded from index
mappings, JSON schemas, and derived GraphQL types (filters,
sort orders, aggregations, highlights), as are fields on
indexed types that reference them, since there's no backing
data to act on.

Infrastructure

• state.namespace_types_by_name registry populated at schema
  definition time.
• Field#target_type_is_namespace? predicate used by both the
  resolver auto-wire and the indexing-suppression logic.

There are no consumers of namespace_type yet — PR 3 converts
the root Query type to use these primitives.

[myronmarston]

I'm not done reviewing but have to call it a day and I wanted to submit my feedback so far.

[myronmarston]

It's a little funny that the field is treated as graphql-only here, but field.graphql_only will return false for it. In Field#initialize can we do this?

def initialize(
  # ...
)
  type_ref = schema_def_state.type_ref(type)
  super(
    # ...
  )

  self.graphql_only = true if target_type_is_namespace?
  # ... the rest of the logic ...
end

That way, the field is consistently treated as a graphql-only field, and this can just check unless field.graphql_only

Edit: I just realized a significant problem here. ElasticGraph is designed to produce the same schema artifacts no matter what order types are defined in. But target_type_is_namespace?

field.target_type_is_namespace? is timing-specific: when called on a field referencing a namespace type that has not yet been defined, it'll return false...and then later it'll return true. That means that we have to be very careful with how we use it. It's safe to use after the user is finished defining their schema (while ElasticGraph is generating the schema artifacts) but it's not safe to use while we're evaluating the user's schema definition.

One way we deal with this is to check state.user_definition_complete, like so:

elasticgraph/elasticgraph-schema_definition/lib/elastic_graph/schema_definition/state.rb

Lines 188 to 190 in 3cd0da0

	unless user_definition_complete
	raise Errors::SchemaError, "Cannot access `user_defined_field_references_by_type_name` until the schema definition is complete."
	end

I think we should similarly prevent calls to target_type_is_namespace? when the user definition is incomplete. That way, it'll be accurate every time it's used and when it's called from a context in which it isn't accurate, we'll raise an error.

[myronmarston]

👍 thanks for the thorough docs!