1- # Custom Queries
1+ # Custom Queries and Mutations
22
33[[ toc]]
44
5+ With custom mutations and custom queries we distinguish between model related and model unrelated (simple) custom
6+ quries/mutations. The difference is that model related queries/mutations always are tied to a model, so Vuex-ORM-Apollo
7+ expected that the query/mutation type is the same as the model. A model related custom mutation ` upvotePost ` is expected
8+ to be of type ` Post ` . To make this even clearer, all model related queries and mutations are called on a specific Model
9+ or a record of this model.
10+
11+ A simple query or simple mutation is not tied to a model. And so Vuex-ORM-Apollo doesn't expect the result to be of a
12+ specific type. Also the return value is not automatically inserted in the Vuex store.
13+
14+
15+ ::: warning
16+ It's not a clean and good solution that the simple queries are also triggered via Vuex action, but currently the only
17+ way. This might be changed in the future, when we find a better solution.
18+ :::
19+
20+
21+ ## Model related custom query
522
623You may sometimes want to send custom GraphQL query. We support this via the ` query ` action. However please notice that
724the convenienceMethods here are named ` customMutation ` and ` $customMutation ` due to a name conflict with the ` query() `
@@ -23,8 +40,8 @@ the post id, but this could be anything else. Please also notice that `record.$c
2340of the record into the arguments list. The plugin automatically determines if there are multiple records or a single
2441record is requests by looking in the arguments hash if there is a ` id ` field and respectively setups the query.
2542
26- A custom query is always tied to the model, so the plugin expects the return value of the custom query is of the model
27- type. In this example that means, that Vuex-ORM-Apollo expects that the ` example ` query is of type ` Post ` .
43+ A model related custom query is always tied to the model, so the plugin expects the return value of the custom query
44+ is of the model type. In this example that means, that Vuex-ORM-Apollo expects that the ` example ` query is of type ` Post ` .
2845
2946This generates the following query:
3047
@@ -55,3 +72,122 @@ Variables:
5572
5673Like for all other operations, all records which are returned replace the respective existing records in the Vuex-ORM
5774database.
75+
76+
77+ ## Model unrelated simple query
78+
79+ There might be cases when you just want to send a plan graphql query without having this plugin doing magic things.
80+
81+ Simple Queries allow to do that. Let's assume we do have a ` status ` query in our GraphQL API which let ask for the
82+ status of all subsystems:
83+
84+ ``` javascript
85+ const query = `
86+ query status {
87+ backend
88+ smsGateway
89+ paypalIntegration
90+ }` ;
91+
92+ const result = store .dispatch (' entities/simpleQuery' : {}, bypassCache: true });
93+ ```
94+
95+ The result contains a hash which is shaped like the request:
96+
97+ ``` javascript
98+ {
99+ backend: true ,
100+ smsGateway: false ,
101+ paypalIntegration: true
102+ }
103+ ```
104+
105+ Nothing is inserted in the Vuex store.
106+
107+
108+ ## Model related custom mutation
109+
110+ Along with the CRUD mutations you may want to send custom GraphQL mutations. We support this via the ` mutate ` action:
111+
112+ ``` javascript
113+ const post = Post .query ().first ();
114+ await post .$mutate ({ mutation: ' upvotePost'
115+
116+ // is the same as
117+ await Post .mutate ({ mutation: ' upvotePost' : post .id });
118+
119+ // or
120+ await Post .dispatch (' mutate' : ' upvotePost' : post .id });
121+ ```
122+
123+ As you can see you have to provide the mutation name and any further arguments you want to pass. In this case we send
124+ the post id, but this could be anything else. Please also notice that ` record.$mutate ` automatically adds the id
125+ of the record into the arguments list. The plugin automatically determines if there are multiple records or a single
126+ record is requests by looking in the arguments hash if there is a ` id ` field and respectively setups the query.
127+
128+ A model related custom mutation is always tied to the model, so the plugin expects the return value of the custom query
129+ is of the model type. In this example that means, that Vuex-ORM-Apollo expects that the ` upvotePost ` mutation is of type
130+ ` Post ` .
131+
132+ This generates the following query:
133+
134+
135+ ``` graphql
136+ mutation UpvotePost ($id : ID ! ) {
137+ upvotePost (post : $id ) {
138+ id
139+ userId
140+ content
141+ title
142+
143+ user {
144+ id
145+ email
146+ }
147+ }
148+ }
149+ ```
150+
151+ Variables:
152+
153+ ``` json
154+ {
155+ "id" : 42
156+ }
157+ ```
158+
159+ Like for all other operations, all records which are returned replace the respective existing records in the Vuex-ORM
160+ database.
161+
162+
163+ ## Model unrelated simple mutation
164+
165+ Like simple custom queries, you can also send simple custom mutations. The action (` simpleQuery ` ) stays the same.
166+ Let's assume we do have a ` sendSms ` mutation (this is a bad example, never setup your app like this please!) in our
167+ GraphQL API which let us send a SMS.
168+
169+ ``` javascript
170+ const query = `
171+ mutation SendSms($to: string!, $text: string!) {
172+ sendSms(to: $to, text: $text) {
173+ delivered
174+ }
175+ }` ;
176+
177+ const result = store .dispatch (' entities/simpleQuery'
178+ query,
179+ variables: { to: ' +4912345678' : ' GraphQL is awesome!'
180+ });
181+ ```
182+
183+ The result contains a hash which is shaped like the request:
184+
185+ ``` javascript
186+ {
187+ sendSms: {
188+ delivered: true
189+ }
190+ }
191+ ```
192+
193+ Nothing is inserted in the Vuex store.
0 commit comments