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      "indexes": []
25    }
26  ]
27}

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

Onyx Cloud Database models cross-table relationships through resolver properties rather than a dedicatedrelationships array. Each resolver executes Onyx Database JavaScript SDK queries to hydrate related records on demand.

Resolver fields:

• name (string): The property exposed on the entity.
• resolver (string): JavaScript that receivesdb and this, and mustreturn await the related data.

Key capabilities:

• Call resolve("resolverName") in scripts to load related collections only when needed.
• Reference resolver metadata (such asresolverName.size) inside predicates for filtered queries.
• Combine resolvers with cascade helpers to persist nested payloads while keeping schemas declarative.

Example resolver:

1"resolvers": [
2  {
3    "name": "orders",
4    "resolver": "return await db.from(\"Order\").where(eq(\"customerId\", this.customerId)).list();"
5  }
6]

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, resolver-backed 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      "resolvers": [
36        {
37          "name": "orders",
38          "resolver": "return await db.from(\"Order\").where(eq(\"customerId\", this.customerId)).list();"
39        }
40      ],
41      "indexes": [
42        {
43          "name": "email"
44        }
45      ],
46      "partition": "countryCode"
47    }
48  ]
49}

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 support@onyx.dev.