How Object Type Merges Work in Anypoint DataGraph

You can merge an object type from your API schema with either another object type in your unified schema or another object type in the same API schema. Merging types enables you to combine similar types into a single type and extend their fields and datasets for a more enriched query result.

You can only merge object types with other object types. You can have an extension merge, in which the merged types join data, or you can have a composition merge, in which the merged types simplify the unified schema but are joined without primary keys.

In Anypoint DataGraph, the type you configure to merge is your current type and the type you merge with is your target type.

Merge Two Collaboration Enabled Types

You can merge your current type with a target type that has collaboration enabled. If both types provide a primary key, you must ensure that both primary keys represent the same objects and identify the same record of that object. In this type of merge, known as an extension merge, both object types return the same dataset.

For example, assume you have a Customer API Schema that returns a Customer type with default query method customersById(id) and primary key id:

customersById(id): Customer
--------------------
--------------------
Customer
--------------------
id: string!
email:
firstName:
lastName:
telephone:

You also have an API schema called UserAccount with a type User:

usersById(id): User
--------------------
--------------------
User
--------------------
id:
email:
address: Address
accountId:
type:
organization:
--------------------
--------------------
Address
--------------------
addressLine1:
addressLine2:
city:
postalCode:
state:
country:

Assume that both Customer and User types point to the same object type and return the same information for that same object. To have the same primary key value, both types must identify the same customer object. Moreover, any common fields between the types must also return the same values. For example, for id = 1 in Customer type and id = 1 in User type, the values of the email fields must be exactly the same.

You might choose to merge the two types so that their combined data about the same customer can be queried in a single request.

Additionally, because both types also have a default query method that retrieves the same object, you can also merge the types so that in the unified schema, there is only one joined query method and type:

Customer type
- Default query method: customersById(id): Customer
- Primary key: id
UserAccount type:
- Default query method: usersById(id): User
- Primary key: id

The result is a single, merged, enriched type in the unified schema.

How Types Are Ordered When Merged

Whichever type is added first to the unified schema has the advantage of defining the name for the merged type and the corresponding default query method.

In this example, because the Customer API type was added first, the resulting type in the unified schema is called Customer, containing all the fields from both Customer and UserAccount types. The resulting query method is called customersById, returning the merged Customer type:

customersById(id): Customer
--------------------
--------------------
Customer
--------------------
id: string!
email:
firstName:
lastName:
telephone:
address: Address
accountId:
type:
organization:
--------------------
--------------------
Address
--------------------
addressLine1:
addressLine2:
city:
postalCode:
state:
country:

Merge Two Types When Only One Is Collaboration Enabled

You can also merge two types when only one of the types has collaboration enabled. In this case, the merge causes your current type (the type you are configuring to merge) to act as a reference to the target type (the type you are merging with). Note that for the merge to happen, the target type must have collaboration enabled, and both types must define one primary key or use composite keys.

After the merge is complete, the reference is declared and you can retrieve the fields only from your target type. If your current type has any other fields besides its primary keys, those fields become hidden and cannot be queried.

For example, assume an Order API schema that returns a Product type:

ordersById(id: string!) : Order
Order
----------
id: string!
amount: float!
date: string!
product: Product
-----------
-----------
Product
-----------
id: string!
name: string
------------

And a Product API Schema that also returns a Product type:

productsById(id: string!) : Product
Product
------------
id: string!
name: string
brand: string
description: string
unitPrice: float!
quantityRemaining: int!
-----------

You can merge the Product type in the Order API schema to the Product type in the Product API schema. In this case, the Product type in the Order API schema becomes a reference to the Product type in the Product API.

After merging, the unified schema looks like this:

ordersById(id: string!) : Order
productsById(id: string!) : Product
Order
----------
id: string!
amount: float!
date: string!
product: Product
-----------
-----------
Product
-----------
id: string!
name: string
brand: string
description: string
unitPrice: float!
quantityRemaining: int!
-----------

Note that now the Order type returns more data about the related product without you having to write a separate query.

In this example, the primary key for both types is id, and for both APIs, id returns the same product object record.

Merge Types That Use Composite Keys

The types you merge can also have query methods that use composite keys.

For example, assume the same Order API schema that returns a Product type:

ordersById(id: string!) : Order
Order
----------
id: string!
amount: float!
date: string!
product: Product
-----------
-----------
Product
-----------
id: string!
name: string
sku: string
------------

Consider also a SalesOrder API that also returns a Product type but uses composite keys id and sku:

SalesOrder(id: string!, sku: string!) : SalesOrder
Product
------------
id: string!
sku: string!
name: string
brand: string
description: string
unitPrice: float!
quantityRemaining: int!
-----------

After merging, the unified schema looks like this:

ordersById(id: string!, sku: string!) : Order
SalesOrderByID(id: string!, sku: string!) : SalesOrder
Order
----------
id: string!
amount: float!
date: string!
product: Product
-----------
-----------
Product
-----------
id: string!
sku: string!
name: string
brand: string
description: string
unitPrice: float!
quantityRemaining: int!
-----------

Merge Two Types That Do Not Have Primary Keys Configured

A composition merge occurs when you merge two types and neither has a primary key defined. This merging strategy does not require you to provide a default query method or a primary key.

Because there is no primary key in either type, merging them does not join the datasets returned by the types but rather joins both types as a single one. In this merge, you do not reference the same object: you combine the fields. After merging the current and target types, all fields in the current type become nullable in the unified schema. The result of this merge does not affect the query results for the types, but it allows for a cleaner unified schema in case you have duplicate types that don’t return the same dataset.

For example, assume you have a Europe Sales API Schema that returns an Amount type:

Europe Sales API Schema

Amount
----------
currency: String
price: float

You also have a North America API Schema that also returns an Amount type:

North America API Schema

Amount
----------
currency: String
price: float

You can merge them so that in the unified schema there is only one Amount type that returns data from the Europe Sales API or the North America Sales API, depending on the query. Although both types are similar, their datasets are not joined.

Merge Input Types

Input types are POST, PUT, and DELETE objects you use to modify information in your unified schema when you run mutations.

You can merge two input types only when all their fields match. Both types must have the same number of fields and cannot contain subsets of fields.

For example, assume you have an OrderInput API and a PurchaseInput API that contain the following identical fields:

OrderInput
----------
orderId: String!
customerEmail: String!
customerId: String!
OrderDate: String!
product: Product
Status: OrderStatus
totalAmount: float

You can merge the OrderInput API into the PurchaseInput API in the unified schema to consolidate these types.

You do not need to, nor can you, enable collaboration to merge input types.

Local Merges Between Objects in the Same API Schema

A local merge occurs when you merge an object type with another object type in the same API schema. You can then merge the resulting type with another local object type or with a type in the unified schema.

After a local merge, you can view and edit only the type that is the outcome of the merge. Additionally, you cannot enable or disable collaboration on the type or change its default query method or primary key. You can rename object types and fields, hide object types and fields, and merge and link with another object type.

Field Visibility in Local Merges

If you locally merge two object types that contain common fields but those fields have different visibilities, the fields in the locally merged type behave as follows:

Scenario	TypeA Field	TypeB Field	MergedType (Local)
1	Hidden	Hidden	Hidden
2	Hidden	Visible	Visible
3	Visible	Hidden	Visible
4	Visible	Visible	Visible

Scenario

TypeA Field

TypeB Field

MergedType (Local)

Hidden

Visible