Saving an Entity

Persisting data is the heart of any database system. With Onyx Database, you can efficiently save entities and handle batch operations. This tutorial demonstrates how to declare an entity and persist it.

Prerequisites (Onyx Cloud Database)

Before saving an entity using the Onyx Cloud Database script editor, ensure you have:

  • Created an Onyx Cloud Database instance.
  • Created a schema with a table that includes the necessary properties. Below is an example schema derived from the Kotlin snippet:

Steps to Save an Entity (Onyx Cloud Database)

1

Declare the Schema

Use the provided JSON schema to declare your entity in the Onyx Cloud Database.
1{
2  "tables": [
3    {
4      "name": "Person",
5      "identifier": {
6        "name": "id",
7        "generator": "Sequence",
8        "type": "Long"
9      },
10      "partition": "",
11      "attributes": [
12        {
13          "name": "id",
14          "type": "Long",
15          "maxSize": null,
16          "isNullable": false
17        },
18        {
19          "name": "dateCreated",
20          "type": "Date",
21          "maxSize": null,
22          "isNullable": false
23        },
24        {
25          "name": "dateUpdated",
26          "type": "Date",
27          "maxSize": null,
28          "isNullable": true
29        },
30        {
31          "name": "firstName",
32          "type": "String",
33          "maxSize": 100,
34          "isNullable": false
35        },
36        {
37          "name": "lastName",
38          "type": "String",
39          "maxSize": 100,
40          "isNullable": false
41        }
42      ],
43      "relationships": [],
44      "indexes": []
45    }
46  ],
47  "revisionDescription": "Initial Schema"
48}
  • Ensure your schema defines all required attributes, including types, sizes, and nullability.
  • The identifier field is mandatory for each table and must include a unique name and a supported generator type (e.g., Sequence or UUID).
  • Relationships and indexes are optional but improve performance and enforce data integrity.
2

Declare the Identifier

Extract and declare the identifier for your entity using the provided code snippets.
1"identifier": {
2    "name": "id",
3    "generator": "Sequence",
4    "type": "Long"
5},
  • The identifier must match the primary key definition in your schema.
  • Supported identifier types include String, Long, and other common scalar types.
  • Use a sequence generator for numeric identifiers to enable automatic incrementation.
  • Alternatively, you can use a UUID identifier generator for unique string identifiers.
3

Create and Save the Entity

Create an entity and define your entity's properties and use the Persistence Manager to save it.
1const person = {
2  firstName: "John",
3  lastName: "Elway",
4  dateCreated: new Date()
5};
6
7const savedPerson = await db.save("Person", person);
8console.log(`Person ${savedPerson.id} saved successfully`);
  • Ensure that all required properties are populated before saving the entity.
  • Use appropriate types for each attribute as defined in the schema (e.g., String, Date, Long).
  • If an entity with the same identifier already exists, Onyx Cloud Database will update the record instead of inserting a new one.
4

Verify the Save Operation

Retrieve the saved entity using the Persistence Manager to confirm it has been persisted.
1const retrievedPerson = await db.findById("Person", savedPerson.id);
2console.log(`Person ${retrievedPerson.id} saved successfully`);
  • Ensure you are using the correct identifier when retrieving the entity.
  • If retrieval fails, double-check the schema definition and ensure the identifier was correctly populated.
  • Consider logging the retrieval result to verify the entity’s attributes and state.

Important Notes

  • Onyx does not differentiate between insert and update operations. If an entity with the same primary key exists, it will be updated.
  • An entity's fields must not include transient fields unless explicitly annotated with @Attribute.
  • For better performance, consider batching save operations where applicable.

Troubleshooting

  • Entity Not Persisting: Ensure that the entity is properly annotated with @Entity and that all required fields are set before saving.
  • Invalid Identifier: Verify that the primary key is correctly annotated with @Identifier and that its data type is supported.
  • Persistence Manager Not Initialized: Make sure that the PersistenceManagerFactory is properly initialized before attempting to obtain a PersistenceManager.
  • Null Pointer Exceptions: Check that all non-nullable attributes are assigned values before saving the entity.

Next Steps

Now that you know how to save an entity, you can explore advanced topics: