# Nested Queries

The Avonni Nested Query Data Source allows you to retrieve hierarchical data from your Salesforce org—specifically, parent records and their related child records—in a single query. This is ideal for displaying data in components like the Avonni Tree, which requires a nested structure.

{% hint style="warning" %}
Currently, nested queries are only supported by the [Avonni Tree](/dynamic-components/components/tree.md) and [Avonni Relationship Graph](/dynamic-components/components/relationship-graph.md) components.
{% endhint %}

***

## Core Concepts

### What is a Nested Query?

A Nested Query retrieves a list of parent records and, for *each* parent record, also retrieves its associated child records. This creates a nested data structure reflecting your Salesforce data's parent-child relationships. This differs from a standard Query, which retrieves a flat list of records.

### When to Use Nested Queries

Use Nested Queries when you need to display hierarchical data, typically in components like:

* **Avonni Tree:** The primary use case, as the Tree component is designed to visualize hierarchical data.
* Other components might benefit from displaying nested relationships in the future.

***

## Managing Nested Queries

{% hint style="warning" %}

#### Important Note: Nested Query Configuration Updates

We are enhancing the configuration process for Nested Queries to make it even more straightforward. As a result, the specific steps and options described on *this page* may differ slightly from the latest version available in the Avonni Dynamic Components builder. This documentation will be updated shortly to reflect these improvements once fully released.
{% endhint %}

### Creating a Nested Query

You can create a new Avonni Nested Query in two ways:

* **Via the Resources Button:**
  1. Click the **Resources** button (usually located in the page editor or component panel).
  2. Select the option to create a new **Nested Query Resource**.
* **From an Avonni Component (e.g., Tree):**
  1. Select the Avonni component (e.g., Tree) to connect to the nested query.
  2. In the component's properties panel, look for a button or link labeled "**Create a Nested Query**" or "**New Nested Query**". Click it.

{% @arcade/embed flowId="kThBCDpa9aWmKcckM3dh" url="<https://app.arcade.software/share/kThBCDpa9aWmKcckM3dh>" %}

### Editing a Nested Query

You can modify an existing Avonni Nested Query in two ways:

* **From the Resources Menu:**
  1. Click the **Resources** button.
  2. Locate the Nested Query you want to edit in the list of resources.
  3. Select the option to edit the Nested Query (this might be an "Edit" button, a pencil icon, or clicking the query name).
* **From an Avonni Component:**
  1. Select the Avonni component (e.g., Tree) currently using the Nested Query.
  2. Find the section related to the data source or query in the component's properties panel.
  3. Look for an option to edit the Nested Query (this might be an "Edit" button, a pencil icon, or similar).

{% hint style="warning" %}

#### Important Note

* Modifying an existing Nested Query will affect *all* Avonni components within your project using that same Nested Query.
* **Creating a New Version (Recommended):** If you want to change a Nested Query *without* affecting other components, use the "**Save As**" to create a *new* copy of the Nested Query. Then, modify the latest copy.
  {% endhint %}

***

## Configuring Nested Queries

Configuring a Nested Query involves defining both the parent query (to retrieve the top-level records) and the child query (to retrieve the related records for each parent).

### Parent Query Configuration

The parent query defines the top-level records you want to retrieve. This is similar to configuring a standard Query:

* **Object:** Select the Salesforce object for the parent records (e.g., `Account`).
* **Fields:** Choose the fields you want to retrieve from the parent object.
* **Filters (Optional):** Add filters to limit the parent records retrieved (e.g., `Type equals 'Customer'`). You can use both static and reactive filters here.

### Child Query Configuration

The child query defines how to retrieve the related records for *each* parent record.

* **Object:** Select the Salesforce object for the child records (e.g., `Contact`).
* **Fields:** Choose the fields you want to retrieve from the child object.
* **Relationship Field:** *Crucially*, you'll need to specify the field on the *child* object that relates it to the *parent* object (e.g., `AccountId` on the `Contact` object). This is how the Nested Query knows which child records belong to which parent record.
* **Filters (Optional):** You can add filters to refine the child records retrieved further. You can even use reactive filters here, referencing attributes of the *parent* record. For example, you could filter Contacts to only show those with a `Status` of 'Active' for each selected Account.

### Example: Accounts and Contacts

To display a tree of Accounts and their related Contacts:

1. **Create a Nested Query Resource.**
2. **Parent Query:**
   * **Object:** `Account`
   * **Fields:** `Id`, `Name` (and any other Account fields you want to display)
3. **Child Query:**
   * **Object:** `Contact`
   * **Fields:** `Id`, `FirstName`, `LastName`, `Email`
   * **Relationship Field:** `AccountId` (This links the Contact to its parent Account)
4. **Connect the Nested Query to an Avonni Tree component.**
5. **Configure the Tree component** to display the desired fields from parent (Account) and child (Contact) records.

***

## Reactive Nested Queries

Nested Queries can also be reactive, just like standard Queries. This means that the data displayed can update dynamically based on user interactions or changes in other components.

* **Reactive Filters in Parent Query:** You can use reactive filters to control which top-level records are displayed in the parent query.
* **Reactive Filters in Child Query:** You can use reactive filters in the *child* query, and these filters can even reference attributes of the *parent* record. This allows for very dynamic and context-aware data displays. For example, you could have a dropdown that controls which *type* of Contacts are shown for each Account.


---

# Agent Instructions: 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.avonnicomponents.com/dynamic-components/component-builder/data-sources/nested-queries.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.