View Source Absinthe.Subscription (absinthe v1.7.9)

Real time updates via GraphQL

For a how to guide on getting started with Absinthe.Subscriptions in your phoenix project see the Absinthe.Phoenix package.

Define in your schema via Absinthe.Schema.subscription/2

Basic Usage

Performance Characteristics

There are a couple of limitations to the beta release of subscriptions that are worth keeping in mind if you want to use this in production:

By design, all subscription docs triggered by a mutation are run inside the mutation process as a form of back pressure.

At the moment however database batching does not happen across the set of subscription docs. Thus if you have a lot of subscription docs and they each do a lot of extra DB lookups you're going to delay incoming mutation responses by however long it takes to do all that work.

Before the final version of 1.4.0 we want

  • Batching across subscriptions
  • More user control over back pressure / async balance.

Summary

Types

opt()
subscription_field_spec()

Functions

child_spec(pubsub)

Build a child specification for subscriptions.

publish(pubsub, mutation_result, info)

Publish a mutation

start_link(opts_or_pubsub)

Add Absinthe.Subscription to your process tree.

Types

opt()

@type opt() ::
  {:pubsub, atom()}
  | {:compress_registry?, boolean()}
  | {:pool_size, pos_integer()}

subscription_field_spec()

@type subscription_field_spec() :: {atom(), term() | (term() -> term())}

Functions

child_spec(pubsub)

@spec child_spec(atom() | [opt()]) :: Supervisor.child_spec()

Build a child specification for subscriptions.

In order to use subscriptions in your application, you must add Absinthe.Subscription to your supervision tree after your endpoint.

See guides/subscriptions.md for more information on how to get up and running with subscriptions.

Options

  • :pubsub - (Required) The Phoenix.Pubsub that should be used to publish subscriptions. Typically this will be your Phoenix.Endpoint.
  • :compress_registry? - (Optional - default true) A boolean controlling whether the Registry used to keep track of subscriptions will should be compressed or not.
  • :pool_size - (Optional - default System.schedulers() * 2) An integer specifying the number of Absinthe.Subscription.Proxy processes to start. You may want to specify a fixed :pool_size if your deployment environment does not guarantee an equal number of CPU cores to be available on all application nodes. In such case, using the defaults may lead to missing messages. This situation often happens on cloud-based deployment environments.

publish(pubsub, mutation_result, info)

@spec publish(
  Absinthe.Subscription.Pubsub.t(),
  term(),
  Absinthe.Resolution.t() | [subscription_field_spec()]
) :: :ok

Publish a mutation

This function is generally used when trying to publish to one or more subscription fields "out of band" from any particular mutation.

Examples

Note: As with all subscription examples if you're using Absinthe.Phoenix pubsub will be MyAppWeb.Endpoint.

Absinthe.Subscription.publish(pubsub, user, [new_users: user.account_id])
# publish to two subscription fields
Absinthe.Subscription.publish(pubsub, user, [
  new_users: user.account_id,
  other_user_subscription_field: user.id,
])

start_link(opts_or_pubsub)

@spec start_link(atom() | [opt()]) :: Supervisor.on_start()

Add Absinthe.Subscription to your process tree.