4.1 Tables
      Back to home
      1. Home
      2. 4: Data Tables & Labels
      3. 4.1 Tables

      Understanding Primary vs Secondary Tables

      The two types of structured data tables in Rayven, and how they work together.

      Overview

      Tables are the backbone of structured data storage in Rayven applications. Every application must include a Primary Table—this is the anchor for structured data, providing unique identifiers (UIDs) that other data can relate to. You can also create any number of Secondary Tables to support, enrich, or extend the records in your Primary Table. Understanding the distinction and how to use them effectively is crucial to designing well-structured and scalable applications.

      Primary Tables

      A Primary Table is required in every Rayven application. It contains your core records—those entities that everything else in the app revolves around. Each row in a Primary Table must have a UID and can optionally include label columns to enable grouping and filtering of data.

      Examples of Primary Table use cases:

      • A CRM application might have Customers as the primary table.

      • A fleet management system might use Vehicles.

      • An employee tracking system might use Staff Members.

      Each UID in the Primary Table serves as a reference point for structured and unstructured data alike. It becomes the basis for data iteration, grouping, workflow processing, and user data filtering.

      Best used for:

      • Entities you want to apply workflows to individually or in filtered groups.

      • Central records to which most other data will relate.

      Secondary Tables

      Secondary Tables are optional but essential for building powerful and flexible applications. They are used to store structured data that supplements or relates to the records in your Primary Table.

      A Secondary Table might include:

      • Additional entity types – e.g. Contacts, Projects, Tasks that relate to the core records in the Primary Table.

      • Lookup values – e.g. Status types, dropdown options used in forms or workflows.

      • Child records – e.g. Quote line items tied to a Quote record in the Primary Table.

      • Reference data – e.g. Equipment types, job categories, or template entries.


      Secondary Tables can contain multiple rows for each Primary Table UID. They can be linked via configuration or through workflow logic.

      Important options when configuring columns in a Secondary Table:

      • Key Column – Used as the unique identifier for each row (required for write-back via workflows).

      • Unique Values – Prevents duplicate values in that column.

      • Required Value – Ensures no nulls in that column.

      • Column Lookup ID – Used for advanced logic or CSV import mappings.

      When to Use Which?

      Scenario Use Primary Table Use Secondary Table
      Tracking core records (e.g. Assets, Customers) ✅ ✅
      Storing metadata or child items (e.g. Line items for a quote, Tasks for a project, or Contacts for a customer) ❌ ✅
      Grouping/filtering users or records by labels ✅ ❌
      Storing additional sets of data that relate to UIDs ❌ ✅
      Storing system reference data (e.g. statuses, options) ❌ ✅
       

      Linking Primary and Secondary Tables

      Tables can be linked:

      • Using the “Table Linking Options” from the Actions menu on a Secondary Table, which allows enforced linking via UID or Label.

      • Manually in a Workflow, using logic nodes or Javascript to associate rows based on shared column values.

      Note: Linking between two Secondary Tables is not natively supported in the Workspace UI but can be achieved with custom logic.

      Labels and Their Role in Primary Tables

      Only Primary Tables support labels, which are used for grouping, filtering, and controlling access:

      • Labels are configured as columns.

      • Labels can be Default (none), Single Label, or Multi-Label.

      • User Groups can be assigned label-based filters to control what data each user sees.

      • Workflows and widgets can be configured to iterate over or display data by label value.

      Summary

      • Primary Tables store the core records of your app. They are mandatory and must include unique identifiers (UIDs).

      • Secondary Tables are optional and used to store related or supplemental data. They can link to Primary Table UIDs or labels.

      • Use Table Linking to define relationships and Labels to support grouping and access control.

      • The right use of both types of tables leads to well-structured, modular, and scalable applications in Rayven.

      FAQs

      Do I need a Secondary Table in every application?
      No. You only need a Secondary Table if you have additional data sets that don't belong in your Primary Table.

      Can I have multiple Primary Tables?
      No. Each application must have one Primary Table. However, you can structure multiple applications under a single account if needed.

      Can Secondary Tables link to other Secondary Tables?
      Not directly using the workspace UI, but you can create logic-based links via workflows or UI Code nodes.

      What happens if I delete a UID in the Primary Table?

      Deleting a UID from the Primary Table will permanently remove the anchor for that record. This means:

      • All unstructured workflow data stored against that UID in the Cassandra database will be lost.

      • Any Secondary Table records linked to that UID may become orphaned and unusable.

      This action is irreversible and should only be done with caution. It's best practice to use workflows to manage deletion scenarios and preserve data integrity.

      Can I create a workflow that iterates over rows in a Secondary Table?
      Yes, but iteration is only native for Primary Table rows. For Secondary Tables, you'll need to use Query Table nodes and loop manually in logic.