Send Mutation Requests
| AVAILABLE API VERSION |
|---|
| Beta v59.0–65.0 |
| Generally Available v66.0 and later |
A mutation request modifies your record data by either creating, updating, or deleting the data. When you send a record create request, you can also request for fields from the newly created record in one request. However, you can’t query fields with record update and delete requests.
Your request can fail if you have multiple fields with the same name, which results in naming conflicts. To avoid conflicts, use aliases to rename the result of a field.
1first: AccountCreate(input: { ... })
2second: AccountCreate(input: { ... })All or None Requests
The uiapi field of UIAPIMutations type has an input field for an allOrNone boolean argument. The default is true.
1mutation OperationName {
2 uiapi(input: { allOrNone: false }) {
3 first: AccountCreate(input: { ... })
4 second: AccountCreate(input: { ... })
5 }
6}When allOrNone is true, all operations are rolled back if any operation fails, or all operations are executed within a transaction. When allOrNone is set to false, only operations that fail are rolled back along with any operations that depend on those failed operations, allowing other successful operations to execute.
Example: Successful Multiple Account Creation
If you set allOrNone to false when creating multiple accounts, a failed operation doesn’t prevent the other operations from successfully executing. In this example, the second operation successfully executes while the first one fails.
1mutation MutipleAccounts{
2 uiapi(input: { allOrNone: false }) {
3 AccountCreate(input: {
4 Account: {
5 NumberOfEmployees: 100
6 }
7 }) {
8 Record {
9 Id
10 Name { value }
11 }
12 }
13 second: AccountCreate(input: {
14 Account: {
15 Name: "Amazing Account"
16 }
17 }){
18 Record {
19 Id
20 Name { value }
21 }
22 }
23 }
24}The response looks like this.
1{
2 "data": {
3 "uiapi": {
4 "AccountCreate": null,
5 "second": {
6 "Record": {
7 "Id": "001RM000005eoXGYAY",
8 "Name": {
9 "value": "Amazing Account"
10 }
11 }
12 }
13 }
14 },
15 "errors": [
16 {
17 "extensions": {
18 "ErrorType": "DataFetchingException"
19 },
20 "locations": [
21 {
22 "column": 5,
23 "line": 3
24 }
25 ],
26 "message": "Required fields are missing: [Name]",
27 "paths": ["uiapi", "AccountCreate"]
28 }
29 ]
30}Example: Unsuccessful Multiple Account Creation
If allOrNone is true when you’re creating multiple accounts, all account creation fails if any single operation fails. In this example, the first account create operation fails because Name if a required field on accounts, so the other operation also fails.
1mutation MutipleAccounts{
2 uiapi(input: { allOrNone: true }) {
3 AccountCreate(input: {
4 Account: {
5 NumberOfEmployees: 100
6 }
7 }) {
8 Record {
9 Id
10 Name { value }
11 }
12 }
13 second: AccountCreate(input: {
14 Account: {
15 Name: "Amazing Account"
16 }
17 }){
18 Record {
19 Id
20 Name { value }
21 }
22 }
23 }
24}The response looks like this.
1{
2 "data": {
3 "uiapi": {
4 "AccountCreate": null,
5 "second": null
6 }
7 },
8 "errors": [
9 {
10 "extensions": {
11 "ErrorType": "DataFetchingException"
12 },
13 "locations": [
14 {
15 "column": 5,
16 "line": 3
17 }
18 ],
19 "message": "Required fields are missing: [Name]",
20 "paths": ["uiapi", "AccountCreate"]
21 },
22 {
23 "extensions": {
24 "ErrorType": "DataFetchingException"
25 },
26 "locations": [
27 {
28 "column": 5,
29 "line": 13
30 }
31 ],
32 "message": "The transaction was rolled back since another operation in the same transaction failed.",
33 "paths": ["uiapi", "second"]
34 }
35 ]
36}Order of Operations
The order of operations depends on each operation’s dependencies. To enable an operation to use a field from another operation in the same execution, use the @{alias} syntax. See Mutation Field References.
1FieldName: "@{aliasName}"Example: Multiple Account Creation and Updates
You can create multiple accounts and update them in a single request. The update operation requires the Id field value from the create operation. In this example, the account create operation with the second alias is successful, followed by a successful update on the same account. The first account create fails because a required field is missing.
1mutation MutipleCreateWithUpdate{
2 uiapi(input: { allOrNone: false }) {
3 AccountCreate(input: {
4 Account: {
5 NumberOfEmployees: 100
6 }
7 }) {
8 Record {
9 Id
10 Name { value }
11 }
12 }
13 second: AccountCreate(input: {
14 Account: {
15 Name: "Amazing Account"
16 }
17 }){
18 Record {
19 Id
20 Name { value }
21 }
22 }
23 AccountUpdate(input: {
24 Account: {
25 Name: "Awesome Account"
26 }
27 Id: "@{second}"
28 }) {
29 Record {
30 Id
31 Name { value }
32 }
33 }
34 }
35}The response looks like this.
1{
2 "data": {
3 "uiapi": {
4 "AccountCreate": null,
5 "second": {
6 "Record": {
7 "Id": "001RM000005eoYEYAY",
8 "Name": {
9 "value": "Amazing Account"
10 }
11 }
12 },
13 "AccountUpdate": {
14 "Record": {
15 "Id": "001RM000005eoYEYAY",
16 "Name": {
17 "value": "Amazing Account"
18 }
19 }
20 }
21 }
22 },
23 "errors": [
24 {
25 "extensions": {
26 "ErrorType": "DataFetchingException"
27 },
28 "locations": [
29 {
30 "column": 5,
31 "line": 3
32 }
33 ],
34 "message": "Required fields are missing: [Name]",
35 "paths": ["uiapi", "AccountCreate"]
36 }
37 ]
38}
j