lighthouse-graphql 0.5.0 → 0.7.0

data/docs/filtering-and-ordering.md

@@ -37,12 +37,14 @@ Override it with `key:` — above, `minAge` filters the `age` column.
 
 ### `@where` operators
 
-`@where(operator: "...")` supports the same operator vocabulary as
-`@whereConditions`:
+`@where(operator: "...")` takes these operators:
 
 `EQ`, `NEQ`, `GT`, `GTE`, `LT`, `LTE`, `IN`, `NIN`, `CONTAINS`, `STARTS_WITH`,
 `ENDS_WITH`, `IS_NULL`, `IS_NOT_NULL`.
 
+They are not `@whereConditions`' `SQLOperator` values, which follow PHP
+Lighthouse (see below).
+
 ```graphql
 type Query {
   events(
@@ -52,38 +54,192 @@ type Query {
 }
 ```
 
-## Ordering — `@orderBy`
+## Ordering
+
+`@orderBy` works as in PHP Lighthouse. On an argument, the client picks the
+order. On a field, the order is fixed.
+
+### Client-controlled ordering
+
+Write the argument's type as `_`. Lighthouse then generates an input that
+takes the allowed columns as an enum, together with the `SortOrder` enum:
+
+```graphql
+type Query {
+  posts(orderBy: _ @orderBy(columns: ["posted_at", "title"])): [Post!]! @all
+}
+```
+
+Lighthouse generates this from it:
+
+```graphql
+"Order by clause for Query.posts.orderBy."
+input QueryPostsOrderByOrderByClause {
+  "The column that is used for ordering."
+  column: QueryPostsOrderByColumn!
+
+  "The direction that is used for ordering."
+  order: SortOrder!
+}
+
+"Allowed column names for Query.posts.orderBy."
+enum QueryPostsOrderByColumn {
+  POSTED_AT @enum(value: "posted_at")
+  TITLE @enum(value: "title")
+}
+
+"Directions for ordering a list of records."
+enum SortOrder {
+  ASC
+  DESC
+}
+```
+
+The argument becomes `orderBy: [QueryPostsOrderByOrderByClause!]`. The client
+passes a list of clauses, which apply in turn:
+
+```graphql
+{
+  posts(orderBy: [{ column: POSTED_AT, order: DESC }, { column: TITLE, order: ASC }]) {
+    title
+  }
+}
+```
+
+The names follow `<Type><Field><Argument>`: `QueryPostsOrderBy…` for
+`Query.posts(orderBy:)`. Each clause needs an `order`. Without `columns:`,
+`columnsEnum:` or `relations:`, the argument takes the shared `OrderByClause`,
+whose `column` is a `String!`. That allows any column, so restrict the columns
+whenever clients are not trusted.
 
-Sort the result by one or more columns. The client passes a list of clauses, each
-with a `column` and an `order` (`ASC`/`DESC`); clauses apply in order.
+To reuse one enum on several fields, name it with `columnsEnum:`. Its
+`@enum(value:)` gives each value's column:
 
 ```graphql
 type Query {
-  users(orderBy: [OrderByClause!] @orderBy): [User!]! @all
+  allPosts(orderBy: _ @orderBy(columnsEnum: "PostColumn")): [Post!]! @all
+  paginatedPosts(orderBy: _ @orderBy(columnsEnum: "PostColumn")): [Post!]! @paginate
+}
 
-  # query:
-  # users(orderBy: [{ column: NAME, order: ASC }, { column: CREATED_AT, order: DESC }])
+enum PostColumn {
+  POSTED_AT @enum(value: "posted_at")
+  TITLE @enum(value: "title")
 }
 ```
 
