User Guide

Everything you need to install, configure, and build with Montycat — from getting started to governance, advanced operations, and security.

Insertion

Insert value

Values can be inserted using a ready-to-use method. Supported value types include:

Integer
String
Float
Complex serializable data structures

Each value (record) is related to a key and can be retrieved by that key.
Internally, the database stores all keys as 128-bit native unique integers.
For client operations, these keys are returned as string representations.

Note for Rust: When working with Rust, ensure that complex data structures implement the Serialize trait from the serde library. Also if you are operating with no schemas use .insert_value_no_schema() method.

from schemas import EmployeesSchema #schemas.py
from keyspaces import Employees #keyspaces.py

res1 = await Employees.insert_value("John")
res2 = await Employees.insert_value(28)
res3 = await Employees.insert_value(28.8)
res4 = await Employees.insert_value(["John", "Doe"])
res5 = await Employees.insert_value({"username": "John", "age": 28})

# {"status": True, "payload": "128222336824100726154851618391811195396", "error": None}
# or {"status": False, "payload": None, "error": "Error Text"}

Using schema and ORM

When using the ORM approach, you define a custom data schema by instantiating the Montycat Schema class.
This converts the object into a serializable data structure that can be stored in the database.
The schema name is automatically tracked in the database.
Data can later be queried by schema name.
Each keyspace can contain multiple schemas.

Before calling the insertion method, you must invoke .serialize() on the schema instance.
Note for Rust: Rust client does not require explicit serialization. Just make sure your struct implements the Serialize trait from serde and RuntimeSchema from montycat, which re-exports the derive macro — so cargo add montycat and cargo add serde --features derive are all you need.

from schemas import EmployeesSchema #schemas.py
from keyspaces import Employees #keyspaces.py

record = EmployeesSchema(
    username="Name",
    location="Location",
    age=21
).serialize()

result1 = await Employees.insert_value(record)

# {"status": True, "payload": "128222336824100726154851618391811195396", "error": None}
# or {"status": False, "payload": None, "error": "Error Text"}

Insert value with a custom key

Montycat provides a method to insert a value with a custom key.
The custom key must be a string.
Internally, the database converts the custom key into a 128-bit integer for storage.
Custom keys enable fast and efficient record lookups.
Note: Montycat does not allow duplicate keys within the same keyspace.
If you attempt to insert a record with an existing key, the operation will fail with the error: Key already exists.

from keyspaces import Employees #keyspaces.py

res1 = await Employees.insert_custom_key_value(custom_key="myCustomKey", value="John")
# {"status": True, "payload": "112424342341342", "error": None}

Insert custom key with no value

It is also possible to insert a custom key without an associated value.
This can be useful for scenarios where you need to reserve a key in advance for future use.

from keyspaces import Employees #keyspaces.py

res1 = await Employees.insert_custom_key(custom_key="myCustomKey")

# {"status": True, "payload": "112424342341342", "error": None}

Insert bulk

Montycat supports native bulk insertion of multiple values.
Bulk operations are executed using asynchronous handles and multi-threaded execution for maximum performance.
The number of simultaneous operations is determined automatically by the database engine based on system parameters.
This default value can be overridden manually if required.
Custom keys are not supported in bulk insertion.
Typically, bulk insertion does not return the inserted keys.
If any operations fail during the bulk insert, the method will return a list of the failed values for further handling.

from keyspaces import Employees #keyspaces.py

array = []

for num in range(1000):
    value = {
        "username": f"Name {num}",
        "location": f"Location {num}",
        "age": 21
    }
    array.extend([value])

res1 = await Employees.insert_bulk(bulk_values=array)

# {"status": True, "payload": None, "error": None}
# or if all insertions failed: {"status": False, "payload": None, "error": "Error Text"}
# or if some of insertions failed:
# {
#  "status": False,
#  "payload": {"failed": [{"username": "Name 3", "location": "Location 3", "age": 21 }]},
#  "error": None
# }