How to put a GraphQL API on Materialize?

[ruf-io]

We've seen users asking for recommendations and options for putting a GraphQL API layer in front of Materialize. I'm using this Q&A post to centralize and track the current state of GraphQL on Materialize.

If I wanted to query Materialize via GraphQL, what are my options?

[ruf-io]

There are several approaches to this that each come with trade-offs which I'll attempt to call out so that you can look at your specific requirements and decide on a solution that aligns with your needs.

Option One: Custom Node.js Service

If you're only serving very specific GraphQL queries, it might be ideal to write your own API service in Node that takes full advantage of the streaming TAIL features of Materialize.

📖 Example Reference: The App script in this real-time demo app

👍Pros: Full control over how Materialize is queried. Ability to subscribe to updates to a view and use GraphQL streaming to stream updates to the client.
👎Cons: Doesn't scale well if you need to handle a truly diverse set of queries.

Option Two: Postgraphile (with hacks)

If you're already using Postgraphile, or you don't want to write your own postgraphile is the most popular "graphql on postgres" framework. There is a three-step "hack" to make Materialize work with Postgraphile:

1. Take the views you want to query in Materialize and replicate their schema in standard Postgres, connect Postgraphile to that standard Postgres instance and export the postgraphile schema to a file.
2. When initializing Postgraphile on Materialize, use the --schema argument to supply the exported file from step 1 above so that Postgraphile doesn't attempt to introspect Materialize (it will fail on a pg_catalog endpoint that is not yet implemented.)
3. Lastly, you need to override three json functions with their jsonb equivalent in a dependency of GraphQL:

   find postgraphile/node_modules/graphile-build-pg/node8plus/ -type f -name "*.js*" -exec sed -i'' -e 's/to_json/to_jsonb/g' {} +
   find postgraphile/node_modules/graphile-build-pg/node8plus/ -type f -name "*.js*" -exec sed -i'' -e 's/json_agg/jsonb_agg/g' {} +
   find postgraphile/node_modules/graphile-build-pg/node8plus/ -type f -name "*.js*" -exec sed -i'' -e 's/json_build_object/jsonb_build_object/g' {} +

👍Pros: Ideal if you're already running Postgraphile. Postgraphile provides a rich set of GraphQL features and integrations
👎Cons: It's a hack. Can't handle TAIL queries AFAIK

Option Three: Cube.js GraphQL API

Cube.js is a "headless BI" service that provides, among other things, a GraphQL API to schemas you define on top of Materialize.

📖 Example Reference: The Demo in Cube.js repo

👍Pros: Comes with additional features like authentication. Also works via Cube Cloud
👎Cons: Might add more complexity than you need by requiring you also define JS schemas for your materialized views. Can't handle TAIL queries AFAIK