Getting Started with Table / Entity Definitions in Onyx Database

Introduction to Onyx Cloud Database Schema

In Onyx Cloud Database, entities are defined using JSON schemas. These schemas allow you to precisely model your data structures, including entities, attributes, relationships, and indexes. The JSON schema provides a clear and concise way to define how your data should be stored and managed in the cloud database.

Defining an Entity

An entity represents a data model or a table in the database. It consists of attributes, an identifier, optional relationships, and indexes.

Entity JSON Structure

1{
2  "tables": [
3    {
4      "name": "Person",
5      "identifier": {
6        "name": "id",
7        "type": "Int",
8        "generator": "Sequence"
9      },
10      "attributes": [
11        {
12          "name": "firstName",
13          "type": "String",
14          "isNullable": false,
15          "maxSize": 50
16        },
17        {
18          "name": "lastName",
19          "type": "String",
20          "isNullable": false,
21          "maxSize": 50
22        }
23      ],
24      "relationships": [],
25      "indexes": []
26    }
27  ]
28}

Identifier Specification

The identifier serves as the primary key for the entity. It uniquely identifies each record in the database.

Identifier Types and Generators

Attributes:

• name (string): The name of the identifier field.
• type (enum): The data type of the identifier. Supported types include String, Int,Long, etc.
• generator (enum): The method used to auto-generate the identifier. Options are:
  • Sequence: Auto-incrementing numeric value.
  • UUID: Universally unique identifier.
  • None: No auto-generation; you must provide the value.

Example:

1"identifier": {
2  "name": "id",
3  "type": "Int",
4  "generator": "Sequence"
5}

Defining Attributes

Attributes represent the fields or columns of your entity. Attributes can have various data types and constraints.

Attributes:

• name (string): The name of the attribute.
• type (enum): The data type. Supported types are String, Int, Boolean, etc.
• isNullable (boolean): Determines if the attribute can be null.
• maxSize (number, optional): Maximum size for string attributes.

Supported Attribute Types

Example:

1"attributes": [
2  {
3    "name": "email",
4    "type": "String",
5    "isNullable": false,
6    "maxSize": 100
7  },
8  {
9    "name": "age",
10    "type": "Int",
11    "isNullable": true
12  }
13]

Specifying Relationships

Relationships define how entities relate to one another, similar to foreign keys in relational databases.

Attributes:

• name (string): The name of the relationship.
• inverseClass (string): The name of the related entity.
• type (enum): The relationship cardinality.
• inverse (string, optional): The name of the inverse relationship in the related entity.
• fetchPolicy (enum, optional): Determines when related entities are fetched (Eager, Lazy, None).
• cascadePolicy (enum, optional): Determines how operations cascade (Save, Delete, All, None).

Relationship Types

• OneToOne: Each instance of Entity A relates to one instance of Entity B.
• OneToMany: An instance of Entity A relates to multiple instances of Entity B.
• ManyToOne: Multiple instances of Entity A relate to one instance of Entity B.
• ManyToMany: Instances of Entity A relate to multiple instances of Entity B and vice versa.

Fetch and Cascade Policies

Fetch Policies:

• Eager: Related entities are loaded immediately.
• Lazy: Related entities are loaded on demand.
• None: Related entities are not loaded.

Cascade Policies:

• Save: Changes in the parent entity cascade to related entities on save.
• Delete: Deleting the parent entity deletes related entities.
• All: Both save and delete operations cascade.
• None: No cascading occurs.

Example:

1"relationships": [
2  {
3    "name": "orders",
4    "inverseClass": "Order",
5    "type": "OneToMany",
6    "inverse": "customer",
7    "fetchPolicy": "Lazy",
8    "cascadePolicy": "Save"
9  }
10]

Creating Indexes

Indexes improve query performance on specific attributes by allowing faster data retrieval.

Attributes:

• name (string): The name of the attribute to index.

Example:

1"indexes": [
2  {
3    "name": "email"
4  }
5]

Partitioning Entities

Partitioning allows you to optimize data access for large datasets. Use the @Partition annotation to indicate a property that partitions the entity.

Attributes:

• name (string): The name of the attribute to partition the entities by.

Example:

1"partition": "countryCode"

Complete Entity Example

Putting it all together, here's a complete example of an entity with attributes, an identifier, relationships, and indexes.

1{
2  "tables": [
3    {
4      "name": "Customer",
5      "identifier": {
6        "name": "customerId",
7        "type": "Int",
8        "generator": "Sequence"
9      },
10      "attributes": [
11        {
12          "name": "firstName",
13          "type": "String",
14          "isNullable": false,
15          "maxSize": 50
16        },
17        {
18          "name": "lastName",
19          "type": "String",
20          "isNullable": false,
21          "maxSize": 50
22        },
23        {
24          "name": "email",
25          "type": "String",
26          "isNullable": false,
27          "maxSize": 100
28        },
29        {
30          "name": "dateCreated",
31          "type": "Timestamp",
32          "isNullable": false
33        }
34      ],
35      "relationships": [
36        {
37          "name": "orders",
38          "inverseClass": "Order",
39          "type": "OneToMany",
40          "inverse": "customer",
41          "fetchPolicy": "Lazy",
42          "cascadePolicy": "Save"
43        }
44      ],
45      "indexes": [
46        {
47          "name": "email"
48        }
49      ],
50      "partition": "countryCode"
51    }
52  ]
53}

Next Steps

Now that you understand how to define entities in Onyx Cloud Database using JSON schemas, you can proceed to:

• Deploying the Schema: Upload your schema to the Onyx Cloud Database and initialize your database.
• Performing CRUD Operations: Use the Onyx Cloud API to create, read, update, and delete records.
• Advanced Queries: Leverage the powerful query capabilities to retrieve and manipulate data.

Additional Resources

Need Help?

For further assistance, please contact our support team at [email protected].