Apollo Elements Apollo Elements Guides API Blog Toggle darkmode

FAST: ApolloQuery

ApolloQuery inherits from ApolloElement and implements the ApolloQueryInterface.

Read the query component guides for examples and tips.

Exports

import { ApolloQuery } from '@apollo-elements/fast/apollo-query';

Properties

client

inherited from ApolloElementInterface
ApolloClient<NormalizedCacheObject> | null

The Apollo Client instance

Defaults to window.__APOLLO_CLIENT__, which is set by default when creating an Apollo Client. That means that in most cases, it's not necessary to explicity set the client property. For more information see Getting Started: Apollo Client.

context

(optional)
inherited from ApolloElementInterface
Record<string, unknown>

Context passed to the link execution chain.

data

inherited from ApolloElementInterface
Data<D> | null

Latest query data.

document

inherited from ApolloElementInterface
DocumentNode | TypedDocumentNode | null

A GraphQL document containing a single query, mutation, or subscription. You can set it as a JavaScript property or by appending a GraphQL script to the element (light DOM).

static

documentType

inherited from ApolloElementInterface
'query'

Hint that this is a query component

error

(optional)
inherited from ApolloElementInterface
Error | ApolloError | null

Latest error

errorPolicy

(optional)
inherited from ApolloElementInterface error-policy
ErrorPolicy

Specifies the Error Policy to be used for this query.

Much like fetchPolicy, errorPolicy allows you to control how GraphQL Errors from the server are sent to your UI code. By default, the error policy treats any GraphQL Errors as network errors and ends the request chain. It doesn't save any data in the cache, and renders your UI with the error property set to an ApolloError. By changing this policy per request, you can adjust how GraphQL Errors are managed by your UI. The possible options for errorPolicy are:

  • none: This is the default policy to match how Apollo Client 1.0 worked. Any GraphQL Errors are treated the same as network errors and any data is ignored from the response.
  • ignore: Ignore allows you to read any data that is returned alongside GraphQL Errors, but doesn't save the errors or report them to your UI.
  • all: Using the all policy is the best way to notify your users of potential issues while still showing as much data as possible from your server. It saves both data and errors so your UI can use them.

errors

(optional)
inherited from ApolloElementInterface
readonly GraphQLError[] | null

Latest errors.

fetchPolicy

(optional)
inherited from ApolloQueryInterface fetch-policy
FetchPolicy

Determines where the client may return a result from. The options are:

  • cache-first (default): return result from cache, fetch from network if cached result is not available.
  • cache-and-network: return result from cache first (if it exists), then return network result once it's available.
  • cache-only: return result from cache if available, fail otherwise.
  • no-cache: return result from network, fail if network call doesn't succeed, don't save to cache
  • network-only: return result from network, fail if network call doesn't succeed, save to cache
  • standby: only for queries that aren't actively watched, but should be available for refetch and updateQueries.

loading

inherited from ApolloElementInterface
boolean

Whether a request is in-flight.

networkStatus

inherited from ApolloQueryInterface
NetworkStatus

networkStatus is useful if you want to display a different loading indicator (or no indicator at all) depending on your network status as it provides a more detailed view into the state of a network request on your component than loading does. networkStatus is an enum with different number values between 1 and 8. These number values each represent a different network state.

  1. loading: The query has never been run before and the request is now pending. A query will still have this network status even if a result was returned from the cache, but a query was dispatched anyway.
  2. setVariables: If a query’s variables change and a network request was fired then the network status will be setVariables until the result of that query comes back. React users will see this when options.variables changes on their queries.
  3. fetchMore: Indicates that fetchMore was called on this query and that the network request created is currently in flight.
  4. refetch: It means that refetch was called on a query and the refetch request is currently in flight.
  5. Unused.
  6. poll: Indicates that a polling query is currently in flight. So for example if you are polling a query every 10 seconds then the network status will switch to poll every 10 seconds whenever a poll request has been sent but not resolved.
  7. ready: No request is in flight for this query, and no errors happened. Everything is OK.
  8. error: No request is in flight for this query, but one or more errors were detected.

If the network status is less then 7 then it is equivalent to loading being true. In fact you could replace all of your loading checks with networkStatus < 7 and you would not see a difference. It is recommended that you use loading, however.

nextFetchPolicy

(optional)
inherited from ApolloQueryInterface next-fetch-policy
FetchPolicy

When someone chooses cache-and-network or network-only as their initial FetchPolicy, they often do not want future cache updates to trigger unconditional network requests, which is what repeatedly applying the cache-and-network or network-only policies would seem to imply. Instead, when the cache reports an update after the initial network request, it may be desirable for subsequent network requests to be triggered only if the cache result is incomplete. The nextFetchPolicy option provides a way to update options.fetchPolicy after the intial network request, without having to set options.

noAutoSubscribe

inherited from ApolloQueryInterface no-auto-subscribe
boolean

When true, the component will not automatically subscribe to new data. Call the subscribe() method to do so.

notifyOnNetworkStatusChange

(optional)
inherited from ApolloQueryInterface
boolean

Whether or not updates to the network status should trigger next on the observer of this query.

observableQuery

(optional)
inherited from ApolloQueryInterface
ObservableQuery<Data<D>, Variables<D, V>>

The ObservableQuery watching this element's query.

options

inherited from ApolloQueryInterface
Partial<WatchQueryOptions<Variables<D, V>, Data<D>>> | null

Set to reobserve the ObservableQuery

partial

(optional)
inherited from ApolloQueryInterface
boolean

If data was read from the cache with missing fields, partial will be true. Otherwise, partial will be falsy.

partialRefetch

(optional)
inherited from ApolloQueryInterface
boolean

If true, perform a query refetch if the query result is marked as being partial, and the returned data is reset to an empty Object by the Apollo Client QueryManager (due to a cache miss). The default value is false for backwards-compatibility's sake, but should be changed to true for most use-cases.

pollInterval

(optional)
inherited from ApolloQueryInterface
number

The time interval (in milliseconds) on which this query should be refetched from the server.

query

inherited from ApolloQueryInterface
DocumentNode | TypedDocumentNode

A GraphQL document containing a single query. You can set it as a JavaScript property or by appending a GraphQL script to the element (light DOM).

<script type="application/graphql">
  query { helloWorld }
</script>

returnPartialData

(optional)
inherited from ApolloQueryInterface
boolean

Opt into receiving partial results from the cache for queries that are not fully satisfied by the cache.

variables

inherited from ApolloElementInterface
Variables<D, V> | null

Query variables

An object that maps from the name of a variable as used in the operation's GraphQL document to that variable's value. If the element has not yet subscribed and noAutoSubscribe is not set, setting variables causes the element to subscribe, otherwise, setting variables causes the query to refetch.

Methods

protected

documentChanged

(optional)
inherited from ApolloElementInterface

Lifecycle callback that reacts to changes in the GraphQL document.

Parameters

document

DocumentNode | TypedDocumentNode | null

The GraphQL document.

Returns

void
async

executeQuery

inherited from ApolloQueryInterface

Executes a Query once and updates the component with the result

Parameters

params

Partial<QueryOptions<Variables<D, V>>>

Options for the operation. All values default to their respective element instance property values.

Option Type Description
query
DocumentNode | TypedDocumentNode
A GraphQL document that consists of a single query to be sent down to the server.
variables
Variables<D, V> 
A map going from variable name to variable value, where the variables are used within the GraphQL query.
fetchPolicy
FetchPolicy
Specifies the fetchPolicy to be used for this query.
errorPolicy
ErrorPolicy
Specifies the ErrorPolicy to be used for this query.
context
Record<string, unknown>
Context object passed through the link execution chain.

Returns

Promise<ApolloQueryResult<Data<D>> | void>

Result of the query operation

Property Type Description
data
Data<D>
If the query resolved, the data.
error
ApolloError
If the query rejected, the error.
errors
readonly GraphQLError[]
If the query returned partials results, and some were errors, the list of errors.
loading
boolean
Whether the operation is in-flight.
partial
boolean
Whether the query returned partial data.
networkStatus
NetworkStatus
See NetworkStatus.
async

fetchMore

inherited from ApolloQueryInterface

Exposes the ObservableQuery#fetchMore method.

The optional updateQuery parameter is a function that takes the previous query data, then an object with a subscriptionData property that is a SubscriptionResult, and returns an object with updated query data based on the new results.

The variables parameter is an optional new variables object.

Parameters

params

Partial<FetchMoreParams<D, V>>
Option Type Description
query
DocumentNode | TypedDocumentNode
Query to fetch, defaults to this.query
updateQuery
Function
Function to determine how to update the cache when the query resolves. (deprecated - use field policies instead)
variables
Variables<D, V> 
Query variables
context
Record<string, unknown>
Context object passed through the link execution chain.

Returns

Promise<ApolloQueryResult<Data<D>>>

Result of the query operation

Property Type Description
data
Data<D>
If the query resolved, the data.
error
ApolloError
If the query rejected, the error.
errors
readonly GraphQLError[]
If the query returned partials results, and some were errors, the list of errors.
loading
boolean
Whether the operation is in-flight.
partial
boolean
Whether the query returned partial data.
networkStatus
NetworkStatus
See NetworkStatus.

