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:

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

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

API UserAccount Schema
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.

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 was added first, the resulting type in the unified schema is called Customer, containing all the fields from both Customer and UserAccount types, and the resulting query method is called customersById, returning the merged Customer type:

Unified Schema
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 merging 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 a primary key.

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 key, those fields become hidden and cannot be queried.

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

Order API Schema
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:

Product API Schema
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:

Unified schema
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 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.

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

Was this article helpful?

πŸ’™ Thanks for your feedback!

Edit on GitHub