> For the complete documentation index, see [llms.txt](https://docs.ins-pi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ins-pi.com/freelucy/work-in-the-app/usage.md).

# How relationships work in Freelucy

YouDesign Freelucy opens on a single CI, your **primary element**. From there you add other records as upstream or downstream relationships, remap them between sides, and remove them. You do this in whichever view fits the task, and nothing is written to your CMDB until you click **Commit**.

<figure><img src="/files/GRAkwIotxm5GAW04mzGH" alt="The primary element with upstream and downstream relationships"><figcaption><p>Upstream relationships sit on one side of your primary element, downstream on the other.</p></figcaption></figure>

## The mental model

* **Primary element.** The record you opened Freelucy from. Every view centers on it.
* **Upstream and downstream.** Relationships have a direction. Freelucy keeps the two sides separate so you always know which way a relationship points.
* **Data Hub.** The drawer you pull records from to relate to your primary element. See [Find records with the Data Hub](/freelucy/work-in-the-app/data-hub.md).
* **Views.** Three ways to see and edit the same record: Classic, Flow, and List. Staged edits are shared across all of them. See [Choose a view](/freelucy/get-started/choose-a-view.md).
* **Stage, then commit.** Every edit is staged first. You review the full batch before anything reaches ServiceNow.

{% hint style="info" %}
**You can only map allowed relationships.** Freelucy shows tables and relationship types that are defined as suggested relationships or approved by your administrator. If you need a relationship that is not available, ask your administrator to add it. See [Manage suggested relationships](/freelucy/configuration/suggested-relationships.md).
{% endhint %}

## Two ways to add a relationship

Every view supports the same two gestures:

1. **Click to add.** Find a record in the Data Hub and use its **Add to Upstream** or **Add to Downstream** action. This is the most forgiving path and works the same in every view.
2. **Drag to add.** Drag a record from the Data Hub onto a valid drop target. Freelucy lights up only the sides your metamodel allows.

## Stage, review, commit

<figure><img src="/files/ud7GJK3yLWWiH6rWmBqP" alt="Stage, review, then commit"><figcaption><p>Staged edits live on the canvas until you commit them as one batch.</p></figcaption></figure>

Until you commit, every edit is a stage. You can keep adding, remapping, and removing for as long as you like. When you are ready, [commit your changes](/freelucy/work-in-the-app/commit-changes.md) and Freelucy writes the whole batch to ServiceNow at once. Discard instead, and everything staged is dropped.

***

## What's next

* [Find records with the Data Hub](/freelucy/work-in-the-app/data-hub.md)
* [Create a relationship](/freelucy/work-in-the-app/create-relationship.md)
* [Create multiple relationships at once](/freelucy/work-in-the-app/create-multiple.md)
* [Remap a relationship](/freelucy/work-in-the-app/remap-relationship.md)
* [Delete a relationship](/freelucy/work-in-the-app/delete-relationship.md)
* [Commit your changes](/freelucy/work-in-the-app/commit-changes.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ins-pi.com/freelucy/work-in-the-app/usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.