From 9616c61f2c6e7efc240ac1ef5ed67750803c3107 Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Sun, 23 Aug 2026 07:43:14 -0600 Subject: [PATCH] docs: clarify create returns a new entity --- guide/getting-started/creating-new-entities.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/guide/getting-started/creating-new-entities.md b/guide/getting-started/creating-new-entities.md index 7b24dc0..a3dbfe7 100644 --- a/guide/getting-started/creating-new-entities.md +++ b/guide/getting-started/creating-new-entities.md @@ -72,6 +72,22 @@ var user = getInstance( "User" ).create( { There is no need to call `save` when using the `create` method. +{% hint style="warning" %} +`create` is a factory method. It creates, saves, and returns a **new entity instance**; it does not fill, save, or otherwise mutate the entity on which it was called. Always use the returned entity when you need the persisted record. +{% endhint %} + +```javascript +var user = getInstance( "User" ).newEntity(); + +user = user.create( { + "username": "JaneDoe", + "email": "jane@example.com", + "password": "mypass1234" +} ); + +user.isLoaded(); // true +``` + ## firstOrNew | Name | Type | Required | Default | Description |