Entities

Entities are the foundation of every Anybuild application. An entity represents a real or abstract thing that the application needs to track - a Customer, an Invoice, a Patient, a Booking, a Product. Everything else in the platform - views, workflows, UI, security - builds on top of entities.

Defining an entity does a lot of work in one place. A field with Is Mandatory and Is Unique turned on doesn’t just validate input in a form - it becomes a real database constraint. A Reference field doesn’t just render a lookup widget - it becomes a foreign key. This is the practical meaning of “model-driven” introduced in How the Platform Works: the entity definition is the system, generated forms and database schema included, not a description of it that something else has to keep in sync.

This page covers everything that makes up an entity’s definition - fields and their four kinds, components, conditional relevance, and security rules - roughly in the order you’d touch them when building one out from scratch.

The Entities Screen

Navigate to Data Model → Entities to see all entities in the current application.

The entities screen has three views, selectable from the tab strip at the top:

List view

The default view. Shows all entities as a sortable table with columns:

Entity Name - the human-readable name
Module Name - which module the entity belongs to
Created By - the user who created it
Modified On - last modification timestamp
Published On - when the entity was last published
Status - a checkmark (✓) if published and current, or a Publish link if there are unpublished changes

Use + Add Entity to create a new entity. Select one or more rows with the checkboxes to enable the Delete button.

Diagram view

Shows all entities as an interactive ERD. Each entity appears as a card listing its fields and their types. Relationships between entities are shown as connecting lines.

Within the diagram:

Pan by clicking and dragging the canvas
Zoom with the + / − buttons or scroll wheel
Fit to screen and grid toggle from the toolbar at the bottom left
Locate Entity… dropdown at the top right to jump to a specific entity
Collapse All to reduce all entity cards to their headers
Click a field row to open the Edit Field panel for that field
Each entity card has per-entity actions: edit (pencil icon), clone, collapse

Publish All Changes button at the top right publishes all pending changes across all entities at once.

Modules view

Shows entities grouped by module as visual cards. Each module card lists the entities it contains as clickable links. Use the Filter elements search to find entities by name. This view is useful for understanding the overall structure of the application at a glance.

Publishing

Entities in Anybuild have a published/unpublished state. Changes made in the designer - adding fields, editing components, adjusting security rules - do not affect the live application until they are explicitly published.

To publish a single entity: click the Publish button at the top of the entity detail view, or click the Publish link in the Status column of the list view.

To publish all pending changes: use the Publish All Changes button in the diagram view.

An amber warning icon next to the Publish link in the list view indicates that the entity has been modified since its last publish. The Published On timestamp only updates when a publish action is performed.

Creating an Entity

Click + Add Entity from any view to open the Edit Entity panel.

Field	Description
Entity Name	Human-readable name, e.g. “Patient”
Entity ID	Auto-generated from the name, e.g. “patient”. Used internally and in the database.
Entity Module	Which module this entity belongs to. Required.
Entity Plural Name	Used in UI labels, e.g. “Patients” for list headings
Entity Description	Shown as a subtitle in the generated list view. Helps users understand what the entity represents.

After saving, the entity appears in the list with no fields yet. Add fields and components from the entity detail view.

Entity Detail View

Click any entity name in the list to open its detail view. This can be opened in two ways:

Open - opens as a slide-in panel while keeping the entity list visible behind it
Open in Tab - opens as a full dedicated page

The detail view shows a header bar with the entity name and four action buttons:

Edit - opens the Edit Entity panel to change name, module, plural name, or description
Add Component - adds a component (sub-entity) to this entity
Add Field - adds a new field to this entity
Security Rules - manages access rules for this entity

The Publish button appears at the top left. Open Data Entry and Clone links appear at the top right.

Fields are listed beneath the header bar. Each field shows its name and type in parentheses. The key icon identifies the ID field. Different icons distinguish value fields from reference fields.

Hovering a field row reveals inline actions: Edit, Clone Field, Security Rules, Delete.

Components appear below the fields as expandable rows. Click the > arrow to expand a component and see its fields listed beneath it, indented. Components can themselves contain nested components.

Fields

Fields define what information an entity stores. Each field has a Field Kind that determines its fundamental nature:

Field Kind	Stores	Use it for
Value	Plain user-entered or default data	Most fields - text, numbers, dates, booleans
Reference	A link to another record	Relationships - a Quote’s Customer, an Order’s Product
Stored Calculation	A computed value, persisted in the database	Computed values you need to query, filter, sort, or index by - order totals, status flags
Virtual Calculation	A computed value, never persisted	Computed values that are cheap to derive and don’t need indexing - margins, formatted labels

Value

A plain data field storing a single value - text, number, date, boolean, and so on. This is the most common field kind.

Field Type is selected from a dropdown. The available types include:

Base PostgreSQL types (Text, Bigint, Integer, Numeric, Boolean, Date, Timestamp, etc.)
Custom field types defined in Data Model → Field Types

Field options:

Option	Description
Has Default Value	When enabled, exposes the Default Value configuration. See Default Values below.
Is ID Field	Marks this field as the entity’s natural identifier. Creates a unique constraint in the database. Only one field should be marked as the ID field per entity.
Is Mandatory	The field must have a value before a record can be saved.
Is Unique	Values in this field must be unique across all records of this entity.
Is Indexed	Creates a database index on this field, improving query performance for large datasets.
Is Conditionally Relevant	See Conditional Relevance below.
Show In List	Whether the field appears as a column in the entity’s list view. On by default.
Show In Form	Whether the field appears in the record creation form. On by default.
Show In Details	Whether the field appears in the record detail view. On by default.

Default Values

When Has Default Value is enabled on a field, three default value types are available:

Fixed Value A static value that is always used as the default. Suitable for fields that should start with a known constant - a default status, a fixed category, a boolean flag.

Auto-Increment Links the field to an Auto-Number configuration (see Auto-Numbers below). Each new record automatically receives the next value in the sequence. Used for identifier fields such as invoice numbers, order IDs, and reference codes.

Expression The most powerful option. An SQL expression is evaluated each time a new record is created, and the result is used as the default value. The expression has access to the full context of the record being created:

Component Fields - all fields on the current entity and its components, accessible by name (e.g. price, quantity)
Reference chain traversal - fields on referenced entities and their references in turn, using dot notation: vehicle_make.make_name, or deeper: booking.patient.preferred_language. This means a default can pull in data from anywhere in the data model that is reachable through references.
Scalar SQL functions - PostgreSQL’s built-in function library, including mathematical functions, string functions, date/time functions, conditional logic (CASE), and more
Custom scalar functions - functions defined within the platform under Automation → Server Functions, which can themselves query the database, apply complex business rules, and return a single value

This makes expression defaults genuinely powerful. A line item’s tax code can be determined automatically from the item type and the customer’s region. A delivery date can be calculated from the order date plus a lead time derived from the supplier. A price can be looked up from a current pricelist based on the customer group and the product.

Can User Overwrite For all three default types, a toggle controls whether the user can override the generated value. When set to false, the default behaves as a read-only calculated value - the user sees it but cannot change it. When set to true (the default), the generated value is a suggestion that the user can accept or replace.

This distinction matters: a true calculated field (like a running total) should not be overwritable, while a suggested reference code should be. The Can User Overwrite toggle is how you control that behaviour without needing a separate field kind.

Choosing a default value type:

Type	Use when
Fixed Value	The default is always the same constant - a status of “New”, a boolean defaulting to false
Auto-Increment	The field needs a sequential, formatted identifier - invoice numbers, reference codes
Expression	The default needs to be derived from the record being created - looked up from a reference, calculated from other fields, or computed by a Server Function

Reference

Creates a relationship to another entity. When a user fills in a reference field, they are selecting an existing record from the referenced entity.

Field Type selects the target - this can be any entity, an Enum, or a custom Lookup field type (see Field Types section below).

Mappings - an optional but powerful feature. Mappings filter the available choices in the lookup based on values already entered in the current record. For example, on a Sales Quote, a mapping from the Quote’s Sales Party to the Opportunity’s Sales Party means the user only sees Opportunities belonging to the same customer - potentially filtering thousands of records down to a handful. Click + Add new mapping to configure.

Reference fields carry the same options as value fields (Is Mandatory, Is Unique, Show In List/Form/Details, Is Conditionally Relevant).

Using a Reference field automatically creates a Foreign Key constraint in the database, ensuring that only valid, pre-existing records can be referenced. That foreign key is also what lets a View in Design mode auto-join the referenced entity with one click, with no manual join condition needed.

Stored Calculation

A calculated field whose result is computed by an expression and stored in the database. Because the value is stored, it is fast to query and can be indexed, but it must be recalculated when source values change.

Is Volatile - when enabled, the stored value is recalculated every time it is read rather than only when dependencies change.

The expression is defined in a split-pane editor:

Left pane - SQL expression code editor. Write SQL directly; do not include SELECT - it is added automatically.
Right pane - browsable reference panel with five sections:
- Component Fields - fields from components of this entity, useful for aggregates
- Aggregate Functions - sum, count, avg, min, max, last, etc.
- Scalar SQL Functions - single-value functions
- Dataset SQL Functions - set-returning functions
- Postgres Functions - the full PostgreSQL function library

Click Expand to open the expression editor full-screen.

Example - summing a component’s values:

pg_catalog.sum(order_items.line_sale)

Stored calculations default to showing in List and Details but not in Form, since calculated values are not user-editable.

Virtual Calculation

A calculated field whose result is computed on the fly whenever the record is read. The value is never stored in the database. Virtual calculations are suited for derived values that change frequently or where storage overhead is not justified.

The expression editor is identical to Stored Calculation. Field Type can be left unspecified and will be inferred from the expression.

Is Volatile is available here as well.

Example - subtracting two sibling fields:

