Modeling data

Synthigy is model-first. You draw entities and relations, deploy the model, and Synthigy creates the tables, keeps them migrated and serves them over /data with access control on every entity, relation and attribute.

Datasets and versions

A dataset is one named model — Movies, CRM, Inventory. It has versions. You edit a draft version; deploying it makes it the live model of that dataset.

• A deployed version never changes. To change the model, create a new version, edit it and deploy it.
• The live model of the instance is the latest deployed version of every dataset, merged. Datasets can share entities (several datasets can relate to User, for example).
• Deploying migrates the database: new tables and columns are created, changed ones are altered.

Entities and attributes

An entity becomes a table. Every record gets an xid — a short, URL-safe unique id. To record who created a record and when, and who changed it last, add stamp attributes (see Stamps below).

An attribute becomes a column. Types:

Type	Holds
string	text
int, float	numbers
boolean	true / false
timestamp	a point in time, always UTC
enum	one of a fixed list of values
json	any JSON document
encrypted	JSON encrypted at rest (ENCRYPTION.md)
hashed	a one-way hash, e.g. a password — the plain value is never stored
user, group, role	a reference to an IAM user, group or role

Each attribute has a constraint: optional (the default), mandatory (NOT NULL), unique, or unique+mandatory. Unique attributes are arranged in unique groups in the modeler: the combination of values in one group must be unique.

Attributes can carry classification tags — pii, phi, secret, internal. Values of secret attributes are withheld from the audit history (DATALINE.md); the other tags are labels for your own policies.

Changing a type in a new version converts the column. Conversions inside one family (int → float, enum → string) are safe. Others, such as string → int, need every stored value to convert and fail the deploy if one does not. The modeler warns before you deploy. A reference attribute cannot change type: deactivate it and add a new one.

Stamps. A timestamp or user attribute can be stamped by the system:

• on create: set once, when the record is created;
• on modify: set on every write.

A timestamp stamp takes the time and a user stamp the writing user. A client value for a stamp is ignored by default; the attribute can instead refuse it with ATTRIBUTE_FORBIDDEN. The modeler's Add stamps declares the usual four: Created On, Created By, Modified On and Modified By. They replace the old entity audit switch, and an upgrade turns that switch into these attributes on the same columns.

Removing an attribute from a deployed model deactivates it. The column and its data stay in the database; the attribute disappears from the API.

Relations

A relation links two entities, with a label on each side. The labels are the names you traverse in queries: a movie relation labelled actors on one side and movies on the other is read as movie → actors and person → movies.

Cardinality	Meaning
o2o	one to one: linking a target to another record moves it there
o2m / m2o	one to many / many to one: a child has one parent; listing it under another moves it there
m2m	many to many
tree	an entity related to itself as parent and children

Deploying

From the Data modeling tool — in the console under Tools, or as a web component in your own page (<synthigy-data-modeling>, see the tooling repository): draw the model, then Deploy. The deploy view lists what will change before anything does.

From code: export the version from the modeler and pass the file to an SDK. The server decodes the export, so the same file deploys anywhere:

const ack = await client.deploy(fs.readFileSync("movies.json", "utf8"))
// ack.dataset is the dataset's xid
await client.destroy(ack.dataset) // removes every version, table and row

Deploying needs the dataset:deploy scope and destroying dataset:delete — both come with the Dataset Developer role. Dataset Modeler edits the datasets shared with it but cannot deploy.

Next

• Read and write the data: DATA.md
• Queries as files, with generated typed code: XSQL.md
• Who may see what: ACCESS.md