-`@orderBy` also accepts `{ field:, direction: }` clause shapes, so it slots into
-existing client conventions.
+`columns:` and `columnsEnum:` cannot be used together.
+
+### Ordering by a relation
+
+`relations:` lets the client order by an aggregate of a relation. Without
+columns, that aggregate is `COUNT`. With a relation's own `columns:` (or
+`columnsEnum:`), it is `AVG`, `MIN`, `MAX`, `SUM` or `COUNT` of one of them:
+
+```graphql
+type Query {
+  users(
+    orderBy: _ @orderBy(columns: ["name"], relations: [{ relation: "posts" }, { relation: "tasks", columns: ["difficulty"] }])
+  ): [User!]! @all
+}
+```
+
+```graphql
+{
+  users(
+    orderBy: [
+      { posts: { aggregate: COUNT }, order: DESC }
+      { tasks: { aggregate: MAX, column: DIFFICULTY }, order: DESC }
+      { column: NAME, order: ASC }
+    ]
+  ) {
+    name
+  }
+}
+```
+
+The argument then takes `[QueryUsersOrderByRelationOrderByClause!]`. Each clause
+names exactly one of `column` and the relations. Each relation has an input of
+its own, `QueryUsersOrderByPosts` / `QueryUsersOrderByTasks`, with the
+`OrderByRelationAggregateFunction` or
+`OrderByRelationWithColumnAggregateFunction` enum.
+
+The aggregate is computed once per record, in a `LEFT JOIN` on a grouped
+subquery. A record with no related records is still listed, with a `COUNT` of 0.
+This also works on a relationship field (`posts(orderBy: _ @orderBy(...)): [Post!]! @hasMany`),
+including when its pages are batched.
+
+### Predefined ordering
+
+On a field, `@orderBy(column:, direction:)` always orders the result, whatever
+the client sends:
+
+```graphql
+type Query {
+  latestUsers: [User!]! @all @orderBy(column: "created_at", direction: DESC)
+}
+```
+
+A field's `@orderBy` applies after the client's `orderBy` argument, so on a
+field with both, it breaks ties:
+
+```graphql
+type Query {
+  posts(orderBy: _ @orderBy(columns: ["title"])): [Post!]! @paginate @orderBy(column: "created_at", direction: DESC)
+}
+```
+
+An argument written with a type of its own, such as `orderBy: [MyClause!] @orderBy`,
+keeps that type. Its input needs a `column` and an `order`.
 
 ## Complex where conditions
 
-For a flexible, client-controlled `WHERE` builder, use `@whereConditions`.
-Lighthouse generates the input and column-enum types automatically — you only
-declare the allowed columns.
+`@whereConditions` works as in PHP Lighthouse. The client builds the `WHERE`
+clause itself, from conditions joined by `AND` and `OR`, and from `HAS` checks on
+relations. Write the argument's type as `_`, and declare the allowed columns:
 
 ```graphql
 type Query {
   people(
-    where: _ @whereConditions(columns: ["age", "type", "height"])
+    where: _ @whereConditions(columns: ["age", "type", "haircolour", "height"])
   ): [Person!]! @all
 }
 ```
 
-Clients can then build dynamic conditions with `AND` / `OR` / operators:
+Lighthouse generates these types for `Query.people(where:)`:
+
+```graphql
+"Dynamic WHERE conditions for the `where` argument of Query.people."
+input QueryPeopleWhereWhereConditions {
+  column: QueryPeopleWhereColumn
+  operator: SQLOperator = EQ
+  value: Mixed
+  AND: [QueryPeopleWhereWhereConditions!]
+  OR: [QueryPeopleWhereWhereConditions!]
+  HAS: QueryPeopleWhereWhereConditionsRelation
+}
+
+"Allowed column names for Query.people.where."
+enum QueryPeopleWhereColumn {
+  AGE @enum(value: "age")
+  TYPE @enum(value: "type")
+  HAIRCOLOUR @enum(value: "haircolour")
+  HEIGHT @enum(value: "height")
+}
+
+input QueryPeopleWhereWhereConditionsRelation {
+  relation: String!
+  operator: SQLOperator = GTE
+  amount: Int = 1
+  condition: QueryPeopleWhereWhereConditionsHasCondition
+}
+```
+
+`QueryPeopleWhereWhereConditionsHasCondition` has the same fields as the
+conditions input, but its `column` is a `String`. It filters the related
+records, whose columns are not the model's.
+
+The conditions of one level all hold. An `AND` list is a group whose conditions
+all hold, and an `OR` list is a group where at least one does:
 
 ```graphql
 {
@@ -91,38 +247,182 @@ Clients can then build dynamic conditions with `AND` / `OR` / operators:
     where: {
       AND: [
         { column: AGE, operator: GT, value: 37 }
-        { OR: [
-            { column: TYPE, value: "Actor" }
+        { column: TYPE, value: "Actor" }
+        {
+          OR: [
+            { column: HAIRCOLOUR, value: "red" }
             { column: HEIGHT, operator: GTE, value: 150 }
-        ] }
+          ]
+        }
+      ]
+    }
+  ) {
+    name
+  }
+}
+```
+
+```graphql
+{
+  people(
+    where: {
+      AND: [
+        { column: HAIRCOLOUR, operator: IS_NULL }
+        { column: HEIGHT, operator: BETWEEN, value: [150, 200] }
       ]
     }
-  ) { name }
+  ) {
+    name
+  }
 }
 ```
 
