Skip to main content

Namespaced operations

Grouping also works with namespaced operations (for example, Query.analytics.*, Mutation.admin.*, or Subscription.events.*).

If a root operation returns a namespace object, nested fields are generated as operation pages.

Namespace object type names must follow the corresponding operation suffix convention (*Query, *Mutation, *Subscription).

type Query {
  analytics: AnalyticsQuery @doc(category: "Grade")
}

type AnalyticsQuery @doc(category: "Grade") {
  semesterGPA(semesterId: ID!): Int @doc(category: "Grade")
  coursesByDepartment(departmentId: ID!): [Course!]! @doc(category: "Course")
}

Generated operation pages include nested paths such as:

  • operations/queries/analytics/semester-gpa
  • operations/queries/analytics/courses-by-department

When groupByDirective is enabled, these namespaced operations are still grouped by their directive category.

Generated code snippet for these namespaced operations will be wrapped in the namespace:

analytics {
  coursesByDepartment(
    departmentId: ID!
  ): [Course!]!
}

Disable namespace wrapping with hooks​

If you want to keep nested output paths but render operation code blocks without the namespace wrapper, use beforePrintCodeHook in your custom MDX module.

This hook runs before the code block is generated, so you can clear operationNamespaceParts only for the printed snippet.

custom-mdx.mjs
import { isOperation } from "@graphql-markdown/graphql";

const beforePrintCodeHook = async (event) => {
  const { type } = event.data;

  if (!isOperation(type)) {
    return;
  }

  event.data.options.operationNamespaceParts = null;
};

export { beforePrintCodeHook };

Then register the module with mdxParser as described in Hooks Recipes and Integration with Frameworks.

With this hook enabled, a namespaced operation page can still be generated at operations/queries/analytics/courses-by-department, but its code block will render without the namespace wrapper:

coursesByDepartment(
  departmentId: ID!
): [Course!]!