Skip to content

Managing Relationships Between Entities

There are multiple ways to create relationships based on OData specification.

In general, you can do any of the following:

  1. Create relationship between existing entities.

  2. Create a new entity and establish relationship with an existing one.

  3. Create new entities and establish relationships between them.

Create Relationship Between Existing Entities

This approach is used when entities on both ends of the relationship can exist independently. For example, an event can exist without any features and a feature can exist without any associated event.

To create a relationship between existing entities, use the createLink() method from DataService or a subclass. And use the deleteLink() method to delete a relationship.

// Locate the event to be linked
Event event = ...;

// Locate the feature to be linked with the event
Feature feature = ...;

// Link them together
eventService.createLink(event, Event.features, feature);

// Delete the relationship between the feature and the event
eventService.deleteLink(event, Event.features, feature);
/// Locate the event to be linked
let event = ...

/// Locate the feature to be linked with the event
let feature = ...

/// Link them together
try eventService.createLink(from: event, property: Event.features, to: feature)

/// Delete the relationship between the feature and the event
try eventService.deleteLink(from: event, property: Event.features, to: feature)

Note

Since the cardinality of an event-feature relationship is many-to-many, a relationship between an event and a feature can be created or deleted, but cannot be updated.

You can also use createLink() and deleteLink() to create/delete relationships between entities which relationship cardinality is zero-or-one or many. You can perform updates with either createLink() or updateLink(). Use of updateLink() verifies that the end being updated has a cardinality of zero-or-one.

In this example , there is only one global theme per event.

// Locate the global theme for the event
GlobalTheme theme = ...;

// Establish a relationship between the event and the global theme
eventService.createLink(event, Event.theme, theme);

// Use another theme
GlobalTheme anotherTheme = ...;

// Link the event to the other theme
eventService.updateLink(event, Event.theme, anotherTheme);
/// Locate the global theme for the event
let theme = ...

/// Establish a relationship between the event and the global theme
try eventService.createLink(from: event, property: Event.theme, to: theme)

/// Use another theme
let anotherTheme = ...

/// Link the event to the other theme
try eventService.updateLink(from: event, property: Event.theme, to: anotherTheme)

Create a New Entity and Associate It with an Existing Entity

There are two approaches to create a new entity and associate it with an existing entity. Each approach generates a different OData request. However, some OData services may only accept one of the two approaches.

  • Create with Bind This approach creates the new entity against its own entity set. The new entity is bound to an existing entity with which the relationship is to be established.

    // Declare a new session
    Session session = new Session(false);
    
    // Set session properties
    ...
    
    // Locate the event to associate with
    Event event = ...;
    
    // Bind the new session to the existing event
    session.bindEntity(event, Session.event);
    
    // Create the session
    eventService.createEntity(session);
    
    /// Declare a new session
    let session = Session(withDefaults: false)
    
    /// Set session properties
    ...
    
    /// Locate the event to associate with
    let event = ...
    
    /// Bind the new session to the existing event
    session.bindEntity(event, to: Session.event)
    
    /// Create the new session
    try eventService.createEntity(session)
    
  • Create Related Entity This approach creates the new entity against navigation property of an existing entity with which the relationship is to be established.

    // Declare a new session
    Session session = new Session(false);
    
    // Set session properties
    ...
    
    // Locate the event to associate with
    Event event = ...;
    
    // Create new session and associate with the specified event
    eventService.createRelatedEntity(session, event, Event.sessions);
    
    /// Declare a new session
    let session = Session(withDefaults: false)
    
    /// Set session properties
    ...
    
    /// Locate the event to associate with
    let event = ...
    
    /// Create new session and associate it with the specified event
    try eventService.createRelatedEntity(session, in: event, property: Event.sessions)
    

Deep Insert

Deep insert is an approach to create an entity with inline definitions of related entities. Support of this varies between OData services. Offline OData also has some limitations with deep inert. See Limitations with Deep Inserts.

// Declare a new event
Event newEvent = new Event(false);

// Set properties for the new event
...

// Declare a session belonging to the event
Session newSession = new Session(false);

// Set properties for the new session
...

// Link event to session
newSession.setEvent(newEvent);

// Create a new session with the event in-line
eventService.createEntity(newSession);
/// Declare a new event
let newEvent = Event(withDefaults: false)

/// Set event properties
...

/// Declare a new session
let newSession = Session(withDefaults: false)

/// Set session properties
...

/// Assign the new event to the new session
newSession.event = newEvent

/// Create the new session with the new event in-line
try eventService.createEntity(newSession)

Note that, due to an Offline OData limitation, you may not be able to create a new event with a number of new sessions using deep insert.

Batch and Change Set

This approach takes advantage of OData batch and change set. A batch can contain multiple queries and change sets. A change set can contain multiple requests that make changes to data. Creating multiple entities and establishing relationships between them can be done using a feature of OData change set whereby later requests can reference entities created by former requests. As a result, in the same change set, you can create a parent entity first, and then create its child entities by referencing it.

RequestBatch batch = new RequestBatch();
ChangeSet changeSet = new ChangeSet();

// Declare a new event
Event newEvent = new Event(false);

// Set properties for new event
...

// Declare a new session
Session newSession = new Session(false);

// Set properties for new session
...

// Create the new event in change set
changeSet.createEntity(newEvent);

// Create the new session in the change set. This indicates that the session is dependent
// upon the creation of the event.
changeSet.createRelatedEntity(newSession, newEvent, Event.sessions);

// Add change set to batch
batch.addChanges(changeSet);

// Execute the batch request
eventService.processBatch(batch);
let changeSet = ChangeSet()
let batch = RequestBatch()

/// Declare a new event
let newEvent = Event(withDefaults: false)

/// Set properties for the new event
...

/// Declare a new session
let newSession = Session(withDefaults: false)

/// Set properties for the new session
...

/// Create the new event in change set
changeSet.createEntity(newEvent)

/// Create the new session in change set. This indicates that the session is dependent upon creation of the event
changeSet.createRelatedEntity(newSession, in: newEvent, property: Event.sessions)

/// Add change set to batch
batch.addChanges(changeSet)

/// Execute the batch request
try eventService.processBatch(batch)

Last update: September 23, 2022