Feature Proposal: Allow namespacing of GraphQL queries

[aidanhollinshead-toast]

Summary

When adding Elasticgraph to a supergraph it would be useful if the queries could all be namespaced, as opposed to always being under the top level Query.

Context

Currently, all generated queries are put at the root Query level. This works okay for people connecting directly to Elasticgraph's GraphQL endpoint, but if you want to add Elasticgraph as a sub-graph in a corporate supergraph the EG queries can get lost amidst all the others.

The Elasticgraph queries all have consistent query patterns, type names, etc. so we would like to be able to group them together. We would like to be able to put all the ElasticGraph queries into a namespace, for example olap.

Current State

Currently all generated queries get put in the root Query directly. There is the ability to specify the plural and singular names in the root query

    t.root_query_fields plural: "widgets", singular: "widget"

which will then result in a schema of

type Query {

  widgetAggregations(...) : WidgetAggregationConnection

  widgets(...) : WidgetConnection

}

Proposed Solution

Add an extra parameter to t_root_query_fields that will allow you to specify a namespace at the type level. For example

    t.root_query_fields plural: "widgets", singular: "widget", namespace: "olap"

This would then result in the following GraphQL schema.

  type Query {
    # Namespaced queries
    olap: OlapQuery!
    # all other queries
  }

  type OlapQuery {
    widgetAggregations(...) : WidgetAggregationConnection
    widgets(...) : WidgetConnection
  }

Having it on each object_type gives maximum flexibility to use different namespaces on different objects.

An alternative would be to have a query_namespace that you could wrap the object_type in

  schema.query_namespace "olap" do |ns|
    ns.object_type "Widget" do |t|
      # ...
    end

    ns.object_type ...
  end

which would produce the same GraphQL schema

[myronmarston]

Thanks for the great writeup, @aidanhollinshead-toast! This is a well-motivated feature request and I agree it's a worthwhile feature for supergraph use cases. I also think we can leverage it internally to remove some current special casing that's in place for the Query type.

I've been thinking about how to support this. Rather than a namespace: string that EG auto-expands, I think we can build on existing APIs plus one new concept: a namespace_type. Here's what I'm thinking:

Proposed Design

1. Define a namespace type (new API)

schema.namespace_type "OlapQuery" do |t|
  t.documentation "Namespace for OLAP query fields."
end

namespace_type is a new API that tells ElasticGraph "this type is a namespace for indexed type root fields." Under the hood, it's a thin wrapper over object_type -- it mostly just delegates to it but applies some namespace-specific logic on top (resolver wiring, validation, etc. -- more on that below).

2. Add it to the root Query type (existing API)

schema.on_root_query_type do |t|
  t.field "olap", "OlapQuery" do |f|
    f.documentation "Namespace for OLAP query fields."
  end
end

on_root_query_type already exists, so you can use it today. EG will auto-wire a resolver for any no-args field that references a namespace type. Users who want to use a custom namespace will be responsible for adding their namespace field to Query using this API.

3. Target it from root_query_fields (via a new on: option)

schema.object_type "Widget" do |t|
  t.root_query_fields plural: "widgets", singular: "widget", on: "OlapQuery"
  # ...
end

The new on: option would have a default value of "Query"--essentially "Query" simply becomes the "default" namespace.

This produces:

type Query {
  olap: OlapQuery!
}

type OlapQuery {
  widgetAggregations(...): WidgetAggregationConnection
  widgets(...): WidgetConnection
}

Deep nesting

You can nest namespaces arbitrarily. If you want olap.domain1.widgets and olap.domain2.otherTypes:

schema.namespace_type "OlapQuery" do |t|
  # Fields referencing other namespace types define the nesting.
  t.field "domain1", "Domain1Query"
  t.field "domain2", "Domain2Query"
end

schema.namespace_type "Domain1Query"
schema.namespace_type "Domain2Query"

schema.on_root_query_type do |t|
  t.field "olap", "OlapQuery"
end

schema.object_type "Widget" do |t|
  t.root_query_fields plural: "widgets", on: "Domain1Query"
  # ...
end

schema.object_type "OtherType" do |t|
  t.root_query_fields plural: "otherTypes", on: "Domain2Query"
  # ...