-The generated `SQLOperator` enum covers `EQ`, `NEQ`, `GT`, `GTE`, `LT`, `LTE`,
-`IN`, `NIN`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `IS_NULL`, `IS_NOT_NULL`.
+`where: null` filters nothing.
+
+### Operators
 
-### `@whereHasConditions`
+The generated `SQLOperator` enum has PHP Lighthouse's operators. `IS_NULL` and
+`IS_NOT_NULL` take no value. Any other operator needs one, or the query fails
+with "Did not receive a value to match the WhereConditions for column …".
 
-Filter by the existence of a related record, with conditions applied to the
-relation:
+| Operator | SQL | `value` |
+| --- | --- | --- |
+| `EQ` (default) | `=` | a scalar |
+| `NEQ` | `!=` | a scalar |
+| `GT`, `GTE`, `LT`, `LTE` | `>`, `>=`, `<`, `<=` | a scalar |
+| `LIKE`, `NOT_LIKE` | `LIKE`, `NOT LIKE` | a pattern: `"%Rails%"` |
+| `IN`, `NOT_IN` | `IN`, `NOT IN` | a list |
+| `BETWEEN`, `NOT_BETWEEN` | `BETWEEN`, `NOT BETWEEN` | `[from, to]` |
+| `IS_NULL`, `IS_NOT_NULL` | `IS NULL`, `IS NOT NULL` | none |
+
+### Related records — `HAS`
+
+`HAS` keeps the records that have related records. By default, at least one,
+which is `operator: GTE, amount: 1`. Its `condition` filters the related
+records, on their own table's columns:
+
+```graphql
+{
+  users(where: { HAS: { relation: "posts", amount: 3, condition: { column: "published", value: true } } }) {
+    name
+  }
+}
+```
+
+`relation` names an association of the model (`posts`, or `blogPosts` for
+`blog_posts`). `{ relation: "posts", operator: LT, amount: 1 }` keeps the users
+with no posts. A `condition` can hold its own `HAS`, which checks the related
+records' relations.
+
+### Without `columns:`
+
+Without `columns:` or `columnsEnum:`, the argument takes the shared
+`WhereConditions` input, whose `column` is a `String`. A column a client
+names there must be an identifier or `table.column`, optionally followed by a
+[JSON path](#json-columns) (`meta->tags`). Anything else fails with "Column names
+may contain only alphanumerics or underscores, optionally a table and a JSON path
+(posts.meta->tags), and may not begin with a digit, got: …". Any column of the
+table can still be filtered on, so declare the allowed columns when clients are
+not trusted.
+
+### JSON columns
+
+As in PHP Lighthouse (and Laravel), a column can point into a JSON document with
+`->`: `meta->series`, `meta->author->name`, and `meta->tags->0` for an array
+element. `@whereConditions`, `@whereHasConditions` and `@orderBy`, on an argument
+or on a field, take it in `columns:` like any column:
 
 ```graphql
 type Query {
-  users(
-    hasPosts: _ @whereHasConditions(columns: ["status"])
-  ): [User!]! @all
+  posts(
+    where: _ @whereConditions(columns: ["title", "meta->series", "meta->rank"])
+    orderBy: _ @orderBy(columns: ["meta->rank"])
+  ): [Post!]! @all
+  rankedPosts: [Post!]! @all @orderBy(column: "meta->rank", direction: DESC)
+}
+```
+
+The generated enum names the path with `__` (`META__SERIES`, `META__AUTHOR__NAME`):
+
+```graphql
+{
+  posts(
+    where: { AND: [{ column: META__SERIES, value: "graphql" }, { column: META__RANK, operator: GT, value: 9 }] }
+    orderBy: [{ column: META__RANK, order: DESC }]
+  ) {
+    title
+  }
+}
+```
+
+The value at the path is compiled for the database: `"meta"->>'series'` on
+PostgreSQL, `JSON_UNQUOTE(JSON_EXTRACT(meta, '$."series"'))` on MySQL, and
+`json_extract(meta, '$."series"')` on SQLite. Unlike Laravel, it behaves the same
+on all three:
+
+- A number compares as a number (`meta->rank GT 9` keeps 10), and a boolean as a
+  boolean. `LIKE` compares the text.
+- `IS_NULL` holds for a missing key and for a JSON `null`.
+- `@orderBy` orders by the JSON value, so numbers sort numerically.
+
+### A custom handler
+
+`handler:` names a class, looked up in `Config.namespaces[:builders]` (`Builders::`).
+It applies the conditions instead of Lighthouse:
+
+```graphql
+type Query {
+  people(where: _ @whereConditions(columns: ["age"], handler: "PeopleConditions")): [Person!]! @all
 }
 ```
 
-The relation is inferred from the `has<Relation>` argument name (`hasPosts` →
-`posts`), or specified with `relation:`.
+```ruby
+class Builders::PeopleConditions
+  # `conditions` as the client sent them: { column: "age", operator: "GT", value: 37, and: [...], ... }
+  def self.call(relation, conditions)
+    relation.where(...)
+  end
+end
+```
+
+Use `"Class@method"` to call another method.
+
+## `@whereHasConditions`
+
+`@whereHasConditions` keeps the records that have at least one related record
+matching the client's conditions. The input is the same as `@whereConditions`',
+applied to the relation:
+
+```graphql
+type Query {
+  people(hasRole: _ @whereHasConditions(columns: ["name", "access_level"])): [Person!]! @all
+}
+```
+
+```graphql
+{
+  people(hasRole: { column: ACCESS_LEVEL, operator: GTE, value: 5 }) {
+    name
+  }
+}
+```
+
+The relation is the argument's name without `has` (`hasRole` → `role`, and
+`roles` if the model has that instead). You can also name it with `relation:`:
+`work: _ @whereHasConditions(relation: "tasks")`. The generated input is
+`QueryPeopleHasRoleWhereHasConditions`.
+
+`hasRole: {}` keeps the people with any role. `hasRole: null` filters nothing.
+
+The client's conditions are an argument directive like any other, so they also
+work on `@paginate`, `@count`, `@first`, the relationship directives, and
+`resolve_info.enhance_builder`. The argument can have any name.
 
 ## How columns are resolved
 
 Column names from enums (e.g. `CREATED_AT`) and arguments (`minAge`) are mapped to
 real columns through one central rule (`Lighthouse::Support::Naming`): ALLCAPS
 enum keys are downcased, and camelCase is converted to snake_case. This keeps
