Overview Defining a Model Instances Creating Nodes and Relationships Merging Nodes and Relationships Updating Nodes and Relationships Deleting Nodes Deleting Relationships Finding Nodes and Relationships Hooks Temporary Databases
Each Instance of a Model represents a node in the database, with its label, properties etc. matching those in the Model definition.
Instances offer flexible access to a node's properties, as well as operations regarding it, such as updating/deleting the node itself and its relationships.
An Instance is returned from various Model operations (such as Create, Find), or a new Instance (which doesn't yet exist in the database) can be created as follows:
1link /* --> creates an Instance of the Users model, which still doesn't exist in the database */
2link const user = Users.build({
3link id: '1',
4link name: 'John',
5link age: 38,
6link });
7link
8link /* --> the Instance can be saved to the database. This will run a CREATE operation to create a node to match the Users Model configuration (label etc.) */
9link await user.save({
10link /* --> (optional, default true) validates that the properties of the Instance are valid, given the schema of the Model definition */
11link validate: true,
12link /* --> (optional) an existing session or transaction to use */
13link session: null,
14link });
1link /* --> given a user Instance, like the one created above, we can change the properties of the Instance */
2link user.name = 'Alex';
3link
4link /* --> we reflect this change to the database. Since the node already exists in the databse, neogma will automatically run a MATCH-SET operation to update just the name of this node */
5link await user.save({
6link validate: false,
7link });
If nothing has changed, .save() will do nothing.
WARNING: Updating a instance ignores its Association fields (as described below) meaning that related nodes will not be created and associated. Only the initial save (when an instance doesn't yet exist in the database) creates related nodes.
1link /* --> the Instance's properties and methods are accessible by their key */
2link console.log(user.id, user.name, user.age); // "1" "Alex" 38
3link /* --> all the instance properties can be taken as follows */
4link console.log(user.getDataValues()); // { id: "1", name: "Alex", age: 38 }
5link /* --> the methods, used in the Model definition can be used */
6link console.log(user.bar()); // "The name of this user is: Alex"
1link user.age = 30;
2link /* --> we can validate the properties of the Instance without saving it to the database. The properties of the Instance are valid, so this will not throw an error */
3link await user.validate();
4link
5link try {
6link user.age = -1;
7link /* --> the properties of the Instance are invalid, so this will throw an error */
8link await user.validate();
9link } catch(err) {
10link console.log(err); // NeogmaInstanceValidationError
11link }
1link /* --> by using the Related Nodes aliases specified in the Model definition, related nodes can also be created */
2link const userWithOrder = Users.build({
3link id: '2',
4link name: 'Alex',
5link /* --> the 'Orders' alias will be used, as defined in the 'Users' model */
6link Orders: {
7link /* --> (optional) create new nodes and associate with them */
8link properties: [{
9link /* --> a new Order node will be created with the following properties, and a relationship with the configuration of alias 'Orders' will be created (direction: out, name: CREATES) */
10link id: '3'
11link }],
12link }
13link });
14link /* --> when calling the following method, the User node, the Order node and the relationship between them */
15link await userWithOrder.save();
For more examples of creating realted nodes, refer to the Create operations, as the same interface is used.
If a Node already exists in the database, an Instance can still be created. This is useful for running methods like .save() on it.
When a record is available (i.e. from a QueryResult), an Instance can be built using it directly in the buildFromRecord static.
This is the easiest and best way to build an Instance from an existing node, as its labels field is properly set.
This static is used internally in Neogma for this purpose.
1linkconst result = await new QueryBuilder() // @see [QueryBuilder](../QueryBuilder/Overview)
2link .match({
3link model: Users,
4link where: {
5link id: '1'
6link },
7link identifier: 'u'
8link })
9link .return ('u')
10link .run();
11link
12linkconst userRecord = result.records[0]?.get('u');
13linkif (!userRecord) {
14link throw new Error('user not found');
15link}
16link
17linkconst userInstance = Users.buildFromRecord(userRecord);
18link
19linkconsole.log(userInstance.labels); // ["User"]
20link
21linkuserInstance.name = 'Some new name';
22link
23linkawait userInstance.save(); /* --> the instance will be updated */
Another way is to use the build static. It's not recommended as the labels property is not set.
The first parameter of the build function must equal to the data of the Node, for example from the statement result.
The second parameter is an object with its status property set to existing.
1linkconst result = await new QueryBuilder() // @see [QueryBuilder](../QueryBuilder/Overview)
2link .match({
3link model: Users,
4link where: {
5link id: '1'
6link },
7link identifier: 'u'
8link })
9link .return ('u')
10link .run();
11link
12linkconst userData = result.records[0]?.get('u')?.properties;
13linkif (!userData) {
14link throw new Error('user not found');
15link}
16link
17linkconst userInstance = Users.build(userData, { status: 'existing' });
18link
19linkuserInstance.name = 'Some new name';
20link
21linkawait userInstance.save(); /* --> the instance will be updated */
The labels of the Instance can be taken from the labels attribute. It's properly set when the Instance is built internally (i.e. in the findMany, update, updateRelationship statics), or when building an Instance using the buildFromRecord static.
1link/* --> let "user" be a Users instance */
2linkconsole.log(user.labels); // ["User"]
More Instance methods are found at the corresponding documentation, i.e. Creating Nodes and Relationships