sales_total - cost_total

Stored vs. Virtual - which to use:

	Stored Calculation	Virtual Calculation
Persisted to the database	Yes	No - computed on every read
Can be indexed / queried efficiently	Yes	No
Recalculates	When dependencies change, or on every read if Is Volatile is enabled	Always - recomputed every read
Best for	Values you need to filter, sort, or index on - order totals, running balances	Cheap derived values you just need to display - margins, formatted strings

Conditional Relevance

Both fields and components support Is Conditionally Relevant. When enabled, the field or component only appears in the UI when a specified condition is true.

Enabling the toggle expands a condition builder with:

Setting	Description
Operand 1	A field from this entity or a related entity to evaluate
Operator	Comparison operator (equals, greater than, is empty, etc.)
Source Type	Whether to compare against the Value of another field, or a Fixed value
Value	The fixed value to compare against (when Source Type is Fixed value)

This is useful for forms where certain fields only make sense in specific situations - for example, showing an “Exemption reason” field only when a “Tax exempt” boolean is true.

Components

Components are sub-entities that belong to a parent entity and cannot exist without it. They represent a one-to-many or one-to-one relationship where the child records are tightly coupled to the parent.

Examples: Invoice Lines belonging to an Invoice, Addresses belonging to a Patient, Phone numbers belonging to a Contact.

Component types

Type	Relation	Use case
Multiple	1:Many	The most common. One parent record can have many component records. e.g. an invoice can have many line items.
Additional	1:1	A single extension record. Used when extra fields for the same entity are better kept separate.

Adding a component

Click Add Component from the entity header bar. The Add Component panel requires:

Component Type - Multiple or Additional
Component Name - human-readable
Component ID - auto-generated, used internally
Component Description - optional

Editing a component

Click a component row in the entity detail view to open the Edit Component panel. In addition to the basic fields, the panel provides:

Is Conditionally Relevant - same condition builder as for fields; hides the entire component section in the UI unless the condition is met
Add Component - nest a further component inside this one
Add Field - add fields to this component directly from the panel

Components can be nested: a component can itself contain further components. In the entity detail view, expand a component row to see its fields, and expand further for nested components.

In the generated application, every component shows up as its own tab on the parent record’s detail view - a Lead entity with Lead Email and Lead Phone components gets Lead Email and Lead Phone tabs automatically. See The Generated Application → Tabs for what that looks like to an end user.

A practical rule of thumb: if the child data only ever makes sense in the context of its parent, and a user would never need to look it up independently, it’s a component. If it’s something you’d want to list, search, or report on by itself, it should probably be its own entity with a Reference field back to the parent instead.

Security Rules

Security rules control who can access an entity, component, or field, and at what level. Rules can be defined at all three levels independently.

Access levels

Level	Description
No Access	The entity/component/field is not visible or accessible to the specified users
Read Only	Users can read but not modify data
Read and Write	Users can read and modify data

Scope

Each rule applies either to All Users or to specific Security Dimensions.

All Users - check this box to apply the rule to everyone, including anonymous users if “Anyone (Application and Anonymous Users)” is selected.

Security Dimensions - when All Users is unchecked, specify who the rule applies to. Each dimension row has:

Type - User (a specific user identity) or Role (a defined role)
Value - the specific user or role

Multiple dimension rows can be added with + Add more, allowing a single rule to cover several users and/or roles.

Multiple rules

An entity can have multiple security rules. Use Back to list in the panel to see all rules defined for that entity and add additional ones. Rules are evaluated cumulatively - a user who matches a Read and Write rule for their role, and a No Access rule for their user identity, will have the more restrictive access applied.

Field-level security

Security rules on individual fields override entity-level rules for that field. This allows, for example, making an entity broadly readable while restricting a sensitive field (such as a salary or date of birth) to specific roles only.

Worked example

Take an Employee entity that most staff need to browse (e.g. for an internal directory), but where compensation data is sensitive:

An entity-level rule with All Users checked, set to Read Only - everyone can see employee records.
A field-level rule on the Salary field, scoped to the HR role, set to Read and Write - only HR can see or edit it.

Because field-level rules override entity-level ones for that field, the net effect is: everyone can read the Employee entity, but the Salary field only appears for users with the HR role. Nothing needs to be set to No Access explicitly - the absence of a matching rule on a field for a given user simply means the entity-level rule is what applies.

Where entities go from here

An entity definition on its own already produces a working table, form, and list view - that’s what Generate does with it. Everything covered on this page is what you refine afterwards, in Evolve:

Views query entities - directly, through references, or through components - to build lists, reports, and lookups that don’t map one-to-one onto a single entity.
Database Workflows and Server Functions act on entities, and are exactly what gets called from Expression default values and Stored/Virtual Calculations when built-in SQL isn’t enough.
The User Interface section covers how generated forms and lists can be customized beyond the Show In List/Form/Details toggles described here.
Security Roles and Identities are what you reference when scoping a Security Rule beyond a specific named user.