|
| 1 | +--- |
| 2 | +id: input-unions |
| 3 | +title: Input Unions |
| 4 | +sidebar_label: Input Unions |
| 5 | +sidebar_position: 3 |
| 6 | +--- |
| 7 | + |
| 8 | + |
| 9 | + |
| 10 | +Input unions (Spec § [3.10.1](https://spec.graphql.org/September2025/#sec-OneOf-Input-Objects)) are a variant on standard input objects such that only one of the defined fields may be used in a query. This can be helpful if you have an input object, such as search parameters, that gives multiple ways to search, but you want the user submitting a query to choose exactly one option to search by. |
| 11 | + |
| 12 | +By definition an input union is a standard [input object](../types/input-objects.md) (a class or a struct), all rules of standard input objects apply (i.e. field names must be unique, no use of interfaces etc.). However... |
| 13 | + |
| 14 | +**Input unions:**<br/> |
| 15 | +✅ MUST have no default values declared on any field.<br/> |
| 16 | +✅ MUST have all nullable fields |
| 17 | + |
| 18 | +:::warning |
| 19 | +A declaration exception will be thrown and the server will fail to start if either of these rules are violated for any declared input union. |
| 20 | +::: |
| 21 | + |
| 22 | +## Creating An Input Union |
| 23 | +An object can be declared as an input union in multiple ways: |
| 24 | + |
| 25 | +### Using Attribution |
| 26 | + |
| 27 | +Use the `[OneOf]` attribute to mark an object as ALWAYS being an input union. Any place the class or struct is referenced as an input to a method it will be handled as an input union. |
| 28 | + |
| 29 | +```csharp title="Declaring an input union with the [OneOf] attribute" |
| 30 | +// highlight-next-line |
| 31 | +[OneOf] |
| 32 | +[GraphType(InputName = "SearchOptions")] |
| 33 | +public class SearchDonutParams |
| 34 | +{ |
| 35 | + public string Name {get; set;} |
| 36 | + public Flavor? Flavor {get; set; } // assume flavor is an enum |
| 37 | +} |
| 38 | +``` |
| 39 | + |
| 40 | +```csharp title="Using an Input Union in a Controller" |
| 41 | +public class BakeryController : GraphController |
| 42 | +{ |
| 43 | + [QueryRoot("findDonuts")] |
| 44 | + // highlight-next-line |
| 45 | + public List<Donut> FindDonuts(SearchDonutParams search) |
| 46 | + { |
| 47 | + /// guaranteed that only one value (name or flavor) is non-null |
| 48 | + return []; |
| 49 | + } |
| 50 | +} |
| 51 | +``` |
| 52 | + |
| 53 | +```graphql title="Equivilant schema type definition" |
| 54 | +## relevant graphql type generated |
| 55 | +input SearchOptions @oneOf { |
| 56 | + name: String |
| 57 | + flavor: Flavor |
| 58 | +} |
| 59 | +``` |
| 60 | + |
| 61 | +### Inherit from GraphInputUnion |
| 62 | + |
| 63 | +Creating a class that inherits from `GraphInputUnion` works in the same way as using `[OneOf]` but adds some additional quality of life features in terms of metadata and default value handling. |
| 64 | + |
| 65 | +_See below for details on using `GraphInputUnion`_ |
| 66 | + |
| 67 | + |
| 68 | +```csharp title="Inheriting from GraphInputUnion" |
| 69 | +[GraphType(InputName "SearchParams")] |
| 70 | +// highlight-next-line |
| 71 | +public class SearchDonutParams : GraphInputUnion |
| 72 | +{ |
| 73 | + public string Name {get; set;} |
| 74 | + public Flavor? Flavor {get; set; } // assume flavor is an enum |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +```csharp title="Using an Input Union in a Controller" |
| 79 | +public class BakeryController : GraphController |
| 80 | +{ |
| 81 | + [QueryRoot("findDonuts")] |
| 82 | + // highlight-next-line |
| 83 | + public List<Donut> FindDonuts(SearchDonutParams search) |
| 84 | + { |
| 85 | + /// guaranteed that only one value (name or flavor) is non-null |
| 86 | + return []; |
| 87 | + } |
| 88 | +} |
| 89 | +``` |
| 90 | + |
| 91 | +```graphql title="Equivilant schema type definition" |
| 92 | +## relevant graphql type generated |
| 93 | +input SearchOptions @oneOf { |
| 94 | + name: String |
| 95 | + flavor: Flavor |
| 96 | +} |
| 97 | +``` |
| 98 | + |
| 99 | +## Nullable Fields |
| 100 | +The specification defines an input union as *"a special variant of Input Object where exactly one field must be set and non-null, all others being omitted."* (Spec § [3.10.1](https://spec.graphql.org/September2025/#sec-OneOf-Input-Objects)). As such, all properties declared on a class or struct that is being used as an input union must be nullable, the supplied query MUST set exactly one field to a non-null value on a query document. |
| 101 | + |
| 102 | +```csharp title="Example Scenarios" |
| 103 | + |
| 104 | +// 🧨 FAIL: Flavor is non-nullable. A graph declaration exception will be thrown at start up. |
| 105 | +[OneOf] |
| 106 | +public class SearchDonutParams |
| 107 | +{ |
| 108 | + public string Name {get; set;} |
| 109 | + public Flavor Flavor {get; set; } // assume flavor is an enum |
| 110 | +} |
| 111 | + |
| 112 | +// 🧨 FAIL: Name declares a default value. A graph declaration exception will be thrown at start up. |
| 113 | +[OneOf] |
| 114 | +public class SearchDonutParams |
| 115 | +{ |
| 116 | + public SearchDonutParams |
| 117 | + { |
| 118 | + this.Name = "%"; |
| 119 | + } |
| 120 | + |
| 121 | + public string Name {get; set;} |
| 122 | + public Flavor? Flavor {get; set; } // assume flavor is an enum |
| 123 | +} |
| 124 | + |
| 125 | +// ✅ SUCCESS |
| 126 | +[OneOf] |
| 127 | +public class SearchDonutParams |
| 128 | +{ |
| 129 | + public string Name {get; set;} |
| 130 | + public Flavor? Flavor {get; set; } |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +## Using `GraphInputUnion` |
| 135 | +This special base type can be used to expose some additional, quality of life methods for dealing with nullability and default values. |
| 136 | + |
| 137 | +```csharp |
| 138 | +public abstract class GraphInputUnion |
| 139 | +{ |
| 140 | + // Will return the value, if it was supplied on the query, otherwise fallbackValue. |
| 141 | + // this method is is heavily optimized to be performant at runtime |
| 142 | + public TReturn ValueOrDefault<TValue, TReturn>(Expression<Func<TObject, TValue>> selector, TReturn fallbackValue = default); |
| 143 | +} |
| 144 | + |
| 145 | +[GraphType(InputName = "SearchParams")] |
| 146 | +public class SearchDonutParams : GraphInputUnion |
| 147 | +{ |
| 148 | + public string Name {get; set;} |
| 149 | + |
| 150 | + public Flavor? Flavor {get; set; } // assume flavor is an enum |
| 151 | +} |
| 152 | + |
| 153 | + |
| 154 | +// Sample Usage |
| 155 | +public class BakeryController : GraphController |
| 156 | +{ |
| 157 | + [QueryRoot("findDonuts")] |
| 158 | + public List<Donut> FindDonuts(SearchDonutParams search) |
| 159 | + { |
| 160 | + InternalSearchParams internalParams = new(); |
| 161 | + internalParams.Name = search.ValueOrDefault(x => x.Name, "%"); |
| 162 | + internalParams.Flavor = search.ValueOrDefault(x => x.Flavor, Flavor.All); |
| 163 | + return _service.SearchDonuts(internalParams); |
| 164 | + } |
| 165 | +} |
| 166 | +``` |
| 167 | + |
| 168 | +:::info |
| 169 | +The `ValueOrDefault()` method will return a type of the fallback value, NOT of the input object property. This allows you to return non-null defaults in place of nullable values that must be passed on the input object. This should greatly reduce bloat in transferring query supplied values and reasonable fallbacks when necessary. When returning non-reference types, they must have compatibility between the nullable and non-nullable versions (e.g. `int` and `int?`) |
| 170 | +::: |
| 171 | + |
| 172 | + |
| 173 | +## Support |
| 174 | +Input Unions are supported in *GraphQL ASP.NET version 1.6* or later |
0 commit comments