Bucket Management
=================

Creating Buckets
----------------

ArcaneDB provides three distinct creation modes, controlled by keyword modifiers on the ``create bucket`` statement. The schema is declared as a parenthesised, comma-separated list of ``field_name: type`` pairs.

**Syntax:**

.. code-block:: none

   create [forced] [unique] bucket <name> (<field>: <type>, ...);
   create [forced] [unique] bucket <name> from csv("<filepath>");

**Creation Modes:**

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Syntax
     - Behaviour
   * - ``create bucket``
     - Attempts to create the bucket. Raises an error if a bucket with that name already exists.
   * - ``create unique bucket``
     - Creates the bucket only if it does not already exist. If it exists, the statement is silently ignored. Equivalent to SQL's ``CREATE TABLE IF NOT EXISTS``.
   * - ``create forced bucket``
     - Always creates the bucket, dropping and replacing any existing bucket of the same name along with all its data.
   * - ``create forced unique bucket``
     - If the bucket exists, it is dropped and recreated (identical to ``forced``). If it does not exist, it is created fresh.

**Example — schema declaration:**

.. code-block:: aql

   create forced bucket Sales (
       product:   string,
       price:     float,
       quantity:  int,
       revenue:   float,
       timestamp: int
   );

**Example — creation from a CSV file:**

.. code-block:: aql

   create forced unique bucket Products2 from csv("generated.csv");

When creating from a CSV file, ArcaneDB infers the schema from the file's header row and populates the bucket with the file's data in a single operation.

Dropping a Field
----------------

An individual field can be permanently removed from a bucket's schema using the ``drop`` statement. The field is removed from all existing records as well as from the schema definition. This operation is irreversible without recreating the bucket.

**Syntax:**

.. code-block:: none

   drop <field> from <bucket>;

**Example:**

.. code-block:: aql

   drop price from Products;

After execution, the ``price`` field no longer exists on any record in ``Products`` and cannot be referenced in subsequent queries against that bucket.

Truncating a Bucket
-------------------

The ``truncate`` statement removes all records from a bucket while preserving the schema.

**Syntax:**

.. code-block:: none

   truncate <bucket>;

**Example:**

.. code-block:: aql

   truncate Names;

Inspecting a Bucket
-------------------

The ``describe`` statement prints the schema of a named bucket, including all field names and their types.

**Syntax:**

.. code-block:: none

   describe <bucket>;

**Example:**

.. code-block:: aql

   describe Products;
   describe Names;

Listing All Buckets
-------------------

The ``show buckets`` statement enumerates all buckets currently registered in the database.

**Syntax:**

.. code-block:: none

   show buckets;