Finding an Entity by ID within a Partition

Accessing data within specific partitions allows for efficient querying in distributed databases. This tutorial demonstrates how to find an entity by ID within a partition using Onyx Database.

Steps to Find an Entity by ID within a Partition (Onyx Cloud Database)

1

Declare the Entities

Use the provided JSON schema to declare your entities with partitioning and deploy the database using this schema definition.
1{
2  "tables": [
3    {
4      "name": "CellPhone",
5      "identifier": {
6        "name": "cellPhoneNumber",
7        "type": "String",
8        "generator": "None"
9      },
10      "attributes": [
11        {
12          "name": "cellPhoneNumber",
13          "type": "String",
14          "isNullable": false
15        },
16        {
17          "name": "areaCode",
18          "type": "Int",
19          "isNullable": true
20        }
21      ],
22      "relationships": [
23        {
24          "name": "callLogs",
25          "inverse": "callFrom",
26          "inverseClass": "CallLog",
27          "type": "OneToMany",
28          "fetchPolicy": "None",
29          "cascadePolicy": "None"
30        }
31      ],
32      "indexes": [],
33      "partition": ""
34    },
35    {
36      "name": "CallLog",
37      "identifier": {
38        "name": "callLogId",
39        "type": "Long",
40        "generator": "Sequence"
41      },
42      "attributes": [
43        {
44          "name": "callLogId",
45          "type": "Long",
46          "isNullable": false
47        },
48        {
49          "name": "destinationNumber",
50          "type": "String",
51          "isNullable": true
52        },
53        {
54          "name": "timeDateStarted",
55          "type": "Date",
56          "isNullable": true
57        },
58        {
59          "name": "isNSAListening",
60          "type": "Boolean",
61          "isNullable": false
62        },
63        {
64          "name": "callFromAreaCode",
65          "type": "Int",
66          "isNullable": true
67        }
68      ],
69      "relationships": [
70        {
71          "name": "callFrom",
72          "inverse": "callLogs",
73          "inverseClass": "CellPhone",
74          "type": "ManyToOne",
75          "fetchPolicy": "None",
76          "cascadePolicy": "None"
77        }
78      ],
79      "indexes": [
80        {
81          "name": "isNSAListeningIndex",
82          "attributes": ["isNSAListening"]
83        }
84      ],
85      "partition": "callFromAreaCode"
86    }
87  ],
88  "revisionDescription": "Schema for CallLog and CellPhone with partitioning"
89}
  • Ensure your schema defines all required attributes, including types and nullability.
  • The partition attribute specifies which field is used for partitioning.
  • Relationships must be correctly defined with appropriate types and inverse properties.
2

Populate Test Data in Different Partitions

Call logs are stored in partitions for area codes 555 and 123.
1// Create a call log for area code (555)
2const myPhoneNumber = {
3    cellPhoneNumber: "(555) 303-2322",
4    areaCode: 555
5};
6
7await db.save("CellPhone", myPhoneNumber);
8
9const callToMom = {
10    destinationNumber: "(555) 323-2222",
11    isNSAListening: true,
12    callFrom: myPhoneNumber,
13    callFromAreaCode: myPhoneNumber.areaCode
14};
15
16await db.save("CallLog", callToMom);
17
18const callToEdwardSnowden = {
19    destinationNumber: "(555) 122-2341",
20    isNSAListening: false,
21    callFrom: myPhoneNumber,
22    callFromAreaCode: myPhoneNumber.areaCode
23};
24
25await db.save("CallLog", callToEdwardSnowden);
26
27// Create a call log for area code (123)
28const mySecretPhone = {
29    cellPhoneNumber: "(123) 936-3733",
30    areaCode: 123
31};
32
33await db.save("CellPhone", mySecretPhone);
34
35const callToSomeoneShady = {
36    destinationNumber: "(555) 322-1143",
37    isNSAListening: false,
38    callFrom: mySecretPhone,
39    callFromAreaCode: mySecretPhone.areaCode
40};
41
42await db.save("CallLog", callToSomeoneShady);
43
44const callToJoe = {
45    destinationNumber: "(555) 286-9987",
46    isNSAListening: true,
47    callFrom: mySecretPhone,
48    callFromAreaCode: mySecretPhone.areaCode
49};
50
51await db.save("CallLog", callToJoe);
  • Ensure the partition attribute is set when saving the entities.
  • Partitioning is handled automatically based on the partition key.
3

Find a CallLog by ID in Partition 555

Use the query builder to find entities within a specific partition.
1// Use Query Builder to fetch a call log within a partition
2const callLogInAreaCode555 = (await db.from("CallLog")
3    .where(eq("callLogId", 1))
4    .inPartition(555)
5    .list())[0] || null;
6
7const callLogInAreaCode123 = (await db.from("CallLog")
8    .where(eq("callLogId", 1))
9    .inPartition(123)
10    .list())[0] || null;
11    
12// Alternatively you can use the following to find an entity within a partition
13const callLogInAreaCode555Alt = await db.findByIdInPartition("CallLog", 1, 555);
14const callLogInAreaCode123Alt = await db.findByIdInPartition("CallLog", 1, 123);
15
16// Make sure the CallLog(s) are 2 different entities.
17console.assert("The Destination Number should be different for each CallLog!", 
18    callLogInAreaCode123?.destinationNumber !== callLogInAreaCode555?.destinationNumber);
  • Specify the correct partition when querying.
Next Tutorial: Lifecycle Events

Important Notes

  • Partitions are used to distribute data across different physical storage units, improving scalability and performance.
  • An entity"s identifier is not unique across partitions; it is unique within a partition.
  • Define the partition key before persisting entities, as it cannot be altered at runtime.

Troubleshooting

  • Entity Not Found: Ensure you"re querying the correct partition and the entity exists within that partition.
  • Duplicate Identifiers: Remember that identifiers can be the same across different partitions. Always specify the partition when querying.
  • Incorrect Partition Configuration: Verify that the partition attribute is correctly annotated and set before saving entities.

Next Steps

Now that you know how to find an entity by ID within a partition, you can explore advanced topics: