Class Mixins: ApolloQueryMixin
ApolloQueryMixin
applies ApolloElementMixin
and the ApolloQueryInterface
.
Read the query component guides for examples and tips.
Exports
import { ApolloQueryMixin } from '@apollo-elements/mixins/apollo-query-mixin';
Signature
ApolloQueryMixin
Parameters
superclass
Constructor<CustomElement>
Returns
Constructor<ApolloQuery>
Properties
client
inherited from ApolloElementInterfaceApolloClient<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 ApolloElementInterfaceRecord<string, unknown>
Context passed to the link execution chain.
data
inherited from ApolloElementInterfaceData<D> | null
Latest query data.
document
inherited from ApolloElementInterfaceDocumentNode | 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).
documentType
inherited from ApolloElementInterface'query'
Hint that this is a query component
error
(optional) inherited from ApolloElementInterfaceError | ApolloError | null
Latest error
errorPolicy
(optional) inherited from ApolloElementInterface error-policyErrorPolicy
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 ApolloElementInterfacereadonly GraphQLError[] | null
Latest errors.
fetchPolicy
(optional) inherited from ApolloQueryInterface fetch-policyFetchPolicy
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 cachenetwork-only
: return result from network, fail if network call doesn't succeed, save to cachestandby
: only for queries that aren't actively watched, but should be available for refetch and updateQueries.
loading
inherited from ApolloElementInterfaceboolean
Whether a request is in-flight.
networkStatus
inherited from ApolloQueryInterfaceNetworkStatus
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.
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.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.fetchMore
: Indicates that fetchMore was called on this query and that the network request created is currently in flight.refetch
: It means that refetch was called on a query and the refetch request is currently in flight.- Unused.
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.ready
: No request is in flight for this query, and no errors happened. Everything is OK.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-policyFetchPolicy
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-subscribeboolean
When true, the component will not automatically subscribe to new data. Call the subscribe()
method to do so.
notifyOnNetworkStatusChange
(optional) inherited from ApolloQueryInterfaceboolean
Whether or not updates to the network status should trigger next on the observer of this query.
observableQuery
(optional) inherited from ApolloQueryInterfaceObservableQuery<Data<D>, Variables<D, V>>
The ObservableQuery
watching this element's query.
options
inherited from ApolloQueryInterfacePartial<WatchQueryOptions<Variables<D, V>, Data<D>>> | null
Set to reobserve the ObservableQuery
partial
(optional) inherited from ApolloQueryInterfaceboolean
If data was read from the cache with missing fields, partial will be true. Otherwise, partial will be falsy.
partialRefetch
(optional) inherited from ApolloQueryInterfaceboolean
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 ApolloQueryInterfacenumber
The time interval (in milliseconds) on which this query should be refetched from the server.
query
inherited from ApolloQueryInterfaceDocumentNode | 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 ApolloQueryInterfaceboolean
Opt into receiving partial results from the cache for queries that are not fully satisfied by the cache.
variables
inherited from ApolloElementInterfaceVariables<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
documentChanged
(optional) inherited from ApolloElementInterfaceLifecycle callback that reacts to changes in the GraphQL document.
Parameters
document
DocumentNode | TypedDocumentNode | null
The GraphQL document.
Returns
void
executeQuery
inherited from ApolloQueryInterfaceExecutes 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 |
|
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. |
fetchPolicy |
|
Specifies the fetchPolicy to be used for this query. |
errorPolicy |
|
Specifies the ErrorPolicy to be used for this query. |
context |
|
Context object passed through the link execution chain. |
Returns
Promise<ApolloQueryResult<Data<D>> | void>
Result of the query operation
Property | Type | Description |
---|---|---|
data |
|
If the query resolved, the data. |
error |
|
If the query rejected, the error. |
errors |
|
If the query returned partials results, and some were errors, the list of errors. |
loading |
|
Whether the operation is in-flight. |
partial |
|
Whether the query returned partial data. |
networkStatus |
|
See NetworkStatus. |
fetchMore
inherited from ApolloQueryInterfaceExposes 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 |
|
Query to fetch, defaults to this.query |
updateQuery |
|
Function to determine how to update the cache when the query resolves. (deprecated - use field policies instead) |
variables |
|
Query variables |
context |
|
Context object passed through the link execution chain. |
Returns
Promise<ApolloQueryResult<Data<D>>>
Result of the query operation
Property | Type | Description |
---|---|---|
data |
|
If the query resolved, the data. |
error |
|
If the query rejected, the error. |
errors |
|
If the query returned partials results, and some were errors, the list of errors. |
loading |
|
Whether the operation is in-flight. |
partial |
|
Whether the query returned partial data. |
networkStatus |
|
See NetworkStatus. |
onData
(optional) inherited from ApolloQueryInterfaceCallback for when a query is completed.
Parameters
result
ApolloQueryResult<Data<D>>
Result of the query operation
Property | Type | Description |
---|---|---|
data |
|
If the query resolved, the data. |
error |
|
If the query rejected, the error. |
errors |
|
If the query returned partials results, and some were errors, the list of errors. |
loading |
|
Whether the operation is in-flight. |
partial |
|
Whether the query returned partial data. |
networkStatus |
|
See NetworkStatus. |
Returns
void
onError
(optional) inherited from ApolloQueryInterfaceCallback for when an error occurs.
Parameters
error
Error
Returns
void
refetch
inherited from ApolloQueryInterfaceUpdate 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 |
|
If the query resolved, the data. |
error |
|
If the query rejected, the error. |
errors |
|
If the query returned partials results, and some were errors, the list of errors. |
loading |
|
Whether the operation is in-flight. |
partial |
|
Whether the query returned partial data. |
networkStatus |
|
See NetworkStatus. |
shouldSubscribe
inherited from ApolloQueryInterfaceDetermines 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 |
|
See query |
variables |
|
See variables |
fetchPolicy |
|
See fetchPolicy |
errorPolicy |
|
See errorPolicy |
context |
|
Context object passed through the link execution chain. |
Returns
boolean
subscribe
inherited from ApolloQueryInterfaceResets 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 |
|
See query |
variables |
|
See variables |
fetchPolicy |
|
See fetchPolicy |
errorPolicy |
|
See errorPolicy |
context |
|
Context object passed through the link execution chain. |
Returns
ZenObservable.Subscription
subscribeToMore
inherited from ApolloQueryInterfaceLets 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
variablesChanged
(optional) inherited from ApolloElementInterfaceLifecycle callback that reacts to changes in the operation variables.
Parameters
variables
Variables<D, V> | null
The variables.
Returns
void
watchQuery
inherited from ApolloQueryInterfaceCreates an instance of ObservableQuery with the options provided by the element.
context
Context to be passed to link execution chainerrorPolicy
Specifies the ErrorPolicy to be used for this queryfetchPolicy
Specifies the FetchPolicy to be used for this queryfetchResults
Whether or not to fetch resultsmetadata
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 querypollInterval
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 |
|
when the element connects to the DOM |
apollo-element-disconnected |
|
when the element disconnects from the DOM |
apollo-error |
|
when the query rejects |
apollo-query-result |
|
when the query resolves |