Skip to main content
Version: v14.0.0

requestSubscription

requestSubscription​

Imperative API for establishing a GraphQL Subscription. See also the useSubscription API and the Guide to Updating Data.

import {graphql, requestSubscription} from 'react-relay';

const subscription = graphql`
  subscription UserDataSubscription($input: InputData!) {
    # ...
  }
`;

function createSubscription(environment: IEnvironment): Disposable {
  return requestSubscription(environment, {
    subscription,
    variables: {input: {userId: '4'}},
  });
}

Arguments​

  • environment: A Relay Environment
  • config: GraphQLSubscriptionConfig

Type GraphQLSubscriptionConfig<TSubscriptionPayload>​

  • An object with the following fields:
    • cacheConfig: [Optional] CacheConfig
    • subscription: GraphQLTaggedNode. A GraphQL subscription specified using a graphql template literal
    • variables: The variables to pass to the subscription
    • onCompleted: [Optional] () => void. An optional callback that is executed when the subscription is established
    • onError: [Optional] (Error) => {}. An optional callback that is executed when an error occurs
    • onNext: [Optional] (TSubscriptionPayload) => {}. An optional callback that is executed when new data is received
    • updater: [Optional] SelectorStoreUpdater.

Type CacheConfig​

  • An object with the following fields:
    • force: [Optional] A boolean. If true, causes a query to be issued unconditionally, regardless of the state of any configured response cache.
    • poll: [Optional] A number. Causes a query to live-update by polling at the specified interval, in milliseconds. (This value will be passed to setTimeout).
    • liveConfigId: [Optional] A string. Causes a query to live-update by calling GraphQLLiveQuery; it represents a configuration of gateway when doing live query.
    • metadata: [Optional] An object. User-supplied metadata.
    • transactionId: [Optional] A string. A user-supplied value, intended for use as a unique id for a given instance of executing an operation.

Type SelectorStoreUpdater​

  • A function with signature (store: RecordSourceSelectorProxy, data) => void
  • This interface allows you to imperatively write and read data directly to and from the Relay store. This means that you have full control over how to update the store in response to the subscription payload: you can create entirely new records, or update or delete existing ones. The full API for reading and writing to the Relay store is available here.

Flow Type Parameters​

  • TSubscriptionPayload: The type of the payloads vended by the subscription. You should pass the flow type imported from the auto-generated .graphql file corresponding to the subscription, e.g. use UserDataSubscription as the type parameter, from import type {UserDataSubscription} from './__generated__/UserDataSubscription.graphql';

Return Type​

Interface Disposable​

  • An object with the following key:
    • dispose: () => void. Disposes of the resource.

Behavior​

  • Imperatively establish a subscription.
  • See the GraphQL Subscriptions Guide for a more detailed explanation of how to work with subscriptions.
Is this page useful?

Help us make the site even better by answering a few quick questions.