Skip to content

Add mapping concepts and query pipeline documentation #930

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
phdoerfler wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Add mapping concepts and query pipeline documentation #930

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 16 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,32 +36,41 @@ and [imbus AG](https://www.imbus.de/) over the last five years.
## Getting Started

- See the [tutorial](https://typelevel.org/grackle) and accompanying [demo](https://github.com/typelevel/grackle/tree/main/demo/src/main).
- New to Grackle's mapping model? Start with [Mapping Concepts](https://typelevel.org/grackle/mappings.html) for a guided tour of
`ValueMapping`, `GenericMapping`, `CirceMapping`, `SqlMapping`, `ComposedMapping` and friends,
and how to pick the right one for your data source.
- Online Scaladoc is available [here](https://javadoc.io/doc/org.typelevel/grackle-core_2.13).
- Ask us anything the in **#grackle** channel on the Typelevel [discord server][grackle-dev].

To add Grackle to your project you should add the following to your `build.sbt`,

```scala
// Required: Scala 2.13/3.3+
libraryDependencies += "org.typelevel" %% "grackle-core" % "0.26.0"
libraryDependencies += "org.typelevel" %% "grackle-core" % "0.30.0"

// Optional: support for in-memory Json backend using circe
libraryDependencies += "org.typelevel" %% "grackle-circe" % "0.26.0"
libraryDependencies += "org.typelevel" %% "grackle-circe" % "0.30.0"

// Optional: support for in-memory generic Scala backend using shapeless
libraryDependencies += "org.typelevel" %% "grackle-generic" % "0.26.0"
libraryDependencies += "org.typelevel" %% "grackle-generic" % "0.30.0"

// Optional: support for Postgres backend via Doobie (JVM only)
libraryDependencies += "org.typelevel" %% "grackle-doobie-pg" % "0.26.0"
libraryDependencies += "org.typelevel" %% "grackle-doobie-pg" % "0.30.0"

// Optional: support for Postgres backend via Skunk
libraryDependencies += "org.typelevel" %% "grackle-skunk" % "0.26.0"
libraryDependencies += "org.typelevel" %% "grackle-skunk" % "0.30.0"

// Optional: support for Oracle backend via Doobie (JVM only)
libraryDependencies += "org.typelevel" %% "grackle-doobie-oracle" % "0.26.0"
libraryDependencies += "org.typelevel" %% "grackle-doobie-oracle" % "0.30.0"

// Optional: support for SQL Server backend via Doobie (JVM only)
libraryDependencies += "org.typelevel" %% "grackle-doobie-mssql" % "0.26.0"
libraryDependencies += "org.typelevel" %% "grackle-doobie-mssql" % "0.30.0"

// Optional: support for H2 backend via Doobie (JVM only)
libraryDependencies += "org.typelevel" %% "grackle-doobie-h2" % "0.30.0"

// Optional: support for SQLite backend via Doobie (JVM only)
libraryDependencies += "org.typelevel" %% "grackle-doobie-sqlite" % "0.30.0"

@milessabin milessabin Sep 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MOAR!!!

```

## Running tests for database backed mappings
Expand Down
2 changes: 2 additions & 0 deletions docs/directory.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,7 @@ laika.navigationOrder = [
index.md
tutorial
howto
mappings.md
pipeline.md
CONTRIBUTING.md
]
11 changes: 9 additions & 2 deletions docs/tutorial/compiler-phases.md → docs/howto/compiler-phases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,10 @@ in the `Elab` monad. `Elab` gives phases access to the schema, the current conte
definitions, and allows compilation to be aborted with one or more GraphQL errors via `Elab.failure`. A phase which
fails prevents the query from executing at all — the client receives an error response with no data.

`transform` is not abstract: the inherited implementation walks the whole query algebra, maintaining the `Elab`
context as it descends, so a phase overrides it for the node types it cares about and delegates the rest to
`super.transform`.

This makes phases a natural place to enforce global policies on incoming queries. Grackle provides one such policy
phase out of the box: `QuerySizeValidator`.

Expand All @@ -45,7 +49,7 @@ _Depth_ is the number of nested selection levels in the query, and _width_ is th
selected. Both are computed after fragment spreads have been resolved, so a query cannot evade the limits by
factoring its selections into fragments.

For example, with the Star Wars model from the previous chapter and the limits above, the query,
For example, with the [Star Wars model](../tutorial/in-memory-model.md) and the limits above, the query,

```yaml
query {
Expand Down Expand Up @@ -84,8 +88,11 @@ exceeding both limits at once is reported as `"Query is too complex"`.

## Limitations

Depth and width are syntactic measures: they are computed from the query text alone and know nothing about the size
Depth and width are structural measures: they are computed from the query's shape and know nothing about the size

@milessabin milessabin Sep 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not convinced this is an improvement. The key contrast is between the query text, which is syntax, and data-independent, and the result size, which is data dependent.

of the underlying data. In particular, width does not account for list sizes — a field yielding a thousand elements
contributes to the width just once. `QuerySizeValidator` is therefore a coarse first line of defence rather than a
complete cost model. Guarding against expensive list expansions requires taking field cardinalities and arguments
into account, which can be implemented as a custom phase following the same pattern.

Introspection is not measured at all: an `Introspect` node contributes nothing to either figure, so a deeply

@milessabin milessabin Sep 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not to say that this is inaccurate, but it might actually be a problem 🤔

nested `__schema` query passes whichever limits are configured.
1 change: 1 addition & 0 deletions docs/howto/directory.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
laika.title = How-to Guides
laika.navigationOrder = [
interfaces-across-tables.md
compiler-phases.md
]
9 changes: 9 additions & 0 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@ and [imbus AG](https://www.imbus.de/) over the last five years.
## Getting Started

- See the [tutorial](https://typelevel.org/grackle) and accompanying [demo](https://github.com/typelevel/grackle/tree/main/demo/src/main).
- New to Grackle's mapping model? Start with [Mapping Concepts](https://typelevel.org/grackle/mappings.html) for a guided tour of
`ValueMapping`, `GenericMapping`, `CirceMapping`, `SqlMapping`, `ComposedMapping` and friends,
and how to pick the right one for your data source.
- Online Scaladoc is available [here](https://javadoc.io/doc/org.typelevel/grackle-core_2.13).
- Ask us anything the in **#grackle** channel on the Typelevel [discord server][grackle-dev].

Expand All @@ -56,6 +59,12 @@ libraryDependencies += "org.typelevel" %% "grackle-doobie-oracle" % "@VERSION@"

// Optional: support for SQL Server backend via Doobie (JVM only)
libraryDependencies += "org.typelevel" %% "grackle-doobie-mssql" % "@VERSION@"

// Optional: support for H2 backend via Doobie (JVM only)
libraryDependencies += "org.typelevel" %% "grackle-doobie-h2" % "@VERSION@"

// Optional: support for SQLite backend via Doobie (JVM only)
libraryDependencies += "org.typelevel" %% "grackle-doobie-sqlite" % "@VERSION@"

@milessabin milessabin Sep 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

More to add now 😄

```

## Running tests for database backed mappings
Expand Down
Loading
Loading