-client-facing GraphQL idiomatic while matching your Rails schema.
+client-facing GraphQL idiomatic while matching your Rails schema. An enum
+value's `@enum(value:)` names its column directly, as in the enums `@orderBy`
+and `@whereConditions` generate.

data/docs/generators.md

@@ -2,51 +2,51 @@
 
 Lighthouse builds on graphql-ruby, and so do its generators: it writes only what
 graphql-ruby has no generator for, or what an SDL-first schema needs differently.
-Every graphql-ruby app's base classes (`Types::BaseObject`, `Resolvers::BaseResolver`,
-`Mutations::BaseMutation`, ...) come from graphql-ruby's own `graphql:install`.
+Every graphql-ruby app's schema class and base classes (`Types::BaseObject`,
+`Resolvers::BaseResolver`, `Mutations::BaseMutation`, ...) come from graphql-ruby's
+own `graphql:install`, and `lighthouse:install` builds on them.
 
 ## `lighthouse:install`
 
 ```shell
+bin/rails generate graphql:install     # graphql-ruby's, with the options you choose
 bin/rails generate lighthouse:install
 ```
 
-It runs graphql-ruby's install first
-(`graphql:install --no-relay --skip-graphiql --skip-query-logs`), which writes:
+It works on what graphql-ruby's `graphql:install` wrote, with whichever of its
+options the app chose (`--relay`, the default, `--batch`, `--skip-mutation-root-type`,
+`--schema`, `--directory`, `--api`, ...). When the app has no graphql-ruby schema
+class yet, it runs `graphql:install` first, with graphql-ruby's defaults (and
+`--api` when `config.api_only = true`). Then it adapts what graphql-ruby wrote:
 
