Interfaces: ApolloQuery
Apollo Query elements read data from the Apollo cache. Regardless of which library you use to build them, they share a common interface, e.g. a query component built with lit-apollo
has the same basic API as one built using hybrids
.
Query components inherit the ApolloElementInterface.
Exports
import { ApolloQueryInterface } from '@apollo-elements/interfaces/apollo-query';
Properties
errorPolicy
ErrorPolicy
Specifies the ErrorPolicy
to be used for this query.
fetchPolicy
(optional)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 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.
networkStatus
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.
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)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
no-auto-subscribeboolean
When true, the component will not automatically subscribe to new data. Call the subscribe()
method to do so.
notifyOnNetworkStatusChange
(optional)boolean
Whether or not updates to the network status should trigger next on the observer of this query.
observableQuery
(optional)ObservableQuery<Data<D>, Variables<D, V>>
The ObservableQuery
watching this element's query.
options
Partial<WatchQueryOptions<Variables<D, V>, Data<D>>> | null
Set to reobserve the ObservableQuery
partial
(optional)boolean
If data was read from the cache with missing fields, partial will be true. Otherwise, partial will be falsy.
partialRefetch
(optional)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)number
The time interval (in milliseconds) on which this query should be refetched from the server.
query
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)boolean
Opt into receiving partial results from the cache for queries that are not fully satisfied by the cache.
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
errors
(optional) inherited from ApolloElementInterfacereadonly GraphQLError[] | null
Latest errors.
loading
inherited from ApolloElementInterfaceboolean
Whether a request is in-flight.
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
executeQuery
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 |
|
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
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 |
|
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)Callback 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)Callback for when an error occurs.
Parameters
error
Error
Returns
void
refetch
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 |
|
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
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 |
|
See query |
variables |
|
See variables |
fetchPolicy |
|
See fetchPolicy |
errorPolicy |
|
See errorPolicy |
context |
|
Context object passed through the link execution chain. |
Returns
boolean
subscribe
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 |
|
See query |
variables |
|
See variables |
fetchPolicy |
|
See fetchPolicy |
errorPolicy |
|
See errorPolicy |
context |
|
Context object passed through the link execution chain. |
Returns
ZenObservable.Subscription
subscribeToMore
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
watchQuery
Creates 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>>
documentChanged
(optional) inherited from ApolloElementInterfaceLifecycle callback that reacts to changes in the GraphQL document.
Parameters
document
DocumentNode | TypedDocumentNode | null
The GraphQL document.
Returns
void
variablesChanged
(optional) inherited from ApolloElementInterfaceLifecycle callback that reacts to changes in the operation variables.
Parameters
variables
Variables<D, V> | null
The variables.
Returns
void
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 |