Deciding What Belongs in the Primary Table

Understanding how to structure your application data using Rayven's Primary Table.

Overview

The Primary Table in Rayven is the foundational data structure that underpins your application. It holds the core entities that your app revolves around—each identified by a UID (Unique Identifier). This UID acts as the anchor point for all structured and unstructured data, workflow executions, and user access control.

This article helps you decide what data should go into the Primary Table, and how it differs from data better suited to Secondary Tables. Getting this right is essential for performance, scalability, and clarity when building your app.

Understanding the Role of the Primary Table

The Primary Table serves a special purpose in every Rayven application:

• It defines the core record type that your application is built around.

• It is the anchor for all workflow data, including time series records stored in Cassandra.

• It is the target for label-based grouping and filtering across the application.

• It is used to drive logic and visualisation in workflows and interface widgets.

Each row in the Primary Table must have a unique UID. All unstructured data stored by workflows, and all interface filtering, is tied back to these UIDs.

When to Use the Primary Table

You should use the Primary Table to store the main entity type your application is managing. This is usually the "thing" that all other data relates to. Examples include:

• Assets in an asset management app

• Customers in a CRM

• Projects in a project management app

• Sites in an environmental monitoring app

• Properties in a property maintenance app

• Devices or sensors in a real-time monitoring app

These entities are typically:

• Persistent (they don't change often)

• Unique (each one represents a distinct object)

• Central to the app’s logic and data model

How the Primary Table is Used in the Platform

The Primary Table enables:

• Iterative Workflows: Workflows can loop over each UID or apply logic only to a filtered subset using label values.

• Widget Generation: Many front-end nodes (widgets) have display settings like "One widget per UID", which rely on Primary Table UIDs.

• Data Aggregation: Label columns in the Primary Table allow for grouping and summarising data.

• Access Control: User Groups use Label Filters based on Primary Table labels to control what data users can see.

Note: The Primary Table is the anchor for all Cassandra time series (unstructured) data.
Primary and Secondary Tables store structured data with fixed columns, while Cassandra stores unstructured, time series data that can be an ongoing stream with dynamic structures. The Primary Table’s UID is what links those time series records to the correct entity.

What Doesn't Belong in the Primary Table

Avoid putting data into the Primary Table if it:

• Represents supporting information that can have multiple rows per entity (e.g. Contacts for a Customer, Tasks for a Project, Asset Maintenance Schedules, Store Hours for a Site)

• Is best stored as related structured records rather than expanding the core entity table (to keep the Primary Table focused and efficient)

• Needs to be linked to multiple different UIDs (i.e. complex many-to-many relationships)

These types of records belong in Secondary Tables, which are designed for this purpose.

What If You’re Not Sure?

A simple rule of thumb:

If you can say: “Everything else in the app relates back to this,” then it probably belongs in the Primary Table.

If you need multiple key entities (e.g. both Projects and Employees as top-level entities), you should choose one as the Primary Table based on which entity will act as the central point for labelling, grouping, and filtering. The other entity can be created as a Secondary Table with a Key Column to ensure each record is unique if needed. Remember, only the Primary Table supports label columns, so your choice should be guided by which set of records other data and relationships will be grouped around.

Labels and the Primary Table

Label columns are only available in the Primary Table. They are essential for grouping, filtering, and user-specific views. You can use multiple labels (e.g. Region, Department, Customer Type) to build flexible filtering and logic.

What Happens if You Change the UID?

Changing the UID of a Primary Table row is not recommended. All unstructured workflow data in Cassandra is stored by UID, so if you change it, that row’s historical time series data will no longer be linked to the record. The structured table data itself will remain intact, but it will no longer be associated with the historical unstructured data collected under the old UID.

Summary

The Primary Table is the backbone of your Rayven application. Use it to define your central entities—those that serve as the core reference point for all data, workflows, and interfaces.

Secondary Tables are there to support and enrich your Primary Table records with additional details, relationships, or logs. Getting this structure right will ensure a scalable, logical, and easy-to-maintain application.

FAQs

What happens if I don’t define a Primary Table?
Every Rayven application must have a Primary Table. It is required for workflows, widgets, labelling, and linking unstructured time series data in Cassandra.

Can I have more than one Primary Table?
No. Each application has a single Primary Table. If you need multiple key entities, choose one as the Primary Table based on which entity should have labels for grouping and filtering. The other entity can be created as a Secondary Table with a Key Column for unique records if needed.

Can I change a UID after data has been ingested?
Yes, but it is not recommended. The structured table data will remain, but any unstructured workflow data stored in Cassandra under the old UID will no longer be linked to the record.

Why are labels only available in Primary Tables?
Labels are designed for grouping and filtering top-level records. Since Secondary Tables may contain multiple records per UID, applying labels there would not provide consistent grouping or filtering behaviour across the application.

Can a Secondary Table link to more than one Primary Table?
No. A Secondary Table links to a single Primary Table using UID or Label values. More complex relationships can be managed via workflows or custom logic.