onData

(optional)
inherited from ApolloQueryInterface

Callback for when a query is completed.

Parameters

result

ApolloQueryResult<Data<D>>

Result of the query operation

Property Type Description
data
Data<D>
If the query resolved, the data.
error
ApolloError
If the query rejected, the error.
errors
readonly GraphQLError[]
If the query returned partials results, and some were errors, the list of errors.
loading
boolean
Whether the operation is in-flight.
partial
boolean
Whether the query returned partial data.
networkStatus
NetworkStatus
See NetworkStatus.

Returns

void

onError

(optional)
inherited from ApolloQueryInterface

Callback for when an error occurs.

Parameters

error

Error

Returns

void
async

refetch

inherited from ApolloQueryInterface

Update the variables of this observable query, and fetch the new results.

Parameters

variables

Variables<D, V>

Partial new set of variables. If there are missing variables, the previous values of those variables will be used.

Returns

Promise<ApolloQueryResult<Data<D>>>

Result of the query operation

Property Type Description
data
Data<D>
If the query resolved, the data.
error
ApolloError
If the query rejected, the error.
errors
readonly GraphQLError[]
If the query returned partials results, and some were errors, the list of errors.
loading
boolean
Whether the operation is in-flight.
partial
boolean
Whether the query returned partial data.
networkStatus
NetworkStatus
See NetworkStatus.
protected

shouldSubscribe

inherited from ApolloQueryInterface

Determines whether the element should attempt to subscribe i.e. begin querying. Override to prevent subscribing unless your conditions are met.

Parameters

options

Partial<SubscriptionOptions<Variables<D, V>, Data<D>>>
Property Type Description
query
DocumentNode | TypedDocumentNode
See query
variables
Variables<D, V> 
See variables
fetchPolicy
FetchPolicy
See fetchPolicy
errorPolicy
ErrorPolicy
See errorPolicy
context
Record<string, unknown>
Context object passed through the link execution chain.

Returns

boolean

subscribe

inherited from ApolloQueryInterface

Resets the observableQuery and subscribes.

Parameters

params

Partial<SubscriptionOptions<Variables<D, V>, Data<D>>>

Options to control how the component subscribes to its ObservableQuery

Property Type Description
query
DocumentNode | TypedDocumentNode
See query
variables
Variables<D, V> 
See variables
fetchPolicy
FetchPolicy
See fetchPolicy
errorPolicy
ErrorPolicy
See errorPolicy
context
Record<string, unknown>
Context object passed through the link execution chain.

Returns

ZenObservable.Subscription

subscribeToMore

inherited from ApolloQueryInterface

Lets you pass a GraphQL subscription and updateQuery function to subscribe to more updates for your query. The updateQuery parameter is a function that takes the previous query data, then an object with a subscriptionData property that is a SubscriptionResult, and returns an object with updated query data based on the new results.

Parameters

options

SubscribeToMoreOptions<Data<D>, Variables<D, V>>

Returns

(() => void) | void

function which unsubscribes from the subscription

protected

variablesChanged

(optional)
inherited from ApolloElementInterface

Lifecycle callback that reacts to changes in the operation variables.

Parameters

variables

Variables<D, V> | null

The variables.

Returns

void

watchQuery

inherited from ApolloQueryInterface

Creates an instance of ObservableQuery with the options provided by the element.

  • context Context to be passed to link execution chain
  • errorPolicy Specifies the ErrorPolicy to be used for this query
  • fetchPolicy Specifies the FetchPolicy to be used for this query
  • fetchResults Whether or not to fetch results
  • metadata Arbitrary metadata stored in the store with this query. Designed for debugging, developer tools, etc.
  • notifyOnNetworkStatusChange Whether or not updates to the network status should trigger next on the observer of this query
  • pollInterval The time interval (in milliseconds) on which this query should be refetched from the server.
  • query A GraphQL document that consists of a single query to be sent down to the server.
  • variables A map going from variable name to variable value, where the variables are used within the GraphQL query.

Parameters

options

Partial<WatchQueryOptions<Variables<D, V>, Data<D>>>

Returns

ObservableQuery<Data<D>, Variables<D, V>>

Events

Name Type Description
apollo-element-connected
CustomEvent<ApolloElement>

when the element connects to the DOM

apollo-element-disconnected
CustomEvent<ApolloElement>

when the element disconnects from the DOM

apollo-error
CustomEvent<ApolloError>

when the query rejects

apollo-query-result
CustomEvent<ApolloQueryResult<Data<D>>>

when the query resolves