create-mapped-relationship.md

targetFilterKeys identify properties in the targetEntity that are used to locate the entites to connect to the sourceEntityKey. For example, if you know that you want to build a relationship to user entities with a known email, this can be expressed by:

{
  ...,
  targetFilterKeys: [['_class', 'email']],
  targetEntity: {
    _class: 'User',
    email: '[email protected]',
    firstName: 'Person',
    lastName: 'Example'
  }
}

In J1QL, it is expressed by this query:

find User with email='[email protected]'

The system will create a relationship to each entity returned by the query.

CREATE_MAPPED_RELATIONSHIP operations will soon support specifying a J1QL statement instead otargetFilterKeys.

In the example, targetFilterKeys contains a single, compound key target filter using the _class and email property values. targetFilterKeys is an Array to support finding entities in more than one way.

find User with email='[email protected]' or (firstName='Person' and lastName='Example')

This is currently achieved with:

{
  ...,
  targetFilterKeys: [['_class', 'email'], ['_class', 'firstName', 'lastName']],
  targetEntity: {
    _class: 'User',
    email: '[email protected]',
    firstName: 'Person',
    lastName: 'Example'
  }
}

A new entity will be automatically created when no matching entities are found, unless skipTargetCreation: true is included in the operation. This auto-create mechanism supports the scenario where a provider entity is related to something that is not ingested from the provider account.

The targetEntity properties will be added to entities created in this way; the properties will not be added to matching entities which were created by an integration directly