Go to AppSheet

Search for articles...

All Collections DATA References References Between Tables

References Between Tables

Learn about references, when to create them, and how to use them so
that your data makes sense.
Written by Santiago Uribe Montoya
Updated over a week ago

Understanding References
Introduction

Once you have an app with multiple tables, it's often useful to create connections,
known as references, between the app's tables.

For example, an order capture app might contain the following tables:

1. Customers table having one record per customer.

2. Products table having one record per product being sold.
3. Orders table having one record per order taken.
4. Order Details table having one record per line item in its parent order.

The order capture app might contain the following references:

1. Each Orders record will reference the Customers record of the customer who
placed that order.
2. Each Order Details record will reference its parent Orders record.
3. Each Order Details record will reference its corresponding Products record.

References serve three purposes:

1. They allow you to represent relationships. For example, the reference between
the Orders record and the Customers record allows you to capture the
relationship between an order and the customer who placed that order.
2. They allow you to easily retrieve information from a related record in another
table. For example, the reference between the Order Details record and the
Products table allows you to start from an individual Order Details record and
retrieve the name, image, and price fields from the related Products record.
3. They allow you to navigate from one record to another. For example, you might
retrieve a particular Order Detail record then navigate to the related Orders
records, and then to the related Customers records.
Adding a Reference

You create a reference by adding a Ref type field to a table and specifying the related
table's name. For example, in the Orders table you would add a Ref to the Customers
table. In the Order Details table you would add one Ref to the Orders table and
another to the Products table.

Reverse References

For each Ref you add, the system automatically adds a reverse reference in the
opposite direction. For example, when you add the Ref from the Orders table to the
Customers table, the system automatically adds a reverse reference from the
Customers table to the Orders table.

Reverse References serve three purposes:

1. They allow you to navigate from one record to all of its related records.
2. They allow the user interface to easily display a record along with all of its related
records in another table.
3. They allow aggregates to be computed like the count of a customer's orders or
the total dollar value of a customer's orders.

References and Reverse References Contain Key Values

A Ref type field always stores the key value of the referenced record. For example, if
the key value of a Customers record is "Ann Adams" then the Ref field in the related
Orders record will contain the value "Ann Adams". A table's key value uniquely
identifies each record in that table. The copy of the key value in the Ref field allows
the system to unambiguously retrieve the proper record in the referenced table. You
can read more about key columns here.

The system-added reverse reference field is a list of the key values of the related
records. For example, the reverse reference in Customers record "Ann Adams" would
contain "1003", "1005", and "1010" if those were the key values of Ann's related Orders
records. When viewing an individual records, related reverse references appear as
inline views that can be customized.

Expressing Ownership Between Tables

References can indicate not only that two tables are related, but that records of one
table should be owned by (considered a part of) records from another table. This is
done by activating the IsAPartOf option in the Ref column structure. Typically, this
should only be done in cases where records containing the Ref column only make
sense when associated with a record from the referenced table. For example, you
may have a separate Order Details table for line items that reference an Order, but
conceptually each entry should be considered "part of" an Order and shouldn't exist
independently (put another way, the Order record "owns" the Order Details that
reference it).

There are several implications of enabling this ownership relationship:

1. Form views should allow users to add or update related records that are a part of
that record without leaving the form.
2. A form comprised of multiple records should be treated as a single update.
 3. If a record is deleted, any related records that are a part of it should also be
deleted (and again treated as a single update).

These behaviors haven't yet been fully implemented, but all three should be
considered when deciding whether to activate this option.

The first of these to take effect will be #1: System-generated reverse reference
columns related to Ref columns marked "IsAPartOf" will appear in form views and
allow users to view, add, and edit line items within the form view. The availability of
these options is limited by the table or slice permissions (and until the final form is
saved, pending adds can still be modified even if the table doesn't allow updates).

There are some limitations of which to be aware:

A table can only have one Ref column marked "IsAPartOf" (a record can only be a
part of one other record).
Actions are not supported within forms. Inline views based on reverse references
in forms will not display actions or trigger actions based on view events.
Canceling a form with pending line item adds/edits also cancels those adds/edits.

Creating References
A reference can be added to a table in two ways.

AppSheet automatically adds references when you generate or regenerate a

table.
You can manually add references.

System-Added References

When you initially create your app or when you regenerate a table's column structure,
AppSheet will try to automatically infer references between tables. For example, if you
have a Customers table with a Name column as its key, and if the Orders table has a
column called "Customer Name", the "Customer Name" field is assumed to be a Ref
column.

User-Added References

You can add a reference as follows:

1. Ensure your worksheet has a column to contain the reference.

2. If you needed to add a new worksheet column to contain the reference, go to the
Data > Column Structure pane and click the Regenerate button for the table. This
will include the newly added worksheet column in the table.
3. Go to the Data > Column Structure pane, show the table schema, and select the
column you wish to make a reference.
4. In the "Column Type" dropdown, select "Ref".
5. In the "ReferencedTableName" dropdown, select the referenced table.
6. Click "OK".
7. Save the changes.

System-Added Reverse References

Whenever a Ref column is created, AppSheet automatically creates a "reverse
reference" virtual column in the referenced table. This is true whether you add the
reference or the system does.

The "reverse reference" virtual column is given a default name that you can change.

The "reverse reference" virtual column is assigned an app formula that uses the
special function REF_ROWS(). REF_ROWS() is the name of a complex SELECT()
function.

For both references and reverse references, reference icons are displayed.

Connect Multiple Tables in Apps

Did this answer your question?

😞😐😃

My Apps 🙋Ask the Community

We run on Intercom