Behaviour and utilities for GraphQL schema management.

Defines the contract for modules that provide GraphQL schemas and includes a __using__ macro for easy schema module setup with automatic file loading and validation.

Options for use GraphqlQuery.Schema:

• :schema_path - Path to a .graphql or .gql schema file to load.
• :absinthe_schema - An Absinthe schema module to extract the schema from.
• :remote - Keyword list with remote schema configuration. Requires at least :url. Supports :mode option — :fetch (default, GET SDL directly) or :introspect (POST introspection query, convert JSON response to SDL). The schema file is auto-derived from the module name and stored locally. Use mix graphql_query.schema.fetch to download remote schemas.
• :schemas_dir - Directory for storing remote schemas (used with :remote). Defaults to application config or "priv/graphql/schemas".
• :federation - Enable Apollo Federation directive support when loading the schema.

Option Combinations

Some options are mutually exclusive and will raise a CompileError if combined:

• :absinthe_schema + :remote — cannot be used together
• :absinthe_schema + :schema_path — cannot be used together
• :schemas_dir without :remote — :schemas_dir is only meaningful with :remote
• :schema_path + :remote + :schemas_dir — when :schema_path is provided with :remote, it fully specifies the file location, making :schemas_dir redundant

The valid combination of :schema_path + :remote uses the explicit path for both loading the schema at compile time and as the save target for mix graphql_query.schema.fetch, overriding the auto-derived path from the module name.

Examples

defmodule MyApp.Schema do
  use GraphqlQuery.Schema, schema_path: "priv/schema.graphql"
end

defmodule MyApp.AbsintheSchema do
  use GraphqlQuery.Schema, absinthe_schema: MyAppWeb.Graphql.Schema
end

defmodule MyApp.FederatedSchema do
  use GraphqlQuery.Schema,
    schema_path: "priv/federated_schema.graphql",
    federation: true
end

# Remote schema - auto-derives file path from module name
defmodule MyApp.ExternalApi.Schema do
  use GraphqlQuery.Schema,
    remote: [url: "https://api.example.com/schema.graphql"]
end
# Schema file: priv/graphql/schemas/my_app/external_api/schema.graphql
# Fetch with: mix graphql_query.schema.fetch

# Remote schema with explicit file path (overrides auto-derived path)
defmodule MyApp.ExternalApi.CustomPath do
  use GraphqlQuery.Schema,
    remote: [url: "https://api.example.com/schema.graphql"],
    schema_path: "priv/graphql/external_api.graphql"
end
# Schema file: priv/graphql/external_api.graphql (explicit, not derived)
# Fetch saves to the explicit path

# Remote schema with authentication
defmodule MyApp.AuthenticatedApi.Schema do
  use GraphqlQuery.Schema,
    remote: [url: "https://api.example.com/schema.graphql"]

  def build_request(req) do
    Req.Request.put_header(req, "authorization", "Bearer " <> System.get_env("API_TOKEN"))
  end
end

# The schema will be automatically loaded from the file
MyApp.Schema.schema()
#=> %GraphqlQuery.Document{type: :schema, query: "type Query { user(id: ID!): User } ..."

# For Absinthe, the schema is extracted at compile time
MyApp.AbsintheSchema.schema()
#=> %GraphqlQuery.Document{type: :schema, query: "type Query { user(id: ID!): User } ..."

# Get the file path
MyApp.Schema.schema_path()
#=> "priv/schema.graphql"