Best Practices for Creating Primary and Secondary Tables in Rayven.io

Creating well-structured Primary and Secondary Tables is essential for building scalable, maintainable applications in Rayven.io.

1. Understand the Purpose of Primary and Secondary Tables

Primary Tables contain your core business entities. Each record represents a unique item, such as a device, user, or customer.

Secondary Tables are used to store related or historical data, typically in a one-to-many relationship with a Primary Table.

Examples

2. Keep Primary Tables Lean

Primary Tables should store only essential attributes that describe the core entity. Avoid including fast-changing or voluminous data such as logs, calculations, or events.

Good examples of Primary Table fields:

• ID or UID

• Name or label

• Type or category

• Status

• Location or region

Avoid:

• Time-series readings

• Detailed logs

• Long text comments

These should be stored in Secondary Tables.

3. Use Unique IDs and Foreign Keys

Each row in a Primary Table must include a Unique ID (UID). This allows workflows and dashboards to join and associate data reliably.

Secondary Tables must include a foreign key that references the UID in the related Primary Table.

Example:

• Primary Table Devices has a UID: device_001

• Secondary Table SensorReadings has a column device_id that matches device_001

This enables real-time workflows to associate incoming data with known entities.

4. Label Key Fields in Primary Tables

Label fields in Primary Tables are used for filtering, grouping, and controlling visibility across Rayven.io.

Examples:

• building_name

• city

• device_type

• customer_segment

These labels can be used in:

• Workflow nodes for filtering or branching

• Dashboards for grouping and summarizing

• User group rules to control access to specific data

5. Use Secondary Tables for Related Data or Metadata

 

• Used to store related data or metadata associated with entries in a Primary Table.

• Typical use cases:

  • Metadata or extensions of a primary entity (e.g., device settings, tags, audit records)

  • Sub-entity records (e.g., order line items, asset attachments)

  • Event logs or historical data (e.g., temperature readings, status changes, user actions)

• Characteristics:

  • Linked to Primary Tables through reference fields (e.g., foreign keys like device_id)

  • Support append-style data storage (e.g., logging a new row per event or interaction)

  • Schema still matters — fields must be defined and respected

  • Often queried or joined with Primary Tables to enrich dashboards or logic

Important: Secondary Tables are not inherently schema-less or better suited to high-frequency writes unless designed carefully. Workflows that use Secondary Tables should follow performance best practices, including batching, filtering, and size management.

6. Avoid Mixing Concepts

Keep Primary Tables focused on defining entities. Do not use them to store variable-length logs, JSON blobs, or inconsistent fields.

Instead:

• Use one Primary Table per distinct entity

• Use one Secondary Table per relationship or event stream

• Keep fields consistent and typed

7. Use Clear Naming Conventions

Standardized naming improves clarity and usability across teams and workflows.

Examples:

• Table names: Devices, DeviceReadings, Users, UserActions

• Field names: device_id, created_at, status, value, region

Avoid ambiguous or overloaded field names like name, type, or data.

8. Apply Validation and Visibility Rules

Rayven.io allows configuration of rules such as:

• Required fields

• Unique values

• Hidden columns in dashboards

• Default values or formats

Apply these wherever possible to ensure data integrity.

9. Test with Simulated Data and Workflows

Before using in production:

• Insert test data into tables

• Run workflows to check UID joins

• Confirm label-based filtering works

• Test dashboards and grouping behavior

Use debug nodes in workflows to trace how Primary and Secondary Table data is accessed and transformed.

---

Q&A: Table Design in Rayven.io

Q: What is the main difference between a Primary and Secondary Table?
A: A Primary Table stores core entities like devices or customers. A Secondary Table stores data related to those entities, such as readings, logs, or transactions.

Q: When should I use a Secondary Table instead of adding more columns to a Primary Table?
A: Use a Secondary Table when you need to store one-to-many records, such as multiple readings for one device or multiple feedback entries for one customer.

Q: How are tables linked in workflows?
A: Workflows use Unique IDs to match real-time or imported data with records in a Primary Table. Secondary Tables are written to or read from as part of processing.

Q: Can I filter data in workflows or dashboards using table values?
A: Yes. Label fields in the Primary Table can be used to filter or group data dynamically across workflows and interfaces.

Q: What happens if a Secondary Table does not reference a valid UID?
A: The data may be stored but will not be associated correctly with a Primary Table record, which can break dashboards or workflow logic.

Q: Can I use Secondary Tables without a Primary Table?
A: It’s possible, but not recommended. Most workflows assume the presence of a related Primary Table for context, filtering, and data integrity.

---

Summary

• Use Primary Tables for core entities and label-driven filtering

• Use Secondary Tables for logs, readings, transactions, or one-to-many data

• Enforce UIDs and maintain referential integrity

• Keep schemas clean, consistent, and optimized for real-time workflows

• Test with real data and validate joins in workflows