end

Why namespace_type instead of plain object_type

EG needs to know which types are namespaces so it can:

• Automatically wire up resolvers: a constant_value resolver (configured with {}) for no-args fields referencing a namespace type, and the existing resolver for indexed type fields on a namespace.
• Set resolve_fields_with nil on namespace types (so each field uses its own resolver).
• Validate that on: references a namespace type, not an arbitrary object type.
• Custom fields with custom resolvers are still supported on namespace types, just like on Query today.

Why this over namespace: "olap"

• Composes with existing concepts -- namespaces are types with fields, not a magic string.
• Supports arbitrary nesting -- deep nesting falls out naturally.
• Explicit over implicit -- the user controls the type name, field name, and documentation.

Limitation

This doesn't support putting the document query field (e.g. widgets) and the aggregation query field (e.g. widgetAggregations) on different namespace types. I don't think that's a common need, and the root_query_fields API could be evolved later to support it if needed.

Changes needed

Here's a rough list of the changes I expect we'll need to make:

Unify Query as a namespace type

Currently, Query is defined as a special case in Results#define_root_graphql_type. The first step is to rework Query to be modeled as a namespace_type internally:

1. Define Query as a namespace type in built_in_types.rb instead of special-casing it in results.rb. Query becomes the "root" namespace type that others can nest under.

2. Rework Results#define_root_graphql_type: Instead of this method iterating over all directly-queryable types and adding fields to Query, each indexed type's root_query_fields call should register an after_user_definition_complete callback that adds its fields to the target namespace type. This decentralizes the logic and means define_root_graphql_type no longer needs to exist as a monolithic method.

New namespace_type API

3. api.rb: Add schema.namespace_type method. It's a thin wrapper over object_type that delegates to it but additionally marks the type as a namespace and sets resolve_fields_with nil.

4. has_indices.rb: Add on: keyword parameter to root_query_fields (default: "Query"). The root_query_fields call registers an after_user_definition_complete callback that adds the type's fields to the target namespace (via relates_to_many, same as today), capturing on:, plural:, singular:, and the customization block via closure. When root_query_fields isn't called (it's currently optional), the index call registers a default callback that adds fields to Query with default names, guarded by a flag so it's a no-op if root_query_fields was also called.

Resolvers

5. constant_value resolver (new, general-purpose): Returns a configurable constant value. For namespace fields (e.g. Query.olap), configured with {} -- the child fields don't use the parent object, so the value just needs to be non-null. Auto-wired for any no-args field that references a namespace type.

6. Rename ListRecords to IndexedTypeRootFieldsResolver (prep PR): The current name is misleading since it handles both document listing and aggregations. A rename clarifies its role.

Validation

7. on: must reference a namespace type: Error if it names a regular object type or a type that doesn't exist. This validation belongs in the after_user_definition_complete callback, since namespace types may be defined in any order.

8. Namespace types must be reachable from the root Query type: if a user defines a namespace_type and forgets to also define a path to it from "parent" types (e.g. a field on Query, or a field on another namespace_type which is reachable from Query), then we should raise a validation error telling the user of their mistake.

9. Fields on namespace types: Custom fields with custom resolvers are fine. For fields without a resolver, the existing SchemaError ("needs a resolver") already fires at schema artifact generation time, so no additional enforcement is needed.

Testing

10. Schema definition unit tests: namespace_type API, on: parameter, generated schema structure, resolver wiring.

11. Integration/acceptance tests: End-to-end queries through a namespace (document + aggregation queries), multi-level nesting (e.g. olap.domain.widgets).

12. Regression tests for Query as default namespace: Existing behavior (no on: specified) should be unchanged after the Query-as-namespace-type refactor.

Documentation

13. YARD docs: New namespace_type API, updated root_query_fields with on: parameter and examples.

14. User-facing docs: Add a section on namespacing queries (e.g. in the schema definition guide).

---

@aidanhollinshead-toast how does that design sound? Can you tackle adding this? Before you start, it would be good to discuss the PR breakdown as it's helpful to review this via a series of small stacked PRs.

[myronmarston]

Closing as this has been implemented. It'll be in the next release.