-
Notifications
You must be signed in to change notification settings - Fork 1
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.
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.
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"] }
}
]
}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 ] }). |
{ "name": "modelName", "fields": [ { "name": "fieldName1", .... }, { "name": "fieldName2", .... } ], "constraints": [ // uniqueness { "name": "uniqueConstraint", type: "unique", keys: ["fieldName1", "fieldName2"] } ] }
- 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)
Fields are the attributes that make up a model. data-primals-engine supports a wide variety of field types to cover all needs:
| 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 |
| 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.
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
Editorcan create and modify articles, but not delete them.
This system allows for granular security of access to your data.
The engine includes a robust authentication system based on JWT (JSON Web Tokens).
-
User Management: A
Usermodel is typically used to manage user accounts. -
Security:
JWT_SECRETensures that tokens cannot be forged.
-
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.