Common GraphQL Unions

A union is a GraphQL type that can be one of several object types. A field that returns a union can give you a different object each time, and you choose which fields to read for each possible type.

The Insites schema has one union, Customizable. You only meet it when you work with older, deprecated model queries. New code reads records and users directly and does not need it.

Customizable

union Customizable = Listing | Profile | User

Customizable is the object a customization is attached to. The schema marks it as deprecated and says to use records instead.

Two object types have a customizable field that returns this union: Customization and ListingsCustomization.

Reading a union

A union has no fields of its own. Ask for __typename to learn which type you got, and use an inline fragment for each type whose fields you need:

customizable {
  __typename
  ... on User { id email }
  ... on Profile { id }
}

Example: check the union on your instance

{
  __type(name: "Customizable") {
    kind
    possibleTypes { name }
  }
}

{
  "data": {
    "__type": {
      "kind": "UNION",
      "possibleTypes": [
        { "name": "Listing" },
        { "name": "Profile" },
        { "name": "User" }
      ]
    }
  }
}

This ran read-only on the docs.insites.io instance on 1 November 2026.

Common mistakes

• Selecting a field directly on the union, such as customizable { id }. GraphQL refuses it. Put the field inside an inline fragment.
• Forgetting __typename. Without it, your code cannot tell which fragment matched.
• Building new features on it. It belongs to deprecated queries; use records and users.

• ObjectsThe object types a union can return.
• InterfacesFields shared by several objects.