Introduction
Welcome to RDataCore! If you're new to our platform, understanding the relationship between entity definitions and entities is the foundation for everything else you'll build. Think of it like this: if you're running a hospital, the entity definition is the patient record template that defines what information you track (name, date of birth, blood type, allergies), while entities are the actual patient records that follow that template.
In this guide, we'll walk through these core concepts step by step, explore the various field types and options available, and show you the different ways data can flow into your RDataCore instance. By the end, you'll have a solid understanding of how to model and manage any type of data, from customer profiles to IoT sensor readings to inventory items.
Entity Definitions: Your Data Blueprints
An entity definition is the schema or blueprint that describes the structure of your data. Before you can store any information in RDataCore, you need to define what that information looks like. It's where you specify what fields exist, what type of data each field holds, what constraints apply, and how the data should be validated.
Think of entity definitions as templates or molds. Before you can create a "Temperature Sensor" record, you need a "Temperature Sensor" entity definition that specifies:
- What fields exist (location, current_reading, unit, last_calibration_date, battery_level)
- What type each field is (text, decimal, date, percentage)
- Which fields are required vs. optional
- What default values to use
- Which fields should be indexed for fast searching
- Which fields must be unique
Entity definitions are created once and then used to create many entities. A single "Recipe" definition can be used to store thousands of recipes. A "Flight Reservation" definition serves as the template for millions of bookings.
When you modify an entity definition, RDataCore's versioning system (covered in an upcoming blog post) ensures smooth transitions without breaking existing data.
You can also configure visual and organizational settings on entity definitions, like icons for easy recognition in the UI and groupings to organize related definitions together.
What Are Entities?
An entity in RDataCore is a single data record: an instance of structured data that represents something in the real world. This could be a patient record, a warehouse location, a recipe, a flight booking, a sensor reading, or literally any piece of information you want to track.
Each entity belongs to a specific entity definition that determines its structure. When you create an entity, you're filling in the fields defined by its entity definition with actual values. For example, a "Weather Station" entity might have values like
station_id: "WS-2847", location: "Munich Airport", temperature: 18.5, and humidity: 72.Entities are the actual data you work with day-to-day. They can be:
- Created manually through the UI
- Imported in bulk from CSV files or external databases
- Generated automatically through workflows
- Pushed via API by external applications like your e-commerce platform or CRM
- Received through webhook triggers from services like Stripe, Shopify, or custom systems
Every entity gets a unique UUID, timestamps for creation and modification, and can be organized into hierarchical structures using paths. To learn more about organizing entities, check out our blog post on Entity Hierarchies.
Understanding Field Types
RDataCore supports a comprehensive set of field types to model virtually any data structure. When adding a field to an entity definition, you choose from:
Basic Types:
String- Text data of any length (product names, descriptions, addresses)Integer- Whole numbers (quantities, counts, age)Float- Decimal numbers for precise calculations (prices, measurements, coordinates)Boolean- True/false values (is_active, has_warranty, is_verified)
Date and Time:
Date- Calendar dates without time (birth_date, expiry_date)DateTime- Full timestamps with date and time (created_at, last_login)Time- Time of day without date (opening_hours, scheduled_departure)
Complex Types:
JSON- Flexible structured data for nested objects or arrays (metadata, configuration, tags)UUID- Universally unique identifiers, perfect for references to other entitiesEnum- Predefined list of allowed values (status: pending|approved|rejected, priority: low|medium|high|critical)
Special Types:
Email- Validated email addresses with format checkingURL- Validated web addressesPhone- Phone number fields with formatting support
Choosing the right field type is important because it affects validation, storage efficiency, and how the data appears in the UI. For example, a
Date field will show a date picker, while an Enum field will display a dropdown with your predefined options. A Float field on a "Lab Result" entity definition might store blood glucose levels, while a JSON field on a "Product" definition could store variant options like sizes and colors.Field Constraints and Options
Beyond the basic field type, each field can be configured with additional options that control how data is validated and stored:
Required vs. Optional: Mark fields as required to ensure entities can't be created without essential data. A "Medical Record" entity should require patient_id, while emergency_contact might be optional.
Default Values: Set default values that automatically populate when creating new entities. Useful for status fields (default: "pending"), timestamps (default: current date), or counters (default: 0). A "Support Ticket" might default priority to "medium" and status to "open".
Uniqueness Constraints: Mark fields as unique to prevent duplicate values across all entities of that type. Perfect for email addresses, SKUs, serial numbers, license plates, or any identifier that must be one-of-a-kind. Your "Asset" definition might have a unique asset_tag field.
Indexing: Enable indexing on fields you frequently search or filter by. Indexed fields offer dramatically faster query performance, especially important as your dataset grows. Common candidates include email addresses, status fields, dates, external IDs, and foreign keys. If you're building a "Shipment Tracking" system, index the tracking_number and status fields.
Validation Rules: Some field types include automatic validation. Email fields validate email format, URL fields validate URL structure, and Enum fields only accept predefined values.
These options work together to ensure your data stays clean, consistent, and queryable. A well-designed entity definition with appropriate constraints prevents bad data from entering your system in the first place. You can explore all these options in our API documentation.
Entity Definition Configuration
Beyond fields, entity definitions themselves have several configuration options:
Icons: Assign an icon to your entity definition for visual recognition in the UI. When browsing the entity tree or viewing lists, icons help you quickly identify different entity types. A truck icon for "Shipments", a user icon for "Customers", a thermometer for "Temperature Readings", a box for "Inventory Items". Choose from a library of icons or use custom ones.
Groupings: Organize related entity definitions into groups. For example, you might have a "Logistics" group containing Shipment, Warehouse, and Carrier definitions, an "IoT" group with Sensor, Reading, and Alert definitions, and a "CRM" group with Contact, Company, and Deal definitions. Groupings make navigation easier in systems with many entity types.
Draft Mode: Entity definitions support a draft mode that lets you design and test your schema before activating it. While in draft, you can freely modify fields without affecting production data. Once you're satisfied, publish the definition to make it available for entity creation.
Description: Add a description to document the purpose of the entity definition. This helps team members understand what data the definition is meant to capture. A "Clinical Trial Participant" definition might include notes about HIPAA compliance requirements.
Versioning (Standard Feature): RDataCore automatically versions your entity definitions. When you modify a published definition, the system creates a new version while maintaining compatibility with existing entities. This is a standard feature we'll cover in detail in an upcoming blog post about Entity Definition Versioning.
Creating Entities Manually
The most straightforward way to create an entity is through the RDataCore admin interface. This is ideal for:
- Adding individual records (a new employee, a single product)
- Testing your entity definitions before bulk imports
- Manual data entry for small datasets
- Quick corrections or additions
To create an entity manually:
- Navigate to the entity definition you want to create an instance of
- Click "Create Entity" (or the plus icon)
- Fill in the required and optional fields
- Optionally set a path for hierarchical organization (see our Entity Hierarchies guide)
- Save the entity
The form automatically validates your input based on the field types and constraints. Required fields are marked, invalid data is highlighted, and helpful error messages guide you to fix any issues. If you try to enter a duplicate value in a unique field or an invalid email format, the system will let you know immediately.
Manual creation is great for small volumes and testing, but RDataCore really shines when handling bulk data through automated processes. For large datasets (think importing 50,000 products from your old system or syncing orders from your e-commerce platform) you'll want to use imports, workflows, or the API.
Multiple Ways to Populate Your Database
Manual creation is just one of many ways entities can enter your RDataCore database. For real-world data management, you'll typically use a combination of these approaches:
Import Workflows: Import data from CSV, JSON, or XML files. Define field mappings, transformation rules, and target paths. Perfect for migrating existing data from legacy systems, periodic bulk updates from partners, or loading historical records. Import 100,000 customer records from your old CRM in minutes.
API Integration (Active - Push): Your applications can actively push data to RDataCore using our REST API. Create, update, and delete entities programmatically. Ideal for real-time integrations where your e-commerce platform pushes new orders, your IoT gateway sends sensor readings, or your mobile app creates user profiles.
API Integration (Passive - Pull): RDataCore can also actively fetch data from external APIs on a schedule or trigger. Pull inventory levels from your supplier's API every hour, sync contact updates from Salesforce daily, or fetch exchange rates from a financial data provider.
Webhooks: Receive real-time notifications from external systems. When events occur in other platforms (Stripe payment completed, Shopify order placed, GitHub issue created), webhooks can trigger entity creation or updates automatically. No polling required.
Export Workflows: While primarily for getting data out, export workflows can be part of a bidirectional sync where data flows both ways between RDataCore and other systems.
Each method integrates with RDataCore's workflow engine, allowing you to apply transformations, validations, and business logic regardless of how data enters the system. We'll cover workflow definitions in detail in an upcoming blog post about Import/Export Workflows.
The Public API for Third Parties
RDataCore provides a comprehensive Public API that enables third-party integrations and external access to your data. This is separate from the Admin API and is designed specifically for controlled external access.
With the Public API, you can:
- Allow partners to query specific entity types (distributors checking inventory levels)
- Enable customers to access their own data (order history, account details)
- Build custom applications that read from RDataCore (mobile apps, dashboards)
- Create public data portals (product catalogs, event listings)
Access is controlled through API keys and pre-shared tokens, giving you fine-grained control over who can access what data. You can restrict access by entity definition, filter by fields, and limit operations (read-only vs. read-write).
The Public API follows RESTful conventions and includes full OpenAPI documentation. You can explore the available endpoints, test queries, and generate client code directly from the API documentation.
For integration scenarios, the Public API is often combined with webhooks: external systems push notifications to RDataCore via webhooks, and pull data back via the API. This creates a robust, bidirectional data flow between your systems.