-- `app/graphql/types/base_*.rb`: `BaseObject`, `BaseField`, `BaseArgument`,
-  `BaseInterface`, `BaseUnion`, `BaseScalar`, `BaseEnum`, `BaseInputObject`;
-- `app/graphql/resolvers/base_resolver.rb` and `app/graphql/mutations/base_mutation.rb`;
-- its schema class, `Types::QueryType`, `Types::MutationType` and controller, and the
-  `POST /graphql` route.
+| File | What Lighthouse does |
+| --- | --- |
+| `app/graphql/app_schema.rb` | `class AppSchema < GraphQL::Schema` becomes `class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(options: { base_types: { ... } })`, naming every class graphql-ruby wrote. The rest of the class stays, but the `query(...)` / `mutation(...)` lines (the SDL's root types are built on those classes) and the `resolve_type` stub (Lighthouse resolves types). With `--batch`, `use GraphQL::Dataloader` goes beside `use GraphQL::Batch`, as Lighthouse's directives batch through the Dataloader |
+| `app/graphql/types/query_type.rb`, `mutation_type.rb` | The example `test_field` goes. Relay's `node` / `nodes` stay: the SDL's `Query` is built on `Types::QueryType`, so its `field`s are the schema's too |
+| `app/graphql/types/base_object.rb`, `base_interface.rb`, `base_union.rb`, `base_scalar.rb` | `include Lighthouse::GraphQL::Type`: every type class inheriting from them is Lighthouse's, `Types::QueryType` and `Types::NodeType` included |
+| `app/graphql/mutations/base_mutation.rb` | Kept as graphql-ruby wrote it, a `RelayClassicMutation` (see [resolvers.md](resolvers.md#resolution-by-convention)) |
+| `app/controllers/graphql_controller.rb` | Replaced by one including `Lighthouse::GraphQL::Controller` (`lighthouse_schema AppSchema`), when it is still as graphql-ruby wrote it. One the app changed is kept, and the install says how to serve the schema |
 
-Then Lighthouse puts its own on top of what graphql-ruby wrote in that run:
+And it adds Lighthouse's own:
 
-| File | What Lighthouse does |
+| File | What it is |
 | --- | --- |
-| `app/graphql/app_schema.rb` | Replaced by the schema built from the SDL, naming every base class in `base_types` |
-| `app/controllers/graphql_controller.rb` | Replaced by one including `Lighthouse::GraphQL::Controller` |
-| `app/graphql/types/query_type.rb`, `mutation_type.rb` | Removed: the SDL declares the root types |
-| `app/graphql/mutations/base_mutation.rb` | Made a `GraphQL::Schema::Mutation`: the SDL declares a mutation's arguments, where graphql-ruby's `RelayClassicMutation` takes a single `input:` |
-| `app/graphql/subscriptions/base_subscription.rb` | Written: graphql-ruby has no subscription base. It includes `Lighthouse::GraphQL::Subscription` |
-| `config/initializers/lighthouse.rb` | Written: every [configuration](configuration.md) option, commented out |
+| `config/initializers/lighthouse.rb` | Every [configuration](configuration.md) option, commented out |
 | `graphql/schema.graphql` | A starter schema, unless the folder holds `.graphql` files already |
 | `graphql.config.yml` | IDE configuration, and `.gitignore` entries for the [IDE helper](getting-started.md#ide-support) files |
+| `app/graphql/subscriptions/base_subscription.rb` | With `--subscriptions` only: graphql-ruby has no subscription base. It includes `Lighthouse::GraphQL::Subscription` |
+| `config/routes.rb` | `post "/graphql", to: "graphql#execute"`, when missing |
 
 | Option | Effect |
 | --- | --- |
-| `--schema=ApiSchema` | Name of the schema constant (default `AppSchema`) |
-| `--sdl-folder=app/schema` | Where the `.graphql` files live (default `graphql`); sets `config.sdl_folder` |
-| `--skip-controller` | No controller or route (graphql-ruby's are removed too) — for apps that serve GraphQL themselves |
+| `--schema=ApiSchema` | Which graphql-ruby schema class to adopt, and its name when `graphql:install` has to run |
+| `--schema-path=app/schema/schema.graphql` | The schema's entrypoint, which imports the other `.graphql` files (default `graphql/schema.graphql`); sets `config.schema_path` |
+| `--subscriptions` | Write `Subscriptions::BaseSubscription` and name it in `base_types` |
+| `--skip-controller` | Leave graphql-ruby's controller as it is, and add no route — for apps that serve GraphQL themselves |
 | `--skip-ide` | No `graphql.config.yml` or `.gitignore` entries |
-| `--force` | Replace a schema class or controller the app had before |
 
-Rerunning it is safe: a file the app has is kept, and the route and `.gitignore`
-entries are added once. In an app that already had a graphql-ruby schema class or
-controller, those are kept (Lighthouse replaces only what graphql-ruby wrote in the
-same run), and graphql-ruby's install points that schema at the root types it
-wrote: have the controller call `AppSchema.execute(...)` to serve Lighthouse's
-schema, or pass `--force`.
+Rerunning it changes nothing: a schema class that is Lighthouse's already, a file
+the app has, the route and the `.gitignore` entries are left as they are.
 
 ## Lighthouse's generators
 
@@ -56,27 +56,29 @@ schema. Each writes into the first namespace configured for its kind (or
 
 | Generator | Writes |
 | --- | --- |
-| `lighthouse:query LatestPosts` | `Resolvers::LatestPosts < BaseResolver`, which `Query.latestPosts` resolves to by convention |
-| `lighthouse:mutation PublishPost` | `Mutations::PublishPost < BaseMutation`, for `Mutation.publishPost` |
 | `lighthouse:subscription PostUpdated` | `Subscriptions::PostUpdated < BaseSubscription`, with its hooks (and the base, when missing) |
 | `lighthouse:builder Published` | `Builders::Published`, for `@builder(class: "Published")` |
 | `lighthouse:validator CreatePostInput` | `Validators::CreatePostInputValidator`, a `Dry::Validation::Contract` |
 
-The class's arguments and return type are the SDL's, so it declares neither. When
-the base class is missing (an app that never ran an install, or a namespace of its
-own such as `Api::Resolvers`), the generator says so: `lighthouse:install` writes it
-through graphql-ruby, or write `Api::Resolvers::BaseResolver` yourself.
+A subscription's arguments and return type are the SDL's, so the class declares
+neither. When `Subscriptions::BaseSubscription` is missing, `lighthouse:subscription`
+writes it.
+
+A resolver or mutation class has no Lighthouse generator: write a
+`Resolvers::BaseResolver` subclass by hand (see [resolvers.md](resolvers.md)), add a
+method to `Types::QueryType`, or run graphql-ruby's `graphql:mutation`.
 
 ## graphql-ruby's generators in a Lighthouse app
 
 | Generator | In a Lighthouse app |
 | --- | --- |
-| `graphql:install` | Run by `lighthouse:install`. On its own, it writes a code-first schema, root types and a `RelayClassicMutation` base: run `lighthouse:install` instead |
-| `graphql:object Post` | **Use it** for a [type class](resolvers.md#type-classes): add `include Lighthouse::GraphQL::Type`, then methods. The `field` lines it writes (from the model's columns, when there is one) are ignored, as the SDL declares the fields: delete them |
-| `graphql:scalar DateTime` | **Use it** for a [scalar](types.md#scalars): add `include Lighthouse::GraphQL::Type`; its `coerce_input` / `coerce_result` are the ones Lighthouse calls |
-| `graphql:union SearchResult`, `graphql:interface Authored` | **Use them** when the [default resolution](types.md#the-default) is not enough: add `include Lighthouse::GraphQL::Type` and a `resolve_type`. Its `possible_types` and `field` lines are ignored |
+| `graphql:install` | The base `lighthouse:install` builds on: run it first with the options you want, or let `lighthouse:install` run it with its defaults |
+| `graphql:object Post` | **Use it** for a [type class](resolvers.md#type-classes): it inherits from `Types::BaseObject`, so it is Lighthouse's; add methods. The `field` lines it writes (from the model's columns, when there is one) are ignored, as the SDL declares the fields: delete them |
+| `graphql:scalar DateTime` | **Use it** for a [scalar](types.md#scalars): its `coerce_input` / `coerce_result` are the ones Lighthouse calls |
+| `graphql:union SearchResult`, `graphql:interface Authored` | **Use them** when the [default resolution](types.md#the-default) is not enough: add a `resolve_type`. Their `possible_types` and `field` lines are ignored |
 | `graphql:enum`, `graphql:input` | Not needed: the SDL declares enums and inputs ([`@enum`](directives.md#enum) gives a value an internal one) |
-| `graphql:mutation`, `graphql:mutation_create` / `_update` / `_delete` | **Not ready**: they add a field to `Types::MutationType`, which a Lighthouse app has none of (they write it again), and write a `RelayClassicMutation` taking `input:`. Use `lighthouse:mutation`, or [`@create`, `@update`, `@delete`](mutations.md) |
-| `graphql:relay` | Not needed: [`@node`, `@globalId`](relay.md) and `@paginate(type: CONNECTION)` |
+| `graphql:mutation PublishPost` | **Use it** for a code-first mutation: it writes `Mutations::PublishPost` and adds `field :publish_post, mutation: Mutations::PublishPost` to `Types::MutationType`, which the SDL's `Mutation` is built on. The class declares its own arguments and fields, as in graphql-ruby |
+| `graphql:mutation_create` / `_update` / `_delete` | Code-first mutations like `graphql:mutation`'s, whose payload and input are code-first types (`Types::PostType`, `Types::PostInputType`). For a type the SDL declares, use [`@create`, `@update`, `@delete`](mutations.md) |
+| `graphql:relay` | Run by `graphql:install` (`--relay` is its default). On an app installed with `--no-relay`, it adds `Types::NodeType`, `node` / `nodes` and the schema's `id_from_object` / `object_from_id`: add `node: Types::NodeType` to `base_types` by hand. See [relay.md](relay.md#relay-through-graphql-ruby) |
 | `graphql:loader` | A GraphQL::Batch loader, which your own resolver classes may use; Lighthouse's directives batch through graphql-ruby's Dataloader instead |
-| `graphql:detailed_trace` | **Not ready**: it edits a `class AppSchema < GraphQL::Schema`, which Lighthouse's `AppSchema = get_schema(...)` is not. Add its migration and `AppSchema.use(GraphQL::Tracing::DetailedTrace)` by hand |
+| `graphql:detailed_trace` | **Not ready**: it looks for `class AppSchema < GraphQL::Schema`, which a Lighthouse schema class (`< Lighthouse::GraphQL::RbLightHouse.get_schema(...)`) does not match, and stops. Add `use GraphQL::Tracing::DetailedTrace` and `def self.detailed_trace?(query)` to the class body by hand, with graphql-ruby's migration (or `redis:`) |