Core Concepts
=============

Buckets
-------

A bucket is the primary storage unit in ArcaneDB. It holds a collection of records, each conforming to the bucket's field schema. Buckets support typed fields, schema enforcement, unique existence semantics, and a range of query and analytical operations.

Data Types
----------

ArcaneDB supports the following primitive field types:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Type
     - Description
   * - ``string``
     - A variable-length text value.
   * - ``float``
     - A 64-bit floating-point number.
   * - ``int``
     - A 64-bit signed integer.
   * - ``bool``
     - A boolean value; literals are ``true`` and ``false``.

Transactions
------------

ArcaneDB wraps every operation in an implicit transaction. An implicit transaction begins automatically with any data-modifying statement and can be finalised at any time using ``commit!``. For more granular control, explicit transaction blocks may be used with ``begin!``, ``commit!``, and ``rollback!``.

All data-modifying statements — ``insert``, ``set``, ``delete``, and ``truncate`` — participate in the active transaction. Read operations such as ``get`` are not transactional in the sense that they always reflect the last committed state.

The Internal Hash Field
-----------------------

Every record in ArcaneDB is assigned an internal identifier accessible via the reserved field name ``__hash__``. This value is managed entirely by the system and cannot be set or modified by the user. It can be retrieved using ``get __hash__`` in place of a field list or alongside other fields in a ``get`` statement.