Concepts

Fundamental Concepts

data-primals-engine is built on a set of core concepts designed to provide maximum flexibility and power. Understanding these concepts is essential to getting the most out of the platform.

---

1. Models

A model represents a data entity in your application, similar to a table in an SQL database or a collection in MongoDB. Each model has a set of fields that define the structure of the data it contains.

• Visual Definition: Models can be created and modified directly from the user interface, without requiring manual database migrations.

• Flexibility: A model's structure can be updated at any time.

Model generation

Models are the way to handle structured data. They organize data and they can be declared in JSON.

{
  "name": "product",
  "description": "E-commerce product schema",
  "fields": [
    { "name": "name", "type": "string", "required": true },
    { "name": "price", "type": "number", "required": true },
    { "name": "stock", "type": "number", "default": 0 },
    { "name": "category", "type": "relation", "relation": "taxonomy",
       "relationFilter": { "$eq": ["$type", "category"] }
    },
    { "name": "tags", "type": "relation", "relation": "taxonomy", "multiple": true,
       "relationFilter": { "$eq": ["$type", "keyword"] }
    }
  ]
}

Dynamic Index Management

The engine features a sophisticated system for managing database indexes directly from the model editor UI. This eliminates the need for manual database administration or migration scripts for indexing, significantly speeding up development and reducing errors.

Indexes are created, updated, and removed automatically when you save a model's structure. All created indexes are partial indexes, meaning they only include documents for the specific model and user, which optimizes storage and performance.

You can enable indexing on any field by checking the index box in the model editor and choosing one of the following types:

Index Type	indexType	Use Case & Behavior -
Regular	regular	Purpose: The standard index for most use cases. It dramatically speeds up queries, sorting, and filtering on a specific field. Behavior: Creates a standard ascending B-tree index on a single field. This is the default and most common index type. -
Text Search	text	Purpose: Enables powerful, language-aware full-text search across one or more fields. It's ideal for implementing search bars that need to query descriptions, titles, and other text-heavy content. Behavior: Creates a single, special compound text index for the entire model. All fields marked with indexType: 'text' are included in this single index. This allows you to use MongoDB's $text operator in your search queries. -
Geospatial	2dsphere	Purpose: Essential for location-based queries. It allows you to efficiently find documents within a certain radius, within a polygon, or sorted by distance. Behavior: Creates a 2dsphere index on a single field. This index type should be used exclusively on fields of type geolocation which store data in GeoJSON format (e.g., { "type": "Point", "coordinates": [ -73.97, 40.77 ] }).

Model constraints

{
    "name": "modelName",
    "fields": [
         { "name": "fieldName1", .... },
         { "name": "fieldName2", .... }
    ],
    "constraints": [
        // uniqueness
        { "name": "uniqueConstraint", type: "unique", keys: ["fieldName1", "fieldName2"] }
    ]
}

Other model features

• Handles up to 1500 direct relations per document by default (can be customized). For larger datasets, use intermediate collections or maxRelationsPerData constant.
• Anonymizable fields (encrypted for API users)

2. Fields

Fields are the attributes that make up a model. data-primals-engine supports a wide variety of field types to cover all needs:

Fields types

Type	Description	Properties/Notes
string	Character string.	minLength, maxLength
string_t	International character string ID.	same as string, translated in { key, value }
number	Numeric value (integer or float).	min, max
boolean	Boolean value (true/false).	–
date	Stores a ISO date.	–
datetime	Stores an ISO date and time.	–
richtext	Rich text field (HTML) for WYSIWYG editors.
richtext_t	International rich text field (HTML) for WYSIWYG editors.	i18n
email	String validated as an email address.	–
password	String that will be automatically hashed.	–
enum	Allows selecting a value from a predefined list.	items: ["value1", "value2"]
relation	Creates a link to a document in another model.	relation: "target_model_name", multiple: true/false
file	For uploading a file (stored on S3 if configured).	allowedTypes:['image/jpeg', 'image/png', 'image/bmp'], maxSize: 1024*1000
image	Specialized file type for images, with preview.	–
array	Stores a list of values.	itemsType: 'enum' // any type except relations
object	Stores a nested JSON object. –
code	Stores language="*" as string, stores language="json" as arbitrary JSON structure.	language="json" conditionBuilder=true
color	Stores an hexadecimal value of an RGB color	'#FF0000'
model	Stores a model by name	–
modelField	Stores a model field path	–

Each field can have specific validation rules to guarantee data integrity.

3. Permissions (RBAC)

Access management is handled by a Role-Based Access Control (RBAC) system.

• Roles: You can define roles (e.g., Admin, Editor, Visitor).

• Granular Permissions: For each model, you can assign CRUD (Create, Read, Update, Delete) permissions to each role. For example, an Editor can create and modify articles, but not delete them.

This system allows for granular security of access to your data.

4. Authentication

The engine includes a robust authentication system based on JWT (JSON Web Tokens).

• User Management: A User model is typically used to manage user accounts.

• Security: JWT_SECRET ensures that tokens cannot be forged.

5. Advanced Data Management

• Complex Queries: Leverage the power of MongoDB to perform complex queries and aggregations on your data.

• Automatic Auditing: The engine can automatically maintain a history of changes for each record, allowing you to know who did what and when.